@b9g/zen 0.1.0

package/chunk-56M5Z3A6.js

@@ -0,0 +1,1346 @@
+// src/impl/errors.ts
+var DatabaseError = class extends Error {
+  code;
+  constructor(code, message, options) {
+    super(message, options);
+    this.name = "DatabaseError";
+    this.code = code;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+};
+var ValidationError = class extends DatabaseError {
+  fieldErrors;
+  constructor(message, fieldErrors = {}, options) {
+    super("VALIDATION_ERROR", message, options);
+    this.name = "ValidationError";
+    this.fieldErrors = fieldErrors;
+  }
+};
+var TableDefinitionError = class extends DatabaseError {
+  tableName;
+  fieldName;
+  constructor(message, tableName, fieldName, options) {
+    super("TABLE_DEFINITION_ERROR", message, options);
+    this.name = "TableDefinitionError";
+    this.tableName = tableName;
+    this.fieldName = fieldName;
+  }
+};
+var MigrationError = class extends DatabaseError {
+  fromVersion;
+  toVersion;
+  constructor(message, fromVersion, toVersion, options) {
+    super("MIGRATION_ERROR", message, options);
+    this.name = "MigrationError";
+    this.fromVersion = fromVersion;
+    this.toVersion = toVersion;
+  }
+};
+var MigrationLockError = class extends DatabaseError {
+  constructor(message, options) {
+    super("MIGRATION_LOCK_ERROR", message, options);
+    this.name = "MigrationLockError";
+  }
+};
+var QueryError = class extends DatabaseError {
+  sql;
+  constructor(message, sql, options) {
+    super("QUERY_ERROR", message, options);
+    this.name = "QueryError";
+    this.sql = sql;
+  }
+};
+var NotFoundError = class extends DatabaseError {
+  tableName;
+  id;
+  constructor(tableName, id, options) {
+    const message = id ? `${tableName} with id "${id}" not found` : `${tableName} not found`;
+    super("NOT_FOUND", message, options);
+    this.name = "NotFoundError";
+    this.tableName = tableName;
+    this.id = id;
+  }
+};
+var AlreadyExistsError = class extends DatabaseError {
+  tableName;
+  field;
+  value;
+  constructor(tableName, field, value, options) {
+    const message = field ? `${tableName} with ${field}="${value}" already exists` : `${tableName} already exists`;
+    super("ALREADY_EXISTS", message, options);
+    this.name = "AlreadyExistsError";
+    this.tableName = tableName;
+    this.field = field;
+    this.value = value;
+  }
+};
+var ConstraintViolationError = class extends DatabaseError {
+  /**
+   * Type of constraint that was violated.
+   * "unknown" if the specific type couldn't be determined from the error.
+   */
+  kind;
+  /**
+   * Name of the constraint (e.g., "users_email_unique", "users.email").
+   * May be undefined if the database error didn't include it.
+   */
+  constraint;
+  /**
+   * Table name where the violation occurred.
+   * May be undefined if not extractable from the error.
+   */
+  table;
+  /**
+   * Column name involved in the violation.
+   * May be undefined if not extractable from the error.
+   */
+  column;
+  constructor(message, details, options) {
+    super("CONSTRAINT_VIOLATION", message, options);
+    this.name = "ConstraintViolationError";
+    this.kind = details.kind;
+    this.constraint = details.constraint;
+    this.table = details.table;
+    this.column = details.column;
+  }
+};
+var ConnectionError = class extends DatabaseError {
+  constructor(message, options) {
+    super("CONNECTION_ERROR", message, options);
+    this.name = "ConnectionError";
+  }
+};
+var TransactionError = class extends DatabaseError {
+  constructor(message, options) {
+    super("TRANSACTION_ERROR", message, options);
+    this.name = "TransactionError";
+  }
+};
+var EnsureError = class extends DatabaseError {
+  /** The operation that failed */
+  operation;
+  /** The table being operated on */
+  table;
+  /** The step index where failure occurred (0-based) */
+  step;
+  constructor(message, details, options) {
+    super("ENSURE_ERROR", message, options);
+    this.name = "EnsureError";
+    this.operation = details.operation;
+    this.table = details.table;
+    this.step = details.step;
+  }
+};
+var SchemaDriftError = class extends DatabaseError {
+  /** The table where drift was detected */
+  table;
+  /** Description of what drifted */
+  drift;
+  /** Suggested action to resolve */
+  suggestion;
+  constructor(message, details, options) {
+    super("SCHEMA_DRIFT_ERROR", message, options);
+    this.name = "SchemaDriftError";
+    this.table = details.table;
+    this.drift = details.drift;
+    this.suggestion = details.suggestion;
+  }
+};
+var ConstraintPreflightError = class extends DatabaseError {
+  /** The table being constrained */
+  table;
+  /** The constraint being added (e.g., "unique:email" or "fk:authorId") */
+  constraint;
+  /** Number of violating rows */
+  violationCount;
+  /** The SQL query that found the violations - run it to see details */
+  query;
+  constructor(message, details, options) {
+    super("CONSTRAINT_PREFLIGHT_ERROR", message, options);
+    this.name = "ConstraintPreflightError";
+    this.table = details.table;
+    this.constraint = details.constraint;
+    this.violationCount = details.violationCount;
+    this.query = details.query;
+  }
+};
+function isDatabaseError(error) {
+  return error instanceof DatabaseError;
+}
+function hasErrorCode(error, code) {
+  return isDatabaseError(error) && error.code === code;
+}
+
+// src/impl/builtins.ts
+var CURRENT_TIMESTAMP = Symbol.for("@b9g/zen:CURRENT_TIMESTAMP");
+var CURRENT_DATE = Symbol.for("@b9g/zen:CURRENT_DATE");
+var CURRENT_TIME = Symbol.for("@b9g/zen:CURRENT_TIME");
+var NOW = CURRENT_TIMESTAMP;
+var TODAY = CURRENT_DATE;
+function isSQLBuiltin(value) {
+  if (typeof value !== "symbol")
+    return false;
+  const key = Symbol.keyFor(value);
+  return key === "@b9g/zen:CURRENT_TIMESTAMP" || key === "@b9g/zen:CURRENT_DATE" || key === "@b9g/zen:CURRENT_TIME";
+}
+function resolveSQLBuiltin(sym) {
+  const key = Symbol.keyFor(sym);
+  if (!key?.startsWith("@b9g/zen:")) {
+    throw new Error(`Unknown SQL builtin: ${String(sym)}`);
+  }
+  return key.slice("@b9g/zen:".length);
+}
+
+// src/impl/template.ts
+var SQL_TEMPLATE = Symbol.for("@b9g/zen:template");
+function createTemplate(strings, values = []) {
+  const tuple = [strings, ...values];
+  return Object.assign(tuple, { [SQL_TEMPLATE]: true });
+}
+function isSQLTemplate(value) {
+  return Array.isArray(value) && Object.prototype.hasOwnProperty.call(value, SQL_TEMPLATE) && value[SQL_TEMPLATE] === true;
+}
+var SQL_IDENT = Symbol.for("@b9g/zen:ident");
+function ident(name) {
+  return { [SQL_IDENT]: true, name };
+}
+function isSQLIdentifier(value) {
+  return value !== null && typeof value === "object" && SQL_IDENT in value && value[SQL_IDENT] === true;
+}
+function makeTemplate(parts) {
+  return Object.assign([...parts], { raw: parts });
+}
+
+// src/impl/table.ts
+import { z } from "zod";
+function validateIdentifier(name, type) {
+  const controlCharRegex = /[\x00-\x1f\x7f]/;
+  if (controlCharRegex.test(name)) {
+    throw new TableDefinitionError(
+      // eslint-disable-next-line no-control-regex
+      `Invalid ${type} identifier "${name.replace(/[\x00-\x1f\x7f]/g, "\\x")}": ${type} names cannot contain control characters`
+    );
+  }
+  if (name.includes(";")) {
+    throw new TableDefinitionError(
+      `Invalid ${type} identifier "${name}": ${type} names cannot contain semicolons`
+    );
+  }
+  if (name.includes("`")) {
+    throw new TableDefinitionError(
+      `Invalid ${type} identifier "${name}": ${type} names cannot contain backticks`
+    );
+  }
+}
+function validateWithStandardSchema(schema, data) {
+  const standard = schema["~standard"];
+  if (!standard?.validate) {
+    throw new Error(
+      "Schema does not implement Standard Schema (~standard.validate). Ensure you're using Zod v3.23+ or another Standard Schema-compliant library."
+    );
+  }
+  const result = standard.validate(data);
+  if (result && typeof result.then === "function") {
+    throw new Error(
+      "Async validation is not supported. Standard Schema validate() must be synchronous."
+    );
+  }
+  if (result.issues) {
+    throw new ValidationError(
+      "Validation failed",
+      result.issues.reduce(
+        (acc, issue) => {
+          const path = issue.path && issue.path.length > 0 ? issue.path.map(String).join(".") : "_root";
+          if (!acc[path])
+            acc[path] = [];
+          acc[path].push(issue.message);
+          return acc;
+        },
+        {}
+      )
+    );
+  }
+  return result.value;
+}
+var DB_META_NAMESPACE = "db";
+function getDBMeta(schema) {
+  try {
+    const meta = typeof schema.meta === "function" ? schema.meta() : {};
+    const dbMeta = meta?.[DB_META_NAMESPACE];
+    if (dbMeta && Object.keys(dbMeta).length > 0) {
+      return dbMeta;
+    }
+    if (schema instanceof z.ZodOptional || schema instanceof z.ZodNullable) {
+      return getDBMeta(schema.unwrap());
+    }
+    if (schema instanceof z.ZodDefault) {
+      return getDBMeta(schema.removeDefault());
+    }
+    if (schema instanceof z.ZodCatch) {
+      return getDBMeta(schema.removeCatch());
+    }
+    return {};
+  } catch {
+    return {};
+  }
+}
+function setDBMeta(schema, dbMeta) {
+  const existing = (typeof schema.meta === "function" ? schema.meta() : void 0) ?? {};
+  return schema.meta({
+    ...existing,
+    [DB_META_NAMESPACE]: {
+      ...existing[DB_META_NAMESPACE] ?? {},
+      ...dbMeta
+    }
+  });
+}
+function isTemplateStringsArray(value) {
+  return Array.isArray(value) && "raw" in value;
+}
+function mergeFragment(strings, values, template, suffix) {
+  const templateStrings = template[0];
+  const templateValues = template.slice(1);
+  strings[strings.length - 1] += templateStrings[0];
+  for (let j = 1; j < templateStrings.length; j++) {
+    strings.push(templateStrings[j]);
+  }
+  values.push(...templateValues);
+  strings[strings.length - 1] += suffix;
+}
+function hasZodDefault(schema) {
+  return typeof schema.removeDefault === "function";
+}
+function isUuidSchema(schema) {
+  return schema instanceof z.ZodString && schema.format === "uuid";
+}
+function isIntSchema(schema) {
+  if (!(schema instanceof z.ZodNumber))
+    return false;
+  const checks = schema._def?.checks;
+  if (!Array.isArray(checks))
+    return false;
+  return checks.some((c) => c.isInt === true);
+}
+function createDBMethods(schema) {
+  return {
+    /**
+     * Mark field as primary key.
+     * @example z.string().uuid().db.primary()
+     */
+    primary() {
+      return setDBMeta(schema, { primary: true });
+    },
+    /**
+     * Mark field as unique.
+     * @example z.string().email().db.unique()
+     */
+    unique() {
+      return setDBMeta(schema, { unique: true });
+    },
+    /**
+     * Create an index on this field.
+     * @example z.date().db.index()
+     */
+    index() {
+      return setDBMeta(schema, { indexed: true });
+    },
+    /**
+     * Mark field as soft delete timestamp.
+     * @example z.date().nullable().default(null).db.softDelete()
+     */
+    softDelete() {
+      return setDBMeta(schema, { softDelete: true });
+    },
+    /**
+     * Define a foreign key reference with optional reverse relationship.
+     *
+     * @example
+     * // Forward reference only
+     * authorId: z.string().uuid().db.references(Users, "author")
+     *
+     * @example
+     * // With options
+     * authorId: z.string().uuid().db.references(Users, "author", {
+     *   reverseAs: "posts",   // user.posts = Post[]
+     *   ondelete: "cascade",
+     * })
+     */
+    references(table2, as, options) {
+      return setDBMeta(schema, {
+        reference: {
+          table: table2,
+          as,
+          ...options
+        }
+      });
+    },
+    /**
+     * Encode app values to DB values (for INSERT/UPDATE).
+     * One-way transformation is fine (e.g., password hashing).
+     *
+     * @example
+     * password: z.string().db.encode(hashPassword)
+     *
+     * @example
+     * // Bidirectional: pair with .db.decode()
+     * status: z.enum(["pending", "active"])
+     *   .db.encode(s => statusMap.indexOf(s))
+     *   .db.decode(i => statusMap[i])
+     */
+    encode(encodeFn) {
+      const existing = getDBMeta(schema);
+      if (existing.inserted || existing.updated) {
+        throw new TableDefinitionError(
+          `encode() cannot be combined with inserted() or updated(). DB expressions bypass encoding and are sent directly to the database.`
+        );
+      }
+      return setDBMeta(schema, { encode: encodeFn });
+    },
+    /**
+     * Decode DB values to app values (for SELECT).
+     * One-way transformation is fine.
+     *
+     * @example
+     * legacy: z.string().db.decode(deserializeLegacyFormat)
+     */
+    decode(decodeFn) {
+      const existing = getDBMeta(schema);
+      if (existing.inserted || existing.updated) {
+        throw new TableDefinitionError(
+          `decode() cannot be combined with inserted() or updated(). DB expressions bypass decoding and are sent directly to the database.`
+        );
+      }
+      return setDBMeta(schema, { decode: decodeFn });
+    },
+    /**
+     * Specify explicit column type for DDL generation.
+     * Required when using custom encode/decode on objects/arrays
+     * that transform to a different storage type.
+     *
+     * @example
+     * // Store array as CSV instead of JSON
+     * tags: z.array(z.string())
+     *   .db.encode((arr) => arr.join(","))
+     *   .db.decode((str) => str.split(","))
+     *   .db.type("TEXT")
+     */
+    type(columnType) {
+      return setDBMeta(schema, { columnType });
+    },
+    /**
+     * Set a value to apply on INSERT.
+     *
+     * Three forms:
+     * - Tagged template: .db.inserted`CURRENT_TIMESTAMP` → raw SQL
+     * - Symbol: .db.inserted(NOW) → dialect-aware SQL
+     * - Function: .db.inserted(() => "draft") → client-side per-insert
+     *
+     * Field becomes optional for insert.
+     *
+     * **Note:** SQL expressions (tagged templates and symbols) bypass encode/decode
+     * since they're executed by the database, not the application. Use function
+     * form if you need encoding applied.
+     *
+     * **Note:** Interpolated values in tagged templates are parameterized but not
+     * schema-validated. Ensure values are appropriate for the column type.
+     *
+     * @example
+     * createdAt: z.date().db.inserted(NOW)
+     * token: z.string().db.inserted(() => crypto.randomUUID())
+     * slug: z.string().db.inserted`LOWER(name)`
+     */
+    inserted(stringsOrValue, ...templateValues) {
+      let insertedMeta;
+      if (isTemplateStringsArray(stringsOrValue)) {
+        const strings = [];
+        const values = [];
+        for (let i = 0; i < stringsOrValue.length; i++) {
+          if (i === 0) {
+            strings.push(stringsOrValue[i]);
+          }
+          if (i < templateValues.length) {
+            const value = templateValues[i];
+            if (isSQLTemplate(value)) {
+              mergeFragment(strings, values, value, stringsOrValue[i + 1]);
+            } else {
+              values.push(value);
+              strings.push(stringsOrValue[i + 1]);
+            }
+          }
+        }
+        insertedMeta = {
+          type: "sql",
+          template: createTemplate(makeTemplate(strings), values)
+        };
+      } else if (isSQLBuiltin(stringsOrValue)) {
+        insertedMeta = { type: "symbol", symbol: stringsOrValue };
+      } else if (typeof stringsOrValue === "function") {
+        insertedMeta = { type: "function", fn: stringsOrValue };
+      } else {
+        throw new TableDefinitionError(
+          `inserted() requires a tagged template, symbol (NOW), or function. Got: ${typeof stringsOrValue}`
+        );
+      }
+      const existing = getDBMeta(schema);
+      if (existing.encode || existing.decode) {
+        throw new TableDefinitionError(
+          `inserted() cannot be combined with encode() or decode(). DB expressions and functions bypass encoding/decoding.`
+        );
+      }
+      const optionalSchema = schema.optional();
+      return setDBMeta(optionalSchema, { ...existing, inserted: insertedMeta });
+    },
+    /**
+     * Set a value to apply on UPDATE only.
+     *
+     * Same forms as inserted(). See inserted() for notes on codec bypass
+     * and template parameter validation.
+     *
+     * Field becomes optional for update operations.
+     *
+     * @example
+     * modifiedAt: z.date().db.updated(NOW)
+     * lastModified: z.date().db.updated(() => new Date())
+     */
+    updated(stringsOrValue, ...templateValues) {
+      let updatedMeta;
+      if (isTemplateStringsArray(stringsOrValue)) {
+        const strings = [];
+        const values = [];
+        for (let i = 0; i < stringsOrValue.length; i++) {
+          if (i === 0) {
+            strings.push(stringsOrValue[i]);
+          }
+          if (i < templateValues.length) {
+            const value = templateValues[i];
+            if (isSQLTemplate(value)) {
+              mergeFragment(strings, values, value, stringsOrValue[i + 1]);
+            } else {
+              values.push(value);
+              strings.push(stringsOrValue[i + 1]);
+            }
+          }
+        }
+        updatedMeta = {
+          type: "sql",
+          template: createTemplate(makeTemplate(strings), values)
+        };
+      } else if (isSQLBuiltin(stringsOrValue)) {
+        updatedMeta = { type: "symbol", symbol: stringsOrValue };
+      } else if (typeof stringsOrValue === "function") {
+        updatedMeta = { type: "function", fn: stringsOrValue };
+      } else {
+        throw new TableDefinitionError(
+          `updated() requires a tagged template, symbol (NOW), or function. Got: ${typeof stringsOrValue}`
+        );
+      }
+      const existing = getDBMeta(schema);
+      if (existing.encode || existing.decode) {
+        throw new TableDefinitionError(
+          `updated() cannot be combined with encode() or decode(). DB expressions and functions bypass encoding/decoding.`
+        );
+      }
+      const optionalSchema = schema.optional();
+      return setDBMeta(optionalSchema, { ...existing, updated: updatedMeta });
+    },
+    /**
+     * Set a value to apply on both INSERT and UPDATE.
+     *
+     * Same forms as inserted(). See inserted() for notes on codec bypass
+     * and template parameter validation.
+     *
+     * Field becomes optional for insert/update.
+     *
+     * @example
+     * updatedAt: z.date().db.upserted(NOW)
+     * lastModified: z.date().db.upserted(() => new Date())
+     */
+    upserted(stringsOrValue, ...templateValues) {
+      let upsertedMeta;
+      if (isTemplateStringsArray(stringsOrValue)) {
+        const strings = [];
+        const values = [];
+        for (let i = 0; i < stringsOrValue.length; i++) {
+          if (i === 0) {
+            strings.push(stringsOrValue[i]);
+          }
+          if (i < templateValues.length) {
+            const value = templateValues[i];
+            if (isSQLTemplate(value)) {
+              mergeFragment(strings, values, value, stringsOrValue[i + 1]);
+            } else {
+              values.push(value);
+              strings.push(stringsOrValue[i + 1]);
+            }
+          }
+        }
+        upsertedMeta = {
+          type: "sql",
+          template: createTemplate(makeTemplate(strings), values)
+        };
+      } else if (isSQLBuiltin(stringsOrValue)) {
+        upsertedMeta = { type: "symbol", symbol: stringsOrValue };
+      } else if (typeof stringsOrValue === "function") {
+        upsertedMeta = { type: "function", fn: stringsOrValue };
+      } else {
+        throw new TableDefinitionError(
+          `upserted() requires a tagged template, symbol (NOW), or function. Got: ${typeof stringsOrValue}`
+        );
+      }
+      const existing = getDBMeta(schema);
+      if (existing.encode || existing.decode) {
+        throw new TableDefinitionError(
+          `upserted() cannot be combined with encode() or decode(). DB expressions and functions bypass encoding/decoding.`
+        );
+      }
+      const optionalSchema = schema.optional();
+      return setDBMeta(optionalSchema, { ...existing, upserted: upsertedMeta });
+    },
+    /**
+     * Auto-generate value on insert based on field type.
+     *
+     * Type-aware behavior:
+     * - `z.string().uuid()` → generates UUID via `crypto.randomUUID()`
+     * - `z.number().int()` on primary key → auto-increment (database-side)
+     * - `z.date()` → current timestamp via NOW
+     *
+     * Field becomes optional for insert.
+     *
+     * @example
+     * id: z.string().uuid().db.primary().db.auto()
+     * // → crypto.randomUUID() on insert
+     *
+     * @example
+     * id: z.number().int().db.primary().db.auto()
+     * // → auto-increment
+     *
+     * @example
+     * createdAt: z.date().db.auto()
+     * // → NOW on insert
+     */
+    auto() {
+      const existing = getDBMeta(schema);
+      const optionalSchema = schema.optional();
+      if (isUuidSchema(schema)) {
+        const insertedMeta = {
+          type: "function",
+          fn: () => crypto.randomUUID()
+        };
+        return setDBMeta(optionalSchema, { ...existing, inserted: insertedMeta });
+      }
+      if (isIntSchema(schema)) {
+        return setDBMeta(optionalSchema, { ...existing, autoIncrement: true });
+      }
+      if (schema instanceof z.ZodDate) {
+        const insertedMeta = {
+          type: "symbol",
+          symbol: NOW
+        };
+        return setDBMeta(optionalSchema, { ...existing, inserted: insertedMeta });
+      }
+      throw new Error(
+        `.db.auto() is not supported for this type. Supported: z.string().uuid(), z.number().int(), z.date()`
+      );
+    }
+  };
+}
+function extendZod(zodModule) {
+  for (const key of Object.keys(zodModule)) {
+    const value = zodModule[key];
+    if (typeof value === "function" && value.prototype && key.startsWith("Zod")) {
+      if (!("db" in value.prototype)) {
+        Object.defineProperty(value.prototype, "db", {
+          get() {
+            return createDBMethods(this);
+          },
+          enumerable: false,
+          configurable: true
+        });
+      }
+    }
+  }
+}
+extendZod(z);
+var TABLE_MARKER = Symbol.for("@b9g/zen:table");
+var TABLE_META = Symbol.for("@b9g/zen:table-meta");
+function getTableMeta(table2) {
+  return table2[TABLE_META];
+}
+function table(name, shape, options = {}) {
+  validateIdentifier(name, "table");
+  if (name.includes(".")) {
+    throw new TableDefinitionError(
+      `Invalid table name "${name}": table names cannot contain "." as it conflicts with normalization prefixes`,
+      name
+    );
+  }
+  const zodShape = {};
+  const meta = {
+    primary: null,
+    unique: [],
+    indexed: [],
+    softDeleteField: null,
+    references: [],
+    fields: {}
+  };
+  for (const [key, value] of Object.entries(shape)) {
+    validateIdentifier(key, "column");
+    if (key.includes(".")) {
+      throw new TableDefinitionError(
+        `Invalid field name "${key}" in table "${name}": field names cannot contain "." as it conflicts with normalization prefixes`,
+        name,
+        key
+      );
+    }
+    const fieldSchema = value;
+    zodShape[key] = fieldSchema;
+    if (hasZodDefault(fieldSchema)) {
+      throw new TableDefinitionError(
+        `Field "${key}" uses Zod .default() which applies at parse time, not write time. Use .db.inserted() or .db.updated() instead.`,
+        name,
+        key
+      );
+    }
+    const fieldDBMeta = getDBMeta(fieldSchema);
+    const dbMeta = {};
+    if (fieldDBMeta.primary) {
+      if (meta.primary !== null) {
+        throw new TableDefinitionError(
+          `Table "${name}" has multiple primary keys: "${meta.primary}" and "${key}". Only one primary key is allowed.`,
+          name
+        );
+      }
+      meta.primary = key;
+      dbMeta.primaryKey = true;
+    }
+    if (fieldDBMeta.unique) {
+      meta.unique.push(key);
+      dbMeta.unique = true;
+    }
+    if (fieldDBMeta.indexed) {
+      meta.indexed.push(key);
+      dbMeta.indexed = true;
+    }
+    if (fieldDBMeta.softDelete) {
+      if (meta.softDeleteField !== null) {
+        throw new TableDefinitionError(
+          `Table "${name}" has multiple soft delete fields: "${meta.softDeleteField}" and "${key}". Only one soft delete field is allowed.`,
+          name
+        );
+      }
+      meta.softDeleteField = key;
+      dbMeta.softDelete = true;
+    }
+    if (fieldDBMeta.reference) {
+      const ref = fieldDBMeta.reference;
+      if (ref.as in shape) {
+        throw new TableDefinitionError(
+          `Table "${name}": reference property "${ref.as}" (from field "${key}") collides with existing schema field. Choose a different 'as' name.`,
+          name,
+          key
+        );
+      }
+      if (options.derive && ref.as in options.derive) {
+        throw new TableDefinitionError(
+          `Table "${name}": reference property "${ref.as}" (from field "${key}") collides with derived property. Choose a different 'as' name.`,
+          name,
+          key
+        );
+      }
+      const existingRef = meta.references.find((r) => r.as === ref.as);
+      if (existingRef) {
+        throw new TableDefinitionError(
+          `Table "${name}": duplicate reference alias "${ref.as}" used by fields "${existingRef.fieldName}" and "${key}". Each reference must have a unique 'as' name.`,
+          name,
+          key
+        );
+      }
+      if (ref.reverseAs) {
+        const targetShape = ref.table.schema.shape;
+        if (ref.reverseAs in targetShape) {
+          throw new TableDefinitionError(
+            `Table "${name}": reverse reference property "${ref.reverseAs}" (from field "${key}") collides with existing field in target table "${ref.table.name}". Choose a different 'reverseAs' name.`,
+            name,
+            key
+          );
+        }
+      }
+      meta.references.push({
+        fieldName: key,
+        table: ref.table,
+        referencedField: ref.field ?? getTableMeta(ref.table).primary ?? "id",
+        as: ref.as,
+        reverseAs: ref.reverseAs,
+        onDelete: ref.onDelete
+      });
+      dbMeta.reference = ref;
+    }
+    if (fieldDBMeta.encode) {
+      dbMeta.encode = fieldDBMeta.encode;
+    }
+    if (fieldDBMeta.decode) {
+      dbMeta.decode = fieldDBMeta.decode;
+    }
+    if (fieldDBMeta.columnType) {
+      dbMeta.columnType = fieldDBMeta.columnType;
+    }
+    if (fieldDBMeta.inserted) {
+      dbMeta.inserted = fieldDBMeta.inserted;
+    }
+    if (fieldDBMeta.updated) {
+      dbMeta.updated = fieldDBMeta.updated;
+    }
+    if (fieldDBMeta.upserted) {
+      dbMeta.upserted = fieldDBMeta.upserted;
+    }
+    if (fieldDBMeta.autoIncrement) {
+      dbMeta.autoIncrement = fieldDBMeta.autoIncrement;
+    }
+    meta.fields[key] = dbMeta;
+  }
+  const schema = z.object(zodShape);
+  return createTableObject(name, schema, zodShape, meta, options);
+}
+function createColsProxy(tableName, zodShape) {
+  return new Proxy({}, {
+    get(_target, prop) {
+      if (prop in zodShape) {
+        return createTemplate(makeTemplate(["", ".", ""]), [
+          ident(tableName),
+          ident(prop)
+        ]);
+      }
+      return void 0;
+    },
+    has(_target, prop) {
+      return prop in zodShape;
+    },
+    ownKeys() {
+      return Object.keys(zodShape);
+    },
+    getOwnPropertyDescriptor(_target, prop) {
+      if (prop in zodShape) {
+        return { enumerable: true, configurable: true };
+      }
+      return void 0;
+    }
+  });
+}
+function createTableObject(name, schema, zodShape, meta, options) {
+  const cols = createColsProxy(name, zodShape);
+  const primary = meta.primary ? createTemplate(makeTemplate(["", ".", ""]), [
+    ident(name),
+    ident(meta.primary)
+  ]) : null;
+  if (options.derive) {
+    for (const key of Object.keys(options.derive)) {
+      if (key in zodShape) {
+        throw new TableDefinitionError(
+          `Table "${name}": derived property "${key}" collides with existing schema field. Choose a different name.`,
+          name
+        );
+      }
+    }
+  }
+  const internalMeta = { ...meta, derive: options.derive };
+  const table2 = {
+    [TABLE_MARKER]: true,
+    [TABLE_META]: internalMeta,
+    name,
+    schema,
+    indexes: options.indexes ?? [],
+    unique: options.unique ?? [],
+    compoundReferences: options.references ?? [],
+    cols,
+    primary,
+    // Internal getter for backward compatibility - use getTableMeta() instead
+    get meta() {
+      return internalMeta;
+    },
+    fields() {
+      const result = {};
+      for (const [key, zodType] of Object.entries(zodShape)) {
+        const dbMeta = meta.fields[key] || {};
+        result[key] = extractFieldMeta(key, zodType, dbMeta);
+      }
+      for (const ref of meta.references) {
+        result[ref.as] = {
+          fields: () => ref.table.fields(),
+          table: ref.table
+        };
+      }
+      return result;
+    },
+    primaryKey() {
+      return meta.primary;
+    },
+    references() {
+      return meta.references;
+    },
+    deleted() {
+      const softDeleteField = meta.softDeleteField;
+      if (!softDeleteField) {
+        throw new Error(
+          `Table "${name}" does not have a soft delete field. Use softDelete() wrapper to mark a field.`
+        );
+      }
+      return createTemplate(makeTemplate(["", ".", " IS NOT NULL"]), [
+        ident(name),
+        ident(softDeleteField)
+      ]);
+    },
+    in(field, values) {
+      if (!(field in zodShape)) {
+        throw new Error(
+          `Field "${field}" does not exist in table "${name}". Available fields: ${Object.keys(zodShape).join(", ")}`
+        );
+      }
+      if (values.length === 0) {
+        return createTemplate(makeTemplate(["1 = 0"]), []);
+      }
+      const POSTGRESQL_PARAM_LIMIT = 32767;
+      if (values.length > POSTGRESQL_PARAM_LIMIT) {
+        throw new Error(
+          `Too many values in IN clause: ${values.length} exceeds PostgreSQL's parameter limit of ${POSTGRESQL_PARAM_LIMIT}. Consider using a temporary table or splitting the query.`
+        );
+      }
+      const strings = ["", ".", " IN ("];
+      const templateValues = [ident(name), ident(field)];
+      for (let i = 0; i < values.length; i++) {
+        templateValues.push(values[i]);
+        strings.push(i < values.length - 1 ? ", " : ")");
+      }
+      return createTemplate(makeTemplate(strings), templateValues);
+    },
+    pick(...fields) {
+      const fieldSet = new Set(fields);
+      const pickObj = {};
+      for (const f of fields) {
+        pickObj[f] = true;
+      }
+      const pickedSchema = schema.pick(pickObj);
+      const pickedZodShape = {};
+      for (const f of fields) {
+        if (f in zodShape) {
+          pickedZodShape[f] = zodShape[f];
+        }
+      }
+      const existingDerivedExprs = meta.derivedExprs ?? [];
+      const existingDerivedFields = meta.derivedFields ?? [];
+      const pickedDerivedExprs = existingDerivedExprs.filter(
+        (expr) => fieldSet.has(expr.fieldName)
+      );
+      const pickedDerivedFields = existingDerivedFields.filter(
+        (f) => fieldSet.has(f)
+      );
+      const pickedMeta = {
+        primary: meta.primary && fieldSet.has(meta.primary) ? meta.primary : null,
+        unique: meta.unique.filter((f) => fieldSet.has(f)),
+        indexed: meta.indexed.filter((f) => fieldSet.has(f)),
+        softDeleteField: meta.softDeleteField && fieldSet.has(meta.softDeleteField) ? meta.softDeleteField : null,
+        references: meta.references.filter((r) => fieldSet.has(r.fieldName)),
+        fields: Object.fromEntries(
+          Object.entries(meta.fields).filter(([k]) => fieldSet.has(k))
+        ),
+        isPartial: true,
+        isDerived: void 0,
+        derivedExprs: void 0,
+        derivedFields: void 0
+      };
+      if (pickedDerivedExprs.length > 0) {
+        pickedMeta.isDerived = true;
+        pickedMeta.derivedExprs = pickedDerivedExprs;
+        pickedMeta.derivedFields = pickedDerivedFields;
+      }
+      const pickedIndexes = (options.indexes ?? []).filter(
+        (idx) => idx.every((f) => fieldSet.has(f))
+      );
+      const pickedUnique = (options.unique ?? []).filter(
+        (u) => u.every((f) => fieldSet.has(f))
+      );
+      const pickedCompoundRefs = (options.references ?? []).filter(
+        (ref) => ref.fields.every((f) => fieldSet.has(f))
+      );
+      return createTableObject(name, pickedSchema, pickedZodShape, pickedMeta, {
+        indexes: pickedIndexes,
+        unique: pickedUnique,
+        references: pickedCompoundRefs
+      });
+    },
+    derive(fieldName, fieldType) {
+      return (stringsOrValue, ...templateValues) => {
+        const strings = [];
+        const values = [];
+        for (let i = 0; i < stringsOrValue.length; i++) {
+          if (i === 0) {
+            strings.push(stringsOrValue[i]);
+          }
+          if (i < templateValues.length) {
+            const value = templateValues[i];
+            if (isSQLTemplate(value)) {
+              mergeFragment(strings, values, value, stringsOrValue[i + 1]);
+            } else {
+              values.push(value);
+              strings.push(stringsOrValue[i + 1]);
+            }
+          }
+        }
+        if (strings.length > 0) {
+          strings[0] = strings[0].trimStart();
+          strings[strings.length - 1] = strings[strings.length - 1].trimEnd();
+        }
+        const derivedExpr = {
+          fieldName,
+          template: createTemplate(makeTemplate(strings), values)
+        };
+        const mergedSchema = schema.extend({ [fieldName]: fieldType });
+        const mergedZodShape = { ...zodShape, [fieldName]: fieldType };
+        const existingExprs = meta.derivedExprs ?? [];
+        const existingDerivedFields = meta.derivedFields ?? [];
+        const derivedMeta = {
+          ...meta,
+          isDerived: true,
+          derivedExprs: [...existingExprs, derivedExpr],
+          derivedFields: [...existingDerivedFields, fieldName],
+          fields: {
+            ...meta.fields,
+            [fieldName]: {}
+          }
+        };
+        return createTableObject(
+          name,
+          mergedSchema,
+          mergedZodShape,
+          derivedMeta,
+          options
+        );
+      };
+    },
+    set(values) {
+      const entries = Object.entries(values).filter(([, v]) => v !== void 0);
+      if (entries.length === 0) {
+        throw new Error("set() requires at least one non-undefined field");
+      }
+      const strings = [""];
+      const templateValues = [];
+      for (let i = 0; i < entries.length; i++) {
+        const [field, value] = entries[i];
+        templateValues.push(ident(field));
+        strings.push(" = ");
+        templateValues.push(value);
+        strings.push(i < entries.length - 1 ? ", " : "");
+      }
+      return createTemplate(makeTemplate(strings), templateValues);
+    },
+    on(referencingTable, alias) {
+      const refs = getTableMeta(referencingTable).references.filter(
+        (r) => r.table.name === name
+      );
+      if (refs.length === 0) {
+        throw new Error(
+          `Table "${referencingTable.name}" has no foreign key references to "${name}"`
+        );
+      }
+      let ref;
+      if (refs.length === 1) {
+        ref = refs[0];
+      } else if (alias) {
+        const found = refs.find((r) => r.as === alias);
+        if (!found) {
+          const availableAliases = refs.map((r) => `"${r.as}"`).join(", ");
+          throw new Error(
+            `No foreign key with alias "${alias}" found. Available aliases: ${availableAliases}`
+          );
+        }
+        ref = found;
+      } else {
+        const availableAliases = refs.map((r) => `"${r.as}"`).join(", ");
+        throw new Error(
+          `Multiple foreign keys from "${referencingTable.name}" to "${name}". Specify an alias: ${availableAliases}`
+        );
+      }
+      const tableRef = alias ?? name;
+      return createTemplate(makeTemplate(["", ".", " = ", ".", ""]), [
+        ident(tableRef),
+        ident(ref.referencedField),
+        ident(referencingTable.name),
+        ident(ref.fieldName)
+      ]);
+    },
+    values(rows) {
+      if (rows.length === 0) {
+        throw new Error("values() requires at least one row");
+      }
+      const columns = Object.keys(rows[0]);
+      if (columns.length === 0) {
+        throw new Error("values() requires at least one column");
+      }
+      const schemaKeys = Object.keys(schema.shape);
+      for (const col of columns) {
+        if (!schemaKeys.includes(col)) {
+          throw new TableDefinitionError(
+            `Column "${col}" does not exist in table schema`,
+            name,
+            col
+          );
+        }
+      }
+      const partialSchema = schema.partial();
+      const strings = ["("];
+      const templateValues = [];
+      for (let i = 0; i < columns.length; i++) {
+        templateValues.push(ident(columns[i]));
+        strings.push(i < columns.length - 1 ? ", " : ") VALUES ");
+      }
+      for (let rowIdx = 0; rowIdx < rows.length; rowIdx++) {
+        const row = rows[rowIdx];
+        const validated = validateWithStandardSchema(partialSchema, row);
+        strings[strings.length - 1] += "(";
+        for (let colIdx = 0; colIdx < columns.length; colIdx++) {
+          const col = columns[colIdx];
+          if (!(col in row)) {
+            throw new Error(
+              `All rows must have the same columns. Row is missing column "${col}"`
+            );
+          }
+          templateValues.push(validated[col]);
+          strings.push(colIdx < columns.length - 1 ? ", " : ")");
+        }
+        if (rowIdx < rows.length - 1) {
+          strings[strings.length - 1] += ", ";
+        }
+      }
+      return createTemplate(makeTemplate(strings), templateValues);
+    }
+  };
+  return table2;
+}
+function getLayerMeta(schema) {
+  if (typeof schema.meta === "function") {
+    return schema.meta() ?? {};
+  }
+  return {};
+}
+function unwrapType(schema) {
+  let core = schema;
+  let hasDefault = false;
+  let defaultValue = void 0;
+  const metaLayers = [];
+  const isOptional = schema.isOptional();
+  const isNullable = schema.isNullable();
+  while (true) {
+    metaLayers.push(getLayerMeta(core));
+    if (typeof core.removeDefault === "function") {
+      hasDefault = true;
+      try {
+        defaultValue = core.parse(void 0);
+      } catch {
+      }
+      core = core.removeDefault();
+      continue;
+    }
+    if (typeof core.unwrap === "function") {
+      core = core.unwrap();
+      continue;
+    }
+    if (typeof core.innerType === "function") {
+      core = core.innerType();
+      continue;
+    }
+    break;
+  }
+  const collectedMeta = {};
+  for (let i = metaLayers.length - 1; i >= 0; i--) {
+    Object.assign(collectedMeta, metaLayers[i]);
+  }
+  return {
+    core,
+    isOptional,
+    isNullable,
+    hasDefault,
+    defaultValue,
+    collectedMeta
+  };
+}
+function extractFieldMeta(name, zodType, dbMeta) {
+  const {
+    core,
+    isOptional,
+    isNullable,
+    hasDefault,
+    defaultValue,
+    collectedMeta
+  } = unwrapType(zodType);
+  const { db: _db, ...userMeta } = collectedMeta;
+  const meta = {
+    name,
+    type: "text",
+    required: !isOptional && !isNullable && !hasDefault,
+    ...userMeta
+    // Spread user-defined metadata (label, helpText, widget, etc.)
+  };
+  if (dbMeta.primaryKey)
+    meta.primaryKey = true;
+  if (dbMeta.unique)
+    meta.unique = true;
+  if (dbMeta.indexed)
+    meta.indexed = true;
+  if (dbMeta.softDelete)
+    meta.softDelete = true;
+  if (dbMeta.reference) {
+    meta.reference = {
+      table: dbMeta.reference.table,
+      field: dbMeta.reference.field ?? getTableMeta(dbMeta.reference.table).primary ?? "id",
+      as: dbMeta.reference.as,
+      onDelete: dbMeta.reference.onDelete
+    };
+  }
+  if (dbMeta.encode)
+    meta.encode = dbMeta.encode;
+  if (dbMeta.decode)
+    meta.decode = dbMeta.decode;
+  if (dbMeta.columnType)
+    meta.columnType = dbMeta.columnType;
+  if (dbMeta.autoIncrement)
+    meta.autoIncrement = true;
+  if (dbMeta.inserted)
+    meta.inserted = dbMeta.inserted;
+  if (dbMeta.updated)
+    meta.updated = dbMeta.updated;
+  if (dbMeta.upserted)
+    meta.upserted = dbMeta.upserted;
+  if (defaultValue !== void 0) {
+    meta.default = defaultValue;
+  }
+  if (core instanceof z.ZodString) {
+    meta.type = "text";
+    const str = core;
+    if (str.format === "email" || str.isEmail)
+      meta.type = "email";
+    if (str.format === "url" || str.isURL)
+      meta.type = "url";
+    if (str.maxLength !== void 0) {
+      meta.maxLength = str.maxLength;
+      if (str.maxLength > 500)
+        meta.type = "textarea";
+    }
+    if (str.minLength !== void 0) {
+      meta.minLength = str.minLength;
+    }
+  } else if (core instanceof z.ZodNumber) {
+    meta.type = "number";
+    const num = core;
+    if (num.format === "int" || num.isInt)
+      meta.type = "integer";
+    if (num.minValue !== void 0)
+      meta.min = num.minValue;
+    if (num.maxValue !== void 0)
+      meta.max = num.maxValue;
+  } else if (core instanceof z.ZodBoolean) {
+    meta.type = "checkbox";
+  } else if (core instanceof z.ZodDate) {
+    meta.type = "datetime";
+  } else if (core instanceof z.ZodEnum) {
+    meta.type = "select";
+    meta.options = core.options;
+  } else if (core instanceof z.ZodArray || core instanceof z.ZodObject) {
+    meta.type = "json";
+  }
+  return meta;
+}
+function decodeData(table2, data) {
+  if (!data)
+    return data;
+  const decoded = {};
+  const shape = table2.schema.shape;
+  for (const [key, value] of Object.entries(data)) {
+    const fieldMeta = getTableMeta(table2).fields[key];
+    const fieldSchema = shape?.[key];
+    if (fieldMeta?.decode && typeof fieldMeta.decode === "function") {
+      decoded[key] = fieldMeta.decode(value);
+    } else if (fieldSchema) {
+      let core = fieldSchema;
+      while (typeof core.unwrap === "function") {
+        if (core instanceof z.ZodArray || core instanceof z.ZodObject) {
+          break;
+        }
+        core = core.unwrap();
+      }
+      if (core instanceof z.ZodObject || core instanceof z.ZodArray) {
+        if (typeof value === "string") {
+          try {
+            decoded[key] = JSON.parse(value);
+          } catch (e) {
+            throw new Error(
+              `JSON parse error for field "${key}": ${e instanceof Error ? e.message : String(e)}. Value was: ${value.slice(0, 100)}${value.length > 100 ? "..." : ""}`
+            );
+          }
+        } else {
+          decoded[key] = value;
+        }
+      } else if (core instanceof z.ZodDate) {
+        if (typeof value === "string") {
+          const date = new Date(value);
+          if (isNaN(date.getTime())) {
+            throw new Error(
+              `Invalid date value for field "${key}": "${value}" cannot be parsed as a valid date`
+            );
+          }
+          decoded[key] = date;
+        } else if (value instanceof Date) {
+          if (isNaN(value.getTime())) {
+            throw new Error(
+              `Invalid Date object for field "${key}": received an Invalid Date`
+            );
+          }
+          decoded[key] = value;
+        } else {
+          decoded[key] = value;
+        }
+      } else {
+        decoded[key] = value;
+      }
+    } else {
+      decoded[key] = value;
+    }
+  }
+  return decoded;
+}
+
+export {
+  DatabaseError,
+  ValidationError,
+  TableDefinitionError,
+  MigrationError,
+  MigrationLockError,
+  QueryError,
+  NotFoundError,
+  AlreadyExistsError,
+  ConstraintViolationError,
+  ConnectionError,
+  TransactionError,
+  EnsureError,
+  SchemaDriftError,
+  ConstraintPreflightError,
+  isDatabaseError,
+  hasErrorCode,
+  CURRENT_TIMESTAMP,
+  CURRENT_DATE,
+  CURRENT_TIME,
+  NOW,
+  TODAY,
+  isSQLBuiltin,
+  resolveSQLBuiltin,
+  createTemplate,
+  isSQLTemplate,
+  ident,
+  isSQLIdentifier,
+  makeTemplate,
+  validateWithStandardSchema,
+  extendZod,
+  getTableMeta,
+  table,
+  decodeData
+};