@shaferllc/keel 0.80.0 → 0.81.1

package/docs/migrations.md

@@ -73,12 +73,41 @@ t.boolean("active").default(true);     // sqlite: DEFAULT 1, else DEFAULT true
 t.integer("retries").default(0);       // ... DEFAULT 0
 ```
 
-For anything the builder doesn't cover — indexes, foreign keys, an `ALTER
-TABLE` — `schema.raw(sql, bindings?)` runs arbitrary SQL:
+### Indexes and foreign keys
+
+`createTable` builds indexes and foreign keys alongside the columns:
+
+```ts
+schema.createTable("members", (t) => {
+  t.id();
+  t.integer("team_id");
+  t.string("email");
+  t.uniqueIndex("email");                       // or t.index(["a", "b"]) for composite
+  t.foreign("team_id").references("id").on("teams").onDelete("cascade");
+});
+```
+
+### Altering a table
+
+`schema.alterTable(name, build)` adds, renames, and drops columns and indexes on
+an existing table (dialect-aware SQL). Drop an index before the column it covers:
 
 ```ts
 up: (schema) =>
-  schema.raw("CREATE INDEX idx_posts_user ON posts (user_id)"),
+  schema.alterTable("users", (t) => {
+    t.string("phone").nullable();     // ADD COLUMN
+    t.renameColumn("name", "full_name");
+    t.index("phone");
+    t.dropIndex("users_legacy_index");
+    t.dropColumn("legacy");
+  }),
+```
+
+For anything the builder still doesn't cover, `schema.raw(sql, bindings?)` runs
+arbitrary SQL:
+
+```ts
+up: (schema) => schema.raw("CREATE INDEX idx_posts_user ON posts (user_id)"),
 ```
 
 > `raw()` writes through the connection **without** placeholder conversion, so
@@ -256,11 +285,10 @@ already gone — the typical `down()` for a `createTable`.
 
 `raw(sql: string, bindings?: unknown[]): Promise<void>`
 
-Runs arbitrary SQL through the connection — the escape hatch for indexes, foreign
-keys, and `ALTER TABLE`.
+Runs arbitrary SQL through the connection — the escape hatch for anything the
+builders don't cover.
 
 ```ts
-await schema.raw("CREATE INDEX idx_posts_user ON posts (user_id)");
 await schema.raw("UPDATE users SET active = ? WHERE active IS NULL", [true]);
 ```
 
@@ -268,6 +296,22 @@ await schema.raw("UPDATE users SET active = ? WHERE active IS NULL", [true]);
 `raw()` does **not** rewrite `?` to `$n`, so pass `$1, $2, …` yourself on the
 `postgres` dialect.
 
+#### `alterTable(name, build)`
+
+`alterTable(name: string, build: (table: AlterTableBuilder) => void): Promise<void>`
+
+Alter an existing table — the callback gets an [`AlterTableBuilder`](#altertablebuilder)
+for adding, renaming, and dropping columns and indexes. Emits one dialect-aware
+statement per operation, ordered so a dropped index precedes its column.
+
+```ts
+await schema.alterTable("users", (t) => {
+  t.string("phone").nullable();
+  t.renameColumn("name", "full_name");
+  t.dropColumn("legacy");
+});
+```
+
 ### `TableBuilder`
 
 Describes a table's columns. **You get one from the `createTable` callback** — it
@@ -384,6 +428,27 @@ t.toCreateSql("users", "postgres");
 // CREATE TABLE users (id SERIAL PRIMARY KEY, email VARCHAR(255) NOT NULL)
 ```
 
+#### `index(columns, name?)` / `uniqueIndex(columns, name?)`
+
+Add a (possibly composite) index or unique index; `columns` is a name or array.
+Emitted as `CREATE [UNIQUE] INDEX` after the table. Auto-named unless `name` is
+given.
+
+```ts
+t.index("email");
+t.uniqueIndex(["team_id", "slug"]);
+```
+
+#### `foreign(column)`
+
+`foreign(column: string): ForeignKeyBuilder`
+
+Add a foreign key, built fluently and emitted inline in the `CREATE TABLE`.
+
+```ts
+t.foreign("team_id").references("id").on("teams").onDelete("cascade");
+```
+
 #### `columns`
 
 `readonly columns: Column[]`
