@shaferllc/keel 0.81.0 → 0.81.2

package/docs/database.md

@@ -609,6 +609,53 @@ await db("sessions").where("expires_at", "<", now).delete();
 **Notes:** with no `where`, empties the table. There's no soft-delete here — pair
 with a `deleted_at` column and `whereNull` if you want one.
 
+#### `whereColumn(first, operator?, second)` · `whereRaw(sql, bindings?)`
+
+Compare two columns (no binding) or add a raw WHERE fragment with its own
+bindings. `whereColumn("updated_at", ">", "created_at")`; `whereRaw("score >= ?", [10])`.
+
+#### `join(table, first, operator?, second)` · `leftJoin(...)`
+
+Add an `INNER JOIN` / `LEFT JOIN` on an equality (or the given operator).
+Included in `get`, `count`, and aggregates. Qualify ambiguous columns
+(`"posts.user_id"`).
+
+#### `groupBy(...columns)` · `having(column, operator?, value)` · `distinct()`
+
+`GROUP BY`, a bound `HAVING` predicate, and `SELECT DISTINCT`.
+
+#### `orderByRaw(sql)` · `when(condition, then, otherwise?)`
+
+A raw `ORDER BY` fragment; and conditional building — `then(query, value)` runs
+only when `condition` is truthy, else `otherwise`.
+
+#### `increment(column, amount?, extra?)` · `decrement(column, amount?, extra?)`
+
+`increment(column: string, amount = 1, extra: Row = {}): Promise<WriteResult>`
+
+Atomically `column = column ± amount` on matching rows, optionally setting other
+columns in the same statement. Scope with `where`.
+
+#### `upsert(rows, uniqueBy, update?)`
+
+`upsert(rows: Row | Row[], uniqueBy: string[], update?: string[]): Promise<WriteResult>`
+
+Insert rows, updating `update` columns (default: all non-unique) on a conflict
+against `uniqueBy`. Dialect-aware: `ON CONFLICT … DO UPDATE` (sqlite/postgres) or
+`ON DUPLICATE KEY UPDATE` (mysql).
+
+#### `insertOrIgnore(rows)`
+
+Insert one or more rows, skipping any that violate a unique constraint
+(`INSERT OR IGNORE` / `INSERT IGNORE` / `ON CONFLICT DO NOTHING`).
+
+#### `chunk(size, callback)`
+
+`chunk(size: number, callback: (rows: T[]) => void | boolean | Promise<void | boolean>): Promise<void>`
+
+Process results a page at a time so a large table never loads at once. Return
+`false` from the callback to stop early. Pair with `orderBy` for a stable order.
+
 ### Interfaces & types
 
 #### `Connection`

package/docs/examples/teams.ts

@@ -0,0 +1,101 @@
+// Typechecked example for docs/teams.md.
+import { Application, sessionMiddleware } from "@shaferllc/keel/core";
+import {
+  TeamsServiceProvider,
+  TenantModel,
+  TENANT_SCOPE,
+  acceptInvitation,
+  createTeam,
+  currentTeam,
+  invite,
+  memberOf,
+  pendingInvitations,
+  requireRole,
+  revokeInvitation,
+  roleAtLeast,
+  roleOf,
+  runForTeam,
+  switchTeam,
+  teamContext,
+  teamsFor,
+  withoutTenant,
+} from "@shaferllc/keel/teams";
+
+const app = new Application();
+app.register(TeamsServiceProvider);
+
+// Put every request inside a team; TenantModel queries are scoped from then on.
+const middleware = [sessionMiddleware(), teamContext()];
+
+/* -------------------------------- a tenant model -------------------------- */
+
+class Post extends TenantModel {
+  static override table = "posts";
+  static override fillable = ["title"];
+
+  declare id: number;
+  declare title: string;
+}
+
+async function inAHandler() {
+  const mine = await Post.all(); // only the current team's
+  const one = await Post.find(1); // null if it belongs to another team
+  const made = await Post.create({ title: "Hi" }); // stamped with the current team
+  return { mine, one, made, team: currentTeam() };
+}
+
+/* ------------------------------ outside a request ------------------------- */
+
+async function aJob(team: { id: number }) {
+  // Without this, the query throws — it does not quietly return every team's rows.
+  await runForTeam(team, async () => {
+    await Post.all();
+  });
+}
+
+async function anAdminReport() {
+  // Crossing tenants, said out loud so it can be found at audit time.
+  return withoutTenant(() => Post.withoutGlobalScope(TENANT_SCOPE).get());
+}
+
+/* --------------------------------- membership ----------------------------- */
+
+async function onboarding(userId: number) {
+  const team = await createTeam("Acme", userId);
+
+  await teamsFor(userId);
+  await roleOf(userId, team.id);
+  await memberOf(userId, team.id, "admin");
+  await switchTeam(userId, team.id); // false if they aren't a member
+
+  return team;
+}
+
+const adminsOnly = requireRole("admin");
+const ordered = roleAtLeast("owner", "admin"); // true
+
+/* -------------------------------- invitations ----------------------------- */
+
+async function inviteSomeone(teamId: number, userId: number) {
+  const { token, invitation } = await invite(teamId, "grace@example.com", "admin");
+
+  await pendingInvitations(teamId);
+  await revokeInvitation(invitation.id);
+
+  // The invited address is re-checked, so a forwarded link can't be redeemed by
+  // someone else.
+  return acceptInvitation(token, userId, "grace@example.com");
+}
+
+export {
+  app,
+  middleware,
+  Post,
+  inAHandler,
+  aJob,
+  anAdminReport,
+  onboarding,
+  adminsOnly,
+  ordered,
+  inviteSomeone,
+};

package/docs/migrations.md

@@ -285,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]);
 ```
 
@@ -297,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
@@ -413,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[]`
@@ -420,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

@@ -219,6 +219,31 @@ 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:
 
@@ -532,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.
@@ -592,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?)`
@@ -630,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)`
 
@@ -767,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.