litedbmodel 2.2.6 → 2.2.8

package/docs/api/functions/parentRef.md

@@ -1,4 +1,4 @@
-[**litedbmodel v2.2.6**](../README.md)
+[**litedbmodel v2.2.8**](../README.md)
 
 ***
 

package/docs/api/functions/sql.md

@@ -1,4 +1,4 @@
-[**litedbmodel v2.2.6**](../README.md)
+[**litedbmodel v2.2.8**](../README.md)
 
 ***
 

package/docs/api/globals.md

@@ -1,8 +1,8 @@
-[**litedbmodel v2.2.6**](README.md)
+[**litedbmodel v2.2.8**](README.md)
 
 ***
 
-# litedbmodel v2.2.6
+# litedbmodel v2.2.8
 
 litedbmodel - A lightweight TypeScript data access layer
 
@@ -37,6 +37,12 @@ Supports PostgreSQL and SQLite databases.
 
 ## Interfaces
 
+### Decorators
+
+- [ColumnDecorator](interfaces/ColumnDecorator.md)
+- [RelationDecorator](interfaces/RelationDecorator.md)
+- [ModelClassDecorator](interfaces/ModelClassDecorator.md)
+
 ### Types
 
 - [PkeyResult](interfaces/PkeyResult.md)
@@ -63,17 +69,44 @@ Supports PostgreSQL and SQLite databases.
 
 ## Type Aliases
 
-### SkipType
+### Column
+
+#### WriteValue
 
 ```ts
-type SkipType = typeof SKIP;
+type WriteValue<V> = V | V extends string ? Date | bigint : never;
 ```
 
 Defined in: [Column.ts:780](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L780)
 
+What a column ACCEPTS on write, given the type it READS BACK.
+
+A `@column.datetime()` / `.date()` / `.bigint()` column reads a string — the column's own textual
+form, or a BIGINT's exact decimal — but the write path still takes the JS value that string stands
+for: a `Date` goes through the driver's dialect-specific datetime serializer (MySQL wants a local
+`YYYY-MM-DD HH:mm:ss`, PostgreSQL an ISO instant, and getting that right is the library's job, not
+the caller's), and a `bigint` is written as its exact digits. TypeScript cannot tell those columns
+from a plain text one — all of them read `string` — so the widening applies to every string column.
+
+##### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `V` |
+
+### Other
+
+#### SkipType
+
+```ts
+type SkipType = typeof SKIP;
+```
+
+Defined in: [Column.ts:805](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L805)
+
 ***
 
-### MiddlewareClass
+#### MiddlewareClass
 
 ```ts
 type MiddlewareClass = {
@@ -98,9 +131,9 @@ the assigned own property wins over the prototype method). So the DOCUMENTED pai
 (`DBModel.use(DBModel.createMiddleware(…))`, README) did not typecheck even though it is the
 runtime-correct call, and every stateful middleware in the README was affected.
 
-#### Methods
+##### Methods
 
-##### getCurrentContext()
+###### getCurrentContext()
 
 ```ts
 getCurrentContext(): object;