@@ -391,6 +456,21 @@ t.toCreateSql("users", "postgres");
 The `Column` instances added so far, in declaration order. Read-only inspection
 seam; you rarely touch it.
 
+### `AlterTableBuilder`
+
+From the `alterTable` callback. Column methods (`string`, `integer`, …) **add**
+columns; plus:
+
+- `dropColumn(name)` — drop a column.
+- `renameColumn(from, to)` — rename a column.
+- `index(columns, name?)` / `uniqueIndex(columns, name?)` — add an index.
+- `dropIndex(name)` — drop an index (runs before column drops).
+
+### `ForeignKeyBuilder`
+
+From `TableBuilder.foreign(column)`. Chainable: `references(column)`, `on(table)`,
+`onDelete(action)`, `onUpdate(action)`.
+
 ### `Column`
 
 A single column definition. **You get one from a `TableBuilder` method** (`t.string(...)` etc.) — you don't construct it in migrations. Modifier methods

package/docs/models.md

@@ -173,6 +173,110 @@ return json(user);       // works directly — json() serializes it
 user.fill({ name: "X" }); // merge mass-assignable attributes without saving
 ```
 
+Control what `toJSON()` exposes with three statics. `hidden` strips columns;
+`visible` is an allowlist that wins over everything; `appends` adds computed
+attributes — a getter or a zero-arg method on the model:
+
+```ts
+class User extends Model {
+  static table = "users";
+  static hidden = ["password"];       // never serialized
+  static appends = ["fullName"];      // added to the output
+  get fullName() { return `${this.first} ${this.last}`; }
+}
+```
+
+## Lifecycle events
+
+A model fires events as it is retrieved, saved, and deleted. Hook onto them to
+slug a title, bust a cache, or cascade — without touching every call site. The
+`*ing` events are **cancelable**: a hook returning `false` aborts the write.
+
+```ts
+User.creating((user) => { user.uuid = crypto.randomUUID(); });
+User.saved((user) => cache().forget(`user:${user.id}`));
+User.deleting((user) => (user.isRoot ? false : undefined)); // veto
+
+// Or group them in an observer:
+User.observe({
+  creating: (u) => { u.uuid = crypto.randomUUID(); },
+  deleted:  (u) => audit(`deleted ${u.id}`),
+});
+```
+
+Events: `retrieved`, `creating`/`created`, `updating`/`updated`,
+`saving`/`saved`, `deleting`/`deleted`, `restoring`/`restored`. They're keyed by
+the exact class (subclasses don't inherit a parent's hooks).
+
+## Query scopes
+
+A **global scope** constrains every query a model builds — the base for
+multi-tenancy, published-only reads, and soft deletes:
+
+```ts
+Post.addGlobalScope("published", (q) => q.where("published", true));
+await Post.all();        // only published
+await Post.query().where("author_id", 1).get();  // still only published
+```
+
+Scopes **inherit**. A scope declared on a base class constrains every model that
+extends it — which is what makes a single tenant-scoped base class possible:
+
+```ts
+class TenantModel extends Model {}
+TenantModel.addGlobalScope("tenant", (q) => q.where("teamId", currentTeamId()));
+
+class Post extends TenantModel {}   // scoped, without repeating yourself
+```
+
+Scopes from several levels all apply, and a subclass overrides an ancestor's scope
+by reusing its name — the nearest declaration wins.
+
+### Escaping a scope
+
+```ts
+await Post.withoutGlobalScope("tenant").get();   // one named scope
+await Post.withoutGlobalScopes().get();          // all of them
+```
+
+Escaping is deliberately explicit, and worth keeping that way. A query that steps
+outside a tenancy scope is exactly the thing you want to be able to *find* — so it
+should be typed out and greppable, never something you arrive at by forgetting a
+`where`.
+
+A **local scope** is just a static method returning a query — no framework
+feature needed:
+
+```ts
+class Post extends Model {
+  static popular() { return this.query().where("views", ">", 1000); }
+}
+await Post.popular().orderBy("views", "desc").get();
+```
+
+## Soft deletes
+
+Opt in with `static softDeletes = true` and a `deleted_at` column. `delete()`
+then sets the timestamp instead of removing the row, and a global scope hides
+soft-deleted rows from every query.
+
+```ts
+class User extends Model {
+  static table = "users";
+  static softDeletes = true;
+  static casts = { deleted_at: "date" };
+}
+
+await user.delete();          // sets deleted_at; row stays in the table
+user.trashed();               // true
+await User.find(user.id);     // null — hidden by the scope
+
+await User.withTrashed().get();   // include soft-deleted
+await User.onlyTrashed().get();   // only soft-deleted
+await user.restore();             // clear deleted_at
+await user.forceDelete();         // remove the row for good
+```
+
 ## Relationships
 
 Define a relationship as a method that returns one of `hasMany` / `hasOne` /
@@ -222,6 +326,29 @@ users[0].toJSON();             // includes `posts` and `roles`
 Loaded relations are stored off the model, so they never leak into `save()`,
 and `toJSON()` serializes them (nested models included).
 
+### Querying relationships (`with`, `withCount`, `whereHas`)
+
+`Model.query()` returns a model-aware builder with the relationship operations a
+raw query can't express. `with()` eager-loads (dotted paths nest), `withCount()`
+adds a `<relation>_count`, and `has`/`whereHas`/`doesntHave` filter by whether a
+related row exists:
+
+```ts
+const users = await User.query()
+  .where("active", true)
+  .with("posts.comments")                       // nested eager load
+  .withCount("posts")                            // users[i].posts_count
+  .whereHas("posts", (q) => q.where("published", true))
+  .get();
+
+await User.has("posts").get();        // users with at least one post
+await User.doesntHave("posts").get(); // users with none
+```
+
+`with`/`withCount`/`whereHas`/`has`/`doesntHave` are also static shortcuts
+(`User.with(...)`, `User.whereHas(...)`). Existence filters use the same
+driver-agnostic two-query strategy as the relations themselves — no JOIN.
+
 ### Many-to-many
 
 `belongsToMany` reads through a pivot table (default name: the two table names
@@ -242,11 +369,39 @@ this.belongsTo(User, "owner_id", "id");
 this.belongsToMany(Role, "user_roles", "user_id", "role_id");
 ```
 
