@palbase/backend 24.3.0 → 25.0.0

package/dist/{index-BLAbr9ZH.d.cts → index-CwaWRhyc.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,19 @@ 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 relation name, when the derived one would be ambiguous. */
+    refAs?: 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 +184,37 @@ 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.
      *
-     * `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.
+     * 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.
      *
-     * 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.
+     * 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.
      */
-    referencesAuthUser(onDelete: AuthUserOnDelete): ColumnBuilder<K, N, D, E, P, T>;
+    references(target: () => AnyColumn, opts?: {
+        as?: 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")`.
-     *
-     * 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.
+     * Foreign key onto THIS table (`parent_id → id`) — category trees, comment
+     * replies, org charts.
      *
-     * `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 +313,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.
@@ -482,7 +533,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,6 +706,10 @@ 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[];
@@ -675,35 +730,39 @@ interface SchemaInput<T extends Record<string, TableInput> = Record<string, Tabl
 /** 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 +772,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 +1076,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 +1117,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 +1135,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 +1212,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, defineSchema as B, ColumnBuilder as C, defineTable as D, type EnvTypedDatabase as E, enumType as F, installationRef as G, integer as H, type InsertShape as I, isPalbaseExtension as J, jsonb as K, makeTypedDB as L, numeric as M, openai as N, type OnDeleteAction as O, PALBASE_EXTENSIONS as P, ownedByUser as Q, type RawConstraintDef as R, type SchemaDef as S, TABLE_META as T, policy as U, raw as V, text as W, timestamp as X, userRef as Y, uuid as Z, vector as _, 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 SchemaInput as p, type TableDef as q, type TableHandle as r, type TableInput as s, type TxPlan as t, type TxTables as u, type TypedDB as v, type TypedTable as w, type TypedTx as x, bigint as y, boolean as z };