@b9g/zen 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.4] - 2025-12-28
+
+### Added
+
+- `db.explain()` - Get query execution plan (EXPLAIN QUERY PLAN for SQLite, EXPLAIN for PostgreSQL/MySQL)
+- `explain()` method on Driver interface - each driver owns its dialect-specific EXPLAIN syntax
+
+### Fixed
+
+- README documented fake APIs that never existed (`Users.ddl()`, `Posts.ensureColumn()`, `Posts.ensureIndex()`, `Users.copyColumn()`)
+- README now documents the real APIs: `db.ensureTable()`, `db.ensureView()`, `db.ensureConstraints()`, `db.copyColumn()`
+
+### Changed
+
+- `getColumns()` is now required on Driver interface (was optional with fallback)
+- Removed dialect-switching logic from database.ts - drivers own all dialect-specific behavior
+
 ## [0.1.3] - 2025-12-22
 
 ### Added

package/README.md

@@ -595,14 +595,16 @@ IndexedDB-style event-based migrations:
 db.addEventListener("upgradeneeded", (e) => {
   e.waitUntil((async () => {
     if (e.oldVersion < 1) {
-      await db.exec`${Users.ddl()}`;
-      await db.exec`${Posts.ddl()}`;
+      await db.ensureTable(Users);
+      await db.ensureTable(Posts);
     }
     if (e.oldVersion < 2) {
-      await db.exec`${Posts.ensureColumn("views")}`;
+      // Add a new column - just update the schema and call ensureTable again
+      await db.ensureTable(Posts); // Adds missing "views" column
     }
     if (e.oldVersion < 3) {
-      await db.exec`${Posts.ensureIndex(["title"])}`;
+      // Add constraints after data cleanup
+      await db.ensureConstraints(Posts);
     }
   })());
 });
@@ -623,7 +625,7 @@ await db.open(3); // Opens at version 3, fires upgradeneeded if needed
 zen provides idempotent helpers that encourage safe, additive-only migrations:
 
 ```typescript
-// Add a new column (reads from schema)
+// Add a new column - update schema and call ensureTable
 const Posts = table("posts", {
   id: z.string().db.primary(),
   title: z.string(),
@@ -631,24 +633,32 @@ const Posts = table("posts", {
 });
 
 if (e.oldVersion < 2) {
-  await db.exec`${Posts.ensureColumn("views")}`;
+  await db.ensureTable(Posts); // Adds missing columns from schema
 }
-// → ALTER TABLE "posts" ADD COLUMN IF NOT EXISTS "views" REAL DEFAULT 0
+// → ALTER TABLE "posts" ADD COLUMN "views" REAL DEFAULT 0
+
+// Add indexes - defined in schema, applied by ensureTable
+const Posts = table("posts", {
+  id: z.string().db.primary(),
+  title: z.string().db.index(), // NEW - add index
+  views: z.number().db.inserted(() => 0),
+});
 
-// Add an index
 if (e.oldVersion < 3) {
-  await db.exec`${Posts.ensureIndex(["title", "views"])}`;
+  await db.ensureTable(Posts); // Adds missing indexes
 }
-// → CREATE INDEX IF NOT EXISTS "idx_posts_title_views" ON "posts"("title", "views")
+// → CREATE INDEX IF NOT EXISTS "idx_posts_title" ON "posts"("title")
 
 // Safe column rename (additive, non-destructive)
 const Users = table("users", {
-  emailAddress: z.string().email(), // renamed from "email"
+  id: z.string().db.primary(),
+  email: z.string().email(), // Keep old column
+  emailAddress: z.string().email(), // NEW - add new column
 });
 
 if (e.oldVersion < 4) {
-  await db.exec`${Users.ensureColumn("emailAddress")}`;
-  await db.exec`${Users.copyColumn("email", "emailAddress")}`;
+  await db.ensureTable(Users); // Adds emailAddress column
+  await db.copyColumn(Users, "email", "emailAddress"); // Copy data
   // Keep old "email" column for backwards compat
   // Drop it in a later migration if needed (manual SQL)
 }
@@ -656,9 +666,10 @@ if (e.oldVersion < 4) {
 ```
 
 **Helper methods:**
-- `table.ensureColumn(fieldName, options?)` - Idempotent ALTER TABLE ADD COLUMN
-- `table.ensureIndex(fields, options?)` - Idempotent CREATE INDEX
-- `table.copyColumn(from, to)` - Copy data between columns (for safe renames)
+- `db.ensureTable(table)` - Idempotent CREATE TABLE / ADD COLUMN / CREATE INDEX
+- `db.ensureView(view)` - Idempotent DROP + CREATE VIEW
+- `db.ensureConstraints(table)` - Add unique/FK constraints (with preflight checks)
+- `db.copyColumn(table, from, to)` - Copy data between columns (for safe renames)
 
 All helpers read from your table schema (single source of truth) and are safe to run multiple times (idempotent).
 
