@palbase/backend 24.3.0 → 25.0.1

package/dist/{index-BLAbr9ZH.d.cts → index-DmVyY6N7.d.cts}

@@ -1,4 +1,4 @@
-import { Tables, TableTypes } from './db/env.cjs';
+import { Tables, TableTypes, Schemas } from './db/env.cjs';
 import { D as DBClient, b8 as TxPlanHandle, bh as TxTable, M as Materialized } from './endpoint-BSGw1pTu.cjs';
 
 /** On delete action for foreign key references. */
@@ -26,6 +26,31 @@ interface ColumnDef {
         table: string;
         column: string;
     };
+    /** Pending FK target, resolved by `defineSchema` once every binding exists. */
+    referencesThunk?: () => ColumnBuilder;
+    /** FK onto THIS table — no thunk needed, the target is the declaring table. */
+    selfRefColumn?: string;
+    /** This column OWNS the row: erasure, RLS and the `owner` relation read it. */
+    owns?: true;
+    /** Explicit name for the FORWARD relation (child → parent), when the one
+     * derived from the column would be ambiguous or unclear. */
+    refAs?: string;
+    /**
+     * Explicit name for the REVERSE relation (parent → children).
+     *
+     * Separate from {@link refAs} because the two directions are different facts:
+     * the forward name describes the parent this row points at (`author`), the
+     * reverse one describes the rows hanging off the parent (`posts`). One option
+     * naming both made an ordinary schema undeclarable — `posts.author_id` and
+     * `comments.author_id` both named `{ as: "author" }` collided on `users`, and
+     * the refusal asked for the `{ as }` they had both already written.
+     */
+    reverseAs?: string;
+    /** The table this column belongs to; set by `defineTable`. */
+    ownerTable?: {
+        name: string;
+        columns: Record<string, ColumnBuilder>;
+    };
     /**
      * The name this column used to have. A diff cannot tell a rename from a drop and
      * an add — both leave one name gone and another present — so the intent has to be
@@ -171,47 +196,44 @@ declare class ColumnBuilder<K extends ColumnType = ColumnType, N extends boolean
      * safety gate in silence.
      */
     ignored(): ColumnBuilder<K, N, D, E, P, T>;
-    references(table: string, column: string): ColumnBuilder<K, N, D, E, P, T>;
     /**
-     * Add a real DB-level foreign key to the built-in auth users
-     * (`REFERENCES auth.users(id)`), so a column like `user_id` gets true
-     * database cascade/integrity instead of app-layer-only. Sugar for
-     * `.references("auth.users", "id")`.
+     * Foreign key onto another table's column.
+     *
+     * The target is a THUNK, not a direct reference. In a cycle (`x → y`, `y → x`)
+     * the second table does not exist yet when the first is built; a direct
+     * reference makes TypeScript chase its own tail (TS7022 — measured, and making
+     * the return type independent of the target does NOT help). The thunk is
+     * invoked in `defineSchema`, where every binding exists and every table
+     * already knows its name.
      *
-     * `auth.users` lives in the SAME tenant database (palauth-owned), so this is
-     * a genuine cross-schema integrity constraint scoped to THIS tenant's users.
-     * The referenced `auth.users.id` is `text` (palauth ids are `usr_<uuid>`), so
-     * the referencing column must be `text()` too.
+     * In a cycle, ONE side needs an explicit return type:
+     * `references((): AnyColumn => y.id)`. One side is enough — measured.
+     * For a self-reference use `selfReferences(column)`: no thunk, no annotation.
      *
-     * ON DELETE is REQUIRED here and may only be `cascade` or `set null`: an
-     * account-erasure request must never be blocked by a lingering FK, so
-     * `restrict` / `no action` are not accepted (they don't type-check). Example:
-     * `text().notNull().referencesAuthUser("cascade")`, or
-     * `text().nullable().referencesAuthUser("set null")`. The server
-     * (validateAuthUserFK) enforces this — and the remaining rules the type can't
-     * express (referencing column is text, `set null` needs a nullable column) —
-     * as the real boundary; this signature is the compile-time DX mirror.
+     * `as` names the FORWARD relation (`author_id` → `author` by default);
+     * `reverseAs` names the REVERSE one on the parent, whose default is this
+     * table's own name (`users.posts`). Two foreign keys from one table onto one
+     * parent therefore need a `reverseAs` on at least one of them — the reverse
+     * names would otherwise both be this table's name.
      */
