uql-orm 0.109.2 → 0.111.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/README.md +3 -3
  2. package/dist/bunSql/bunSqlQuerier.d.ts +2 -5
  3. package/dist/d1/d1Querier.d.ts +1 -2
  4. package/dist/d1/d1Querier.js +0 -2
  5. package/dist/dialect/abstractSqlDialect.js +2 -2
  6. package/dist/dialect/aliases.d.ts +2 -0
  7. package/dist/dialect/aliases.js +2 -0
  8. package/dist/entity/columnOptionsBuilder.d.ts +1 -2
  9. package/dist/entity/columnOptionsBuilder.js +2 -5
  10. package/dist/entity/decorator/members.d.ts +37 -11
  11. package/dist/entity/decorator/members.js +0 -5
  12. package/dist/entity/metadata/definedFixture/animal.d.ts +4 -0
  13. package/dist/entity/metadata/definedFixture/animal.js +1 -1
  14. package/dist/entity/metadata/definedFixture/author.d.ts +4 -0
  15. package/dist/entity/metadata/definedFixture/author.js +1 -1
  16. package/dist/entity/metadata/definedFixture/book.d.ts +5 -0
  17. package/dist/entity/metadata/definedFixture/book.js +1 -1
  18. package/dist/entity/metadata/definition.d.ts +0 -2
  19. package/dist/entity/metadata/definition.js +4 -9
  20. package/dist/mariadb/mariadbQuerier.d.ts +2 -4
  21. package/dist/migrate/builder/columnBuilder.js +2 -2
  22. package/dist/migrate/codegen/entityCodeGenerator.js +1 -1
  23. package/dist/migrate/codegen/fieldOptionsSource.js +2 -13
  24. package/dist/migrate/schemaGenerator.d.ts +2 -2
  25. package/dist/migrate/schemaGenerator.js +9 -5
  26. package/dist/mongodb/mongodbQuerier.d.ts +1 -2
  27. package/dist/mongodb/mongodbQuerier.js +0 -2
  28. package/dist/mssql/mssqlQuerier.d.ts +2 -4
  29. package/dist/mysql/mysql2Querier.d.ts +2 -10
  30. package/dist/pglite/pgliteQuerier.d.ts +4 -7
  31. package/dist/pglite/pgliteQuerier.js +0 -2
  32. package/dist/postgres/pgQuerier.d.ts +2 -1
  33. package/dist/querier/abstractPoolQuerier.d.ts +1 -2
  34. package/dist/querier/abstractPoolQuerier.js +0 -2
  35. package/dist/querier/abstractSqlQuerier.d.ts +8 -2
  36. package/dist/querier/abstractSqlQuerier.js +29 -4
  37. package/dist/schema/canonicalType.d.ts +3 -3
  38. package/dist/schema/canonicalType.js +9 -4
  39. package/dist/schema/declaredColumn.d.ts +2 -4
  40. package/dist/schema/declaredColumn.js +4 -5
  41. package/dist/schema/schemaASTBuilder.js +1 -2
  42. package/dist/sqlite/hranaQuerier.d.ts +1 -2
  43. package/dist/sqlite/hranaQuerier.js +0 -2
  44. package/dist/sqlite/sqliteQuerier.d.ts +3 -9
  45. package/dist/sqlite/sqliteQuerier.js +0 -2
  46. package/dist/turso/tursoSessionQuerier.d.ts +1 -2
  47. package/dist/turso/tursoSessionQuerier.js +0 -2
  48. package/dist/type/column.d.ts +41 -73
  49. package/dist/type/definedEntity.d.ts +1 -1
  50. package/dist/type/entity.d.ts +19 -14
  51. package/dist/type/querierPool.d.ts +1 -1
  52. package/dist/type/utility.d.ts +4 -2
  53. package/dist/util/field.util.d.ts +1 -7
  54. package/dist/util/field.util.js +2 -12
  55. package/package.json +5 -5
  56. package/skills/uql-orm/SKILL.md +7 -7
