@b9g/zen 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -5,6 +5,28 @@ 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.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
@@ -818,6 +838,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
 
@@ -970,41 +991,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 +1034,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";
 ```
 

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.3",
+  "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.js

@@ -3,15 +3,15 @@ import {
   placeholder,
   quoteIdent,
   renderDDL
-} from "../chunk-NBXBBEMA.js";
+} from "./_chunks/chunk-2C6KOX4F.js";
 import {
   generateDDL,
   generateViewDDL
-} from "../chunk-ARUUB3H4.js";
+} from "./_chunks/chunk-2R6FDKLS.js";
 import {
   getTableMeta,
   resolveSQLBuiltin
-} from "../chunk-BEX6VPES.js";
+} from "./_chunks/chunk-DKLSJISE.js";
 
 // src/bun.ts
 import { SQL } from "bun";
@@ -742,7 +742,7 @@ var BunDriver = class {
     return applied;
   }
   async #addColumn(table, fieldName) {
-    const { generateColumnDDL } = await import("../ddl-OT6HPLQY.js");
+    const { generateColumnDDL } = await import("./_chunks/ddl-32B7E53E.js");
     const zodType = table.schema.shape[fieldName];
     const fieldMeta = table.meta.fields[fieldName] || {};
     const colTemplate = generateColumnDDL(

package/src/impl/builtins.d.ts

@@ -0,0 +1,52 @@
+/**
+ * SQL Builtins - SQL-native values with no JavaScript equivalent.
+ *
+ * These symbols represent database functions that are evaluated at query time,
+ * not in JavaScript. They're used for default values and expressions.
+ */
+/**
+ * Current timestamp - resolves to CURRENT_TIMESTAMP (standard SQL).
+ *
+ * @example
+ * createdAt: z.date().db.inserted(CURRENT_TIMESTAMP)
+ * updatedAt: z.date().db.updated(NOW)
+ */
+export declare const CURRENT_TIMESTAMP: unique symbol;
+/**
+ * Current date - resolves to CURRENT_DATE (standard SQL).
+ *
+ * @example
+ * dateOnly: z.date().db.inserted(CURRENT_DATE)
+ */
+export declare const CURRENT_DATE: unique symbol;
+/**
+ * Current time - resolves to CURRENT_TIME (standard SQL).
+ *
+ * @example
+ * timeOnly: z.string().db.inserted(CURRENT_TIME)
+ */
+export declare const CURRENT_TIME: unique symbol;
+/**
+ * Ergonomic alias for CURRENT_TIMESTAMP.
+ *
+ * @example
+ * createdAt: z.date().db.inserted(NOW)
+ */
+export declare const NOW: typeof CURRENT_TIMESTAMP;
+/**
+ * Ergonomic alias for CURRENT_DATE.
+ *
+ * @example
+ * dateOnly: z.date().db.inserted(TODAY)
+ */
+export declare const TODAY: typeof CURRENT_DATE;
+/** SQL builtins - SQL-native values with no JavaScript representation */
+export type SQLBuiltin = typeof CURRENT_TIMESTAMP | typeof CURRENT_DATE | typeof CURRENT_TIME;
+/**
+ * Check if a value is a known SQL builtin.
+ */
+export declare function isSQLBuiltin(value: unknown): value is SQLBuiltin;
+/**
+ * Resolve a SQL builtin symbol to its SQL representation.
+ */
+export declare function resolveSQLBuiltin(sym: symbol): string;