@b9g/zen 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -5,6 +5,29 @@ 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.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

@@ -253,7 +253,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:
@@ -815,17 +822,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
 
@@ -961,6 +978,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

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

@@ -1,9 +1,10 @@
 import {
   createTemplate,
   getTableMeta,
+  getViewMeta,
   ident,
   makeTemplate
-} from "./chunk-56M5Z3A6.js";
+} from "./chunk-XHXMCOSW.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
 };

package/chunk-W7JTNEM4.js

@@ -0,0 +1,63 @@
+import {
+  isSQLBuiltin,
+  isSQLIdentifier,
+  resolveSQLBuiltin
+} from "./chunk-XHXMCOSW.js";
+
+// src/impl/sql.ts
+function quoteIdent(name, dialect) {
+  if (dialect === "mysql") {
+    return `\`${name.replace(/`/g, "``")}\``;
+  }
+  return `"${name.replace(/"/g, '""')}"`;
+}
+function placeholder(index, dialect) {
+  if (dialect === "postgresql") {
+    return `$${index}`;
+  }
+  return "?";
+}
+function renderDDL(strings, values, dialect) {
+  let sql = "";
+  for (let i = 0; i < strings.length; i++) {
+    sql += strings[i];
+    if (i < values.length) {
+      const value = values[i];
+      if (isSQLBuiltin(value)) {
+        sql += resolveSQLBuiltin(value);
+      } else if (isSQLIdentifier(value)) {
+        sql += quoteIdent(value.name, dialect);
+      } else {
+        sql += inlineLiteral(value, dialect);
+      }
+    }
+  }
+  return sql;
+}
+function inlineLiteral(value, dialect) {
+  if (value === null || value === void 0) {
+    return "NULL";
+  }
+  if (typeof value === "boolean") {
+    if (dialect === "sqlite") {
+      return value ? "1" : "0";
+    }
+    return value ? "TRUE" : "FALSE";
+  }
+  if (typeof value === "number") {
+    return String(value);
+  }
+  if (typeof value === "string") {
+    return `'${value.replace(/'/g, "''")}'`;
+  }
+  if (value instanceof Date) {
+    return `'${value.toISOString()}'`;
+  }
+  return `'${String(value).replace(/'/g, "''")}'`;
+}
+
+export {
+  quoteIdent,
+  placeholder,
+  renderDDL
+};

package/{chunk-56M5Z3A6.js → chunk-XHXMCOSW.js}

@@ -668,6 +668,120 @@ var TABLE_META = Symbol.for("@b9g/zen:table-meta");
 function getTableMeta(table2) {
   return table2[TABLE_META];
 }
