litedbmodel 2.2.6 → 2.2.8

package/dist/decorators.js

@@ -27,16 +27,15 @@ const TypeCast_1 = require("./TypeCast");
 const coltype_1 = require("./scp/coltype");
 // ── v1 read type contract (issue #9), aligned to the v2 SCP read de-box ────────
 // The legacy v1 `DBModel` decorator read path historically materialized `@column.bigint()` to a JS
-// `bigint` (not JSON-safe) and `@column.datetime()` / an auto-inferred `Date` to a JS `Date`
-// (TZ-shifted). Both carry the SAME i64-rounding / date-corruption hazards the v2 SCP read path
+// `bigint` (not JSON-safe) and `@column.datetime()` to a JS `Date` (TZ-shifted). Both carry the SAME i64-rounding / date-corruption hazards the v2 SCP read path
 // already closed. Per the owner (2026-07-15), v1 is realigned to the v2 read TYPE CONTRACT — and it
 // does so by REUSING the v2 materializer (`materializeCell`, `src/scp/coltype.ts`), NOT a divergent
 // v1 coercion. The v1 decorator IS the static type source (unlike v2, whose SoT is the SQL DDL), so
 // each read-affected decorator variant pins its v2 `MaterializeClass` and routes the raw driver cell
 // through `materializeCell`:
-//   - `@column.bigint()` / auto `BigInt`  → `int64` → EXACT decimal STRING (no i64 rounding, JSON-safe)
-//   - `@column.datetime()` / auto `Date`  → `date`  → TZ-attached STRING (NOT a TZ-shifted JS Date)
-//   - `@column.boolean()`  / auto `Boolean` → `bool` → JS boolean
+//   - `@column.bigint()`   → `int`   → JS bigint (bc's `int` value model, checked i64)
+//   - `@column.datetime()` → `date`  → TZ-attached STRING (NOT a TZ-shifted JS Date)
+//   - `@column.boolean()`  → `bool`  → JS boolean
 // `null`/`undefined` pass through (nullable columns) exactly as `materializeCell` and the prior v1
 // casts did. Fail-closed like v2: a driver cell that cannot be coerced to the declared class throws
 // (a declared BIGINT column returning a non-integer string is a driver-contract violation, not a
@@ -48,183 +47,211 @@ const coltype_1 = require("./scp/coltype");
 // ============================================
 const COLUMNS_KEY = Symbol('litedbmodel:columns');
 const RELATIONS_KEY = Symbol('litedbmodel:relations');
+// ============================================
+// Decorator Protocol Adapter (legacy + TC39 standard)
+// ============================================
 /**
- * Infer type cast function from design:type metadata
- * Returns undefined if type cannot be inferred (Array, Object, etc.)
- * Note: All type casts preserve null (DB NULL -> JS null)
+ * TC39 (standard) decorators carry NO `design:type`: `emitDecoratorMetadata` is a legacy-decorator
+ * feature, and esbuild — which powers `tsx`, `vite` and `vitest` — does not implement it even for
+ * legacy decorators. A column's type is therefore declared by its `@column.*` FAMILY, which is the
+ * single source of truth on every toolchain (`.text()` / `.number()` / `.datetime()` / …). The bare
+ * `@column()` carries no type and is rejected at decoration time — see {@link requireColumnFamily}.
+ *
+ * Standard decorators reach the class through `context.metadata`: the SAME object is handed to every
+ * member decorator of a class and then to the class decorator, in that order. TypeScript only creates
+ * it when `Symbol.metadata` exists (esbuild always creates it), so the polyfill below — the one the
+ * TC39 proposal prescribes — makes the two emits behave identically.
  */
