@palbase/backend 24.3.0 → 25.0.1

package/docs/schema.md

@@ -1,50 +1,108 @@
 # Schema & typed database access
 
-Declare your tables in `db/schema.ts` with `defineSchema`. This drives
+Declare your tables under `db/`, **one file per schema**: `db/public.ts` is the
+schema Palbase expects to find, `db/billing.ts` declares a second one. Each file
+default-exports a `defineSchema("<name>", { tables })` call. That drives
 [migrations](./migrations.md) (additive changes auto-apply on deploy; type
 changes need an explicit migration) and makes `Database.tables.*` typed
 everywhere — by default, with no import and no generic.
 
+> Coming from a single `db/schema.ts` with tables declared inline? That layout is
+> gone, and a push says so by name. The migration guide at
+> `/docs/backend/schema-migration` walks the four changes with before/after code.
+
 ## Defining a schema
 
-The table NAME comes from the object key under `tables`. Each table value is an
-object whose only required field is `columns`; `rls` and `policies` enable
+A table is declared with `defineTable("<name>", { … })` and is a **value that
+knows its own name**. `defineSchema` takes the schema's name and an ARRAY of
+those values — never a dictionary, because a name in a dictionary key is a second
+place the name is written, and a table built under a key does not yet know what
+to call itself when a sibling references it.
+
+Each table's only required field is `columns`; `rls` and `policies` enable
 [Row-Level Security](#row-level-security-rls), and `indexes` declares plain
 btree [indexes](#indexes).
 
 ```ts
 import {
-  defineSchema,
-  uuid, text, integer, boolean, timestamp, jsonb, enumType,
+  defineSchema, defineTable,
+  uuid, text, integer, boolean, timestamp, jsonb, enumType, ownedByUser,
 } from "@palbase/backend";
 
-export default defineSchema({
-  tables: {
-    rooms: {
-      columns: {
-        id: uuid().primaryKey().defaultRandom(),
-        name: text().notNull(),
-        capacity: integer().nullable(),
-        is_active: boolean().default(true),
-        created_at: timestamp().defaultNow(),
-      },
-    },
-    sessions: {
-      columns: {
-        id: uuid().primaryKey().defaultRandom(),
-        room_id: uuid().notNull().references("rooms", "id").onDelete("cascade"),
-        user_id: uuid().notNull(),
-        data: jsonb().nullable(),
-        started_at: timestamp().defaultNow(),
-      },
-    },
-    orders: {
-      columns: {
-        id: uuid().primaryKey().defaultRandom(),
-        status: enumType("order_status", ["pending", "paid", "shipped", "cancelled"]),
-        amount: integer().notNull(),
-      },
-    },
+export const rooms = defineTable("rooms", {
+  columns: {
+    id: uuid().primaryKey().defaultRandom(),
+    name: text().notNull(),
+    capacity: integer().nullable(),
+    is_active: boolean().default(true),
+    created_at: timestamp().defaultNow(),
+  },
+});
+
+export const sessions = defineTable("sessions", {
+  columns: {
+    id: uuid().primaryKey().defaultRandom(),
+    room_id: uuid().references(() => rooms.id).onDelete("cascade"),
+    user_id: ownedByUser(),
+    data: jsonb().nullable(),
+    started_at: timestamp().defaultNow(),
+  },
+});
+
+export const orders = defineTable("orders", {
+  columns: {
+    id: uuid().primaryKey().defaultRandom(),
+    status: enumType("order_status", ["pending", "paid", "shipped", "cancelled"]),
+    amount: integer().notNull(),
+  },
+});
+
+export default defineSchema("public", {
+  tables: [rooms, sessions, orders],
+});
+```
+
+A `defineTable` value **is its columns** — `rooms.id` is the `id` builder, which
+is what makes `references(() => rooms.id)` an ordinary expression. The table's own
+metadata hangs off a symbol rather than a plain field, so a column may be called
+`name`, `columns`, `rls` or `indexes` without shadowing the table's identity.
+
+### One file per schema, and `exposed`
+
+The schema name comes from the declaration; the file name must agree with it. A
+`db/billing.ts` declaring `defineSchema("accounts", …)` is refused at push with
+both names in the error.
+
+`exposed` decides whether a schema is served over `/v1/db`, and the default is
+NOT uniform: **`public` defaults to `true`**, every other schema to `false`. The
+asymmetry is deliberate — `public` is reachable today and stays reachable, because
+a uniform default would silently 404 every existing project's `/v1/db` traffic on
+upgrade, while a schema you add later is not on the internet just because you
+declared it.
+
+```ts
+// db/public.ts — reachable, and you write nothing to get that
+export default defineSchema("public", { tables: [rooms, sessions] });
+
+// db/billing.ts — declared and typed, but not reachable from a client
+export default defineSchema("billing", { tables: [invoices] });
+```
+
+Write the field only to go against the grain — `exposed: false` closes `public`,
+`exposed: true` opens a second schema. Server-side `Database.*` ignores it either
+way: your controllers, jobs and hooks read every schema you declared.
+
+A foreign key may cross schemas: import the table binding and point at it.
+
+```ts
+// db/billing.ts
+import { lists } from "./public";
+
+export const invoices = defineTable("invoices", {
+  columns: {
+    id: uuid().primaryKey().defaultRandom(),
+    list_id: uuid().references(() => lists.id),
+    amount: numeric(),
   },
 });
 ```
@@ -63,9 +121,124 @@ export default defineSchema({
 
 Chainable modifiers: `.primaryKey()`, `.notNull()` (default), `.nullable()`,
 `.default(value)`, `.defaultRandom()` (uuid → `gen_random_uuid()`),
-`.defaultNow()` (timestamp → `now()`), `.references(table, column)`,
+`.defaultNow()` (timestamp → `now()`),
+`.references(() => table.column, { as?, reverseAs?, onDelete? })`,
+`.selfReferences("column", opts?)`,
 `.onDelete("cascade" | "set null" | "restrict" | "no action")`, `.ignored()`.
 
+## Foreign keys
+
+The target of `references` is a **thunk**, not a direct reference. The callback is
+invoked inside `defineSchema`, where every binding exists and every table already
+knows its name — which is what makes a cycle expressible at all: in `x → y, y → x`
+the second table does not exist yet when the first is built.
+
+```ts
+list_id: uuid().references(() => lists.id),
+```
+
+**Pointing at this same table** takes no thunk and no annotation — the target
+table is the one being declared, so there is nothing to defer:
+
+```ts
+parent_id: uuid().nullable().selfReferences("id"),
+```
+
+Naming a column the table does not have is refused where you declare it.
+
+**Two tables that point at each other** need an explicit return type on ONE side,
+and one is enough — measured. Without it TypeScript chases its own tail (TS7022):
+
+```ts
+import { type AnyColumn } from "@palbase/backend";
+
+export const users = defineTable("users", {
+  columns: {
+    id: uuid().primaryKey().defaultRandom(),
+    primary_org_id: uuid().nullable().references((): AnyColumn => orgs.id),
+  },
+});
+
+export const orgs = defineTable("orgs", {
+  columns: {
+    id: uuid().primaryKey().defaultRandom(),
+    owner_id: uuid().nullable().references(() => users.id),
+  },
+});
+```
+
+### Relation names
+
+Every foreign key produces **two** named relations, and the two names are derived
+separately:
+
+| Direction | Where it appears | Default name | Option that changes it |
+|---|---|---|---|
+| forward (child → parent) | on the child | the column minus `_id` — `list_id` → `list` | `as` |
+| reverse (parent → children) | on the parent | the **child table's** name — `lists.todos` | `reverseAs` |
+
+So `todos.list_id → lists` gives `todos.list` and `lists.todos`, and neither
+needs declaring. `as` renames the forward side only: `author_id` declared
+`{ as: "author" }` gives `posts.author` and still gives `users.posts`. That is
+why the two options exist separately — `posts` and `comments` can both call their
+forward relation `author` without colliding, because what lands on `users` is
+`posts` and `comments`.
+
+**Two foreign keys from one table to the same parent** collide on the reverse
+side: both reverse relations want the child table's name. Name them:
+
+```ts
+billing_address_id:  uuid().references(() => addresses.id, { reverseAs: "billed_orders" }),
+shipping_address_id: uuid().references(() => addresses.id, { reverseAs: "shipped_orders" }),
+```
+
+The forward names here (`billing_address`, `shipping_address`) are already
+distinct, so no `as` is needed. Add one when two columns WOULD derive the same
+forward name.
+
+Any two relations resolving to one name on one table are refused at push, with
+both relations named and the option that separates them.
+
+## Rows that belong to a user
+
+There is no `public.users` table: auth users live in the `auth` schema of the same
+Postgres. Three column factories declare a real foreign key onto it. They are
+factories rather than chain methods because the column type, its nullability and
+its `ON DELETE` are part of what each one MEANS — so they cannot be written wrong.
+
+```ts
+user_id:    ownedByUser(),                              // text, NOT NULL, ON DELETE CASCADE
+edited_by:  userRef({ onDelete: "set null" }).nullable(),
+device_id:  installationRef({ onDelete: "cascade" }),
+```
+
+| | `ownedByUser()` | `userRef({ onDelete })` | `installationRef({ onDelete })` |
+|---|---|---|---|
+| References | `auth.users(id)` | `auth.users(id)` | `auth.installations(id)` |
+| Means | the row **belongs to** that user | the row **points at** a user | the row is scoped to an app install |
+| `ON DELETE` | `cascade`, no argument | required: `cascade` / `set null` | required: `cascade` / `set null` |
+| Account erasure follows it | yes | no | no |
+| Per table | **at most one** | unlimited | unlimited |
+
+Several `userRef` columns on one table are fine — they are ordinary foreign keys
+and each takes its own relation name from its column (`created_by`, `edited_by`).
+Only two of them resolving to the SAME name is refused, and `userRef({ onDelete,
+as })` is how you separate them. `auth.users` is not a table of your schema, so
+none of these produce a reverse relation to collide over.
+
+`ownedByUser()` takes no `onDelete` because there is only one correct answer:
+ownership is what account erasure walks, so a row owned by an account has to go
+when the account does. `"set null"` on a `userRef` needs a `.nullable()` column.
+
+**One `ownedByUser()` per table, enforced.** Two on one table are refused at push
+with both column names in the error. The rule exists because the alternative was
+worse than a refusal: when several columns could reference `auth.users`, the owner
+was whichever came FIRST IN DECLARATION ORDER — so moving a `created_by` above a
+`user_id` silently changed which rows an account deletion took with it.
+
+An installation reference is **not** ownership. A user-owned row still needs its
+own `ownedByUser()`, or erasing the account leaves it behind.
+
 ## Removing a column
 
 A deploy applies the schema while the PREVIOUS release is still answering requests, so
@@ -82,23 +255,47 @@ Removing a column is therefore two deploys:
 
 ```ts
 // 1. Mark it. The column stays; nothing breaks; no DDL is produced.
-export const schema = defineSchema({
-  tables: { notes: { columns: { id: uuid().primaryKey(), old_body: text().ignored() } } },
+const notes = defineTable("notes", {
+  columns: { id: uuid().primaryKey(), old_body: text().ignored() },
 });
+export default defineSchema("public", { tables: [notes] });
 ```
 
 ```ts
 // 2. Ship that. Then delete the column and ship again — this time the gate passes,
 //    because the release now serving promised it does not name the column.
-export const schema = defineSchema({
-  tables: { notes: { columns: { id: uuid().primaryKey() } } } },
-});
+const notes = defineTable("notes", { columns: { id: uuid().primaryKey() } });
+export default defineSchema("public", { tables: [notes] });
 ```
 
 `palbase db plan` tells you which step you are on before you push. Locally,
 `palbase db apply` is not restricted — local is where you experiment, and there is no
 traffic to protect.
 
+### When you cannot wait two deploys
+
+There is an escape, and it is deliberately loud:
+
+```
+palbase push --accept-breaking
+```
+
+It opens the gate for one push. Use it when the running release is ALREADY broken and
+the fix is the very change the gate refuses — an incident, not an inconvenience. Outside
+that, two deploys cost less than the one this can break.
+
+It is not silent, and that is the whole design: the push prints the consents it is
+sending, and the server records a `BREAK-GLASS` line naming the digest that was serving
+and every object the gate had refused. So the decision has an author and a time, and
+whoever asks later why a column disappeared finds the answer instead of a normal-looking
+push.
+
+Two things it will not do. It does not apply to a cloud push — `--accept-breaking` there
+is refused by name rather than ignored, because the gate needs to know what is serving
+and only a linked checkout can tell it. And it does not skip the data-loss consent:
+`--approve` is a separate question about erasing rows, and answering one does not answer
+the other.
+
 The word is `ignored` and not `deprecated` on purpose: deprecation is defined, in
 RFC 9745 and in the GraphQL spec alike, as changing NO behaviour. This changes what a
 deploy will accept.
@@ -121,7 +318,7 @@ Add a value instead, and let the old one die:
 
 ```sql
 -- 1. Add the new label. This IS safe while the previous release serves.
---    (Declare it in db/schema.ts; the rail emits ALTER TYPE … ADD VALUE.)
+--    (Declare it in db/public.ts; the rail emits ALTER TYPE … ADD VALUE.)
 -- 2. Move the data:
 UPDATE posts SET status = 'review' WHERE status = 'onay';
 -- 3. Stop naming the old value in the next release.
@@ -142,19 +339,15 @@ used to reject passed after the rename.
 `indexes` declares plain (non-unique) btree indexes over an ordered column list:
 
 ```ts
-export default defineSchema({
-  tables: {
-    sessions: {
-      columns: {
-        id:         uuid().primaryKey().defaultRandom(),
-        room_id:    uuid().notNull().references("rooms", "id"),
-        started_at: timestamp().defaultNow(),
-      },
-      indexes: [
-        { name: "sessions_room_started_idx", columns: ["room_id", "started_at"] },
-      ],
-    },
+export const sessions = defineTable("sessions", {
+  columns: {
+    id:         uuid().primaryKey().defaultRandom(),
+    room_id:    uuid().references(() => rooms.id),
+    started_at: timestamp().defaultNow(),
   },
+  indexes: [
+    { name: "sessions_room_started_idx", columns: ["room_id", "started_at"] },
+  ],
 });
 ```
 
@@ -166,7 +359,7 @@ name and every column are identifier-validated before any SQL is built.
 knowing before you name an index:
 
 - An index that exists in the database but is not in `indexes` is never dropped.
-  `db/schema.ts` does not own the database's indexes; it only adds the ones it
+  Your schema file does not own the database's indexes; it only adds the ones it
   names.
 - Removing an entry from `indexes` therefore does **not** drop the index. Drop it
   in an explicit [migration](./migrations.md).
@@ -192,10 +385,9 @@ nothing. Rather than ship a half-working partial-index path, the typed field
 stays columns-only and `raw()` carries the rest:
 
 ```ts
-import { defineSchema, raw, uuid, text, timestamp } from "@palbase/backend";
+import { defineTable, raw, uuid, text, timestamp } from "@palbase/backend";
 
-// …
-orders: {
+export const orders = defineTable("orders", {
   columns: {
     id:         uuid().primaryKey().defaultRandom(),
     status:     text().notNull(),
@@ -208,7 +400,7 @@ orders: {
       { down: "DROP INDEX IF EXISTS orders_pending_idx" },
     ),
   ],
-},
+});
 ```
 
 `raw()`'s `up` is emitted verbatim on the privileged DDL connection and, like
@@ -218,12 +410,34 @@ and an index is not one.
 
 ## Typed DB access — by default
 
-You do **not** wire anything per endpoint. Saving `db/schema.ts` regenerates
+You do **not** wire anything per endpoint. Saving a file under `db/` regenerates
 `palbase-env.d.ts`, which types `Database.tables.<name>` everywhere — no import
 of the schema, no generic, no cast:
 
 ```ts
-import { Controller, Post, Body, Database, z } from "@palbase/backend";
+// services/room.service.ts — the layer that touches the database.
+import { Database } from "@palbase/backend";
+
+type RoomsTable = typeof Database.tables.rooms;   // typed from db/schema.ts
+
+export class RoomService {
+  private readonly rooms: RoomsTable;
+  constructor(rooms: RoomsTable) { this.rooms = rooms; }
+
+  async create(name: string) {
+    const room = await this.rooms.insert({ name });
+    return { id: room.id, name: room.name };      // room.id: string ✓
+    // room.nope ← compile error
+  }
+}
+
+export const roomService = new RoomService(Database.tables.rooms);
+```
+
+```ts
+// controllers/rooms.controller.ts — HTTP only; no `Database` import here.
+import { Controller, Post, Body, z } from "@palbase/backend";
+import { roomService } from "../services/room.service.js";
 
 const CreateRoomBody = z.object({ name: z.string() });
 const RoomOut = z.object({ id: z.string(), name: z.string() });
@@ -233,10 +447,8 @@ export default class RoomsController {
   @Post("")
   // The return type names the 200 schema — `z.infer<typeof RoomOut>` works
   // inline, no separate `export type` needed.
-  async create(@Body(CreateRoomBody) body: z.infer<typeof CreateRoomBody>): Promise<z.infer<typeof RoomOut>> {
-    const room = await Database.tables.rooms.insert({ name: body.name });
-    return { id: room.id, name: room.name }; // room.id: string ✓
-    // room.nope ← compile error
+  create(@Body(CreateRoomBody) body: z.infer<typeof CreateRoomBody>): Promise<z.infer<typeof RoomOut>> {
+    return roomService.create(body.name);
   }
 }
 ```
@@ -334,36 +546,37 @@ rows.
 ### Owner-scoped `todos` example
 
 ```ts
-import { defineSchema, policy, uuid, text, boolean, timestamp } from "@palbase/backend";
-
-export default defineSchema({
-  tables: {
-    todos: {
-      columns: {
-        id:         uuid().primaryKey().defaultRandom(),
-        owner:      text().notNull(),        // palauth user id (TEXT)
-        title:      text().notNull(),
-        done:       boolean().default(false),
-        created_at: timestamp().defaultNow(),
-      },
-      // `policies` non-empty ⇒ RLS is enabled + FORCEd automatically.
-      policies: [
-        // Read: a user sees only their own todos.
-        policy("pb_todos_owner_select")
-          .for("select")
-          .to("authenticated")
-          .using("owner = (select auth.uid())"),
-
-        // Write: a user can insert/update/delete only rows they own.
-        policy("pb_todos_owner_write")
-          .for("all")
-          .to("authenticated")
-          .using("owner = (select auth.uid())")
-          .withCheck("owner = (select auth.uid())"),
-      ],
-    },
+import {
+  defineSchema, defineTable, policy, ownedByUser,
+  uuid, text, boolean, timestamp,
+} from "@palbase/backend";
+
+export const todos = defineTable("todos", {
+  columns: {
+    id:         uuid().primaryKey().defaultRandom(),
+    owner:      ownedByUser(),           // text FK onto auth.users(id), NOT NULL, CASCADE
+    title:      text().notNull(),
+    done:       boolean().default(false),
+    created_at: timestamp().defaultNow(),
   },
+  // `policies` non-empty ⇒ RLS is enabled + FORCEd automatically.
+  policies: [
+    // Read: a user sees only their own todos.
+    policy("pb_todos_owner_select")
+      .for("select")
+      .to("authenticated")
+      .using("owner = (select auth.uid())"),
+
+    // Write: a user can insert/update/delete only rows they own.
+    policy("pb_todos_owner_write")
+      .for("all")
+      .to("authenticated")
+      .using("owner = (select auth.uid())")
+      .withCheck("owner = (select auth.uid())"),
+  ],
 });
+
+export default defineSchema("public", { tables: [todos] });
 ```
 
 With this in place, `await Database.tables.todos.findMany({})` returns only the
@@ -382,4 +595,3 @@ so they apply without the `acceptDataLoss` confirmation that column drops need.
 > Changing a policy's body (its `USING`/`WITH CHECK` SQL) in place is not yet
 > auto-applied — rename the policy (new `(table, name)`) or drop the old one in
 > a hand-written migration. Policy DROP/rewrite churn is a documented TODO.
-

package/docs/services.md

@@ -273,16 +273,51 @@ stand-in and never needs a database.
 
 ```ts
 // services/note.service.test.ts — `npm test`, no database
-import assert from "node:assert/strict";
 import { test } from "node:test";
+import assert from "node:assert/strict";
+
 import { NoteService } from "./note.service.ts";
 
-test("list filters by owner", async () => {
+// WHY THIS TEST NEEDS NO DATABASE
+//
+// `NoteService` is handed the table it works on rather than reaching for the
+// singleton itself. That constructor is the seam: a stand-in goes in here, and
+// the logic — which rows, whose, in what order — is exercised without a
+// database. Test your own services the same way.
+//
+// When you want the whole database surface instead of one table, `fakeDatabase()`
+// from `@palbase/backend/test` is the stand-in.
+//
+// Node's ESM resolver wants the extension on a relative import inside a test
+// (`./note.service.ts`); this scaffold's `tsconfig.json` allows it.
+
+test("list asks only for the caller's notes", async () => {
   const seen: unknown[] = [];
-  const fake = { findMany: async (q: unknown) => (seen.push(q), []) };
-  await new NoteService(fake as never).list("u_1");
+  const notes = {
+    findMany: async (where: unknown) => {
+      seen.push(where);
+      return [];
+    },
+  };
+
+  await new NoteService(notes as never).list("u_1");
+
   assert.deepEqual(seen, [{ user_id: "u_1" }]);
 });
+
+test("create writes ownership from the argument, never from the body", async () => {
+  const written: unknown[] = [];
+  const notes = {
+    insert: async (row: unknown) => {
+      written.push(row);
+      return row;
+    },
+  };
+
+  await new NoteService(notes as never).create("u_1", "hello");
+
+  assert.deepEqual(written, [{ user_id: "u_1", body: "hello" }]);
+});
 ```
 
 Node's ESM resolver wants the extension on a relative import inside a test

package/package.json

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