@shaferllc/keel 0.81.0 → 0.81.1

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.