-function inferTypeCastFromDesignType(target, propertyKey) {
-    const designType = Reflect.getMetadata('design:type', target, propertyKey);
-    if (!designType)
-        return undefined;
-    switch (designType) {
-        case Boolean:
-            return {
-                // v2 read contract: BOOLEAN → boolean, via the shared materializer.
-                typeCast: (v) => {
-                    if (v === undefined)
-                        return undefined;
-                    return (0, coltype_1.materializeCell)(v, 'bool');
-                },
-                sqlCast: 'boolean',
-            };
-        case Date:
-            // Auto-inferred Date: same behavior as @column.datetime() — v2 read contract materializes the
-            // date family to a TZ-attached STRING (NOT a TZ-shifted JS Date), via the shared materializer.
-            return {
-                typeCast: (v) => {
-                    if (v === undefined)
-                        return undefined;
-                    return (0, coltype_1.materializeCell)(v, 'date');
-                },
-                // Delegate to driver-specific serializeDatetime
-                serialize: (val, typeCast) => {
-                    if (val === null || val === undefined)
-                        return null;
-                    if (val instanceof Date) {
-                        return typeCast?.serializeDatetime(val) ?? val;
-                    }
-                    return val;
-                },
-                sqlCast: 'timestamp',
-            };
-        case Number:
-            return {
-                typeCast: (v) => {
-                    if (v === undefined)
-                        return undefined;
-                    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 === undefined)
-                        return undefined;
-                    return (0, coltype_1.materializeCell)(v, 'int64');
-                },
-                sqlCast: 'bigint',
-            };
-        // Array, Object, String, and other types require explicit specification
-        default:
-            return undefined;
-    }
+if (typeof Symbol === 'function' && !Symbol.metadata) {
+    // `configurable: true`, as the TC39 proposal's own `Symbol.metadata ??= Symbol('Symbol.metadata')`
+    // leaves it: a library has no business locking a global well-known symbol. Locking it made a
+    // polyfill loaded LATER throw `Cannot redefine property: metadata`. `Symbol.for` keeps the value
+    // identical across copies of this package, so a later polyfill that reuses it is a no-op.
+    Object.defineProperty(Symbol, 'metadata', {
+        value: Symbol.for('Symbol.metadata'),
+        writable: false,
+        enumerable: false,
+        configurable: true,
+    });
 }
 /**
- * Derive the §4.1 SQL-type token from a field's TS `design:type` (Phase F-2 / #105 option B), for a
- * column with NO explicit `sqlCast` family. This types the SCP typed-read de-box for a bare `@column()`
- * (the README shape) — extending the SAME `design:type` source `inferTypeCastFromDesignType` reads for
- * the read cast, so it stays consistent with v1's read contract (String→TEXT→string, Number→INTEGER→
- * number, Boolean→BOOLEAN, Date→TIMESTAMP, BigInt→BIGINT). Returns `undefined` when `design:type` is
- * absent (no `emitDecoratorMetadata`) or is a family with no unambiguous SQL type (Array/Object) — the
- * adapter then falls back to its documented default / the `columnTypes` escape hatch (REAL/DECIMAL/etc.).
+ * Which decorator protocol a decorator was invoked under. Legacy passes `(prototype, propertyKey)`;
+ * standard passes `(value, context)` where `context.kind` names the member being decorated. The
+ * `kind` probe is the discriminator both emits guarantee.
+ * @internal
  */