@@ -5,7 +5,7 @@ import type { FilterOptions, RelationQuery } from './query.js';
5
5
  import type { ColumnRef, JsonPathRef, QuerySql, SqlFor, RelationAggregate } from './querySql.js';
6
6
  import type { QueryWhere } from './queryWhere.js';
7
7
  import type { StandardSchemaV1 } from './standardSchema.js';
8
- import type { AtLeastOne, ExactlyOne, IsEqual, Merge, IsJson, JsonBrand, IsMany, Json, JsonScalar, Scalar, Type, AbstractType, Unpacked, Writable } from './utility.js';
8
+ import type { AtLeastOne, ExactlyOne, IsBranded, IsEqual, Merge, IsJson, JsonBrand, IsMany, Json, JsonScalar, Scalar, Type, AbstractType, Unpacked, Writable } from './utility.js';
9
9
  import type { VectorDistance, VectorIndexOptions, VectorIndexType } from './vector.js';
10
10
  /** Brands the property an entity is identified by, where it is not `id`, `_id` or `uuid`. */
11
11
  export declare const idKey: unique symbol;
@@ -49,11 +49,10 @@ export type WritableKey<E> = {
49
49
  readonly [K in FieldKey<E>]-?: IsEqual<Pick<E, K>, Writable<Pick<E, K>>> extends true ? K : never;
50
50
  }[FieldKey<E>];
51
51
  /**
52
- * What an insert may leave out however the entity declares it: a single-column key, which something
53
- * usually generates, the version, which uql starts at 0, and what {@link filledKey} lists. A composite
54
- * key is the references a row is made of, so an insert names it.
52
+ * What an insert may leave out, the class saying so: `_id`, which MongoDB fills, the version, which uql starts at 0,
53
+ * and what {@link filledKey} lists. A `?` property a write keeps as it is.
55
54
  */
56
- type FilledKey<E> = SoleIdKey<E> | VersionKey<E> | (BrandNames<E, typeof filledKey> & FieldKey<E>);
55
+ type FilledKey<E> = VersionKey<E> | (('_id' | BrandNames<E, typeof filledKey>) & FieldKey<E>);
57
56
  /**
58
57
  * A whole-record write as a caller supplies one: {@link EntityData} without the fields it cannot write,
59
58
  * a {@link FilledKey} optional. That part is a conditional, which TypeScript leaves shut while it types a
@@ -254,17 +253,21 @@ export type ColumnFamily = keyof typeof COLUMN_TYPES;
254
253
  type ColumnTypeOf<F extends ColumnFamily> = (typeof COLUMN_TYPES)[F][number];
255
254
  export type NumericColumnType = ColumnTypeOf<'numeric'>;
256
255
  export type StringColumnType = ColumnTypeOf<'string'>;
257
- export type DateColumnType = ColumnTypeOf<'date'>;
256
+ type DateColumnType = ColumnTypeOf<'date'>;
258
257
  /** A date column holding a time of day, which names no day: every driver reads it back as text, never a `Date`. */
259
258
  type TimeColumnType = 'time';
260
259
  /** A numeric column holding an exact decimal, read as its text: a JS number would round it. */
261
260
  type DecimalColumnType = 'decimal' | 'numeric';
262
261
  export type JsonColumnType = ColumnTypeOf<'json'>;
263
- export type BlobColumnType = ColumnTypeOf<'blob'>;
262
+ type BlobColumnType = ColumnTypeOf<'blob'>;
264
263
  export type BooleanColumnType = ColumnTypeOf<'boolean'>;
265
- export type VectorColumnType = ColumnTypeOf<'vector'>;
264
+ type VectorColumnType = ColumnTypeOf<'vector'>;
266
265
  /** SQL column types supported by uql migrations. */
267
266
  export type ColumnType = ColumnTypeOf<ColumnFamily>;
