@b9g/zen 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -5,6 +5,45 @@ 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
+
+- Validation that compound constraints (`indexes`, `unique`, `references` options) have 2+ fields
+  - Single-field constraints now throw `TableDefinitionError` with helpful message pointing to field-level API
+
+### Fixed
+
+- **TypeScript types now work in published package** - Updated libuild to fix module augmentation and `.d.ts` path resolution
+
+### Changed
+
+- New tagline: "Define Zod tables. Write raw SQL. Get typed objects."
+
+### Documentation
+
+- Added `.db.inserted()`, `.db.updated()`, `.db.upserted()` documentation with examples
+- Added compound unique constraints example
+- Fixed table naming consistency (all plural)
+- Various README cleanups and improvements
+
 ## [0.1.2] - 2025-12-22
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # ZenDB
 
-The simple database client. Define tables. Write SQL. Get objects.
+Define Zod tables. Write raw SQL. Get typed objects.
 
 [Website](https://zendb.org) · [GitHub](https://github.com/bikeshaving/zen) · [npm](https://www.npmjs.com/package/@b9g/zen)
 
@@ -47,7 +47,7 @@ import SQLiteDriver from "@b9g/zen/sqlite";
 const driver = new SQLiteDriver("file:app.db");
 
 // 1. Define tables
-const Users = table("users", {
+let Users = table("users", {
   id: z.string().uuid().db.primary().db.auto(),
   email: z.string().email().db.unique(),
   name: z.string(),
@@ -73,14 +73,14 @@ db.addEventListener("upgradeneeded", (e) => {
     }
     if (e.oldVersion < 2) {
       // Evolve schema: add avatar column (safe, additive)
-      const UsersV2 = table("users", {
+      Users = table("users", {
         id: z.string().uuid().db.primary().db.auto(),
         email: z.string().email().db.unique(),
         name: z.string(),
-        avatar: z.string().optional(),
+        avatar: z.string().optional(), // new field
       });
-      await db.ensureTable(UsersV2);          // adds missing columns/indexes
-      await db.ensureConstraints(UsersV2);    // applies new constraints on existing data
+      await db.ensureTable(Users); // adds missing columns/indexes
+      await db.ensureConstraints(Users); // applies new constraints on existing data
     }
   })());
 });
@@ -115,14 +115,8 @@ await db.update(Users, {name: "Alice Smith"}, user.id);
 Zen is the missing link between SQL and typed data. By writing tables with Zod schema, you get idempotent migration helpers, typed CRUD, normalized object references, and many features other database clients cannot provide.
 
 ### What Zen is not:
-- **Zen is not a query builder** — Rather than using a fluent query builder interface (`.where().orderBy().limit()`), Zen uses explicit SQL tagged template functions instead
-  ```
-  db.get(Posts)`
-    WHERE ${Posts.cols.published} = ${true}
-    ORDER BY ${Posts.cols.publishDate}
-    DESC LIMIT 20
-  ```.
-- **Zen is not an ORM** — Tables are not classes, they are Zod-powered singletons which provide schema-aware SQL-fragment helpers. These tables can be passed to CRUD helpers to validate writes, generate DDL, and normalize joined data into an object graph.
+- **Zen is not a query builder** — Rather than building SQL with fluent chains `.where().orderBy().limit()`, you write it directly with templates: `` db.all(Posts)`WHERE published = ${true} ORDER BY created_at DESC LIMIT 20` `` Helper functions help you write the tedious parts of SQL without hiding it or limiting your queries.
+- **Zen is not an ORM** — Tables are not classes. They are Zod-powered singletons which provide schema-aware utilities. These tables can be used to validate writes, generate DDL, and deduplicate joined data.
 - **Zen is not a startup** — Zen is an open-source library, not a venture-backed SaaS. There will never be a managed “ZenDB” instance or a “Zen Studio.” The library is a thin wrapper around Zod and JavaScript SQL drivers, with a focus on runtime abstractions rather than complicated tooling.
 
 ### Safety
@@ -133,9 +127,6 @@ Zen is the missing link between SQL and typed data. By writing tables with Zod s
 - **No destructive helpers** — No `dropColumn()`, `dropTable()`, `renameColumn()`
 - **No automatic migrations** — Schema changes are explicit in upgrade events
 
-Migrations are **additive and idempotent** by design. Use `ensureColumn()`, `ensureIndex()`, `copyColumn()` for safe schema evolution. Breaking changes require multi-step migrations. Rollbacks are new forward migrations.
-
-
 ## Table Definitions
 
 ```typescript
@@ -214,10 +205,37 @@ const Users = table("users", {
 
 // id and createdAt are optional - auto-generated if not provided
 const user = await db.insert(Users, {name: "Alice"});
-user.id;        // "550e8400-e29b-41d4-a716-446655440000"
+user.id; // "550e8400-e29b-41d4-a716-446655440000"
 user.createdAt; // 2024-01-15T10:30:00.000Z
 ```
 
+**Default values with `.db.inserted()`, `.db.updated()`, `.db.upserted()`:**
+
+These methods set default values for write operations. They accept JS functions or SQL builtins (`NOW`, `TODAY`, `CURRENT_TIMESTAMP`, `CURRENT_DATE`, `CURRENT_TIME`):
+
+```typescript
+import {z, table, NOW} from "@b9g/zen";
+
+const Posts = table("posts", {
+  id: z.string().uuid().db.primary().db.auto(),
+  title: z.string(),
+  // JS function — runs client-side
+  slug: z.string().db.inserted(() => generateSlug()),
+  // SQL builtin — runs database-side
+  createdAt: z.date().db.inserted(NOW),
+  updatedAt: z.date().db.upserted(NOW),  // set on insert AND update
+  viewCount: z.number().db.inserted(() => 0).db.updated(() => 0), // reset on update
+});
+```
+
+| Method | When applied | Field becomes optional for |
+|--------|--------------|---------------------------|
+| `.db.inserted(value)` | INSERT only | insert |
+| `.db.updated(value)` | UPDATE only | update |
+| `.db.upserted(value)` | INSERT and UPDATE | insert and update |
+
+**Why not Zod's `.default()`?** Zod's `.default()` applies at *parse time*, not *write time*. This means defaults would be applied when reading data, not when inserting. Zen throws an error if you use `.default()` — use `.db.inserted()` instead.
+
 **Automatic JSON encoding/decoding:**
 
 Objects (`z.object()`) and arrays (`z.array()`) are automatically serialized to JSON when stored and parsed back when read:
@@ -238,7 +256,7 @@ const settings = await db.insert(Settings, {
 
 // On read: JSON strings are parsed back to objects/arrays
 settings.config.theme; // "dark" (object, not string)
-settings.tags[0];      // "admin" (array, not string)
+settings.tags[0]; // "admin" (array, not string)
 ```
 
 **Custom encoding/decoding:**
@@ -246,7 +264,7 @@ settings.tags[0];      // "admin" (array, not string)
 Override automatic JSON encoding with custom transformations:
 
 ```typescript
-const Custom = table("custom", {
+const Articles = table("articles", {
   id: z.string().db.primary(),
   // Store array as CSV instead of JSON
   tags: z.array(z.string())
@@ -255,8 +273,8 @@ const Custom = table("custom", {
     .db.type("TEXT"), // Required: explicit column type for DDL
 });
 
-await db.insert(Custom, {id: "c1", tags: ["a", "b", "c"]});
-// Stored as: tags='a,b,c' (not '["a","b","c"]')
+await db.insert(Articles, {id: "a1", tags: ["news", "tech", "featured"]});
+// Stored as: tags='news,tech,featured' (not '["news","tech","featured"]')
 ```
 
 **Explicit column types:**
@@ -301,14 +319,16 @@ const posts = await db.all([Posts, Users.active])`
 `;
 ```
 
-**Compound indexes** via table options:
+**Compound indexes and unique constraints** via table options:
 ```typescript
 const Posts = table("posts", {
   id: z.string().db.primary(),
   authorId: z.string(),
+  slug: z.string(),
   createdAt: z.date(),
 }, {
   indexes: [["authorId", "createdAt"]],
+  unique: [["authorId", "slug"]],  // unique together
 });
 ```
 
@@ -355,16 +375,16 @@ type Post = Row<typeof Posts>;
 // Post includes: id, title, authorId, titleUpper, tags
 
 const posts = await db.all([Posts, Users, PostTags, Tags])`
-  JOIN "users" ON ${Users.on(Posts)}
-  LEFT JOIN "post_tags" ON ${PostTags.cols.postId} = ${Posts.cols.id}
-  LEFT JOIN "tags" ON ${Tags.on(PostTags)}
+  JOIN ${Users} ON ${Users.on(Posts)}
+  LEFT JOIN ${PostTags} ON ${PostTags.cols.postId} = ${Posts.cols.id}
+  LEFT JOIN ${Tags} ON ${Tags.on(PostTags)}
 `;
 
 const post = posts[0];
 post.titleUpper;  // "HELLO WORLD" — typed as string
-post.tags;        // ["javascript", "typescript"] — traverses relationships
-Object.keys(post);  // ["id", "title", "authorId", "author"] (no derived props)
-JSON.stringify(post);  // Excludes derived properties (non-enumerable)
+post.tags; // ["javascript", "typescript"] — traverses relationships
+Object.keys(post); // ["id", "title", "authorId", "author"] (no derived props)
+JSON.stringify(post); // Excludes derived properties (non-enumerable)
 ```
 
 Derived properties:
@@ -376,9 +396,9 @@ Derived properties:
 
 **Partial selects** with `pick()`:
 ```typescript
-const UserSummary = Users.pick("id", "name");
-const posts = await db.all([Posts, UserSummary])`
-  JOIN "users" ON ${UserSummary.on(Posts)}
+const UserSummaries = Users.pick("id", "name");
+const posts = await db.all([Posts, UserSummaries])`
+  JOIN ${UserSummaries} ON ${UserSummaries.on(Posts)}
 `;
 // posts[0].author has only id and name
 ```
@@ -470,6 +490,29 @@ await db.exec`CREATE INDEX idx_posts_author ON ${Posts}(${Posts.cols.authorId})`
 const count = await db.val<number>`SELECT COUNT(*) FROM ${Posts}`;
 ```
 
+## CRUD Helpers
+```typescript
+// Insert with Zod validation (uses RETURNING to get actual row)
+const user = await db.insert(Users, {
+  email: "alice@example.com",
+  name: "Alice",
+});
+// Returns actual row from DB, including auto-generated id and DB-computed defaults
+const userId = user.id;
+
+// Update by primary key (uses RETURNING)
+const updated = await db.update(Users, {name: "Bob"}, userId);
+
+// Delete by primary key
+await db.delete(Users, userId);
+
+// Soft delete (sets deletedAt timestamp, requires softDelete() field)
+await db.softDelete(Users, userId);
+```
+
+**RETURNING support:** `insert()` and `update()` use `RETURNING *` on SQLite and PostgreSQL to return the actual row from the database, including DB-computed defaults and triggers. MySQL falls back to a separate SELECT.
+
+
 ## Fragment Helpers
 
 Type-safe SQL fragments as methods on Table objects:
@@ -519,29 +562,6 @@ const posts = await db.all(Posts)`WHERE ${Posts.in("id", [])}`;
 // → WHERE 1 = 0
 ```
 
-## CRUD Helpers
-
-```typescript
-// Insert with Zod validation (uses RETURNING to get actual row)
-const user = await db.insert(Users, {
-  email: "alice@example.com",
-  name: "Alice",
-});
-// Returns actual row from DB, including auto-generated id and DB-computed defaults
-const userId = user.id;
-
-// Update by primary key (uses RETURNING)
-const updated = await db.update(Users, {name: "Bob"}, userId);
-
-// Delete by primary key
-await db.delete(Users, userId);
-
-// Soft delete (sets deletedAt timestamp, requires softDelete() field)
-await db.softDelete(Users, userId);
-```
-
-**RETURNING support:** `insert()` and `update()` use `RETURNING *` on SQLite and PostgreSQL to return the actual row from the database, including DB-computed defaults and triggers. MySQL falls back to a separate SELECT.
-
 ## Transactions
 
 ```typescript
@@ -575,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);
     }
   })());
 });