-function inferBaseSqlTypeFromDesignType(target, propertyKey) {
-    const designType = Reflect.getMetadata('design:type', target, propertyKey);
-    if (!designType)
-        return undefined;
-    switch (designType) {
-        case String:
-            return 'TEXT';
-        case Number:
-            return 'INTEGER';
-        case Boolean:
-            return 'BOOLEAN';
-        case Date:
-            return 'TIMESTAMP';
-        case BigInt:
-            return 'BIGINT';
-        default:
-            // Array / Object / unknown — no unambiguous scalar SQL type. The adapter's escape hatch pins it.
-            return undefined;
+function isStandardContext(second) {
+    return typeof second === 'object' && second !== null && typeof second.kind === 'string';
+}
+/**
+ * The TC39 metadata bag of the class currently being defined. Fail-closed: a toolchain that hands a
+ * decorator no bag cannot register a column at all, and silently dropping it is exactly the class of
+ * defect this file is being repaired for (issue #287) — so it throws, naming the cause.
+ */
+function classMetadataBag(context, propertyKey) {
+    const bag = context.metadata;
+    if (bag === undefined) {
+        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 — import litedbmodel (or 'litedbmodel/decorators') BEFORE the module that defines the model.`);
     }
+    return bag;
 }
 /**
- * Register column metadata on the model class
+ * The COLUMN map a decorator registers into, per protocol.
+ *
+ * A subclass must NOT write into the map it INHERITS: `Reflect.getMetadata` walks the prototype chain
+ * (and a TC39 metadata bag prototype-chains by construction), so mutating the value it returns leaks a
+ * subclass's columns into its base — and from there into every SIBLING subclass that extends the same
+ * decorated base. Both resolvers therefore COPY the inherited map on first write and own the copy.
  */
-function registerColumn(target, propertyKey, options) {
-    const constructor = target.constructor;
-    // Get or create columns map
-    const columns = Reflect.getMetadata(COLUMNS_KEY, constructor) || new Map();
-    // Auto-infer type info if not explicitly provided
-    let finalTypeCast = options.typeCast;
-    let finalSerialize = options.serialize;
-    let finalSqlCast = options.sqlCast;
-    if (!options.skipAutoInfer) {
-        const inferred = inferTypeCastFromDesignType(target, propertyKey);
-        if (inferred) {
-            // Use inferred values only if not explicitly provided
-            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 !== undefined)
+        return own;
+    const inherited = Reflect.getMetadata(COLUMNS_KEY, constructor);
+    const map = new Map(inherited);
+    Reflect.defineMetadata(COLUMNS_KEY, map, constructor);
+    return map;
+}
+/** @see legacyColumnMap */
+function standardColumnMap(bag) {
+    if (!Object.prototype.hasOwnProperty.call(bag, COLUMNS_KEY)) {
+        bag[COLUMNS_KEY] = new Map(bag[COLUMNS_KEY]);
     }
-    // Phase F-2 (#105 option B): record the base SQL-type token from the field's TS `design:type` so the
-    // SCP typed-read de-box can type a bare `@column()` (no explicit sqlCast family) correctly — the fix
-    // for F1's blanket-INTEGER default (which threw `materialize int32` on a live string column). Recorded
-    // always (independent of the auto-infer skip / explicit sqlCast); the adapter consults it only when
-    // there is no explicit `sqlCast` family and no `columnTypes` override.
-    const baseSqlType = inferBaseSqlTypeFromDesignType(target, propertyKey);
+    return bag[COLUMNS_KEY];
+}
+/** The RELATION list a decorator registers into. Copy-on-inherit, exactly as the column map. */
+function legacyRelationList(constructor) {
+    const own = Reflect.getOwnMetadata(RELATIONS_KEY, constructor);
+    if (own !== undefined)
+        return own;
+    const inherited = Reflect.getMetadata(RELATIONS_KEY, constructor);
+    const list = inherited !== undefined ? [...inherited] : [];
+    Reflect.defineMetadata(RELATIONS_KEY, list, constructor);
+    return list;
+}
+/** @see legacyRelationList */
+function standardRelationList(bag) {
+    if (!Object.prototype.hasOwnProperty.call(bag, RELATIONS_KEY)) {
+        const inherited = bag[RELATIONS_KEY];
+        bag[RELATIONS_KEY] = inherited !== undefined ? [...inherited] : [];
+    }
+    return bag[RELATIONS_KEY];
+}
+/**
+ * Record one column on the class being defined. The ONE place a `@column.*` family lands, for both
+ * decorator protocols — the protocol only decides WHICH map is handed in ({@link legacyColumnMap} /
+ * {@link standardColumnMap}).
+ */
+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 !== undefined ? { baseSqlType } : {}),
+        sqlCast: options.sqlCast,
+        ...(options.baseSqlType !== undefined ? { baseSqlType: options.baseSqlType } : {}),
     });
-    Reflect.defineMetadata(COLUMNS_KEY, columns, constructor);
+}
+/** Parse the `columnName | ColumnOptions` argument every family accepts. */
+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 };
 }
 /**
- * Create a column decorator with optional type cast and serialize
+ * Reject a write a TEXT-shaped family cannot carry.
+ *
+ * {@link WriteValue} widens every string-reading column to also accept the `Date` / `bigint` that a
+ * datetime or bigint column serializes, because `Column<V>` carries only the READ type — the type
+ * system cannot tell `@column.text()` from `@column.datetime()` (both read `string`). The FAMILY can,
+ * so it says so here: a `Date` handed to a text column reaches the driver unserialized and PostgreSQL
+ * stores `{}` — silent corruption, measured. Fail closed, naming the family that would have taken it.
+ */
+function rejectNonText(family, val) {
+    if (val === null || val === undefined)
+        return null;
+    if (val instanceof Date) {
+        throw new Error(`litedbmodel: @column.${family}() received a Date. A text column cannot serialize one — 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;
+}
+/**
+ * Read a column whose family declares `string`. Most drivers already hand back a string, 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.
+ */
+function materializeString(family, v) {
+    if (v === undefined || 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.');
+}
+/**
+ * Build one `@column.*` family decorator. The returned decorator accepts BOTH protocols: legacy hands
+ * it `(prototype, propertyKey)`, TC39 standard hands it `(undefined, context)`. Everything that
+ * describes the COLUMN (cast, serializer, SQL family) is fixed here by the family itself — nothing is
+ * read back from the compiler, so every toolchain produces the same model.
+ *
  * @param typeCast - Function to convert DB value to JS value (read)
  * @param serialize - Function to convert JS value to DB value (write)
- * @param skipAutoInfer - If true, skip auto-inference even if typeCast is undefined
- * @param sqlCast - SQL type for automatic casting in conditions (e.g., 'uuid')
+ * @param sqlCast - SQL type family for casting in conditions / typed reads (e.g. `'uuid'`)
+ * @param baseSqlType - §4.1 SQL-type token for a family that applies no cast (`@column.text()`)
  */
-function createColumnDecorator(typeCast, serialize, skipAutoInfer = false, sqlCast) {
+function createColumnDecorator(typeCast, serialize, sqlCast, baseSqlType) {
     return function (columnNameOrOptions) {
-        return function (target, propertyKey) {
-            const propKey = String(propertyKey);
-            // If typeCast is explicitly provided, skip auto-inference
-            const shouldSkipAutoInfer = skipAutoInfer || typeCast !== undefined;
-            // Parse options
-            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 propKey = String(keyOrContext.name);
+                const parsed = parseColumnOptions(columnNameOrOptions, propKey);
+                registerColumn(standardColumnMap(classMetadataBag(keyOrContext, propKey)), propKey, {
+                    ...parsed, typeCast, serialize, sqlCast, baseSqlType,
+                });
+                return;
             }
-            registerColumn(target, propKey, {
-                columnName,
-                typeCast,
-                serialize,
-                skipAutoInfer: shouldSkipAutoInfer,
-                primaryKey,
-                autoIncrement,
-                sqlCast,
+            const propKey = String(keyOrContext);
+            const parsed = parseColumnOptions(columnNameOrOptions, propKey);
+            registerColumn(legacyColumnMap(targetOrValue.constructor), propKey, {
+                ...parsed, typeCast, serialize, sqlCast, baseSqlType,
             });
         };
     };
 }
+/**
+ * The bare `@column()` — REMOVED. It declared no type: it relied on `design:type`, which only exists
+ * under legacy decorators AND `emitDecoratorMetadata`, which esbuild (tsx / vite / vitest) does not
+ * implement and TC39 standard decorators do not have. Where that metadata was absent the column
+ * silently got NO cast and the raw driver value reached the caller — an `integer` read back as a
+ * `bigint`, a `numeric` as a `string` (issue #286). A column states its own type instead.
+ */
+function requireColumnFamily() {
+    throw new Error('litedbmodel: `@column()` no longer declares a column — 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.');
+}
 /**
  * Serialize array using driver's type cast if available.
  * Falls back to PostgreSQL format for backward compatibility.
@@ -293,85 +320,104 @@ function serializeJson(val, typeCast) {
 /**
  * Column decorator for defining model properties.
  *
- * **Auto-inference**: For simple types (boolean, number, Date, bigint),
- * type conversion is automatically inferred from the TypeScript property type.
- * No need to use explicit variants like `@column.boolean()`.
- *
- * Auto-inferred types:
- * ```typescript
- * @column() id?: number;          // Auto: Number conversion
- * @column() name?: string;        // No conversion needed
- * @column() is_active?: boolean;  // Auto: Boolean conversion
- * @column() created_at?: Date;    // Auto: DateTime conversion
- * @column() large_id?: bigint;    // Auto: BigInt conversion
- * @column('custom_name') prop?: string;  // Custom column name
- * ```
+ * **A column declares its own type with a family** — the family decides both the TypeScript type the
+ * model declares and the value `find()` gives back, on every toolchain and under either decorator
+ * protocol. Nothing is inferred from the TypeScript type annotation.
  *
- * Explicit type conversion required (cannot be auto-inferred):
  * ```typescript
- * @column.stringArray() tags?: string[];           // Array element type unknown
- * @column.intArray() scores?: number[];            // Array element type unknown
- * @column.json<MyType>() data?: MyType;            // Generic type unknown
- * @column.date() birth_date?: string;              // date vs datetime distinction
+ * @column.number({ primaryKey: true, autoIncrement: true }) id?: number;
+ * @column.text() name?: string;                // TEXT / VARCHAR / CHAR / ENUM — no cast needed
+ * @column.text('custom_name') prop?: string;   // custom column name
+ * @column.decimal() price?: string;           // NUMERIC / DECIMAL — exact decimal string
+ * @column.boolean() is_active?: boolean;
+ * @column.datetime() created_at?: string;      // TZ-attached string, NOT a JS Date
+ * @column.date() birth_date?: string;          // 'YYYY-MM-DD'
+ * @column.bigint() large_id?: bigint;           // bc `int` — a JS bigint
+ * @column.uuid() ext_id?: string;
+ * @column.stringArray() tags?: string[];
+ * @column.intArray() scores?: number[];
+ * @column.json<MyType>() data?: MyType;
+ * @column.date() birth_date?: string;              // 'YYYY-MM-DD' — not a datetime
+ * @column.passthrough() payload?: unknown;         // BYTEA / BLOB — no cast exists
+ * @column.custom((v) => String(v).toUpperCase()) status?: string;
  * ```
  *
- * Note: The explicit variants (`@column.boolean()`, `@column.datetime()`, etc.)
- * still work and can be used when you want to be explicit about the conversion.
+ * Every family takes what the removed bare `@column()` took: a column name, or {@link ColumnOptions}.
+ * The bare form inferred the type from `emitDecoratorMetadata`, which esbuild (tsx / vite / vitest)
+ * never emits and TC39 standard decorators do not have, so it silently produced untyped reads; it now
+ * reports the migration instead (see {@link requireColumnFamily}).
  *
  * @category Decorators
  */
 exports.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
+    undefined, // 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 === undefined)
             return undefined;
         return (0, coltype_1.materializeCell)(v, 'bool');
     }, undefined, // 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 === undefined)
             return undefined;
         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 === undefined)
             return undefined;
-        return (0, coltype_1.materializeCell)(v, 'int64');
+        return (0, coltype_1.materializeCell)(v, 'int');
     }, undefined, // no custom serialize
-    false, // allow auto-inference
     'bigint' // sqlCast for WHERE/INSERT type casting
-    )(columnName),
+    )(columnNameOrOptions),
     // ============================================
     // Date/Time Types
     // ============================================
@@ -383,9 +429,9 @@ createColumnDecorator(), {
      * - 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.
@@ -402,9 +448,8 @@ createColumnDecorator(), {
             return typeCast?.serializeDatetime(val) ?? val;
         }
         return val;
-    }, false, // allow auto-inference
-    'timestamp' // sqlCast for updateMany type inference
-    )(columnName),
+    }, 'timestamp' // sqlCast for updateMany type inference
+    )(columnNameOrOptions),
     /**
      * Date type conversion — returns YYYY-MM-DD string.
      * Preserves null for nullable columns, undefined stays undefined.
@@ -412,9 +457,9 @@ createColumnDecorator(), {
      * 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((v) => {
+    date: (columnNameOrOptions) => createColumnDecorator((v) => {
         if (v === undefined)
             return undefined;
         if (v === null)
@@ -440,9 +485,8 @@ createColumnDecorator(), {
             return isNaN(val.getTime()) ? null : (0, TypeCast_1.formatLocalDate)(val);
         }
         return val;
-    }, false, // allow auto-inference
-    'date' // sqlCast for updateMany type inference
-    )(columnName),
+    }, 'date' // sqlCast for updateMany type inference
+    )(columnNameOrOptions),
     // ============================================
     // Array Types
     // ============================================
@@ -451,60 +495,65 @@ createColumnDecorator(), {
      * Preserves null for nullable columns, undefined stays undefined
      * @example @column.stringArray() tags?: string[];
      */
