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.
- package/dist/entity/columnOptionsBuilder.d.ts +0 -1
- package/dist/entity/columnOptionsBuilder.js +0 -3
- package/dist/entity/decorator/members.d.ts +24 -7
- package/dist/entity/decorator/members.js +0 -5
- package/dist/entity/metadata/definition.js +1 -1
- package/dist/type/column.d.ts +37 -67
- package/dist/type/entity.d.ts +15 -9
- package/dist/type/utility.d.ts +4 -2
- package/package.json +5 -5
- package/skills/uql-orm/SKILL.md +2 -2
|
@@ -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;
|
|
@@ -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
|
|
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
|
-
} & ([
|
|
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)
|
|
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<
|
|
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 `
|
|
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)))];
|
package/dist/type/column.d.ts
CHANGED
|
@@ -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 {
|
|
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
|
|
127
|
-
references<C extends Type<object>>(entity: () => C
|
|
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
|
|
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
|
|
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
|
|
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
|
-
},
|
|
234
|
-
text(): StringColumn<{
|
|
233
|
+
}, V>;
|
|
234
|
+
text<V extends string = string>(): StringColumn<{
|
|
235
235
|
readonly type: 'text';
|
|
236
|
-
},
|
|
237
|
-
uuid(): StringColumn<{
|
|
236
|
+
}, V>;
|
|
237
|
+
uuid<V extends string = string>(): StringColumn<{
|
|
238
238
|
readonly type: 'uuid';
|
|
239
|
-
},
|
|
240
|
-
number(): NumericColumn<{
|
|
239
|
+
}, V>;
|
|
240
|
+
number<V extends number = number>(): NumericColumn<{
|
|
241
241
|
readonly type: NumberConstructor;
|
|
242
|
-
},
|
|
243
|
-
bigint(): NumericColumn<{
|
|
242
|
+
}, V>;
|
|
243
|
+
bigint<V extends bigint = bigint>(): NumericColumn<{
|
|
244
244
|
readonly type: BigIntConstructor;
|
|
245
|
-
},
|
|
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
|
-
},
|
|
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
|
-
},
|
|
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
|
-
},
|
|
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
|
-
},
|
|
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:
|
|
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;
|
package/dist/type/entity.d.ts
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
263
|
+
type BlobColumnType = ColumnTypeOf<'blob'>;
|
|
264
264
|
export type BooleanColumnType = ColumnTypeOf<'boolean'>;
|
|
265
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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]-?: [
|
|
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, {
|
package/dist/type/utility.d.ts
CHANGED
|
@@ -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
|
|
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
|
-
|
|
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.
|
|
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.
|
|
127
|
-
"@electric-sql/pglite-pgvector": "0.0.
|
|
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.
|
|
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.
|
|
150
|
+
"ws": "^8.22.1"
|
|
151
151
|
},
|
|
152
152
|
"author": "Roger Padilla",
|
|
153
153
|
"repository": {
|
package/skills/uql-orm/SKILL.md
CHANGED
|
@@ -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.
|
|
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
|
|
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.
|