@palbase/backend 3.0.0 → 5.0.0

package/docs/llms.txt

@@ -1,6 +1,6 @@
 # Palbase Backend SDK (`@palbase/backend`)
 
-> File-based TypeScript backend SDK. All handler types import service singletons (`Database`, `Cache`, …). Trigger arg differs by type: endpoints use `req`, workers `(payload, meta)`, jobs `(meta)`, hooks/webhooks `(event, meta)`. Middleware is the one exception (`ctx`). Not Express, not Supabase Edge Functions.
+> TypeScript backend SDK. NestJS-style class controllers: `@Controller` classes with `@Get`/`@Post`/… methods and `@Body`/`@Query`/`@Param`/`@User` parameter decorators. All handler types import service singletons (`Database`, `Cache`, …). Trigger arg differs by type: endpoints use parameter decorators, workers `(payload, meta)`, jobs `(meta)`, hooks/webhooks `(event, meta)`. Middleware is the one exception (`ctx`). Not Express, not Supabase Edge Functions.
 
 ## Docs
 

package/docs/migrations.md

@@ -1,98 +1,100 @@
 # Migrations
 
-`db/schema.ts` is the single source of truth for your Postgres schema. On every
-deploy, Palbase diffs your declared schema against the live branch database and
-reconciles it — but *how* it reconciles depends on whether the change is safe to
-apply automatically.
-
-## Two kinds of change
-
-### 1. Additive — auto-applied, no migration file
-
-A new table, or a new **nullable** or **defaulted** column, is additive: the
-deploy applies it automatically (`CREATE TABLE` / `ADD COLUMN`) with no manual
-step and no backfill risk. Just edit `db/schema.ts` and deploy.
-
-```ts
-// before
-todos: {
-  id: uuid().primaryKey().defaultRandom(),
-  title: text().notNull(),
-}
-
-// after — additive: `notes` (nullable) + `priority` (defaulted) auto-apply on deploy
-todos: {
-  id: uuid().primaryKey().defaultRandom(),
-  title: text().notNull(),
-  notes: text().nullable(),
-  priority: text().nullable().default("normal"),
-}
-```
+`db/schema.ts` is the single source of truth for your Postgres schema. You change
+the schema by editing that file, then generating a **migration** from the diff
+with `palbase db diff`. Every schema change — additive or destructive — flows
+through a reviewable migration file committed to git. The deploy applies the
+migrations in `db/migrations/`; nothing is auto-applied behind your back.
 
-> A new **NOT NULL column without a default** is NOT additive-safe on a table
-> that already has rows (there is nothing to put in the existing rows). Make it
-> `.nullable()`, give it a `.default(...)`, or apply it as an explicit migration
-> (add nullable → backfill → set NOT NULL).
+## The workflow
 
-### 2. Destructive / type-changing — needs an explicit migration
+```bash
+# 1. Edit db/schema.ts (add a column, a table, a policy, …)
 
-Renaming or dropping a column, changing a column's type, or adding a NOT NULL
-constraint can lose or corrupt existing data — so the deploy's **drift-gate
-blocks them** and the deploy fails until you provide an explicit migration.
-Write the SQL yourself in `db/migrations/`:
+# 2. Generate the migration from the diff (declared schema vs the live branch)
+palbase db diff -f add_priority
+#   → writes db/migrations/<timestamp>_add_priority.sql
 
+# 3. Review the generated SQL (especially destructive changes — see below),
+#    then commit + push. git push deploys; the migration runs on deploy.
+git add db/migrations && git commit -m "add priority column" && git push
 ```
-db/migrations/
-  001_user_id_to_text.up.sql
-  001_user_id_to_text.down.sql
+
+`palbase db diff` introspects your **live branch database** (there is no local
+database — every branch runs on the server), diffs it against `db/schema.ts`, and
+writes one migration SQL file. If the schema is already in sync it writes nothing
+and tells you so.
+
+## Additive vs destructive
+
+The generated SQL labels what it does. An additive change (new table, new column)
+is plain DDL:
+
+```sql
+-- palbase db diff: add_priority
+-- generated 20260605T142233
+
+ALTER TABLE todos ADD COLUMN IF NOT EXISTS priority text;
 ```
 
+A **destructive** change (dropping a column or table — losing data) is generated
+with a clear warning comment, and `palbase db diff` prints a warning. Review it
+before committing:
+
 ```sql
--- 001_user_id_to_text.up.sql
-ALTER TABLE todos ALTER COLUMN user_id TYPE text USING user_id::text;
+-- DESTRUCTIVE: dropping todos.notes loses its data
+ALTER TABLE todos DROP COLUMN notes;
 ```
 
+A **column type change** is emitted as a commented stub — auto-migration never
+alters types, so you write the real `ALTER ... TYPE` with whatever `USING` cast
+and backfill your data needs:
+
 ```sql
--- 001_user_id_to_text.down.sql
-ALTER TABLE todos ALTER COLUMN user_id TYPE uuid USING user_id::uuid;
+-- TYPE CHANGE: todos.priority text -> integer (review; auto-migrate does not ALTER types)
+-- ALTER TABLE todos ALTER COLUMN priority TYPE integer;
 ```
 
-Migrations are golang-migrate style: numbered `NNN_name.up.sql` / `.down.sql`
-pairs, applied in order and tracked so each runs exactly once (idempotent).
-`db/schema.ts` always describes the **end state**; the migration describes **how
-existing data gets there**. Keep the two in sync — after the migration lands,
-`schema.ts` should already reflect the new column type.
+## The drift gate
+
+You can't push a schema change without its migration:
 
-## The drift-gate
+- **`palbase db check`** exits non-zero when `db/schema.ts` declares something the
+  database lacks (i.e. you edited the schema but didn't run `palbase db diff`).
+- The scaffold installs a **git pre-push hook** that runs `palbase db check`, so a
+  plain `git push` is **blocked** until you generate + commit the migration.
+  (Bypass with `git push --no-verify` — but the deploy-time gate still rejects it.)
+- On deploy, after migrations run, Palbase asserts `db/schema.ts` matches the live
+  database. Any unresolved drift **fails the deploy** and keeps the previous
+  version live — a broken schema never goes out silently.
 
-On deploy, Palbase compares `db/schema.ts` to the live database:
+## `palbase serve` uses the deployed database
 
-- **Additive** diffs → auto-applied.
-- **Type-changing / destructive** diffs **with** a matching migration → the
-  migration runs.
-- **Type-changing / destructive** diffs **without** a migration → the deploy
-  **aborts** and your currently-running version keeps serving.
+`palbase serve` runs your controllers locally but proxies `Database` and `ctx.*`
+to the **deployed** branch — it does not spin up a local Postgres. So a schema
+change in `db/schema.ts` doesn't exist in the database until you generate the
+migration and push. Run `palbase gen-types` (or just `palbase serve`, which
+regenerates on change) after editing the schema to refresh `palbase-env.d.ts` so
+`Database.tables.<name>` is fully typed in your services.
 
-This is deliberate: it stops an accidental column-type change from silently
-dropping production data. A blocked deploy is a prompt to write the migration,
-not a failure to work around.
+## Hand-written migrations
 
-## Local dev: `palbase serve` uses the deployed database
+`db/migrations/*.sql` is plain SQL applied in filename order and tracked in
+`schema_migrations` (idempotent — a migration runs once). `palbase db diff`
+generates them for you, but you can also hand-write one for anything the diff
+can't express (a data backfill, a complex type change with a `USING` cast, a
+trigger). Keep `db/schema.ts` as the declared end-state so the drift gate passes.
 
-`palbase serve` runs your controllers locally but proxies `Database` and
-`ctx.*` to the **deployed** branch — it does **not** spin up a local Postgres or
-apply migrations locally. So when your local `db/schema.ts` or `db/migrations/`
-is ahead of what's deployed, serve prints a note: new tables/columns won't exist
-until you push. Deploy to apply them.
+## Adding a NOT NULL column to a table with rows
 