@@ -937,25 +948,9 @@ const query = db.print`SELECT * FROM ${Posts} WHERE ${Posts.cols.published} = ${
 console.log(query.sql);     // SELECT * FROM "posts" WHERE "posts"."published" = ?
 console.log(query.params);  // [true]
 
-// Inspect DDL generation
-const ddl = db.print`${Posts.ddl()}`;
-console.log(ddl.sql);  // CREATE TABLE IF NOT EXISTS "posts" (...)
-
-// Analyze query execution plan
-const plan = await db.explain`
-  SELECT * FROM ${Posts}
-  WHERE ${Posts.cols.authorId} = ${userId}
-`;
-console.log(plan);
-// SQLite: [{ detail: "SEARCH posts USING INDEX idx_posts_authorId (authorId=?)" }]
-// PostgreSQL: [{ "QUERY PLAN": "Index Scan using idx_posts_authorId on posts" }]
-
 // Debug fragments
 console.log(Posts.set({ title: "Updated" }).toString());
 // SQLFragment { sql: "\"title\" = ?", params: ["Updated"] }
-
-console.log(Posts.ddl().toString());
-// DDLFragment { type: "create-table", table: "posts" }
 ```
 
 ## Dialect Support
@@ -1085,12 +1080,6 @@ const Posts = table("posts", {
 
 const rows = [{id: "u1", email: "alice@example.com", deletedAt: null}];
 
-// DDL Generation
-Users.ddl();                     // DDLFragment for CREATE TABLE
-Users.ensureColumn("emailAddress"); // DDLFragment for ALTER TABLE ADD COLUMN
-Users.ensureIndex(["email"]);    // DDLFragment for CREATE INDEX
-Users.copyColumn("email", "emailAddress"); // SQLFragment for UPDATE (copy data)
-
 // Query Fragments
 Users.set({email: "alice@example.com"}); // SQLFragment for SET clause
 Users.values(rows);                      // SQLFragment for INSERT VALUES
@@ -1157,9 +1146,15 @@ await db.transaction(async (tx) => {
   await tx.exec`SELECT 1`;
 });
 
+// Schema Management
+await db.ensureTable(Users);           // CREATE TABLE / ADD COLUMN / CREATE INDEX
+await db.ensureView(AdminUsers);       // DROP + CREATE VIEW
+await db.ensureConstraints(Users);     // Add unique/FK constraints
+await db.copyColumn(Users, "old", "new"); // Copy data between columns
+
 // Debugging
-db.print`SELECT 1`;
-await db.explain`SELECT * FROM ${Users}`;
+db.print`SELECT 1`;                       // Returns { sql, params } without executing
+await db.explain`SELECT * FROM ${Users}`; // Returns query execution plan
 ```
 
 ### Driver Exports

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@b9g/zen",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Define Zod tables. Write raw SQL. Get typed objects.",
   "keywords": [
     "database",

package/src/bun.d.ts

@@ -58,4 +58,5 @@ export default class BunDriver implements Driver {
         type?: string;
         notnull?: boolean;
     }[]>;
+    explain(strings: TemplateStringsArray, values: unknown[]): Promise<Record<string, unknown>[]>;
 }

package/src/bun.js

@@ -370,7 +370,9 @@ var BunDriver = class {
         },
         transaction: async () => {
           throw new Error("Nested transactions are not supported");
-        }
+        },
+        getColumns: this.getColumns.bind(this),
+        explain: this.explain.bind(this)
       };
       return await fn(txDriver);
     });
@@ -524,6 +526,15 @@ var BunDriver = class {
   async getColumns(tableName) {
     return await this.#getColumns(tableName);
   }
+  async explain(strings, values) {
+    await this.#ensureSqliteInit();
+    const { sql, params } = buildSQL(strings, values, this.#dialect);
+    const explainPrefix = this.#dialect === "sqlite" ? "EXPLAIN QUERY PLAN " : "EXPLAIN ";
+    return await this.#sql.unsafe(
+      explainPrefix + sql,
+      params
+    );
+  }
   // ==========================================================================
   // Introspection Helpers (private)
   // ==========================================================================

package/src/impl/database.d.ts

@@ -127,12 +127,14 @@ export interface Driver {
      * @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<{
+    /** Introspection: list columns for a table (name, type, nullability). */
+    getColumns(tableName: string): Promise<{
         name: string;
         type?: string;
         notnull?: boolean;
     }[]>;
+    /** Get the query execution plan for a SQL query. */
+    explain(strings: TemplateStringsArray, values: unknown[]): Promise<Record<string, unknown>[]>;
 }
 /**
  * Result from ensure operations.
@@ -396,6 +398,20 @@ export declare class Database extends EventTarget {
         sql: string;
         params: unknown[];
     };
+    /**
+     * Get the query execution plan without running the query.
+     *
+     * Returns the database's EXPLAIN output for the given query.
+     * The format varies by database:
+     * - SQLite: EXPLAIN QUERY PLAN output
+     * - PostgreSQL: EXPLAIN output
+     * - MySQL: EXPLAIN output
+     *
+     * @example
+     * const plan = await db.explain`SELECT * FROM ${Users} WHERE email = ${"test@example.com"}`;
+     * console.log(plan);
+     */
+    explain(strings: TemplateStringsArray, ...values: unknown[]): Promise<Record<string, unknown>[]>;
     /**
      * Ensure a table exists with its columns and indexes.
      *

package/src/mysql.d.ts

@@ -71,4 +71,10 @@ export default class MySQLDriver implements Driver {
      * Applies unique and foreign key constraints with preflight checks.
      */
     ensureConstraints<T extends Table<any>>(table: T): Promise<EnsureResult>;
+    getColumns(tableName: string): Promise<{
+        name: string;
+        type: string;
+        notnull: boolean;
+    }[]>;
+    explain(strings: TemplateStringsArray, values: unknown[]): Promise<Record<string, unknown>[]>;
 }

package/src/mysql.js

@@ -268,7 +268,9 @@ var MySQLDriver = class {
         },
         transaction: async () => {
           throw new Error("Nested transactions are not supported");
-        }
+        },
+        getColumns: this.getColumns.bind(this),
+        explain: this.explain.bind(this)
       };
       const result = await fn(txDriver);
       await connection.query("COMMIT");
@@ -443,7 +445,7 @@ var MySQLDriver = class {
     );
     return (rows[0]?.count ?? 0) > 0;
   }
-  async #getColumns(tableName) {
+  async getColumns(tableName) {
     const [rows] = await this.#pool.execute(
       `SELECT COLUMN_NAME, DATA_TYPE, IS_NULLABLE FROM information_schema.columns WHERE table_schema = DATABASE() AND table_name = ? ORDER BY ordinal_position`,
       [tableName]
@@ -454,6 +456,11 @@ var MySQLDriver = class {
       notnull: row.IS_NULLABLE === "NO"
     }));
   }
+  async explain(strings, values) {
+    const { sql, params } = buildSQL(strings, values);
+    const [rows] = await this.#pool.execute(`EXPLAIN ${sql}`, params);
+    return rows;
+  }
   async #getIndexes(tableName) {
     const [rows] = await this.#pool.execute(
       `SELECT
@@ -508,7 +515,7 @@ var MySQLDriver = class {
     return constraints;
   }
   async #ensureMissingColumns(table) {
-    const existingCols = await this.#getColumns(table.name);
+    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;

package/src/postgres.d.ts

@@ -71,4 +71,10 @@ export default class PostgresDriver implements Driver {
      * Applies unique and foreign key constraints with preflight checks.
      */
     ensureConstraints<T extends Table<any>>(table: T): Promise<EnsureResult>;
+    getColumns(tableName: string): Promise<{
+        name: string;
+        type: string;
+        notnull: boolean;
+    }[]>;
+    explain(strings: TemplateStringsArray, values: unknown[]): Promise<Record<string, unknown>[]>;
 }

package/src/postgres.js

@@ -235,7 +235,9 @@ var PostgresDriver = class {
         },
         transaction: async () => {
           throw new Error("Nested transactions are not supported");
-        }
+        },
+        getColumns: this.getColumns.bind(this),
+        explain: this.explain.bind(this)
       };
       return await fn(txDriver);
     });