-    stringArray: (columnName) => createColumnDecorator((v) => {
+    stringArray: (columnNameOrOptions) => createColumnDecorator((v) => {
         if (v === undefined)
             return undefined;
         if (v === null)
             return null;
         return (0, TypeCast_1.castToStringArray)(v);
-    }, serializeArray, false, 'text[]')(columnName),
+    }, serializeArray, 'text[]')(columnNameOrOptions),
     /**
      * Integer array type conversion (integer[])
      * Preserves null for nullable columns, undefined stays undefined
      * @example @column.intArray() scores?: number[];
      */
-    intArray: (columnName) => createColumnDecorator((v) => {
+    intArray: (columnNameOrOptions) => createColumnDecorator((v) => {
         if (v === undefined)
             return undefined;
         if (v === null)
             return null;
         return (0, TypeCast_1.castToIntegerArray)(v);
-    }, serializeArray, false, 'int[]')(columnName),
+    }, serializeArray, 'int[]')(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((v) => {
+    numericArray: (columnNameOrOptions) => createColumnDecorator((v) => {
         if (v === undefined)
             return undefined;
         if (v === null)
             return null;
         return (0, TypeCast_1.castToNumericArray)(v);
-    }, serializeArray, false, 'numeric[]')(columnName),
+    }, serializeArray, 'numeric[]')(columnNameOrOptions),
     /**
      * Boolean array type conversion (boolean[])
      * Preserves null for nullable columns, undefined stays undefined
      * @example @column.booleanArray() flags?: (boolean | null)[];
      */
-    booleanArray: (columnName) => createColumnDecorator((v) => {
+    booleanArray: (columnNameOrOptions) => createColumnDecorator((v) => {
         if (v === undefined)
             return undefined;
         if (v === null)
             return null;
         return (0, TypeCast_1.castToBooleanArray)(v);
-    }, serializeBooleanArray, false, 'boolean[]')(columnName),
+    }, serializeBooleanArray, 'boolean[]')(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((v) => {
+    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 === undefined)
             return undefined;
         if (v === null)
             return null;
-        return (0, TypeCast_1.castToDatetimeArray)(v);
+        return (0, TypeCast_1.castToDatetimeArray)(v).map((d) => (d === null ? null : (0, coltype_1.materializeCell)(d, 'date')));
     }, 
     // DateTime arrays serialize each Date to ISO string
     (val) => {
@@ -514,7 +563,7 @@ createColumnDecorator(), {
             return val;
         const mapped = val.map(v => v === null ? 'NULL' : (v instanceof Date ? v.toISOString() : String(v)));
         return `{${mapped.join(',')}}`;
-    })(columnName),
+    })(columnNameOrOptions),
     // ============================================
     // JSON Types
     // ============================================