-## Workflow
+There's nothing to put in existing rows, so do it in two migrations: first add it
+nullable (or with a default) and backfill, then a follow-up `ALTER ... SET NOT
+NULL`. `db/schema.ts` describes the end state; the migrations describe how
+existing data gets there.
 
-1. Edit `db/schema.ts`.
-2. **Additive** change? → `git push`. It auto-migrates on deploy.
-3. **Type change / rename / drop?** → add `db/migrations/NNN_*.up.sql` (+
-   `.down.sql`), then `git push`. The runner applies it; without it the
-   drift-gate blocks the deploy.
-4. `palbase serve` warns locally until the change is deployed.
+## Row-Level Security
 
-See [schema.md](./schema.md) for the column builders and typed
+Add `rls: true` + `policies: [policy(...)]` to a table in `db/schema.ts`; the
+generated migration emits the `ENABLE ROW LEVEL SECURITY` + `CREATE POLICY` DDL.
+See [schema.md](./schema.md) for the column builders, the policy DSL, and typed
 `Database.tables.*` access.

package/docs/routing.md

@@ -1,67 +1,61 @@
 # Routing
 
-Routes are declared in code. A **handler** is one endpoint unit (schema + thin
-logic) with NO route on it; a **controller** is a route map (method+path →
-handler). Putting a controller file under `controllers/` mounts it — there is no
+Routes are declared in code with **class controllers**. A controller is a class
+decorated with `@Controller(basePath)`; each route is a method decorated with
+`@Get`/`@Post`/`@Put`/`@Patch`/`@Delete`. Request input + context are injected
+into the method via **parameter decorators** (`@Body`/`@Query`/`@Param`/`@User`/
+…). Putting a controller file under `controllers/` mounts it — there is no
 central router and no manual registration.
 
 ```ts
-import { defineController, route } from "@palbase/backend";
+import { Controller, Get, Post, Body, Query, Param, User } from "@palbase/backend";
 ```
 
-## Handlers — one endpoint per file, no route
+## Controllers — class + method decorators
 
-A handler declares everything that types `req` (`auth`/`input`/`output`/
-`errors`) and the logic; it has no method or path.
-
-```ts
-// handlers/places/import-nearby.ts
-import { defineHandler, z } from "@palbase/backend";
-import { placeService } from "../../services/place.service.js";
-
-export default defineHandler({
-  auth:   { required: true },
-  input:  z.object({ lat: z.number(), lng: z.number() }),
-  output: z.object({ imported: z.number() }),
-  errors: { quotaExceeded: { status: 429, code: "quota_exceeded" } },
-  handler: (req) => placeService.importNearby(req.input.lat, req.input.lng),
-});
-```
-
-## Controllers — the route map
-
-A controller maps method+path to handlers with `route.get|post|put|patch|delete`.
-The route-map KEY is authoring sugar only (it is NOT the operationId).
+`@Controller(basePath)` marks the class and sets the mount path. Each route
+method declares its verb + subpath; the real work lives in a `services/` class
+(the controller method is thin).
 
 ```ts
 // controllers/places.controller.ts
-import { defineController, route } from "@palbase/backend";
-import importNearby  from "../handlers/places/import-nearby.js";
-import addFavorite   from "../handlers/places/add-favorite.js";
-import listFavorites from "../handlers/places/list-favorites.js";
-
-export default defineController("/places", {
-  importNearby:  route.post("/import",    importNearby),
-  addFavorite:   route.post("/favorites", addFavorite),
-  listFavorites: route.get ("/favorites", listFavorites),
-});
+import { Controller, Get, Post, Body, User } from "@palbase/backend";
+import type { UserT } from "@palbase/backend";
+import { placeService } from "../services/place.service.js";
+import { ImportNearbyBody } from "../models/places/import.js";
+import type { PlaceSchema } from "../models/places/shared.js";  // the return TYPE names the 200 schema
+
+@Controller("/places")
+export default class PlacesController {
+  @Post("/import")
+  importNearby(@Body(ImportNearbyBody) body: ImportNearbyBody, @User() user: UserT): PlaceSchema {
+    return placeService.importNearby(body.lat, body.lng, user.id);
+  }
+
+  @Get("/favorites", { auth: false })
+  listFavorites(): PlaceSchema[] {
+    return placeService.listFavorites();
+  }
+}
 ```
 
-| Map key (sugar) | Method | Full path | operationId (flat) |
+| Method name (sugar) | Verb | Full path | operationId (flat) |
 |---|---|---|---|
 | `importNearby`  | POST | `/places/import`    | `postPlacesImport` |
-| `addFavorite`   | POST | `/places/favorites` | `postPlacesFavorites` |
 | `listFavorites` | GET  | `/places/favorites` | `getPlacesFavorites` |
 
 Rules:
 
 - The full path of a route is `basePath + subpath` (`"/places" + "/import"`).
-- A `{segment}` in a path becomes a route param, read via `req.params.segment`.
-- Each route value MUST be a `route.*(...)` result — a bare handler is a
-  compile error, which keeps logic out of controllers.
+- A `{segment}` in a path becomes a path param, injected via `@Param("segment")`.
+- Input is declared with the parameter decorators — `@Body(schema)`,
+  `@Query(schema)`, `@Param("id")`, `@Headers(schema?)`. The success response is
+  the method's RETURN TYPE (`: PlaceSchema` or `: z.infer<typeof PlaceSchema>`):
+  codegen + the runtime read that named type to drive the OpenAPI 200 response.
+  A body route with no named return type is a build error — annotate `: void`
+  (or `: Promise<void>`) for no body.
 - The operationId is derived FLAT from method + full path (`postPlacesImport`),
-  not from the map key. Change a verb with `route.post` → `route.put` — no file
-  rename.
+  not from the method name. Change `@Post` → `@Put` — no file rename.
 
-See [endpoints.md](./endpoints.md) for the full `defineHandler` config (`req`,
-auth, input/output, errors, middleware) reference.
+See [endpoints.md](./endpoints.md) for the full decorator reference (`@Controller`
+options, the parameter decorators, auth cascade, and error classes).

package/docs/schema.md

@@ -7,8 +7,9 @@ everywhere — by default, with no import and no generic.
 
 ## Defining a schema
 
-The table NAME comes from the object key under `tables` — there is one
-canonical form.
+The table NAME comes from the object key under `tables`. Each table value is an
+object `{ columns, rls?, policies? }` — `columns` is required; `rls` and
+`policies` enable [Row-Level Security](#row-level-security-rls).
 
 ```ts
 import {
@@ -19,23 +20,29 @@ import {
 export default defineSchema({
   tables: {
     rooms: {
-      id: uuid().primaryKey().defaultRandom(),
-      name: text().notNull(),
-      capacity: integer().nullable(),
-      is_active: boolean().default(true),
-      created_at: timestamp().defaultNow(),
+      columns: {
+        id: uuid().primaryKey().defaultRandom(),
+        name: text().notNull(),
+        capacity: integer().nullable(),
+        is_active: boolean().default(true),
+        created_at: timestamp().defaultNow(),
+      },
     },
     sessions: {
-      id: uuid().primaryKey().defaultRandom(),
-      room_id: uuid().notNull().references("rooms", "id").onDelete("cascade"),
-      user_id: uuid().notNull(),
-      data: jsonb().nullable(),
-      started_at: timestamp().defaultNow(),
+      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: {
-      id: uuid().primaryKey().defaultRandom(),
-      status: enumType("order_status", ["pending", "paid", "shipped", "cancelled"]),
-      amount: integer().notNull(),
+      columns: {
+        id: uuid().primaryKey().defaultRandom(),
+        status: enumType("order_status", ["pending", "paid", "shipped", "cancelled"]),
+        amount: integer().notNull(),
+      },
     },
   },
 });
@@ -65,17 +72,22 @@ You do **not** wire anything per endpoint. Saving `db/schema.ts` regenerates
 of the schema, no generic, no cast:
 
 ```ts
-import { defineHandler, z, Database } from "@palbase/backend";
+import { Controller, Post, Body, Database, z } from "@palbase/backend";
 
-export default defineHandler({
-  input: z.object({ name: z.string() }),
-  output: z.object({ id: z.string(), name: z.string() }),
-  handler: async (req) => {
-    const room = await Database.tables.rooms.insert({ name: req.input.name });
+const CreateRoomBody = z.object({ name: z.string() });
+const RoomOut = z.object({ id: z.string(), name: z.string() });
+
+@Controller("/rooms")
+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
-  },
-});
+  }
+}
 ```
 
 `Database.tables.<name>` exposes `insert`, `update(id, data)`, `delete(id)`,
@@ -90,3 +102,103 @@ If you want a row type explicitly, import it from the generated env module:
 import type { Tables } from "@palbase/backend/env";
 type Room = Tables["rooms"]["row"];
 ```
