@b9g/zen 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -5,6 +5,46 @@ 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.2] - 2025-12-22
+
+### Added
+
+- New type exports: `PartialTable`, `DerivedTable`, `SetValues`, `FieldDBMeta`, `ReferenceInfo`, `CompoundReference`, `TaggedQuery`, `SQLDialect`, `isTable`
+- Views documentation section in README
+- `EnsureError` and `SchemaDriftError` documented in error types
+
+### Changed
+
+- Reorganized `zen.ts` exports into logical groups
+- README Types section now accurately reflects actual exports (removed non-existent `SQLFragment`, `DDLFragment`, `DBExpression`)
+
+### Fixed
+
+- `isTable` type guard now exported (was missing)
+
+## [0.1.1] - 2025-12-21
+
+### Added
+
+- Driver-level type encoding/decoding for dialect-specific handling
+  - `encodeValue(value, fieldType)` and `decodeValue(value, fieldType)` methods on Driver interface
+  - SQLite: Date→ISO string, boolean→1/0, JSON stringify/parse
+  - MySQL: Date→"YYYY-MM-DD HH:MM:SS", boolean→1/0, JSON stringify/parse
+  - PostgreSQL: Mostly passthrough (pg handles natively), JSON stringify
+- `inferFieldType()` helper to infer field type from Zod schema
+- Node.js tests for encode/decode functionality
+
+### Changed
+
+- **Breaking:** Removed deprecated `Infer<T>` type alias (use `Row<T>` instead)
+- Renamed internal types for clarity:
+  - `InferRefs` → `RowRefs`
+  - `WithRefs` → `JoinedRow`
+
+### Fixed
+
+- Invalid datetime values now throw errors instead of returning Invalid Date
+
 ## [0.1.0] - 2025-12-20
 
 Initial release of @b9g/zen - the simple database client.

package/README.md

@@ -1,9 +1,8 @@
 # ZenDB
-The simple database client.
 
-Define tables. Write SQL. Get objects.
+The simple database client. Define tables. Write SQL. Get objects.
 