@@ -603,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(),
@@ -611,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)
 }
@@ -636,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).
 
@@ -818,6 +849,7 @@ const refs = Posts.references();      // [{fieldName: "authorId", table: Users,
 - Tagged template queries are cached by template object identity (compiled once per call site)
 - Normalization cost is O(rows) with hash maps per table
 - Reference resolution is zero-cost after deduplication
+- Zod validation happens on writes, never on reads.
 
 ## Driver Interface
 
@@ -916,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
@@ -970,41 +986,41 @@ Override with `.db.type("CUSTOM")` when using custom encode/decode.
 ```typescript
 import {
   // Zod (extended with .db namespace)
-  z,                  // Re-exported Zod with .db already available
+  z,                        // Re-exported Zod with .db already available
+  extendZod,                // Extend a separate Zod instance (advanced)
 
   // Table and view definition
-  table,              // Create a table definition from Zod schema
-  view,               // Create a read-only view from a table
-  isTable,            // Type guard for Table objects
-  isView,             // Type guard for View objects
-  extendZod,          // Extend a separate Zod instance (advanced)
+  table,                    // Create a table definition from Zod schema
+  view,                     // Create a read-only view from a table
+  isTable,                  // Type guard for Table objects
+  isView,                   // Type guard for View objects
 
   // Database
-  Database,           // Main database class
-  Transaction,        // Transaction context (passed to transaction callbacks)
-  DatabaseUpgradeEvent, // Event object for "upgradeneeded" handler
+  Database,                 // Main database class
+  Transaction,              // Transaction context (passed to transaction callbacks)
+  DatabaseUpgradeEvent,     // Event object for "upgradeneeded" handler
 
   // SQL builtins (for .db.inserted() / .db.updated())
-  NOW,                // CURRENT_TIMESTAMP alias
-  TODAY,              // CURRENT_DATE alias
-  CURRENT_TIMESTAMP,  // SQL CURRENT_TIMESTAMP
-  CURRENT_DATE,       // SQL CURRENT_DATE
-  CURRENT_TIME,       // SQL CURRENT_TIME
+  NOW,                      // CURRENT_TIMESTAMP alias
+  TODAY,                    // CURRENT_DATE alias
+  CURRENT_TIMESTAMP,        // SQL CURRENT_TIMESTAMP
+  CURRENT_DATE,             // SQL CURRENT_DATE
+  CURRENT_TIME,             // SQL CURRENT_TIME
 
   // Errors
-  DatabaseError,        // Base error class
-  ValidationError,    // Schema validation failed
-  TableDefinitionError, // Invalid table definition
-  MigrationError,     // Migration failed
-  MigrationLockError, // Failed to acquire migration lock
-  QueryError,         // SQL execution failed
-  NotFoundError,      // Entity not found
-  AlreadyExistsError, // Unique constraint violated
+  DatabaseError,            // Base error class
+  ValidationError,          // Schema validation failed
+  TableDefinitionError,     // Invalid table definition
+  MigrationError,           // Migration failed
+  MigrationLockError,       // Failed to acquire migration lock
+  QueryError,               // SQL execution failed
+  NotFoundError,            // Entity not found
+  AlreadyExistsError,       // Unique constraint violated
   ConstraintViolationError, // Database constraint violated
-  ConnectionError,    // Connection failed
-  TransactionError,   // Transaction failed
-  isDatabaseError,      // Type guard for DatabaseError
-  hasErrorCode,       // Check error code
+  ConnectionError,          // Connection failed
+  TransactionError,         // Transaction failed
+  isDatabaseError,          // Type guard for DatabaseError
+  hasErrorCode,             // Check error code
 } from "@b9g/zen";
 ```
 
