@b9g/zen 0.1.2 → 0.1.3

package/src/impl/database.d.ts

@@ -0,0 +1,495 @@
+/**
+ * Database wrapper - the main API for schema-driven SQL.
+ *
+ * Provides typed queries with entity normalization and reference resolution.
+ * Extends EventTarget for IndexedDB-style migration events.
+ */
+import type { Table, View, Queryable, Row, Insert, FullTableOnly, JoinedRow } from "./table.js";
+import { CURRENT_TIMESTAMP, CURRENT_DATE, CURRENT_TIME, NOW, TODAY, isSQLBuiltin, resolveSQLBuiltin, type SQLBuiltin } from "./builtins.js";
+export { CURRENT_TIMESTAMP, CURRENT_DATE, CURRENT_TIME, NOW, TODAY, isSQLBuiltin, resolveSQLBuiltin, type SQLBuiltin, };
+/**
+ * Encode data for database insert/update operations.
+ * Converts app values → DB values using .db.encode() functions.
+ *
+ * Priority order:
+ * 1. Custom field-level .db.encode() (always wins)
+ * 2. Driver.encodeValue() (dialect-specific)
+ * 3. Auto-encode fallback (JSON.stringify, Date→string)
+ *
+ * @param table - The table definition
+ * @param data - The data to encode
+ * @param driver - Optional driver for dialect-specific encoding
+ */
+export declare function encodeData<T extends Table<any>>(table: T, data: Record<string, unknown>, driver?: Driver): Record<string, unknown>;
+import { decodeData } from "./table.js";
+export { decodeData };
+/**
+ * Database driver interface.
+ *
+ * Drivers own all SQL generation and dialect-specific behavior. They receive
+ * template parts (strings + values) and build SQL with native placeholders.
+ *
+ * This keeps the Database class dialect-agnostic - it only interacts with
+ * drivers through this interface and the `supportsReturning` capability flag.
+ */
+export interface Driver {
+    /**
+     * Execute a query and return all rows.
+     * Driver joins strings with native placeholders (? or $1, $2, ...).
+     */
+    all<T = Record<string, unknown>>(strings: TemplateStringsArray, values: unknown[]): Promise<T[]>;
+    /**
+     * Execute a query and return the first row.
+     */
+    get<T = Record<string, unknown>>(strings: TemplateStringsArray, values: unknown[]): Promise<T | null>;
+    /**
+     * Execute a statement and return the number of affected rows.
+     */
+    run(strings: TemplateStringsArray, values: unknown[]): Promise<number>;
+    /**
+     * Execute a query and return a single value, or null if no rows.
+     */
+    val<T = unknown>(strings: TemplateStringsArray, values: unknown[]): Promise<T | null>;
+    /**
+     * Close the database connection.
+     */
+    close(): Promise<void>;
+    /**
+     * Execute a function within a database transaction.
+     */
+    transaction<T>(fn: (txDriver: Driver) => Promise<T>): Promise<T>;
+    /**
+     * Whether this driver supports RETURNING clause for INSERT/UPDATE.
+     * - SQLite: true
+     * - PostgreSQL: true
+     * - MySQL: false
+     * - MariaDB 10.5+: true
+     */
+    readonly supportsReturning: boolean;
+    /**
+     * Execute a function while holding an exclusive migration lock.
+     */
+    withMigrationLock?<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Encode a JS value for database insertion.
+     * Called for each value before building the SQL query.
+     *
+     * @param value - The JS value to encode
+     * @param fieldType - The field type: "text", "integer", "real", "boolean", "datetime", "json"
+     * @returns The encoded value suitable for this database dialect
+     */
+    encodeValue?(value: unknown, fieldType: string): unknown;
+    /**
+     * Decode a database value to JS.
+     * Called for each column value after query execution.
+     *
+     * @param value - The raw database value
+     * @param fieldType - The field type: "text", "integer", "real", "boolean", "datetime", "json"
+     * @returns The decoded JS value
+     */
+    decodeValue?(value: unknown, fieldType: string): unknown;
+    /**
+     * Ensure a table exists with its columns and indexes.
+     *
+     * **For new tables**: Creates the table with full structure including
+     * primary key, unique constraints, foreign keys, and indexes.
+     *
+     * **For existing tables**: Only performs safe, additive operations:
+     * - Adds missing columns
+     * - Adds missing non-unique indexes
+     *
+     * Throws SchemaDriftError if existing table has missing constraints
+     * (directs user to run ensureConstraints).
+     */
+    ensureTable?<T extends Table<any>>(table: T): Promise<EnsureResult>;
+    /**
+     * Ensure constraints (unique, foreign key) are applied to an existing table.
+     *
+     * Performs preflight checks to detect data violations before applying
+     * constraints. Throws ConstraintPreflightError if violations found.
+     */
+    ensureConstraints?<T extends Table<any>>(table: T): Promise<EnsureResult>;
+    /**
+     * Ensure a view exists in the database.
+     *
+     * Creates the view if it doesn't exist, or replaces it if it does.
+     * The base table must already exist.
+     */
+    ensureView?<T extends View<any>>(view: T): Promise<EnsureResult>;
+    /**
+     * Copy column data for safe rename migrations.
+     *
+     * Executes: UPDATE <table> SET <toField> = <fromField> WHERE <toField> IS NULL
+     *
+     * @param table The table to update
+     * @param fromField Source column (may be legacy/not in schema)
+     * @param toField Destination column (must exist in schema)
+     * @returns Number of rows updated
+     */
+    copyColumn?<T extends Table<any>>(table: T, fromField: string, toField: string): Promise<number>;
+    /** Optional introspection: list columns for a table (name, type, nullability). */
+    getColumns?(tableName: string): Promise<{
+        name: string;
+        type?: string;
+        notnull?: boolean;
+    }[]>;
+}
+/**
+ * Result from ensure operations.
+ */
+export interface EnsureResult {
+    /** Whether any DDL was executed (false = no-op) */
+    applied: boolean;
+}
+/**
+ * Event fired when database version increases during open().
+ *
+ * Similar to IndexedDB's IDBVersionChangeEvent combined with
+ * ServiceWorker's ExtendableEvent (for waitUntil support).
+ *
+ * **Migration model**: Zealot uses monotonic, forward-only versioning:
+ * - Versions are integers that only increase: 1 → 2 → 3 → ...
+ * - Downgrading (e.g., 3 → 2) is NOT supported
+ * - Branching version histories are NOT supported
+ * - Each version should be deployed once and never modified
+ *
+ * **Best practices**:
+ * - Use conditional checks: `if (e.oldVersion < 2) { ... }`
+ * - Prefer additive changes (new columns, indexes) over destructive ones
+ * - Never modify past migrations - add new versions instead
+ * - Keep migrations idempotent when possible (use db.ensureTable())
+ */
+export declare class DatabaseUpgradeEvent extends Event {
+    #private;
+    readonly oldVersion: number;
+    readonly newVersion: number;
+    constructor(type: string, init: {
+        oldVersion: number;
+        newVersion: number;
+    });
+    /**
+     * Extend the event lifetime until the promise settles.
+     * Like ExtendableEvent.waitUntil() from ServiceWorker.
+     */
+    waitUntil(promise: Promise<void>): void;
+    /**
+     * @internal Wait for all waitUntil promises to settle.
+     */
+    _settle(): Promise<void>;
+}
+/**
+ * Tagged template query function that returns normalized entities.
+ */
+export type TaggedQuery<T> = (strings: TemplateStringsArray, ...values: unknown[]) => Promise<T>;
+/**
+ * Transaction context with query methods.
+ *
+ * Provides the same query interface as Database, but bound to a single
+ * connection for the duration of the transaction.
+ */
+export declare class Transaction {
+    #private;
+    constructor(driver: Driver);
+    all<T extends Queryable<any, any>>(table: T): TaggedQuery<Row<T>[]>;
+    all<T extends Queryable<any, any>, Rest extends Queryable<any, any>[]>(tables: [T, ...Rest]): TaggedQuery<JoinedRow<T, [T, ...Rest]>[]>;
+    get<T extends Queryable<any, any>>(table: T, id: string | number): Promise<Row<T> | null>;
+    get<T extends Queryable<any, any>>(table: T): TaggedQuery<Row<T> | null>;
+    get<T extends Queryable<any, any>, Rest extends Queryable<any, any>[]>(tables: [T, ...Rest]): TaggedQuery<JoinedRow<T, [T, ...Rest]> | null>;
+    insert<T extends Table<any>>(table: T & FullTableOnly<T>, data: Insert<T>): Promise<Row<T>>;
+    insert<T extends Table<any>>(table: T & FullTableOnly<T>, data: Insert<T>[]): Promise<Row<T>[]>;
+    update<T extends Table<any>>(table: T & FullTableOnly<T>, data: Partial<Insert<T>>, id: string | number): Promise<Row<T> | null>;
+    update<T extends Table<any>>(table: T & FullTableOnly<T>, data: Partial<Insert<T>>, ids: (string | number)[]): Promise<(Row<T> | null)[]>;
+    update<T extends Table<any>>(table: T & FullTableOnly<T>, data: Partial<Insert<T>>): TaggedQuery<Row<T>[]>;
+    delete<T extends Table<any>>(table: T, id: string | number): Promise<number>;
+    delete<T extends Table<any>>(table: T, ids: (string | number)[]): Promise<number>;
+    delete<T extends Table<any>>(table: T): TaggedQuery<number>;
+    softDelete<T extends Table<any>>(table: T, id: string | number): Promise<number>;
+    softDelete<T extends Table<any>>(table: T, ids: (string | number)[]): Promise<number>;
+    softDelete<T extends Table<any>>(table: T): TaggedQuery<number>;
+    query<T = Record<string, unknown>>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T[]>;
+    exec(strings: TemplateStringsArray, ...values: unknown[]): Promise<number>;
+    val<T>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T | null>;
+    /**
+     * Print the generated SQL and parameters without executing.
+     * Useful for debugging query composition and fragment expansion.
+     * Note: SQL shown uses ? placeholders; actual query may use $1, $2 etc.
+     */
+    print(strings: TemplateStringsArray, ...values: unknown[]): {
+        sql: string;
+        params: unknown[];
+    };
+}
+/**
+ * Database wrapper with typed queries and entity normalization.
+ * Extends EventTarget for IndexedDB-style "upgradeneeded" events.
+ *
+ * @example
+ * const db = new Database(driver);
+ *
+ * db.addEventListener("upgradeneeded", (e) => {
+ *   e.waitUntil(runMigrations(e));
+ * });
+ *
+ * await db.open(2);
+ */
+export declare class Database extends EventTarget {
+    #private;
+    constructor(driver: Driver, options?: {
+        tables?: Table<any>[];
+    });
+    /**
+     * Current database schema version.
+     * Returns 0 if database has never been opened.
+     */
+    get version(): number;
+    /**
+     * Open the database at a specific version.
+     *
+     * If the requested version is higher than the current version,
+     * fires an "upgradeneeded" event and waits for all waitUntil()
+     * promises before completing.
+     *
+     * Migration safety: Uses exclusive locking to prevent race conditions
+     * when multiple processes attempt migrations simultaneously.
+     *
+     * @example
+     * db.addEventListener("upgradeneeded", (e) => {
+     *   e.waitUntil(runMigrations(e));
+     * });
+     * await db.open(2);
+     */
+    open(version: number): Promise<void>;
+    /**
+     * Query multiple entities with joins and reference resolution.
+     *
+     * @example
+     * // Single table
+     * const posts = await db.all(Posts)`WHERE published = ${true}`;
+     *
+     * // Multi-table with joins (typed!)
+     * const posts = await db.all([Posts, Users])`
+     *   JOIN users ON users.id = posts.author_id
+     *   WHERE published = ${true}
+     * `;
+     * posts[0].author.name  // typed as string!
+     */
+    all<T extends Queryable<any, any>>(table: T): TaggedQuery<Row<T>[]>;
+    all<T extends Queryable<any, any>, Rest extends Queryable<any, any>[]>(tables: [T, ...Rest]): TaggedQuery<JoinedRow<T, [T, ...Rest]>[]>;
+    /**
+     * Query a single entity.
+     *
+     * @example
+     * // By primary key
+     * const post = await db.get(Posts, postId);
+     *
+     * // With query
+     * const post = await db.get(Posts)`WHERE slug = ${slug}`;
+     *
+     * // Multi-table (typed!)
+     * const post = await db.get([Posts, Users])`
+     *   JOIN users ON users.id = posts.author_id
+     *   WHERE posts.id = ${postId}
+     * `;
+     * post?.author.name  // typed as string!
+     */
+    get<T extends Queryable<any, any>>(table: T, id: string | number): Promise<Row<T> | null>;
+    get<T extends Queryable<any, any>>(table: T): TaggedQuery<Row<T> | null>;
+    get<T extends Queryable<any, any>, Rest extends Queryable<any, any>[]>(tables: [T, ...Rest]): TaggedQuery<JoinedRow<T, [T, ...Rest]> | null>;
+    /**
+     * Insert one or more entities.
+     *
+     * Uses RETURNING to get the actual inserted row(s) (with DB defaults).
+     *
+     * @example
+     * // Single insert
+     * const user = await db.insert(Users, {
+     *   id: crypto.randomUUID(),
+     *   email: "alice@example.com",
+     *   name: "Alice",
+     * });
+     *
+     * // Bulk insert
+     * const users = await db.insert(Users, [
+     *   { id: "1", email: "alice@example.com", name: "Alice" },
+     *   { id: "2", email: "bob@example.com", name: "Bob" },
+     * ]);
+     */
+    insert<T extends Table<any>>(table: T & FullTableOnly<T>, data: Insert<T>): Promise<Row<T>>;
+    insert<T extends Table<any>>(table: T & FullTableOnly<T>, data: Insert<T>[]): Promise<Row<T>[]>;
+    /**
+     * Update entities.
+     *
+     * @example
+     * // Update by primary key
+     * const user = await db.update(Users, { name: "Bob" }, userId);
+     *
+     * // Update multiple by primary keys
+     * const users = await db.update(Users, { active: true }, [id1, id2, id3]);
+     *
+     * // Update with custom WHERE clause
+     * const count = await db.update(Users, { active: false })`WHERE lastLogin < ${cutoff}`;
+     */
+    update<T extends Table<any>>(table: T & FullTableOnly<T>, data: Partial<Insert<T>>, id: string | number): Promise<Row<T> | null>;
+    update<T extends Table<any>>(table: T & FullTableOnly<T>, data: Partial<Insert<T>>, ids: (string | number)[]): Promise<(Row<T> | null)[]>;
+    update<T extends Table<any>>(table: T & FullTableOnly<T>, data: Partial<Insert<T>>): TaggedQuery<Row<T>[]>;
+    /**
+     * Delete entities.
+     *
+     * @example
+     * // Delete by primary key (returns 0 or 1)
+     * const count = await db.delete(Users, userId);
+     *
+     * // Delete multiple by primary keys
+     * const count = await db.delete(Users, [id1, id2, id3]);
+     *
+     * // Delete with custom WHERE clause
+     * const count = await db.delete(Users)`WHERE inactive = ${true}`;
+     */
+    delete<T extends Table<any>>(table: T, id: string | number): Promise<number>;
+    delete<T extends Table<any>>(table: T, ids: (string | number)[]): Promise<number>;
+    delete<T extends Table<any>>(table: T): TaggedQuery<number>;
+    /**
+     * Soft delete entities by marking the soft delete field with the current timestamp.
+     *
+     * @example
+     * // Soft delete by primary key (returns 0 or 1)
+     * const count = await db.softDelete(Users, userId);
+     *
+     * // Soft delete multiple by primary keys
+     * const count = await db.softDelete(Users, [id1, id2, id3]);
+     *
+     * // Soft delete with custom WHERE clause
+     * const count = await db.softDelete(Users)`WHERE inactive = ${true}`;
+     */
+    softDelete<T extends Table<any>>(table: T, id: string | number): Promise<number>;
+    softDelete<T extends Table<any>>(table: T, ids: (string | number)[]): Promise<number>;
+    softDelete<T extends Table<any>>(table: T): TaggedQuery<number>;
+    /**
+     * Execute a raw query and return rows.
+     *
+     * @example
+     * const counts = await db.query<{ count: number }>`
+     *   SELECT COUNT(*) as count FROM posts WHERE author_id = ${userId}
+     * `;
+     */
+    query<T = Record<string, unknown>>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T[]>;
+    /**
+     * Execute a statement (INSERT, UPDATE, DELETE, DDL).
+     *
+     * @example
+     * await db.exec`CREATE TABLE IF NOT EXISTS users (id TEXT PRIMARY KEY)`;
+     */
+    exec(strings: TemplateStringsArray, ...values: unknown[]): Promise<number>;
+    /**
+     * Execute a query and return a single value.
+     *
+     * @example
+     * const count = await db.val<number>`SELECT COUNT(*) FROM posts`;
+     */
+    val<T>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T | null>;
+    /**
+     * Print the generated SQL and parameters without executing.
+     * Useful for debugging query composition and fragment expansion.
+     * Note: SQL shown uses ? placeholders; actual query may use $1, $2 etc.
+     */
+    print(strings: TemplateStringsArray, ...values: unknown[]): {
+        sql: string;
+        params: unknown[];
+    };
+    /**
+     * Ensure a table exists with its columns and indexes.
+     *
+     * **For new tables**: Creates the table with full structure including
+     * primary key, unique constraints, foreign keys, and indexes.
+     *
+     * **For existing tables**: Only performs safe, additive operations:
+     * - Adds missing columns
+     * - Adds missing non-unique indexes
+     *
+     * Unique constraints and foreign keys on existing tables require
+     * explicit `ensureConstraints()` call (they can fail or lock).
+     *
+     * @throws {EnsureError} If DDL execution fails
+     * @throws {SchemaDriftError} If existing table has missing constraints
+     *   (directs user to run ensureConstraints)
+     *
+     * @example
+     * // In migration handler
+     * await db.ensureTable(Users);
+     * await db.ensureTable(Posts); // FK to Users - ensure Users first
+     */
+    ensureTable<T extends Table<any>>(table: T): Promise<EnsureResult>;
+    /**
+     * Ensure a view exists in the database.
+     *
+     * Creates the view if it doesn't exist, or replaces it if it does.
+     * The base table must already exist.
+     *
+     * @example
+     * const ActiveUsers = view("active_users", Users)`WHERE ${Users.cols.deletedAt} IS NULL`;
+     * await db.ensureTable(Users);
+     * await db.ensureView(ActiveUsers);
+     */
+    ensureView<T extends View<any>>(viewObj: T): Promise<EnsureResult>;
+    /**
+     * Ensure constraints (unique, foreign key) are applied to an existing table.
+     *
+     * **WARNING**: This operation can be expensive and cause locks on large tables.
+     * It performs preflight checks to detect data violations before applying constraints.
+     *
+     * For each declared constraint:
+     * 1. Preflight: Check for violations (duplicates for UNIQUE, orphans for FK)
+     * 2. If violations found: Throw ConstraintPreflightError with diagnostic query
+     * 3. If clean: Apply the constraint
+     *
+     * @throws {Error} If table doesn't exist
+     * @throws {ConstraintPreflightError} If data violates a constraint
+     * @throws {EnsureError} If DDL execution fails
+     *
+     * @example
+     * // After ensuring table structure
+     * await db.ensureTable(Users);
+     * // Explicitly apply constraints (may lock, may fail)
+     * await db.ensureConstraints(Users);
+     */
+    ensureConstraints<T extends Table<any>>(table: T): Promise<EnsureResult>;
+    /**
+     * Copy column data for safe rename migrations.
+     *
+     * Executes: UPDATE <table> SET <toField> = <fromField> WHERE <toField> IS NULL
+     *
+     * This is idempotent - rows where toField already has a value are skipped.
+     * The fromField may be a legacy column not in the current schema.
+     *
+     * @param table The table to update
+     * @param fromField Source column (may be legacy/not in schema)
+     * @param toField Destination column (must exist in schema)
+     * @returns Number of rows updated
+     *
+     * @example
+     * // Rename "email" to "emailAddress":
+     * // 1. Add new column
+     * await db.ensureTable(UsersWithEmailAddress);
+     * // 2. Copy data
+     * const updated = await db.copyColumn(Users, "email", "emailAddress");
+     * // 3. Later: remove old column (manual migration)
+     */
+    copyColumn<T extends Table<any>>(table: T, fromField: string, toField: string): Promise<number>;
+    /**
+     * Execute a function within a database transaction.
+     *
+     * If the function completes successfully, the transaction is committed.
+     * If the function throws an error, the transaction is rolled back.
+     *
+     * All operations within the transaction callback use the same database
+     * connection, ensuring transactional consistency.
+     *
+     * @example
+     * await db.transaction(async (tx) => {
+     *   const user = await tx.insert(users, { id: "1", name: "Alice" });
+     *   await tx.insert(posts, { id: "1", authorId: user.id, title: "Hello" });
+     *   // If any insert fails, both are rolled back
+     * });
+     */
+    transaction<T>(fn: (tx: Transaction) => Promise<T>): Promise<T>;
+}

