uql-orm 0.109.2 → 0.110.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.
@@ -24,7 +24,6 @@ export declare class ColumnOptionsBuilder {
24
24
  columnType(columnType: QuerySql): ColumnOptionsBuilder;
25
25
  references(references: () => Type<object>): ColumnOptionsBuilder;
26
26
  onDelete(onDelete: ForeignKeyAction): ColumnOptionsBuilder;
27
- narrow(): ColumnOptionsBuilder;
28
27
  as(computed: QuerySql): ColumnOptionsBuilder;
29
28
  stored(events?: readonly StampEvent[]): ColumnOptionsBuilder;
30
29
  precision(precision: number): ColumnOptionsBuilder;
@@ -56,9 +56,6 @@ export class ColumnOptionsBuilder {
56
56
  onDelete(onDelete) {
57
57
  return this.with({ onDelete });
58
58
  }
59
- narrow() {
60
- return this;
61
- }
62
59
  as(computed) {
63
60
  return this.with({ computed });
64
61
  }
@@ -1,4 +1,4 @@
1
- import { type Column, type ComputedRefs, type EntityGetter, type FilledOptions, type filledKey, type HookContext, type IsEqual, type Json, type JsonBrand, type NamedIdKey, type NullOf, type QuerySql, RelationAggregate, type RelationManyToManyOptions, type RelationManyToOneOptions, type RelationOneToManyOptions, type RelationOneToOneOptions, type VersionKey } from '../../type/index.js';
1
+ import { type Column, type ComputedRefs, type EntityGetter, type FilledOptions, type filledKey, type HookContext, type HoldsKind, type IsEqual, type Json, type JsonBrand, type NamedIdKey, type NullOf, type QuerySql, type ReferencedKey, RelationAggregate, type RelationManyToManyOptions, type RelationManyToOneOptions, type RelationOneToManyOptions, type RelationOneToOneOptions, type VersionKey } from '../../type/index.js';
2
2
  /** A member decorator that also constrains the property it may be applied to, on a class `O`. */
3
3
  type MemberDecorator<V, O = unknown> = (value: undefined, context: ClassFieldDecoratorContext<O, V>) => void;
4
4
  /**
@@ -10,23 +10,40 @@ type MemberDecorator<V, O = unknown> = (value: undefined, context: ClassFieldDec
10
10
  * family - `jsonb`, whose document the property shapes, or `numeric`, either number kind - is meant to
11
11
  * be narrowed. A column insists on its `null`; an aggregate, whose value is exact, insists on all of it.
12
12
  */
13
- type AdmittingDecorator<V, M, O, Filled = true, Key = false, Lock = false> = <P extends V | undefined, N extends PropertyKey>(value: undefined, context: ClassFieldDecoratorContext<O, P> & {
13
+ type AdmittingDecorator<V, M, O> = <P extends V | undefined, N extends PropertyKey>(value: undefined, context: MemberContext<O, P, N, M, true, false, false>) => void;
14
+ /** What {@link AdmittingDecorator} asks of a property, a column's own value aside. */
15
+ type MemberContext<O, P, N, M, Filled, Key, Lock> = ClassFieldDecoratorContext<O, P> & {
14
16
  readonly name: N;
15
- } & ([M] extends [P] ? unknown : {
17
+ } & ([
18
+ M
19
+ ] extends [P] ? unknown : {
16
20
  readonly __propertyMustAdmit: M;
17
- }) & FilledIfBranded<O, N, Filled> & ([Key] extends [true] ? KeyIsNamed<O> : unknown) & ([Lock] extends [true] ? VersionIsBranded<O> : unknown)) => void;
21
+ }) & FilledIfBranded<O, N, Filled> & ([Key] extends [true] ? KeyIsNamed<O> : unknown) & ([Lock] extends [true] ? VersionIsBranded<O> : unknown);
22
+ /** An {@link AdmittingDecorator} for a column: its class is the decorator's own, and `K` is the key it references, `never` if none. */
23
+ type ColumnDecorator<V, M, Filled, Key, Lock, K = never> = <This, P extends V | undefined, N extends PropertyKey>(value: undefined, context: MemberContext<This, P, N, M, Filled, Key, Lock> & PropertyHoldsKey<P, K>) => void;
24
+ /** Refuses a property that does not hold the key a column references: a builder cannot say, a property brands what it does not. */
25
+ type PropertyHoldsKey<P, K> = [K] extends [never] ? unknown : HoldsKind<P, K> extends true ? unknown : {
26
+ readonly __propertyMustHoldReferencedKey: K;
27
+ };
28
+ /** The key a typed column references, `never` otherwise: `f.references` has no type of its own, its value being the key. */
29
+ type ReferencedKeyOf<O> = O extends {
30
+ readonly type: unknown;
31
+ readonly references: () => infer C;
32
+ } ? NonNullable<ReferencedKey<C>> : never;
18
33
  /** A field the `filledKey` brand lets an insert leave out, which only a default can then fill. */
19
34
  type FilledIfBranded<O, N, Filled> = [Filled] extends [true] ? unknown : typeof filledKey extends keyof O ? N extends O[typeof filledKey] ? {
20
35
  readonly __filledKeyNeedsADefault: true;
21
36
  } : unknown : unknown;
37
+ /** What `Field` answers: a column's own checks, and that a property holds the key its column references. */
38
+ type FieldDecorator<O, V> = ColumnDecorator<Narrowable<V> | NullOf<O>, NullOf<O>, O extends FilledOptions ? true : false, IsKey<O>, O extends {
39
+ readonly version: true;
40
+ } ? true : false, ReferencedKeyOf<O>>;
22
41
  /**
23
42
  * Declares a persisted field, the property checked against the column: `@Field(f.string()) name!: string;`, and
24
43
  * `@Field(f.string().nullable()) bio?: string | null;` for a column holding `null`. A key is `f.number().id()`.
25
44
  * @example `@Field(f.references(() => User).nullable()) userId?: number | null;`
26
45
  */
27
- export declare function Field<This, O, V>(column: Column<O, V>): AdmittingDecorator<Narrowable<V> | NullOf<O>, NullOf<O>, This, O extends FilledOptions ? true : false, IsKey<O>, O extends {
28
- readonly version: true;
29
- } ? true : false>;
46
+ export declare function Field<O, V>(column: Column<O, V>): FieldDecorator<O, V>;
30
47
  /**
31
48
  * Declares a field the database computes, read off the entity's refs: SQL as a column,
32
49
  * `@Computed((user) => f.string().as(sql`upper(${user.name})`)) readonly shout?: string;`, or a relation
@@ -3,11 +3,6 @@ import { aggregateField } from '../../util/field.util.js';
3
3
  import { memberRefs } from '../../util/sql.js';
4
4
  import { relationRegistration } from '../metadata/definition.js';
5
5
  import { memberRegistrations } from './bag.js';
6
- /**
7
- * Declares a persisted field, the property checked against the column: `@Field(f.string()) name!: string;`, and
8
- * `@Field(f.string().nullable()) bio?: string | null;` for a column holding `null`. A key is `f.number().id()`.
9
- * @example `@Field(f.references(() => User).nullable()) userId?: number | null;`
10
- */
11
6
  export function Field(column) {
12
7
  return (_value, context) => {
13
8
  memberRegistrations(context.metadata).fields[String(context.name)] = column[COLUMN_OPTIONS];
@@ -723,7 +723,7 @@ export function generatesKey(meta) {
723
723
  const sole = soleId(meta);
724
724
  return !!sole && isAutoIncrement(sole.field, ownsSoleKey(meta, sole.key));
725
725
  }
726
- /** The kinds a column of `type` holds as a join compares them, as `JoinKind` does: a bigint is a number, which BIGINT widens. */
726
+ /** The kinds a column of `type` holds as a join compares them, as `HoldsKind` does: a bigint is a number, which BIGINT widens. */
727
727
  function joinedKinds(type) {
728
728
  const types = valueTypesOf(type);
729
729
  return types && [...new Set(types.map((kind) => (kind === 'bigint' ? 'number' : kind)))];
@@ -1,10 +1,9 @@
1
1
  import type { ForeignKeyAction } from '../schema/types.js';
2
2
  import type { TYPE_BOUNDS, VALUE_DECIDERS } from '../util/fieldOption.util.js';
3
- import type { ReferencedKey } from './definedEntity.js';
4
- import type { BlobColumnType, BooleanColumnType, ColumnType, DateColumnType, DdlDefault, JsonColumnType, NumericColumnType, StringColumnType, VectorColumnType, FieldOptions, HasCompositeKey, IdValue, JoinKind, OnFieldCallback, StampEvent } from './entity.js';
3
+ import type { ColumnType, DdlDefault, FamilyOf, FieldOptions, HasCompositeKey, IdValue, JsonColumnType, OnFieldCallback, StampEvent, TsTypeOf } from './entity.js';
5
4
  import type { QuerySql } from './querySql.js';
6
5
  import type { StandardSchemaV1 } from './standardSchema.js';
7
- import type { Type, Json, AbstractType } from './utility.js';
6
+ import type { Type, Json, JsonDocument, JsonScalar, AbstractType } from './utility.js';
8
7
  import type { VectorDistance } from './vector.js';
9
8
  /** Where a column builder holds its options, so every string key of a builder is a method. */
10
9
  export declare const COLUMN_OPTIONS: unique symbol;
@@ -123,8 +122,8 @@ export interface ColumnBuilder<in out O, in out V, F extends Family> extends Col
123
122
  columnType(this: Lacking<TypeBound>, type: QuerySql): With<O, V, {
124
123
  readonly columnType: QuerySql;
125
124
  }, F>;
126
- /** A foreign key to `entity`'s key, which the column has to hold the kind of: `f.number().references(() => User)`. */
127
- references<C extends Type<object>>(entity: () => C & HoldsKey<C, V>): With<O, V, {
125
+ /** A foreign key to `entity`'s key, which `@Field` holds its property to: `f.number().references(() => User)`. */
126
+ references<C extends Type<object>>(entity: () => C): With<O, V, {
128
127
  readonly references: () => C;
129
128
  }, F>;
130
129
  /** The foreign key's delete action. */
@@ -133,8 +132,6 @@ export interface ColumnBuilder<in out O, in out V, F extends Family> extends Col
133
132
  }>, action: ForeignKeyAction): With<O, V, {
134
133
  readonly onDelete: ForeignKeyAction;
135
134
  }, F>;
136
- /** Narrows the value a row holds, a branded id or a literal union: `f.uuid().narrow<UserId>()`. */
137
- narrow<T extends V>(): Builders<O, T>[F];
138
135
  /**
139
136
  * A column the database computes from `expression`, read in each query naming it; `stored()` keeps it. A relation
140
137
  * aggregate is no column's SQL: it is read on each query, so `@Computed` or `aggregates` declares one.
@@ -200,24 +197,18 @@ export interface VersionColumn<in out O, in out V> extends Column<O, V> {
200
197
  readonly comment: string;
201
198
  }, V>;
202
199
  }
203
- /** Refuses a target whose key is another kind of value than the column holds, which no join matches. */
204
- type HoldsKey<C, V> = [JoinKind<NonNullable<ReferencedKey<C>>>] extends [JoinKind<V>] ? unknown : {
205
- readonly __columnMustHoldReferencedKey: ReferencedKey<C>;
206
- };
207
- /** The column types holding an exact decimal, read as its text: a JS number would round it. */
208
- type DecimalType = 'decimal' | 'numeric';
209
200
  /** A JSON column of `T`, typed by the payload its schema validates to, or any document with none. */
210
201
  type JsonColumn<T extends 'json' | 'jsonb'> = {
211
- (): ColumnBuilder<{
202
+ <P extends JsonScalar | object = JsonDocument>(): ColumnBuilder<{
212
203
  readonly type: T;
213
- }, Json, 'json'>;
204
+ }, Json<P>, 'json'>;
214
205
  <S extends StandardSchemaV1>(schema: S): ColumnBuilder<{
215
206
  readonly type: T;
216
207
  readonly schema: S;
217
208
  }, JsonOutput<PayloadOf<S['~standard']['types']>>, 'json'>;
218
209
  };
219
210
  /** A schema's output as a JSON column holds it: a document, or the primitive a payload may be. */
220
- type JsonOutput<O> = O extends object | string | number | boolean | null ? Json<O> : Json;
211
+ type JsonOutput<O> = O extends JsonScalar | object | null ? Json<O> : Json;
221
212
  /** The output a schema's `types` states, `unknown` where it states none: `never` would type the column as nothing. */
222
213
  type PayloadOf<T> = NonNullable<T> extends infer N ? [N] extends [never] ? unknown : N extends {
223
214
  readonly output: infer O;
@@ -226,42 +217,51 @@ type PayloadOf<T> = NonNullable<T> extends infer N ? [N] extends [never] ? unkno
226
217
  type ReferenceValue<C> = C extends AbstractType<infer E> ? HasCompositeKey<E> extends true ? {
227
218
  readonly __compositeKeyNeedsAColumnPerKey: true;
228
219
  } : NonNullable<IdValue<E>> : never;
229
- /** The builders, one per value a column holds; `column` takes any SQL type, its family deciding what it offers. */
220
+ /** The builder of a SQL type, its value what the type reads as: a family alone does not say, `time` and a decimal being text. */
221
+ type ColumnOf<T extends ColumnType> = [FamilyOf<T>] extends [never] ? ColumnBuilder<{
222
+ readonly type: ColumnType;
223
+ }, unknown, 'any'> : Builders<{
224
+ readonly type: T;
225
+ }, T extends JsonColumnType ? Json : TsTypeOf<T>>[FamilyOf<T>];
226
+ /**
227
+ * The builders, one per value a column holds; `column` takes any SQL type, its family deciding what it offers. A
228
+ * scalar's or a document's type argument narrows what a row holds, a brand or a payload: `f.uuid<UserId>()`.
229
+ */
230
230
  export type ColumnFactory = {
231
- string(): StringColumn<{
231
+ string<V extends string = string>(): StringColumn<{
232
232
  readonly type: StringConstructor;
233
- }, string>;
234
- text(): StringColumn<{
233
+ }, V>;
234
+ text<V extends string = string>(): StringColumn<{
235
235
  readonly type: 'text';
236
- }, string>;
237
- uuid(): StringColumn<{
236
+ }, V>;
237
+ uuid<V extends string = string>(): StringColumn<{
238
238
  readonly type: 'uuid';
239
- }, string>;
240
- number(): NumericColumn<{
239
+ }, V>;
240
+ number<V extends number = number>(): NumericColumn<{
241
241
  readonly type: NumberConstructor;
242
- }, number>;
243
- bigint(): NumericColumn<{
242
+ }, V>;
243
+ bigint<V extends bigint = bigint>(): NumericColumn<{
244
244
  readonly type: BigIntConstructor;
245
- }, bigint>;
245
+ }, V>;
246
246
  /** An exact decimal, read as its text: a JS number would round it. `f.number().precision()` opts in to that. */
247
- decimal(): NumericColumn<{
247
+ decimal<V extends string = string>(): NumericColumn<{
248
248
  readonly type: 'decimal';
249
- }, string>;
250
- decimal(precision: number): NumericColumn<{
249
+ }, V>;
250
+ decimal<V extends string = string>(precision: number): NumericColumn<{
251
251
  readonly type: 'decimal';
252
252
  readonly precision: number;
253
- }, string>;
254
- decimal(precision: number, scale: number): NumericColumn<{
253
+ }, V>;
254
+ decimal<V extends string = string>(precision: number, scale: number): NumericColumn<{
255
255
  readonly type: 'decimal';
256
256
  readonly precision: number;
257
257
  readonly scale: number;
258
- }, string>;
258
+ }, V>;
259
259
  boolean(): ColumnBuilder<{
260
260
  readonly type: BooleanConstructor;
261
261
  }, boolean, 'boolean'>;
262
- date(): DateColumn<{
262
+ date<V extends Date = Date>(): DateColumn<{
263
263
  readonly type: DateConstructor;
264
- }, Date>;
264
+ }, V>;
265
265
  json: JsonColumn<'json'>;
266
266
  jsonb: JsonColumn<'jsonb'>;
267
267
  vector(dimensions: number): VectorColumn<{
@@ -289,38 +289,8 @@ export type ColumnFactory = {
289
289
  readonly type: BigIntConstructor;
290
290
  readonly version: true;
291
291
  }, bigint>;
292
- /** A column of SQL type `type`, offering what its family takes. */
293
- column(type: DecimalType): NumericColumn<{
294
- readonly type: DecimalType;
295
- }, string>;
296
- column(type: Exclude<NumericColumnType, DecimalType>): NumericColumn<{
297
- readonly type: NumericColumnType;
298
- }, number | bigint>;
299
- column(type: StringColumnType): StringColumn<{
300
- readonly type: StringColumnType;
301
- }, string>;
302
- column(type: 'time'): DateColumn<{
303
- readonly type: 'time';
304
- }, string>;
305
- column(type: Exclude<DateColumnType, 'time'>): DateColumn<{
306
- readonly type: DateColumnType;
307
- }, Date>;
308
- column(type: VectorColumnType): VectorColumn<{
309
- readonly type: VectorColumnType;
310
- }, readonly number[]>;
311
- column(type: BooleanColumnType): ColumnBuilder<{
312
- readonly type: BooleanColumnType;
313
- }, boolean, 'boolean'>;
314
- column(type: JsonColumnType): ColumnBuilder<{
315
- readonly type: JsonColumnType;
316
- }, Json, 'json'>;
317
- column(type: BlobColumnType): ColumnBuilder<{
318
- readonly type: BlobColumnType;
319
- }, Uint8Array, 'blob'>;
320
- /** A column whose type is data, as an entity defined at run time declares one. */
321
- column(type: ColumnType): ColumnBuilder<{
322
- readonly type: ColumnType;
323
- }, unknown, 'any'>;
292
+ /** A column of SQL type `type`, offering what its family takes, or what any does where its type is data. */
293
+ column<T extends ColumnType>(type: T): ColumnOf<T>;
324
294
  /** A foreign key to `entity`'s key, its column typed as that key is. */
325
295
  references<C extends Type<object>>(entity: () => C): ColumnBuilder<{
326
296
  readonly references: () => C;
@@ -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;
@@ -254,17 +254,21 @@ export type ColumnFamily = keyof typeof COLUMN_TYPES;
254
254
  type ColumnTypeOf<F extends ColumnFamily> = (typeof COLUMN_TYPES)[F][number];
255
255
  export type NumericColumnType = ColumnTypeOf<'numeric'>;
256
256
  export type StringColumnType = ColumnTypeOf<'string'>;
257
- export type DateColumnType = ColumnTypeOf<'date'>;
257
+ type DateColumnType = ColumnTypeOf<'date'>;
258
258
  /** A date column holding a time of day, which names no day: every driver reads it back as text, never a `Date`. */
259
259
  type TimeColumnType = 'time';
260
260
  /** A numeric column holding an exact decimal, read as its text: a JS number would round it. */
261
261
  type DecimalColumnType = 'decimal' | 'numeric';
262
262
  export type JsonColumnType = ColumnTypeOf<'json'>;
263
- export type BlobColumnType = ColumnTypeOf<'blob'>;
263
+ type BlobColumnType = ColumnTypeOf<'blob'>;
264
264
  export type BooleanColumnType = ColumnTypeOf<'boolean'>;
265
- export type VectorColumnType = ColumnTypeOf<'vector'>;
265
+ type VectorColumnType = ColumnTypeOf<'vector'>;
266
266
  /** SQL column types supported by uql migrations. */
267
267
  export type ColumnType = ColumnTypeOf<ColumnFamily>;
268
+ /** The family every type of `T` belongs to, `never` where they span several: then only the run time knows. */
269
+ export type FamilyOf<T extends ColumnType> = {
270
+ readonly [F in ColumnFamily]: [T] extends [ColumnTypeOf<F>] ? F : never;
271
+ }[ColumnFamily];
268
272
  /** What a field declares its `type` as: a constructor, or a column type. */
269
273
  export type FieldType = StringConstructor | NumberConstructor | BooleanConstructor | DateConstructor | BigIntConstructor | ColumnType;
270
274
  /** A field as the registry holds it: what was authored, plus what registration worked out, which no decorator can write. */
@@ -355,9 +359,9 @@ export type OnFieldCallback<V = unknown> = V | QuerySql | (() => V | QuerySql);
355
359
  * an untyped one, a string being a JSON string. The erased `FieldOptions` takes them all, so every field's
356
360
  * options stay assignable to it.
357
361
  */
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;
362
+ 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
363
  /** 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>>>[];
364
+ type StoredDocument<T> = IsJson<T> extends true ? UnwrapJson<T> : readonly UnwrapJson<NonNullable<Unpacked<T>>>[];
361
365
  /** What a JSON column, and the field-less `FieldOptions`, may default to: a document, a list or a scalar included. */
362
366
  type JsonDdlDefault = JsonScalar | Record<string, unknown> | readonly unknown[];
363
367
  /** The TypeScript type a declared `type` implies: a decorator checks the property against it, a defined entity derives it. */
@@ -413,11 +417,13 @@ export type RelationReference<O, E> = {
413
417
  export type FieldKeyOf<E, T> = {
414
418
  readonly [K in FieldKey<E>]-?: [NonNullable<E[K]>] extends [T] ? K : never;
415
419
  }[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;
420
+ /** A value's kind as a join compares it, a brand aside: a number and a bigint are one kind, which BIGINT widens. */
421
+ type JoinKind<T> = T extends number | bigint ? number : T extends string ? T extends object ? string : T : T extends Date ? Date : T;
422
+ /** 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. */
423
+ 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
424
  /** The fields of `O` that can hold a key of `V`'s kind, compared as a join compares it at run time. */
419
425
  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;
426
+ readonly [K in keyof O]-?: HoldsKind<O[K], NonNullable<V>> extends true ? K : never;
421
427
  }[FieldKey<O>];
422
428
  /** A relation once `getMeta` resolved it: `references` settled into pairs and `mappedBy` a name. */
423
429
  export type RelationMeta = Merge<RelationRegistration, {
@@ -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
  */
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.110.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
@@ -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.