+var VIEW_MARKER = Symbol("view");
+var VIEW_META = Symbol("viewMeta");
+function isView(value) {
+  return typeof value === "object" && value !== null && value[VIEW_MARKER] === true;
+}
+function getViewMeta(view2) {
+  return view2[VIEW_META];
+}
+function view(name, baseTable) {
+  validateIdentifier(name, "table");
+  if (name.includes(".")) {
+    throw new TableDefinitionError(
+      `Invalid view name "${name}": view names cannot contain "." as it conflicts with normalization prefixes`,
+      name
+    );
+  }
+  return (strings, ...templateValues) => {
+    const resultStrings = [];
+    const resultValues = [];
+    for (let i = 0; i < strings.length; i++) {
+      if (i === 0) {
+        resultStrings.push(strings[i]);
+      }
+      if (i < templateValues.length) {
+        const value = templateValues[i];
+        if (isSQLTemplate(value)) {
+          mergeFragment(resultStrings, resultValues, value, strings[i + 1]);
+        } else {
+          resultValues.push(value);
+          resultStrings.push(strings[i + 1]);
+        }
+      }
+    }
+    if (resultStrings.length > 0) {
+      resultStrings[0] = resultStrings[0].trimStart();
+      resultStrings[resultStrings.length - 1] = resultStrings[resultStrings.length - 1].trimEnd();
+    }
+    const whereTemplate = createTemplate(
+      makeTemplate(resultStrings),
+      resultValues
+    );
+    return createViewObject(name, baseTable, whereTemplate);
+  };
+}
+function createViewObject(name, baseTable, whereTemplate) {
+  const baseMeta = getTableMeta(baseTable);
+  const cols = new Proxy({}, {
+    get(_target, prop) {
+      if (prop in baseTable.schema.shape) {
+        return createTemplate(makeTemplate(["", ".", ""]), [
+          ident(name),
+          ident(prop)
+        ]);
+      }
+      return void 0;
+    },
+    has(_target, prop) {
+      return prop in baseTable.schema.shape;
+    },
+    ownKeys() {
+      return Object.keys(baseTable.schema.shape);
+    },
+    getOwnPropertyDescriptor(_target, prop) {
+      if (prop in baseTable.schema.shape) {
+        return { enumerable: true, configurable: true };
+      }
+      return void 0;
+    }
+  });
+  const primary = baseMeta.primary ? createTemplate(makeTemplate(["", ".", ""]), [
+    ident(name),
+    ident(baseMeta.primary)
+  ]) : null;
+  const viewMeta = {
+    baseTable,
+    whereTemplate
+  };
+  const tableMeta = {
+    ...baseMeta,
+    isView: true,
+    viewOf: baseTable.name,
+    derivedExprs: void 0,
+    derivedFields: void 0,
+    isDerived: void 0
+  };
+  const viewObj = {
+    name,
+    schema: baseTable.schema,
+    meta: tableMeta,
+    cols,
+    primary,
+    baseTable,
+    fields() {
+      return baseTable.fields();
+    },
+    references() {
+      return baseTable.references();
+    }
+  };
+  Object.defineProperty(viewObj, VIEW_MARKER, { value: true, enumerable: false });
+  Object.defineProperty(viewObj, VIEW_META, {
+    value: viewMeta,
+    enumerable: false
+  });
+  Object.defineProperty(viewObj, TABLE_MARKER, {
+    value: true,
+    enumerable: false
+  });
+  Object.defineProperty(viewObj, TABLE_META, {
+    value: tableMeta,
+    enumerable: false
+  });
+  return viewObj;
+}
 function table(name, shape, options = {}) {
   validateIdentifier(name, "table");
   if (name.includes(".")) {
@@ -886,7 +1000,7 @@ function createTableObject(name, schema, zodShape, meta, options) {
           `Table "${name}" does not have a soft delete field. Use softDelete() wrapper to mark a field.`
         );
       }
-      return createTemplate(makeTemplate(["", ".", " IS NOT NULL"]), [
+      return createTemplate(makeTemplate(["(", ".", " IS NOT NULL)"]), [
         ident(name),
         ident(softDeleteField)
       ]);
@@ -1113,6 +1227,28 @@ function createTableObject(name, schema, zodShape, meta, options) {
         }
       }
       return createTemplate(makeTemplate(strings), templateValues);
+    },
+    get active() {
+      const softDeleteField = meta.softDeleteField;
+      if (!softDeleteField) {
+        throw new Error(
+          `Table "${name}" does not have a soft delete field. Use .db.softDelete() to mark a field for soft delete.`
+        );
+      }
+      const whereTemplate = createTemplate(
+        makeTemplate(["WHERE ", ".", " IS NULL"]),
+        [ident(name), ident(softDeleteField)]
+      );
+      const activeViewName = `${name}_active`;
+      const activeView = createViewObject(
+        activeViewName,
+        table2,
+        whereTemplate
+      );
+      if (!internalMeta.activeView) {
+        internalMeta.activeView = activeView;
+      }
+      return activeView;
     }
   };
   return table2;
@@ -1250,7 +1386,25 @@ function extractFieldMeta(name, zodType, dbMeta) {
   }
   return meta;
 }