package/src/impl/ddl.d.ts

@@ -0,0 +1,34 @@
+/**
+ * DDL generation from table definitions.
+ *
+ * Generates CREATE TABLE statements for SQLite, PostgreSQL, and MySQL.
+ * Uses only Zod's public APIs - no _def access.
+ */
+import { z } from "zod";
+import type { Table, View } from "./table.js";
+import { type SQLTemplate } from "./template.js";
+export type SQLDialect = "sqlite" | "postgresql" | "mysql";
+export interface DDLOptions {
+    dialect?: SQLDialect;
+    ifNotExists?: boolean;
+}
+/**
+ * Generate a single column definition as a template with ident markers.
+ * @internal Used by driver ensureTable implementations.
+ */
+export declare function generateColumnDDL(fieldName: string, zodType: z.ZodType, fieldMeta: Record<string, any>, dialect?: SQLDialect): SQLTemplate;
+/**
+ * Generate CREATE TABLE DDL as a template with ident markers.
+ * Pass to driver.run() to execute, or use renderDDL() in tests.
+ */
+export declare function generateDDL<T extends Table<any>>(table: T, options?: DDLOptions): SQLTemplate;
+/**
+ * Generate CREATE VIEW DDL as a template.
+ *
+ * For views, the DDL is:
+ * DROP VIEW IF EXISTS "view_name";
+ * CREATE VIEW "view_name" AS SELECT * FROM "base_table" WHERE ...;
+ *
+ * Note: We use DROP + CREATE because SQLite doesn't support CREATE OR REPLACE VIEW.
+ */
+export declare function generateViewDDL<T extends View<any>>(viewObj: T, _options?: DDLOptions): SQLTemplate;