litedbmodel 2.2.6 → 2.2.7

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;
@@ -3426,8 +3428,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 +3441,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 +3482,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 +5009,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 +5601,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 +5740,108 @@ 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 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() / .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 +5879,44 @@ 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(
+      // The family DECLARES `string`, so it must hand back one. Most drivers already do, but SQLite
+      // is dynamically typed: it returns a JS number for a `NUMERIC`/`DECIMAL` column whatever the
+      // declaration says, and the declared type would be a lie on that dialect alone.
+      (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 text: driver returned ${typeof v} for a text column. Use @column.passthrough() for a BYTEA/BLOB column, or @column.json<T>() for JSON.`
+        );
+      },
+      (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),
     /**
      * 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 +5924,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 +5967,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 +5985,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 +5995,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 +6022,9 @@ var column = Object.assign(
         }
         return val;
       },
-      false,
-      // allow auto-inference
       "date"
       // sqlCast for updateMany type inference
-    )(columnName),
+    )(columnNameOrOptions),
     // ============================================
     // Array Types
     // ============================================
@@ -6045,71 +6033,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 +6106,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 +6116,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);
       },
       serializeJson,
-      false,
       "jsonb"
-    )(columnName),
+    )(columnNameOrOptions),
     // ============================================
     // UUID Type (PostgreSQL)
     // ============================================
@@ -6166,22 +6153,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) {

package/dist/scp/makesql/json-array.d.ts

@@ -122,6 +122,12 @@ export declare function encodeJsonArrayParam(dialect: Dialect, values: readonly
  * the batch record sets in {@link import('./json-batch')} alike. Both bind values that came OFF a read, so
  * both meet the same two cases (a bc `int` is a `BigInt`, which `JSON.stringify` refuses; a MySQL boolean
  * must ride as 1/0), and a second bare `JSON.stringify` would silently diverge on either.
+ *
+ * A bc `int` is written as a JSON NUMBER TOKEN carrying every digit — `JSON.stringify` cannot emit one
+ * (it throws on a BigInt), and routing it through `Number` LOSES the value: an id past 2^53 was rounded
+ * inside the JSON text and the rounded id is what MySQL/SQLite stored, silently. JSON numbers are
+ * arbitrary-precision by grammar, and both `JSON_TABLE` (MySQL) and `json_each` (SQLite) read an
+ * integer literal within i64 exactly — which is the whole range bc's `int` admits.
  */
 export declare function encodeJsonParam(dialect: Dialect, payload: unknown): string;
 /**