-function decodeData(table2, data) {
+function inferFieldType(schema) {
+  let core = schema;
+  while (typeof core.unwrap === "function") {
+    if (core instanceof z.ZodArray || core instanceof z.ZodObject || core instanceof z.ZodDate || core instanceof z.ZodBoolean || core instanceof z.ZodNumber) {
+      break;
+    }
+    core = core.unwrap();
+  }
+  if (core instanceof z.ZodDate)
+    return "datetime";
+  if (core instanceof z.ZodBoolean)
+    return "boolean";
+  if (core instanceof z.ZodObject || core instanceof z.ZodArray)
+    return "json";
+  if (core instanceof z.ZodNumber)
+    return "real";
+  return "text";
+}
+function decodeData(table2, data, driver) {
   if (!data)
     return data;
   const decoded = {};
@@ -1260,10 +1414,13 @@ function decodeData(table2, data) {
     const fieldSchema = shape?.[key];
     if (fieldMeta?.decode && typeof fieldMeta.decode === "function") {
       decoded[key] = fieldMeta.decode(value);
+    } else if (driver?.decodeValue && fieldSchema) {
+      const fieldType = inferFieldType(fieldSchema);
+      decoded[key] = driver.decodeValue(value, fieldType);
     } else if (fieldSchema) {
       let core = fieldSchema;
       while (typeof core.unwrap === "function") {
-        if (core instanceof z.ZodArray || core instanceof z.ZodObject) {
+        if (core instanceof z.ZodArray || core instanceof z.ZodObject || core instanceof z.ZodBoolean || core instanceof z.ZodDate) {
           break;
         }
         core = core.unwrap();
@@ -1280,9 +1437,20 @@ function decodeData(table2, data) {
         } else {
           decoded[key] = value;
         }
+      } else if (core instanceof z.ZodBoolean) {
+        if (typeof value === "number") {
+          decoded[key] = value !== 0;
+        } else if (typeof value === "string") {
+          decoded[key] = value !== "0" && value !== "";
+        } else if (typeof value === "boolean") {
+          decoded[key] = value;
+        } else {
+          decoded[key] = value;
+        }
       } else if (core instanceof z.ZodDate) {
         if (typeof value === "string") {
-          const date = new Date(value);
+          const normalized = value.includes("T") ? value : value.replace(" ", "T") + "Z";
+          const date = new Date(normalized);
           if (isNaN(date.getTime())) {
             throw new Error(
               `Invalid date value for field "${key}": "${value}" cannot be parsed as a valid date`
@@ -1341,6 +1509,10 @@ export {
   validateWithStandardSchema,
   extendZod,
   getTableMeta,
+  isView,
+  getViewMeta,
+  view,
   table,
+  inferFieldType,
   decodeData
 };

package/ddl-2A2UFUR3.js

@@ -0,0 +1,11 @@
+import {
+  generateColumnDDL,
+  generateDDL,
+  generateViewDDL
+} from "./chunk-CHF7L5PC.js";
+import "./chunk-XHXMCOSW.js";
+export {
+  generateColumnDDL,
+  generateDDL,
+  generateViewDDL
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@b9g/zen",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "The simple database client. Define tables. Write SQL. Get objects.",
   "keywords": [
     "database",

package/src/bun.d.ts

@@ -4,7 +4,7 @@
  * Unified driver supporting PostgreSQL, MySQL, and SQLite via Bun's built-in SQL.
  * Zero dependencies - uses native Bun implementation.
  */
-import type { Driver, Table, EnsureResult } from "./zen.js";
+import type { Driver, Table, View, EnsureResult } from "./zen.js";
 /**
  * Bun driver using Bun's built-in SQL.
  * Supports PostgreSQL, MySQL, and SQLite with automatic dialect detection.
@@ -34,9 +34,20 @@ export default class BunDriver implements Driver {
     run(strings: TemplateStringsArray, values: unknown[]): Promise<number>;
     val<T>(strings: TemplateStringsArray, values: unknown[]): Promise<T | null>;
     close(): Promise<void>;
+    /**
+     * Encode a JS value for database insertion.
+     * Dialect-aware: PostgreSQL uses native types, SQLite/MySQL need conversion.
+     */
+    encodeValue(value: unknown, fieldType: string): unknown;
+    /**
+     * Decode a database value to JS.
+     * Dialect-aware: handles differences in how values are returned.
+     */
+    decodeValue(value: unknown, fieldType: string): unknown;
     transaction<T>(fn: (txDriver: Driver) => Promise<T>): Promise<T>;
     withMigrationLock<T>(fn: () => Promise<T>): Promise<T>;
     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>;
     /**
      * Optional introspection: list columns for a table.

package/src/bun.js

@@ -3,13 +3,15 @@ import {
   placeholder,
   quoteIdent,
   renderDDL
-} from "../chunk-2IEEEMRN.js";
+} from "../chunk-W7JTNEM4.js";
 import {
-  generateDDL
-} from "../chunk-QXGEP5PB.js";
+  generateDDL,
+  generateViewDDL
+} from "../chunk-CHF7L5PC.js";
 import {
+  getTableMeta,
   resolveSQLBuiltin
-} from "../chunk-56M5Z3A6.js";
+} from "../chunk-XHXMCOSW.js";
 
 // src/bun.ts
 import { SQL } from "bun";
@@ -227,13 +229,103 @@ var BunDriver = class {
   async close() {
     await this.#sql.close();
   }
+  // ==========================================================================
+  // Type Encoding/Decoding
+  // ==========================================================================
+  /**
+   * Encode a JS value for database insertion.
+   * Dialect-aware: PostgreSQL uses native types, SQLite/MySQL need conversion.
+   */
+  encodeValue(value, fieldType) {
+    if (value === null || value === void 0) {
+      return value;
+    }
+    switch (fieldType) {
+      case "datetime":
+        if (value instanceof Date && !isNaN(value.getTime())) {
+          if (this.#dialect === "postgresql") {
+            return value;
+          } else if (this.#dialect === "mysql") {
+            return value.toISOString().replace("T", " ").slice(0, 23);
+          } else {
+            return value.toISOString();
+          }
+        }
+        return value;
+      case "boolean":
+        if (this.#dialect === "postgresql") {
+          return value;
+        }
+        return value ? 1 : 0;
+      case "json":
+        return JSON.stringify(value);
+      default:
+        return value;
+    }
+  }
+  /**
+   * Decode a database value to JS.
+   * Dialect-aware: handles differences in how values are returned.
+   */
+  decodeValue(value, fieldType) {
+    if (value === null || value === void 0) {
+      return value;
+    }
+    switch (fieldType) {
+      case "datetime":
+        if (value instanceof Date) {
+          if (isNaN(value.getTime())) {
+            throw new Error(`Invalid Date object received from database`);
+          }
+          return value;
+        }
+        if (typeof value === "string") {
+          let date;
+          if (this.#dialect === "mysql") {
+            const normalized = value.includes("T") ? value : value.replace(" ", "T") + "Z";
+            date = new Date(normalized);
+          } else {
+            date = new Date(value);
+          }
+          if (isNaN(date.getTime())) {
+            throw new Error(
+              `Invalid date value: "${value}" cannot be parsed as a valid date`
+            );
+          }
+          return date;
+        }
+        return value;
+      case "boolean":
+        if (this.#dialect === "postgresql") {
+          return value;
+        }
+        if (typeof value === "number") {
+          return value !== 0;
+        }
+        if (typeof value === "string") {
+          return value !== "0" && value !== "";
+        }
+        return value;
+      case "json":
+        if (typeof value === "string") {
+          return JSON.parse(value);
+        }
+        return value;
+      default:
+        return value;
+    }
+  }
   async transaction(fn) {
     const dialect = this.#dialect;
     const handleError = this.#handleError.bind(this);
     const supportsReturning = this.supportsReturning;
+    const encodeValue = this.encodeValue.bind(this);
+    const decodeValue = this.decodeValue.bind(this);
     return await this.#sql.transaction(async (txSql) => {
       const txDriver = {
         supportsReturning,
+        encodeValue,
+        decodeValue,
         all: async (strings, values) => {
           try {
             const { sql, params } = buildSQL(strings, values, dialect);
@@ -359,6 +451,9 @@ var BunDriver = class {
         step = 4;
         await this.#checkMissingConstraints(table);
       }
+      step = 5;
+      const viewApplied = await this.#ensureViews(table);
+      applied = applied || viewApplied;
       return { applied };
     } catch (error) {
       if (error instanceof SchemaDriftError || error instanceof EnsureError) {
@@ -371,6 +466,19 @@ var BunDriver = class {
       );
     }
   }
+  async ensureView(viewObj) {
+    await this.#ensureSqliteInit();
+    const ddlTemplate = generateViewDDL(viewObj, { dialect: this.#dialect });
+    const ddlSQL = renderDDL(
+      ddlTemplate[0],
+      ddlTemplate.slice(1),
+      this.#dialect
+    );
+    for (const stmt of ddlSQL.split(";").filter((s) => s.trim())) {
+      await this.#sql.unsafe(stmt.trim(), []);
+    }
+    return { applied: true };
+  }
   async ensureConstraints(table) {
     await this.#ensureSqliteInit();
     const tableName = table.name;
@@ -634,7 +742,7 @@ var BunDriver = class {
     return applied;
   }
   async #addColumn(table, fieldName) {
-    const { generateColumnDDL } = await import("../ddl-NAJM37GQ.js");
+    const { generateColumnDDL } = await import("../ddl-2A2UFUR3.js");
     const zodType = table.schema.shape[fieldName];
     const fieldMeta = table.meta.fields[fieldName] || {};
     const colTemplate = generateColumnDDL(
@@ -673,6 +781,30 @@ var BunDriver = class {
     }
     return applied;
   }
+  /**
+   * Ensure the active view exists for this table (if it has soft delete).
+   * Creates the view using generateViewDDL.
+   */
+  async #ensureViews(table) {
+    const meta = getTableMeta(table);
+    if (meta.softDeleteField && !meta.activeView) {
+      void table.active;
+    }
+    const activeView = meta.activeView;
+    if (!activeView) {
+      return false;
+    }
+    const ddlTemplate = generateViewDDL(activeView, { dialect: this.#dialect });
+    const ddlSQL = renderDDL(
+      ddlTemplate[0],
+      ddlTemplate.slice(1),
+      this.#dialect
+    );
+    for (const stmt of ddlSQL.split(";").filter((s) => s.trim())) {
+      await this.#sql.unsafe(stmt.trim(), []);
+    }
+    return true;
+  }
   async #createIndex(tableName, indexName, columns, unique) {
     const uniqueKw = unique ? "UNIQUE " : "";
     const colList = columns.map((c) => quoteIdent(c, this.#dialect)).join(", ");