@@ -397,7 +399,7 @@ var PostgresDriver = class {
 		`;
     return result[0]?.exists ?? false;
   }
-  async #getColumns(tableName) {
+  async getColumns(tableName) {
     const result = await this.#sql`
 			SELECT column_name, data_type, is_nullable
 			FROM information_schema.columns
@@ -411,6 +413,13 @@ var PostgresDriver = class {
       notnull: row.is_nullable === "NO"
     }));
   }
+  async explain(strings, values) {
+    const { sql, params } = buildSQL(strings, values);
+    return await this.#sql.unsafe(
+      `EXPLAIN ${sql}`,
+      params
+    );
+  }
   async #getIndexes(tableName) {
     const result = await this.#sql`
 			SELECT indexname, indexdef
@@ -474,7 +483,7 @@ var PostgresDriver = class {
     });
   }
   async #ensureMissingColumns(table) {
-    const existingCols = await this.#getColumns(table.name);
+    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;

package/src/sqlite.d.ts

@@ -51,4 +51,10 @@ export default class SQLiteDriver implements Driver {
     ensureTable<T extends Table<any>>(table: T): Promise<EnsureResult>;
     ensureView<T extends View<any>>(viewObj: T): Promise<EnsureResult>;
     ensureConstraints<T extends Table<any>>(table: T): Promise<EnsureResult>;
+    getColumns(tableName: string): Promise<{
+        name: string;
+        type: string;
+        notnull: boolean;
+    }[]>;
+    explain(strings: TemplateStringsArray, values: unknown[]): Promise<Record<string, unknown>[]>;
 }