+### Polymorphic
+
+A polymorphic relation lets one model belong to more than one type. The related
+rows carry `<name>_id` + `<name>_type`; register each owner type so `morphTo`
+can resolve it:
+
+```ts
+class Post extends Model {
+  comments() { return this.morphMany(Comment, "commentable"); }
+}
+class Video extends Model {
+  comments() { return this.morphMany(Comment, "commentable"); }
+}
+class Comment extends Model {
+  commentable() { return this.morphTo("commentable"); } // resolves back to Post or Video
+}
+
+registerMorphType("Post", Post);
+registerMorphType("Video", Video);
+
+await post.comments().create({ body: "nice" }); // sets commentable_id/_type
+const owner = await comment.commentable();       // Post | Video | null
+```
+
+`morphOne` is the one-to-one variant. Eager loading (`Model.load` / `with`) works
+across mixed types.
+
 ## What this is (and isn't)
 
-This is a deliberately small active-record — enough for CRUD, relationships,
-casts, and simple queries without an ORM dependency. Nested eager loading
-(`posts.comments`) and query-time `with()` aren't here yet. For complex schemas
+This is a compact active-record — CRUD, lifecycle events, scopes, soft deletes,
+serialization control, eager loading (including nested `with("posts.comments")`),
+relationship queries (`whereHas`/`withCount`), and polymorphic relations — all on
+a driver-agnostic query builder, no ORM dependency. For complex one-off queries
 you can always drop to `db()` or your driver directly.
 
 ---
