@palbase/backend 38.0.16 → 39.1.0

package/docs/README.md

@@ -82,7 +82,7 @@ service the controllers call.
 
 > **Never** emit `defineController`, `defineHandler`, `defineEndpoint`, `route.get(...)`,
 > `req.input`, `req.params`, or `req.errors` — those are the removed legacy model
-> and will not compile against `@palbase/backend` 38.
+> and will not compile against `@palbase/backend` 39.
 
 ### Complete CRUD example (copy-pasteable, compiles)
 

package/docs/database.md

@@ -29,6 +29,56 @@ await Database.public.todos.delete(todo.id);
 
 See [schema.md](./schema.md) for the full typed-table surface.
 
+## Tenant-scoped CRUD — `defineRepository`
+
+Most repository classes are the same two lines per method: add the tenant column
+to the predicate, then unwrap the result. Writing that by hand is what makes it
+forgettable, and one forgotten predicate shows one tenant's row to another.
+`defineRepository` produces a BASE CLASS that writes the predicate once.
+
+```ts
+import { defineRepository } from "@palbase/backend";
+
+export class TodoRepository extends defineRepository(
+  Database.public.todos,
+  { tenant: "household_id" },
+) {}
+```
+
+The subclass gets six typed methods, all scoped to the tenant you pass first:
+`list(tenant)`, `find(tenant, id)`, `insert(tenant, values)`,
+`update(tenant, id, patch)`, `updateScoped(tenant, id, patch)` and
+`delete(tenant, id)`. Add your own methods in the subclass body as usual.
+
+`insert` does NOT take the tenant column in its payload — the repository writes
+it. `update` throws `NotFound` when nothing matches, so the caller does not need
+a `null` branch; `updateScoped` runs the same predicate and returns `null`
+instead, for when absence is a value.
+
+The base class constructor takes no arguments, so the DI container resolves the
+subclass by its own name with no extra metadata. `Database` stays ambient rather
+than injected: it is request-scoped, so a reference captured in a constructor
+would carry one request's client into another.
+
+### A row key that is not `id`
+
+The row key defaults to `id`, but it is not fixed — `defineTable` does not
+require an `id` column, and a primary key can sit on any column. Name it:
+
+```ts
+export class DocRepository extends defineRepository(
+  Database.public.docs,
+  { tenant: "org_id", key: "slug" },
+) {}
+
+await new DocRepository().find("org_1", "getting-started");
+```
+
+The key parameter carries the column's OWN type, so a numeric key is typed
+`number` rather than assumed to be a string. If the table has no `id` column and
+you do not name a key, the surface refuses at compile time and the refusal says
+what to do (`MissingRowKey`).
+
 ## Transaction boundaries and retries
 
 Ordinary Database writes commit when the request completes. `$transaction(fn)`
@@ -455,6 +505,85 @@ const rows = await Database.$query(
 A JavaScript array parameter is encoded as a Postgres array literal, so
 `= ANY($1::uuid[])` works.
 
+**Do not reach for `$query` to take a lock.** That is the single most common
+reason this escape hatch gets used, and there are typed primitives for it —
+see the next section.
+
+### Locks — `$lockRows`, `$lockRowsWhere`, `$advisoryXactLock`, `lock: "update"`
+
+Four surfaces, for four different things.
+
+**`Database.$lockRows(table, ids)` — lock these rows, and let the layer order
+them.** You declare the set you are about to touch; the ordering is not yours to
+choose. Trusting the caller's order means two callers entering the same two rows
+in opposite orders, and the bill for a deadlock is not cheap: `deadlock_timeout`
+defaults to **1 second**, so the loser waits a full second before it errors.
+
+```ts
+await Database.$lockRows("accounts", [input.from, input.to]);
+```
+
+It de-duplicates and sorts the ids, then emits
+`SELECT pk … WHERE pk IN (…) ORDER BY pk FOR NO KEY UPDATE` — the same lock mode
+`updateMany`'s CTE takes, because two write paths must share one order and one
+mode or each will wait on the other. It requires a single-column primary key and
+throws if the table has none. An empty list locks nothing and returns.
+
+**`Database.$lockRowsWhere(table, where, { mode })` — lock what a FILTER
+matches.** `$lockRows` asks you to enumerate the set. "Lock every pending entry
+on this account" cannot: the id list only comes out of a query, and the gap
+between that query and the lock is exactly the race the lock exists to close.
+This form selects and locks the set in ONE statement.
+
+```ts
+await Database.$lockRowsWhere("entries", { account_id: id, status: "pending" });
+const rows = await Database.$findMany("entries", { account_id: id, status: "pending" });
+```
+
+The filter is the ordinary one — same compiler as `findMany` and `updateMany`,
+so there is no second filter dialect and no `$query`. It emits
+`SELECT pk … WHERE … ORDER BY pk <lock clause>`, and that `ORDER BY pk` is the
+**same order `updateMany`'s CTE takes**: two transactions entering the same rows
+by different routes cannot take them in opposite orders. Measured against live
+Postgres in both directions.
+
+The lock MODE is yours, and it is deliberately not equalised with `updateMany`'s:
+
+| `mode` | Postgres clause | when |
+|---|---|---|
+| `"update"` (default) | `FOR UPDATE` | you are about to change these rows |
+| `"share"` | `FOR SHARE` | "nobody may change these while I read them" |
+| `"noKeyUpdate"` | `FOR NO KEY UPDATE` | `updateMany`'s own mode — non-key columns |
+
+Forcing everyone onto one mode would make a reader take a stronger lock than it
+needs. What prevents the deadlock is the ORDER, not the mode. An unrecognised
+mode is refused rather than quietly downgraded — a silently weaker lock is
+fail-open.
+
+Two refusals worth knowing before you reach for it: an **empty filter** is
+rejected (locking the whole table is not somewhere you should arrive by
+accident — every writer waits until your transaction ends), and a table with no
+single-column primary key is rejected, because the lock ORDER needs a key.
+
+**`Database.$advisoryXactLock(key)` — lock a NAME, not a row.** For work that
+has no row to lock: "only one statement close runs at a time", or serializing
+retries of the same idempotency key before reading its result.
+
+```ts
+await tx.$advisoryXactLock(`billing.close:${householdId}:${period}`);
+```
+
+The key is text; Postgres wants a 64-bit integer, so it is hashed with
+`hashtextextended` and **the text never enters the SQL**. Only the
+transaction-scoped family is offered (`pg_advisory_xact_lock`): Postgres releases
+it on commit or rollback, so it cannot be forgotten. The session-scoped version
+is deliberately absent — the connection returns to the pool with the lock still
+held, and the next request waits forever.
+
+**`select(where, { lock: "update" })` — a real `FOR UPDATE`**, inside a
+`$transaction` plan. Use it when the rows you want to lock are the rows you were
+about to select anyway.
+
 ### Bulk writes with a conflict rule
 
 Inside a transaction, `insertMany` takes an optional conflict rule — which is how