@@ -1013,34 +1029,34 @@ import {
 ```typescript
 import type {
   // Table types
-  Table,              // Table definition object
-  PartialTable,       // Table created via .pick()
-  DerivedTable,       // Table with derived fields via .derive()
-  TableOptions,       // Options for table()
-  ReferenceInfo,      // Foreign key reference metadata
-  CompoundReference,  // Compound foreign key reference
+  Table,             // Table definition object
+  PartialTable,      // Table created via .pick()
+  DerivedTable,      // Table with derived fields via .derive()
+  TableOptions,      // Options for table()
+  ReferenceInfo,     // Foreign key reference metadata
+  CompoundReference, // Compound foreign key reference
 
   // Field types
-  FieldMeta,          // Field metadata for form generation
-  FieldType,          // Field type enum
-  FieldDBMeta,        // Database-specific field metadata
+  FieldMeta,         // Field metadata for form generation
+  FieldType,         // Field type enum
+  FieldDBMeta,       // Database-specific field metadata
 
   // Type inference
-  Row,                // Infer row type from Table (after read)
-  Insert,             // Infer insert type from Table (respects defaults/.db.auto())
-  Update,             // Infer update type from Table (all fields optional)
+  Row,               // Infer row type from Table (after read)
+  Insert,            // Infer insert type from Table (respects defaults/.db.auto())
+  Update,            // Infer update type from Table (all fields optional)
 
   // Fragment types
-  SetValues,          // Values accepted by Table.set()
-  SQLTemplate,        // SQL template object (return type of set(), on(), etc.)
-  SQLDialect,         // "sqlite" | "postgresql" | "mysql"
+  SetValues,         // Values accepted by Table.set()
+  SQLTemplate,       // SQL template object (return type of set(), on(), etc.)
+  SQLDialect,        // "sqlite" | "postgresql" | "mysql"
 
   // Driver types
-  Driver,             // Driver interface for adapters
-  TaggedQuery,        // Tagged template query function
+  Driver,            // Driver interface for adapters
+  TaggedQuery,       // Tagged template query function
 
   // Error types
-  DatabaseErrorCode,  // Error code string literals
+  DatabaseErrorCode, // Error code string literals
 } from "@b9g/zen";
 ```
 
@@ -1064,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
@@ -1136,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,7 +1,7 @@
 {
   "name": "@b9g/zen",
-  "version": "0.1.2",
-  "description": "The simple database client. Define tables. Write SQL. Get objects.",
+  "version": "0.1.4",
+  "description": "Define Zod tables. Write raw SQL. Get typed objects.",
   "keywords": [
     "database",
     "sql",
@@ -26,7 +26,7 @@
     "zod": "^4.0.0"
   },
   "devDependencies": {
-    "@b9g/libuild": "^0.1.20",
+    "@b9g/libuild": "^0.1.21",
     "@eslint/js": "^9.39.2",
     "@types/better-sqlite3": "^7.6.0",
     "@types/bun": "^1.3.4",

package/{chunk-NBXBBEMA.js → src/_chunks/chunk-2C6KOX4F.js}

@@ -2,7 +2,7 @@ import {
   isSQLBuiltin,
   isSQLIdentifier,
   resolveSQLBuiltin
-} from "./chunk-BEX6VPES.js";
+} from "./chunk-DKLSJISE.js";
 
 // src/impl/sql.ts
 function quoteIdent(name, dialect) {

package/{chunk-ARUUB3H4.js → src/_chunks/chunk-2R6FDKLS.js}

@@ -4,7 +4,7 @@ import {
   getViewMeta,
   ident,
   makeTemplate
-} from "./chunk-BEX6VPES.js";
+} from "./chunk-DKLSJISE.js";
 
 // src/impl/ddl.ts
 import { z } from "zod";

package/{chunk-BEX6VPES.js → src/_chunks/chunk-DKLSJISE.js}

@@ -793,6 +793,30 @@ function table(name, shape, options = {}) {
       name
     );
   }
+  for (const idx of options.indexes ?? []) {
+    if (idx.length < 2) {
+      throw new TableDefinitionError(
+        `Compound index in table "${name}" must have at least 2 fields. Use .db.index() for single-field indexes.`,
+        name
+      );
+    }
+  }
+  for (const u of options.unique ?? []) {
+    if (u.length < 2) {
+      throw new TableDefinitionError(
+        `Compound unique constraint in table "${name}" must have at least 2 fields. Use .db.unique() for single-field constraints.`,
+        name
+      );
+    }
+  }
+  for (const ref of options.references ?? []) {
+    if (ref.fields.length < 2) {
+      throw new TableDefinitionError(
+        `Compound foreign key in table "${name}" must have at least 2 fields. Use .db.references() for single-field foreign keys.`,
+        name
+      );
+    }
+  }
   const zodShape = {};
   const meta = {
     primary: null,

package/{ddl-OT6HPLQY.js → src/_chunks/ddl-32B7E53E.js}

@@ -2,8 +2,8 @@ import {
   generateColumnDDL,
   generateDDL,
   generateViewDDL
-} from "./chunk-ARUUB3H4.js";
-import "./chunk-BEX6VPES.js";
+} from "./chunk-2R6FDKLS.js";
+import "./chunk-DKLSJISE.js";
 export {
   generateColumnDDL,
   generateDDL,

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>[]>;
 }