@@ -524,13 +573,13 @@ createColumnDecorator(), {
      * @example @column.json() metadata?: Record<string, unknown>;
      * @example @column.json<UserSettings>() settings?: UserSettings;
      */
-    json: (columnName) => createColumnDecorator((v) => {
+    json: (columnNameOrOptions) => createColumnDecorator((v) => {
         if (v === undefined)
             return undefined;
         if (v === null)
             return null;
         return (0, TypeCast_1.castToJson)(v);
-    }, serializeJson, false, 'jsonb')(columnName),
+    }, serializeJson, 'jsonb')(columnNameOrOptions),
     // ============================================
     // UUID Type (PostgreSQL)
     // ============================================
@@ -560,37 +609,71 @@ createColumnDecorator(), {
             return null;
         // UUID values from DB are typically already strings
         return String(v);
-    }, undefined, // 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),
 });
 // ============================================
 // Relation Decorators
 // ============================================
 /**
- * Register relation metadata on the model class
+ * Record one relation on the class being defined — the ONE place `@hasMany` / `@belongsTo` / `@hasOne`
+ * land, for both decorator protocols. The getter itself is installed once, on the prototype, by
+ * {@link applyModelDecorator}; see {@link createRelationDecorator} for why the standard protocol needs
+ * one extra step to let that getter through.
  */
