litedbmodel 2.2.6 → 2.2.8

package/dist/scp/index.mjs

@@ -2054,12 +2054,14 @@ function tupleInPredicate(dialect, table, columns, pgElementTypes) {
 function encodeJsonArrayParam(dialect, values) {
   return encodeJsonParam(dialect, values);
 }
+var BIGINT_SENTINEL = "\0int:";
 function encodeJsonParam(dialect, payload) {
-  return JSON.stringify(payload, (_key, v) => {
-    if (typeof v === "bigint") return Number(v);
+  const tagged = JSON.stringify(payload, (_key, v) => {
+    if (typeof v === "bigint") return `${BIGINT_SENTINEL}${v.toString()}`;
     if (dialect === "mysql" && typeof v === "boolean") return v ? 1 : 0;
     return v;
   });
+  return tagged.replace(/"\\u0000int:(-?\d+)"/g, "$1");
 }
 var JsonArrayConditions = class extends DBConditions {
   _dialect;
@@ -2106,6 +2108,11 @@ function andTrailing(head, tails) {
   return [head, ...guardedTails];
 }
 
+// src/drivers/PostgresHelper.ts
+function castToJson(val) {
+  return val ?? null;
+}
+
 // src/TypeCast.ts
 var defaultTypeCast = {
   castToDatetime(val) {
@@ -2230,17 +2237,15 @@ var defaultTypeCast = {
     }
     return [];
   },
+  // A string is JSON text to decode; any other value is already a JSON value
   castToJson(val) {
     if (val === null || val === void 0) return null;
-    if (typeof val === "object") return val;
-    if (typeof val === "string") {
-      try {
-        return JSON.parse(val);
-      } catch {
-        return null;
-      }
+    if (typeof val !== "string") return val;
+    try {
+      return JSON.parse(val);
+    } catch {
+      return null;
     }
-    return null;
   }
 };
 function parsePostgresArray(literal) {
@@ -2297,7 +2302,7 @@ function castToBooleanArray(val) {
 function castToDatetimeArray(val) {
   return currentTypeCast.castToDatetimeArray(val);
 }
-function castToJson(val) {
+function castToJson2(val) {
   return currentTypeCast.castToJson(val);
 }
 function formatLocalDate(d) {
@@ -2341,16 +2346,7 @@ var postgresTypeCast = {
     return JSON.stringify(val);
   },
   deserializeJson(val) {
-    if (val === null || val === void 0) return null;
-    if (typeof val === "object") return val;
-    if (typeof val === "string") {
-      try {
-        return JSON.parse(val);
-      } catch {
-        return null;
-      }
-    }
-    return null;
+    return castToJson(val);
   },
   serializeBooleanArray(val) {
     if (val === null || val === void 0) return null;
@@ -2654,6 +2650,11 @@ var postgresSqlBuilder = {
   inferPgType
 };
 
+// src/drivers/MysqlHelper.ts
+function castToJson3(val) {
+  return val ?? null;
+}
+
 // src/drivers/MysqlSqlBuilder.ts
 var mysqlTypeCast = {
   driverName: "mysql",
@@ -2679,16 +2680,7 @@ var mysqlTypeCast = {
     return JSON.stringify(val);
   },
   deserializeJson(val) {
-    if (val === null || val === void 0) return null;
-    if (typeof val === "object") return val;
-    if (typeof val === "string") {
-      try {
-        return JSON.parse(val);
-      } catch {
-        return null;
-      }
-    }
-    return null;
+    return castToJson3(val);
   },
   serializeBooleanArray(val) {
     if (val === null || val === void 0) return null;
@@ -2856,6 +2848,24 @@ var mysqlSqlBuilder = {
   }
 };
 
+// src/drivers/SqliteHelper.ts
+function castToJson4(val) {
+  if (val === null || val === void 0) {
+    return null;
+  }
+  if (typeof val === "object" || typeof val === "number") {
+    return val;
+  }
+  if (typeof val === "string") {
+    try {
+      return JSON.parse(val);
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
 // src/drivers/SqliteSqlBuilder.ts
 var sqliteTypeCast = {
   driverName: "sqlite",
@@ -2881,16 +2891,7 @@ var sqliteTypeCast = {
     return JSON.stringify(val);
   },
   deserializeJson(val) {
-    if (val === null || val === void 0) return null;
-    if (typeof val === "object") return val;
-    if (typeof val === "string") {
-      try {
-        return JSON.parse(val);
-      } catch {
-        return null;
-      }
-    }
-    return null;
+    return castToJson4(val);
   },
   serializeBooleanArray(val) {
     if (val === null || val === void 0) return null;
@@ -3426,8 +3427,8 @@ function sqlTypeToMaterializeClass(sqlType) {
     return "passthrough";
   }
   switch (t) {
-    // 32-bit int family: JS number holds the full range exactly. The PostgreSQL SERIAL family maps to
-    // its underlying int width (SERIAL/SERIAL4=int4, SMALLSERIAL/SERIAL2=int2).
+    // Integer family. The PostgreSQL SERIAL types are the same integers under an auto-increment
+    // default (SERIAL/SERIAL4=int4, SMALLSERIAL/SERIAL2=int2, BIGSERIAL/SERIAL8=int8).
     case "INTEGER":
     case "INT":
     case "SMALLINT":
@@ -3439,13 +3440,11 @@ function sqlTypeToMaterializeClass(sqlType) {
     case "SERIAL4":
     case "SMALLSERIAL":
     case "SERIAL2":
-      return "int32";
-    // 64-bit int: needs JS bigint for exactness.
     case "BIGINT":
     case "INT8":
     case "BIGSERIAL":
     case "SERIAL8":
-      return "int64";
+      return "int";
     case "BOOLEAN":
     case "BOOL":
       return "bool";
@@ -3482,44 +3481,45 @@ function sqlTypeToMaterializeClass(sqlType) {
 }
 function keyArrayElemScalar(sqlType) {
   switch (sqlTypeToMaterializeClass(sqlType)) {
-    case "int32":
-      return "float";
-    // materializes to a JS number → bc float
-    case "int64":
+    case "int":
+      return "int";
+    // materializes to a JS bigint → bc int
     case "date":
       return "string";
-    // materializes to a decimal / TZ string → bc string
+    // materializes to a TZ string → bc string
     case "bool":
       return "bool";
     case "passthrough":
       return sqlTypeToBcScalar(sqlType) === "float" ? "float" : "string";
   }
 }
+var I64_MIN = -(2n ** 63n);
+var I64_MAX = 2n ** 63n - 1n;
+function checkI64(v) {
+  if (v < I64_MIN || v > I64_MAX) {
+    throw new Error(`materialize int: ${v} is outside the i64 range behavior-contracts' \`int\` admits`);
+  }
+  return v;
+}
 function materializeCell(value, klass) {
   if (value === null || value === void 0) return value;
   switch (klass) {
-    case "int64": {
-      if (typeof value === "bigint") return value.toString();
+    case "int": {
+      if (typeof value === "bigint") return checkI64(value);
       if (typeof value === "string") {
-        if (!/^-?\d+$/.test(value)) throw new Error(`materialize int64: driver returned a non-integer string '${value}'`);
-        return value;
+        if (!/^-?\d+$/.test(value)) throw new Error(`materialize int: driver returned a non-integer string '${value}'`);
+        return checkI64(BigInt(value));
       }
       if (typeof value === "number") {
-        if (!Number.isInteger(value)) throw new Error(`materialize int64: driver returned a non-integer number ${value} for a 64-bit int column`);
+        if (!Number.isInteger(value)) throw new Error(`materialize int: driver returned a non-integer number ${value} for an integer column`);
         if (!Number.isSafeInteger(value)) {
           throw new Error(
-            `materialize int64: driver returned an UNSAFE JS number ${value} for a 64-bit int column \u2014 precision was already lost before materialization (the driver must return int8 as string/bigint, not a rounded double). Configure the driver (better-sqlite3 safeIntegers / mysql2 supportBigNumbers+bigNumberStrings / pg int8-as-string).`
+            `materialize int: driver returned an UNSAFE JS number ${value} for an integer column \u2014 precision was already lost before materialization (the driver must return integers as bigint/string, not a rounded double). Configure the driver (better-sqlite3 safeIntegers / mysql2 supportBigNumbers+bigNumberStrings / pg int-as-bigint).`
           );
         }
-        return value.toString();
+        return BigInt(value);
       }
-      throw new Error(`materialize int64: unexpected driver JS type ${typeof value}`);
-    }
-    case "int32": {
-      if (typeof value === "number") return value;
-      if (typeof value === "bigint") return Number(value);
-      if (typeof value === "string" && /^-?\d+$/.test(value)) return Number(value);
-      throw new Error(`materialize int32: unexpected driver JS type ${typeof value} (${String(value)})`);
+      throw new Error(`materialize int: unexpected driver JS type ${typeof value}`);
     }
     case "date": {
       if (typeof value === "string") return value;
@@ -5008,8 +5008,7 @@ function onConflictTail(dialect, ports, cols) {
 }
 function pgTypeSpecimen(sqlType) {
   const klass = sqlTypeToMaterializeClass(sqlType);
-  if (klass === "int32") return 0;
-  if (klass === "int64") return 0n;
+  if (klass === "int") return 0n;
   if (klass === "bool") return false;
   if (klass === "date") return /* @__PURE__ */ new Date(0);
   const scalar = sqlTypeToBcScalar(sqlType);
@@ -5601,10 +5600,6 @@ function materializeChildRows(rows, cols) {
         row[key] = materializeCell(row[key], klass);
         continue;
       }
-      if (typeof row[key] === "bigint") {
-        const v = row[key];
-        row[key] = v >= BigInt(Number.MIN_SAFE_INTEGER) && v <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(v) : v.toString();
-      }
     }
   }
   return rows;
@@ -5744,133 +5739,116 @@ function compileDeleteManyBundle(name, options, dialectName = "sqlite") {
 var import_reflect_metadata = __toESM(require_Reflect());
 var COLUMNS_KEY = /* @__PURE__ */ Symbol("litedbmodel:columns");
 var RELATIONS_KEY = /* @__PURE__ */ Symbol("litedbmodel:relations");
-function inferTypeCastFromDesignType(target, propertyKey) {
-  const designType = Reflect.getMetadata("design:type", target, propertyKey);
-  if (!designType) return void 0;
-  switch (designType) {
-    case Boolean:
-      return {
-        // v2 read contract: BOOLEAN → boolean, via the shared materializer.
-        typeCast: (v) => {
-          if (v === void 0) return void 0;
-          return materializeCell(v, "bool");
-        },
-        sqlCast: "boolean"
-      };
-    case Date:
-      return {
-        typeCast: (v) => {
-          if (v === void 0) return void 0;
-          return materializeCell(v, "date");
-        },
-        // Delegate to driver-specific serializeDatetime
-        serialize: (val, typeCast) => {
-          if (val === null || val === void 0) return null;
-          if (val instanceof Date) {
-            return typeCast?.serializeDatetime(val) ?? val;
-          }
-          return val;
-        },
-        sqlCast: "timestamp"
-      };
-    case Number:
-      return {
-        typeCast: (v) => {
-          if (v === void 0) return void 0;
-          if (v === null) return null;
-          const n = Number(v);
-          return isNaN(n) ? null : n;
-        }
-      };
-    case BigInt:
-      return {
-        // v2 read contract: BIGINT/INT8 → EXACT decimal STRING (no i64 rounding, JSON-safe), via the
-        // shared materializer. NOTE: the TS field type stays `bigint` in existing models for source
-        // compat, but the VALUE is now the exact string — the whole point of the #9 realignment.
-        typeCast: (v) => {
-          if (v === void 0) return void 0;
-          return materializeCell(v, "int64");
-        },
-        sqlCast: "bigint"
-      };
-    // Array, Object, String, and other types require explicit specification
-    default:
-      return void 0;
-  }
-}
-function inferBaseSqlTypeFromDesignType(target, propertyKey) {
-  const designType = Reflect.getMetadata("design:type", target, propertyKey);
-  if (!designType) return void 0;
-  switch (designType) {
-    case String:
-      return "TEXT";
-    case Number:
-      return "INTEGER";
-    case Boolean:
-      return "BOOLEAN";
-    case Date:
-      return "TIMESTAMP";
-    case BigInt:
-      return "BIGINT";
-    default:
-      return void 0;
+if (typeof Symbol === "function" && !Symbol.metadata) {
+  Object.defineProperty(Symbol, "metadata", {
+    value: /* @__PURE__ */ Symbol.for("Symbol.metadata"),
+    writable: false,
+    enumerable: false,
+    configurable: true
+  });
+}
+function isStandardContext(second) {
+  return typeof second === "object" && second !== null && typeof second.kind === "string";
+}
+function classMetadataBag(context, propertyKey) {
+  const bag = context.metadata;
+  if (bag === void 0) {
+    throw new Error(
+      `litedbmodel: the standard-decorator context for '${propertyKey}' carries no \`context.metadata\`. litedbmodel defines \`Symbol.metadata\` on import, which every current emit needs to create the bag \u2014 import litedbmodel (or 'litedbmodel/decorators') BEFORE the module that defines the model.`
+    );
   }
+  return bag;
 }
-function registerColumn(target, propertyKey, options) {
-  const constructor = target.constructor;
-  const columns = Reflect.getMetadata(COLUMNS_KEY, constructor) || /* @__PURE__ */ new Map();
-  let finalTypeCast = options.typeCast;
-  let finalSerialize = options.serialize;
-  let finalSqlCast = options.sqlCast;
-  if (!options.skipAutoInfer) {
-    const inferred = inferTypeCastFromDesignType(target, propertyKey);
-    if (inferred) {
-      if (!finalTypeCast) finalTypeCast = inferred.typeCast;
-      if (!finalSerialize) finalSerialize = inferred.serialize;
-      if (!finalSqlCast) finalSqlCast = inferred.sqlCast;
-    }
+function legacyColumnMap(constructor) {
+  const own = Reflect.getOwnMetadata(COLUMNS_KEY, constructor);
+  if (own !== void 0) return own;
+  const inherited = Reflect.getMetadata(COLUMNS_KEY, constructor);
+  const map = new Map(inherited);
+  Reflect.defineMetadata(COLUMNS_KEY, map, constructor);
+  return map;
+}
+function standardColumnMap(bag) {
+  if (!Object.prototype.hasOwnProperty.call(bag, COLUMNS_KEY)) {
+    bag[COLUMNS_KEY] = new Map(bag[COLUMNS_KEY]);
   }
-  const baseSqlType = inferBaseSqlTypeFromDesignType(target, propertyKey);
+  return bag[COLUMNS_KEY];
+}
+function registerColumn(columns, propertyKey, options) {
   columns.set(propertyKey, {
     columnName: options.columnName,
-    typeCast: finalTypeCast,
-    serialize: finalSerialize,
+    typeCast: options.typeCast,
+    serialize: options.serialize,
     primaryKey: options.primaryKey,
     autoIncrement: options.autoIncrement,
-    sqlCast: finalSqlCast,
-    ...baseSqlType !== void 0 ? { baseSqlType } : {}
+    sqlCast: options.sqlCast,
+    ...options.baseSqlType !== void 0 ? { baseSqlType: options.baseSqlType } : {}
   });
-  Reflect.defineMetadata(COLUMNS_KEY, columns, constructor);
 }
-function createColumnDecorator(typeCast, serialize, skipAutoInfer = false, sqlCast) {
+function parseColumnOptions(columnNameOrOptions, propKey) {
+  if (typeof columnNameOrOptions === "string") return { columnName: columnNameOrOptions };
+  if (columnNameOrOptions) {
+    return {
+      columnName: columnNameOrOptions.columnName || propKey,
+      primaryKey: columnNameOrOptions.primaryKey,
+      autoIncrement: columnNameOrOptions.autoIncrement
+    };
+  }
+  return { columnName: propKey };
+}
+function rejectNonText(family, val) {
+  if (val === null || val === void 0) return null;
+  if (val instanceof Date) {
+    throw new Error(
+      `litedbmodel: @column.${family}() received a Date. A text column cannot serialize one \u2014 the driver would store an object literal. Use @column.datetime() / @column.date() for a date column, or format the value yourself.`
+    );
+  }
+  if (typeof val === "object") {
+    throw new Error(
+      `litedbmodel: @column.${family}() received an object. Use @column.json<T>() for a JSON column, or @column.custom() with a serializer.`
+    );
+  }
+  return val;
+}
+function materializeString(family, v) {
+  if (v === void 0 || v === null) return v;
+  if (typeof v === "string") return v;
+  if (typeof v === "number" || typeof v === "bigint" || typeof v === "boolean") return String(v);
+  throw new Error(
+    `materialize ${family}: driver returned ${typeof v} for a ${family} column. Use @column.passthrough() for a BYTEA/BLOB column, or @column.json<T>() for JSON.`
+  );
+}
+function createColumnDecorator(typeCast, serialize, sqlCast, baseSqlType) {
   return function(columnNameOrOptions) {
-    return function(target, propertyKey) {
-      const propKey = String(propertyKey);
-      const shouldSkipAutoInfer = skipAutoInfer || typeCast !== void 0;
-      let columnName;
-      let primaryKey;
-      let autoIncrement;
-      if (typeof columnNameOrOptions === "string") {
-        columnName = columnNameOrOptions;
-      } else if (columnNameOrOptions) {
-        columnName = columnNameOrOptions.columnName || propKey;
-        primaryKey = columnNameOrOptions.primaryKey;
-        autoIncrement = columnNameOrOptions.autoIncrement;
-      } else {
-        columnName = propKey;
+    return function(targetOrValue, keyOrContext) {
+      if (isStandardContext(keyOrContext)) {
+        const propKey2 = String(keyOrContext.name);
+        const parsed2 = parseColumnOptions(columnNameOrOptions, propKey2);
+        registerColumn(standardColumnMap(classMetadataBag(keyOrContext, propKey2)), propKey2, {
+          ...parsed2,
+          typeCast,
+          serialize,
+          sqlCast,
+          baseSqlType
+        });
+        return;
       }
-      registerColumn(target, propKey, {
-        columnName,
+      const propKey = String(keyOrContext);
+      const parsed = parseColumnOptions(columnNameOrOptions, propKey);
+      registerColumn(legacyColumnMap(targetOrValue.constructor), propKey, {
+        ...parsed,
         typeCast,
         serialize,
-        skipAutoInfer: shouldSkipAutoInfer,
-        primaryKey,
-        autoIncrement,
-        sqlCast
+        sqlCast,
+        baseSqlType
       });
     };
   };
 }
+function requireColumnFamily() {
+  throw new Error(
+    "litedbmodel: `@column()` no longer declares a column \u2014 a column must state its type with a family: @column.text() / .decimal() / .number() / .boolean() / .bigint() / .datetime() / .date() / .uuid() / .json() / .stringArray() / .intArray() / .numericArray() / .booleanArray() / .datetimeArray() / .passthrough() / .custom(). Every family takes the same argument as `@column()` did (`@column.text('db_name')`, `@column.number({ primaryKey: true })`). The bare form inferred the type from `emitDecoratorMetadata`, which esbuild (tsx/vite/vitest) never emits and standard decorators do not have, so it silently produced untyped reads."
+  );
+}
 function serializeArray(val, typeCast) {
   if (val === null || val === void 0) return null;
   if (!Array.isArray(val)) return val;
@@ -5908,19 +5886,47 @@ function serializeJson(val, typeCast) {
   return JSON.stringify(val);
 }
 var column = Object.assign(
-  // Basic @column() - no type conversion
-  createColumnDecorator(),
+  // The bare `@column()` declared no type — it is rejected, with the migration in the message.
+  (_columnNameOrOptions) => requireColumnFamily(),
   {
     // ============================================
     // Primitive Types
     // ============================================
+    /**
+     * Text type (TEXT / VARCHAR / CHAR / ENUM / citext) — the driver value is already a string, so no
+     * cast is applied. The family still DECLARES the column so the typed read types it as `TEXT`.
+     * @example @column.text() name?: string;
+     * @example @column.text('user_name') name?: string;
+     */
+    text: (columnNameOrOptions) => createColumnDecorator(
+      (v) => materializeString("text", v),
+      // the family DECLARES `string`, so it hands back one
+      (val) => rejectNonText("text", val),
+      // …and it cannot SERIALIZE a Date or an object
+      void 0,
+      // no sqlCast family (a text literal needs no SQL cast)
+      "TEXT"
+      // §4.1 token: types the SCP typed read
+    )(columnNameOrOptions),
+    /**
+     * Exact decimal type (NUMERIC / DECIMAL) — read back as its exact decimal STRING (a JS number
+     * rounds past 2^53). The family states the column is `numeric`, so a write binds the string as a
+     * numeric — a batch write (`createMany` / `updateMany`) included.
+     * @example @column.decimal() price?: string;
+     */
+    decimal: (columnNameOrOptions) => createColumnDecorator(
+      (v) => materializeString("decimal", v),
+      (val) => rejectNonText("decimal", val),
+      "numeric"
+      // sqlCast for WHERE / INSERT / batch-write type casting
+    )(columnNameOrOptions),
     /**
      * Boolean type conversion
      * Converts 't'/'f', 'true'/'false', 1/0 to boolean
      * Preserves null for nullable columns, undefined stays undefined
      * @example @column.boolean() is_active?: boolean;
      */
-    boolean: (columnName) => createColumnDecorator(
+    boolean: (columnNameOrOptions) => createColumnDecorator(
       // v2 read contract: BOOLEAN → boolean, via the shared materializer (issue #9).
       (v) => {
         if (v === void 0) return void 0;
@@ -5928,42 +5934,38 @@ var column = Object.assign(
       },
       void 0,
       // no custom serialize
-      false,
-      // allow auto-inference
       "boolean"
       // sqlCast for updateMany type inference
-    )(columnName),
+    )(columnNameOrOptions),
     /**
      * Number type conversion (from string)
      * Preserves null for nullable columns, undefined stays undefined
      * @example @column.number() amount?: number;
      */
-    number: (columnName) => createColumnDecorator((v) => {
+    number: (columnNameOrOptions) => createColumnDecorator((v) => {
       if (v === void 0) return void 0;
       if (v === null) return null;
       const n = Number(v);
       return isNaN(n) ? null : n;
-    })(columnName),
+    })(columnNameOrOptions),
     /**
      * BigInt type conversion
      * Preserves null for nullable columns, undefined stays undefined
-     * @example @column.bigint() large_id?: bigint;
+     * @example @column.bigint() large_id?: bigint;   // bc `int` — a JS bigint, checked i64
      */
-    bigint: (columnName) => createColumnDecorator(
-      // v2 read contract: BIGINT/INT8 → EXACT decimal STRING (no i64 rounding, JSON-safe), via the
-      // shared materializer (issue #9). The declared TS field type may still be `bigint` in existing
-      // models, but the runtime value is now the exact string — that IS the realignment.
+    bigint: (columnNameOrOptions) => createColumnDecorator(
+      // An integer column reads back as a JS `bigint` — behavior-contracts' `int` value model
+      // (`int` = bigint, checked i64), which is what the drivers already hand over. `JSON.stringify`
+      // does not serialize a bigint: give the field a `toJSON`, or convert at the boundary.
       (v) => {
         if (v === void 0) return void 0;
-        return materializeCell(v, "int64");
+        return materializeCell(v, "int");
       },
       void 0,
       // no custom serialize
-      false,
-      // allow auto-inference
       "bigint"
       // sqlCast for WHERE/INSERT type casting
-    )(columnName),
+    )(columnNameOrOptions),
     // ============================================
     // Date/Time Types
     // ============================================
@@ -5975,9 +5977,9 @@ var column = Object.assign(
      * - PostgreSQL: Serializes to ISO 8601 UTC string with 'Z' suffix for explicit timezone
      * - MySQL/SQLite: Passes Date object to driver (driver-dependent timezone handling)
      * 
-     * @example @column.datetime() created_at?: Date;
+     * @example @column.datetime() created_at?: string;  // TZ-attached string, NOT a JS Date
      */
-    datetime: (columnName) => createColumnDecorator(
+    datetime: (columnNameOrOptions) => createColumnDecorator(
       // v2 read contract: DATE/TIMESTAMP/TIMESTAMPTZ/DATETIME/TIME → TZ-attached STRING (NOT a
       // TZ-shifted JS Date), via the shared materializer (issue #9). A driver already returning the
       // native textual form passes through; a JS Date is rendered to its lossless ISO instant.
@@ -5993,11 +5995,9 @@ var column = Object.assign(
         }
         return val;
       },
-      false,
-      // allow auto-inference
       "timestamp"
       // sqlCast for updateMany type inference
-    )(columnName),
+    )(columnNameOrOptions),
     /**
      * Date type conversion — returns YYYY-MM-DD string.
      * Preserves null for nullable columns, undefined stays undefined.
@@ -6005,9 +6005,9 @@ var column = Object.assign(
      * DB values (Date object or string) are normalized to 'YYYY-MM-DD' string.
      * On write, string values are passed through; Date objects are formatted as 'YYYY-MM-DD'.
      * 
-     * @example @column.date() birth_date?: string;
+     * @example @column.date() birth_date?: string;      // 'YYYY-MM-DD'
      */
-    date: (columnName) => createColumnDecorator(
+    date: (columnNameOrOptions) => createColumnDecorator(
       (v) => {
         if (v === void 0) return void 0;
         if (v === null) return null;
@@ -6032,11 +6032,9 @@ var column = Object.assign(
         }
         return val;
       },
-      false,
-      // allow auto-inference
       "date"
       // sqlCast for updateMany type inference
-    )(columnName),
+    )(columnNameOrOptions),
     // ============================================
     // Array Types
     // ============================================
@@ -6045,71 +6043,71 @@ var column = Object.assign(
      * Preserves null for nullable columns, undefined stays undefined
      * @example @column.stringArray() tags?: string[];
      */
-    stringArray: (columnName) => createColumnDecorator(
+    stringArray: (columnNameOrOptions) => createColumnDecorator(
       (v) => {
         if (v === void 0) return void 0;
         if (v === null) return null;
         return castToStringArray(v);
       },
       serializeArray,
-      false,
       "text[]"
-    )(columnName),
+    )(columnNameOrOptions),
     /**
      * Integer array type conversion (integer[])
      * Preserves null for nullable columns, undefined stays undefined
      * @example @column.intArray() scores?: number[];
      */
-    intArray: (columnName) => createColumnDecorator(
+    intArray: (columnNameOrOptions) => createColumnDecorator(
       (v) => {
         if (v === void 0) return void 0;
         if (v === null) return null;
         return castToIntegerArray(v);
       },
       serializeArray,
-      false,
       "int[]"
-    )(columnName),
+    )(columnNameOrOptions),
     /**
      * Numeric array type conversion (numeric[], allows null elements)
      * Preserves null for nullable columns, undefined stays undefined
      * @example @column.numericArray() values?: (number | null)[];
      */
-    numericArray: (columnName) => createColumnDecorator(
+    numericArray: (columnNameOrOptions) => createColumnDecorator(
       (v) => {
         if (v === void 0) return void 0;
         if (v === null) return null;
         return castToNumericArray(v);
       },
       serializeArray,
-      false,
       "numeric[]"
-    )(columnName),
+    )(columnNameOrOptions),
     /**
      * Boolean array type conversion (boolean[])
      * Preserves null for nullable columns, undefined stays undefined
      * @example @column.booleanArray() flags?: (boolean | null)[];
      */
-    booleanArray: (columnName) => createColumnDecorator(
+    booleanArray: (columnNameOrOptions) => createColumnDecorator(
       (v) => {
         if (v === void 0) return void 0;
         if (v === null) return null;
         return castToBooleanArray(v);
       },
       serializeBooleanArray,
-      false,
       "boolean[]"
-    )(columnName),
+    )(columnNameOrOptions),
     /**
      * DateTime array type conversion (timestamp[])
      * Preserves null for nullable columns, undefined stays undefined
-     * @example @column.datetimeArray() event_dates?: (Date | null)[];
+     * @example @column.datetimeArray() event_dates?: (string | null)[];
      */
-    datetimeArray: (columnName) => createColumnDecorator(
+    datetimeArray: (columnNameOrOptions) => createColumnDecorator(
+      // Element-wise the SAME contract as `@column.datetime()`: a TZ-attached STRING, never a
+      // TZ-shifted JS Date. The array family used to be the one place a `Date` still came back, so
+      // `JSON.stringify` of a row silently re-rendered those elements in UTC — the exact hazard #9
+      // closed for the scalar.
       (v) => {
         if (v === void 0) return void 0;
         if (v === null) return null;
-        return castToDatetimeArray(v);
+        return castToDatetimeArray(v).map((d) => d === null ? null : materializeCell(d, "date"));
       },
       // DateTime arrays serialize each Date to ISO string
       (val) => {
@@ -6118,7 +6116,7 @@ var column = Object.assign(
         const mapped = val.map((v) => v === null ? "NULL" : v instanceof Date ? v.toISOString() : String(v));
         return `{${mapped.join(",")}}`;
       }
-    )(columnName),
+    )(columnNameOrOptions),
     // ============================================
     // JSON Types
     // ============================================
@@ -6128,16 +6126,15 @@ var column = Object.assign(
      * @example @column.json() metadata?: Record<string, unknown>;
      * @example @column.json<UserSettings>() settings?: UserSettings;
      */
-    json: (columnName) => createColumnDecorator(
+    json: (columnNameOrOptions) => createColumnDecorator(
       (v) => {
         if (v === void 0) return void 0;
         if (v === null) return null;
-        return castToJson(v);
+        return castToJson2(v);
       },
       serializeJson,
-      false,
       "jsonb"
-    )(columnName),
+    )(columnNameOrOptions),
     // ============================================
     // UUID Type (PostgreSQL)
     // ============================================
@@ -6166,22 +6163,28 @@ var column = Object.assign(
         if (v === null) return null;
         return String(v);
       },
-      void 0,
-      // No serialization needed - handled by sqlCast
-      true,
-      // Skip auto-inference
+      (val) => rejectNonText("uuid", val),
+      // the ::uuid cast handles the rest
       "uuid"
       // SQL type for casting
     )(columnNameOrOptions),
     // ============================================
     // Custom Type Conversion
     // ============================================
+    /**
+     * The driver's value, UNCAST — for a column whose type the library has no cast for (`BYTEA` /
+     * `BLOB` arrives as a driver Buffer, a vendor type as whatever the driver decodes). It states
+     * "this column is passed through", which is a DECLARATION; the removed bare `@column()` was the
+     * absence of one, and produced this same passthrough by accident for every unresolvable type.
+     * @example @column.passthrough() payload?: unknown;
+     */
+    passthrough: (columnNameOrOptions) => createColumnDecorator()(columnNameOrOptions),
     /**
      * Custom type conversion with user-provided function
      * @example @column.custom((v) => String(v).toUpperCase()) status?: string;
      * @example @column.custom((v) => v, (v) => JSON.stringify(v)) data?: MyType; // with serializer
      */
-    custom: (castFn, serializeFn, columnName) => createColumnDecorator(castFn, serializeFn)(columnName)
+    custom: (castFn, serializeFn, columnNameOrOptions) => createColumnDecorator(castFn, serializeFn)(columnNameOrOptions)
   }
 );
 function getRelationMeta(modelClass) {
@@ -6225,6 +6228,7 @@ function getPrimaryKey(modelClass) {
 // src/scp/decorator-adapter.ts
 var COLUMN_FAMILY_SQL_TYPE = {
   boolean: "BOOLEAN",
+  numeric: "NUMERIC",
   bigint: "BIGINT",
   timestamp: "TIMESTAMP",
   date: "DATE",