-    referencesAuthUser(onDelete: AuthUserOnDelete): ColumnBuilder<K, N, D, E, P, T>;
+    references(target: () => AnyColumn, opts?: {
+        as?: string;
+        reverseAs?: string;
+        onDelete?: OnDeleteAction;
+    }): ColumnBuilder<K, N, D, E, P, T>;
     /**
-     * Add a real DB-level foreign key to the canonical, server-minted installation
-     * anchor (`REFERENCES auth.installations(id)`) — the app-scoped verified-device
-     * root (`ins_...`). Sugar for `.references("auth.installations", "id")`.
+     * Foreign key onto THIS table (`parent_id → id`) — category trees, comment
+     * replies, org charts.
      *
-     * An installation is an APP INSTALL, not a user: this FK is NOT user ownership.
-     * A user-owned row STILL needs its own `.referencesAuthUser(...)` FK so account
-     * erasure removes it — an installation reference alone does not tie a row to a
-     * user's deletion. Use this only for install-scoped state (device prefs, push
-     * routing, …), alongside a separate auth-user FK where the row is user-owned.
-     *
-     * `auth.installations` lives in the SAME tenant DB (palauth-owned); its `id` is
-     * `text` (`ins_<uuid>`), so the referencing column must be `text()` too. ON
-     * DELETE is REQUIRED and may only be `cascade` or `set null` (same allowed set
-     * as an auth-user FK): an installation revoke / orphan cleanup must never be
-     * blocked by a lingering FK. The server (validateAuthAnchorFK) is the real
-     * boundary; this signature is the compile-time DX mirror.
+     * No thunk and no type annotation: the target table is the one being declared,
+     * so there is nothing to defer and nothing for TypeScript to chase in a circle.
+     * Drizzle forces an explicit `(): AnyPgColumn =>` here because its reference
+     * always goes through a callback; measured, we do not need one.
      */
-    referencesInstallation(onDelete: AuthUserOnDelete): ColumnBuilder<K, N, D, E, P, T>;
+    selfReferences(column: string, opts?: {
+        as?: string;
+        onDelete?: OnDeleteAction;
+    }): ColumnBuilder<K, N, D, E, P, T>;
     /** Set the ON DELETE action for a foreign key reference. */
     onDelete(action: OnDeleteAction): ColumnBuilder<K, N, D, E, P, T>;
     /** Add a single-column UNIQUE constraint. */