@@ -402,6 +557,55 @@ Rarely called directly — `create`/`save` use it internally.
 const storable = Post.toDatabase({ published: true }); // { published: 1 }
 ```
 
+#### `Model.with(...names)` · `Model.withCount(...names)`
+
+Start a [`ModelQuery`](#modelquery) that eager-loads the named relations (dotted
+paths nest: `"posts.comments"`) or counts them into `<relation>_count`.
+
+#### `Model.has(name)` · `Model.whereHas(name, constrain?)` · `Model.doesntHave(name, constrain?)`
+
+Start a `ModelQuery` filtered by relationship existence — has at least one
+related row, has one matching `constrain(query)`, or has none. `constrain`
+receives the related-table query builder.
+
+#### `Model.newQuery()`
+
+`static newQuery(): ModelQuery<T>`
+
+The model-aware query behind the sugar above — hydrates rows to models and adds
+`with`/`withCount`/`whereHas`.
+
+#### `Model.addGlobalScope(name, scope)`
+
+`static addGlobalScope(name: string, scope: (query: QueryBuilder) => void): void`
+
+Register a constraint applied to every query the model builds. Inherited by
+subclasses; a subclass re-using a name overrides it.
+
+#### `Model.withTrashed()` · `Model.onlyTrashed()` · `Model.withoutGlobalScope(...names)` · `Model.withoutGlobalScopes()`
+
+Escape hatches returning a `QueryBuilder`: include (or only) soft-deleted rows,
+or drop named / all global scopes. Deliberately explicit so an unscoped query is
+greppable at audit time.
+
+### `Model` — lifecycle events
+
+Register per-class hooks (keyed by the exact class). The `*ing` events are
+cancelable — a hook returning `false` aborts the operation.
+
+#### `Model.creating` · `created` · `updating` · `updated` · `saving` · `saved` · `deleting` · `deleted` · `restoring` · `restored` · `retrieved`
+
+`static <event>(hook: (model: T) => void | boolean | Promise<void | boolean>): void`
+
+Add a hook for that lifecycle event. `create()` fires `saving`→`creating`→write→
+`created`→`saved`; a save that updates fires the `updating`/`updated` pair.
+
+#### `Model.observe(observer)`
+
+`static observe(observer: Partial<Record<ModelEvent, ModelHook<T>>>): void`
+
+Attach an observer object — each method named after an event becomes a hook.
+
 ### `Model` — configuration statics
 
 Set these on the subclass to configure it. All have defaults.
@@ -462,6 +666,21 @@ class Post extends Model {
 }
 ```
 
+#### `static hidden` / `static visible` / `static appends`
+
+`static hidden: string[]` · `static visible: string[]` · `static appends: string[]`
+
+Shape `toJSON()`: `hidden` strips columns, `visible` is an allowlist that wins,
+`appends` adds computed attributes (a getter or zero-arg method). All default `[]`.
+
+#### `static softDeletes` / `static deletedAtColumn`
+
+`static softDeletes: boolean` (default `false`) · `static deletedAtColumn: string`
+(default `"deleted_at"`)
+
+Turn on soft deletes: `delete()` sets the timestamp and a global scope hides
+trashed rows.
+
 ### `Model` — instance methods
 
 #### `new Model(attributes?)`
@@ -500,14 +719,22 @@ still issues the query.
 
 `delete(): Promise<void>`
 
-Deletes the row matching this model's primary key.
+Deletes the row matching this model's primary key — or, with `static softDeletes`
+on, sets `deleted_at` instead. Fires `deleting`/`deleted`.
 
 ```ts
 await user.delete();
 ```
 
-**Notes:** keys off the current `primaryKey` value; on a model without one, the
-`where` binds `undefined`. Hard delete only — there's no soft-delete built in.
+**Notes:** keys off the current `primaryKey` value. See `forceDelete`/`restore`
+for the soft-delete variants.
+
+#### `forceDelete()` · `restore()` · `trashed()`
+
+`forceDelete(): Promise<void>` · `restore(): Promise<this>` · `trashed(): boolean`
+
+For soft-deletable models: permanently remove the row, clear `deleted_at`
+(fires `restoring`/`restored`), or test whether it's currently trashed.
 
 #### `fill(attributes)`
 
@@ -637,6 +864,52 @@ joined with `_` (User + Role → `role_user`). The pivot keys default to
 `<model>_<primaryKey>`. Reads as two `whereIn` queries (no JOIN), so it stays
 edge-safe.
 
