litedbmodel 2.2.5 → 2.2.7

package/dist/index.cjs

@@ -5632,12 +5632,14 @@ function resolvePgArrayCast(sql2, values) {
 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");
 }
 
 // src/scp/makesql/json-batch.ts
@@ -5799,8 +5801,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":
@@ -5812,13 +5814,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";
@@ -5853,31 +5853,33 @@ function sqlTypeToMaterializeClass(sqlType) {
       );
   }
 }
+var I64_MIN2 = -(2n ** 63n);
+var I64_MAX2 = 2n ** 63n - 1n;
+function checkI642(v) {
+  if (v < I64_MIN2 || v > I64_MAX2) {
+    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 checkI642(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 checkI642(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;
@@ -6376,133 +6378,123 @@ function compileCreateManyBundle(name, options, dialectName = "sqlite", resolveC
 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;
+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 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;
+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]);
   }
+  return bag[COLUMNS_KEY];
 }
-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 legacyRelationList(constructor) {
+  const own = Reflect.getOwnMetadata(RELATIONS_KEY, constructor);
+  if (own !== void 0) return own;
+  const inherited = Reflect.getMetadata(RELATIONS_KEY, constructor);
+  const list = inherited !== void 0 ? [...inherited] : [];
+  Reflect.defineMetadata(RELATIONS_KEY, list, constructor);
+  return list;
+}
+function standardRelationList(bag) {
+  if (!Object.prototype.hasOwnProperty.call(bag, RELATIONS_KEY)) {
+    const inherited = bag[RELATIONS_KEY];
+    bag[RELATIONS_KEY] = inherited !== void 0 ? [...inherited] : [];
   }
-  const baseSqlType = inferBaseSqlTypeFromDesignType(target, propertyKey);
+  return bag[RELATIONS_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;
@@ -6540,19 +6532,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;
@@ -6560,42 +6577,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
     // ============================================
@@ -6607,9 +6620,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.
@@ -6625,11 +6638,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.
@@ -6637,9 +6648,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;
@@ -6664,11 +6675,9 @@ var column = Object.assign(
         }
         return val;
       },
-      false,
-      // allow auto-inference
       "date"
       // sqlCast for updateMany type inference
-    )(columnName),
+    )(columnNameOrOptions),
     // ============================================
     // Array Types
     // ============================================
@@ -6677,71 +6686,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) => {
@@ -6750,7 +6759,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
     // ============================================
@@ -6760,16 +6769,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)
     // ============================================