+
+## Row-Level Security (RLS)
+
+RLS pushes per-user access control **into Postgres**: every `Database.*` query
+runs as the request's verified user (the `authenticated` role with that user's
+claims), and the database itself filters rows your policies don't allow. A
+missing `WHERE user_id = …` in your handler can no longer leak another user's
+rows — the policy enforces it. This is the recommended way to scope data per
+user.
+
+Add `policies` (and optionally `rls`) to a table. `policies` being non-empty
+implies `rls: true` automatically (a table with policies must have RLS enabled
+or the policies are inert). Set `rls: true` with no policies only as a
+deliberate deny-all intermediate step.
+
+### The `policy()` builder
+
+`policy(name)` is a fluent builder, just like the column builders:
+
+```ts
+import { policy } from "@palbase/backend";
+
+policy("pb_owner_all")
+  .for("all")                              // "all" | "select" | "insert" | "update" | "delete"
+  .to("authenticated")                     // one or more DB roles; .to() with no args = PUBLIC
+  .using("owner = (select auth.uid())")    // row-visibility filter (SELECT/UPDATE/DELETE)
+  .withCheck("owner = (select auth.uid())"); // write-validation (INSERT/UPDATE)
+```
+
+| Method | Default | Meaning |
+|--------|---------|---------|
+| `.for(cmd)` | `"all"` | The SQL command the policy governs. |
+| `.to(...roles)` | `["authenticated"]` | DB roles the policy applies to. `.to()` with no args targets PUBLIC. |
+| `.using(sql)` | none | `USING (...)` — which existing rows are visible (SELECT/UPDATE/DELETE). |
+| `.withCheck(sql)` | none | `WITH CHECK (...)` — which rows may be written (INSERT/UPDATE). |
+| `.as(mode)` | `"permissive"` | `"permissive"` (policies OR together) or `"restrictive"` (AND together). |
+
+**`auth.uid()`** returns the verified user's id (palauth user id, TEXT) from the
+request's JWT claims. Wrap it as `(select auth.uid())` — Postgres evaluates that
+once per statement (an initPlan) instead of once per row. `auth.role()` and
+`auth.jwt()` are also available. With no user on the request (anon/public),
+`auth.uid()` is `NULL`, so an `owner = (select auth.uid())` policy matches no
+rows.
+
+> Name policies with a `pb_` prefix. Palbase reconciliation only manages
+> policies it authored (`pb_`-prefixed) and never touches policies created by
+> other modules (storage, cron, …).
+
+### 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())"),
+      ],
+    },
+  },
+});
+```
+
+With this in place, `await Database.tables.todos.findMany({})` returns only the
+calling user's rows — no `WHERE owner = …` needed in the handler. To read or
+write across all users (e.g. an admin job), use the explicit bypass:
+`Database.asService()` (see [database.md](./database.md#bypassing-rls--databaseasservice)).
+
+### How policies are applied
+
+On deploy, Palbase diffs your declared schema against the live database and
+applies RLS **additively**: it emits `ENABLE`/`FORCE ROW LEVEL SECURITY` only
+when the table doesn't already have it, and `CREATE POLICY` only for policies
+that don't already exist (keyed by `(table, name)`). These are non-destructive,
+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

@@ -90,15 +90,18 @@ await Notifications.sms.send({ /* PalbaseSmsSendParams */ });
 ## Flags
 
 ```ts
