@b9g/zen 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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.6] - 2026-01-05
+
+### Added
+
+- `table.relations()` method for unified forward and reverse relation navigation
+- `FieldMeta.schema` - raw Zod schema for direct introspection
+- `FieldMeta.db` - raw database metadata from `.db.*()` methods
+- `Relation` type export for typing relation navigators
+- Chained relation navigation: `Users.relations().posts.fields().author.fields().email`
+
+### Fixed
+
+- Validation no longer runs on reads, matching documented behavior (#16)
+
+### Deprecated
+
+- `FieldMeta.type`, `FieldMeta.required`, and other cooked properties - use `schema` and `db` instead
+
+## [0.1.5] - 2025-12-28
+
+### Fixed
+
+- `ensureTable()`, `ensureView()`, `ensureConstraints()`, `copyColumn()` no longer throw "cannot start a transaction within a transaction" when called inside `upgradeneeded` handler (#12)
+
 ## [0.1.4] - 2025-12-28
 
 ### Added

package/README.md

@@ -110,7 +110,7 @@ const post = await db.get(Posts, posts[0].id);
 await db.update(Users, {name: "Alice Smith"}, user.id);
 ```
 
-## Why Zen?
+## Why ZenDB?
 
 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.
 
@@ -829,19 +829,29 @@ type NewUser = Insert<typeof Users>; // Insert type (respects defaults/.db.auto(
 
 ## Field Metadata
 
-Tables expose metadata for form generation:
+Tables expose metadata for introspection and form generation:
 
 ```typescript
 const fields = Users.fields();
-// {
-//   email: { name: "email", type: "email", required: true, unique: true },
-//   name: { name: "name", type: "text", required: true, maxLength: 100 },
-//   role: { name: "role", type: "select", options: ["user", "admin"], default: "user" },
-// }
 
-const pkName = Users.primaryKey();    // "id" (field name)
+// Preferred: raw schema and db metadata
+fields.email.name;              // "email"
+fields.email.schema;            // ZodString - use Zod APIs (isOptional(), etc.)
+fields.email.db;                // FieldDBMeta object
+fields.email.db.unique;         // true
+fields.email.db.primaryKey;     // undefined
+
+const pkName = Users.meta.primary;    // "id" (field name)
 const pkFragment = Users.primary;     // SQLTemplate: "users"."id"
-const refs = Posts.references();      // [{fieldName: "authorId", table: Users, as: "author"}]
+const refs = Posts.meta.references;   // [{fieldName: "authorId", table: Users, as: "author"}]
+
+// Relation navigation (forward and reverse)
+Posts.relations().author.table;       // Users table
+Posts.relations().author.fields();    // Users field metadata
+Users.relations().posts.table;        // Posts table (if reverseAs: "posts" defined)
+
+// Chain navigation through relationships
+Users.relations().posts.fields().author.fields().email;  // Back to Users.email field
 ```
 
 ## Performance
@@ -1037,9 +1047,9 @@ import type {
   CompoundReference, // Compound foreign key reference
 
   // Field types
-  FieldMeta,         // Field metadata for form generation
-  FieldType,         // Field type enum
+  FieldMeta,         // Field metadata for introspection
   FieldDBMeta,       // Database-specific field metadata
+  Relation,          // Relation navigator from table.relations()
 
   // Type inference
   Row,               // Infer row type from Table (after read)
@@ -1094,10 +1104,9 @@ Users.primary;                 // SQLTemplate for primary key column
 // Metadata
 Users.name;                    // Table name string
 Users.schema;                  // Zod schema
-Users.meta;                    // Table metadata (primary, indexes, etc.)
-Users.primaryKey();            // Primary key field name or null
+Users.meta;                    // Table metadata (primary, references, indexes, etc.)
 Users.fields();                // Field metadata for form generation
-Users.references();            // Foreign key references
+Users.relations();             // Forward and reverse relation navigators
 
 // Derived Tables
 Users.pick("id", "email");     // PartialTable with subset of fields

package/package.json

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

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

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

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

@@ -665,6 +665,25 @@ function extendZod(zodModule) {
 extendZod(z);
 var TABLE_MARKER = Symbol.for("@b9g/zen:table");
 var TABLE_META = Symbol.for("@b9g/zen:table-meta");
+var reverseRelationsRegistry = /* @__PURE__ */ new WeakMap();
+function registerReverseRelation(targetTable, reverseName, getSourceTable, sourceTableName, fieldName) {
+  let relations = reverseRelationsRegistry.get(targetTable);
+  if (!relations) {
+    relations = /* @__PURE__ */ new Map();
+    reverseRelationsRegistry.set(targetTable, relations);
+  }
+  if (relations.has(reverseName)) {
+    throw new TableDefinitionError(
+      `Table "${sourceTableName}": reverse relation "${reverseName}" (from field "${fieldName}") collides with an existing reverse relation on target table "${targetTable.name}". Each reverseAs name must be unique per target table.`,
+      sourceTableName,
+      fieldName
+    );
+  }
+  relations.set(reverseName, getSourceTable);
+}
+function getReverseRelations(table2) {
+  return reverseRelationsRegistry.get(table2);
+}
 function isTable(value) {
   return value !== null && typeof value === "object" && TABLE_MARKER in value && value[TABLE_MARKER] === true;
 }
@@ -907,6 +926,15 @@ function table(name, shape, options = {}) {
             key
           );
         }
+        const targetRefs = getTableMeta(ref.table).references;
+        const collidingRef = targetRefs.find((r) => r.as === ref.reverseAs);
+        if (collidingRef) {
+          throw new TableDefinitionError(
+            `Table "${name}": reverse relation "${ref.reverseAs}" (from field "${key}") collides with forward relation "${collidingRef.as}" in target table "${ref.table.name}". Choose a different 'reverseAs' name.`,
+            name,
+            key
+          );
+        }
       }
       meta.references.push({
         fieldName: key,
@@ -942,7 +970,19 @@ function table(name, shape, options = {}) {
     meta.fields[key] = dbMeta;
   }
   const schema = z.object(zodShape);
-  return createTableObject(name, schema, zodShape, meta, options);
+  const tableObj = createTableObject(name, schema, zodShape, meta, options);
+  for (const ref of meta.references) {
+    if (ref.reverseAs) {
+      registerReverseRelation(
+        ref.table,
+        ref.reverseAs,
+        () => tableObj,
+        name,
+        ref.fieldName
+      );
+    }
+  }
+  return tableObj;
 }
 function createColsProxy(tableName, zodShape) {
   return new Proxy({}, {
@@ -1020,6 +1060,25 @@ function createTableObject(name, schema, zodShape, meta, options) {
     references() {
       return meta.references;
     },
+    relations() {
+      const result = {};
+      for (const ref of meta.references) {
+        result[ref.as] = {
+          fields: () => ref.table.fields(),
+          table: ref.table
+        };
+      }
+      const reverseMap = getReverseRelations(table2);
+      if (reverseMap) {
+        for (const [reverseName, getSourceTable] of reverseMap) {
+          result[reverseName] = {
+            fields: () => getSourceTable().fields(),
+            table: getSourceTable()
+          };
+        }
+      }
+      return result;
+    },
     deleted() {
       const softDeleteField = meta.softDeleteField;
       if (!softDeleteField) {
@@ -1338,7 +1397,11 @@ function extractFieldMeta(name, zodType, dbMeta) {
   } = unwrapType(zodType);
   const { db: _db, ...userMeta } = collectedMeta;
   const meta = {
+    // New: raw schema access (preferred)
     name,
+    schema: zodType,
+    db: dbMeta,
+    // Deprecated: cooked properties for backwards compatibility
     type: "text",
     required: !isOptional && !isNullable && !hasDefault,
     ...userMeta

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

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

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

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

package/src/bun.js

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

package/src/impl/table.d.ts

@@ -125,46 +125,112 @@ export interface FieldDBMeta {
 export declare function extendZod(zodModule: typeof z): void;
 export type FieldType = "text" | "textarea" | "email" | "url" | "tel" | "password" | "number" | "integer" | "checkbox" | "select" | "date" | "datetime" | "time" | "json" | "hidden";
 export interface FieldMeta {
+    /** Field name (the key in the schema) */
     name: string;
+    /** Raw Zod schema - use Zod APIs for introspection (isOptional(), etc.) */
+    schema: z.ZodType;
+    /** Raw database metadata from .db.*() methods */
+    db: FieldDBMeta;
+    /**
+     * @deprecated Use `schema` with Zod APIs instead. This form-specific type
+     * inference will move to a separate @b9g/forms package.
+     */
     type: FieldType;
+    /**
+     * @deprecated Use `!schema.isOptional() && !db.autoIncrement && !db.inserted` instead.
+     */
     required: boolean;
+    /**
+     * @deprecated Use `db.primaryKey` instead.
+     */
     primaryKey?: boolean;
+    /**
+     * @deprecated Use `db.unique` instead.
+     */
     unique?: boolean;
+    /**
+     * @deprecated Use `db.indexed` instead.
+     */
     indexed?: boolean;
+    /**
+     * @deprecated Use `db.softDelete` instead.
+     */
     softDelete?: boolean;
+    /**
+     * @deprecated Use `db.reference` instead.
+     */
     reference?: {
         table: Table;
         field: string;
         as: string;
         onDelete?: "cascade" | "set null" | "restrict";
     };
+    /**
+     * @deprecated Use `db.encode` instead.
+     */
     encode?: (value: any) => any;
+    /**
+     * @deprecated Use `db.decode` instead.
+     */
     decode?: (value: any) => any;
+    /**
+     * @deprecated Use `db.columnType` instead.
+     */
     columnType?: string;
+    /**
+     * @deprecated Use `db.autoIncrement` instead.
+     */
     autoIncrement?: boolean;
+    /**
+     * @deprecated Use `db.inserted` instead.
+     */
     inserted?: {
         type: "sql" | "symbol" | "function";
         template?: SQLTemplate;
         symbol?: SQLBuiltin;
         fn?: () => unknown;
     };
+    /**
+     * @deprecated Use `db.updated` instead.
+     */
     updated?: {
         type: "sql" | "symbol" | "function";
         template?: SQLTemplate;
         symbol?: SQLBuiltin;
         fn?: () => unknown;
     };
+    /**
+     * @deprecated Use `db.upserted` instead.
+     */
     upserted?: {
         type: "sql" | "symbol" | "function";
         template?: SQLTemplate;
         symbol?: SQLBuiltin;
         fn?: () => unknown;
     };
+    /**
+     * @deprecated Extract from Zod schema directly.
+     */
     default?: unknown;
+    /**
+     * @deprecated Extract from Zod schema directly.
+     */
     maxLength?: number;
+    /**
+     * @deprecated Extract from Zod schema directly.
+     */
     minLength?: number;
+    /**
+     * @deprecated Extract from Zod schema directly.
+     */
     min?: number;
+    /**
+     * @deprecated Extract from Zod schema directly.
+     */
     max?: number;
+    /**
+     * @deprecated Extract from Zod schema directly (for ZodEnum).
+     */
     options?: readonly string[];
     /** Additional user-defined metadata from Zod's .meta() (label, helpText, widget, etc.) */
     [key: string]: unknown;
@@ -306,12 +372,13 @@ type FilterRefs<PickedShape extends ZodRawShape, OriginalRefs extends Record<str
     [Alias in keyof OriginalRefs as Alias extends keyof RowRefs<PickedShape> ? Alias : never]: OriginalRefs[Alias];
 };
 /**
- * A relationship jump point for navigating to a referenced table's fields.
+ * A relationship navigator for traversing table relations.
+ * Used for both forward (many-to-one) and reverse (one-to-many) navigation.
  */
 export interface Relation<TargetTable extends Table<any, any>> {
-    /** Navigate to the target table's fields */
+    /** Navigate to the related table's fields */
     fields(): ReturnType<TargetTable["fields"]>;
-    /** Direct access to the referenced table */
+    /** Direct access to the related table */
     readonly table: TargetTable;
 }
 /**
@@ -355,9 +422,10 @@ export interface Table<T extends ZodRawShape = ZodRawShape, Refs extends Record<
      * Get the primary key field name.
      *
      * @returns The primary key field name, or null if no primary key is defined.
+     * @deprecated Use `table.meta.primary` instead.
      *
      * @example
-     * const pk = Users.primaryKey(); // "id"
+     * const pk = Users.meta.primary; // "id"
      */
     primaryKey(): string | null;
     /**
@@ -368,7 +436,10 @@ export interface Table<T extends ZodRawShape = ZodRawShape, Refs extends Record<
      * // → GROUP BY "posts"."id"
      */
     readonly primary: SQLTemplate | null;
-    /** Get all foreign key references */
+    /**
+     * Get all foreign key references.
+     * @deprecated Use `table.meta.references` for raw FK metadata, or `table.relations()` for navigation.
+     */
     references(): ReferenceInfo[];
     /**
      * Generate SQL fragment to check if a row is soft-deleted.
@@ -518,6 +589,39 @@ export interface Table<T extends ZodRawShape = ZodRawShape, Refs extends Record<
      * // → INSERT INTO posts (id, title) VALUES (?, ?), (?, ?)
      */
     values(rows: Partial<z.infer<ZodObject<T>>>[]): SQLTemplate;
+    /**
+     * Navigate table relations (both forward and reverse).
+     *
+     * Returns an object with relation names as keys. Each key provides
+     * a `Relation` with `fields()` and `table` properties.
+     *
+     * - Forward relations come from `as` in `.db.references(Table, "as")`
+     * - Reverse relations come from `reverseAs` in `.db.references(Table, "as", { reverseAs: "..." })`
+     *
+     * @example
+     * const Users = table("users", {
+     *   id: z.string().db.primary(),
+     *   email: z.string().email(),
+     * });
+     *
+     * const Posts = table("posts", {
+     *   id: z.string().db.primary(),
+     *   title: z.string(),
+     *   authorId: z.string().db.references(Users, "author", { reverseAs: "posts" }),
+     * });
+     *
+     * // Forward relation (many-to-one): Posts -> Users
+     * Posts.relations().author.fields().email  // Users.email field metadata
+     * Posts.relations().author.table           // Users table
+     *
+     * // Reverse relation (one-to-many): Users -> Posts
+     * Users.relations().posts.fields().title   // Posts.title field metadata
+     * Users.relations().posts.table            // Posts table
+     *
+     * // Chain navigation
+     * Users.relations().posts.fields().author.fields().email  // Back to Users.email
+     */
+    relations(): Record<string, Relation<Table<any, any>>>;
     /**
      * Get a view that excludes soft-deleted rows.
      *
@@ -583,6 +687,7 @@ export interface View<T extends ZodRawShape = ZodRawShape, Refs extends Record<s
     /**
      * Get reference metadata for foreign key relationships.
      * Delegates to the base table's references.
+     * @deprecated Use `view.baseTable.meta.references` for raw FK metadata, or `view.baseTable.relations()` for navigation.
      */
     references(): ReferenceInfo[];
     /**

package/src/mysql.js

@@ -2,19 +2,19 @@
 import {
   quoteIdent,
   renderDDL
-} from "./_chunks/chunk-2C6KOX4F.js";
+} from "./_chunks/chunk-OT6OQQ6S.js";
 import {
   generateColumnDDL,
   generateDDL,
   generateViewDDL
-} from "./_chunks/chunk-2R6FDKLS.js";
+} from "./_chunks/chunk-BI2NQCYN.js";
 import {
   ConstraintPreflightError,
   EnsureError,
   SchemaDriftError,
   getTableMeta,
   resolveSQLBuiltin
-} from "./_chunks/chunk-DKLSJISE.js";
+} from "./_chunks/chunk-NLI6YKQ6.js";
 
 // src/mysql.ts
 import {

package/src/postgres.js

@@ -2,19 +2,19 @@
 import {
   quoteIdent,
   renderDDL
-} from "./_chunks/chunk-2C6KOX4F.js";
+} from "./_chunks/chunk-OT6OQQ6S.js";
 import {
   generateColumnDDL,
   generateDDL,
   generateViewDDL
-} from "./_chunks/chunk-2R6FDKLS.js";
+} from "./_chunks/chunk-BI2NQCYN.js";
 import {
   ConstraintPreflightError,
   EnsureError,
   SchemaDriftError,
   getTableMeta,
   resolveSQLBuiltin
-} from "./_chunks/chunk-DKLSJISE.js";
+} from "./_chunks/chunk-NLI6YKQ6.js";
 
 // src/postgres.ts
 import {

package/src/sqlite.js

@@ -2,19 +2,19 @@
 import {
   quoteIdent,
   renderDDL
-} from "./_chunks/chunk-2C6KOX4F.js";
+} from "./_chunks/chunk-OT6OQQ6S.js";
 import {
   generateColumnDDL,
   generateDDL,
   generateViewDDL
-} from "./_chunks/chunk-2R6FDKLS.js";
+} from "./_chunks/chunk-BI2NQCYN.js";
 import {
   ConstraintPreflightError,
   EnsureError,
   SchemaDriftError,
   getTableMeta,
   resolveSQLBuiltin
-} from "./_chunks/chunk-DKLSJISE.js";
+} from "./_chunks/chunk-NLI6YKQ6.js";
 
 // src/sqlite.ts
 import {

package/src/zen.js

@@ -1,5 +1,5 @@
 /// <reference types="./zen.d.ts" />
-import "./_chunks/chunk-2C6KOX4F.js";
+import "./_chunks/chunk-OT6OQQ6S.js";
 import {
   AlreadyExistsError,
   CURRENT_DATE,
@@ -39,7 +39,7 @@ import {
   table,
   validateWithStandardSchema,
   view
-} from "./_chunks/chunk-DKLSJISE.js";
+} from "./_chunks/chunk-NLI6YKQ6.js";
 
 // src/zen.ts
 import { z as zod } from "zod";
@@ -87,11 +87,9 @@ function buildEntityMap(rows, tables, driver) {
       const key = entityKey(table2.name, pk);
       if (!entities.has(key)) {
         const decoded = decodeData(table2, data, driver);
-        const parsed = validateWithStandardSchema(
-          table2.schema,
-          decoded
-        );
-        entities.set(key, parsed);
+        if (decoded) {
+          entities.set(key, decoded);
+        }
       }
     }
   }
@@ -1236,6 +1234,7 @@ var Database = class extends EventTarget {
   #version = 0;
   #opened = false;
   #tables = [];
+  #inMigrationLock = false;
   constructor(driver, options) {
     super();
     this.#driver = driver;
@@ -1282,9 +1281,19 @@ var Database = class extends EventTarget {
       }
     };
     if (this.#driver.withMigrationLock) {
-      await this.#driver.withMigrationLock(runMigration);
+      this.#inMigrationLock = true;
+      try {
+        await this.#driver.withMigrationLock(runMigration);
+      } finally {
+        this.#inMigrationLock = false;
+      }
     } else {
-      await this.#driver.transaction(runMigration);
+      this.#inMigrationLock = true;
+      try {
+        await this.#driver.transaction(runMigration);
+      } finally {
+        this.#inMigrationLock = false;
+      }
     }
     this.#version = version;
     this.#opened = true;
@@ -2071,6 +2080,9 @@ var Database = class extends EventTarget {
       );
     }
     const doEnsure = () => this.#driver.ensureTable(table2);
+    if (this.#inMigrationLock) {
+      return await doEnsure();
+    }
     if (this.#driver.withMigrationLock) {
       return await this.#driver.withMigrationLock(doEnsure);
     }
@@ -2094,6 +2106,9 @@ var Database = class extends EventTarget {
       );
     }
     const doEnsure = () => this.#driver.ensureView(viewObj);
+    if (this.#inMigrationLock) {
+      return await doEnsure();
+    }
     if (this.#driver.withMigrationLock) {
       return await this.#driver.withMigrationLock(doEnsure);
     }
@@ -2128,6 +2143,9 @@ var Database = class extends EventTarget {
       );
     }
     const doEnsure = () => this.#driver.ensureConstraints(table2);
+    if (this.#inMigrationLock) {
+      return await doEnsure();
+    }
     if (this.#driver.withMigrationLock) {
       return await this.#driver.withMigrationLock(doEnsure);
     }
@@ -2163,6 +2181,9 @@ var Database = class extends EventTarget {
     }
     if (this.#driver.copyColumn) {
       const doCopy2 = () => this.#driver.copyColumn(table2, fromField, toField);
+      if (this.#inMigrationLock) {
+        return await doCopy2();
+      }
       if (this.#driver.withMigrationLock) {
         return await this.#driver.withMigrationLock(doCopy2);
       }
@@ -2200,6 +2221,9 @@ var Database = class extends EventTarget {
         );
       }
     };
+    if (this.#inMigrationLock) {
+      return await doCopy();
+    }
     if (this.#driver.withMigrationLock) {
       return await this.#driver.withMigrationLock(doCopy);
     }