@@ -6798,61 +6806,101 @@ 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 registerRelation(target, propertyKey, type, keysFactory, options) {
-  const constructor = target.constructor;
-  const relations = Reflect.getMetadata(RELATIONS_KEY, constructor) || [];
-  relations.push({
-    propertyKey,
-    type,
-    keysFactory,
-    options
-  });
-  Reflect.defineMetadata(RELATIONS_KEY, relations, constructor);
+function registerRelation(relations, propertyKey, type, keysFactory, options) {
+  relations.push({ propertyKey, type, keysFactory, options });
+}
+function createRelationDecorator(type, keys, options) {
+  return function(targetOrValue, keyOrContext) {
+    if (isStandardContext(keyOrContext)) {
+      const propKey2 = String(keyOrContext.name);
+      registerRelation(standardRelationList(classMetadataBag(keyOrContext, propKey2)), propKey2, type, keys, options);
+      if (typeof keyOrContext.addInitializer !== "function") {
+        throw new Error(
+          `litedbmodel: the standard-decorator context for relation '${propKey2}' has no \`addInitializer\`, so the class field cannot be removed and would shadow the relation getter.`
+        );
+      }
+      keyOrContext.addInitializer(function() {
+        if (Object.prototype.hasOwnProperty.call(this, propKey2)) {
+          delete this[propKey2];
+        }
+      });
+      return;
+    }
+    const propKey = String(keyOrContext);
+    registerRelation(legacyRelationList(targetOrValue.constructor), propKey, type, keys, options);
+  };
 }
 function hasMany(keys, options) {
-  return function(target, propertyKey) {
-    registerRelation(target, String(propertyKey), "hasMany", keys, options);
-  };
+  return createRelationDecorator("hasMany", keys, options);
 }
 function belongsTo(keys, options) {
-  return function(target, propertyKey) {
-    registerRelation(target, String(propertyKey), "belongsTo", keys, options);
-  };
+  return createRelationDecorator("belongsTo", keys, options);
 }
 function hasOne(keys, options) {
-  return function(target, propertyKey) {
-    registerRelation(target, String(propertyKey), "hasOne", keys, options);
-  };
+  return createRelationDecorator("hasOne", keys, options);
 }
 function getRelationMeta(modelClass) {
   return modelClass._relationMeta || Reflect.getMetadata(RELATIONS_KEY, modelClass) || [];
 }
-function model(tableNameOrConstructor, options) {
+function model(tableNameOrConstructor, optionsOrContext) {
   if (typeof tableNameOrConstructor === "string") {
     const tableName = tableNameOrConstructor;
-    return function(constructor) {
-      return applyModelDecorator(constructor, tableName, options);
+    const options = optionsOrContext;
+    return function(constructor, context) {
+      return applyToClass(constructor, context, tableName, options);
+    };
+  }
+  return applyToClass(tableNameOrConstructor, optionsOrContext);
+}
+function applyToClass(constructor, context, tableName, options) {
+  const members = modelMembers(constructor, context);
+  if (!isStandardContext(context)) return applyModelDecorator(constructor, members, tableName, options);
+  if (typeof context.addInitializer !== "function") {
+    throw new Error(
+      `litedbmodel: the standard-decorator context for '${constructor.name}' has no \`addInitializer\`, so \`@model\` cannot assemble the model after the class is defined.`
+    );
+  }
+  context.addInitializer(function() {
+    applyModelDecorator(this, members, tableName, options);
+  });
+  return constructor;
+}
+function modelMembers(constructor, context) {
+  if (isStandardContext(context)) {
+    const bag = classMetadataBag(context, String(constructor.name ?? "model"));
+    return {
+      columns: bag[COLUMNS_KEY] ?? /* @__PURE__ */ new Map(),
+      relations: bag[RELATIONS_KEY] ?? []
     };
   }
-  return applyModelDecorator(tableNameOrConstructor);
+  return {
+    columns: Reflect.getMetadata(COLUMNS_KEY, constructor) ?? /* @__PURE__ */ new Map(),
+    relations: Reflect.getMetadata(RELATIONS_KEY, constructor) ?? []
+  };
 }
 function isCompositeKeys(keys) {
   return Array.isArray(keys[0]);
@@ -6872,9 +6920,8 @@ function parseKeys(keys) {
     };
   }
 }
-function applyModelDecorator(constructor, tableName, options) {
-  const columns = Reflect.getMetadata(COLUMNS_KEY, constructor) || /* @__PURE__ */ new Map();
-  const relations = Reflect.getMetadata(RELATIONS_KEY, constructor) || [];
+function applyModelDecorator(constructor, members, tableName, options) {
+  const { columns, relations } = members;
   const modelName = constructor.name;
   if (tableName) {
     Object.defineProperty(constructor, "TABLE_NAME", {
@@ -6992,6 +7039,26 @@ function applyModelDecorator(constructor, tableName, options) {
           relationName: propertyKey
         });
       },
+      /**
+       * A relation is a getter, but a class FIELD declaring it still writes to the property. Which
+       * write it is depends on `useDefineForClassFields`: with define semantics (the default from
+       * target ES2022) the field is `defineProperty`-d onto the instance, bypassing this setter — the
+       * standard protocol's initializer removes that shadowing property. With SET semantics (the
+       * default below ES2022) the field ASSIGNS, and an accessor with no setter throws
+       * `Cannot set property … which has only a getter` on EVERY instantiation.
+       *
+       * So: the field's own `undefined` is ignored, and any other value is honoured as an own
+       * property — priming a relation (a loaded graph, a test double) reads back what was set.
+       */
+      set: function(value) {
+        if (value === void 0) return;
+        Object.defineProperty(this, propertyKey, {
+          value,
+          writable: true,
+          enumerable: true,
+          configurable: true
+        });
+      },
       enumerable: true,
       configurable: false
     });
@@ -8054,8 +8121,8 @@ var DBModel = class _DBModel {
    * ```typescript
    * @model('users')
    * class UserModel extends DBModel {
-   *   @column() id?: number;
-   *   @column() name?: string;
+   *   @column.number() id?: number;
+   *   @column.text() name?: string;
    * }
    * export const User = UserModel.asModel();
    * export type User = UserModel;
@@ -8187,15 +8254,14 @@ var DBModel = class _DBModel {
   static _scpColumnTypesCache = /* @__PURE__ */ new WeakMap();
   /**
    * The §4.1 column-type OVERRIDES for the SCP read/write bundle (the F1 `columnTypes` escape hatch).
-   * Phase F-2 (#105): a column whose SQL type cannot be derived from the decorator — no explicit
-   * `sqlCast` family AND no `baseSqlType` (its TS `design:type` is `Object`, e.g. a NULLABLE
-   * `string | null` / `number | null` field: TS emits `design:type = Object` for a union) — would
-   * otherwise take the blanket-INTEGER default and THROW `materialize int32` on a live string. Because
+   * A column whose SQL type cannot be derived from its family — `@column.number()`, whose JS `number`
+   * backs an INTEGER just as well as a REAL/DECIMAL (pg returns DECIMAL as a string that an `int32`
+   * materialize REJECTS) — would otherwise take the blanket-INTEGER default and THROW. Because
    * the DBModel read path does its OWN v1 de-box (`_createInstance` → `typeCastFromDB`), the SCP typed
    * read only needs a NON-THROWING, passthrough-safe SQL type for such columns: we pin them to `TEXT`
    * (passthrough — the driver value flows through unchanged, then v1 casts it). Columns WITH a derivable
-   * type (explicit family / a non-union `design:type`) keep it. This preserves the v1 read contract
-   * exactly (int→number, string→string) while never throwing on an undeterminable nullable column.
+   * type (every family but `@column.number()`) keep it. This preserves the v1 read contract exactly
+   * (int→number, string→string) while never throwing on a column whose width the model did not state.
    * @internal
    */
   static _scpColumnTypes() {
@@ -8207,7 +8273,7 @@ var DBModel = class _DBModel {
       for (const [propKey, m] of meta) {
         const baseSqlType = m.baseSqlType;
         if (m.sqlCast !== void 0) continue;
-        if (baseSqlType !== void 0 && baseSqlType !== "INTEGER") continue;
+        if (baseSqlType !== void 0) continue;
         columnTypes[propKey] = "TEXT";
       }
     }
@@ -10426,12 +10492,12 @@ var DBModel = class _DBModel {
    * // Define models using appropriate base class
    * @model('users')
    * class UserModel extends BaseDB {
-   *   @column() id?: number;
+   *   @column.number() id?: number;
    * }
    *
    * @model('articles')
    * class ArticleModel extends CmsDB {
-   *   @column() id?: number;
+   *   @column.number() id?: number;
    * }
    *
    * // Each base class has independent transactions