-Cultivate your data.
+[Website](https://zendb.org) · [GitHub](https://github.com/bikeshaving/zen) · [npm](https://www.npmjs.com/package/@b9g/zen)
 
 ## Installation
 
@@ -58,7 +57,7 @@ const Posts = table("posts", {
   id: z.string().uuid().db.primary().db.auto(),
   authorId: z.string().uuid().db.references(Users, "author"),
   title: z.string(),
-  published: z.boolean().default(false),
+  published: z.boolean().db.inserted(() => false),
 });
 
 // 2. Create database with migrations
@@ -111,6 +110,32 @@ const post = await db.get(Posts, posts[0].id);
 await db.update(Users, {name: "Alice Smith"}, user.id);
 ```
 
+## Why Zen?
+
+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 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
+
+- **No lazy loading** — Related data comes from your JOINs
+- **No ORM identity map** — Normalization is per-query, not session-wide
+- **No down migrations** — Forward-only versioning (1 → 2 → 3)
+- **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
@@ -121,7 +146,7 @@ const Users = table("users", {
   id: z.string().uuid().db.primary().db.auto(),
   email: z.string().email().db.unique(),
   name: z.string().max(100),
-  role: z.enum(["user", "admin"]).default("user"),
+  role: z.enum(["user", "admin"]).db.inserted(() => "user"),
   createdAt: z.date().db.auto(),
 });
 
@@ -130,10 +155,23 @@ const Posts = table("posts", {
   title: z.string(),
   content: z.string().optional(),
   authorId: z.string().uuid().db.references(Users, "author", {onDelete: "cascade"}),
-  published: z.boolean().default(false),
+  published: z.boolean().db.inserted(() => false),
 });
 ```
 
+**Zod to Database Behavior:**
+
+| Zod Method | Effect |
+|------------|--------|
+| `.optional()` | Column allows `NULL`; field omittable on insert |
+| `.nullable()` | Column allows `NULL`; must explicitly pass `null` or value |
+| `.string().max(n)` | `VARCHAR(n)` in DDL (if n ≤ 255) |
+| `.string().uuid()` | Used by `.db.auto()` to generate UUIDs |
+| `.number().int()` | `INTEGER` column type |
+| `.date()` | `TIMESTAMPTZ` / `DATETIME` / `TEXT` depending on dialect |
+| `.object()` / `.array()` | Stored as JSON, auto-encoded/decoded |
+| `.default()` | **Throws error** — use `.db.inserted()` instead |
+
 **The `.db` namespace:**
 
 The `.db` property is available on all Zod types imported from `@b9g/zen`. It provides database-specific modifiers:
@@ -253,7 +291,14 @@ await db.delete(Users, userId);
 const activeUsers = await db.all(Users)`
   WHERE NOT ${Users.deleted()}
 `;
-// → WHERE NOT "users"."deletedAt" IS NOT NULL
+
+// Or use the .active view (auto-generated, read-only)
+const activeUsers = await db.all(Users.active)``;
+
+// JOINs with .active automatically filter deleted rows
+const posts = await db.all([Posts, Users.active])`
+  JOIN "users_active" ON ${Users.active.cols.id} = ${Posts.cols.authorId}
+`;
 ```
 
 **Compound indexes** via table options:
@@ -267,6 +312,28 @@ const Posts = table("posts", {
 });
 ```
 
+**Compound foreign keys** for composite primary keys:
+```typescript
+const OrderProducts = table("order_products", {
+  orderId: z.string().uuid(),
+  productId: z.string().uuid(),
+  // ... compound primary key
+});
+
+const OrderItems = table("order_items", {
+  id: z.string().uuid().db.primary(),
+  orderId: z.string().uuid(),
+  productId: z.string().uuid(),
+  quantity: z.number(),
+}, {
+  references: [{
+    fields: ["orderId", "productId"],
+    table: OrderProducts,
+    as: "orderProduct",
+  }],
+});
+```
+
 **Derived properties** for client-side transformations:
 ```typescript
 const Posts = table("posts", {
@@ -279,27 +346,33 @@ const Posts = table("posts", {
   derive: {
     // Pure functions only (no I/O, no side effects)
     titleUpper: (post) => post.title.toUpperCase(),
-    tags: (post) => post.postTags?.map(pt => pt.tag) ?? [],
+    // Traverse relationships (requires JOIN in query)
+    tags: (post) => post.postTags?.map(pt => pt.tag?.name) ?? [],
   }
 });
 
-const posts = await db.all([Posts, Users])`
+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)}
 `;
 
-type PostWithDerived = Row<typeof Posts> & {titleUpper: string; tags: string[]};
-const post = posts[0] as PostWithDerived;
-post.titleUpper;  // ✅ "HELLO WORLD"
-Object.keys(post);  // ["id", "title", "authorId", "author"] (no "titleUpper")
-JSON.stringify(post);  // ✅ Excludes derived properties (non-enumerable)
+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)
 ```
 
 Derived properties:
 - Are lazy getters (computed on access, not stored)
 - Are non-enumerable (hidden from `Object.keys()` and `JSON.stringify()`)
 - Must be pure functions (no I/O, no database queries)
-- Only transform data already in the entity
-- Are NOT part of TypeScript type inference
+- Can traverse resolved relationships from the same query
+- Are fully typed via `Row<T>` inference
 
 **Partial selects** with `pick()`:
 ```typescript
@@ -312,6 +385,55 @@ const posts = await db.all([Posts, UserSummary])`
 
 **Table identity**: A table definition is a singleton value which is passed to database methods for validation, normalization, schema management, and convenient CRUD operations. It is not a class.
 
+## Views
+
+Views are read-only projections of tables with predefined WHERE clauses:
+
+```typescript
+import {z, table, view} from "@b9g/zen";
+
+const Users = table("users", {
+  id: z.string().db.primary(),
+  name: z.string(),
+  role: z.enum(["user", "admin"]),
+  deletedAt: z.date().nullable().db.softDelete(),
+});
+
+// Define views with explicit names
+const ActiveUsers = view("active_users", Users)`
+  WHERE ${Users.cols.deletedAt} IS NULL
+`;
+
+const AdminUsers = view("admin_users", Users)`
+  WHERE ${Users.cols.role} = ${"admin"}
+`;
+
+// Query from views (same API as tables)
+const admins = await db.all(AdminUsers)``;
+const admin = await db.get(AdminUsers, "u1");
+
+// Views are read-only — mutations throw errors
+await db.insert(AdminUsers, {...});  // ✗ Error
+await db.update(AdminUsers, {...});  // ✗ Error
+await db.delete(AdminUsers, "u1");   // ✗ Error
+```
+
+**Auto-generated `.active` view:** Tables with a `.db.softDelete()` field automatically get an `.active` view:
+
+```typescript
+// Equivalent to: view("users_active", Users)`WHERE deletedAt IS NULL`
+const activeUsers = await db.all(Users.active)``;
+```
+
+**Views preserve table relationships:** Views inherit references from their base table, so JOINs work identically:
+
+```typescript
+const posts = await db.all([Posts, AdminUsers])`
+  JOIN "admin_users" ON ${AdminUsers.on(Posts)}
+`;
+posts[0].author?.role; // "admin"
+```
+
 ## Queries
 
 Tagged templates with automatic parameterization:
@@ -485,7 +607,7 @@ zen provides idempotent helpers that encourage safe, additive-only migrations:
 const Posts = table("posts", {
   id: z.string().db.primary(),
   title: z.string(),
-  views: z.number().default(0), // NEW - add to schema
+  views: z.number().db.inserted(() => 0), // NEW - add to schema
 });
 
 if (e.oldVersion < 2) {
@@ -727,6 +849,8 @@ interface Driver {
 
 **Migration locking**: If the driver provides `withMigrationLock()`, migrations run atomically (PostgreSQL uses advisory locks, MySQL uses `GET_LOCK`, SQLite uses exclusive transactions).
 
+**Connection pooling**: Handled by the underlying driver. `postgres.js` and `mysql2` pool automatically; `better-sqlite3` uses a single connection (SQLite is single-writer anyway).
+
 ## Error Handling
 
 All errors extend `DatabaseError` with typed error codes:
@@ -776,6 +900,8 @@ await db.transaction(async (tx) => {
 - `AlreadyExistsError` — Unique constraint violated (tableName, field, value)
 - `QueryError` — SQL execution failed (sql)
 - `MigrationError` / `MigrationLockError` — Migration failures (fromVersion, toVersion)
+- `EnsureError` — Schema ensure operation failed (operation, table, step)
+- `SchemaDriftError` — Existing schema doesn't match definition (table, drift)
 - `ConnectionError` / `TransactionError` — Connection/transaction issues
 
 ## Debugging
@@ -815,17 +941,27 @@ console.log(Posts.ddl().toString());
 
 | Feature | SQLite | PostgreSQL | MySQL |
 |---------|--------|------------|-------|
-| **DDL Generation** | ✅ | ✅ | ✅ |
-| **RETURNING** | ✅ | ✅ | ❌ (uses SELECT after) |
-| **IF NOT EXISTS** (CREATE TABLE) | ✅ | ✅ | ✅ |
-| **IF NOT EXISTS** (ADD COLUMN) | ✅ | ✅ | ❌ (may error if exists) |
-| **Migration Locks** | BEGIN EXCLUSIVE | pg_advisory_lock | GET_LOCK |
-| **EXPLAIN** | EXPLAIN QUERY PLAN | EXPLAIN | EXPLAIN |
-| **JSON Type** | TEXT | JSONB | TEXT |
-| **Boolean Type** | INTEGER (0/1) | BOOLEAN | BOOLEAN |
-| **Date Type** | TEXT (ISO) | TIMESTAMPTZ | DATETIME |
-| **Transactions** | ✅ | ✅ | ✅ |
-| **Advisory Locks** | ❌ | ✅ | ✅ (named) |
+| RETURNING | ✅ | ✅ | ⚠️ fallback |
+| IF NOT EXISTS (CREATE TABLE) | ✅ | ✅ | ✅ |
+| IF NOT EXISTS (ADD COLUMN) | ✅ | ✅ | ⚠️ may error |
+| Migration Locks | BEGIN EXCLUSIVE | pg_advisory_lock | GET_LOCK |
+| Advisory Locks | — | ✅ | ✅ |
+
+### Zod to SQL Type Mapping
+
+| Zod Type | SQLite | PostgreSQL | MySQL |
+|----------|--------|------------|-------|
+| `z.string()` | TEXT | TEXT | TEXT |
+| `z.string().max(n)` (n ≤ 255) | TEXT | VARCHAR(n) | VARCHAR(n) |
+| `z.number()` | REAL | DOUBLE PRECISION | REAL |
+| `z.number().int()` | INTEGER | INTEGER | INTEGER |
+| `z.boolean()` | INTEGER | BOOLEAN | BOOLEAN |
+| `z.date()` | TEXT | TIMESTAMPTZ | DATETIME |
+| `z.enum([...])` | TEXT | TEXT | TEXT |
+| `z.object({...})` | TEXT | JSONB | TEXT |
+| `z.array(...)` | TEXT | JSONB | TEXT |
+
+Override with `.db.type("CUSTOM")` when using custom encode/decode.
 
 ## Public API Reference
 
@@ -836,9 +972,11 @@ import {
   // Zod (extended with .db namespace)
   z,                  // Re-exported Zod with .db already available
 
-  // Table definition
+  // 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)
 
   // Database
@@ -846,13 +984,12 @@ import {
   Transaction,        // Transaction context (passed to transaction callbacks)
   DatabaseUpgradeEvent, // Event object for "upgradeneeded" handler
 
-  // DB expressions
-  db,                 // Runtime DB expressions (db.now(), db.json(), etc.)
-  isDBExpression,     // Type guard for DBExpression objects
-
-  // Custom field helpers
-  setDBMeta,          // Set database metadata on a Zod schema
-  getDBMeta,          // Get database metadata from a Zod schema
+  // 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
 
   // Errors
   DatabaseError,        // Base error class
@@ -895,19 +1032,15 @@ import type {
 
   // Fragment types
   SetValues,          // Values accepted by Table.set()
-  SQLFragment,        // SQL fragment object
-  DDLFragment,        // DDL fragment object
+  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
 
-  // Expression types
-  DBExpression,       // Runtime database expression
-
   // Error types
-  DatabaseErrorCode,    // Error code string literals
+  DatabaseErrorCode,  // Error code string literals
 } from "@b9g/zen";
 ```
 
@@ -961,6 +1094,9 @@ Users.pick("id", "email");     // PartialTable with subset of fields
 Users.derive("hasEmail", z.boolean())`
   ${Users.cols.email} IS NOT NULL
 `;
+
+// Views
+Users.active;                  // View excluding soft-deleted rows (read-only)
 ```
 
 ### Database Methods
@@ -1020,25 +1156,3 @@ import PostgresDriver from "@b9g/zen/postgres";
 // MySQL (mysql2)
 import MySQLDriver from "@b9g/zen/mysql";
 ```
-
-## What This Library Does Not Do
-
-**Query Generation:**
-- **No model classes** — Tables are plain definitions, not class instances
-- **No hidden JOINs** — You write all SQL explicitly
-- **No implicit query building** — No `.where().orderBy().limit()` chains
-- **No lazy loading** — Related data comes from your JOINs
-- **No ORM identity map** — Normalization is per-query, not session-wide
-
-**Migrations:**
-- **No down migrations** — Forward-only, monotonic versioning (1 → 2 → 3)
-- **No destructive helpers** — No `dropColumn()`, `dropTable()`, `renameColumn()` methods
-- **No automatic migrations** — DDL must be written explicitly in upgrade events
-- **No migration files** — Event handlers replace traditional migration folders
-- **No branching versions** — Linear version history only
-
-**Safety Philosophy:**
-- Migrations are **additive and idempotent** by design
-- Use `ensureColumn()`, `ensureIndex()`, `copyColumn()` for safe schema changes
-- Breaking changes require multi-step migrations (add, migrate data, deprecate)
-- Version numbers never decrease — rollbacks are new forward migrations

package/{chunk-QXGEP5PB.js → chunk-ARUUB3H4.js}

@@ -1,9 +1,10 @@
 import {
   createTemplate,
   getTableMeta,
+  getViewMeta,
   ident,
   makeTemplate
-} from "./chunk-56M5Z3A6.js";
+} from "./chunk-BEX6VPES.js";
 
 // src/impl/ddl.ts
 import { z } from "zod";
@@ -303,8 +304,32 @@ CREATE INDEX ${indexExists}`;
   }
   return createTemplate(makeTemplate(strings), values);
 }
+function generateViewDDL(viewObj, _options = {}) {
+  const viewMeta = getViewMeta(viewObj);
+  const strings = [];
+  const values = [];
+  strings.push("DROP VIEW IF EXISTS ");
+  values.push(ident(viewObj.name));
+  strings.push(";\n\n");
+  strings[strings.length - 1] += "CREATE VIEW ";
+  values.push(ident(viewObj.name));
+  strings.push(" AS SELECT * FROM ");
+  values.push(ident(viewMeta.baseTable.name));
+  strings.push(" ");
+  const whereTemplate = viewMeta.whereTemplate;
+  const whereStrings = whereTemplate[0];
+  const whereValues = whereTemplate.slice(1);
+  strings[strings.length - 1] += whereStrings[0];
+  for (let i = 0; i < whereValues.length; i++) {
+    values.push(whereValues[i]);
+    strings.push(whereStrings[i + 1]);
+  }
+  strings[strings.length - 1] += ";";
+  return createTemplate(makeTemplate(strings), values);
+}
 
 export {
   generateColumnDDL,
-  generateDDL
+  generateDDL,
+  generateViewDDL
 };