@palbase/backend 2.0.2 → 3.0.0

package/dist/index-CXUs9iTQ.d.ts

@@ -0,0 +1,294 @@
+import { Tables, TableTypes } from './db/env.js';
+import { D as DBClient } from './endpoint-DJ98tQd6.js';
+
+/** On delete action for foreign key references. */
+type OnDeleteAction = 'cascade' | 'set null' | 'restrict' | 'no action';
+/** Column type identifiers. */
+type ColumnType = 'uuid' | 'text' | 'integer' | 'boolean' | 'timestamp' | 'jsonb' | 'enum';
+/** Base column definition shared by all column types. */
+interface ColumnDef {
+    type: ColumnType;
+    nullable: boolean;
+    primaryKey: boolean;
+    defaultValue?: unknown;
+    defaultRandom?: boolean;
+    defaultNow?: boolean;
+    references?: {
+        table: string;
+        column: string;
+    };
+    onDeleteAction?: OnDeleteAction;
+    enumName?: string;
+    enumValues?: string[];
+}
+declare const __colKind: unique symbol;
+declare const __colNullable: unique symbol;
+declare const __colHasDefault: unique symbol;
+declare const __colEnumValues: unique symbol;
+/**
+ * Fluent column builder with phantom type params:
+ *  K — ColumnType literal (e.g. "text", "integer")
+ *  N — boolean: true when nullable() has been called last (false = NOT NULL)
+ *  D — boolean: true when a default has been set
+ *  E — enum value union (never for non-enum columns)
+ *
+ * All four params have defaults so bare `ColumnBuilder` (no args) still
+ * satisfies `Record<string, ColumnBuilder>` in schema.ts without modification.
+ *
+ * The four `declare readonly` brand fields carry the phantom types into the
+ * structural shape so that conditional types like ColValue<C> can discriminate
+ * on K without requiring runtime values on those fields.
+ */
+declare class ColumnBuilder<K extends ColumnType = ColumnType, N extends boolean = boolean, D extends boolean = boolean, E = unknown> {
+    readonly [__colKind]: K;
+    readonly [__colNullable]: N;
+    readonly [__colHasDefault]: D;
+    readonly [__colEnumValues]: E;
+    readonly _def: ColumnDef;
+    constructor(type: K, existingDef?: ColumnDef);
+    /** Mark this column as the primary key. */
+    primaryKey(): ColumnBuilder<K, N, D, E>;
+    /** Mark this column as NOT NULL (default). */
+    notNull(): ColumnBuilder<K, false, D, E>;
+    /** Allow NULL values. */
+    nullable(): ColumnBuilder<K, true, D, E>;
+    /** Set a default value. */
+    default(value: unknown): ColumnBuilder<K, N, true, E>;
+    /** UUID: generate a random default (gen_random_uuid()). */
+    defaultRandom(): ColumnBuilder<K, N, true, E>;
+    /** Timestamp: default to now(). */
+    defaultNow(): ColumnBuilder<K, N, true, E>;
+    /** Add a foreign key reference. */
+    references(table: string, column: string): ColumnBuilder<K, N, D, E>;
+    /** Set the ON DELETE action for a foreign key reference. */
+    onDelete(action: OnDeleteAction): ColumnBuilder<K, N, D, E>;
+}
+/**
+ * Extracts the TypeScript value type for a column, respecting nullability.
+ * - "uuid" | "text" | "timestamp" → string (or string | null when N = true)
+ * - "integer" → number
+ * - "boolean" → boolean
+ * - "jsonb" → unknown (opaque JSON)
+ * - "enum" → E (the union of literal values)
+ */
+type ColValue<C> = C extends ColumnBuilder<'uuid' | 'text' | 'timestamp', infer N, infer _D, infer _E> ? N extends true ? string | null : string : C extends ColumnBuilder<'integer', infer N, infer _D, infer _E> ? N extends true ? number | null : number : C extends ColumnBuilder<'boolean', infer N, infer _D, infer _E> ? N extends true ? boolean | null : boolean : C extends ColumnBuilder<'jsonb', infer _N, infer _D, infer _E> ? unknown : C extends ColumnBuilder<'enum', infer N, infer _D, infer E> ? N extends true ? E | null : E : never;
+/**
+ * True when a column is optional on INSERT:
+ *  - nullable columns (N = true) — the DB allows NULL so the field may be omitted
+ *  - columns with a default (D = true) — the DB fills in the value when absent
+ */
+type ColIsOptionalOnInsert<C> = C extends ColumnBuilder<infer _K, true, infer _D, infer _E> ? true : C extends ColumnBuilder<infer _K, infer _N, true, infer _E> ? true : false;
+/** Create a UUID column. */
+declare function uuid(): ColumnBuilder<'uuid', false, false, never>;
+/** Create a TEXT column. */
+declare function text(): ColumnBuilder<'text', false, false, never>;
+/** Create an INTEGER column. */
+declare function integer(): ColumnBuilder<'integer', false, false, never>;
+/** Create a BOOLEAN column. */
+declare function boolean(): ColumnBuilder<'boolean', false, false, never>;
+/** Create a TIMESTAMP column. */
+declare function timestamp(): ColumnBuilder<'timestamp', false, false, never>;
+/** Create a JSONB column. */
+declare function jsonb(): ColumnBuilder<'jsonb', false, false, never>;
+/**
+ * Create an ENUM column.
+ * @param name   The PostgreSQL enum type name (used in DDL).
+ * @param values A readonly tuple of valid string values — kept `const` so the
+ *               union `V[number]` is as narrow as possible.
+ */
+declare function enumType<const V extends readonly string[]>(name: string, values: V): ColumnBuilder<'enum', false, false, V[number]>;
+
+/**
+ * A map of column builders keyed by column name — the value you write under
+ * each key of `defineSchema({ tables: { <name>: <columns> } })`.
+ *
+ * The default `Record<string, ColumnBuilder>` keeps bare references compiling
+ * without a type argument.
+ */
+type ColumnMap = Record<string, ColumnBuilder>;
+/**
+ * A table definition with its name and columns.
+ *
+ * The runtime value shape — `{ name, columns }` — is the contract the Go
+ * runtime's `schema_extract.js` reads (it keys tables by `tableDef.name`).
+ * `defineSchema` derives `name` from the object key, so authors never repeat
+ * the table name.
+ *
+ * The `C` type parameter preserves the precise per-column phantom types so
+ * that downstream mapped types (InsertShape, RowShape) can discriminate on
+ * them.
+ */
+interface TableDef<C extends ColumnMap = ColumnMap> {
+    name: string;
+    columns: C;
+}
+/**
+ * A schema definition containing multiple tables, keyed by table name.
+ *
+ * The `T` type parameter preserves the exact `TableDef<...>` type for each
+ * table so that `SchemaDef["tables"]["rooms"]` resolves to the precise
+ * `TableDef<{ id: ColumnBuilder<'uuid', false, true, never>; ... }>`.
+ */
+interface SchemaDef<T extends Record<string, TableDef> = Record<string, TableDef>> {
+    tables: T;
+}
+/** The author-facing input to `defineSchema` — a `tables` map whose keys are
+ * the table names and whose values are the column maps. */
+interface SchemaInput<T extends Record<string, ColumnMap> = Record<string, ColumnMap>> {
+    tables: T;
+}
+/** Map the author's `{ tables: { <name>: <columns> } }` input to the
+ * `{ tables: { <name>: TableDef<columns> } }` runtime/type shape. */
+type TablesFromInput<T extends Record<string, ColumnMap>> = {
+    [K in keyof T]: TableDef<T[K]>;
+};
+/**
+ * Define a schema. The table NAME comes from the object key — there is one
+ * canonical form:
+ *
+ *   export default defineSchema({
+ *     tables: {
+ *       todos: {
+ *         id:    uuid().primaryKey().defaultRandom(),
+ *         title: text().notNull(),
+ *       },
+ *     },
+ *   });
+ *
+ * The returned value is `{ tables: { todos: { name: "todos", columns: {...} } } }`
+ * — the exact shape the runtime schema extractor parses. Per-column phantom
+ * types are preserved so `Database.tables.todos.insert({...})` is typed.
+ *
+ * @example
+ * import { defineSchema, uuid, text, timestamp } from "@palbase/backend";
+ *
+ * export default defineSchema({
+ *   tables: {
+ *     todos: {
+ *       id:         uuid().primaryKey().defaultRandom(),
+ *       title:      text().notNull(),
+ *       done:       boolean().default(false),
+ *       created_at: timestamp().defaultNow(),
+ *     },
+ *   },
+ * });
+ */
+declare function defineSchema<T extends Record<string, ColumnMap>>(input: SchemaInput<T>): SchemaDef<TablesFromInput<T>>;
+
+/**
+ * typed-db.ts — Task 2: TypedDB schema-derived insert/row shapes.
+ *
+ * Derives INSERT and full-row TypeScript types from a `defineSchema()` result
+ * and wraps the untyped runtime `DBClient` with a typed facade.
+ *
+ * No value-any. No `as unknown as X`. The two narrow `as` casts in
+ * `makeTypedTable` are safe because:
+ *  - `data as Record<string, unknown>`: InsertShape<T> maps string keys to
+ *    typed values; all value types are subsets of `unknown`, so the cast is
+ *    structurally sound.
+ *  - `result as RowShape<T>`: The runtime DBClient returns `Record<string,
+ *    unknown>` which is the erased form of the typed row; we're narrowing back
+ *    to the precise shape that the schema declared.
+ * Both casts are narrowing only (not widening) and correctness is guaranteed
+ * by the schema the caller provides.
+ */
+
+/** Keys of C whose columns are required on INSERT (not nullable, no default). */
+type RequiredKeys<C> = {
+    [K in keyof C]: ColIsOptionalOnInsert<C[K]> extends true ? never : K;
+}[keyof C];
+/** Keys of C whose columns are optional on INSERT (nullable or has a default). */
+type OptionalKeys<C> = {
+    [K in keyof C]: ColIsOptionalOnInsert<C[K]> extends true ? K : never;
+}[keyof C];
+/**
+ * The TypeScript type for an INSERT payload for table `T`.
+ * - Required: columns that are NOT NULL and have no DB-level default.
+ * - Optional: columns that are nullable or carry a default.
+ *
+ * When all columns are optional, `RequiredKeys<C>` resolves to `never` and
+ * the first part becomes `{}`, which is a neutral element for `&`.
+ */
+type InsertShape<T extends TableDef> = {
+    [K in RequiredKeys<T["columns"]>]: ColValue<T["columns"][K]>;
+} & {
+    [K in OptionalKeys<T["columns"]>]?: ColValue<T["columns"][K]>;
+};
+/**
+ * The TypeScript type for a full row returned by the DB for table `T`.
+ * Every column is present; nullable columns resolve to `T | null`.
+ */
+type RowShape<T extends TableDef> = {
+    [K in keyof T["columns"]]: ColValue<T["columns"][K]>;
+};
+/** A typed table accessor that mirrors the runtime DBClient surface. */
+interface TypedTable<T extends TableDef> {
+    insert(data: InsertShape<T>): Promise<RowShape<T>>;
+    update(id: string, data: Partial<InsertShape<T>>): Promise<RowShape<T>>;
+    delete(id: string): Promise<void>;
+    findById(id: string): Promise<RowShape<T> | null>;
+    findMany(query?: Partial<RowShape<T>>): Promise<RowShape<T>[]>;
+}
+/** A typed DB facade covering all tables declared in schema `S`. */
+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]>;
+    };
+}
+/**
+ * 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.
+ *
+ * `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` 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.
+ */
+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. */
+interface EnvTypedTable<T extends TableTypes> {
+    insert(data: T["insert"]): Promise<T["row"]>;
+    update(id: string, data: Partial<T["insert"]>): Promise<T["row"]>;
+    delete(id: string): Promise<void>;
+    findById(id: string): Promise<T["row"] | null>;
+    findMany(query?: Partial<T["row"]>): Promise<T["row"][]>;
+}
+/** The `tables` map exposed on `Database`/`tx`, keyed by the env `Tables`
+ * interface. When no schema is declared `Tables` is empty, so `tables` is an
+ * empty object — accessing `.tables.foo` is then a compile error (no member). */
+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 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`
+ * and a `transaction` whose callback receives the typed tables.
+ *
+ * `transaction` is declared here (overriding `DBClient["transaction"]`) so the
+ * `tx` the callback receives carries the typed `.tables` API.
+ */
+interface EnvTypedDatabase extends Omit<DBClient, "transaction"> {
+    tables: EnvTables;
+    transaction<T>(fn: (tx: EnvTypedTx) => Promise<T>): Promise<T>;
+}
+
+export { ColumnBuilder as C, type EnvTypedDatabase as E, type InsertShape as I, type OnDeleteAction as O, type RowShape as R, type SchemaDef as S, type TableDef as T, type ColumnDef as a, type ColumnMap as b, type ColumnType as c, type EnvTables as d, type EnvTypedTable as e, type EnvTypedTx as f, type SchemaInput as g, type TypedDB as h, type TypedTable as i, type TypedTx as j, boolean as k, defineSchema as l, enumType as m, integer as n, jsonb as o, makeTypedDB as p, timestamp as q, text as t, uuid as u };

package/dist/index-CZAwpQE1.d.cts

@@ -0,0 +1,294 @@
+import { Tables, TableTypes } from './db/env.cjs';
+import { D as DBClient } from './endpoint-DJ98tQd6.cjs';
+
+/** On delete action for foreign key references. */
+type OnDeleteAction = 'cascade' | 'set null' | 'restrict' | 'no action';
+/** Column type identifiers. */
+type ColumnType = 'uuid' | 'text' | 'integer' | 'boolean' | 'timestamp' | 'jsonb' | 'enum';
+/** Base column definition shared by all column types. */
+interface ColumnDef {
+    type: ColumnType;
+    nullable: boolean;
+    primaryKey: boolean;
+    defaultValue?: unknown;
+    defaultRandom?: boolean;
+    defaultNow?: boolean;
+    references?: {
+        table: string;
+        column: string;
+    };
+    onDeleteAction?: OnDeleteAction;
+    enumName?: string;
+    enumValues?: string[];
+}
+declare const __colKind: unique symbol;
+declare const __colNullable: unique symbol;
+declare const __colHasDefault: unique symbol;
+declare const __colEnumValues: unique symbol;
+/**
+ * Fluent column builder with phantom type params:
+ *  K — ColumnType literal (e.g. "text", "integer")
+ *  N — boolean: true when nullable() has been called last (false = NOT NULL)
+ *  D — boolean: true when a default has been set
+ *  E — enum value union (never for non-enum columns)
+ *
+ * All four params have defaults so bare `ColumnBuilder` (no args) still
+ * satisfies `Record<string, ColumnBuilder>` in schema.ts without modification.
+ *
+ * The four `declare readonly` brand fields carry the phantom types into the
+ * structural shape so that conditional types like ColValue<C> can discriminate
+ * on K without requiring runtime values on those fields.
+ */
+declare class ColumnBuilder<K extends ColumnType = ColumnType, N extends boolean = boolean, D extends boolean = boolean, E = unknown> {
+    readonly [__colKind]: K;
+    readonly [__colNullable]: N;
+    readonly [__colHasDefault]: D;
+    readonly [__colEnumValues]: E;
+    readonly _def: ColumnDef;
+    constructor(type: K, existingDef?: ColumnDef);
+    /** Mark this column as the primary key. */
+    primaryKey(): ColumnBuilder<K, N, D, E>;
+    /** Mark this column as NOT NULL (default). */
+    notNull(): ColumnBuilder<K, false, D, E>;
+    /** Allow NULL values. */
+    nullable(): ColumnBuilder<K, true, D, E>;
+    /** Set a default value. */
+    default(value: unknown): ColumnBuilder<K, N, true, E>;
+    /** UUID: generate a random default (gen_random_uuid()). */
+    defaultRandom(): ColumnBuilder<K, N, true, E>;
+    /** Timestamp: default to now(). */
+    defaultNow(): ColumnBuilder<K, N, true, E>;
+    /** Add a foreign key reference. */
+    references(table: string, column: string): ColumnBuilder<K, N, D, E>;
+    /** Set the ON DELETE action for a foreign key reference. */
+    onDelete(action: OnDeleteAction): ColumnBuilder<K, N, D, E>;
+}
+/**
+ * Extracts the TypeScript value type for a column, respecting nullability.
+ * - "uuid" | "text" | "timestamp" → string (or string | null when N = true)
+ * - "integer" → number
+ * - "boolean" → boolean
+ * - "jsonb" → unknown (opaque JSON)
+ * - "enum" → E (the union of literal values)
+ */
+type ColValue<C> = C extends ColumnBuilder<'uuid' | 'text' | 'timestamp', infer N, infer _D, infer _E> ? N extends true ? string | null : string : C extends ColumnBuilder<'integer', infer N, infer _D, infer _E> ? N extends true ? number | null : number : C extends ColumnBuilder<'boolean', infer N, infer _D, infer _E> ? N extends true ? boolean | null : boolean : C extends ColumnBuilder<'jsonb', infer _N, infer _D, infer _E> ? unknown : C extends ColumnBuilder<'enum', infer N, infer _D, infer E> ? N extends true ? E | null : E : never;
+/**
+ * True when a column is optional on INSERT:
+ *  - nullable columns (N = true) — the DB allows NULL so the field may be omitted
+ *  - columns with a default (D = true) — the DB fills in the value when absent
+ */
+type ColIsOptionalOnInsert<C> = C extends ColumnBuilder<infer _K, true, infer _D, infer _E> ? true : C extends ColumnBuilder<infer _K, infer _N, true, infer _E> ? true : false;
+/** Create a UUID column. */
+declare function uuid(): ColumnBuilder<'uuid', false, false, never>;
+/** Create a TEXT column. */
+declare function text(): ColumnBuilder<'text', false, false, never>;
+/** Create an INTEGER column. */
+declare function integer(): ColumnBuilder<'integer', false, false, never>;
+/** Create a BOOLEAN column. */
+declare function boolean(): ColumnBuilder<'boolean', false, false, never>;
+/** Create a TIMESTAMP column. */
+declare function timestamp(): ColumnBuilder<'timestamp', false, false, never>;
+/** Create a JSONB column. */
+declare function jsonb(): ColumnBuilder<'jsonb', false, false, never>;
+/**
+ * Create an ENUM column.
+ * @param name   The PostgreSQL enum type name (used in DDL).
+ * @param values A readonly tuple of valid string values — kept `const` so the
+ *               union `V[number]` is as narrow as possible.
+ */
+declare function enumType<const V extends readonly string[]>(name: string, values: V): ColumnBuilder<'enum', false, false, V[number]>;
+
+/**
+ * A map of column builders keyed by column name — the value you write under
+ * each key of `defineSchema({ tables: { <name>: <columns> } })`.
+ *
+ * The default `Record<string, ColumnBuilder>` keeps bare references compiling
+ * without a type argument.
+ */
+type ColumnMap = Record<string, ColumnBuilder>;
+/**
+ * A table definition with its name and columns.
+ *
+ * The runtime value shape — `{ name, columns }` — is the contract the Go
+ * runtime's `schema_extract.js` reads (it keys tables by `tableDef.name`).
+ * `defineSchema` derives `name` from the object key, so authors never repeat
+ * the table name.
+ *
+ * The `C` type parameter preserves the precise per-column phantom types so
+ * that downstream mapped types (InsertShape, RowShape) can discriminate on
+ * them.
+ */
+interface TableDef<C extends ColumnMap = ColumnMap> {
+    name: string;
+    columns: C;
+}
+/**
+ * A schema definition containing multiple tables, keyed by table name.
+ *
+ * The `T` type parameter preserves the exact `TableDef<...>` type for each
+ * table so that `SchemaDef["tables"]["rooms"]` resolves to the precise
+ * `TableDef<{ id: ColumnBuilder<'uuid', false, true, never>; ... }>`.
+ */
+interface SchemaDef<T extends Record<string, TableDef> = Record<string, TableDef>> {
+    tables: T;
+}
+/** The author-facing input to `defineSchema` — a `tables` map whose keys are
+ * the table names and whose values are the column maps. */
+interface SchemaInput<T extends Record<string, ColumnMap> = Record<string, ColumnMap>> {
+    tables: T;
+}
+/** Map the author's `{ tables: { <name>: <columns> } }` input to the
+ * `{ tables: { <name>: TableDef<columns> } }` runtime/type shape. */
+type TablesFromInput<T extends Record<string, ColumnMap>> = {
+    [K in keyof T]: TableDef<T[K]>;
+};
+/**
+ * Define a schema. The table NAME comes from the object key — there is one
+ * canonical form:
+ *
+ *   export default defineSchema({
+ *     tables: {
+ *       todos: {
+ *         id:    uuid().primaryKey().defaultRandom(),
+ *         title: text().notNull(),
+ *       },
+ *     },
+ *   });
+ *
+ * The returned value is `{ tables: { todos: { name: "todos", columns: {...} } } }`
+ * — the exact shape the runtime schema extractor parses. Per-column phantom
+ * types are preserved so `Database.tables.todos.insert({...})` is typed.
+ *
+ * @example
+ * import { defineSchema, uuid, text, timestamp } from "@palbase/backend";
+ *
+ * export default defineSchema({
+ *   tables: {
+ *     todos: {
+ *       id:         uuid().primaryKey().defaultRandom(),
+ *       title:      text().notNull(),
+ *       done:       boolean().default(false),
+ *       created_at: timestamp().defaultNow(),
+ *     },
+ *   },
+ * });
+ */
+declare function defineSchema<T extends Record<string, ColumnMap>>(input: SchemaInput<T>): SchemaDef<TablesFromInput<T>>;
+
+/**
+ * typed-db.ts — Task 2: TypedDB schema-derived insert/row shapes.
+ *
+ * Derives INSERT and full-row TypeScript types from a `defineSchema()` result
+ * and wraps the untyped runtime `DBClient` with a typed facade.
+ *
+ * No value-any. No `as unknown as X`. The two narrow `as` casts in
+ * `makeTypedTable` are safe because:
+ *  - `data as Record<string, unknown>`: InsertShape<T> maps string keys to
+ *    typed values; all value types are subsets of `unknown`, so the cast is
+ *    structurally sound.
+ *  - `result as RowShape<T>`: The runtime DBClient returns `Record<string,
+ *    unknown>` which is the erased form of the typed row; we're narrowing back
+ *    to the precise shape that the schema declared.
+ * Both casts are narrowing only (not widening) and correctness is guaranteed
+ * by the schema the caller provides.
+ */
+
+/** Keys of C whose columns are required on INSERT (not nullable, no default). */
+type RequiredKeys<C> = {
+    [K in keyof C]: ColIsOptionalOnInsert<C[K]> extends true ? never : K;
+}[keyof C];
+/** Keys of C whose columns are optional on INSERT (nullable or has a default). */
+type OptionalKeys<C> = {
+    [K in keyof C]: ColIsOptionalOnInsert<C[K]> extends true ? K : never;
+}[keyof C];
+/**
+ * The TypeScript type for an INSERT payload for table `T`.
+ * - Required: columns that are NOT NULL and have no DB-level default.
+ * - Optional: columns that are nullable or carry a default.
+ *
+ * When all columns are optional, `RequiredKeys<C>` resolves to `never` and
+ * the first part becomes `{}`, which is a neutral element for `&`.
+ */
+type InsertShape<T extends TableDef> = {
+    [K in RequiredKeys<T["columns"]>]: ColValue<T["columns"][K]>;
+} & {
+    [K in OptionalKeys<T["columns"]>]?: ColValue<T["columns"][K]>;
+};
+/**
+ * The TypeScript type for a full row returned by the DB for table `T`.
+ * Every column is present; nullable columns resolve to `T | null`.
+ */
+type RowShape<T extends TableDef> = {
+    [K in keyof T["columns"]]: ColValue<T["columns"][K]>;
+};
+/** A typed table accessor that mirrors the runtime DBClient surface. */
+interface TypedTable<T extends TableDef> {
+    insert(data: InsertShape<T>): Promise<RowShape<T>>;
+    update(id: string, data: Partial<InsertShape<T>>): Promise<RowShape<T>>;
+    delete(id: string): Promise<void>;
+    findById(id: string): Promise<RowShape<T> | null>;
+    findMany(query?: Partial<RowShape<T>>): Promise<RowShape<T>[]>;
+}
+/** A typed DB facade covering all tables declared in schema `S`. */
+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]>;
+    };
+}
+/**
+ * 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.
+ *
+ * `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` 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.
+ */
+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. */
+interface EnvTypedTable<T extends TableTypes> {
+    insert(data: T["insert"]): Promise<T["row"]>;
+    update(id: string, data: Partial<T["insert"]>): Promise<T["row"]>;
+    delete(id: string): Promise<void>;
+    findById(id: string): Promise<T["row"] | null>;
+    findMany(query?: Partial<T["row"]>): Promise<T["row"][]>;
+}
+/** The `tables` map exposed on `Database`/`tx`, keyed by the env `Tables`
+ * interface. When no schema is declared `Tables` is empty, so `tables` is an
+ * empty object — accessing `.tables.foo` is then a compile error (no member). */
+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 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`
+ * and a `transaction` whose callback receives the typed tables.
+ *
+ * `transaction` is declared here (overriding `DBClient["transaction"]`) so the
+ * `tx` the callback receives carries the typed `.tables` API.
+ */
+interface EnvTypedDatabase extends Omit<DBClient, "transaction"> {
+    tables: EnvTables;
+    transaction<T>(fn: (tx: EnvTypedTx) => Promise<T>): Promise<T>;
+}
+
+export { ColumnBuilder as C, type EnvTypedDatabase as E, type InsertShape as I, type OnDeleteAction as O, type RowShape as R, type SchemaDef as S, type TableDef as T, type ColumnDef as a, type ColumnMap as b, type ColumnType as c, type EnvTables as d, type EnvTypedTable as e, type EnvTypedTx as f, type SchemaInput as g, type TypedDB as h, type TypedTable as i, type TypedTx as j, boolean as k, defineSchema as l, enumType as m, integer as n, jsonb as o, makeTypedDB as p, timestamp as q, text as t, uuid as u };