@palbase/backend 39.0.0 → 39.1.0

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)`

package/docs/llms-full.txt

@@ -1163,6 +1163,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)`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palbase/backend",
-  "version": "39.0.0",
+  "version": "39.1.0",
   "description": "Palbase Backend SDK — class controllers (@Controller/@Get/@Post + @Body/@QueryParams/@Param), error classes, schema DSL",
   "license": "MIT",
   "repository": {