@@ -310,6 +332,54 @@ declare function enumType<const V extends readonly string[]>(name: string, value
  * 2000 = pgvector'ün HNSW-indekslenebilir tavanı; auto-index bu beyanla bağlı
  * (spec FR-001, D-3). */
 declare function vector(dimensions: number): ColumnBuilder<'vector', false, false, unknown, number[]>;
+/**
+ * Any column, whatever its type parameters.
+ *
+ * Exported so a cycle can be broken from ONE side:
+ * `references((): AnyColumn => y.id)`.
+ */
+type AnyColumn = ColumnBuilder;
+/**
+ * The column that OWNS this row: a `text` FK onto `auth.users(id)`, NOT NULL,
+ * ON DELETE CASCADE.
+ *
+ * Ownership drives account erasure, so cascade is the only correct action and
+ * takes no argument. The referencing column must be `text` (palauth ids are
+ * `usr_<uuid>`) and NOT NULL — both are implied here rather than left to the
+ * caller, so three rules the type could not express before become UNWRITABLE.
+ *
+ * At most ONE per table. The old shape let several columns reference
+ * `auth.users` and picked the FIRST IN DECLARATION ORDER as the owner — moving a
+ * `created_by` above a `user_id` silently changed which rows an account deletion
+ * took with it. A second one is now rejected at push.
+ *
+ * For a column that merely POINTS at a user without owning the row
+ * (`created_by`, `edited_by`), use `userRef({ onDelete })`.
+ */
+declare function ownedByUser(): ColumnBuilder<'text', false, false, never>;
+/**
+ * A plain FK onto `auth.users(id)` that does NOT own the row.
+ *
+ * `created_by` / `edited_by`: deleting that user must not delete the row. ON
+ * DELETE is required and limited to `cascade | set null` so an erasure request
+ * is never blocked by a lingering FK; `set null` needs a nullable column.
+ */
+declare function userRef(opts: {
+    onDelete: AuthUserOnDelete;
+    as?: string;
+}): ColumnBuilder<'text', boolean, false, never>;
+/**
+ * A plain FK onto `auth.installations(id)` — the app-scoped verified-device
+ * anchor.
+ *
+ * An installation is an APP INSTALL, not a user: this is NOT ownership. A
+ * user-owned row still needs its own `ownedByUser()` so account erasure removes
+ * it; an installation reference alone does not tie a row to a user's deletion.
+ */
+declare function installationRef(opts: {
+    onDelete: AuthUserOnDelete;
+    as?: string;
+}): ColumnBuilder<'text', boolean, false, never>;
 
 /**
  * policy.ts — the RLS policy authoring DSL.
@@ -438,7 +508,8 @@ declare const EXTENSION_DEPENDENCIES: Partial<Record<PalbaseExtension, PalbaseEx
 declare function isPalbaseExtension(name: string): name is PalbaseExtension;
 
 /**
- * A named raw-SQL DDL object declared in db/schema.ts for anything the typed DSL
+ * A named raw-SQL DDL object declared in a schema file (`db/public.ts`,
+ * `db/billing.ts`, …) for anything the typed DSL
  * cannot express (EXCLUDE, CHECK, partial/expression indexes, triggers, views).
  * The deploy emits `up` verbatim on the privileged DDL connection — same trust
  * posture as policy().using(). Tracked by NAME (not by diffing the body), so a
@@ -482,7 +553,7 @@ declare const openai: {
 
 /**
  * A map of column builders keyed by column name — the value you write under
- * the `columns` key of `defineSchema({ tables: { <name>: { columns } } })`.
+ * the `columns` key of `defineTable("<name>", { columns })`.
  *
  * The default `Record<string, ColumnBuilder>` keeps bare references compiling
  * without a type argument.
@@ -655,55 +726,50 @@ interface TableDef<C extends ColumnMap = ColumnMap> {
  * `TableDef<{ id: ColumnBuilder<'uuid', false, true, never>; ... }>`.
  */
 interface SchemaDef<T extends Record<string, TableDef> = Record<string, TableDef>> {
+    /** The schema's own name — `public`, `billing`, … Declared, never derived. */
+    name: string;
+    /** Reachable over HTTP? False unless the author opts in. */
+    exposed: boolean;
     tables: T;
     /** Postgres extensions to install on deploy. Normalized to `[]` when absent. */
     extensions: PalbaseExtension[];
 }
-/** The author-facing input to `defineSchema` — a `tables` map whose keys are
- * the table names and whose values are `{ columns, rls?, policies? }`, plus an
- * optional `extensions` allowlist. */
-interface SchemaInput<T extends Record<string, TableInput> = Record<string, TableInput>> {
-    tables: T;
-    /**
-     * Postgres extensions to enable for this project, e.g. `["vector"]`.
-     * Config-as-code: installed by the deploy (CREATE EXTENSION … SCHEMA
-     * extensions) with the privileged deploy connection. The type is an
-     * allowlist union, so unsupported names fail typecheck.
-     */
-    extensions?: PalbaseExtension[];
-}
 /** Map the author's `{ tables: { <name>: { columns } } }` input to the
  * `{ tables: { <name>: TableDef<columns> } }` runtime/type shape, threading the
  * per-table column map `T[K]["columns"]` so column-level inference survives. */
-type TablesFromInput<T extends Record<string, TableInput>> = {
-    [K in keyof T]: TableDef<T[K]["columns"]>;
+type TablesByName<T extends readonly TableHandle[]> = {
+    [K in T[number] as K[typeof TABLE_META]["name"]]: K[typeof TABLE_META];
 };
 /**
- * Define a schema. The table NAME comes from the object key. Each table value
- * is `{ columns, rls?, policies? }`:
+ * How a schema file reads. One file per schema — `db/public.ts`, `db/billing.ts`
+ * — and the schema says its own name:
  *
- *   export default defineSchema({
- *     tables: {
- *       todos: {
- *         columns: {
- *           id:    uuid().primaryKey().defaultRandom(),
- *           owner: text().notNull(),
- *           title: text().notNull(),
- *         },
- *         rls: true,
- *         policies: [
- *           policy("owner_all").for("all").to("authenticated")
- *             .using("owner = (select auth.uid())")
- *             .withCheck("owner = (select auth.uid())"),
- *         ],
- *       },
+ *   const todos = defineTable("todos", {
+ *     columns: {
+ *       id:    uuid().primaryKey().defaultRandom(),
+ *       owner: text().notNull(),
+ *       title: text().notNull(),
  *     },
+ *     rls: true,
+ *     policies: [
+ *       policy("owner_all").for("all").to("authenticated")
+ *         .using("owner = (select auth.uid())")
+ *         .withCheck("owner = (select auth.uid())"),
+ *     ],
  *   });
  *
- * The returned value is
- * `{ tables: { todos: { name, columns, rls, policies } } }` — the exact shape
- * the runtime schema extractor parses. Per-column phantom types are preserved
- * so `Database.tables.todos.insert({...})` stays typed.
+ *   export default defineSchema("public", { tables: [todos] });
+ *
+ * The dictionary form `defineSchema({ tables: { todos: {…} } })` is RETIRED and
+ * refused by name: a table whose name comes from a key does not know what it is
+ * called while it is being built, so it cannot resolve `references(() =>
+ * other.id)`, and a schema that does not say its own name cannot tell one
+ * `invoices` from another schema's `invoices`.
+ *
+ * The returned value is `{ name, tables: { todos: { name, columns, rls,
+ * policies } }, extensions, exposed }` — the exact shape the runtime schema
+ * extractor parses. Per-column phantom types are preserved so
+ * `Database.tables.todos.insert({...})` stays typed.
  *
  * RLS normalization: `rls` defaults to **`true`**, `policies` to `[]`. A table
  * that declares neither is therefore deny-all — nothing reads it until a policy
@@ -713,7 +779,46 @@ type TablesFromInput<T extends Record<string, TableInput>> = {
  * `rls` is forced on (ENABLE + FORCE) regardless of the declared flag — a table
  * with policies must have RLS enabled or the policies would be inert.
  */
-declare function defineSchema<T extends Record<string, TableInput>>(input: SchemaInput<T>): SchemaDef<TablesFromInput<T>>;
+/**
+ * Where a table's metadata lives.
+ *
+ * The table VALUE is its columns, so `lists.id` is the column — which means a
+ * column called `name` would overwrite the table's own name if metadata sat in
+ * a plain field. Measured, not imagined: the existing `users` / `rooms` tests
+ * (both declare a `name` column) produced an `[object Object]` table key.
+ * `columns`, `rls`, `search`, `memory`, `unique` and `indexes` are all plausible
+ * column names too. A column cannot collide with a symbol.
+ */
+declare const TABLE_META: unique symbol;
+/** A value produced by `defineTable`: the columns, plus metadata behind the symbol. */
+type TableHandle<C extends ColumnMap = ColumnMap, N extends string = string> = C & {
+    readonly [TABLE_META]: TableDef<C> & {
+        name: N;
+    };
+};
+/**
+ * Declare one table as a standalone value that KNOWS ITS OWN NAME.
+ *
+ * The name lives here, not in a dictionary key. A table whose name comes from a
+ * key cannot resolve `references(() => other.id)` when it is built — it does not
+ * know what to call itself — which forces a two-phase resolution with an
+ * empty-name intermediate state. One name source, no empty identity.
+ *
+ * The returned object spreads its own columns, so a sibling can point at it:
+ * `references(() => lists.id)`.
+ */
+declare function defineTable<const N extends string, C extends ColumnMap>(name: N, input: TableInput<C>): TableHandle<C, N>;
+/**
+ * Collect declared tables into one schema.
+ *
+ * Takes an ARRAY, not a dictionary: the tables already carry their names, and a
+ * second name source is a second thing that can disagree.
+ */
+declare function defineSchema<const T extends readonly TableHandle[]>(name: string, input: {
+    tables: T;
+    exposed?: boolean;
+    extensions?: PalbaseExtension[];
+}): SchemaDef<TablesByName<T>>;
 
 /**
  * typed-db.ts — Task 2: TypedDB schema-derived insert/row shapes.
@@ -978,6 +1083,26 @@ type EnvTypedTable<T extends TableTypes> = EnvTypedTableBase<T> & (T extends {
 type EnvTables = {
     [K in keyof Tables]: EnvTypedTable<Tables[K]>;
 };
+/**
+ * The project's NON-public schemas, keyed by schema name, each exposing its own
+ * `tables` map — the shape `Database.schema("billing")` returns.
+ *
+ * The intermediate `tables` is there for the reason {@link EnvTables} sits under
+ * `.tables`: a schema's table names must not share a namespace with anything the
+ * accessor itself might grow.
+ *
+ * Empty by default. The generated `palbase-env.d.ts` augments `Schemas` with one
+ * member per declared schema other than `public`, so a project that declares
+ * none has `keyof Schemas = never` and every `schema(...)` call is a compile
+ * error rather than a runtime surprise.
+ */
+type EnvSchemas = {
+    [S in keyof Schemas]: {
+        tables: {
+            [T in keyof Schemas[S]]: EnvTypedTable<Extract<Schemas[S][T], TableTypes>>;
+        };
+    };
+};
 /** The project's tables as PLAN operations, keyed by the env `Tables`
  * interface. The transaction twin of {@link EnvTables}. */
 type TxTables = {
@@ -999,6 +1124,10 @@ type TxPlan = TxPlanHandle<TxTables>;
  */
 interface EnvServiceDatabase extends Omit<DBClient, "txPlan" | "asService"> {
     tables: EnvTables;
+    /** See {@link EnvTypedDatabase.schema}. The bypass sibling reaches every
+     * schema the default surface does — a `billing` table is no less reachable
+     * because the caller asked to run as the service role. */
+    schema<S extends keyof Schemas>(name: S): EnvSchemas[S];
     transaction<T>(fn: (tx: TxPlan) => T extends Promise<unknown> ? never : T): Promise<Materialized<T>>;
 }
 /**
@@ -1013,6 +1142,26 @@ interface EnvServiceDatabase extends Omit<DBClient, "txPlan" | "asService"> {
  */
 interface EnvTypedDatabase extends Omit<DBClient, "txPlan" | "asService"> {
     tables: EnvTables;
+    /**
+     * The tables of a schema other than `public`.
+     *
+     * `Database.tables.*` is the PUBLIC schema and only the public schema. Two
+     * schemas may declare the same table name — `public.invoices` and
+     * `billing.invoices` are different tables — so one flat namespace would make
+     * `Database.tables.invoices` resolve by declaration order. It does not: the
+     * bare name is always public's, and everything else is asked for by schema.
+     *
+     * The name is `keyof Schemas`, so a schema the project never declared is a
+     * compile error. On the wire the table travels schema-qualified
+     * (`billing.invoices`); `public` stays bare.
+     *
+     * Declaring a schema does not publish it — reachability over HTTP is the
+     * schema's own `exposed` flag, checked by the broker.
+     *
+     * @example
+     * const inv = await Database.schema("billing").tables.invoices.findById(id);
+     */
+    schema<S extends keyof Schemas>(name: S): EnvSchemas[S];
     /**
      * Run a transaction. The callback DESCRIBES the operations; the whole
      * description travels in one request and the broker runs it inside a single
@@ -1070,4 +1219,4 @@ interface EnvTypedDatabase extends Omit<DBClient, "txPlan" | "asService"> {
     asService(): EnvServiceDatabase;
 }
 
-export { isPalbaseExtension as A, jsonb as B, ColumnBuilder as C, makeTypedDB as D, type EnvTypedDatabase as E, numeric as F, openai as G, policy as H, type InsertShape as I, raw as J, text as K, timestamp as L, uuid as M, vector as N, type OnDeleteAction as O, PALBASE_EXTENSIONS as P, type RawConstraintDef as R, type SchemaDef as S, type TableDef as T, type ColumnDef as a, type ColumnMap as b, type ColumnType as c, EXTENSION_DEPENDENCIES as d, type EmbeddingModelRef as e, type EnvServiceDatabase as f, type EnvTables as g, type EnvTypedTable as h, type PalbaseExtension as i, PolicyBuilder as j, type PolicyCommand as k, type PolicyDef as l, type PolicyMode as m, type RowShape as n, type SchemaInput as o, type TableInput as p, type TxPlan as q, type TxTables as r, type TypedDB as s, type TypedTable as t, type TypedTx as u, bigint as v, boolean as w, defineSchema as x, enumType as y, integer as z };
+export { type AnyColumn as A, defineTable as B, ColumnBuilder as C, enumType as D, type EnvTypedDatabase as E, installationRef as F, integer as G, isPalbaseExtension as H, type InsertShape as I, jsonb as J, makeTypedDB as K, numeric as L, openai as M, ownedByUser as N, type OnDeleteAction as O, PALBASE_EXTENSIONS as P, policy as Q, type RawConstraintDef as R, type SchemaDef as S, TABLE_META as T, raw as U, text as V, timestamp as W, userRef as X, uuid as Y, vector as Z, type ColumnDef as a, type ColumnMap as b, type ColumnType as c, EXTENSION_DEPENDENCIES as d, type EmbeddingModelRef as e, type EnvSchemas as f, type EnvServiceDatabase as g, type EnvTables as h, type EnvTypedTable as i, type PalbaseExtension as j, PolicyBuilder as k, type PolicyCommand as l, type PolicyDef as m, type PolicyMode as n, type RowShape as o, type TableDef as p, type TableHandle as q, type TableInput as r, type TxPlan as s, type TxTables as t, type TypedDB as u, type TypedTable as v, type TypedTx as w, bigint as x, boolean as y, defineSchema as z };

package/dist/{index-C-ALG22n.d.cts → index-VsjBQ4Kw.d.cts}

@@ -1,7 +1,7 @@
 import { Buckets, BucketTypes } from './stack.cjs';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { C as CacheClient, P as PalbaseDocsClient, a as PalbaseFlagsClient, L as Logger, b as PalbaseNotificationsClient, c as PalbaseRealtimeClient, D as DBClient, S as SecretsService, d as PalbaseStorageClient, e as PalbaseBucketClient, f as DBOps, T as TxPlanBody, g as TxPlanResponse, A as AuthSpec } from './endpoint-BSGw1pTu.cjs';
-import { E as EnvTypedDatabase } from './index-BLAbr9ZH.cjs';
+import { E as EnvTypedDatabase } from './index-DmVyY6N7.cjs';
 import { R as RouteMeta } from './registry-CgJvDYUW.cjs';
 
 /**
@@ -673,6 +673,9 @@ declare function withTables<T extends ReturnType<typeof createOps>>(ops: T, sche
     }>;
 }): T & {
     tables: Record<string, unknown>;
+    schema: (name: string) => {
+        tables: Record<string, unknown>;
+    };
 };
 /** The two transactions a request may hold, and the single `Database` over them. */
 interface RequestDatabase {
@@ -1007,7 +1010,7 @@ interface CreateAppOptions {
     /** `@Controller` classes. A class that collected zero routes is fatal. */
     controllers: readonly unknown[];
     /** The project's `defineSchema()` result, for the typed `.tables` surface. */
-    schema?: unknown;
+    schemas?: readonly unknown[];
     /** The SQL driver. Omitted ⇒ built from `Bun.sql` when running under Bun. */
     sql?: SqlDriver;
     /** Module clients. Omitted ⇒ each corresponding singleton throws when used. */