@b9g/zen 0.1.0

package/src/postgres.js

@@ -0,0 +1,555 @@
+/// <reference types="./postgres.d.ts" />
+import {
+  quoteIdent,
+  renderDDL
+} from "../chunk-2IEEEMRN.js";
+import {
+  generateColumnDDL,
+  generateDDL
+} from "../chunk-QXGEP5PB.js";
+import {
+  ConstraintPreflightError,
+  EnsureError,
+  SchemaDriftError,
+  getTableMeta,
+  resolveSQLBuiltin
+} from "../chunk-56M5Z3A6.js";
+
+// src/postgres.ts
+import {
+  ConstraintViolationError,
+  isSQLBuiltin,
+  isSQLIdentifier
+} from "./zen.js";
+import postgres from "postgres";
+var DIALECT = "postgresql";
+function quoteIdent2(name) {
+  return quoteIdent(name, DIALECT);
+}
+function buildSQL(strings, values) {
+  let sql = strings[0];
+  const params = [];
+  let paramIndex = 1;
+  for (let i = 0; i < values.length; i++) {
+    const value = values[i];
+    if (isSQLBuiltin(value)) {
+      sql += resolveSQLBuiltin(value) + strings[i + 1];
+    } else if (isSQLIdentifier(value)) {
+      sql += quoteIdent2(value.name) + strings[i + 1];
+    } else {
+      sql += `$${paramIndex++}` + strings[i + 1];
+      params.push(value);
+    }
+  }
+  return { sql, params };
+}
+var PostgresDriver = class {
+  supportsReturning = true;
+  #sql;
+  constructor(url, options = {}) {
+    this.#sql = postgres(url, {
+      max: options.max ?? 10,
+      idle_timeout: options.idleTimeout ?? 30,
+      connect_timeout: options.connectTimeout ?? 30
+    });
+  }
+  /**
+   * Convert PostgreSQL errors to Zealot errors.
+   */
+  #handleError(error) {
+    if (error && typeof error === "object" && "code" in error) {
+      const code = error.code;
+      const message = error.message || String(error);
+      const constraint = error.constraint_name || error.constraint;
+      const table = error.table_name || error.table;
+      const column = error.column_name || error.column;
+      let kind = "unknown";
+      if (code === "23505")
+        kind = "unique";
+      else if (code === "23503")
+        kind = "foreign_key";
+      else if (code === "23514")
+        kind = "check";
+      else if (code === "23502")
+        kind = "not_null";
+      if (kind !== "unknown") {
+        throw new ConstraintViolationError(
+          message,
+          {
+            kind,
+            constraint,
+            table,
+            column
+          },
+          {
+            cause: error
+          }
+        );
+      }
+    }
+    throw error;
+  }
+  async all(strings, values) {
+    try {
+      const { sql, params } = buildSQL(strings, values);
+      const result = await this.#sql.unsafe(sql, params);
+      return result;
+    } catch (error) {
+      return this.#handleError(error);
+    }
+  }
+  async get(strings, values) {
+    try {
+      const { sql, params } = buildSQL(strings, values);
+      const result = await this.#sql.unsafe(sql, params);
+      return result[0] ?? null;
+    } catch (error) {
+      return this.#handleError(error);
+    }
+  }
+  async run(strings, values) {
+    try {
+      const { sql, params } = buildSQL(strings, values);
+      const result = await this.#sql.unsafe(sql, params);
+      return result.count;
+    } catch (error) {
+      return this.#handleError(error);
+    }
+  }
+  async val(strings, values) {
+    try {
+      const { sql, params } = buildSQL(strings, values);
+      const result = await this.#sql.unsafe(sql, params);
+      const row = result[0];
+      if (!row)
+        return null;
+      const rowValues = Object.values(row);
+      return rowValues[0];
+    } catch (error) {
+      return this.#handleError(error);
+    }
+  }
+  async close() {
+    await this.#sql.end();
+  }
+  async transaction(fn) {
+    const handleError = this.#handleError.bind(this);
+    const result = await this.#sql.begin(async (txSql) => {
+      const txDriver = {
+        supportsReturning: true,
+        all: async (strings, values) => {
+          try {
+            const { sql, params } = buildSQL(strings, values);
+            const result2 = await txSql.unsafe(sql, params);
+            return result2;
+          } catch (error) {
+            return handleError(error);
+          }
+        },
+        get: async (strings, values) => {
+          try {
+            const { sql, params } = buildSQL(strings, values);
+            const result2 = await txSql.unsafe(sql, params);
+            return result2[0] ?? null;
+          } catch (error) {
+            return handleError(error);
+          }
+        },
+        run: async (strings, values) => {
+          try {
+            const { sql, params } = buildSQL(strings, values);
+            const result2 = await txSql.unsafe(sql, params);
+            return result2.count;
+          } catch (error) {
+            return handleError(error);
+          }
+        },
+        val: async (strings, values) => {
+          try {
+            const { sql, params } = buildSQL(strings, values);
+            const result2 = await txSql.unsafe(sql, params);
+            const row = result2[0];
+            if (!row)
+              return null;
+            const rowValues = Object.values(row);
+            return rowValues[0];
+          } catch (error) {
+            return handleError(error);
+          }
+        },
+        close: async () => {
+        },
+        transaction: async () => {
+          throw new Error("Nested transactions are not supported");
+        }
+      };
+      return await fn(txDriver);
+    });
+    return result;
+  }
+  async withMigrationLock(fn) {
+    const MIGRATION_LOCK_ID = 1952393421;
+    await this.#sql`SELECT pg_advisory_lock(${MIGRATION_LOCK_ID})`;
+    try {
+      return await fn();
+    } finally {
+      await this.#sql`SELECT pg_advisory_unlock(${MIGRATION_LOCK_ID})`;
+    }
+  }
+  // ========================================================================
+  // Schema Management Methods
+  // ========================================================================
+  /**
+   * Ensure table exists with the specified structure.
+   * Creates table if missing, adds missing columns/indexes.
+   * Throws SchemaDriftError if constraints are missing.
+   */
+  async ensureTable(table) {
+    const tableName = table.name;
+    let step = 0;
+    let applied = false;
+    try {
+      const exists = await this.#tableExists(tableName);
+      if (!exists) {
+        step = 1;
+        const ddlTemplate = generateDDL(table, { dialect: DIALECT });
+        const ddlSQL = renderDDL(ddlTemplate[0], ddlTemplate.slice(1), DIALECT);
+        for (const stmt of ddlSQL.split(";").filter((s) => s.trim())) {
+          await this.#sql.unsafe(stmt.trim());
+        }
+        applied = true;
+      } else {
+        step = 2;
+        const columnsApplied = await this.#ensureMissingColumns(table);
+        applied = applied || columnsApplied;
+        step = 3;
+        const indexesApplied = await this.#ensureMissingIndexes(table);
+        applied = applied || indexesApplied;
+        step = 4;
+        await this.#checkMissingConstraints(table);
+      }
+      return { applied };
+    } catch (error) {
+      if (error instanceof SchemaDriftError || error instanceof ConstraintPreflightError) {
+        throw error;
+      }
+      throw new EnsureError(
+        `Failed to ensure table "${tableName}" exists (step ${step})`,
+        {
+          operation: "ensureTable",
+          table: tableName,
+          step
+        },
+        {
+          cause: error
+        }
+      );
+    }
+  }
+  /**
+   * Ensure constraints exist on the table.
+   * Applies unique and foreign key constraints with preflight checks.
+   */
+  async ensureConstraints(table) {
+    const tableName = table.name;
+    let step = 0;
+    let applied = false;
+    try {
+      step = 1;
+      const existingConstraints = await this.#getConstraints(tableName);
+      step = 2;
+      const uniqueApplied = await this.#ensureUniqueConstraints(
+        table,
+        existingConstraints
+      );
+      applied = applied || uniqueApplied;
+      step = 3;
+      const fkApplied = await this.#ensureForeignKeys(
+        table,
+        existingConstraints
+      );
+      applied = applied || fkApplied;
+      return { applied };
+    } catch (error) {
+      if (error instanceof SchemaDriftError || error instanceof ConstraintPreflightError) {
+        throw error;
+      }
+      throw new EnsureError(
+        `Failed to ensure constraints on table "${tableName}" (step ${step})`,
+        {
+          operation: "ensureConstraints",
+          table: tableName,
+          step
+        },
+        {
+          cause: error
+        }
+      );
+    }
+  }
+  // ========================================================================
+  // Private Helper Methods
+  // ========================================================================
+  async #tableExists(tableName) {
+    const result = await this.#sql`
+			SELECT EXISTS (
+				SELECT FROM information_schema.tables
+				WHERE table_schema = 'public'
+				AND table_name = ${tableName}
+			) as exists
+		`;
+    return result[0]?.exists ?? false;
+  }
+  async #getColumns(tableName) {
+    const result = await this.#sql`
+			SELECT column_name, data_type, is_nullable
+			FROM information_schema.columns
+			WHERE table_schema = 'public'
+			AND table_name = ${tableName}
+			ORDER BY ordinal_position
+		`;
+    return result.map((row) => ({
+      name: row.column_name,
+      type: row.data_type,
+      notnull: row.is_nullable === "NO"
+    }));
+  }
+  async #getIndexes(tableName) {
+    const result = await this.#sql`
+			SELECT indexname, indexdef
+			FROM pg_indexes
+			WHERE schemaname = 'public'
+			AND tablename = ${tableName}
+		`;
+    return result.map((row) => {
+      const match = row.indexdef.match(/\((.*?)\)/);
+      const columns = match ? match[1].split(",").map((c) => c.trim().replace(/"/g, "")) : [];
+      const unique = row.indexdef.includes("UNIQUE INDEX");
+      return {
+        name: row.indexname,
+        columns,
+        unique
+      };
+    });
+  }
+  async #getConstraints(tableName) {
+    const result = await this.#sql`
+			SELECT
+				tc.constraint_name,
+				tc.constraint_type,
+				array_agg(kcu.column_name ORDER BY kcu.ordinal_position)::text as column_names,
+				ccu.table_name as foreign_table_name,
+				array_agg(ccu.column_name ORDER BY kcu.ordinal_position)::text as foreign_column_names
+			FROM information_schema.table_constraints tc
+			LEFT JOIN information_schema.key_column_usage kcu
+				ON tc.constraint_name = kcu.constraint_name
+				AND tc.table_schema = kcu.table_schema
+			LEFT JOIN information_schema.constraint_column_usage ccu
+				ON tc.constraint_name = ccu.constraint_name
+				AND tc.table_schema = ccu.table_schema
+			WHERE tc.table_schema = 'public'
+			AND tc.table_name = ${tableName}
+			GROUP BY tc.constraint_name, tc.constraint_type, ccu.table_name
+		`;
+    return result.map((row) => {
+      let type;
+      if (row.constraint_type === "UNIQUE")
+        type = "unique";
+      else if (row.constraint_type === "FOREIGN KEY")
+        type = "foreign_key";
+      else if (row.constraint_type === "PRIMARY KEY")
+        type = "primary_key";
+      else
+        type = "check";
+      const parseArray = (str) => {
+        if (!str)
+          return [];
+        const match = str.match(/^\{(.*)\}$/);
+        return match ? match[1].split(",").map((s) => s.trim()) : [];
+      };
+      return {
+        name: row.constraint_name,
+        type,
+        columns: parseArray(row.column_names),
+        referencedTable: row.foreign_table_name ?? void 0,
+        referencedColumns: row.foreign_column_names ? parseArray(row.foreign_column_names) : void 0
+      };
+    });
+  }
+  async #ensureMissingColumns(table) {
+    const existingCols = await this.#getColumns(table.name);
+    const existingColNames = new Set(existingCols.map((c) => c.name));
+    const schemaFields = Object.keys(table.schema.shape);
+    let applied = false;
+    for (const fieldName of schemaFields) {
+      if (!existingColNames.has(fieldName)) {
+        await this.#addColumn(table, fieldName);
+        applied = true;
+      }
+    }
+    return applied;
+  }
+  async #addColumn(table, fieldName) {
+    const zodType = table.schema.shape[fieldName];
+    const fieldMeta = getTableMeta(table).fields[fieldName] || {};
+    const colTemplate = generateColumnDDL(
+      fieldName,
+      zodType,
+      fieldMeta,
+      DIALECT
+    );
+    const colSQL = renderDDL(colTemplate[0], colTemplate.slice(1), DIALECT);
+    await this.#sql.unsafe(
+      `ALTER TABLE ${quoteIdent2(table.name)} ADD COLUMN IF NOT EXISTS ${colSQL}`
+    );
+  }
+  async #ensureMissingIndexes(table) {
+    const existingIndexes = await this.#getIndexes(table.name);
+    const existingIndexNames = new Set(existingIndexes.map((idx) => idx.name));
+    const meta = getTableMeta(table);
+    let applied = false;
+    for (const fieldName of meta.indexed) {
+      const indexName = `idx_${table.name}_${fieldName}`;
+      if (!existingIndexNames.has(indexName)) {
+        await this.#createIndex(table.name, [fieldName], false);
+        applied = true;
+      }
+    }
+    for (const indexCols of table.indexes) {
+      const indexName = `idx_${table.name}_${indexCols.join("_")}`;
+      if (!existingIndexNames.has(indexName)) {
+        await this.#createIndex(table.name, indexCols, false);
+        applied = true;
+      }
+    }
+    return applied;
+  }
+  async #createIndex(tableName, columns, unique) {
+    const prefix = unique ? "uniq" : "idx";
+    const indexName = `${prefix}_${tableName}_${columns.join("_")}`;
+    const uniqueClause = unique ? "UNIQUE " : "";
+    const columnList = columns.map(quoteIdent2).join(", ");
+    const sql = `CREATE ${uniqueClause}INDEX IF NOT EXISTS ${quoteIdent2(indexName)} ON ${quoteIdent2(tableName)} (${columnList})`;
+    await this.#sql.unsafe(sql);
+    return indexName;
+  }
+  async #checkMissingConstraints(table) {
+    const existingConstraints = await this.#getConstraints(table.name);
+    const meta = getTableMeta(table);
+    for (const fieldName of Object.keys(meta.fields)) {
+      const fieldMeta = meta.fields[fieldName];
+      if (fieldMeta.unique) {
+        const hasConstraint = existingConstraints.some(
+          (c) => c.type === "unique" && c.columns.length === 1 && c.columns[0] === fieldName
+        );
+        if (!hasConstraint) {
+          throw new SchemaDriftError(
+            `Table "${table.name}" is missing UNIQUE constraint on column "${fieldName}"`,
+            {
+              table: table.name,
+              drift: `missing unique:${fieldName}`,
+              suggestion: `Run ensureConstraints() to apply constraints`
+            }
+          );
+        }
+      }
+    }
+    for (const ref of meta.references) {
+      const hasFK = existingConstraints.some(
+        (c) => c.type === "foreign_key" && c.columns.length === 1 && c.columns[0] === ref.fieldName && c.referencedTable === ref.table.name && c.referencedColumns?.[0] === ref.referencedField
+      );
+      if (!hasFK) {
+        throw new SchemaDriftError(
+          `Table "${table.name}" is missing FOREIGN KEY constraint on column "${ref.fieldName}"`,
+          {
+            table: table.name,
+            drift: `missing foreign_key:${ref.fieldName}->${ref.table.name}.${ref.referencedField}`,
+            suggestion: `Run ensureConstraints() to apply constraints`
+          }
+        );
+      }
+    }
+  }
+  async #ensureUniqueConstraints(table, existingConstraints) {
+    const meta = getTableMeta(table);
+    let applied = false;
+    for (const fieldName of Object.keys(meta.fields)) {
+      const fieldMeta = meta.fields[fieldName];
+      if (fieldMeta.unique) {
+        const hasConstraint = existingConstraints.some(
+          (c) => c.type === "unique" && c.columns.includes(fieldName)
+        );
+        if (!hasConstraint) {
+          await this.#preflightUnique(table.name, [fieldName]);
+          await this.#createIndex(table.name, [fieldName], true);
+          applied = true;
+        }
+      }
+    }
+    return applied;
+  }
+  async #ensureForeignKeys(table, existingConstraints) {
+    const meta = getTableMeta(table);
+    let applied = false;
+    for (const ref of meta.references) {
+      const hasFK = existingConstraints.some(
+        (c) => c.type === "foreign_key" && c.columns.length === 1 && c.columns[0] === ref.fieldName && c.referencedTable === ref.table.name && c.referencedColumns?.[0] === ref.referencedField
+      );
+      if (!hasFK) {
+        await this.#preflightForeignKey(
+          table.name,
+          ref.fieldName,
+          ref.table.name,
+          ref.referencedField
+        );
+        const constraintName = `fk_${table.name}_${ref.fieldName}`;
+        const onDelete = ref.onDelete ? ` ON DELETE ${ref.onDelete.toUpperCase()}` : "";
+        await this.#sql.unsafe(
+          `ALTER TABLE ${quoteIdent2(table.name)} ADD CONSTRAINT ${quoteIdent2(constraintName)} FOREIGN KEY (${quoteIdent2(ref.fieldName)}) REFERENCES ${quoteIdent2(ref.table.name)} (${quoteIdent2(ref.referencedField)})${onDelete}`
+        );
+        applied = true;
+      }
+    }
+    return applied;
+  }
+  async #preflightUnique(tableName, columns) {
+    const columnList = columns.map(quoteIdent2).join(", ");
+    const result = await this.#sql.unsafe(
+      `SELECT COUNT(*) as count FROM ${quoteIdent2(tableName)} GROUP BY ${columnList} HAVING COUNT(*) > 1`
+    );
+    const violationCount = result.length;
+    if (violationCount > 0) {
+      const diagQuery = `SELECT ${columnList}, COUNT(*) FROM ${quoteIdent2(tableName)} GROUP BY ${columnList} HAVING COUNT(*) > 1`;
+      throw new ConstraintPreflightError(
+        `Cannot add UNIQUE constraint on "${tableName}"(${columns.join(", ")}): duplicate values exist`,
+        {
+          table: tableName,
+          constraint: `unique:${columns.join(",")}`,
+          violationCount,
+          query: diagQuery
+        }
+      );
+    }
+  }
+  async #preflightForeignKey(tableName, column, refTable, refColumn) {
+    const result = await this.#sql.unsafe(
+      `SELECT COUNT(*) as count FROM ${quoteIdent2(tableName)} t WHERE t.${quoteIdent2(column)} IS NOT NULL AND NOT EXISTS (SELECT 1 FROM ${quoteIdent2(refTable)} r WHERE r.${quoteIdent2(refColumn)} = t.${quoteIdent2(column)})`
+    );
+    const violationCount = parseInt(result[0]?.count ?? "0", 10);
+    if (violationCount > 0) {
+      const diagQuery = `SELECT t.${quoteIdent2(column)} FROM ${quoteIdent2(tableName)} t WHERE t.${quoteIdent2(column)} IS NOT NULL AND NOT EXISTS (SELECT 1 FROM ${quoteIdent2(refTable)} r WHERE r.${quoteIdent2(refColumn)} = t.${quoteIdent2(column)})`;
+      throw new ConstraintPreflightError(
+        `Cannot add FOREIGN KEY constraint on "${tableName}"(${column}): ${violationCount} orphaned rows exist`,
+        {
+          table: tableName,
+          constraint: `foreign_key:${column}->${refTable}.${refColumn}`,
+          violationCount,
+          query: diagQuery
+        }
+      );
+    }
+  }
+};
+export {
+  PostgresDriver as default
+};

package/src/sqlite.d.ts

@@ -0,0 +1,43 @@
+/**
+ * better-sqlite3 adapter for @b9g/zen
+ *
+ * Provides a Driver implementation for better-sqlite3 (Node.js).
+ * The connection is persistent - call close() when done.
+ *
+ * Requires: better-sqlite3
+ */
+import type { Driver, EnsureResult } from "./zen.js";
+import type { Table } from "./impl/table.js";
+/**
+ * SQLite driver using better-sqlite3.
+ *
+ * @example
+ * import SQLiteDriver from "@b9g/zen/sqlite";
+ * import {Database} from "@b9g/zen";
+ *
+ * const driver = new SQLiteDriver("file:app.db");
+ * const db = new Database(driver);
+ *
+ * db.addEventListener("upgradeneeded", (e) => {
+ *   e.waitUntil(runMigrations(e));
+ * });
+ *
+ * await db.open(1);
+ *
+ * // When done:
+ * await driver.close();
+ */
+export default class SQLiteDriver implements Driver {
+    #private;
+    readonly supportsReturning = true;
+    constructor(url: string);
+    all<T>(strings: TemplateStringsArray, values: unknown[]): Promise<T[]>;
+    get<T>(strings: TemplateStringsArray, values: unknown[]): Promise<T | null>;
+    run(strings: TemplateStringsArray, values: unknown[]): Promise<number>;
+    val<T>(strings: TemplateStringsArray, values: unknown[]): Promise<T | null>;
+    close(): Promise<void>;
+    transaction<T>(fn: (txDriver: Driver) => Promise<T>): Promise<T>;
+    withMigrationLock<T>(fn: () => Promise<T>): Promise<T>;
+    ensureTable<T extends Table<any>>(table: T): Promise<EnsureResult>;
+    ensureConstraints<T extends Table<any>>(table: T): Promise<EnsureResult>;
+}