app

package
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 11, 2026 License: Apache-2.0 Imports: 4 Imported by: 0

README

app

The shape of the application: the package that owns no library, imports three of them, and consolidates what they each own into one statement.

It is nobody's dependency. Nothing imports it, which is what makes it the right place — the only place — for knowledge of the whole picture to live.

What it knows that no library does

app owns app_profile and app_subscription, and it knows that authlite's user, phone's number, workspace's membership and its own company column all describe the same person. None of the three can know that, and none of them has to.

type User struct {
	authlite.User

	Phone      phone.Data
	Membership workspace.Membership
	Company    string

	workspaceID string
}

The layout is the convention worth copying. Columns that live on the driving table are embedded and flat, because they are the same row. Anything reached by a join is a nested struct, because it may not be there at all, and the nested type is what carries the Exists method that says so.

Two methods, one slice

Joins() and Bindings() satisfy authlite.Composite, so the library builds the statement and the application decides its shape.

Bindings() is where the boundary pays off. Four packages contribute to one slice via sqlb.Bindings, and because the select list and the scan targets are that same slice, they cannot drift apart — there is no second list to keep in step, so inserting a column in the middle cannot silently shift a scan.

Two things are load-bearing and easy to get wrong:

  • Every join is LEFT. An INNER join in a load-one-user query is a filter nobody wrote. Changing one to INNER makes a user with no profile row vanish, and the executed test fails with sql: no rows in result set — which is how that claim was verified rather than asserted.
  • workspaceID is unexported and set by NewUser. A zero value there would join to the empty workspace and find nothing, which reads exactly like "not a member".

The other direction

SubscriptionJoin is the reverse case, and the more common one: the library owns the query, and the application wants one more join, filter and column added to it through sqlb.WithJoin, sqlb.WithWhere and sqlb.WithColumns. The library's own NotBanned predicate is written before Apply and no option can remove it, because there is no option that subtracts.

Where it is proven

Rendered in ../example_test.go, recipes 1 and 2. Executed against a real database in contrib/driver-sqlite/crosspackage_test.go. The walkthrough is docs/cross-package.md.

Documentation

Overview

Package app is the application side of the cross-package story: the code that owns no library, imports three of them, and consolidates what they each own into one statement.

The three it composes are deliberately three different shapes, because a real application meets all three:

  • authlite owns tables and exports typed columns for them.
  • phone borrows one of authlite's tables under its own alias, so it can join to a row authlite already knows about without authlite knowing the plugin exists.
  • workspace owns its own tables and imports nothing. It takes the user id column as an argument, so any identity source works.

None of them knows about app_profile or app_subscription, which this package owns, and none of them can be made to. That is the boundary sqlb exists for: the application supplies the joins and the scan targets, and the compiler checks every one of them.

Index

Constants

View Source
const (
	TableNameProfile  = "app_profile"
	TableAliasProfile = "p"

	ColProfileUserID  = "user_id"
	ColProfileCompany = "company"

	TableNameSubscription  = "app_subscription"
	TableAliasSubscription = "s"

	ColSubUserID = "user_id"
	ColSubStatus = "status"
	ColSubPlan   = "plan"
)

The application's own table and column names. Constants for the same reason the libraries use them: the migration and the column declarations spell the name once.

Variables

The typed columns of app_profile.

The typed columns of app_subscription.

View Source
var TableProfile = sqlb.Table{Name: TableNameProfile, Alias: TableAliasProfile}

TableProfile is an application table. No library imports this package, so no library can join to it; the application does the joining.

View Source
var TableSubscription = sqlb.Table{Name: TableNameSubscription, Alias: TableAliasSubscription}

TableSubscription is the second application table, used to extend a library's own query rather than to build one.

Functions

func SubscriptionJoin

func SubscriptionJoin(userID sqlb.Expr[string]) sqlb.Join

SubscriptionJoin joins the application's subscription table to any string user id column. It is what the application passes to a library query through sqlb.WithJoin, which is the other direction of the boundary: the library's query, extended by the application, with the library's own predicates still in place.

Types

type SubStatus

type SubStatus string

SubStatus is a named string type, so the closed set of states cannot be widened by passing an arbitrary string at a call site.

const (
	SubActive   SubStatus = "active"
	SubCanceled SubStatus = "canceled"
)

The subscription states this application knows.

type User

type User struct {
	authlite.User

	Phone      phone.Data
	Membership workspace.Membership
	Company    string
	// contains filtered or unexported fields
}

User is the composite the application actually wants: the auth library's own row, plus everything reached across a package boundary.

The shape is the convention worth copying. Columns that live ON auth_user are embedded and flat, because they are the same row; anything reached by a join is a nested struct, because it may not be there at all and the nested type is what carries the Exists method that says so.

func NewUser

func NewUser(workspaceID string) *User

NewUser returns a composite destination scoped to one workspace.

func (*User) Bindings

func (u *User) Bindings() []sqlb.Binding

Bindings satisfies authlite.Composite: every column the statement selects, in order, each bound to the field it scans into.

This is where the boundary pays off. Four packages contribute bindings to one slice, the select list and the scan targets come from that one slice, and the compiler has checked every column against the field it writes to. Inserting a column in the middle cannot shift a scan, because there is no second list to keep in step.

func (*User) Joins

func (u *User) Joins() []sqlb.Join

Joins satisfies authlite.Composite. The application decides the shape of the statement the library builds: which tables are reached, in what order, and by which join type.

Every one is LEFT. An INNER join here would silently drop every user without a phone, without a membership, or without a profile row, turning a load-one-user query into a filter nobody wrote.

func (*User) WorkspaceID

func (u *User) WorkspaceID() string

WorkspaceID reports the workspace the membership join is scoped to.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL