@palbase/backend 10.3.0 → 12.0.0

package/dist/{index-DfryIw9U.d.ts → index-l7DhBDtn.d.ts}

@@ -1,5 +1,5 @@
 import { Tables, TableTypes } from './db/env.js';
-import { D as DBClient } from './endpoint-92kVepng.js';
+import { D as DBClient, ba as TxPlanHandle, bk as TxTable, M as Materialized } from './endpoint-Ck4hER_7.js';
 
 /** On delete action for foreign key references. */
 type OnDeleteAction = 'cascade' | 'set null' | 'restrict' | 'no action';
@@ -536,29 +536,27 @@ interface TypedDB<S extends SchemaDef> {
     tables: {
         [K in keyof S["tables"]]: TypedTable<S["tables"][K]>;
     };
-    transaction<T>(fn: (tx: TypedTx<S>) => Promise<T>): Promise<T>;
-}
-/** Transaction-scoped typed facade: same typed tables, no nested transaction. */
-interface TypedTx<S extends SchemaDef> {
-    tables: {
-        [K in keyof S["tables"]]: TypedTable<S["tables"][K]>;
-    };
+    /** Run a transaction plan. See {@link EnvTypedDatabase.transaction}. */
+    transaction<T>(fn: (tx: TypedTx<S>) => T extends Promise<unknown> ? never : T): Promise<Materialized<T>>;
 }
+/** The plan-building handle a `TypedDB<S>` transaction callback receives: the
+ * schema's tables, expressed as plan operations rather than awaited calls. */
+type TypedTx<S extends SchemaDef> = TxPlanHandle<{
+    [K in keyof S["tables"]]: TxTable<RowShape<S["tables"][K]>, InsertShape<S["tables"][K]>>;
+}>;
 /**
  * Wraps a raw `DBClient` with the type-safe `TypedDB<S>` facade derived from
- * the provided schema. No behavior change — all calls delegate to `raw` with
- * the table name as a plain string.
+ * the provided schema. No behavior change for the direct ops — all calls
+ * delegate to `raw` with the table name as a plain string.
  *
- * `buildTables` is the reusable factory that wraps any op-bearing client
- * (`TxClient` — the surface shared by `DBClient` and the transaction-scoped
- * client) into the typed tables map. It is used both for the top-level db
- * (wrapping `raw`) and inside `transaction`, where it wraps the raw `TxClient`
- * the runtime yields so the callback sees the same typed `.tables` API.
+ * `transaction` does NOT delegate to a per-op client: the callback describes a
+ * plan against a fresh {@link TxPlanBuilder}, and the whole plan travels in one
+ * `raw.txPlan` call. The schema is used only for its table NAMES; the values
+ * are typed by `S` at compile time and are plain strings at run time.
  *
- * `transaction` delegates straight to `raw.transaction`; the two narrow
- * `as TypedTx<S>` / `as TypedDB<S>` casts are single structural narrowings
- * from the dynamically-built tables object to the precise mapped type (TS
- * cannot infer through `Object.keys` iteration) — see module-level doc comment.
+ * The `as` casts are single structural narrowings from a dynamically-built
+ * object to the precise mapped type (TS cannot infer the mapped-type result
+ * through `Object.keys` iteration) — see the module-level doc comment.
  */
 declare function makeTypedDB<S extends SchemaDef>(schema: S, raw: DBClient): TypedDB<S>;
 /** A typed table accessor derived from one env `Tables` entry's flat shapes. */
