@palbase/backend 24.3.0 → 25.0.1

package/dist/db/env.d.ts

@@ -6,7 +6,8 @@ export { BucketTypes, Buckets } from '../stack.js';
  *
  * `Database.tables.<name>` is typed against the `Tables` interface declared
  * here. By default `Tables` is EMPTY; the generated `palbase-env.d.ts`
- * (emitted from `db/schema.ts` by {@link makeEnvDts}) augments it with one
+ * (emitted from the project's `db/*.ts` schema files by {@link makeEnvDts})
+ * augments it with one
  * member per table:
  *
  *   // palbase-env.d.ts (generated — do not edit)
@@ -27,28 +28,37 @@ export { BucketTypes, Buckets } from '../stack.js';
  *   type Todo = Tables["todos"]["row"];
  */
 /**
- * One typed table's shapes and its position in the user-rooted graph:
+ * One typed table's shapes and its relations:
  *
  * - `row` — the full row, every column present.
  * - `insert` — the write payload, required vs optional columns.
- * - `owner` — the column that foreign-keys `auth.users` (declared in
- *   `db/schema.ts` with `.referencesAuthUser(...)`), or `null` when the table
- *   is not user-rooted. This is what makes a seed/fixture DSL able to OMIT the
- *   owner column from the author-facing type: the apply step fills it.
- * - `children` — tables that foreign-key THIS table, mapped to the FK column on
- *   the child (`{ todos: "list_id" }`). Lets a nested seed attach children
- *   without the author ever writing the FK. Self-FKs and cycle back-edges are
- *   omitted by the generator so recursive types over `children` terminate.
+ * - `relations` — every foreign key this table takes part in, named, in both
+ *   directions. `{ list: { to: "lists", kind: "one", via: "list_id" } }` on the
+ *   child; `{ todos: { to: "todos", kind: "many", via: "list_id" } }` on the
+ *   parent. Ownership declared with `ownedByUser()` appears as `owner`.
  *
  * The generated `palbase-env.d.ts` fills `row`/`insert` with flat object types —
  * no `ColumnBuilder` phantom types ever appear in the generated output — and
- * `owner`/`children` with string literals.
+ * `relations` with string literals.
  */
 interface TableTypes {
     row: Record<string, unknown>;
     insert: Record<string, unknown>;
-    owner: string | null;
-    children: Record<string, string>;
+    /**
+     * The table's relations, derived from its declared foreign keys.
+     *
+     * Replaces the old `owner` / `children` pair, which nothing ever read: `owner`
+     * was whichever column happened to reference `auth.users` FIRST in declaration
+     * order, and `children` silently kept only ONE foreign key per parent.
+     *
+     * `to` is the target's table key — bare for `public`, schema-qualified
+     * otherwise, the same convention `RefJSON.table` uses.
+     */
+    relations: Record<string, {
+        to: string;
+        kind: "one" | "many";
+        via: string;
+    }>;
 }
 /**
  * The project's tables, keyed by table name. EMPTY by default; the generated
@@ -57,5 +67,12 @@ interface TableTypes {
  */
 interface Tables {
 }
+/**
+ * Tables in schemas other than `public`, reached with
+ * `Database.schema("<name>").tables.*`. Declaring a schema does not put it on
+ * the internet — see `exposed`.
+ */
+interface Schemas {
+}
 
-export type { TableTypes, Tables };
+export type { Schemas, TableTypes, Tables };

package/dist/db/index.cjs

@@ -23,29 +23,39 @@ __export(db_exports, {
   EXTENSION_DEPENDENCIES: () => EXTENSION_DEPENDENCIES,
   PALBASE_EXTENSIONS: () => PALBASE_EXTENSIONS,
   PolicyBuilder: () => PolicyBuilder,
+  TABLE_META: () => TABLE_META,
   TxPlanError: () => TxPlanError,
   TxRefError: () => TxRefError,
   bigint: () => bigint,
   boolean: () => boolean,
   dec: () => dec,
   defineSchema: () => defineSchema,
+  defineTable: () => defineTable,
   enumType: () => enumType,
   inc: () => inc,
+  installationRef: () => installationRef,
   integer: () => integer,
   isPalbaseExtension: () => isPalbaseExtension,
   jsonb: () => jsonb,
   makeTypedDB: () => makeTypedDB,
   now: () => now,
   openai: () => openai,
+  ownedByUser: () => ownedByUser,
   policy: () => policy,
   raw: () => raw,
   text: () => text,
   timestamp: () => timestamp,
+  userRef: () => userRef,
   uuid: () => uuid,
   vector: () => vector
 });
 module.exports = __toCommonJS(db_exports);
 
+// src/db/schema-json.ts
+function qualifiedTableKey(schemaName, tableName) {
+  return schemaName === "public" ? tableName : `${schemaName}.${tableName}`;
+}
+
 // src/db/policy.ts
 function quote(name) {
   return `"${name.replace(/"/g, '""')}"`;
@@ -140,102 +150,186 @@ function policy(name) {
 function toPolicyDef(p) {
   return p instanceof PolicyBuilder ? p._def : p;
 }
-function defineSchema(input) {
-  const tables = {};
-  for (const name of Object.keys(input.tables)) {
-    const table = input.tables[name];
-    if (table === void 0) continue;
-    const policies = (table.policies ?? []).map(toPolicyDef);
-    const rls = policies.length > 0 || table.rls !== false;
-    const tableDef = {
-      name,
-      columns: table.columns,
-      rls,
-      policies
-    };
-    if (table.primaryKey !== void 0) tableDef.primaryKey = table.primaryKey;
-    if (table.unique !== void 0) tableDef.unique = table.unique;
-    if (table.raw !== void 0 && table.raw.length > 0) tableDef.raw = table.raw.slice();
-    if (table.checks !== void 0 && table.checks.length > 0) tableDef.checks = table.checks.slice();
-    if (table.indexes !== void 0 && table.indexes.length > 0) tableDef.indexes = table.indexes.slice();
-    if (table.search !== void 0) {
-      const s = table.search;
-      if (s.from !== void 0) {
-        if (s.vector !== void 0) {
-          throw new Error(
-            `table ${String(name)}: search beyan\u0131nda tek bi\xE7im kullan\u0131n \u2014 'from' (yeni) ile 'vector' (eski) birlikte olamaz`
-          );
-        }
-        if (s.from.length === 0) {
-          throw new Error(`table ${String(name)}: search.from bo\u015F olamaz`);
-        }
-        if (s.model === void 0) {
-          throw new Error(
-            `table ${String(name)}: search.from model'siz anlams\u0131z \u2014 auto-embed i\xE7in model verin (BYO i\xE7in eski 'vector' bi\xE7imini kullan\u0131n)`
-          );
-        }
-        if (Array.isArray(s.text) && s.text.length === 0) {
-          throw new Error(`table ${String(name)}: search.text bo\u015F dizi olamaz \u2014 FTS istemiyorsan text: false yaz\u0131n`);
+var TABLE_META = /* @__PURE__ */ Symbol.for("palbase.table.meta");
+function defineTable(name, input) {
+  if (name.trim() === "") {
+    throw new Error("defineTable(name, \u2026): name must not be empty");
+  }
+  const policies = (input.policies ?? []).map(toPolicyDef);
+  const rls = policies.length > 0 || input.rls !== false;
+  const owned = {};
+  for (const [colName, b] of Object.entries(input.columns)) {
+    const builder = b;
+    const clone = Object.create(Object.getPrototypeOf(builder));
+    Object.defineProperty(clone, "_def", { value: { ...builder._def }, enumerable: true, writable: true });
+    owned[colName] = clone;
+  }
+  const def = {
+    name,
+    columns: owned,
+    rls,
+    policies
+  };
+  if (input.primaryKey !== void 0) def.primaryKey = input.primaryKey;
+  if (input.unique !== void 0) def.unique = input.unique;
+  if (input.raw !== void 0 && input.raw.length > 0) def.raw = input.raw.slice();
+  if (input.checks !== void 0 && input.checks.length > 0) def.checks = input.checks.slice();
+  if (input.indexes !== void 0 && input.indexes.length > 0) def.indexes = input.indexes.slice();
+  if (input.search !== void 0) {
+    const s = input.search;
+    if (s.from !== void 0) {
+      if (s.vector !== void 0) {
+        throw new Error(
+          `table ${name}: search beyan\u0131nda tek bi\xE7im kullan\u0131n \u2014 'from' (yeni) ile 'vector' (eski) birlikte olamaz`
+        );
+      }
+      if (s.from.length === 0) {
+        throw new Error(`table ${name}: search.from bo\u015F olamaz`);
+      }
+      if (s.model === void 0) {
+        throw new Error(
+          `table ${name}: search.from model'siz anlams\u0131z \u2014 auto-embed i\xE7in model verin (BYO i\xE7in eski 'vector' bi\xE7imini kullan\u0131n)`
+        );
+      }
+      if (Array.isArray(s.text) && s.text.length === 0) {
+        throw new Error(`table ${name}: search.text bo\u015F dizi olamaz \u2014 FTS istemiyorsan text: false yaz\u0131n`);
+      }
+    } else {
+      if (typeof s.text === "boolean") {
+        throw new Error(`table ${name}: text:${String(s.text)} yaln\u0131z yeni bi\xE7imde ('from' ile) ge\xE7erli`);
+      }
+      if (s.text === void 0 && s.vector === void 0) {
+        throw new Error(
+          `table ${name}: search beyan\u0131 bo\u015F \u2014 en az bir kol (text ya da vector) verin, yoksa alan\u0131 hi\xE7 yazmay\u0131n`
+        );
+      }
+      if (s.text !== void 0 && s.text.length === 0) {
+        throw new Error(`table ${name}: search.text bo\u015F olamaz \u2014 FTS kolu istemiyorsan alan\u0131 hi\xE7 yazma`);
+      }
+      const legs = s.vector === void 0 ? [] : Array.isArray(s.vector) ? s.vector : [s.vector];
+      for (const leg of legs) {
+        if (leg.model !== void 0 && (leg.from === void 0 || leg.from.length === 0)) {
+          throw new Error(`table ${name}: search.vector.model beyan edildi ama 'from' yok \u2014 embed kayna\u011F\u0131 kolonlar zorunlu (C-2)`);
         }
-      } else {
-        if (typeof s.text === "boolean") {
-          throw new Error(`table ${String(name)}: text:${String(s.text)} yaln\u0131z yeni bi\xE7imde ('from' ile) ge\xE7erli`);
+        if (leg.model === void 0 && leg.from !== void 0) {
+          throw new Error(`table ${name}: search.vector.from model'siz anlams\u0131z \u2014 auto-embed i\xE7in model verin`);
         }
-        if (s.text === void 0 && s.vector === void 0) {
+      }
+    }
+    def.search = s;
+  }
+  if (input.memory !== void 0) {
+    if (input.memory.from.length === 0) {
+      throw new Error(`table ${name}: memory.from bo\u015F olamaz`);
+    }
+    def.memory = input.memory;
+  }
+  for (const b of Object.values(owned)) {
+    b._def.ownerTable = def;
+  }
+  const handle = { ...owned };
+  Object.defineProperty(handle, TABLE_META, { value: def, enumerable: false });
+  return handle;
+}
+var declaringSchemaOf = /* @__PURE__ */ new WeakMap();
+function resolveReferences(tables, schemaName) {
+  for (const table of Object.values(tables)) {
+    for (const [colName, builder] of Object.entries(table.columns)) {
+      const def = builder._def;
+      if (def.selfRefColumn !== void 0) {
+        if (!(def.selfRefColumn in table.columns)) {
           throw new Error(
-            `table ${String(name)}: search beyan\u0131 bo\u015F \u2014 en az bir kol (text ya da vector) verin, yoksa alan\u0131 hi\xE7 yazmay\u0131n`
+            `table "${table.name}" column "${colName}": selfReferences("${def.selfRefColumn}") \u2014 no such column on this table`
           );
         }
-        if (s.text !== void 0 && s.text.length === 0) {
-          throw new Error(`table ${String(name)}: search.text bo\u015F olamaz \u2014 FTS kolu istemiyorsan alan\u0131 hi\xE7 yazma`);
-        }
-        const legs = s.vector === void 0 ? [] : Array.isArray(s.vector) ? s.vector : [s.vector];
-        for (const leg of legs) {
-          if (leg.model !== void 0 && (leg.from === void 0 || leg.from.length === 0)) {
-            throw new Error(`table ${String(name)}: search.vector.model beyan edildi ama 'from' yok \u2014 embed kayna\u011F\u0131 kolonlar zorunlu (C-2)`);
-          }
-          if (leg.model === void 0 && leg.from !== void 0) {
-            throw new Error(`table ${String(name)}: search.vector.from model'siz anlams\u0131z \u2014 auto-embed i\xE7in model verin`);
-          }
-        }
+        def.references = {
+          table: qualifiedTableKey(schemaName, table.name),
+          column: def.selfRefColumn
+        };
+        continue;
       }
-      tableDef.search = s;
-    }
-    if (table.memory !== void 0) {
-      if (table.memory.from.length === 0) {
-        throw new Error(`table ${String(name)}: memory.from bo\u015F olamaz`);
+      if (def.referencesThunk === void 0) continue;
+      const target = def.referencesThunk();
+      const owner = target?._def?.ownerTable;
+      if (owner === void 0) {
+        throw new Error(
+          `table "${table.name}" column "${colName}": references(() => \u2026) must point at a column of a table declared with defineTable(...)`
+        );
+      }
+      const targetColumn = Object.entries(owner.columns).find(
+        ([, b]) => b._def === target._def
+      )?.[0];
+      if (targetColumn === void 0) {
+        throw new Error(
+          `table "${table.name}" column "${colName}": the referenced column was not found on table "${owner.name}"`
+        );
       }
-      tableDef.memory = table.memory;
+      const targetSchema = declaringSchemaOf.get(owner);
+      if (targetSchema === void 0) {
+        throw new Error(
+          `table "${table.name}" column "${colName}": references(() => \u2026) points at table "${owner.name}", which no defineSchema(...) has claimed yet \u2014 a foreign key cannot be written without its target's schema. Declare that table's schema first (one file per schema: db/public.ts, db/billing.ts \u2026, imported by this one).`
+        );
+      }
+      def.references = {
+        table: qualifiedTableKey(targetSchema, owner.name),
+        column: targetColumn
+      };
     }
-    tables[name] = tableDef;
   }
-  for (const [name, def] of Object.entries(tables)) {
+}
+function defineSchema(name, input) {
+  if (typeof name !== "string") {
+    throw new Error(
+      `defineSchema(...) takes the schema NAME first: defineSchema("public", { tables: [todos, lists] }). The one-argument form defineSchema({ tables: { \u2026 } }) is gone \u2014 a schema that does not say its own name cannot be told apart from another schema's table of the same name, which is what a cross-schema foreign key has to do. Migrate db/public.ts (one file per schema: db/public.ts, db/billing.ts \u2026): name the schema, and lift each table key onto the table itself with defineTable("todos", { columns: { \u2026 } }), then list the tables in the array.`
+    );
+  }
+  if (name.trim() === "") {
+    throw new Error("defineSchema(name, \u2026): name must not be empty");
+  }
+  const tables = {};
+  for (const handle of input.tables) {
+    const table = handle[TABLE_META];
+    if (tables[table.name] !== void 0) {
+      throw new Error(
+        `defineSchema("${name}"): two tables declare the name "${table.name}" \u2014 table names must be unique within a schema`
+      );
+    }
+    tables[table.name] = table;
+    declaringSchemaOf.set(table, name);
+  }
+  resolveReferences(tables, name);
+  for (const [name2, def] of Object.entries(tables)) {
     const m = def.memory;
     if (m === void 0) continue;
     const target = Object.values(tables).find((t) => t.name === m.into);
     if (target === void 0) {
-      throw new Error(`table ${name}: memory.into "${m.into}" \u015Femada declared de\u011Fil`);
+      throw new Error(`table ${name2}: memory.into "${m.into}" \u015Femada declared de\u011Fil`);
     }
     const subject = m.subject ?? "owner";
     if (!(subject in def.columns)) {
-      throw new Error(`table ${name}: memory.subject "${subject}" kolonu kaynak tabloda yok`);
+      throw new Error(`table ${name2}: memory.subject "${subject}" kolonu kaynak tabloda yok`);
     }
     if (!(subject in target.columns)) {
-      throw new Error(`table ${name}: memory.subject "${subject}" kolonu hedef "${m.into}" tablosunda yok`);
+      throw new Error(`table ${name2}: memory.subject "${subject}" kolonu hedef "${m.into}" tablosunda yok`);
     }
     const factCol = target.columns["fact"];
     const factDef = factCol !== void 0 && "_def" in factCol ? factCol._def : factCol;
     if (factDef === void 0 || factDef.type !== "text") {
-      throw new Error(`table ${name}: memory.into "${m.into}" tablosunda "fact" (text) kolonu zorunlu`);
+      throw new Error(`table ${name2}: memory.into "${m.into}" tablosunda "fact" (text) kolonu zorunlu`);
     }
     for (const c of m.from) {
       if (!(c in def.columns)) {
-        throw new Error(`table ${name}: memory.from kolonu "${c}" kaynak tabloda yok`);
+        throw new Error(`table ${name2}: memory.from kolonu "${c}" kaynak tabloda yok`);
       }
     }
   }
   const extensions = [...new Set(input.extensions ?? [])];
-  return { tables, extensions };
+  return {
+    name,
+    tables,
+    extensions,
+    exposed: input.exposed ?? name === "public"
+  };
 }
 
 // src/db/extensions.ts
@@ -380,59 +474,53 @@ var ColumnBuilder = class _ColumnBuilder {
       ignored: true
     });
   }
-  references(table, column) {
-    refuseOnVector(this._def, "references");
-    this._def.references = { table, column };
-    return new _ColumnBuilder(this._def.type, this._def);
-  }
   /**
-   * 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.
+   *
+   * `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) {
-    refuseOnVector(this._def, "referencesAuthUser");
-    this._def.references = { table: "auth.users", column: "id" };
-    this._def.onDeleteAction = onDelete;
+  references(target, opts) {
+    refuseOnVector(this._def, "references");
+    if (typeof target !== "function") {
+      throw new Error(
+        `references(...) takes a callback: write references(() => otherTable.column). The two-string form references("table", "column") is gone \u2014 a string cannot be type-checked and cannot point at a table that does not exist yet.`
+      );
+    }
+    this._def.referencesThunk = target;
+    if (opts?.as !== void 0) this._def.refAs = opts.as;
+    if (opts?.reverseAs !== void 0) this._def.reverseAs = opts.reverseAs;
+    if (opts?.onDelete !== void 0) this._def.onDeleteAction = opts.onDelete;
     return new _ColumnBuilder(this._def.type, this._def);
   }
   /**
-   * 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) {
-    refuseOnVector(this._def, "referencesInstallation");
-    this._def.references = { table: "auth.installations", column: "id" };
-    this._def.onDeleteAction = onDelete;
+  selfReferences(column, opts) {
+    refuseOnVector(this._def, "selfReferences");
+    this._def.selfRefColumn = column;
+    if (opts?.as !== void 0) this._def.refAs = opts.as;
+    if (opts?.onDelete !== void 0) this._def.onDeleteAction = opts.onDelete;
     return new _ColumnBuilder(this._def.type, this._def);
   }
   /** Set the ON DELETE action for a foreign key reference. */
@@ -504,6 +592,28 @@ function vector(dimensions) {
   b._def.dimensions = dimensions;
   return b;
 }
+function ownedByUser() {
+  const b = new ColumnBuilder("text");
+  b._def.nullable = false;
+  b._def.references = { table: "auth.users", column: "id" };
+  b._def.onDeleteAction = "cascade";
+  b._def.owns = true;
+  return b;
+}
+function userRef(opts) {
+  const b = new ColumnBuilder("text");
+  b._def.references = { table: "auth.users", column: "id" };
+  b._def.onDeleteAction = opts.onDelete;
+  if (opts.as !== void 0) b._def.refAs = opts.as;
+  return b;
+}
+function installationRef(opts) {
+  const b = new ColumnBuilder("text");
+  b._def.references = { table: "auth.installations", column: "id" };
+  b._def.onDeleteAction = opts.onDelete;
+  if (opts.as !== void 0) b._def.refAs = opts.as;
+  return b;
+}
 
 // src/db/raw.ts
 function raw(name, up, opts) {
@@ -1013,24 +1123,29 @@ function makeTypedDB(schema, raw2) {
   EXTENSION_DEPENDENCIES,
   PALBASE_EXTENSIONS,
   PolicyBuilder,
+  TABLE_META,
   TxPlanError,
   TxRefError,
   bigint,
   boolean,
   dec,
   defineSchema,
+  defineTable,
   enumType,
   inc,
+  installationRef,
   integer,
   isPalbaseExtension,
   jsonb,
   makeTypedDB,
   now,
   openai,
+  ownedByUser,
   policy,
   raw,
   text,
   timestamp,
+  userRef,
   uuid,
   vector
 });