-import { defineHandler, z, Flags } from "@palbase/backend";
-
-export default defineHandler({
-  auth: { required: true },           // req.user is non-null here
-  output: z.object({ enabled: z.boolean() }),
-  handler: async (req) => {
-    const { data: enabled } = await Flags.isEnabled("new-checkout", { userId: req.user.id });
-    const { data: variant } = await Flags.getVariant("button-color", { userId: req.user.id });
+import { Controller, Get, User, Flags, z } from "@palbase/backend";
+import type { UserT } from "@palbase/backend";
+
+const FlagsOut = z.object({ enabled: z.boolean() });
+
+@Controller("/checkout")
+export default class CheckoutController {
+  @Get("/flags")                       // auth omitted → required → user is non-null
+  async flags(@User() user: UserT): Promise<z.infer<typeof FlagsOut>> {  // return type names the 200 schema
+    const { data: enabled } = await Flags.isEnabled("new-checkout", { userId: user.id });
+    const { data: variant } = await Flags.getVariant("button-color", { userId: user.id });
     return { enabled: enabled ?? false };
-  },
-});
+  }
+}
 ```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@palbase/backend",
-  "version": "3.0.0",
-  "description": "Palbase Backend SDK — defineEndpoint, context types, schema DSL",
+  "version": "5.0.0",
+  "description": "Palbase Backend SDK — class controllers (@Controller/@Get/@Post + @Body/@Query/@Param), error classes, schema DSL",
   "license": "MIT",
   "repository": {
     "type": "git",

package/dist/chunk-B7EUJP5W.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/db/schema.ts","../src/db/columns.ts","../src/db/typed-db.ts"],"sourcesContent":["import type { ColumnBuilder } from \"./columns.js\";\n\n/**\n * A map of column builders keyed by column name — the value you write under\n * each key of `defineSchema({ tables: { <name>: <columns> } })`.\n *\n * The default `Record<string, ColumnBuilder>` keeps bare references compiling\n * without a type argument.\n */\nexport type ColumnMap = Record<string, ColumnBuilder>;\n\n/**\n * A table definition with its name and columns.\n *\n * The runtime value shape — `{ name, columns }` — is the contract the Go\n * runtime's `schema_extract.js` reads (it keys tables by `tableDef.name`).\n * `defineSchema` derives `name` from the object key, so authors never repeat\n * the table name.\n *\n * The `C` type parameter preserves the precise per-column phantom types so\n * that downstream mapped types (InsertShape, RowShape) can discriminate on\n * them.\n */\nexport interface TableDef<C extends ColumnMap = ColumnMap> {\n  name: string;\n  columns: C;\n}\n\n/**\n * A schema definition containing multiple tables, keyed by table name.\n *\n * The `T` type parameter preserves the exact `TableDef<...>` type for each\n * table so that `SchemaDef[\"tables\"][\"rooms\"]` resolves to the precise\n * `TableDef<{ id: ColumnBuilder<'uuid', false, true, never>; ... }>`.\n */\nexport interface SchemaDef<\n  T extends Record<string, TableDef> = Record<string, TableDef>,\n> {\n  tables: T;\n}\n\n/** The author-facing input to `defineSchema` — a `tables` map whose keys are\n * the table names and whose values are the column maps. */\nexport interface SchemaInput<T extends Record<string, ColumnMap> = Record<string, ColumnMap>> {\n  tables: T;\n}\n\n/** Map the author's `{ tables: { <name>: <columns> } }` input to the\n * `{ tables: { <name>: TableDef<columns> } }` runtime/type shape. */\ntype TablesFromInput<T extends Record<string, ColumnMap>> = {\n  [K in keyof T]: TableDef<T[K]>;\n};\n\n/**\n * Define a schema. The table NAME comes from the object key — there is one\n * canonical form:\n *\n *   export default defineSchema({\n *     tables: {\n *       todos: {\n *         id:    uuid().primaryKey().defaultRandom(),\n *         title: text().notNull(),\n *       },\n *     },\n *   });\n *\n * The returned value is `{ tables: { todos: { name: \"todos\", columns: {...} } } }`\n * — the exact shape the runtime schema extractor parses. Per-column phantom\n * types are preserved so `Database.tables.todos.insert({...})` is typed.\n *\n * @example\n * import { defineSchema, uuid, text, timestamp } from \"@palbase/backend\";\n *\n * export default defineSchema({\n *   tables: {\n *     todos: {\n *       id:         uuid().primaryKey().defaultRandom(),\n *       title:      text().notNull(),\n *       done:       boolean().default(false),\n *       created_at: timestamp().defaultNow(),\n *     },\n *   },\n * });\n */\nexport function defineSchema<T extends Record<string, ColumnMap>>(\n  input: SchemaInput<T>,\n): SchemaDef<TablesFromInput<T>> {\n  const tables = {} as TablesFromInput<T>;\n  for (const name of Object.keys(input.tables) as (keyof T)[]) {\n    tables[name] = { name: name as string, columns: input.tables[name] };\n  }\n  return { tables };\n}\n","/** On delete action for foreign key references. */\nexport type OnDeleteAction = 'cascade' | 'set null' | 'restrict' | 'no action';\n\n/** Column type identifiers. */\nexport type ColumnType = 'uuid' | 'text' | 'integer' | 'boolean' | 'timestamp' | 'jsonb' | 'enum';\n\n/** Base column definition shared by all column types. */\nexport interface ColumnDef {\n  type: ColumnType;\n  nullable: boolean;\n  primaryKey: boolean;\n  defaultValue?: unknown;\n  defaultRandom?: boolean;\n  defaultNow?: boolean;\n  references?: { table: string; column: string };\n  onDeleteAction?: OnDeleteAction;\n  enumName?: string;\n  enumValues?: string[];\n}\n\n// Phantom brand symbols — never have runtime values; exist only to force\n// TypeScript's structural type system to distinguish ColumnBuilder instances\n// with different type-param combinations. Without these, TS sees all\n// ColumnBuilder<K,...> as structurally identical and the first branch of\n// ColValue matches everything.\ndeclare const __colKind: unique symbol;\ndeclare const __colNullable: unique symbol;\ndeclare const __colHasDefault: unique symbol;\ndeclare const __colEnumValues: unique symbol;\n\n/**\n * Fluent column builder with phantom type params:\n *  K — ColumnType literal (e.g. \"text\", \"integer\")\n *  N — boolean: true when nullable() has been called last (false = NOT NULL)\n *  D — boolean: true when a default has been set\n *  E — enum value union (never for non-enum columns)\n *\n * All four params have defaults so bare `ColumnBuilder` (no args) still\n * satisfies `Record<string, ColumnBuilder>` in schema.ts without modification.\n *\n * The four `declare readonly` brand fields carry the phantom types into the\n * structural shape so that conditional types like ColValue<C> can discriminate\n * on K without requiring runtime values on those fields.\n */\nexport class ColumnBuilder<\n  K extends ColumnType = ColumnType,\n  N extends boolean = boolean,\n  D extends boolean = boolean,\n  E = unknown,\n> {\n  // These fields exist only in the type layer (declared, never initialised at\n  // runtime — TypeScript allows declared class members without an initializer\n  // in strict mode as long as they're never read at runtime).\n  declare readonly [__colKind]: K;\n  declare readonly [__colNullable]: N;\n  declare readonly [__colHasDefault]: D;\n  declare readonly [__colEnumValues]: E;\n\n  readonly _def: ColumnDef;\n\n  constructor(type: K, existingDef?: ColumnDef) {\n    this._def = existingDef ?? {\n      type,\n      nullable: false,\n      primaryKey: false,\n    };\n  }\n\n  /** Mark this column as the primary key. */\n  primaryKey(): ColumnBuilder<K, N, D, E> {\n    this._def.primaryKey = true;\n    return new ColumnBuilder<K, N, D, E>(this._def.type as K, this._def);\n  }\n\n  /** Mark this column as NOT NULL (default). */\n  notNull(): ColumnBuilder<K, false, D, E> {\n    this._def.nullable = false;\n    return new ColumnBuilder<K, false, D, E>(this._def.type as K, this._def);\n  }\n\n  /** Allow NULL values. */\n  nullable(): ColumnBuilder<K, true, D, E> {\n    this._def.nullable = true;\n    return new ColumnBuilder<K, true, D, E>(this._def.type as K, this._def);\n  }\n\n  /** Set a default value. */\n  default(value: unknown): ColumnBuilder<K, N, true, E> {\n    this._def.defaultValue = value;\n    return new ColumnBuilder<K, N, true, E>(this._def.type as K, this._def);\n  }\n\n  /** UUID: generate a random default (gen_random_uuid()). */\n  defaultRandom(): ColumnBuilder<K, N, true, E> {\n    this._def.defaultRandom = true;\n    return new ColumnBuilder<K, N, true, E>(this._def.type as K, this._def);\n  }\n\n  /** Timestamp: default to now(). */\n  defaultNow(): ColumnBuilder<K, N, true, E> {\n    this._def.defaultNow = true;\n    return new ColumnBuilder<K, N, true, E>(this._def.type as K, this._def);\n  }\n\n  /** Add a foreign key reference. */\n  references(table: string, column: string): ColumnBuilder<K, N, D, E> {\n    this._def.references = { table, column };\n    return new ColumnBuilder<K, N, D, E>(this._def.type as K, this._def);\n  }\n\n  /** Set the ON DELETE action for a foreign key reference. */\n  onDelete(action: OnDeleteAction): ColumnBuilder<K, N, D, E> {\n    this._def.onDeleteAction = action;\n    return new ColumnBuilder<K, N, D, E>(this._def.type as K, this._def);\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Type extractors — imported by Task 2 to derive insert/row shapes.\n// ---------------------------------------------------------------------------\n\n/**\n * Extracts the TypeScript value type for a column, respecting nullability.\n * - \"uuid\" | \"text\" | \"timestamp\" → string (or string | null when N = true)\n * - \"integer\" → number\n * - \"boolean\" → boolean\n * - \"jsonb\" → unknown (opaque JSON)\n * - \"enum\" → E (the union of literal values)\n */\nexport type ColValue<C> =\n  C extends ColumnBuilder<'uuid' | 'text' | 'timestamp', infer N, infer _D, infer _E>\n    ? N extends true\n      ? string | null\n      : string\n    : C extends ColumnBuilder<'integer', infer N, infer _D, infer _E>\n      ? N extends true\n        ? number | null\n        : number\n      : C extends ColumnBuilder<'boolean', infer N, infer _D, infer _E>\n        ? N extends true\n          ? boolean | null\n          : boolean\n        : C extends ColumnBuilder<'jsonb', infer _N, infer _D, infer _E>\n          ? unknown\n          : C extends ColumnBuilder<'enum', infer N, infer _D, infer E>\n            ? N extends true\n              ? E | null\n              : E\n            : never;\n\n/**\n * True when a column is optional on INSERT:\n *  - nullable columns (N = true) — the DB allows NULL so the field may be omitted\n *  - columns with a default (D = true) — the DB fills in the value when absent\n */\nexport type ColIsOptionalOnInsert<C> =\n  C extends ColumnBuilder<infer _K, true, infer _D, infer _E>\n    ? true\n    : C extends ColumnBuilder<infer _K, infer _N, true, infer _E>\n      ? true\n      : false;\n\n// ---------------------------------------------------------------------------\n// Factory functions\n// ---------------------------------------------------------------------------\n\n/** Create a UUID column. */\nexport function uuid(): ColumnBuilder<'uuid', false, false, never> {\n  return new ColumnBuilder('uuid');\n}\n\n/** Create a TEXT column. */\nexport function text(): ColumnBuilder<'text', false, false, never> {\n  return new ColumnBuilder('text');\n}\n\n/** Create an INTEGER column. */\nexport function integer(): ColumnBuilder<'integer', false, false, never> {\n  return new ColumnBuilder('integer');\n}\n\n/** Create a BOOLEAN column. */\nexport function boolean(): ColumnBuilder<'boolean', false, false, never> {\n  return new ColumnBuilder('boolean');\n}\n\n/** Create a TIMESTAMP column. */\nexport function timestamp(): ColumnBuilder<'timestamp', false, false, never> {\n  return new ColumnBuilder('timestamp');\n}\n\n/** Create a JSONB column. */\nexport function jsonb(): ColumnBuilder<'jsonb', false, false, never> {\n  return new ColumnBuilder('jsonb');\n}\n\n/**\n * Create an ENUM column.\n * @param name   The PostgreSQL enum type name (used in DDL).\n * @param values A readonly tuple of valid string values — kept `const` so the\n *               union `V[number]` is as narrow as possible.\n */\nexport function enumType<const V extends readonly string[]>(\n  name: string,\n  values: V,\n): ColumnBuilder<'enum', false, false, V[number]> {\n  const builder = new ColumnBuilder<'enum', false, false, V[number]>('enum');\n  builder._def.enumName = name;\n  builder._def.enumValues = [...values];\n  return builder;\n}\n","/**\n * typed-db.ts — Task 2: TypedDB schema-derived insert/row shapes.\n *\n * Derives INSERT and full-row TypeScript types from a `defineSchema()` result\n * and wraps the untyped runtime `DBClient` with a typed facade.\n *\n * No value-any. No `as unknown as X`. The two narrow `as` casts in\n * `makeTypedTable` are safe because:\n *  - `data as Record<string, unknown>`: InsertShape<T> maps string keys to\n *    typed values; all value types are subsets of `unknown`, so the cast is\n *    structurally sound.\n *  - `result as RowShape<T>`: The runtime DBClient returns `Record<string,\n *    unknown>` which is the erased form of the typed row; we're narrowing back\n *    to the precise shape that the schema declared.\n * Both casts are narrowing only (not widening) and correctness is guaranteed\n * by the schema the caller provides.\n */\n\nimport type { ColValue, ColIsOptionalOnInsert, ColumnBuilder } from \"./columns.js\";\nimport type { TableDef, SchemaDef } from \"./schema.js\";\nimport type { Tables, TableTypes } from \"./env.js\";\nimport type { DBClient, TxClient } from \"../endpoint.js\";\n\n// ---------------------------------------------------------------------------\n// Key discriminators — split a column map into required vs optional keys.\n// ---------------------------------------------------------------------------\n\n/** Keys of C whose columns are required on INSERT (not nullable, no default). */\ntype RequiredKeys<C> = {\n  [K in keyof C]: ColIsOptionalOnInsert<C[K]> extends true ? never : K;\n}[keyof C];\n\n/** Keys of C whose columns are optional on INSERT (nullable or has a default). */\ntype OptionalKeys<C> = {\n  [K in keyof C]: ColIsOptionalOnInsert<C[K]> extends true ? K : never;\n}[keyof C];\n\n// ---------------------------------------------------------------------------\n// Public shape types — exported so callers can reference them directly.\n// ---------------------------------------------------------------------------\n\n/**\n * The TypeScript type for an INSERT payload for table `T`.\n * - Required: columns that are NOT NULL and have no DB-level default.\n * - Optional: columns that are nullable or carry a default.\n *\n * When all columns are optional, `RequiredKeys<C>` resolves to `never` and\n * the first part becomes `{}`, which is a neutral element for `&`.\n */\nexport type InsertShape<T extends TableDef> = {\n  [K in RequiredKeys<T[\"columns\"]>]: ColValue<T[\"columns\"][K]>;\n} & {\n  [K in OptionalKeys<T[\"columns\"]>]?: ColValue<T[\"columns\"][K]>;\n};\n\n/**\n * The TypeScript type for a full row returned by the DB for table `T`.\n * Every column is present; nullable columns resolve to `T | null`.\n */\nexport type RowShape<T extends TableDef> = {\n  [K in keyof T[\"columns\"]]: ColValue<T[\"columns\"][K]>;\n};\n\n// ---------------------------------------------------------------------------\n// TypedTable + TypedDB interfaces.\n// ---------------------------------------------------------------------------\n\n/** A typed table accessor that mirrors the runtime DBClient surface. */\nexport interface TypedTable<T extends TableDef> {\n  insert(data: InsertShape<T>): Promise<RowShape<T>>;\n  update(id: string, data: Partial<InsertShape<T>>): Promise<RowShape<T>>;\n  delete(id: string): Promise<void>;\n  findById(id: string): Promise<RowShape<T> | null>;\n  findMany(query?: Partial<RowShape<T>>): Promise<RowShape<T>[]>;\n}\n\n/** A typed DB facade covering all tables declared in schema `S`. */\nexport interface TypedDB<S extends SchemaDef> {\n  tables: {\n    [K in keyof S[\"tables\"]]: TypedTable<S[\"tables\"][K]>;\n  };\n  transaction<T>(fn: (tx: TypedTx<S>) => Promise<T>): Promise<T>;\n}\n\n/** Transaction-scoped typed facade: same typed tables, no nested transaction. */\nexport interface TypedTx<S extends SchemaDef> {\n  tables: {\n    [K in keyof S[\"tables\"]]: TypedTable<S[\"tables\"][K]>;\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Runtime factory.\n// ---------------------------------------------------------------------------\n\n/**\n * Builds a typed table accessor that delegates every call to `raw` using the\n * runtime table name string. Two narrow `as` casts bridge the mapped-type\n * shapes to/from `Record<string, unknown>` — see module-level doc comment.\n *\n * The `raw` param is typed `TxClient` (the op surface shared by `DBClient` and\n * the transaction-scoped client) because this only ever calls the five\n * insert/update/delete/findById/findMany ops — never `transaction`. This lets\n * the same factory wrap both the top-level db and a tx without any cast.\n */\nfunction makeTypedTable<T extends TableDef<Record<string, ColumnBuilder>>>(\n  name: string,\n  raw: TxClient,\n): TypedTable<T> {\n  return {\n    insert: (data: InsertShape<T>) =>\n      raw.insert(name, data as Record<string, unknown>) as Promise<RowShape<T>>,\n\n    update: (id: string, data: Partial<InsertShape<T>>) =>\n      raw.update(name, id, data as Record<string, unknown>) as Promise<RowShape<T>>,\n\n    delete: (id: string) => raw.delete(name, id),\n\n    findById: (id: string) =>\n      raw.findById(name, id) as Promise<RowShape<T> | null>,\n\n    findMany: (query?: Partial<RowShape<T>>) =>\n      raw.findMany(name, query as Record<string, unknown> | undefined) as Promise<RowShape<T>[]>,\n  };\n}\n\n/**\n * Wraps a raw `DBClient` with the type-safe `TypedDB<S>` facade derived from\n * the provided schema. No behavior change — all calls delegate to `raw` with\n * the table name as a plain string.\n *\n * `buildTables` is the reusable factory that wraps any op-bearing client\n * (`TxClient` — the surface shared by `DBClient` and the transaction-scoped\n * client) into the typed tables map. It is used both for the top-level db\n * (wrapping `raw`) and inside `transaction`, where it wraps the raw `TxClient`\n * the runtime yields so the callback sees the same typed `.tables` API.\n *\n * `transaction` delegates straight to `raw.transaction`; the two narrow\n * `as TypedTx<S>` / `as TypedDB<S>` casts are single structural narrowings\n * from the dynamically-built tables object to the precise mapped type (TS\n * cannot infer through `Object.keys` iteration) — see module-level doc comment.\n */\nexport function makeTypedDB<S extends SchemaDef>(\n  schema: S,\n  raw: DBClient,\n): TypedDB<S> {\n  function buildTables(client: TxClient): Record<string, TypedTable<TableDef>> {\n    const tables = {} as Record<string, TypedTable<TableDef>>;\n    for (const key of Object.keys(schema.tables)) {\n      const tableDef = schema.tables[key];\n      if (tableDef !== undefined) {\n        tables[key] = makeTypedTable(tableDef.name, client);\n      }\n    }\n    return tables;\n  }\n\n  const result = {\n    tables: buildTables(raw),\n    transaction: <T>(fn: (tx: TypedTx<S>) => Promise<T>): Promise<T> =>\n      raw.transaction((rawTx) => fn({ tables: buildTables(rawTx) } as TypedTx<S>)),\n  };\n\n  // Narrow cast: `result.tables` is structurally identical to\n  // TypedDB<S>[\"tables\"] — each key maps to a TypedTable for the matching\n  // TableDef. TS cannot infer the mapped-type result through Object.keys\n  // iteration, so a single `as` bridges the gap.\n  return result as TypedDB<S>;\n}\n\n// ---------------------------------------------------------------------------\n// Env-augmentation-driven typed surface — the typed-by-default `Database`.\n//\n// These types read the globally-augmented `Tables` interface from\n// `@palbase/backend/env` (filled by the generated `palbase-env.d.ts`). They\n// back `Database.tables.<name>` so handler code is typed with no import and no\n// generic (C5). They DELIBERATELY do not reference `ColumnBuilder` — the env\n// `Tables` interface carries flat `row`/`insert` object types.\n// ---------------------------------------------------------------------------\n\n/** A typed table accessor derived from one env `Tables` entry's flat shapes. */\nexport interface EnvTypedTable<T extends TableTypes> {\n  insert(data: T[\"insert\"]): Promise<T[\"row\"]>;\n  update(id: string, data: Partial<T[\"insert\"]>): Promise<T[\"row\"]>;\n  delete(id: string): Promise<void>;\n  findById(id: string): Promise<T[\"row\"] | null>;\n  findMany(query?: Partial<T[\"row\"]>): Promise<T[\"row\"][]>;\n}\n\n/** The `tables` map exposed on `Database`/`tx`, keyed by the env `Tables`\n * interface. When no schema is declared `Tables` is empty, so `tables` is an\n * empty object — accessing `.tables.foo` is then a compile error (no member). */\nexport type EnvTables = {\n  [K in keyof Tables]: EnvTypedTable<Tables[K]>;\n};\n\n/** Transaction-scoped typed facade for the env-augmented surface: same typed\n * tables, no nested transaction. */\nexport interface EnvTypedTx {\n  tables: EnvTables;\n}\n\n/**\n * The typed-by-default Database surface: the raw string-keyed `DBClient` ops\n * PLUS a `tables` map typed against the project's generated `palbase-env.d.ts`\n * and a `transaction` whose callback receives the typed tables.\n *\n * `transaction` is declared here (overriding `DBClient[\"transaction\"]`) so the\n * `tx` the callback receives carries the typed `.tables` API.\n */\nexport interface EnvTypedDatabase extends Omit<DBClient, \"transaction\"> {\n  tables: EnvTables;\n  transaction<T>(fn: (tx: EnvTypedTx) => Promise<T>): Promise<T>;\n}\n"],"mappings":";AAoFO,SAAS,aACd,OAC+B;AAC/B,QAAM,SAAS,CAAC;AAChB,aAAW,QAAQ,OAAO,KAAK,MAAM,MAAM,GAAkB;AAC3D,WAAO,IAAI,IAAI,EAAE,MAAsB,SAAS,MAAM,OAAO,IAAI,EAAE;AAAA,EACrE;AACA,SAAO,EAAE,OAAO;AAClB;;;AChDO,IAAM,gBAAN,MAAM,eAKX;AAAA,EASS;AAAA,EAET,YAAY,MAAS,aAAyB;AAC5C,SAAK,OAAO,eAAe;AAAA,MACzB;AAAA,MACA,UAAU;AAAA,MACV,YAAY;AAAA,IACd;AAAA,EACF;AAAA;AAAA,EAGA,aAAwC;AACtC,SAAK,KAAK,aAAa;AACvB,WAAO,IAAI,eAA0B,KAAK,KAAK,MAAW,KAAK,IAAI;AAAA,EACrE;AAAA;AAAA,EAGA,UAAyC;AACvC,SAAK,KAAK,WAAW;AACrB,WAAO,IAAI,eAA8B,KAAK,KAAK,MAAW,KAAK,IAAI;AAAA,EACzE;AAAA;AAAA,EAGA,WAAyC;AACvC,SAAK,KAAK,WAAW;AACrB,WAAO,IAAI,eAA6B,KAAK,KAAK,MAAW,KAAK,IAAI;AAAA,EACxE;AAAA;AAAA,EAGA,QAAQ,OAA8C;AACpD,SAAK,KAAK,eAAe;AACzB,WAAO,IAAI,eAA6B,KAAK,KAAK,MAAW,KAAK,IAAI;AAAA,EACxE;AAAA;AAAA,EAGA,gBAA8C;AAC5C,SAAK,KAAK,gBAAgB;AAC1B,WAAO,IAAI,eAA6B,KAAK,KAAK,MAAW,KAAK,IAAI;AAAA,EACxE;AAAA;AAAA,EAGA,aAA2C;AACzC,SAAK,KAAK,aAAa;AACvB,WAAO,IAAI,eAA6B,KAAK,KAAK,MAAW,KAAK,IAAI;AAAA,EACxE;AAAA;AAAA,EAGA,WAAW,OAAe,QAA2C;AACnE,SAAK,KAAK,aAAa,EAAE,OAAO,OAAO;AACvC,WAAO,IAAI,eAA0B,KAAK,KAAK,MAAW,KAAK,IAAI;AAAA,EACrE;AAAA;AAAA,EAGA,SAAS,QAAmD;AAC1D,SAAK,KAAK,iBAAiB;AAC3B,WAAO,IAAI,eAA0B,KAAK,KAAK,MAAW,KAAK,IAAI;AAAA,EACrE;AACF;AAoDO,SAAS,OAAmD;AACjE,SAAO,IAAI,cAAc,MAAM;AACjC;AAGO,SAAS,OAAmD;AACjE,SAAO,IAAI,cAAc,MAAM;AACjC;AAGO,SAAS,UAAyD;AACvE,SAAO,IAAI,cAAc,SAAS;AACpC;AAGO,SAAS,UAAyD;AACvE,SAAO,IAAI,cAAc,SAAS;AACpC;AAGO,SAAS,YAA6D;AAC3E,SAAO,IAAI,cAAc,WAAW;AACtC;AAGO,SAAS,QAAqD;AACnE,SAAO,IAAI,cAAc,OAAO;AAClC;AAQO,SAAS,SACd,MACA,QACgD;AAChD,QAAM,UAAU,IAAI,cAA+C,MAAM;AACzE,UAAQ,KAAK,WAAW;AACxB,UAAQ,KAAK,aAAa,CAAC,GAAG,MAAM;AACpC,SAAO;AACT;;;ACzGA,SAAS,eACP,MACA,KACe;AACf,SAAO;AAAA,IACL,QAAQ,CAAC,SACP,IAAI,OAAO,MAAM,IAA+B;AAAA,IAElD,QAAQ,CAAC,IAAY,SACnB,IAAI,OAAO,MAAM,IAAI,IAA+B;AAAA,IAEtD,QAAQ,CAAC,OAAe,IAAI,OAAO,MAAM,EAAE;AAAA,IAE3C,UAAU,CAAC,OACT,IAAI,SAAS,MAAM,EAAE;AAAA,IAEvB,UAAU,CAAC,UACT,IAAI,SAAS,MAAM,KAA4C;AAAA,EACnE;AACF;AAkBO,SAAS,YACd,QACA,KACY;AACZ,WAAS,YAAY,QAAwD;AAC3E,UAAM,SAAS,CAAC;AAChB,eAAW,OAAO,OAAO,KAAK,OAAO,MAAM,GAAG;AAC5C,YAAM,WAAW,OAAO,OAAO,GAAG;AAClC,UAAI,aAAa,QAAW;AAC1B,eAAO,GAAG,IAAI,eAAe,SAAS,MAAM,MAAM;AAAA,MACpD;AAAA,IACF;AACA,WAAO;AAAA,EACT;AAEA,QAAM,SAAS;AAAA,IACb,QAAQ,YAAY,GAAG;AAAA,IACvB,aAAa,CAAI,OACf,IAAI,YAAY,CAAC,UAAU,GAAG,EAAE,QAAQ,YAAY,KAAK,EAAE,CAAe,CAAC;AAAA,EAC/E;AAMA,SAAO;AACT;","names":[]}