+#### `morphMany(related, name, localKey?)` · `morphOne(related, name, localKey?)`
+
+`morphMany<T>(related: ModelClass<T>, name: string, localKey?: string): MorphMany<T>`
+
+The parent side of a polymorphic relation. Related rows carry `<name>_id` +
+`<name>_type` (the type stored is this model's class name). `MorphMany` also has
+`.create(attributes)`, which fills the morph keys.
+
+```ts
+comments() { return this.morphMany(Comment, "commentable"); }
+```
+
+#### `morphTo(name, idColumn?, typeColumn?)`
+
+`morphTo(name: string, idColumn?: string, typeColumn?: string): MorphTo`
+
+The owning side — resolves the parent from the stored `<name>_type` (via
+[`registerMorphType`](#registermorphtypetype-model)) and `<name>_id`. Awaitable;
+returns the parent model or `null`.
+
+```ts
+commentable() { return this.morphTo("commentable"); }
+```
+
+#### `registerMorphType(type, model)`
+
+`registerMorphType(type: string, related: ModelClass<Model>): void`
+
+Register a model under a morph-type string (usually its class name) so `morphTo`
+can resolve it. Call once at boot for each owner type.
+
+### `ModelQuery`
+
+The model-aware builder returned by `Model.query()`, `Model.newQuery()`, and the
+`with`/`whereHas`/`withCount` shortcuts. It proxies the query-builder constraint
+methods (`where`, `orderBy`, `limit`, …) and hydrates results to models, adding:
+
+- `with(...names)` — eager-load relations; dotted paths nest (`"posts.comments"`).
+- `withCount(...names)` — add `<relation>_count` to each result.
+- `has(name)` / `whereHas(name, constrain?)` / `doesntHave(name, constrain?)` —
+  filter by relationship existence.
+- Terminals `get()`, `first()`, `count()`, `exists()`, `paginate(page?, perPage?)`.
+
+Existence filters and counts use the same driver-agnostic two-query strategy as
+the relations (no JOIN). `toBase()` returns the underlying `QueryBuilder`.
+
 ### Relations
 
 You never `new` these — a relationship method (`user.posts()`) returns one. Each

package/docs/teams.md

@@ -0,0 +1,176 @@
+# Teams
+
+Multi-tenancy, membership, roles, and invitations — where a row belongs to a team,
+and one team can never see another's.
+
+```ts
+// bootstrap/providers.ts
+import { TeamsServiceProvider } from "@shaferllc/keel/teams";
+
+app.register(TeamsServiceProvider);
+```
+
+```ts
+// app/Http/Kernel.ts
+import { teamContext } from "@shaferllc/keel/teams";
+
+protected middleware = [sessionMiddleware(), teamContext()];
+```
+
+Then a tenant-owned model is one word:
+
+```ts
+import { TenantModel } from "@shaferllc/keel/teams";
+
+class Post extends TenantModel {
+  static table = "posts";
+}
+
+await Post.all();                     // only the current team's posts
+await Post.create({ title: "Hi" });   // stamped with the current team
+```
+
+## Isolation is the default, not a habit
+
+Two halves, and both matter.
+
+**Reads** are constrained by a global scope on `TenantModel`, so every query the
+model builds carries the team — including `find()`. Naming another team's row by its
+id returns `null`, not that row. This is the difference between tenancy and a list
+filter: a filter you forget on one endpoint is a leak; a scope you never write can't
+be forgotten.
+
+**Writes** are stamped by a `creating` hook, so a row cannot be born ownerless and
+end up visible to everyone (or to no one).
+
+## No team means an error, not "everything"
+
+A queued job, a console command, a webhook, a seeder — none of them run inside a
+request, so none of them have a team. **A tenant query there throws.**
+
+```ts
+await Post.all();
+// Error: No team in context, so a tenant-scoped query can't be built safely.
+//   Inside a request, add teamContext() to your middleware.
+//   In a job, command, or seeder, wrap the work: runForTeam(team, () => …).
+//   If it genuinely spans every team, say so: withoutTenant(() => …).
+```
+
+This is the security model, and the alternatives are worse:
+
+| If no team meant… | Then |
+| --- | --- |
+| *unscoped* | every background job sees every tenant's rows — this is how customer A's invoice reaches customer B |
+| `teamId = NULL` | jobs match nothing, "work" fine, and quietly do nothing for a month |
+| **an error** | a job that forgot **crashes in development** instead of leaking in production |
+
+So a job says which team it's for:
+
+```ts
+await runForTeam(team, () => sendInvoices());
+```
+
+...or says, out loud, that it isn't for one:
+
+```ts
+await withoutTenant(() => Post.withoutGlobalScope(TENANT_SCOPE).get());
+```
+
+Both are named calls you can **grep for at audit time**. That's the point: crossing a
+tenant boundary should be something you typed, never something you arrived at by
+forgetting a `where`.
+
+> Your jobs will crash until each one is wrapped. That friction is the feature — it
+> is a loud failure in development in exchange for not having a silent one in
+> production.
+
+The context lives in `AsyncLocalStorage`, not a module global, so two concurrent
+requests can't see each other's team.
+
+## Teams and membership
+
+```ts
+const team = await createTeam("Acme", user.id);   // creator becomes the owner
+
+await teamsFor(user.id);            // the teams a user is in
+await roleOf(user.id, team.id);     // "owner" | "admin" | "member" | null
+await memberOf(user.id, team.id, "admin");
+await switchTeam(user.id, team.id); // false if they aren't a member
+```
+
+A user is in a team **if and only if a membership row says so**. `teams.owner_id` is a
+convenience, not an authorization source.
+
+`switchTeam()` verifies membership, and so does `teamContext()` on every request —
+`users.current_team_id` is just a number on a row the user can influence, so it is
+checked, never trusted. Without that, switching teams would be a matter of writing
+someone else's id onto your own row.
+
+`Team` and `Membership` are deliberately **not** tenant-scoped: "which teams am I in?"
+is a question you have to answer *before* you know which team you're in.
+
+## Roles
+
+`owner` > `admin` > `member`, ordered — an owner can do anything an admin can.
+
+```ts
+router.delete("/posts/:post", …).middleware(requireRole("admin"));
+```
+
+```ts
+roleAtLeast("owner", "admin");   // true
+roleAtLeast("member", "admin");  // false
+```
+
+## Invitations
+
+```ts
+const { token } = await invite(team.id, "grace@example.com", "admin");
+await acceptInvitation(token, user.id, user.email);
+
+await pendingInvitations(team.id);
+await revokeInvitation(id);
+```
+
+Unlike a password-reset link, an invitation **is** a database row — it has to be
+listable ("3 pending") and revocable, and you can't revoke a stateless token. Only the
+token's **hash** is stored, so a database leak doesn't open every pending team.
+
+The invited address is re-checked on accept, so a **forwarded link doesn't let someone
+else join** in the invitee's place — which is the interesting attack on an invitation
+system. Invitations are single-use, expire (72h by default), and re-inviting the same
+address replaces the outstanding invitation rather than stacking duplicates.
+
+## Personal teams
+
+On by default: every new user gets a team of their own, and a solo user is simply a
+team of one.
+
+Worth leaving on even for an app that feels single-user. **Tenancy is not a feature
+you can add later** — bolting a `team_id` onto a schema that already has customer data
+means a backfill, a migration on every table, and rewriting every query. Ignoring a
+team you have costs one unused row. Needing a team you don't have costs a weekend.
+
+## Configuration
+
+```bash
+keel vendor:publish --tag teams-config
+```
+
+```ts
+export default {
+  userTable: "users",
+  personalTeams: true,
+  invitations: { expiresInHours: 72, url: "/invitations/:token" },
+};
+```
+
+## The schema
+
+| Table | |
+| --- | --- |
+| `teams` | name, slug, owner_id |
+| `team_memberships` | team_id, user_id, role — **unique per (team, user)**, enforced by the database |
+| `team_invitations` | team_id, email, role, token **hash**, expires_at |
+
+Plus `current_team_id` on your users table.