package/src/sqlite.js

@@ -343,7 +343,7 @@ var SQLiteDriver = class {
     const result = this.#db.prepare(`SELECT 1 FROM sqlite_master WHERE type='table' AND name=?`).all(tableName);
     return result.length > 0;
   }
-  async #getColumns(tableName) {
+  async getColumns(tableName) {
     const result = this.#db.prepare(`PRAGMA table_info(${quoteIdent2(tableName)})`).all();
     return result.map((row) => ({
       name: row.name,
@@ -351,6 +351,10 @@ var SQLiteDriver = class {
       notnull: row.notnull === 1
     }));
   }
+  async explain(strings, values) {
+    const { sql, params } = buildSQL(strings, values);
+    return this.#db.prepare(`EXPLAIN QUERY PLAN ${sql}`).all(...params);
+  }
   async #getIndexes(tableName) {
     const indexList = this.#db.prepare(`PRAGMA index_list(${quoteIdent2(tableName)})`).all();
     const indexes = [];
@@ -403,7 +407,7 @@ var SQLiteDriver = class {
   // Schema Ensure Helpers (private)
   // ==========================================================================
   async #ensureMissingColumns(table) {
-    const existingCols = await this.#getColumns(table.name);
+    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;

package/src/zen.js

@@ -2018,6 +2018,26 @@ var Database = class extends EventTarget {
     }
     return { sql, params: expandedValues };
   }
+  /**
+   * Get the query execution plan without running the query.
+   *
+   * Returns the database's EXPLAIN output for the given query.
+   * The format varies by database:
+   * - SQLite: EXPLAIN QUERY PLAN output
+   * - PostgreSQL: EXPLAIN output
+   * - MySQL: EXPLAIN output
+   *
+   * @example
+   * const plan = await db.explain`SELECT * FROM ${Users} WHERE email = ${"test@example.com"}`;
+   * console.log(plan);
+   */
+  async explain(strings, ...values) {
+    const { strings: expandedStrings, values: expandedValues } = expandFragments(
+      strings,
+      values
+    );
+    return await this.#driver.explain(expandedStrings, expandedValues);
+  }
   // ==========================================================================
   // Schema Ensure Methods
   // ==========================================================================
@@ -2190,34 +2210,8 @@ var Database = class extends EventTarget {
    * Queries the actual table structure to verify column existence.
    */
   async #checkColumnExists(tableName, columnName) {
-    if (this.#driver.getColumns) {
-      const columns = await this.#driver.getColumns(tableName);
-      return columns.some((col) => col.name === columnName);
-    }
-    try {
-      const pragmaStrings = makeTemplate(["PRAGMA table_info(", ")"]);
-      const pragmaValues = [ident(tableName)];
-      const columns = await this.#driver.all(
-        pragmaStrings,
-        pragmaValues
-      );
-      if (columns.length > 0) {
-        return columns.some((col) => col.name === columnName);
-      }
-    } catch {
-    }
-    try {
-      const schemaStrings = makeTemplate([
-        "SELECT column_name FROM information_schema.columns WHERE table_name = ",
-        " AND column_name = ",
-        " LIMIT 1"
-      ]);
-      const schemaValues = [tableName, columnName];
-      const result = await this.#driver.all(schemaStrings, schemaValues);
-      return result.length > 0;
-    } catch {
-      return true;
-    }
+    const columns = await this.#driver.getColumns(tableName);
+    return columns.some((col) => col.name === columnName);
   }
   // ==========================================================================
   // Transactions