package/dist/chunk-PHAFZGHN.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/runtime.ts"],"sourcesContent":["/**\n * runtime.ts — request-scoped service singletons.\n *\n * The backend SDK no longer threads a `ctx` god-object through every handler.\n * Instead, endpoint authors import PascalCase service singletons directly:\n *\n *   import { Database, Documents, Cache } from \"@palbase/backend\";\n *\n *   export default defineHandler({\n *     handler: async (req) => {\n *       const row = await Database.insert(\"todos\", { title: req.input.title });\n *       return row;\n *     },\n *   });\n *\n * The singletons are thin Proxies. Every property access forwards to the live\n * client for the CURRENT request scope, resolved through {@link __getRuntime}.\n *\n * # Request-scope resolution (persistent app-server)\n *\n * The runtime is a long-running Node process that serves many concurrent\n * requests on one event loop (NOT a fresh subprocess per request). A single\n * module-global slot would let one in-flight request's services bleed into\n * another's. So the services are carried in an {@link AsyncLocalStorage} store\n * ({@link __requestALS}) that the runtime sets per request with\n * {@link __runWithRuntime}; every async continuation of that request reads its\n * own store. `__getRuntime` reads the ALS store first; the module-global slot\n * (set by {@link __setRuntime}) is only a fallback for callers that run OUTSIDE\n * an ALS scope (dev-server, unit tests, the legacy single-shot path). Because\n * each `br-<ref>` pod is single-tenant, there is no cross-tenant leakage; the\n * ALS store is what prevents cross-REQUEST leakage within the shared process.\n *\n * The seam that makes `import { Database } from \"@palbase/backend\"` resolve to\n * the runtime-injected client: `@palbase/backend` is marked esbuild-EXTERNAL\n * when the tenant bundle is built, and the package is installed globally in the\n * pod (NODE_PATH=/usr/local/lib/node_modules). So worker.js's\n * `require('@palbase/backend')` and the bundle's `import` resolve to ONE shared\n * module instance — the ALS store and `__setRuntime` slot on that instance are\n * visible to the singletons the bundle imported.\n */\n\nimport { AsyncLocalStorage } from \"node:async_hooks\";\n\nimport type {\n  DBClient,\n  TxClient,\n  CacheClient,\n  QueueClient,\n  Logger,\n  PalbaseDocsClient,\n} from \"./endpoint.js\";\nimport type {\n  PalbaseStorageClient,\n  PalbaseNotificationsClient,\n  PalbaseFlagsClient,\n} from \"./clients.js\";\nimport type { EnvTypedDatabase, EnvTypedTx, EnvTables } from \"./db/typed-db.js\";\n\n/** The set of live clients the runtime injects per request scope.\n *\n * EXCLUDED on purpose: Realtime, Functions, CMS, Links, Analytics, Auth. They\n * are not exposed as backend handler singletons (auth lives on the client SDK;\n * the rest are out of scope for backend endpoints). */\nexport interface RuntimeServices {\n  Database: DBClient;\n  Documents: PalbaseDocsClient;\n  Storage: PalbaseStorageClient;\n  Cache: CacheClient;\n  Queue: QueueClient;\n  Log: Logger;\n  Notifications: PalbaseNotificationsClient;\n  Flags: PalbaseFlagsClient;\n}\n\n/**\n * Per-request store. The persistent runtime runs each request inside\n * {@link __runWithRuntime}, so every async continuation of that request reads\n * its OWN `runtime` (and any other request-scoped fields the runtime adds).\n *\n * Exported with a `__` prefix so the runtime (worker.js) shares the SAME ALS\n * instance across the one module instance — two ALS instances would silently\n * not see each other's stores. NOT part of the public author-facing API.\n */\nexport const __requestALS = new AsyncLocalStorage<{ runtime: RuntimeServices }>();\n\n/** Process-global fallback slot. Used only OUTSIDE an ALS scope (dev-server,\n * unit tests, legacy single-shot worker). Inside the persistent server every\n * request runs in {@link __requestALS}, which takes precedence. */\nlet runtime: RuntimeServices | null = null;\n\n/** Install the live clients in the process-global fallback slot.\n *\n * Persistent-server requests should use {@link __runWithRuntime} instead; this\n * remains for dev-server / tests / the legacy single-shot path that run without\n * an ALS scope. NOT part of the public author-facing API. */\nexport function __setRuntime(services: RuntimeServices): void {\n  runtime = services;\n}\n\n/** Run `fn` with `services` bound as the request-scoped runtime.\n *\n * The persistent worker calls this once per request so concurrent requests\n * never share a services slot. NOT part of the public author-facing API. */\nexport function __runWithRuntime<T>(services: RuntimeServices, fn: () => T): T {\n  return __requestALS.run({ runtime: services }, fn);\n}\n\n/** Read the live clients, throwing if accessed outside a request scope.\n *\n * Resolves the ALS store first (persistent server, per-request), then the\n * process-global fallback (dev-server / tests). NOT part of the public\n * author-facing API — used by the runtime and the singleton Proxies. */\nexport function __getRuntime(): RuntimeServices {\n  const scoped = __requestALS.getStore();\n  if (scoped) return scoped.runtime;\n  if (runtime === null) {\n    throw new Error(\n      \"Palbase services accessed outside a request scope. The Database/Documents/… \" +\n        \"singletons are only available inside an endpoint handler (or after the \" +\n        \"runtime has called __runWithRuntime / __setRuntime).\",\n    );\n  }\n  return runtime;\n}\n\n/**\n * Build a Proxy singleton that forwards every property access to the live\n * client named `key` on the current runtime.\n *\n * The single `as RuntimeServices[K]` is the only contained cast in the surface:\n * `Reflect.get` on a typed object returns `unknown` for a `string | symbol`\n * key, but `prop` is constrained to keys of the client interface at the call\n * sites (the exported singletons are typed below), so the forward is sound.\n */\nfunction makeServiceProxy<K extends keyof RuntimeServices>(key: K): RuntimeServices[K] {\n  const handler: ProxyHandler<RuntimeServices[K]> = {\n    get(_target, prop, receiver) {\n      const client = __getRuntime()[key];\n      const value = Reflect.get(client as object, prop, receiver) as unknown;\n      // Bind methods to their owning client so `this` stays correct when the\n      // author destructures or calls `Database.query(...)`.\n      return typeof value === \"function\" ? value.bind(client) : value;\n    },\n  };\n  // The Proxy target is irrelevant (all access goes through `get`); the cast\n  // names the surface type the singleton presents to authors.\n  return new Proxy({} as RuntimeServices[K], handler);\n}\n\n/**\n * Build the `.tables` accessor for an op-bearing client (the top-level\n * `Database` or a transaction-scoped `tx`). Each `tables.<name>` access\n * returns a small object that forwards the five CRUD ops to the underlying\n * client using `name` as the string table identifier. The shapes are typed\n * against the generated `palbase-env.d.ts` (`EnvTables`); at runtime they are\n * plain string-keyed calls, so no schema value is needed here.\n *\n * Returns `EnvTables` — TS cannot infer the mapped type through the Proxy, so\n * a single structural narrowing names the surface (the proxy returns a\n * correctly-shaped accessor for whatever string member is read).\n */\nfunction makeTablesAccessor(ops: () => TxClient): EnvTables {\n  const tablesProxy = new Proxy(\n    {},\n    {\n      get(_t, prop: string | symbol) {\n        if (typeof prop !== \"string\") return undefined;\n        const name = prop;\n        return {\n          insert: (data: Record<string, unknown>) => ops().insert(name, data),\n          update: (id: string, data: Record<string, unknown>) => ops().update(name, id, data),\n          delete: (id: string) => ops().delete(name, id),\n          findById: (id: string) => ops().findById(name, id),\n          findMany: (query?: Record<string, unknown>) => ops().findMany(name, query),\n        };\n      },\n    },\n  );\n  return tablesProxy as EnvTables;\n}\n\n/** The raw string-keyed `DBClient` for the current request scope. */\nconst rawDatabase: DBClient = makeServiceProxy(\"Database\");\n\n/**\n * The project's own Postgres (pgx, schema `env_<envId>`).\n *\n * Typed by default: `Database.tables.<name>.insert({...})` is typed against\n * the project's generated `palbase-env.d.ts` with NO import and NO generic.\n * The raw string ops (`query`/`insert`/`update`/`delete`/`findById`/`findMany`)\n * are also available for dynamic table names and read-only SQL.\n *\n * @example\n * import { Database } from \"@palbase/backend\";\n *\n * const todo = await Database.tables.todos.insert({ title: req.input.title });\n * todo.id; // string ✓\n * const rows = await Database.query(\"SELECT id FROM todos WHERE done = $1\", [false]);\n */\nexport const Database: EnvTypedDatabase = Object.assign(\n  // Spread the raw ops onto a fresh object so the added `tables`/typed\n  // `transaction` members live alongside them. Each op still forwards through\n  // the request-scoped runtime Proxy.\n  {\n    query: (sql: string, params?: unknown[]) => rawDatabase.query(sql, params),\n    insert: (table: string, data: Record<string, unknown>) => rawDatabase.insert(table, data),\n    update: (table: string, id: string, data: Record<string, unknown>) =>\n      rawDatabase.update(table, id, data),\n    delete: (table: string, id: string) => rawDatabase.delete(table, id),\n    findById: (table: string, id: string) => rawDatabase.findById(table, id),\n    findMany: (table: string, query?: Record<string, unknown>) =>\n      rawDatabase.findMany(table, query),\n  } satisfies Omit<DBClient, \"transaction\">,\n  {\n    tables: makeTablesAccessor(() => rawDatabase),\n    transaction<T>(fn: (tx: EnvTypedTx) => Promise<T>): Promise<T> {\n      return rawDatabase.transaction((rawTx) =>\n        fn({ tables: makeTablesAccessor(() => rawTx) }),\n      );\n    },\n  },\n);\n\n/** Firestore-like document client (PalDocs). */\nexport const Documents: PalbaseDocsClient = makeServiceProxy(\"Documents\");\n\n/** Object storage client (buckets, signed URLs). */\nexport const Storage: PalbaseStorageClient = makeServiceProxy(\"Storage\");\n\n/** JSON-typed cache (get/set/incr/getOrSet). */\nexport const Cache: CacheClient = makeServiceProxy(\"Cache\");\n\n/** Background job queue. */\nexport const Queue: QueueClient = makeServiceProxy(\"Queue\");\n\n/** Structured logger. */\nexport const Log: Logger = makeServiceProxy(\"Log\");\n\n/** Push / email / SMS / in-app notifications. */\nexport const Notifications: PalbaseNotificationsClient = makeServiceProxy(\"Notifications\");\n\n/** Feature flags. */\nexport const Flags: PalbaseFlagsClient = makeServiceProxy(\"Flags\");\n"],"mappings":";AAyCA,SAAS,yBAAyB;AA0C3B,IAAM,eAAe,IAAI,kBAAgD;AAKhF,IAAI,UAAkC;AAO/B,SAAS,aAAa,UAAiC;AAC5D,YAAU;AACZ;AAMO,SAAS,iBAAoB,UAA2B,IAAgB;AAC7E,SAAO,aAAa,IAAI,EAAE,SAAS,SAAS,GAAG,EAAE;AACnD;AAOO,SAAS,eAAgC;AAC9C,QAAM,SAAS,aAAa,SAAS;AACrC,MAAI,OAAQ,QAAO,OAAO;AAC1B,MAAI,YAAY,MAAM;AACpB,UAAM,IAAI;AAAA,MACR;AAAA,IAGF;AAAA,EACF;AACA,SAAO;AACT;AAWA,SAAS,iBAAkD,KAA4B;AACrF,QAAM,UAA4C;AAAA,IAChD,IAAI,SAAS,MAAM,UAAU;AAC3B,YAAM,SAAS,aAAa,EAAE,GAAG;AACjC,YAAM,QAAQ,QAAQ,IAAI,QAAkB,MAAM,QAAQ;AAG1D,aAAO,OAAO,UAAU,aAAa,MAAM,KAAK,MAAM,IAAI;AAAA,IAC5D;AAAA,EACF;AAGA,SAAO,IAAI,MAAM,CAAC,GAAyB,OAAO;AACpD;AAcA,SAAS,mBAAmB,KAAgC;AAC1D,QAAM,cAAc,IAAI;AAAA,IACtB,CAAC;AAAA,IACD;AAAA,MACE,IAAI,IAAI,MAAuB;AAC7B,YAAI,OAAO,SAAS,SAAU,QAAO;AACrC,cAAM,OAAO;AACb,eAAO;AAAA,UACL,QAAQ,CAAC,SAAkC,IAAI,EAAE,OAAO,MAAM,IAAI;AAAA,UAClE,QAAQ,CAAC,IAAY,SAAkC,IAAI,EAAE,OAAO,MAAM,IAAI,IAAI;AAAA,UAClF,QAAQ,CAAC,OAAe,IAAI,EAAE,OAAO,MAAM,EAAE;AAAA,UAC7C,UAAU,CAAC,OAAe,IAAI,EAAE,SAAS,MAAM,EAAE;AAAA,UACjD,UAAU,CAAC,UAAoC,IAAI,EAAE,SAAS,MAAM,KAAK;AAAA,QAC3E;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACA,SAAO;AACT;AAGA,IAAM,cAAwB,iBAAiB,UAAU;AAiBlD,IAAM,WAA6B,OAAO;AAAA;AAAA;AAAA;AAAA,EAI/C;AAAA,IACE,OAAO,CAAC,KAAa,WAAuB,YAAY,MAAM,KAAK,MAAM;AAAA,IACzE,QAAQ,CAAC,OAAe,SAAkC,YAAY,OAAO,OAAO,IAAI;AAAA,IACxF,QAAQ,CAAC,OAAe,IAAY,SAClC,YAAY,OAAO,OAAO,IAAI,IAAI;AAAA,IACpC,QAAQ,CAAC,OAAe,OAAe,YAAY,OAAO,OAAO,EAAE;AAAA,IACnE,UAAU,CAAC,OAAe,OAAe,YAAY,SAAS,OAAO,EAAE;AAAA,IACvE,UAAU,CAAC,OAAe,UACxB,YAAY,SAAS,OAAO,KAAK;AAAA,EACrC;AAAA,EACA;AAAA,IACE,QAAQ,mBAAmB,MAAM,WAAW;AAAA,IAC5C,YAAe,IAAgD;AAC7D,aAAO,YAAY;AAAA,QAAY,CAAC,UAC9B,GAAG,EAAE,QAAQ,mBAAmB,MAAM,KAAK,EAAE,CAAC;AAAA,MAChD;AAAA,IACF;AAAA,EACF;AACF;AAGO,IAAM,YAA+B,iBAAiB,WAAW;AAGjE,IAAM,UAAgC,iBAAiB,SAAS;AAGhE,IAAM,QAAqB,iBAAiB,OAAO;AAGnD,IAAM,QAAqB,iBAAiB,OAAO;AAGnD,IAAM,MAAc,iBAAiB,KAAK;AAG1C,IAAM,gBAA4C,iBAAiB,eAAe;AAGlF,IAAM,QAA4B,iBAAiB,OAAO;","names":[]}