@b9g/zen 0.1.1 → 0.1.3

package/src/impl/table.d.ts

@@ -0,0 +1,961 @@
+/**
+ * Table definition with wrapper-based field extensions.
+ *
+ * Uses wrapper functions instead of .pipe() to avoid Zod internals.
+ * Metadata is extracted once at table() call time.
+ */
+import { z, ZodType, ZodObject, ZodRawShape } from "zod";
+import { type SQLBuiltin } from "./builtins.js";
+import { type SQLTemplate } from "./template.js";
+/**
+ * Validate data using Standard Schema.
+ * All Zod schemas (v3.23+) implement the Standard Schema interface.
+ *
+ * @internal Used by table methods and database operations
+ */
+export declare function validateWithStandardSchema<T = unknown>(schema: ZodObject<any>, data: unknown): T;
+/**
+ * Get database metadata from a schema.
+ *
+ * Metadata is stored under a namespaced key to avoid collisions with user metadata.
+ * Unwraps optional/nullable/default/catch wrappers to find the db metadata.
+ *
+ * @param schema - Zod schema to read metadata from
+ * @returns Database metadata object (empty object if none exists)
+ *
+ * @example
+ * const emailMeta = getDBMeta(emailSchema);
+ * if (emailMeta.unique) {
+ *   console.log("This field has a unique constraint");
+ * }
+ */
+export declare function getDBMeta(schema: ZodType): Record<string, any>;
+/**
+ * Set database metadata on a schema, preserving both user metadata and existing DB metadata.
+ *
+ * **Declarative only**: Metadata is read once at `table()` construction time.
+ * Mutating metadata after a table is defined will NOT affect behavior.
+ *
+ * **Precedence**: Later calls to setDBMeta() override earlier ones (last write wins).
+ * User metadata in the root object is preserved separately from DB metadata.
+ *
+ * @param schema - Zod schema to attach metadata to
+ * @param dbMeta - Database metadata to set (merges with existing DB metadata)
+ * @returns New schema with metadata attached
+ *
+ * @example
+ * // Define custom field wrapper
+ * function hashed<T extends z.ZodString>(schema: T) {
+ *   return setDBMeta(
+ *     schema.transform(password => bcrypt.hashSync(password, 10)),
+ *     { hashed: true }
+ *   );
+ * }
+ *
+ * // User metadata is preserved separately
+ * const email = z.string()
+ *   .email()
+ *   .meta({ label: "Email Address" }); // User metadata
+ * const uniqueEmail = setDBMeta(email, { unique: true }); // DB metadata
+ *
+ * // Both are accessible:
+ * uniqueEmail.meta(); // { label: "Email Address", db: { unique: true } }
+ */
+export declare function setDBMeta<T extends ZodType>(schema: T, dbMeta: Record<string, any>): T;
+export interface FieldDBMeta {
+    primaryKey?: boolean;
+    unique?: boolean;
+    indexed?: boolean;
+    softDelete?: boolean;
+    reference?: {
+        table: Table<any>;
+        field?: string;
+        as: string;
+        onDelete?: "cascade" | "set null" | "restrict";
+    };
+    encode?: (value: any) => any;
+    decode?: (value: any) => any;
+    /** Explicit column type override for DDL generation */
+    columnType?: string;
+    /** Auto-increment flag */
+    autoIncrement?: boolean;
+    /** Value to apply on INSERT */
+    inserted?: {
+        type: "sql" | "symbol" | "function";
+        /** SQL template (for type: "sql") */
+        template?: SQLTemplate;
+        symbol?: SQLBuiltin;
+        fn?: () => unknown;
+    };
+    /** Value to apply on UPDATE only */
+    updated?: {
+        type: "sql" | "symbol" | "function";
+        /** SQL template (for type: "sql") */
+        template?: SQLTemplate;
+        symbol?: SQLBuiltin;
+        fn?: () => unknown;
+    };
+    /** Value to apply on both INSERT and UPDATE */
+    upserted?: {
+        type: "sql" | "symbol" | "function";
+        /** SQL template (for type: "sql") */
+        template?: SQLTemplate;
+        symbol?: SQLBuiltin;
+        fn?: () => unknown;
+    };
+}
+/**
+ * Extend Zod with .db namespace for database-specific methods.
+ *
+ * Call this once at application startup to add the .db namespace to all Zod types:
+ *
+ * @example
+ * import {z} from "zod";
+ * import {extendZod, table} from "@b9g/zen";
+ *
+ * extendZod(z);
+ *
+ * const Users = table("users", {
+ *   id: z.string().uuid().db.primary(),
+ *   email: z.string().email().db.unique(),
+ * });
+ *
+ * @param zodModule - The Zod module to extend (typically `z` from `import {z} from "zod"`)
+ */
+export declare function extendZod(zodModule: typeof z): void;
+export type FieldType = "text" | "textarea" | "email" | "url" | "tel" | "password" | "number" | "integer" | "checkbox" | "select" | "date" | "datetime" | "time" | "json" | "hidden";
+export interface FieldMeta {
+    name: string;
+    type: FieldType;
+    required: boolean;
+    primaryKey?: boolean;
+    unique?: boolean;
+    indexed?: boolean;
+    softDelete?: boolean;
+    reference?: {
+        table: Table;
+        field: string;
+        as: string;
+        onDelete?: "cascade" | "set null" | "restrict";
+    };
+    encode?: (value: any) => any;
+    decode?: (value: any) => any;
+    columnType?: string;
+    autoIncrement?: boolean;
+    inserted?: {
+        type: "sql" | "symbol" | "function";
+        template?: SQLTemplate;
+        symbol?: SQLBuiltin;
+        fn?: () => unknown;
+    };
+    updated?: {
+        type: "sql" | "symbol" | "function";
+        template?: SQLTemplate;
+        symbol?: SQLBuiltin;
+        fn?: () => unknown;
+    };
+    upserted?: {
+        type: "sql" | "symbol" | "function";
+        template?: SQLTemplate;
+        symbol?: SQLBuiltin;
+        fn?: () => unknown;
+    };
+    default?: unknown;
+    maxLength?: number;
+    minLength?: number;
+    min?: number;
+    max?: number;
+    options?: readonly string[];
+    /** Additional user-defined metadata from Zod's .meta() (label, helpText, widget, etc.) */
+    [key: string]: unknown;
+}
+/**
+ * Compound foreign key reference defined at the table level.
+ */
+export interface CompoundReference {
+    /** Local field names that form the foreign key */
+    fields: string[];
+    /** Referenced table */
+    table: Table<any>;
+    /** Referenced field names (must match fields length, defaults to referenced table's fields) */
+    referencedFields?: string[];
+    /** Property name for the resolved reference */
+    as: string;
+    /** Delete behavior */
+    onDelete?: "cascade" | "set null" | "restrict";
+}
+export interface TableOptions<TRow = any, TDerive extends Record<string, (entity: TRow) => unknown> = Record<string, (entity: TRow) => unknown>> {
+    /** Compound indexes */
+    indexes?: string[][];
+    /** Compound unique constraints */
+    unique?: string[][];
+    /** Compound foreign key references */
+    references?: CompoundReference[];
+    /**
+     * Derived properties - client-side transformations of already-fetched data.
+     *
+     * Derived properties:
+     * - Are NOT stored in the database
+     * - ARE part of TypeScript type inference (via Row<T>)
+     * - Are lazy getters (computed on access)
+     * - Are non-enumerable (don't appear in Object.keys() or JSON.stringify())
+     * - Must be pure functions (no I/O, no side effects)
+     * - Only transform data already in the entity
+     *
+     * @example
+     * const Posts = table("posts", schema, {
+     *   derive: {
+     *     titleUpper: (post) => post.title.toUpperCase(),
+     *   }
+     * });
+     *
+     * type Post = Row<typeof Posts>;  // includes titleUpper: string
+     * post.titleUpper  // ✅ Typed as string
+     * JSON.stringify(post)  // ✅ Doesn't include titleUpper (non-enumerable)
+     */
+    derive?: TDerive;
+}
+/**
+ * Infer the derived property types from a TableOptions derive object.
+ */
+export type InferDerived<TDerive> = TDerive extends Record<string, (entity: any) => unknown> ? {
+    [K in keyof TDerive]: TDerive[K] extends (entity: any) => infer R ? R : never;
+} : {};
+declare const TABLE_MARKER: unique symbol;
+declare const TABLE_META: unique symbol;
+/**
+ * Check if a value is a Table object.
+ */
+export declare function isTable(value: unknown): value is Table<any>;
+/** Internal table metadata type */
+export interface TableMeta {
+    primary: string | null;
+    unique: string[];
+    indexed: string[];
+    softDeleteField: string | null;
+    references: ReferenceInfo[];
+    fields: Record<string, FieldDBMeta>;
+    derive?: Record<string, (entity: any) => any>;
+    isPartial?: boolean;
+    isDerived?: boolean;
+    derivedExprs?: DerivedExpr[];
+    derivedFields?: string[];
+    /** True if this table represents a view (read-only, no mutations) */
+    isView?: boolean;
+    /** The base table name this view is derived from */
+    viewOf?: string;
+    /** The active view for soft delete (auto-created when .active is accessed) */
+    activeView?: View<any>;
+}
+/**
+ * Get internal metadata from a Table.
+ * For internal library use only - not part of public API.
+ */
+export declare function getTableMeta(table: Queryable<any>): TableMeta;
+export interface ReferenceInfo {
+    fieldName: string;
+    table: Table<any>;
+    referencedField: string;
+    as: string;
+    reverseAs?: string;
+    onDelete?: "cascade" | "set null" | "restrict";
+}
+/**
+ * Metadata for SQL-derived expressions created via Table.derive().
+ */
+export interface DerivedExpr {
+    /** The field name for this derived column */
+    fieldName: string;
+    /** SQL template for the expression */
+    template: SQLTemplate;
+}
+/**
+ * Set values for updates - schema columns only (excludes derived properties).
+ */
+export type SetValues<T extends Table<any>> = {
+    [K in keyof z.infer<T["schema"]>]?: z.infer<T["schema"]>[K];
+};
+/**
+ * Unwrap Zod wrapper types (optional, nullable, default, catch) at the type level.
+ * Used to extract reference metadata from wrapped schemas.
+ */
+type UnwrapZod<T> = T extends z.ZodOptional<infer U> ? UnwrapZod<U> : T extends z.ZodNullable<infer U> ? UnwrapZod<U> : T extends z.ZodDefault<infer U> ? UnwrapZod<U> : T extends z.ZodCatch<infer U> ? UnwrapZod<U> : T;
+/**
+ * Extract relationship references from a table schema.
+ * Maps relationship aliases (the "as" name) to their target tables.
+ *
+ * @example
+ * const Posts = table("posts", {
+ *   authorId: z.string().db.references(Users, "author"),
+ * });
+ * type PostRefs = RowRefs<typeof Posts["schema"]["shape"]>;
+ * // { author: typeof Users }
+ */
+export type RowRefs<T extends ZodRawShape> = {
+    [K in keyof T as UnwrapZod<T[K]> extends {
+        readonly __refAs: infer As;
+    } ? As extends string ? As : never : never]: UnwrapZod<T[K]> extends {
+        readonly __refTable: infer RefTab extends Table<any, any>;
+    } ? RefTab : never;
+};
+/**
+ * Filter refs to only include those whose backing field is in the picked schema.
+ * Used by pick() to correctly narrow relationship types.
+ */
+type FilterRefs<PickedShape extends ZodRawShape, OriginalRefs extends Record<string, Table<any, any>>> = {
+    [Alias in keyof OriginalRefs as Alias extends keyof RowRefs<PickedShape> ? Alias : never]: OriginalRefs[Alias];
+};
+/**
+ * A relationship jump point for navigating to a referenced table's fields.
+ */
+export interface Relation<TargetTable extends Table<any, any>> {
+    /** Navigate to the target table's fields */
+    fields(): ReturnType<TargetTable["fields"]>;
+    /** Direct access to the referenced table */
+    readonly table: TargetTable;
+}
+/**
+ * The return type of `table.fields()` - combines column fields with relationship navigators.
+ */
+export type TableFields<T extends ZodRawShape, Refs extends Record<string, Table<any, any>>> = {
+    [K in keyof T]: FieldMeta;
+} & {
+    [K in keyof Refs]: Relation<Refs[K]>;
+};
+/**
+ * A partial view of a table created via pick().
+ * Can be used for queries but not for insert().
+ * Check via table.meta.isPartial at runtime.
+ */
+export interface PartialTable<T extends ZodRawShape = ZodRawShape, Refs extends Record<string, Table<any, any>> = {}> extends Table<T, Refs> {
+}
+/**
+ * A table with SQL-derived columns created via derive().
+ * Can be used for queries but not for insert/update.
+ * Check via table.meta.isDerived at runtime.
+ */
+export interface DerivedTable<T extends ZodRawShape = ZodRawShape, Refs extends Record<string, Table<any, any>> = {}> extends Table<T, Refs> {
+}
+export interface Table<T extends ZodRawShape = ZodRawShape, Refs extends Record<string, Table<any>> = {}, _Derived extends Record<string, unknown> = {}> {
+    readonly [TABLE_MARKER]: true;
+    /** @internal Symbol-keyed internal metadata */
+    readonly [TABLE_META]: TableMeta;
+    readonly name: string;
+    readonly schema: ZodObject<T>;
+    readonly indexes: string[][];
+    readonly unique: string[][];
+    readonly compoundReferences: CompoundReference[];
+    /**
+     * @internal Internal table metadata. Use getTableMeta() or table methods instead.
+     */
+    readonly meta: TableMeta;
+    /** Get field metadata for forms/admin, with relationship navigators */
+    fields(): TableFields<T, Refs>;
+    /**
+     * Get the primary key field name.
+     *
+     * @returns The primary key field name, or null if no primary key is defined.
+     *
+     * @example
+     * const pk = Users.primaryKey(); // "id"
+     */
+    primaryKey(): string | null;
+    /**
+     * Fully qualified primary key column as SQL fragment.
+     *
+     * @example
+     * db.all(Posts)`GROUP BY ${Posts.primary}`
+     * // → GROUP BY "posts"."id"
+     */
+    readonly primary: SQLTemplate | null;
+    /** Get all foreign key references */
+    references(): ReferenceInfo[];
+    /**
+     * Generate SQL fragment to check if a row is soft-deleted.
+     *
+     * Returns `"table"."deleted_at" IS NOT NULL` where deleted_at is the field
+     * marked with softDelete().
+     *
+     * @throws Error if table doesn't have a soft delete field
+     *
+     * @example
+     * // Exclude soft-deleted records
+     * db.all(Posts)`WHERE NOT (${Posts.deleted()}) AND published = ${true}`
+     *
+     * // Show only soft-deleted records
+     * db.all(Posts)`WHERE ${Posts.deleted()}`
+     */
+    deleted(): SQLTemplate;
+    /**
+     * Generate safe IN clause with proper parameterization.
+     *
+     * Prevents SQL injection and handles empty arrays correctly.
+     *
+     * @throws Error if field doesn't exist in table
+     *
+     * @example
+     * db.all(Posts)`WHERE ${Posts.in("id", postIds)}`
+     * // Generates: "posts"."id" IN (?, ?, ?)
+     *
+     * // Empty array returns FALSE
+     * db.all(Posts)`WHERE ${Posts.in("id", [])}`
+     * // Generates: 1 = 0
+     */
+    in<K extends keyof z.infer<ZodObject<T>>>(field: K, values: unknown[]): SQLTemplate;
+    /**
+     * Create a partial view of this table with only the specified fields.
+     *
+     * Useful for partial selects - the returned table-like object can be
+     * passed to all(), get(), etc. Cannot be used with insert().
+     *
+     * @example
+     * const PostSummary = Posts.pick('id', 'title', 'authorId');
+     * db.all(PostSummary, Users.pick('id', 'name'))`...`
+     */
+    pick<K extends keyof z.infer<ZodObject<T>>>(...fields: K[]): PartialTable<Pick<T, K & keyof T>, FilterRefs<Pick<T, K & keyof T>, Refs>>;
+    /**
+     * Create a new table with SQL-computed derived columns.
+     *
+     * Returns a tagged template function that parses the SQL expression.
+     * Derived columns are computed in the SELECT clause by the database.
+     * The AS aliases must match the schema field names.
+     *
+     * The returned table cannot be used for insert/update - SELECT only.
+     *
+     * @param derivedSchema - Zod schema for the derived fields
+     * @returns Tagged template function that returns a DerivedTable
+     *
+     * @example
+     * const PostsWithStats = Posts
+     *   .derive('likeCount', z.number())`COUNT(DISTINCT ${Likes.cols.id})`
+     *   .derive('commentCount', z.number())`COUNT(DISTINCT ${Comments.cols.id})`;
+     *
+     * db.all(PostsWithStats, Likes, Comments)`
+     *   LEFT JOIN likes ON ${Likes.cols.postId} = ${Posts.cols.id}
+     *   LEFT JOIN comments ON ${Comments.cols.postId} = ${Posts.cols.id}
+     *   GROUP BY ${Posts.primary}
+     * `
+     */
+    derive<N extends string, V extends z.ZodType>(fieldName: N, fieldType: V): (strings: TemplateStringsArray, ...values: unknown[]) => DerivedTable<T & {
+        [K in N]: V;
+    }, Refs>;
+    /**
+     * Access qualified column names as SQL fragments.
+     *
+     * Each property returns a fragment with the fully qualified, quoted column name.
+     * Useful for JOINs, ORDER BY, GROUP BY, or disambiguating columns.
+     *
+     * @example
+     * db.all(Posts, Users)`
+     *   JOIN users ON ${Users.cols.id} = ${Posts.cols.authorId}
+     *   WHERE ${Posts.cols.published} = ${true}
+     *   ORDER BY ${Posts.cols.createdAt} DESC
+     * `
+     * // → JOIN users ON "users"."id" = "posts"."authorId" WHERE "posts"."published" = ? ORDER BY "posts"."createdAt" DESC
+     */
+    readonly cols: {
+        [K in keyof z.infer<ZodObject<T>>]: SQLTemplate;
+    };
+    /**
+     * Generate assignment fragment for UPDATE SET clauses.
+     *
+     * Column names are quoted but not table-qualified (SQL UPDATE syntax).
+     *
+     * @example
+     * db.exec`
+     *   UPDATE posts SET ${Posts.set({ title: "New Title" })} WHERE id = ${id}
+     * `
+     * // → "title" = ?
+     */
+    set(values: SetValues<Table<T>>): SQLTemplate;
+    /**
+     * Generate the ON condition for a JOIN clause (FK equality).
+     *
+     * Called on the table being joined, with the referencing table as argument.
+     * Looks up foreign keys in the referencing table that point to this table.
+     * Returns just the equality condition; you write the JOIN clause.
+     *
+     * @param referencingTable - The table that has a foreign key to this table
+     * @param alias - Optional relationship alias (the "as" name) to disambiguate
+     *                when multiple FKs point to the same table
+     *
+     * @example
+     * // Single FK - no disambiguation needed
+     * db.all([Posts, Users])`
+     *   JOIN "users" ON ${Users.on(Posts)}
+     *   WHERE ${Posts.where({published: true})}
+     * `
+     * // → JOIN "users" ON "users"."id" = "posts"."authorId" WHERE ...
+     *
+     * @example
+     * // Multiple FKs to same table - use alias to disambiguate
+     * const Posts = table("posts", {
+     *   authorId: z.string().db.references(Users, "author"),
+     *   editorId: z.string().db.references(Users, "editor"),
+     * });
+     * db.all([Posts, Users])`
+     *   JOIN "users" AS "author" ON ${Users.on(Posts, "author")}
+     *   JOIN "users" AS "editor" ON ${Users.on(Posts, "editor")}
+     *   WHERE ...
+     * `
+     * // → JOIN "users" AS "author" ON "users"."id" = "posts"."authorId"
+     * //   JOIN "users" AS "editor" ON "users"."id" = "posts"."editorId" WHERE ...
+     */
+    on(referencingTable: Table<any>, alias?: string): SQLTemplate;
+    /**
+     * Generate column list and value tuples for INSERT statements.
+     *
+     * Columns are inferred from the first row's keys. All rows must have
+     * the same columns. Each row is validated against the table schema.
+     *
+     * @example
+     * db.exec`
+     *   INSERT INTO posts ${Posts.values([
+     *     {id: "1", title: "First"},
+     *     {id: "2", title: "Second"},
+     *   ])}
+     * `
+     * // → INSERT INTO posts (id, title) VALUES (?, ?), (?, ?)
+     */
+    values(rows: Partial<z.infer<ZodObject<T>>>[]): SQLTemplate;
+    /**
+     * Get a view that excludes soft-deleted rows.
+     *
+     * Returns a read-only View named `{table}_active` (e.g., `users_active`)
+     * that filters out rows where the soft delete field is not null.
+     *
+     * The view is read-only - use the base table for mutations.
+     *
+     * @throws Error if table doesn't have a soft delete field
+     *
+     * @example
+     * // Define table with soft delete
+     * const Users = table("users", {
+     *   id: z.string().db.primary(),
+     *   name: z.string(),
+     *   deletedAt: z.date().nullable().db.softDelete(),
+     * });
+     *
+     * // Query only active (non-deleted) users
+     * const activeUsers = await db.all(Users.active)``;
+     *
+     * // JOINs automatically filter deleted rows
+     * await db.all([Posts, Users.active])`
+     *   JOIN "users_active" ON ${Users.active.cols.id} = ${Posts.cols.authorId}
+     * `;
+     *
+     * // Views are read-only
+     * await db.insert(Users.active, {...});  // ✗ Throws error
+     */
+    readonly active: View<T, Refs>;
+}
+/** Internal view metadata */
+export interface ViewMeta {
+    /** The base table this view is derived from */
+    baseTable: Table<any>;
+    /** SQL template for the WHERE clause */
+    whereTemplate: SQLTemplate;
+}
+/**
+ * A database view - a read-only projection of a table with a WHERE clause.
+ *
+ * Views are virtual tables that filter rows from a base table.
+ * They can be queried like tables but do not support mutations.
+ */
+export interface View<T extends ZodRawShape = ZodRawShape, Refs extends Record<string, Table> = Record<string, Table>> {
+    /** The view name */
+    readonly name: string;
+    /** Zod schema for validating rows */
+    readonly schema: ZodObject<T>;
+    /** Internal metadata (for library use) */
+    readonly meta: TableMeta;
+    /** Column reference fragments for SQL templates */
+    readonly cols: {
+        readonly [K in keyof T]: SQLTemplate;
+    };
+    /** Primary key column fragment */
+    readonly primary: SQLTemplate | null;
+    /**
+     * Get field metadata for all columns.
+     * Returns an object mapping column names to their metadata.
+     */
+    fields(): Record<string, FieldMeta>;
+    /**
+     * Get reference metadata for foreign key relationships.
+     * Delegates to the base table's references.
+     */
+    references(): ReferenceInfo[];
+    /**
+     * Get the base table this view is derived from.
+     */
+    readonly baseTable: Table<T, Refs>;
+}
+/**
+ * Check if a value is a View object.
+ */
+export declare function isView(value: unknown): value is View<any>;
+/**
+ * Get internal metadata from a View.
+ * For internal library use only - not part of public API.
+ */
+export declare function getViewMeta(view: View<any>): ViewMeta;
+/**
+ * Define a database view based on a table with a WHERE clause.
+ *
+ * Views are read-only projections of tables. They can be queried
+ * like tables but do not support insert, update, or delete.
+ *
+ * @param name - The full view name (e.g., "active_users")
+ * @param baseTable - The table this view is based on
+ * @returns Tagged template function that accepts the WHERE clause
+ *
+ * @example
+ * const Users = table("users", {
+ *   id: z.string().db.primary(),
+ *   name: z.string(),
+ *   role: z.string(),
+ *   deletedAt: z.date().nullable().db.softDelete(),
+ * });
+ *
+ * // Define views with explicit names
+ * const ActiveUsers = view("active_users", Users)`
+ *   WHERE ${Users.cols.deletedAt} IS NULL
+ * `;
+ *
+ * const AdminUsers = view("admin_users", Users)`
+ *   WHERE ${Users.cols.role} = ${"admin"}
+ * `;
+ *
+ * // Query from view
+ * const admins = await db.all(AdminUsers)``;
+ *
+ * // Views are read-only
+ * await db.insert(AdminUsers, {...});  // ✗ Throws error
+ */
+export declare function view<T extends ZodRawShape, Refs extends Record<string, Table>>(name: string, baseTable: Table<T, Refs>): (strings: TemplateStringsArray, ...values: unknown[]) => View<T, Refs>;
+/**
+ * Define a database table with a Zod schema.
+ *
+ * @example
+ * const users = table("users", {
+ *   id: primary(z.string().uuid()),
+ *   email: unique(z.string().email()),
+ *   name: z.string().max(100),
+ *   role: z.enum(["user", "admin"]).default("user"),
+ * });
+ */
+export declare function table<T extends Record<string, ZodType>, TDerive extends Record<string, (entity: z.infer<ZodObject<T>>) => unknown> = {}>(name: string, shape: T, options?: TableOptions<z.infer<ZodObject<T>>, TDerive>): Table<T, RowRefs<T>, InferDerived<TDerive>>;
+/**
+ * A queryable source - either a Table or a View.
+ * Used for read operations that can accept either type.
+ */
+export type Queryable<T extends ZodRawShape = ZodRawShape, Refs extends Record<string, Table> = Record<string, Table>> = Table<T, Refs> | View<T, Refs>;
+/**
+ * Extract the Derived type parameter from a Table.
+ */
+type GetDerived<T> = T extends Table<any, any, infer D> ? D : {};
+/**
+ * Infer the row type from a table or view (full entity after read).
+ * Includes derived properties if defined.
+ *
+ * @example
+ * const Users = table("users", {...});
+ * type User = Row<typeof Users>;
+ *
+ * // With derived properties:
+ * const Posts = table("posts", {...}, {
+ *   derive: { titleUpper: (p) => p.title.toUpperCase() }
+ * });
+ * type Post = Row<typeof Posts>;  // includes titleUpper: string
+ */
+export type Row<T extends Queryable<any>> = z.infer<T["schema"]> & GetDerived<T>;
+/**
+ * Extract the Refs type parameter from a Table or View.
+ */
+type GetRefs<T extends Queryable<any, any>> = T extends Table<any, infer R> ? R : T extends View<any, infer R> ? R : {};
+/**
+ * Given a primary table/view and a tuple of joined tables/views, build an object type
+ * that maps each matching ref alias to Row<RefTable>.
+ *
+ * For example, if Posts has `{ author: typeof Users }` refs and Users is in JoinedTables,
+ * this produces `{ author: Row<typeof Users> }`.
+ */
+type ResolvedRow<Refs extends Record<string, Table<any, any>>, JoinedTables extends readonly Queryable<any, any>[]> = {
+    [Alias in keyof Refs as Refs[Alias] extends JoinedTables[number] ? Alias : never]: Refs[Alias] extends Queryable<any, any> ? Row<Refs[Alias]> | null : never;
+};
+/**
+ * A row type with resolved relationship properties from joined tables.
+ *
+ * When you query `db.all([Posts, Users])`, this type produces:
+ * `Row<Posts> & { author?: Row<Users> }`
+ *
+ * @example
+ * const posts = await db.all([Posts, Users])`JOIN users ON ...`;
+ * posts[0].author?.name;  // typed as string | undefined
+ */
+export type JoinedRow<PrimaryTable extends Queryable<any, any>, JoinedTables extends readonly Queryable<any, any>[]> = Row<PrimaryTable> & ResolvedRow<GetRefs<PrimaryTable>, JoinedTables>;
+/**
+ * Type guard that evaluates to `never` for partial or derived tables.
+ * Use this to prevent insert/update operations at compile time.
+ *
+ * @example
+ * function insert<T extends Table<any>>(
+ *   table: T & FullTableOnly<T>,
+ *   data: Insert<T>
+ * ): Promise<Row<T>>
+ */
+export type FullTableOnly<T> = T extends {
+    meta: {
+        isPartial: true;
+    };
+} ? never : T extends {
+    meta: {
+        isDerived: true;
+    };
+} ? never : T;
+/**
+ * Infer the insert type (respects defaults and .db.auto() fields).
+ * Returns `never` for partial or derived tables to prevent insert at compile time.
+ *
+ * @example
+ * const Users = table("users", {...});
+ * type NewUser = Insert<typeof Users>;
+ */
+export type Insert<T extends Table<any>> = T extends {
+    meta: {
+        isPartial: true;
+    };
+} ? never : T extends {
+    meta: {
+        isDerived: true;
+    };
+} ? never : z.input<T["schema"]>;
+/**
+ * Infer the update type (all fields optional, excludes primary key and insert-only fields).
+ * Returns `never` for partial or derived tables to prevent update at compile time.
+ *
+ * Note: This is a simplified version that makes all fields optional.
+ * Primary key exclusion and insert-only field exclusion require runtime enforcement.
+ *
+ * @example
+ * const Users = table("users", {...});
+ * type EditUser = Update<typeof Users>;
+ */
+export type Update<T extends Table<any>> = T extends {
+    meta: {
+        isPartial: true;
+    };
+} ? never : T extends {
+    meta: {
+        isDerived: true;
+    };
+} ? never : Partial<z.input<T["schema"]>>;
+/**
+ * Database metadata methods available on Zod schemas.
+ * These methods are added via extendZod() and return the same schema type.
+ */
+export interface ZodDBMethods<Schema extends ZodType> {
+    /**
+     * Mark field as primary key.
+     * @example z.string().uuid().db.primary()
+     */
+    primary(): Schema;
+    /**
+     * Mark field as unique.
+     * @example z.string().email().db.unique()
+     */
+    unique(): Schema;
+    /**
+     * Create an index on this field.
+     * @example z.date().db.index()
+     */
+    index(): Schema;
+    /**
+     * Mark field as soft delete timestamp.
+     * @example z.date().nullable().default(null).db.softDelete()
+     */
+    softDelete(): Schema;
+    /**
+     * Define a foreign key reference with optional reverse relationship.
+     *
+     * @example
+     * // Forward reference only
+     * authorId: z.string().uuid().db.references(Users, "author")
+     *
+     * @example
+     * // With options
+     * authorId: z.string().uuid().db.references(Users, "author", {
+     *   reverseAs: "posts",   // user.posts = Post[]
+     *   ondelete: "cascade",
+     * })
+     */
+    references<RefTable extends Table<any, any>, As extends string, ReverseAs extends string | undefined = undefined>(table: RefTable, as: As, options?: {
+        field?: string;
+        reverseAs?: ReverseAs;
+        onDelete?: "cascade" | "set null" | "restrict";
+    }): Schema & {
+        readonly __refTable: RefTable;
+        readonly __refAs: As;
+        readonly __refReverseAs: ReverseAs;
+    };
+    /**
+     * Encode app values to DB values (for INSERT/UPDATE).
+     * One-way transformation is fine (e.g., password hashing).
+     *
+     * @example
+     * password: z.string().db.encode(hashPassword)
+     *
+     * @example
+     * // Bidirectional: pair with .db.decode()
+     * status: z.enum(["pending", "active"])
+     *   .db.encode(s => statusMap.indexOf(s))
+     *   .db.decode(i => statusMap[i])
+     */
+    encode<TDB>(fn: (app: z.infer<Schema>) => TDB): Schema;
+    /**
+     * Decode DB values to app values (for SELECT).
+     * One-way transformation is fine.
+     *
+     * @example
+     * legacy: z.string().db.decode(deserializeLegacyFormat)
+     */
+    decode<TApp>(fn: (db: any) => TApp): Schema;
+    /**
+     * Shorthand for JSON encoding/decoding.
+     * Stores the value as a JSON string in the database.
+     *
+     * @example
+     * metadata: z.object({theme: z.string()}).db.json()
+     */
+    json(): Schema;
+    /**
+     * Shorthand for CSV encoding/decoding of string arrays.
+     * Stores the array as a comma-separated string in the database.
+     *
+     * @example
+     * tags: z.array(z.string()).db.csv()
+     */
+    csv(): Schema;
+    /**
+     * Specify explicit column type for DDL generation.
+     * Required when using custom encode/decode on objects/arrays
+     * that transform to a different storage type.
+     *
+     * @example
+     * // Store array as CSV instead of JSON
+     * tags: z.array(z.string())
+     *   .db.encode((arr) => arr.join(","))
+     *   .db.decode((str) => str.split(","))
+     *   .db.type("TEXT")
+     */
+    type(columnType: string): Schema;
+    /**
+     * Set a value to apply on INSERT.
+     *
+     * Three forms:
+     * - Tagged template: .db.inserted`CURRENT_TIMESTAMP`
+     * - Symbol: .db.inserted(NOW)
+     * - Function: .db.inserted(() => "draft")
+     *
+     * Field becomes optional for insert.
+     *
+     * **Note:** SQL expressions (tagged templates and symbols) bypass encode/decode
+     * since they're executed by the database, not the application. Use function
+     * form if you need encoding applied.
+     *
+     * **Note:** Interpolated values in tagged templates are parameterized but not
+     * schema-validated. Ensure values are appropriate for the column type.
+     *
+     * @example
+     * createdAt: z.date().db.inserted(NOW)
+     * token: z.string().db.inserted(() => crypto.randomUUID())
+     * slug: z.string().db.inserted`LOWER(name)`
+     */
+    inserted(value: import("./database.js").SQLBuiltin | (() => z.infer<Schema>)): Schema;
+    inserted(strings: TemplateStringsArray, ...values: unknown[]): Schema;
+    /**
+     * Set a value to apply on UPDATE only.
+     *
+     * Same forms as inserted(). See inserted() for notes on codec bypass
+     * and template parameter validation.
+     *
+     * Field becomes optional for update operations.
+     *
+     * @example
+     * modifiedAt: z.date().db.updated(NOW)
+     * lastModified: z.date().db.updated(() => new Date())
+     */
+    updated(value: import("./database.js").SQLBuiltin | (() => z.infer<Schema>)): Schema;
+    updated(strings: TemplateStringsArray, ...values: unknown[]): Schema;
+    /**
+     * Set a value to apply on both INSERT and UPDATE.
+     *
+     * Same forms as inserted(). See inserted() for notes on codec bypass
+     * and template parameter validation.
+     *
+     * Field becomes optional for insert/update.
+     *
+     * @example
+     * updatedAt: z.date().db.upserted(NOW)
+     * lastModified: z.date().db.upserted(() => new Date())
+     */
+    upserted(value: import("./database.js").SQLBuiltin | (() => z.infer<Schema>)): Schema;
+    upserted(strings: TemplateStringsArray, ...values: unknown[]): Schema;
+    /**
+     * Auto-generate value on insert based on field type.
+     *
+     * Type-aware behavior:
+     * - `z.string().uuid()` → generates UUID via `crypto.randomUUID()`
+     * - `z.number().int()` → auto-increment (database-side)
+     * - `z.date()` → current timestamp via NOW
+     *
+     * Field becomes optional for insert.
+     *
+     * @example
+     * id: z.string().uuid().db.primary().db.auto()
+     * // → crypto.randomUUID() on insert
+     *
+     * @example
+     * id: z.number().int().db.primary().db.auto()
+     * // → auto-increment
+     *
+     * @example
+     * createdAt: z.date().db.auto()
+     * // → NOW on insert
+     */
+    auto(): Schema;
+}
+declare module "zod" {
+    interface ZodType<out Output, out Input, out Internals> {
+        readonly db: ZodDBMethods<this>;
+    }
+}
+/**
+ * Infer the database field type from a Zod schema.
+ * Used by encodeData() and decodeData() to determine type-specific handling.
+ *
+ * @param schema - The Zod schema for the field
+ * @returns The field type: "text", "integer", "real", "boolean", "datetime", "json"
+ */
+export declare function inferFieldType(schema: z.ZodTypeAny): string;
+/**
+ * Minimal interface for driver decoding capability.
+ * Defined here to avoid circular imports from database.ts.
+ */
+export interface DriverDecoder {
+    decodeValue?(value: unknown, fieldType: string): unknown;
+}
+/**
+ * Decode database result data into proper JS types using table schema.
+ *
+ * Priority order:
+ * 1. Custom field-level .db.decode() (always wins)
+ * 2. Driver.decodeValue() (dialect-specific)
+ * 3. Auto-decode fallback (JSON.parse, 0/1→boolean, string→Date)
+ *
+ * @param table - The table/view definition
+ * @param data - The raw database row
+ * @param driver - Optional driver for dialect-specific decoding
+ */
+export declare function decodeData<T extends Queryable<any>>(table: T, data: Record<string, unknown> | null, driver?: DriverDecoder): Record<string, unknown> | null;
+export {};