-function registerRelation(target, propertyKey, type, keysFactory, options) {
-    const constructor = target.constructor;
-    // Get or create relations array
-    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 });
+}
+/**
+ * Build a relation decorator that accepts BOTH protocols.
+ *
+ * Under legacy decorators a relation is declared `declare posts: Promise<Post[]>` — `declare` emits no
+ * field, so the prototype getter `@model` installs is what the instance sees. TC39 standard decorators
+ * REJECT a decorated `declare` field (TS1206), so the relation is declared `posts!: Promise<Post[]>`
+ * instead — and a class field IS defined on the instance (as `undefined`), which would SHADOW that
+ * prototype getter. The initializer below deletes the shadowing own property, so both protocols end up
+ * reading the exact same getter; the getter is not duplicated for the standard path.
+ */
+function createRelationDecorator(type, keys, options) {
+    return function (targetOrValue, keyOrContext) {
+        if (isStandardContext(keyOrContext)) {
+            const propKey = String(keyOrContext.name);
+            registerRelation(standardRelationList(classMetadataBag(keyOrContext, propKey)), propKey, type, keys, options);
+            if (typeof keyOrContext.addInitializer !== 'function') {
+                throw new Error(`litedbmodel: the standard-decorator context for relation '${propKey}' has no ` +
+                    '`addInitializer`, so the class field cannot be removed and would shadow the relation getter.');
+            }
+            keyOrContext.addInitializer(function () {
+                // Only under DEFINE semantics does the field land as an own property that shadows the
+                // prototype getter; under SET semantics the accessor's setter already swallowed it, and
+                // deleting a property that is not there still costs the object its shape.
+                if (Object.prototype.hasOwnProperty.call(this, propKey)) {
+                    delete this[propKey];
+                }
+            });
+            return;
+        }
+        const propKey = String(keyOrContext);
+        registerRelation(legacyRelationList(targetOrValue.constructor), propKey, type, keys, options);
+    };
 }
 /**
  * HasMany relation decorator (1:N).
@@ -601,7 +684,7 @@ function registerRelation(target, propertyKey, type, keysFactory, options) {
  *
  * @example
  * ```typescript
- * // Single key relation
+ * // Single key relation (legacy decorators: `declare`; standard decorators: `posts!: …`)
  * @hasMany(() => [User.id, Post.author_id])
  * declare posts: Promise<Post[]>;
  *
@@ -623,9 +706,7 @@ function registerRelation(target, propertyKey, type, keysFactory, options) {
  * @category Decorators
  */
 function hasMany(keys, options) {
-    return function (target, propertyKey) {
-        registerRelation(target, String(propertyKey), 'hasMany', keys, options);
-    };
+    return createRelationDecorator('hasMany', keys, options);
 }
 /**
  * BelongsTo relation decorator (N:1).
@@ -651,9 +732,7 @@ function hasMany(keys, options) {
  * @category Decorators
  */
 function belongsTo(keys, options) {
-    return function (target, propertyKey) {
-        registerRelation(target, String(propertyKey), 'belongsTo', keys, options);
-    };
+    return createRelationDecorator('belongsTo', keys, options);
 }
 /**
  * HasOne relation decorator (1:1).
@@ -679,9 +758,7 @@ function belongsTo(keys, options) {
  * @category Decorators
  */
 function hasOne(keys, options) {
-    return function (target, propertyKey) {
-        registerRelation(target, String(propertyKey), 'hasOne', keys, options);
-    };
+    return createRelationDecorator('hasOne', keys, options);
 }
 /**
  * Get relation metadata from a model class
@@ -693,16 +770,62 @@ function getRelationMeta(modelClass) {
         []);
 }
 // Implementation
-function model(tableNameOrConstructor, options) {
+function model(tableNameOrConstructor, 
+// `@model('t', options)` passes ModelOptions; a bare `@model` under the standard protocol passes the
+// ClassDecoratorContext in this position instead.
+optionsOrContext) {
     // Called as @model('table_name') or @model('table_name', options)
     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);
+        };
+    }
+    // Called as `@model` without parentheses. The standard protocol invokes a CLASS decorator as
+    // `(value, context)`, so the second argument here is that CONTEXT, not `ModelOptions` — reading it
+    // as options and applying the legacy path registered a model with NO columns at all, silently.
+    return applyToClass(tableNameOrConstructor, optionsOrContext);
+}
+/**
+ * Apply `@model` under either decorator protocol. The ONE place the class decorator's protocol
+ * difference lives, so `@model` and `@model('t')` cannot diverge.
+ *
+ * Under the standard protocol the class is not finished when its decorator runs: a bundler that
+ * preserves names (esbuild's `--keep-names`, which `tsx` turns on) re-defines `Class.name` AFTER the
+ * decorator returns. Installing the static column accessors here would either be clobbered by that,
+ * or — since they are non-configurable — make it throw `Cannot redefine property: name` on any model
+ * with a `name` column. A class decorator's extra initializer is the one hook that runs after the
+ * class is fully formed, so the model is assembled there.
+ */
+function applyToClass(constructor, context, tableName, options) {
+    const members = modelMembers(constructor, context);
+    if (!isStandardContext(context))
+        return applyModelDecorator(constructor, members, tableName, options);
+    // Fail-closed, exactly as `classMetadataBag` does: assembling nothing and returning the class is how
+    // a model ends up with no columns and no error — the defect this file exists to remove.
+    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;
+}
+/** The columns + relations `@column.*` / `@hasMany` … recorded for this class, per protocol. */
+function modelMembers(constructor, context) {
+    if (isStandardContext(context)) {
+        const bag = classMetadataBag(context, String(constructor.name ?? 'model'));
+        return {
+            columns: bag[COLUMNS_KEY] ?? new Map(),
+            relations: bag[RELATIONS_KEY] ?? [],
         };
     }
-    // Called as @model (without parentheses or arguments)
-    return applyModelDecorator(tableNameOrConstructor);
+    return {
+        columns: Reflect.getMetadata(COLUMNS_KEY, constructor) ?? new Map(),
+        relations: Reflect.getMetadata(RELATIONS_KEY, constructor) ?? [],
+    };
 }
 /**
  * Check if keys are composite (array of pairs) or single pair
@@ -738,9 +861,8 @@ function parseKeys(keys) {
 /**
  * Internal function to apply the model decorator
  */