@@ -578,34 +576,66 @@ interface EnvTypedTable<T extends TableTypes> {
 type EnvTables = {
     [K in keyof Tables]: EnvTypedTable<Tables[K]>;
 };
-/** Transaction-scoped typed facade for the env-augmented surface: same typed
- * tables, no nested transaction. */
-interface EnvTypedTx {
-    tables: EnvTables;
-}
+/** The project's tables as PLAN operations, keyed by the env `Tables`
+ * interface. The transaction twin of {@link EnvTables}. */
+type TxTables = {
+    [K in keyof Tables]: TxTable<Tables[K]["row"], Tables[K]["insert"]>;
+};
+/**
+ * The handle a `Database.transaction(…)` callback receives.
+ *
+ * Tables only — no `query`, no `findById`, no `asService`. A read whose value
+ * the plan does not write belongs outside the transaction, where it costs one
+ * round trip and is an ordinary value you can branch on.
+ */
+type TxPlan = TxPlanHandle<TxTables>;
 /**
  * The RLS-bypass sibling returned by `Database.asService()`. Same typed surface
  * as {@link EnvTypedDatabase} — `tables`, the raw string ops, and a typed
  * `transaction` — but it does NOT re-expose `asService` (no double-bypass).
  * Every op it performs runs as the `service_role` (BYPASSRLS).
  */
-interface EnvServiceDatabase extends Omit<DBClient, "transaction" | "asService"> {
+interface EnvServiceDatabase extends Omit<DBClient, "txPlan" | "asService"> {
     tables: EnvTables;
-    transaction<T>(fn: (tx: EnvTypedTx) => Promise<T>): Promise<T>;
+    transaction<T>(fn: (tx: TxPlan) => T extends Promise<unknown> ? never : T): Promise<Materialized<T>>;
 }
 /**
  * The typed-by-default Database surface: the raw string-keyed `DBClient` ops
  * PLUS a `tables` map typed against the project's generated `palbase-env.d.ts`,
- * a `transaction` whose callback receives the typed tables, and `asService()`
- * for the explicit RLS-bypass sibling.
+ * a `transaction` that runs a whole plan in one request, and `asService()` for
+ * the explicit RLS-bypass sibling.
  *
- * `transaction` is declared here (overriding `DBClient["transaction"]`) so the
- * `tx` the callback receives carries the typed `.tables` API. `asService` is
- * re-typed to return the typed {@link EnvServiceDatabase} sibling.
+ * The low-level `txPlan` op is deliberately NOT re-exposed here: `transaction`
+ * is the surface, and a hand-built plan would bypass the ref/guard machinery
+ * that makes one safe to write.
  */
-interface EnvTypedDatabase extends Omit<DBClient, "transaction" | "asService"> {
+interface EnvTypedDatabase extends Omit<DBClient, "txPlan" | "asService"> {
     tables: EnvTables;
-    transaction<T>(fn: (tx: EnvTypedTx) => Promise<T>): Promise<T>;
+    /**
+     * Run a transaction. The callback DESCRIBES the operations; the whole
+     * description travels in one request and the broker runs it inside a single
+     * transaction — committing when it finishes, rolling back on any failure.
+     *
+     * The callback is SYNCHRONOUS: nothing has run when it returns, so there is
+     * nothing to await. `async` on it and `await` inside it are compile errors.
+     * Values a later operation needs are {@link Ref}s, written straight into the
+     * next operation; values the CALLER needs are returned and substituted before
+     * this promise resolves.
+     *
+     * @example
+     * const { statementId } = await Database.transaction((tx) => {
+     *   const st = tx.tables.statements
+     *     .insert({ household_id: hid, file_sha256: sha, status: "reviewing" })
+     *     .expectOne(new Internal("statement insert failed"));
+     *
+     *   tx.tables.statement_lines.insertMany(
+     *     lines.map((l) => ({ statement_id: st.id, category: resolveCategory(l) })),
+     *   );
+     *
+     *   return { statementId: st.id };
+     * });
+     */
+    transaction<T>(fn: (tx: TxPlan) => T extends Promise<unknown> ? never : T): Promise<Materialized<T>>;
     /**
      * Return a sibling that bypasses RLS by running as the `service_role`. Use
      * sparingly and explicitly — the default `Database.*` path is RLS-enforced.
@@ -617,4 +647,4 @@ interface EnvTypedDatabase extends Omit<DBClient, "transaction" | "asService"> {
     asService(): EnvServiceDatabase;
 }
 
-export { makeTypedDB as A, numeric as B, ColumnBuilder as C, policy as D, type EnvTypedDatabase as E, raw as F, text as G, timestamp as H, type InsertShape as I, uuid as J, 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 EnvServiceDatabase as e, type EnvTables as f, type EnvTypedTable as g, type EnvTypedTx 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 TypedDB as q, type TypedTable as r, type TypedTx as s, bigint as t, boolean as u, defineSchema as v, enumType as w, integer as x, isPalbaseExtension as y, jsonb as z };
+export { jsonb as A, makeTypedDB as B, ColumnBuilder as C, numeric as D, type EnvTypedDatabase as E, policy as F, raw as G, text as H, type InsertShape as I, timestamp as J, uuid as K, 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 EnvServiceDatabase as e, type EnvTables as f, type EnvTypedTable as g, type PalbaseExtension as h, PolicyBuilder as i, type PolicyCommand as j, type PolicyDef as k, type PolicyMode as l, type RowShape as m, type SchemaInput as n, type TableInput as o, type TxPlan as p, type TxTables as q, type TypedDB as r, type TypedTable as s, type TypedTx as t, bigint as u, boolean as v, defineSchema as w, enumType as x, integer as y, isPalbaseExtension as z };