@@ -114,7 +147,7 @@ Defined in: [Middleware.ts:310](https://github.com/foo-ogawa/litedbmodel/blob/ma
 
 ***
 
-### SqlInterpolation
+#### SqlInterpolation
 
 ```ts
 type SqlInterpolation = 
@@ -155,69 +188,77 @@ Union of all types allowed as interpolated values in `sql` tagged templates.
 #### column
 
 ```ts
-const column: (columnNameOrOptions?: string | ColumnOptions) => PropertyDecorator & {
-  boolean: (columnName?: string) => PropertyDecorator;
-  number: (columnName?: string) => PropertyDecorator;
-  bigint: (columnName?: string) => PropertyDecorator;
-  datetime: (columnName?: string) => PropertyDecorator;
-  date: (columnName?: string) => PropertyDecorator;
-  stringArray: (columnName?: string) => PropertyDecorator;
-  intArray: (columnName?: string) => PropertyDecorator;
-  numericArray: (columnName?: string) => PropertyDecorator;
-  booleanArray: (columnName?: string) => PropertyDecorator;
-  datetimeArray: (columnName?: string) => PropertyDecorator;
-  json: <T>(columnName?: string) => PropertyDecorator;
-  uuid: (columnNameOrOptions?: string | ColumnOptions) => PropertyDecorator;
-  custom: <T>(castFn: (value: unknown) => T, serializeFn?: SerializeFn, columnName?: string) => PropertyDecorator;
+const column: (_columnNameOrOptions?: string | ColumnOptions) => never & {
+  text: (columnNameOrOptions?: string | ColumnOptions) => ColumnDecorator<string | null | undefined>;
+  decimal: (columnNameOrOptions?: string | ColumnOptions) => ColumnDecorator<string | null | undefined>;
+  boolean: (columnNameOrOptions?: string | ColumnOptions) => ColumnDecorator<boolean | null | undefined>;
+  number: (columnNameOrOptions?: string | ColumnOptions) => ColumnDecorator<number | null | undefined>;
+  bigint: (columnNameOrOptions?: string | ColumnOptions) => ColumnDecorator<bigint | null | undefined>;
+  datetime: (columnNameOrOptions?: string | ColumnOptions) => ColumnDecorator<string | null | undefined>;
+  date: (columnNameOrOptions?: string | ColumnOptions) => ColumnDecorator<string | null | undefined>;
+  stringArray: (columnNameOrOptions?: string | ColumnOptions) => ColumnDecorator<string[] | null | undefined>;
+  intArray: (columnNameOrOptions?: string | ColumnOptions) => ColumnDecorator<number[] | null | undefined>;
+  numericArray: (columnNameOrOptions?: string | ColumnOptions) => ColumnDecorator<(number | null)[] | null | undefined>;
+  booleanArray: (columnNameOrOptions?: string | ColumnOptions) => ColumnDecorator<(boolean | null)[] | null | undefined>;
+  datetimeArray: (columnNameOrOptions?: string | ColumnOptions) => ColumnDecorator<(string | null)[] | null | undefined>;
+  json: <T>(columnNameOrOptions?: string | ColumnOptions) => ColumnDecorator<T | null | undefined>;
+  uuid: (columnNameOrOptions?: string | ColumnOptions) => ColumnDecorator<string | null | undefined>;
+  passthrough: (columnNameOrOptions?: string | ColumnOptions) => ColumnDecorator<unknown>;
+  custom: <T>(castFn: (value: unknown) => T, serializeFn?: SerializeFn, columnNameOrOptions?: string | ColumnOptions) => ColumnDecorator<T | null | undefined>;
 };
 ```
 
-Defined in: [decorators.ts:516](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L516)
+Defined in: [decorators.ts:598](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L598)
 
 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()`.
+**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.
 
-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
+@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;
 ```
 
-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
-```
-
-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 [ColumnOptions](interfaces/ColumnOptions.md).
+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 requireColumnFamily).
 
 ##### Type Declaration
 
 | Name | Type | Description | Defined in |
 | ------ | ------ | ------ | ------ |
-| `boolean()` | (`columnName?`: `string`) => `PropertyDecorator` | 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;` | [decorators.ts:530](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L530) |
-| `number()` | (`columnName?`: `string`) => `PropertyDecorator` | Number type conversion (from string) Preserves null for nullable columns, undefined stays undefined **Example** `@column.number() amount?: number;` | [decorators.ts:547](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L547) |
-| `bigint()` | (`columnName?`: `string`) => `PropertyDecorator` | BigInt type conversion Preserves null for nullable columns, undefined stays undefined **Example** `@column.bigint() large_id?: bigint;` | [decorators.ts:560](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L560) |
-| `datetime()` | (`columnName?`: `string`) => `PropertyDecorator` | DateTime type conversion (timestamp, timestamptz) Preserves null for nullable columns, undefined stays undefined Timezone handling: - 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;` | [decorators.ts:588](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L588) |
-| `date()` | (`columnName?`: `string`) => `PropertyDecorator` | Date type conversion — returns YYYY-MM-DD string. Preserves null for nullable columns, undefined stays undefined. 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;` | [decorators.ts:618](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L618) |
-| `stringArray()` | (`columnName?`: `string`) => `PropertyDecorator` | String array type conversion (text[]) Preserves null for nullable columns, undefined stays undefined **Example** `@column.stringArray() tags?: string[];` | [decorators.ts:657](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L657) |
-| `intArray()` | (`columnName?`: `string`) => `PropertyDecorator` | Integer array type conversion (integer[]) Preserves null for nullable columns, undefined stays undefined **Example** `@column.intArray() scores?: number[];` | [decorators.ts:674](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L674) |
-| `numericArray()` | (`columnName?`: `string`) => `PropertyDecorator` | Numeric array type conversion (numeric[], allows null elements) Preserves null for nullable columns, undefined stays undefined **Example** `@column.numericArray() values?: (number | null)[];` | [decorators.ts:691](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L691) |
-| `booleanArray()` | (`columnName?`: `string`) => `PropertyDecorator` | Boolean array type conversion (boolean[]) Preserves null for nullable columns, undefined stays undefined **Example** `@column.booleanArray() flags?: (boolean | null)[];` | [decorators.ts:708](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L708) |
-| `datetimeArray()` | (`columnName?`: `string`) => `PropertyDecorator` | DateTime array type conversion (timestamp[]) Preserves null for nullable columns, undefined stays undefined **Example** `@column.datetimeArray() event_dates?: (Date | null)[];` | [decorators.ts:725](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L725) |
-| `json()` | \<`T`\>(`columnName?`: `string`) => `PropertyDecorator` | JSON/JSONB type conversion Preserves null for nullable columns, undefined stays undefined **Examples** `@column.json() metadata?: Record<string, unknown>;` `@column.json<UserSettings>() settings?: UserSettings;` | [decorators.ts:751](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L751) |
-| `uuid()` | (`columnNameOrOptions?`: `string` \| [`ColumnOptions`](interfaces/ColumnOptions.md)) => `PropertyDecorator` | UUID type with automatic casting for PostgreSQL. Automatically adds ::uuid cast to conditions and INSERT/UPDATE values. Preserves null for nullable columns, undefined stays undefined. **Example** `@column.uuid() id?: string; @column.uuid({ primaryKey: true }) id?: string; // Conditions automatically cast to UUID: await User.find([[User.id, 'uuid-string']]); // → WHERE id = ?::uuid // IN clauses also cast: await User.find([[User.id, ['uuid1', 'uuid2']]]); // → WHERE id IN (?::uuid, ?::uuid)` | [decorators.ts:786](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L786) |
-| `custom()` | \<`T`\>(`castFn`: (`value`: `unknown`) => `T`, `serializeFn?`: `SerializeFn`, `columnName?`: `string`) => `PropertyDecorator` | Custom type conversion with user-provided function **Examples** `@column.custom((v) => String(v).toUpperCase()) status?: string;` `@column.custom((v) => v, (v) => JSON.stringify(v)) data?: MyType; // with serializer` | [decorators.ts:808](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L808) |
+| `text()` | (`columnNameOrOptions?`: `string` \| [`ColumnOptions`](interfaces/ColumnOptions.md)) => [`ColumnDecorator`](interfaces/ColumnDecorator.md)\<`string` \| `null` \| `undefined`\> | 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`. **Examples** `@column.text() name?: string;` `@column.text('user_name') name?: string;` | [decorators.ts:612](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L612) |
+| `decimal()` | (`columnNameOrOptions?`: `string` \| [`ColumnOptions`](interfaces/ColumnOptions.md)) => [`ColumnDecorator`](interfaces/ColumnDecorator.md)\<`string` \| `null` \| `undefined`\> | 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;` | [decorators.ts:626](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L626) |
+| `boolean()` | (`columnNameOrOptions?`: `string` \| [`ColumnOptions`](interfaces/ColumnOptions.md)) => [`ColumnDecorator`](interfaces/ColumnDecorator.md)\<`boolean` \| `null` \| `undefined`\> | 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;` | [decorators.ts:639](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L639) |
+| `number()` | (`columnNameOrOptions?`: `string` \| [`ColumnOptions`](interfaces/ColumnOptions.md)) => [`ColumnDecorator`](interfaces/ColumnDecorator.md)\<`number` \| `null` \| `undefined`\> | Number type conversion (from string) Preserves null for nullable columns, undefined stays undefined **Example** `@column.number() amount?: number;` | [decorators.ts:655](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L655) |
+| `bigint()` | (`columnNameOrOptions?`: `string` \| [`ColumnOptions`](interfaces/ColumnOptions.md)) => [`ColumnDecorator`](interfaces/ColumnDecorator.md)\<`bigint` \| `null` \| `undefined`\> | BigInt type conversion Preserves null for nullable columns, undefined stays undefined **Example** `@column.bigint() large_id?: bigint; // bc `int` — a JS bigint, checked i64` | [decorators.ts:668](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L668) |
+| `datetime()` | (`columnNameOrOptions?`: `string` \| [`ColumnOptions`](interfaces/ColumnOptions.md)) => [`ColumnDecorator`](interfaces/ColumnDecorator.md)\<`string` \| `null` \| `undefined`\> | DateTime type conversion (timestamp, timestamptz) Preserves null for nullable columns, undefined stays undefined Timezone handling: - 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?: string; // TZ-attached string, NOT a JS Date` | [decorators.ts:695](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L695) |
+| `date()` | (`columnNameOrOptions?`: `string` \| [`ColumnOptions`](interfaces/ColumnOptions.md)) => [`ColumnDecorator`](interfaces/ColumnDecorator.md)\<`string` \| `null` \| `undefined`\> | Date type conversion — returns YYYY-MM-DD string. Preserves null for nullable columns, undefined stays undefined. 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; // 'YYYY-MM-DD'` | [decorators.ts:724](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L724) |
+| `stringArray()` | (`columnNameOrOptions?`: `string` \| [`ColumnOptions`](interfaces/ColumnOptions.md)) => [`ColumnDecorator`](interfaces/ColumnDecorator.md)\<`string`[] \| `null` \| `undefined`\> | String array type conversion (text[]) Preserves null for nullable columns, undefined stays undefined **Example** `@column.stringArray() tags?: string[];` | [decorators.ts:762](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L762) |
+| `intArray()` | (`columnNameOrOptions?`: `string` \| [`ColumnOptions`](interfaces/ColumnOptions.md)) => [`ColumnDecorator`](interfaces/ColumnDecorator.md)\<`number`[] \| `null` \| `undefined`\> | Integer array type conversion (integer[]) Preserves null for nullable columns, undefined stays undefined **Example** `@column.intArray() scores?: number[];` | [decorators.ts:778](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L778) |
+| `numericArray()` | (`columnNameOrOptions?`: `string` \| [`ColumnOptions`](interfaces/ColumnOptions.md)) => [`ColumnDecorator`](interfaces/ColumnDecorator.md)\<(`number` \| `null`)[] \| `null` \| `undefined`\> | Numeric array type conversion (numeric[], allows null elements) Preserves null for nullable columns, undefined stays undefined **Example** `@column.numericArray() values?: (number | null)[];` | [decorators.ts:794](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L794) |
+| `booleanArray()` | (`columnNameOrOptions?`: `string` \| [`ColumnOptions`](interfaces/ColumnOptions.md)) => [`ColumnDecorator`](interfaces/ColumnDecorator.md)\<(`boolean` \| `null`)[] \| `null` \| `undefined`\> | Boolean array type conversion (boolean[]) Preserves null for nullable columns, undefined stays undefined **Example** `@column.booleanArray() flags?: (boolean | null)[];` | [decorators.ts:810](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L810) |
+| `datetimeArray()` | (`columnNameOrOptions?`: `string` \| [`ColumnOptions`](interfaces/ColumnOptions.md)) => [`ColumnDecorator`](interfaces/ColumnDecorator.md)\<(`string` \| `null`)[] \| `null` \| `undefined`\> | DateTime array type conversion (timestamp[]) Preserves null for nullable columns, undefined stays undefined **Example** `@column.datetimeArray() event_dates?: (string | null)[];` | [decorators.ts:826](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L826) |
+| `json()` | \<`T`\>(`columnNameOrOptions?`: `string` \| [`ColumnOptions`](interfaces/ColumnOptions.md)) => [`ColumnDecorator`](interfaces/ColumnDecorator.md)\<`T` \| `null` \| `undefined`\> | JSON/JSONB type conversion Preserves null for nullable columns, undefined stays undefined **Examples** `@column.json() metadata?: Record<string, unknown>;` `@column.json<UserSettings>() settings?: UserSettings;` | [decorators.ts:856](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L856) |
+| `uuid()` | (`columnNameOrOptions?`: `string` \| [`ColumnOptions`](interfaces/ColumnOptions.md)) => [`ColumnDecorator`](interfaces/ColumnDecorator.md)\<`string` \| `null` \| `undefined`\> | UUID type with automatic casting for PostgreSQL. Automatically adds ::uuid cast to conditions and INSERT/UPDATE values. Preserves null for nullable columns, undefined stays undefined. **Example** `@column.uuid() id?: string; @column.uuid({ primaryKey: true }) id?: string; // Conditions automatically cast to UUID: await User.find([[User.id, 'uuid-string']]); // → WHERE id = ?::uuid // IN clauses also cast: await User.find([[User.id, ['uuid1', 'uuid2']]]); // → WHERE id IN (?::uuid, ?::uuid)` | [decorators.ts:890](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L890) |
+| `passthrough()` | (`columnNameOrOptions?`: `string` \| [`ColumnOptions`](interfaces/ColumnOptions.md)) => [`ColumnDecorator`](interfaces/ColumnDecorator.md)\<`unknown`\> | 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;` | [decorators.ts:913](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L913) |
+| `custom()` | \<`T`\>(`castFn`: (`value`: `unknown`) => `T`, `serializeFn?`: `SerializeFn`, `columnNameOrOptions?`: `string` \| [`ColumnOptions`](interfaces/ColumnOptions.md)) => [`ColumnDecorator`](interfaces/ColumnDecorator.md)\<`T` \| `null` \| `undefined`\> | Custom type conversion with user-provided function **Examples** `@column.custom((v) => String(v).toUpperCase()) status?: string;` `@column.custom((v) => v, (v) => JSON.stringify(v)) data?: MyType; // with serializer` | [decorators.ts:921](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L921) |
 
 ### Other
 
@@ -227,7 +268,7 @@ still work and can be used when you want to be explicit about the conversion.
 const SKIP: typeof SKIP;
 ```
 
-Defined in: [Column.ts:779](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L779)
+Defined in: [Column.ts:804](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L804)
 
 Sentinel value to skip a field in create/update operations.
 Use with conditional expressions to keep code as expressions instead of statements.
@@ -254,7 +295,6 @@ await User.update(conds, [
 - [hasMany](functions/hasMany.md)
 - [belongsTo](functions/belongsTo.md)
 - [hasOne](functions/hasOne.md)
-- [model](functions/model.md)
 
 ### Middleware
 
@@ -293,6 +333,7 @@ await User.update(conds, [
 - [formatLocalDate](functions/formatLocalDate.md)
 - [formatUTCDate](functions/formatUTCDate.md)
 - [isConnectionError](functions/isConnectionError.md)
+- [model](functions/model.md)
 - [createPostgresDriver](functions/createPostgresDriver.md)
 - [createSqliteDriver](functions/createSqliteDriver.md)
 

package/docs/api/interfaces/Column.md

@@ -1,4 +1,4 @@
-[**litedbmodel v2.2.6**](../README.md)
+[**litedbmodel v2.2.8**](../README.md)
 
 ***
 
@@ -6,7 +6,7 @@
 
 # Interface: Column()\<ValueType, ModelType\>
 
-Defined in: [Column.ts:144](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L144)
+Defined in: [Column.ts:145](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L145)
 
 Type-safe column reference as a callable function.
 
@@ -21,7 +21,7 @@ Type-safe column reference as a callable function.
 Column(): string;
 ```
 
-Defined in: [Column.ts:146](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L146)
+Defined in: [Column.ts:147](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L147)
 
 Call to get column name as string (for computed property keys)
 
@@ -33,13 +33,14 @@ Call to get column name as string (for computed property keys)
 
 | Property | Modifier | Type | Description | Defined in |
 | ------ | ------ | ------ | ------ | ------ |
-| <a id="columnname"></a> `columnName` | `readonly` | `string` | The database column name | [Column.ts:149](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L149) |
-| <a id="propertyname"></a> `propertyName` | `readonly` | `string` | The property name on the model class (may differ from columnName) | [Column.ts:152](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L152) |
-| <a id="tablename"></a> `tableName` | `readonly` | `string` | The database table name | [Column.ts:155](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L155) |
-| <a id="modelname"></a> `modelName` | `readonly` | `string` | The model class name (for debugging and static analysis) | [Column.ts:158](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L158) |
-| <a id="_brand"></a> `_brand` | `readonly` | `"Column"` | Brand for type discrimination - enables static analysis to distinguish from regular variables | [Column.ts:161](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L161) |
-| <a id="sqlcast"></a> `sqlCast?` | `readonly` | `string` | SQL type for automatic casting in conditions (e.g., 'uuid') | [Column.ts:164](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L164) |
-| <a id="__model"></a> `__model?` | `readonly` | `ModelType` | Phantom type for model association (compile-time only, not used at runtime) | [Column.ts:167](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L167) |
+| <a id="columnname"></a> `columnName` | `readonly` | `string` | The database column name | [Column.ts:150](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L150) |
+| <a id="propertyname"></a> `propertyName` | `readonly` | `string` | The property name on the model class (may differ from columnName) | [Column.ts:153](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L153) |
+| <a id="tablename"></a> `tableName` | `readonly` | `string` | The database table name | [Column.ts:156](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L156) |
+| <a id="modelname"></a> `modelName` | `readonly` | `string` | The model class name (for debugging and static analysis) | [Column.ts:159](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L159) |
+| <a id="_brand"></a> `_brand` | `readonly` | `"Column"` | Brand for type discrimination - enables static analysis to distinguish from regular variables | [Column.ts:162](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L162) |
+| <a id="sqlcast"></a> `sqlCast?` | `readonly` | `string` | SQL type for automatic casting in conditions (e.g., 'uuid') | [Column.ts:165](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L165) |
+| <a id="serialize"></a> `serialize?` | `readonly` | (`value`: `unknown`, `typeCast?`: `DriverTypeCast`) => `unknown` | The column family's serializer: a condition value binds exactly as a written value does | [Column.ts:168](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L168) |
+| <a id="__model"></a> `__model?` | `readonly` | `ModelType` | Phantom type for model association (compile-time only, not used at runtime) | [Column.ts:171](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L171) |
 
 ## Methods
 
@@ -49,7 +50,7 @@ Call to get column name as string (for computed property keys)
 eq(value: ValueType): Record<string, ValueType | DBCast>;
 ```
 
-Defined in: [Column.ts:177](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L177)
+Defined in: [Column.ts:181](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L181)
 
 Equal condition (column = value)
 
@@ -77,7 +78,7 @@ User.id.eq(1) → { id: 1 }
 ne(value: ValueType): Record<string, ValueType | DBCast>;
 ```
 
-Defined in: [Column.ts:183](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L183)
+Defined in: [Column.ts:187](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L187)
 
 Not equal condition (column != value)
 
@@ -105,7 +106,7 @@ User.status.ne('deleted') → { 'status != ?': 'deleted' }
 gt(value: ValueType): Record<string, ValueType | DBCast>;
 ```
 
-Defined in: [Column.ts:189](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L189)
+Defined in: [Column.ts:193](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L193)
 
 Greater than condition (column > value)
 
@@ -133,7 +134,7 @@ User.age.gt(18) → { 'age > ?': 18 }
 gte(value: ValueType): Record<string, ValueType | DBCast>;
 ```
 
-Defined in: [Column.ts:195](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L195)
+Defined in: [Column.ts:199](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L199)
 
 Greater than or equal condition (column >= value)
 
@@ -161,7 +162,7 @@ User.age.gte(18) → { 'age >= ?': 18 }
 lt(value: ValueType): Record<string, ValueType | DBCast>;
 ```
 
-Defined in: [Column.ts:201](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L201)
+Defined in: [Column.ts:205](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L205)
 
 Less than condition (column < value)
 
@@ -189,7 +190,7 @@ User.age.lt(65) → { 'age < ?': 65 }
 lte(value: ValueType): Record<string, ValueType | DBCast>;
 ```
 
-Defined in: [Column.ts:207](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L207)
+Defined in: [Column.ts:211](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L211)
 
 Less than or equal condition (column <= value)
 
@@ -217,7 +218,7 @@ User.age.lte(65) → { 'age <= ?': 65 }
 like(pattern: string): Record<string, string>;
 ```
 
-Defined in: [Column.ts:213](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L213)
+Defined in: [Column.ts:217](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L217)
 
 LIKE condition (column LIKE pattern)
 
@@ -245,7 +246,7 @@ User.name.like('%test%') → { 'name LIKE ?': '%test%' }
 notLike(pattern: string): Record<string, string>;
 ```
 
-Defined in: [Column.ts:219](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L219)
+Defined in: [Column.ts:223](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L223)
 
 NOT LIKE condition (column NOT LIKE pattern)
 
@@ -273,7 +274,7 @@ User.name.notLike('%test%') → { 'name NOT LIKE ?': '%test%' }
 ilike(pattern: string): Record<string, string>;
 ```
 
-Defined in: [Column.ts:225](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L225)
+Defined in: [Column.ts:229](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L229)
 
 ILIKE condition (case-insensitive LIKE, PostgreSQL specific)
 
@@ -301,7 +302,7 @@ User.name.ilike('%TEST%') → { 'name ILIKE ?': '%TEST%' }
 between(from: ValueType, to: ValueType): Record<string, [ValueType, ValueType]>;
 ```
 
-Defined in: [Column.ts:231](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L231)
+Defined in: [Column.ts:235](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L235)
 
 BETWEEN condition (column BETWEEN from AND to)
 
@@ -330,7 +331,7 @@ User.age.between(18, 65) → { 'age BETWEEN ? AND ?': [18, 65] }
 in(values: ValueType[]): Record<string, ValueType[] | DBCastArray>;
 ```
 
-Defined in: [Column.ts:238](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L238)
+Defined in: [Column.ts:242](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L242)
 
 IN condition (column IN (values))
 Note: Arrays are automatically converted to IN clause by litedbmodel
@@ -359,7 +360,7 @@ User.status.in(['active', 'pending']) → { status: ['active', 'pending'] }
 notIn(values: ValueType[]): Record<string, ValueType[] | DBCastArray>;
 ```
 
-Defined in: [Column.ts:244](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L244)
+Defined in: [Column.ts:248](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L248)
 
 NOT IN condition (column NOT IN (values))
 
@@ -387,7 +388,7 @@ User.status.notIn(['deleted', 'banned'])
 isNull(): Record<string, null>;
 ```
 
-Defined in: [Column.ts:250](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L250)
+Defined in: [Column.ts:254](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L254)
 
 IS NULL condition
 
@@ -409,7 +410,7 @@ User.deleted_at.isNull() → { deleted_at: null }
 isNotNull(): Record<string, DBNotNullValue>;
 ```
 
-Defined in: [Column.ts:256](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L256)
+Defined in: [Column.ts:260](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L260)
 
 IS NOT NULL condition
 
@@ -431,7 +432,7 @@ User.email.isNotNull() → { email: DBNotNullValue }
 asc(): OrderColumn<ModelType>;
 ```
 
-Defined in: [Column.ts:266](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L266)
+Defined in: [Column.ts:270](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L270)
 
 Ascending order
 
@@ -453,7 +454,7 @@ User.created_at.asc() → OrderColumn('created_at', 'ASC')
 desc(): OrderColumn<ModelType>;
 ```
 
-Defined in: [Column.ts:272](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L272)
+Defined in: [Column.ts:276](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L276)
 
 Descending order
 
@@ -475,7 +476,7 @@ User.created_at.desc() → OrderColumn('created_at', 'DESC')
 ascNullsFirst(): OrderColumn<ModelType>;
 ```
 
-Defined in: [Column.ts:278](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L278)
+Defined in: [Column.ts:282](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L282)
 
 Ascending order with NULLS FIRST
 
@@ -497,7 +498,7 @@ User.updated_at.ascNullsFirst() → OrderColumn with NULLS FIRST
 ascNullsLast(): OrderColumn<ModelType>;
 ```
 
-Defined in: [Column.ts:284](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L284)
+Defined in: [Column.ts:288](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L288)
 
 Ascending order with NULLS LAST
 
@@ -519,7 +520,7 @@ User.updated_at.ascNullsLast() → OrderColumn with NULLS LAST
 descNullsFirst(): OrderColumn<ModelType>;
 ```
 
-Defined in: [Column.ts:290](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L290)
+Defined in: [Column.ts:294](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L294)
 
 Descending order with NULLS FIRST
 
@@ -541,7 +542,7 @@ User.updated_at.descNullsFirst() → OrderColumn with NULLS FIRST
 descNullsLast(): OrderColumn<ModelType>;
 ```
 
-Defined in: [Column.ts:296](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L296)
+Defined in: [Column.ts:300](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L300)
 
 Descending order with NULLS LAST
 
@@ -563,7 +564,7 @@ User.updated_at.descNullsLast() → OrderColumn with NULLS LAST
 toString(): string;
 ```
 
-Defined in: [Column.ts:306](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L306)
+Defined in: [Column.ts:310](https://github.com/foo-ogawa/litedbmodel/blob/main/src/Column.ts#L310)
 
 Returns column name (for template literals)
 

package/docs/api/interfaces/ColumnDecorator.md

@@ -0,0 +1,81 @@
+[**litedbmodel v2.2.8**](../README.md)
+
+***
+
+[litedbmodel](../globals.md) / ColumnDecorator
+
+# Interface: ColumnDecorator()\<Value\>
+
+Defined in: [decorators.ts:351](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L351)
+
+What a `@column.*` decorator may be applied to, under EITHER protocol.
+
+Both overloads are typed: `Value` is the decorated field's declared TS type, so a family whose read
+contract yields a `string` (`@column.datetime()`, `@column.bigint()`, …) will not compile onto a
+field declared `Date` / `bigint`. That is the compile-time half of the fix for the "declared type ≠
+value `find()` returns" defect (issue #286), and it holds under BOTH protocols — the legacy
+property decorator receives the prototype, whose property types a mapped type can constrain.
+
+## Type Parameters
+
+| Type Parameter |
+| ------ |
+| `Value` |
+
+## Call Signature
+
+```ts
+ColumnDecorator<This, Key>(target: This, propertyKey: Key): void;
+```
+
+Defined in: [decorators.ts:358](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L358)
+
+Legacy (`experimentalDecorators`) property decorator. The prototype it receives IS typed, so the
+decorated property's declared type is constrained here too — `@column.datetime() x?: Date` does
+not compile under either protocol. (It was believed legacy carried no type information; it does,
+and the majority of models are compiled that way.)
+
+### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `This` *extends* `Partial`\<`Record`\<`Key`, `Value`\>\> |
+| `Key` *extends* `string` \| `symbol` |
+
+### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `target` | `This` |
+| `propertyKey` | `Key` |
+
+### Returns
+
+`void`
+
+## Call Signature
+
+```ts
+ColumnDecorator<This>(value: undefined, context: ClassFieldDecoratorContext<This, Value>): void;
+```
+
+Defined in: [decorators.ts:363](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L363)
+
+TC39 standard class-field decorator.
+
+### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `This` |
+
+### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `value` | `undefined` |
+| `context` | `ClassFieldDecoratorContext`\<`This`, `Value`\> |
+
+### Returns
+
+`void`

package/docs/api/interfaces/ColumnOptions.md

@@ -1,4 +1,4 @@
-[**litedbmodel v2.2.6**](../README.md)
+[**litedbmodel v2.2.8**](../README.md)
 
 ***
 
@@ -6,18 +6,14 @@
 
 # Interface: ColumnOptions
 
-Defined in: [decorators.ts:348](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L348)
+Defined in: [decorators.ts:327](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L327)
 
-Options that can be passed to
-
-## Column
-
-decorator
+Options that can be passed to any `@column.*` decorator
 
 ## Properties
 
 | Property | Type | Description | Defined in |
 | ------ | ------ | ------ | ------ |
-| <a id="columnname"></a> `columnName?` | `string` | Custom column name (defaults to property name) | [decorators.ts:350](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L350) |
-| <a id="primarykey"></a> `primaryKey?` | `boolean` | Mark this column as part of the primary key | [decorators.ts:352](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L352) |
-| <a id="autoincrement"></a> `autoIncrement?` | `boolean` | The SERVER assigns this column's value (`AUTO_INCREMENT` / `SERIAL` / `IDENTITY`) — a write does not supply it. Declare it on an auto-increment primary key so a `RETURNING` write can recover the rows it wrote on a dialect that has no native `RETURNING`. See ColumnMeta.autoIncrement. | [decorators.ts:358](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L358) |
+| <a id="columnname"></a> `columnName?` | `string` | Custom column name (defaults to property name) | [decorators.ts:329](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L329) |
+| <a id="primarykey"></a> `primaryKey?` | `boolean` | Mark this column as part of the primary key | [decorators.ts:331](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L331) |
+| <a id="autoincrement"></a> `autoIncrement?` | `boolean` | The SERVER assigns this column's value (`AUTO_INCREMENT` / `SERIAL` / `IDENTITY`) — a write does not supply it. Declare it on an auto-increment primary key so a `RETURNING` write can recover the rows it wrote on a dialect that has no native `RETURNING`. See ColumnMeta.autoIncrement. | [decorators.ts:337](https://github.com/foo-ogawa/litedbmodel/blob/main/src/decorators.ts#L337) |