267
+ /** The family every type of `T` belongs to, `never` where they span several: then only the run time knows. */
268
+ export type FamilyOf<T extends ColumnType> = {
269
+ readonly [F in ColumnFamily]: [T] extends [ColumnTypeOf<F>] ? F : never;
270
+ }[ColumnFamily];
268
271
  /** What a field declares its `type` as: a constructor, or a column type. */
269
272
  export type FieldType = StringConstructor | NumberConstructor | BooleanConstructor | DateConstructor | BigIntConstructor | ColumnType;
270
273
  /** A field as the registry holds it: what was authored, plus what registration worked out, which no decorator can write. */
@@ -339,7 +342,7 @@ export type FieldOptions<V = unknown> = {
339
342
  readonly unique?: boolean;
340
343
  /** The column's DDL default: a literal, or SQL the database evaluates per inserted row (`currentTimestamp`, `sql`). */
341
344
  readonly defaultValue?: DdlDefault<V> | QuerySql;
342
- /** Whether the database generates the value; a numeric sole key does unless something else fills it. */
345
+ /** Whether the database generates the value. */
343
346
  readonly autoIncrement?: boolean;
344
347
  /**
345
348
  * `true` for an index over the column, a string to name it. A foreign key column is indexed unless
@@ -355,9 +358,9 @@ export type OnFieldCallback<V = unknown> = V | QuerySql | (() => V | QuerySql);
355
358
  * an untyped one, a string being a JSON string. The erased `FieldOptions` takes them all, so every field's
356
359
  * options stay assignable to it.
357
360
  */
358
- export type DdlDefault<V, T = NonNullable<V>> = IsJsonColumn<T> extends true ? unknown extends JsonDocument<T> ? JsonDdlDefault : NonNullable<JsonDocument<T>> : [TsTypeOf<FieldType>] extends [T] ? JsonDdlDefault | T : T;
361
+ export type DdlDefault<V, T = NonNullable<V>> = IsJsonColumn<T> extends true ? unknown extends StoredDocument<T> ? JsonDdlDefault : NonNullable<StoredDocument<T>> : [TsTypeOf<FieldType>] extends [T] ? JsonDdlDefault | T : T;
359
362
  /** The document a JSON column declared as `T` stores: its payload, or a list of them for `Json<P>[]`. */
360
- type JsonDocument<T> = IsJson<T> extends true ? UnwrapJson<T> : readonly UnwrapJson<NonNullable<Unpacked<T>>>[];
363
+ type StoredDocument<T> = IsJson<T> extends true ? UnwrapJson<T> : readonly UnwrapJson<NonNullable<Unpacked<T>>>[];
361
364
  /** What a JSON column, and the field-less `FieldOptions`, may default to: a document, a list or a scalar included. */
362
365
  type JsonDdlDefault = JsonScalar | Record<string, unknown> | readonly unknown[];
363
366
  /** The TypeScript type a declared `type` implies: a decorator checks the property against it, a defined entity derives it. */
@@ -413,11 +416,13 @@ export type RelationReference<O, E> = {
413
416
  export type FieldKeyOf<E, T> = {
414
417
  readonly [K in FieldKey<E>]-?: [NonNullable<E[K]>] extends [T] ? K : never;
415
418
  }[FieldKey<E>];
416
- /** A value's kind as a join compares it: a number and a bigint are one kind, which BIGINT widens. */
417
- export type JoinKind<T> = T extends number | bigint ? number : T;
419
+ /** A value's kind as a join compares it, a brand aside: a number and a bigint are one kind, which BIGINT widens. */
420
+ type JoinKind<T> = T extends number | bigint ? number : T extends string ? T extends object ? string : T : T extends Date ? Date : T;
421
+ /** Whether a field of `V` holds a key of `K`: the same kind, and its brand where it has one, unless `V` is data's. */
422
+ export type HoldsKind<V, K> = true extends IsBranded<K> ? [unknown extends V ? K : NonNullable<V>] extends [K] ? true : false : [JoinKind<K>] extends [JoinKind<V>] ? true : false;
418
423
  /** The fields of `O` that can hold a key of `V`'s kind, compared as a join compares it at run time. */
419
424
  export type KeyHolding<O, V> = [V] extends [never] ? never : {
420
- readonly [K in keyof O]-?: [JoinKind<NonNullable<V>>] extends [JoinKind<NonNullable<O[K]>>] ? K : never;
425
+ readonly [K in keyof O]-?: HoldsKind<O[K], NonNullable<V>> extends true ? K : never;
421
426
  }[FieldKey<O>];
422
427
  /** A relation once `getMeta` resolved it: `references` settled into pairs and `mappedBy` a name. */
423
428
  export type RelationMeta = Merge<RelationRegistration, {
@@ -25,7 +25,7 @@ export interface QuerierPool<Q extends Querier = Querier, D extends AbstractDial
25
25
  /**
26
26
  * extra options
27
27
  */
28
- readonly extra?: ExtraOptions;
28
+ readonly extra?: ExtraOptions | undefined;
29
29
  /**
30
30
  * Default connection for application queries, transactions, and anything that should use the pool's primary URL.
31
31
  */
@@ -25,7 +25,7 @@ export type PrimaryKey = string | number | bigint;
25
25
  * Brands a JSON field so it reads as a field rather than a relation: `settings?: Json<{ isArchived?: boolean }>`.
26
26
  * A bare `Json` holds any JSON value. A `null` in `T` stays `null`, so `Json<X | null>` may be `null`.
27
27
  */
28
- export type Json<T extends object | string | number | boolean | null = JsonDocument> = T extends null ? null : T & JsonBrand;
28
+ export type Json<T extends JsonScalar | object | null = JsonDocument> = T extends null ? null : T & JsonBrand;
29
29
  /** Any value a JSON column holds, which a bare {@link Json} stands for. */
30
30
  export type JsonDocument = string | number | boolean | readonly unknown[] | {
31
31
  readonly [key: string]: unknown;
@@ -39,7 +39,9 @@ export interface JsonBrand {
39
39
  * Whether `T` carries the {@link Json} brand. A primitive matches `Json<infer P>` too, so the key tells.
40
40
  */
41
41
  export type IsJson<T> = typeof json extends keyof T ? true : false;
42
- export type ExpandScalar<T> = T extends Date ? Date | string : T;
42
+ /** Whether `T` carries a brand: a primitive with a tag, or a `Date` narrower than `Date`. */
43
+ export type IsBranded<T> = T extends Date ? Date extends T ? false : true : T extends string | number | bigint ? T extends object ? true : false : false;
44
+ export type ExpandScalar<T> = T extends Date ? (IsBranded<T> extends true ? T : Date | string) : T;
43
45
  /**
44
46
  * A raw database result row before entity mapping.
45
47
  */
@@ -38,12 +38,6 @@ export declare function aggregateField(aggregate: RelationAggregate): FieldOptio
38
38
  * computed column *is* a real column, read like one, but writing to it is an error on every engine.
39
39
  */
40
40
  export declare function isDatabaseWritten(field: FieldOptions): boolean;
41
- /**
42
- * Whether the database generates this column's value: its table's whole and own key (see `ownsSoleKey`), numeric,
43
- * that the application does not fill `onInsert`; a `columnType` only states its width. The one answer the create
44
- * statement and the diff both read.
45
- */
46
- export declare function isAutoIncrement(field: FieldOptions, soleKey: boolean): boolean;
47
41
  /** The column family of a field, from its `columnType` if set, else from its `type`. */
48
42
  export declare function fieldFamily(field: FieldOptions): ColumnFamily | undefined;
49
43
  /** Whether the column is NOT NULL: every column is, a key included, unless it declares `nullable()`. */
@@ -59,7 +53,7 @@ export declare function lacksValue(column: {
59
53
  * {@link lacksValue} for an insert leaving the field out, where a computed column, a stamp its trigger fills included,
60
54
  * holds a value too, unlike on the rows a migration finds.
61
55
  */
62
- export declare function lacksValueOnInsert(field: FieldOptions, soleKey: boolean): boolean;
56
+ export declare function lacksValueOnInsert(field: FieldOptions): boolean;
63
57
  /** Whether `key` is a field of `meta`, as opposed to a relation, a JSON path or an unknown key. */
64
58
  export declare function isFieldKey<E>(meta: EntityMeta<E>, key: string): key is FieldKey<E>;
65
59
  /** The fields `meta` declares whose options `pick` accepts, in declaration order, each as the entity's own key. */
@@ -83,16 +83,6 @@ export function aggregateField(aggregate) {
83
83
  export function isDatabaseWritten(field) {
84
84
  return field.computed !== undefined;
85
85
  }
86
- /**
87
- * Whether the database generates this column's value: its table's whole and own key (see `ownsSoleKey`), numeric,
88
- * that the application does not fill `onInsert`; a `columnType` only states its width. The one answer the create
89
- * statement and the diff both read.
90
- */
91
- export function isAutoIncrement(field, soleKey) {
92
- if (field.autoIncrement !== undefined)
93
- return field.autoIncrement;
94
- return soleKey && columnFamily(field.type) === 'numeric' && !field.onInsert;
95
- }
96
86
  /** The column family of a field, from its `columnType` if set, else from its `type`. */
97
87
  export function fieldFamily(field) {
98
88
  return columnFamily(field.columnType ?? field.type);
@@ -109,12 +99,12 @@ export function lacksValue(column) {
109
99
  * {@link lacksValue} for an insert leaving the field out, where a computed column, a stamp its trigger fills included,
110
100
  * holds a value too, unlike on the rows a migration finds.
111
101
  */
112
- export function lacksValueOnInsert(field, soleKey) {
102
+ export function lacksValueOnInsert(field) {
113
103
  return (!isDatabaseWritten(field) &&
114
104
  lacksValue({
115
105
  nullable: !declaresNotNull(field),
116
106
  defaultValue: field.defaultValue,
117
- isAutoIncrement: isAutoIncrement(field, soleKey),
107
+ isAutoIncrement: field.autoIncrement === true,
118
108
  }));
119
109
  }
120
110
  /** Whether `key` is a field of `meta`, as opposed to a relation, a JSON path or an unknown key. */
package/package.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "homepage": "https://uql-orm.dev",
4
4
  "description": "JSON-native TypeScript ORM for Bun, Browsers, Edge, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, SQL Server, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
5
5
  "license": "MIT",
6
- "version": "0.109.2",
6
+ "version": "0.111.0",
7
7
  "type": "module",
8
8
  "engines": {
9
9
  "node": ">=22.18"
@@ -123,8 +123,8 @@
123
123
  }
124
124
  },
125
125
  "devDependencies": {
126
- "@electric-sql/pglite": "0.5.13",
127
- "@electric-sql/pglite-pgvector": "0.0.14",
126
+ "@electric-sql/pglite": "0.5.14",
127
+ "@electric-sql/pglite-pgvector": "0.0.15",
128
128
  "@libsql/client": "^0.18.0",
129
129
  "@neondatabase/serverless": "^1.2.0",
130
130
  "@nestjs/common": "^12.3.2",
@@ -140,14 +140,14 @@
140
140
  "better-sqlite3": "^13.0.3",
141
141
  "express": "^5.3.0",
142
142
  "mariadb": "^3.5.4",
143
- "mongodb": "^7.7.0",
143
+ "mongodb": "^7.8.0",
144
144
  "mssql": "^12.7.13",
145
145
  "mysql2": "^3.24.6",
146
146
  "pg": "^8.23.1",
147
147
  "pg-query-stream": "^4.17.1",
148
148
  "rxjs": "^7.8.2",
149
149
  "sqlite-vec": "^0.1.9",
150
- "ws": "^8.22.0"
150
+ "ws": "^8.22.1"
151
151
  },
152
152
  "author": "Roger Padilla",
153
153
  "repository": {
@@ -44,7 +44,7 @@ The pool's first argument is the driver's own config; set an acquire timeout the
44
44
 
45
45
  Two forms, mixable per entity, producing the same queries and types:
46
46
 
47
- - **Decorators**: a named class type, and column-level foreign keys (`f.references`), so entities may reference each other in any order. Slightly stricter: a property may be typed narrower than its column (a branded id), and `mappedBy` must name a relation or foreign key at compile time. Each field is written twice (builder and property), and it needs the TC39 decorator transform.
47
+ - **Decorators**: a named class type, and column-level foreign keys (`f.references`), so entities may reference each other in any order. A property may be typed narrower than its column, a branded id, and `f.references(() => User)` takes the key's type. Slightly stricter: `mappedBy` must name a relation or foreign key at compile time. Each field is written twice (builder and property), and it needs the TC39 decorator transform.
48
48
  - **`defineEntity`**: the row type is derived, nothing written twice; no transform, so it fits projects on legacy decorators (NestJS, Angular), and it can be built at run time. Cheaper to type-check. A shared set of fields spreads into `fields`.
49
49
 
50
50
  `uql-codemod` cannot convert one form into the other. Details: https://uql-orm.dev/entities/define-entity.md
@@ -73,7 +73,7 @@ export class User {
73
73
 
74
74
  @Entity()
75
75
  export class Post {
76
- @Field(f.number().id())
76
+ @Field(f.number().autoIncrement())
77
77
  id?: number;
78
78
 
79
79
  @Field(f.string().nullable())
@@ -88,7 +88,7 @@ export class Post {
88
88
  ```
89
89
 
90
90
  - A column is a builder: `f.string()`, `f.text()`, `f.uuid()`, `f.number()`, `f.bigint()`, `f.decimal(precision?, scale?)`, `f.boolean()`, `f.date()`, `f.json(schema?)`, `f.jsonb(schema?)`, `f.vector(dimensions)`, `f.enum(values)`, `f.version()`, `f.column(type)` for any other SQL type uql names (`f.column('smallint')`, `f.column('date')` for a day with no time, `f.column('timestamptz')`), typed by its family, and `f.references(() => Target)` for a foreign key typed as the target's key. A type uql does not name is ``.columnType(sql`citext`)``. Only the methods a column's type takes exist: `.length()` is a string's, `.precision()` a number's or a date's. A builder is immutable, so `const money = f.decimal(12, 2)` is shared across fields, each chaining its own `.nullable()`.
91
- - A column is NOT NULL unless `.nullable()`. Declare a NOT NULL property `!` (`email!: string`), and `?` what an insert may omit: nullable columns (`title?: string | null`), `.eager(false)` and computed fields, relations, and the single-column key and version uql fills. A NOT NULL field a default fills (`.default()`, `.onInsert()`) stays `!` and is listed in the class's `[filledKey]?: 'stock' | 'createdAt'`: inserts may omit it, reads always have it.
91
+ - A column is NOT NULL unless `.nullable()`. Declare a NOT NULL property `!` (`email!: string`), and `?` what an insert may omit: nullable columns (`title?: string | null`), `.eager(false)` and computed fields, relations, and the version uql fills. A key the database generates is `@Field(f.number().autoIncrement()) id?: number` (`f.bigint().autoIncrement()` past 2^53); `.id()` alone generates nothing, so `f.number().id()` is a key the caller supplies and `@Field` refuses `?` on it, as on a `.references()` key. A NOT NULL field something fills (`.default()`, `.onInsert()`, a generated key) stays `!` when listed in the class's `[filledKey]?: 'id' | 'createdAt'`: inserts may omit it, reads always have it. MongoDB fills a text key declared `?` and `_id`. `defineEntity` works all of this out.
92
92
  - `.default()` takes a value of the field's type, or SQL the database evaluates per row: `currentTimestamp`, `currentDate`, `currentTime`, `uuid` (not SQLite), `uuidv7` (Postgres 18+, MariaDB 11.7+), or ``sql`...` ``. A plain string is always text, `'CURRENT_TIMESTAMP'` included. A JSON column defaults to a value, `.default({})` or `.default(0)`, never its JSON text (`'{}'`, `'0'` are refused); any other string there is a JSON string.
93
93
  - `Date` is an instant, stored in UTC to the millisecond. `f.decimal()` is exact text (`price?: string | null`); `f.number().precision(10).scale(2)` opts into a rounding JS number.
94
94
  - A JSON column's property is `Json<T>`: `settings?: Json<{ theme?: string }> | null`. A plain object type reads as a relation, which `$where`, `$sort` and the update operators refuse.
@@ -112,7 +112,7 @@ const Settings = z.object({ theme: z.string(), bio: z.string().optional() });
112
112
  export const Author = defineEntity({
113
113
  name: 'Author',
114
114
  fields: {
115
- id: f.number().id(),
115
+ id: f.number().autoIncrement(),
116
116
  name: f.string(),
117
117
  settings: f.json(Settings).nullable(),
118
118
  },
@@ -125,7 +125,7 @@ export type Author = InstanceType<typeof Author>;
125
125
  export const Book = defineEntity({
126
126
  name: 'Book',
127
127
  fields: {
128
- id: f.number().id(),
128
+ id: f.number().autoIncrement(),
129
129
  title: f.string(),
130
130
  stock: f.number().default(0),
131
131
  authorId: f.number(),
@@ -138,7 +138,7 @@ export const Book = defineEntity({
138
138
  }));
139
139
  ```
140
140
 
141
- - Columns are the same builders. No `!`, `?` or brands to write: a `.nullable()` column reads `| null`, a default makes it optional on insert, `f.enum()` gives the literal union.
141
+ - Columns are the same builders. No `!` or `?` to write: a `.nullable()` column reads `| null`, a default makes it optional on insert, `f.enum()` gives the literal union. A constructor's type argument narrows the column, a brand or a JSON payload with no runtime schema: `f.uuid<UserId>().id()`, `f.json<Settings>()`. It checks the type against the column and exists only in types; a default is written as that type. A filter then takes the branded type, and a foreign key to a branded key must carry the same brand, whether a relation or a decorated property declares it.
142
142
  - `defineEntity` takes `name` (the table derives from it), `table`, `schema`, `extends`, `abstract` and `fields`. Every other option is a section chained after it, each called at most once: `computed`, `indexes`, `checks`, `triggers`, `filters`, `hooks`, then `relations` last; only a `filters` reading through relations follows it.
143
143
  - A relation is a thunk, so entities pointing at each other can sit in any order and file. A foreign key is a plain field that a `manyToOne` names as `references`, checked against the target's key type. `relations`' second callback declares aggregate fields: aggregates over a to-many, or expressions mixing them with columns.
144
144
  - A JSON column's payload is any Standard Schema (Zod, Valibot, ArkType), typed by its output. uql never runs it, so a write is not validated.
@@ -164,7 +164,7 @@ declare module 'uql-orm' {
164
164
  },
165
165
  })
166
166
  export class Invoice {
167
- @Field(f.number().id()) id?: number;
167
+ @Field(f.number().autoIncrement()) id?: number;
168
168
  @Field(f.number()) companyId!: number;
169
169
  @Field(f.string().nullable()) status?: string | null;
170
170
  @Field(f.date().nullable().softDelete()) deletedAt?: Date | null;