-function applyModelDecorator(constructor, tableName, options) {
-    const columns = Reflect.getMetadata(COLUMNS_KEY, constructor) || new Map();
-    const relations = Reflect.getMetadata(RELATIONS_KEY, constructor) || [];
+function applyModelDecorator(constructor, members, tableName, options) {
+    const { columns, relations } = members;
     const modelName = constructor.name;
     // 0. Set TABLE_NAME if provided
     if (tableName) {
@@ -807,7 +929,7 @@ function applyModelDecorator(constructor, tableName, options) {
     const effectiveTableName = tableName ?? modelName.toLowerCase();
     for (const [propKey, meta] of columns) {
         Object.defineProperty(constructor, propKey, {
-            value: (0, Column_1.createColumn)(meta.columnName, effectiveTableName, modelName, propKey, meta.sqlCast),
+            value: (0, Column_1.createColumn)(meta.columnName, effectiveTableName, modelName, propKey, meta.sqlCast, meta.serialize),
             writable: false,
             enumerable: true,
             configurable: false,
@@ -865,18 +987,38 @@ function applyModelDecorator(constructor, tableName, options) {
                 const { sourceKeys, targetKeys, targetModelName } = parseKeys(keys);
                 // Build relation config
                 const order = options?.order ? (0, Column_1.orderToString)(options.order()) : null;
-                const conditions = options?.where ? (0, Column_1.condsToRecord)(options.where()) : undefined;
                 // Call internal relation method
                 return this._loadRelation(type, targetModelName, {
                     sourceKeys,
                     targetKeys,
                     order,
-                    conditions,
+                    where: options?.where?.(),
                     limit: options?.limit,
                     hardLimit: options?.hardLimit,
                     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 === undefined)
+                    return;
+                Object.defineProperty(this, propertyKey, {
+                    value,
+                    writable: true,
+                    enumerable: true,
+                    configurable: true,
+                });
+            },
             enumerable: true,
             configurable: false,
         });