uql-orm 0.106.1 → 0.107.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/README.md CHANGED
@@ -154,7 +154,7 @@ Follow the [Quick Start](https://uql-orm.dev/getting-started), or [switch from](
154
154
 
155
155
  Using a coding agent? The package ships a [skill](skills/uql-orm/SKILL.md) for it, and every docs page is Markdown: [set it up](https://uql-orm.dev/ai-agents).
156
156
 
157
- Release notes live in [CHANGELOG.md](https://github.com/rogerpadilla/uql/blob/main/CHANGELOG.md).
157
+ Release notes live in [CHANGELOG.md](https://github.com/rogerpadilla/uql/blob/main/CHANGELOG.md), and the build order for what comes next in [architecture/roadmap.md](architecture/roadmap.md).
158
158
 
159
159
  ---
160
160
 
@@ -1,9 +1,9 @@
1
1
  import { fieldOf, getMeta, relationOf } from '../entity/index.js';
2
- import { soleId, valueFieldOf } from '../entity/metadata/definition.js';
2
+ import { generatesKey, soleId, valueFieldOf } from '../entity/metadata/definition.js';
3
3
  import { COUNT_RESULT_KEY, parseQueryLock, QuerySql, renderSql, RAW_ALIAS, } from '../type/index.js';
4
4
  import { utcTimestamp } from '../util/date.js';
5
5
  import { ancestorPaths, isExactDecimal, isInlinedExpression, jsonPathKeys } from '../util/field.util.js';
6
- import { isAutoIncrement, RETURNED_ID, isSelectList, assertNonNegativeInteger, assertNoUndefined, assertWhere, definedEntries, escapeSqlId, fillOnFields, filterFieldKeys, getInsertFieldKeys, getKeys, getRelationRequestSummary, deletionOf, hasKeys, idOnlyQuery, keySet, whereAnd, columnFamily, fieldFamily, countedRelations, fieldUpdateOf, fulltextIndexOver, fulltextWeights, isFieldUpdateOp, isJsonObject, isJsonUpdateOp, foldJson, writesKeys, isOperatorMap, isOperatorKey, isVectorSearch, normalizeScalarFieldSelection, parentJoins, rankedTextSearch, targetJoins, textSearchFields, textSortOf, textWeightSteps, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortDirection, populatesRelations, aggregateOf, sql, refs, columnRef, throwUnknownAggregateColumn, upsertAssigned, } from '../util/index.js';
6
+ import { RETURNED_ID, isSelectList, assertNonNegativeInteger, assertNoUndefined, assertWhere, definedEntries, escapeSqlId, fillOnFields, filterFieldKeys, getInsertFieldKeys, getKeys, getRelationRequestSummary, deletionOf, hasKeys, idOnlyQuery, keySet, whereAnd, columnFamily, fieldFamily, countedRelations, fieldUpdateOf, fulltextIndexOver, fulltextWeights, isFieldUpdateOp, isJsonObject, isJsonUpdateOp, foldJson, writesKeys, isOperatorMap, isOperatorKey, isVectorSearch, normalizeScalarFieldSelection, parentJoins, rankedTextSearch, targetJoins, textSearchFields, textSortOf, textWeightSteps, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortDirection, populatesRelations, aggregateOf, sql, refs, columnRef, throwUnknownAggregateColumn, upsertAssigned, } from '../util/index.js';
7
7
  import { cachedIn, isJsonScalar } from '../util/object.util.js';
8
8
  import { escapeAnsiSqlLiteral } from '../util/sqlLiteral.js';
9
9
  import { kindOf, UqlUsageError } from '../util/uqlError.js';
@@ -1549,7 +1549,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
1549
1549
  }
1550
1550
  return this.insertIdSource === 'returning'
1551
1551
  ? rows === 1 || this.features.orderedUpsertReturning
1552
- : rows === 1 && isAutoIncrement(id.field, true);
1552
+ : rows === 1 && generatesKey(meta);
1553
1553
  }
1554
1554
  /** Whether the upsert's assignments bind straight into the statement, as numbered `$n` placeholders can. */
1555
1555
  upsertUpdateBindsInPlace = false;
@@ -72,4 +72,14 @@ export declare function getMeta<E>(entity: AbstractType<E>): EntityMeta<E>;
72
72
  * schema build constrains and a junction joins by, settling the relations holding them first.
73
73
  */
74
74
  export declare function foreignKeysOf<E>(meta: EntityMeta<E>): RelationMeta[];
75
+ /**
76
+ * The fields holding another entity's primary key: each column of a foreign key paired with a column of its
77
+ * target's key, whether `f.references()` or a relation declares it. Per entity, not per field: an entity
78
+ * extending another may join by other columns. Kept once resolved.
79
+ */
80
+ export declare function referenceKeys<E>(meta: EntityMeta<E>): ReadonlySet<string>;
81
+ /** Whether `key` is `meta`'s whole primary key and its own, not the key of the row it references. */
82
+ export declare function ownsSoleKey<E>(meta: EntityMeta<E>, key: string): boolean;
83
+ /** Whether the database generates `meta`'s key on insert: the one answer every insert path reads. */
84
+ export declare function generatesKey<E>(meta: EntityMeta<E>): boolean;
75
85
  export {};
@@ -1,5 +1,5 @@
1
1
  import { COLUMN_OPTIONS, REF_KEY, RelationAggregate, SECTION_ENTRY, SOFT_DELETE_FILTER, } from '../../type/index.js';
2
- import { aggregateField, defaultReadKeys, fieldKeys, isInlinedExpression } from '../../util/field.util.js';
2
+ import { aggregateField, defaultReadKeys, fieldKeys, isAutoIncrement, isInlinedExpression, } from '../../util/field.util.js';
3
3
  import { fieldOptionConflict, findVectorIndex, valueTypesOf, hasKeys, holdsForeignKey, isCascadable, isToManyRelation, indexRefs, memberRefs, fulltextWeights, normalizeIndexColumn, definedEntries, isRecord, whereWith, } from '../../util/index.js';
4
4
  import { UqlUsageError } from '../../util/uqlError.js';
5
5
  import { ownRegistrations } from '../decorator/bag.js';
@@ -488,6 +488,9 @@ export function getMeta(entity) {
488
488
  // reads other entities without resolving them, so no entity is ever read half resolved.
489
489
  fillRelations(meta);
490
490
  meta.readKeys = defaultReadKeys(meta);
491
+ // A column `references` names is a foreign key with or without a relation over it, and one cannot point
492
+ // at a composite key: refused on first read, as a relation that cannot join is, not at the schema build.
493
+ meta.referenceKeys = referenceKeys(meta);
491
494
  meta.stage = 'resolved';
492
495
  return meta;
493
496
  }
@@ -516,9 +519,6 @@ function fillRelations(meta) {
516
519
  "'persist' only: cascade a delete from the side that owns the rows.");
517
520
  }
518
521
  }
519
- // A column `references` names is a foreign key with or without a relation over it, and one cannot point
520
- // at a composite key: refused on first read, as a relation that cannot join is, not at the schema build.
521
- foreignKeysOf(meta);
522
522
  }
523
523
  /**
524
524
  * The pairs a relation joins on, settled on first read, whether its own entity is being resolved or another
@@ -694,6 +694,27 @@ export function foreignKeysOf(meta) {
694
694
  });
695
695
  return [...owning, ...columns];
696
696
  }
697
+ /**
698
+ * The fields holding another entity's primary key: each column of a foreign key paired with a column of its
699
+ * target's key, whether `f.references()` or a relation declares it. Per entity, not per field: an entity
700
+ * extending another may join by other columns. Kept once resolved.
701
+ */
702
+ export function referenceKeys(meta) {
703
+ return (meta.referenceKeys ??
704
+ new Set(foreignKeysOf(meta).flatMap(({ entity, references }) => {
705
+ const { ids } = knownMeta(entity());
706
+ return references.filter(({ foreign }) => ids.some((id) => id === foreign)).map(({ local }) => local);
707
+ })));
708
+ }
709
+ /** Whether `key` is `meta`'s whole primary key and its own, not the key of the row it references. */
710
+ export function ownsSoleKey(meta, key) {
711
+ return soleId(meta)?.key === key && !referenceKeys(meta).has(key);
712
+ }
713
+ /** Whether the database generates `meta`'s key on insert: the one answer every insert path reads. */
714
+ export function generatesKey(meta) {
715
+ const sole = soleId(meta);
716
+ return !!sole && isAutoIncrement(sole.field, ownsSoleKey(meta, sole.key));
717
+ }
697
718
  /** The kinds a column of `type` holds as a join compares them, as `JoinKind` does: a bigint is a number, which BIGINT widens. */
698
719
  function joinedKinds(type) {
699
720
  const types = valueTypesOf(type);
@@ -19,7 +19,7 @@ const METHOD_SOURCE = {
19
19
  nullable: (col) => (col.nullable && !col.isPrimaryKey ? ['.nullable()'] : []),
20
20
  isPrimaryKey: (col) => (col.isPrimaryKey ? ['.id()'] : []),
21
21
  // Generates where `isAutoIncrement` says, which only a column the database treats otherwise contradicts.
22
- isAutoIncrement: (col) => isAutoIncrement({ type: canonicalToColumnType(col.type) }, col.isPrimaryKey && col.table.primaryKey?.columns.length === 1) === col.isAutoIncrement
22
+ isAutoIncrement: (col) => isAutoIncrement({ type: canonicalToColumnType(col.type) }, ownsSoleKey(col)) === col.isAutoIncrement
23
23
  ? []
24
24
  : [col.isAutoIncrement ? '.autoIncrement()' : '.autoIncrement(false)'],
25
25
  isUnique: (col) => (col.isUnique ? ['.unique()'] : []),
@@ -33,6 +33,13 @@ const METHOD_SOURCE = {
33
33
  // The graph link: a foreign key becomes a relation decorator, emitted beside the field rather than in it.
34
34
  table: null,
35
35
  };
36
+ /** The AST's reading of the entity's `ownsSoleKey`: the table's whole key, and not the key of a row it references. */
37
+ function ownsSoleKey(col) {
38
+ const { primaryKey, outgoingRelations } = col.table;
39
+ return (col.isPrimaryKey &&
40
+ primaryKey?.columns.length === 1 &&
41
+ !outgoingRelations.some(({ from }) => from.columns.includes(col)));
42
+ }
36
43
  /** Whether to write `type`'s precision: not for a timestamp at a `Date`'s milliseconds, its default. */
37
44
  function writesPrecision(type) {
38
45
  return type.precision !== undefined && !(type.category === 'timestamp' && type.precision === DATE_PRECISION);
@@ -213,7 +213,6 @@ export declare class MongoDialect extends AbstractDialect {
213
213
  private renamedColumns;
214
214
  /** Each relation's key, the field its rows are read from, and its entity, memoized per entity for `normalizeId`. */
215
215
  private relationReads;
216
- private referenceKeys;
217
216
  normalizeIds<E extends Document>(meta: EntityMeta<E>, docs: Document[]): E[];
218
217
  /** `doc` is the wire shape - `_id`, stored names, `ObjectId`s - and what comes back is the code's. */
219
218
  normalizeId<E extends Document>(meta: EntityMeta<E>, doc: Document): E;
@@ -4,6 +4,7 @@ import { AGGREGATE_VALUE_ALIAS, REL_NESTED_KEY, REL_FIELD_PREFIX, relTempField,
4
4
  import { betweenBounds, inOperands, GROUP_OPS, groupClauses, isGroupOp, LIKE_OPS, likeRegex, whereOperators, sizeComparisons, } from '../dialect/operators.js';
5
5
  import { aggregateColumnField, groupPathField, resolveGroupJoins, relationSortTerms, resolveQueryJoins, resolveSortableJoin, } from '../dialect/queryJoins.js';
6
6
  import { assertSoleId, fieldOf, getMeta, relationOf, soleIdOf } from '../entity/index.js';
7
+ import { referenceKeys } from '../entity/metadata/definition.js';
7
8
  import { COUNT_RESULT_KEY } from '../type/query.js';
8
9
  import { QuerySql } from '../type/querySql.js';
9
10
  import { aggregateOf, isSelectList, assertAggregateColumns, assertNoUndefined, assertNonNegativeInteger, columnFamily, countedRelations, entityName, fieldUpdateOf, fillOnFields, filterFieldKeys, findVectorIndex, findVectorSort, definedEntries, getKeys, holdsForeignKey, jsonPathKeys, getRelationRequestSummary, hasKeys, isFieldUpdateOp, isJsonObject, foldJson, writesKeys, isJsonUpdateOp, isOperatorMap, isOperatorObject, isRecord, isVectorSearch, normalizeScalarFieldSelection, parentJoins, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortDirection, rankedTextSearch, someKey, targetJoins, textSortOf, indexedDistance, vectorDistanceOf, vectorCandidates, populatesRelations, cachedIn, } from '../util/index.js';
@@ -1085,12 +1086,8 @@ export class MongoDialect extends AbstractDialect {
1085
1086
  meta: getMeta(relation.entity()),
1086
1087
  })));
1087
1088
  }
1088
- referenceKeys(meta) {
1089
- return cachedIn(this.#referenceKeys, meta, () => getKeys(meta.fields).filter((key) => meta.fields[key]?.references));
1090
- }
1091
1089
  // Keyed by the meta object itself; entity metadata is immutable once defined.
1092
1090
  #renamedColumns = new WeakMap();
1093
- #referenceKeys = new WeakMap();
1094
1091
  #relationReads = new WeakMap();
1095
1092
  normalizeIds(meta, docs) {
1096
1093
  return docs.map((doc) => this.normalizeId(meta, doc));
@@ -1118,7 +1115,7 @@ export class MongoDialect extends AbstractDialect {
1118
1115
  }
1119
1116
  }
1120
1117
  // After the rename, so a renamed reference is converted under the name the code reads.
1121
- for (const key of this.referenceKeys(meta)) {
1118
+ for (const key of referenceKeys(meta)) {
1122
1119
  if (res[key] !== undefined) {
1123
1120
  res[key] = this.fromWireId(res[key]);
1124
1121
  }
@@ -1161,7 +1158,7 @@ export class MongoDialect extends AbstractDialect {
1161
1158
  }
1162
1159
  /** Whether `key` holds ids the driver stores as `ObjectId`s: the entity's own `_id`, or a reference to one. */
1163
1160
  holdsKeys(meta, key) {
1164
- return this.pathOf(meta, key) === ID_KEY || !!meta.fields[key]?.references;
1161
+ return this.pathOf(meta, key) === ID_KEY || referenceKeys(meta).has(key);
1165
1162
  }
1166
1163
  /** Converts every operand `ops` compares a key against with {@link toWireId}, including inside a `$not`. */
1167
1164
  toWireOperands(ops) {
@@ -1241,7 +1238,7 @@ export class MongoDialect extends AbstractDialect {
1241
1238
  const field = fieldOf(meta, key);
1242
1239
  const value = it[key];
1243
1240
  assertNoRaw(value, 'a write');
1244
- doc[this.resolveColumnName(key, field)] = field.references ? this.toWireId(value) : value;
1241
+ doc[this.resolveColumnName(key, field)] = referenceKeys(meta).has(key) ? this.toWireId(value) : value;
1245
1242
  }
1246
1243
  // Keyed by column, which the driver's types read as `E`'s keys: they name the same fields.
1247
1244
  return doc;
@@ -4,12 +4,12 @@ import { BYTES_PREFIX } from '../dialect/hydrateColumn.js';
4
4
  import { skippablePath, jsonArraySlotArgs, jsonPath, jsonSlotArgs, } from '../dialect/jsonSql.js';
5
5
  import { MergeSqlDialect } from '../dialect/mergeSqlDialect.js';
6
6
  import { getMeta } from '../entity/index.js';
7
- import { soleId } from '../entity/metadata/definition.js';
7
+ import { generatesKey, soleId } from '../entity/metadata/definition.js';
8
8
  import { canonicalToSql, resolveColumnCanonicalType } from '../schema/canonicalType.js';
9
9
  import { QuerySql } from '../type/index.js';
10
10
  import { parseQueryLock } from '../type/index.js';
11
11
  import { bytesToHex } from '../util/bytes.js';
12
- import { isAutoIncrement, isExactDecimal, jsonPathKeys } from '../util/field.util.js';
12
+ import { isExactDecimal, jsonPathKeys } from '../util/field.util.js';
13
13
  import { assertNonNegativeInteger, isOperatorMap, RETURNED_ID } from '../util/index.js';
14
14
  import { escapeSingleQuotes } from '../util/sqlLiteral.js';
15
15
  import { UqlUsageError } from '../util/uqlError.js';
@@ -149,12 +149,12 @@ export class MsSqlDialect extends MergeSqlDialect {
149
149
  }
150
150
  /** The table to toggle, or nothing when no record writes a key the engine would have generated. */
151
151
  identityInsertTarget(meta, payload) {
152
- const id = soleId(meta);
153
- if (!id || !isAutoIncrement(id.field, true)) {
152
+ if (!generatesKey(meta)) {
154
153
  return undefined;
155
154
  }
155
+ const [idKey] = meta.ids;
156
156
  const records = Array.isArray(payload) ? payload : [payload];
157
- const stated = records.some((record) => record[id.key] !== undefined);
157
+ const stated = records.some((record) => record[idKey] !== undefined);
158
158
  return stated ? this.escapedTableName(meta) : undefined;
159
159
  }
160
160
  /** An exact decimal, converted before it crosses the wire, where `tedious` would round it. */
@@ -1,7 +1,7 @@
1
1
  import { AGGREGATE_VALUE_ALIAS, TOTAL_ALIAS } from '../dialect/aliases.js';
2
2
  import { getMeta } from '../entity/index.js';
3
- import { soleId } from '../entity/metadata/definition.js';
4
- import { buildUpdateResult, chunk, clone, getInsertFieldKeys, insertShapeOf, isAutoIncrement, upsertKeepsOwnKey, } from '../util/index.js';
3
+ import { generatesKey, soleId } from '../entity/metadata/definition.js';
4
+ import { buildUpdateResult, chunk, clone, getInsertFieldKeys, insertShapeOf, upsertKeepsOwnKey, } from '../util/index.js';
5
5
  import { statementOf } from '../util/sql.js';
6
6
  import { UqlUsageError } from '../util/uqlError.js';
7
7
  import { AbstractQuerier } from './abstractQuerier.js';
@@ -265,7 +265,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
265
265
  // already carry every column of it. `sole` is what keeps every id path off such a key.
266
266
  const [idKey] = meta.ids;
267
267
  const sole = soleId(meta);
268
- const generatedKey = !!sole && isAutoIncrement(sole.field, true);
268
+ const generatedKey = generatesKey(meta);
269
269
  // Per group, not per batch: the two carry different columns - one names the key, one does not - so a budget
270
270
  // taken over their union would under-fill the statement that is missing one. Header ids are only sound where
271
271
  // every row of a statement left its key to the database, so a supplied id cannot void the others.
@@ -2,7 +2,7 @@ import type { Except, FieldMeta, QuerySql } from '../type/index.js';
2
2
  import type { ColumnNode } from './types.js';
3
3
  /**
4
4
  * The column a field's options declare, whether an entity's table or a migration holds it: `soleKey` says whether it
5
- * is its table's only key, which a numeric one auto-increments as, and `compile` renders its SQL.
5
+ * is its table's whole and own key, which a numeric one auto-increments as, and `compile` renders its SQL.
6
6
  */
7
7
  export declare function declaredColumn(field: FieldMeta, { name, soleKey, compile, }: {
8
8
  readonly name: string;
@@ -3,7 +3,7 @@ import { resolveColumnCanonicalType } from './canonicalType.js';
3
3
  import { schemaDefault } from './sqlExpression.js';
4
4
  /**
5
5
  * The column a field's options declare, whether an entity's table or a migration holds it: `soleKey` says whether it
6
- * is its table's only key, which a numeric one auto-increments as, and `compile` renders its SQL.
6
+ * is its table's whole and own key, which a numeric one auto-increments as, and `compile` renders its SQL.
7
7
  */
8
8
  export function declaredColumn(field, { name, soleKey, compile, }) {
9
9
  return {
@@ -1,7 +1,7 @@
1
- import { fieldOf, foreignKeysOf, getMeta } from '../entity/metadata/definition.js';
1
+ import { fieldOf, foreignKeysOf, getMeta, ownsSoleKey } from '../entity/metadata/definition.js';
2
2
  import { declaredIndexes, enumCheck, ownedCheck, renderIndex } from '../util/ddlExpression.util.js';
3
3
  import { fulltextWeights, textWeightSteps } from '../util/dialect.util.js';
4
- import { isInlinedExpression, isSoleIdField } from '../util/field.util.js';
4
+ import { isInlinedExpression } from '../util/field.util.js';
5
5
  import { entryColumn, entryColumns, renamedEntry } from '../util/indexEntry.util.js';
6
6
  import { definedEntries, entityName } from '../util/object.util.js';
7
7
  import { derivedForeignKeyName, derivedIndexName } from '../util/sql.util.js';
@@ -68,7 +68,7 @@ function addTableFromEntity(ctx, meta) {
68
68
  const column = {
69
69
  ...declaredColumn(field, {
70
70
  name: columnName,
71
- soleKey: isSoleIdField(meta, field),
71
+ soleKey: ownsSoleKey(meta, key),
72
72
  compile: (sql) => ctx.compileDdl(sql, meta.entity),
73
73
  }),
74
74
  ...(notNull.has(key) && { nullable: false }),
@@ -38,8 +38,8 @@ export declare class SqliteQuerier extends AbstractSqlQuerier {
38
38
  protected get connection(): object;
39
39
  /** `reader` picks the call: `run()` would discard the rows of a statement that reads, RETURNING included. */
40
40
  protected execute(sql: string, values?: unknown[]): Promise<{
41
- changes?: undefined;
42
41
  rows: RawRow[];
42
+ changes?: undefined;
43
43
  } | {
44
44
  rows: never[];
45
45
  changes: number;
@@ -771,6 +771,8 @@ export type EntityMeta<E> = {
771
771
  stage?: 'declared' | 'settled' | 'resolved';
772
772
  /** The fields a read answers with where it names none, set once resolved: see `defaultReadKeys`. */
773
773
  readKeys?: readonly FieldKey<E>[];
774
+ /** The fields holding another entity's key, set once resolved: see `referenceKeys`. */
775
+ referenceKeys?: ReadonlySet<string>;
774
776
  };
775
777
  /** When the database writes a stamp: as the row is inserted, as it is updated, or both. */
776
778
  export type StampEvent = 'insert' | 'update';
@@ -38,14 +38,12 @@ 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
- /** Whether the field is the whole primary key, the only kind a serial stands for and a column may declare. */
42
- export declare function isSoleIdField<E>(meta: EntityMeta<E>, field: FieldOptions): boolean;
43
41
  /**
44
- * Whether the database generates this column's value: a numeric key nothing else fills. `onInsert` fills
45
- * it from the application and `references` from the row it shares its key with; a `columnType` only
46
- * states its width. The one answer the create statement and the diff both read.
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.
47
45
  */
48
- export declare function isAutoIncrement(field: FieldOptions, isPrimaryKey: boolean): boolean;
46
+ export declare function isAutoIncrement(field: FieldOptions, soleKey: boolean): boolean;
49
47
  /** The column family of a field, from its `columnType` if set, else from its `type`. */
50
48
  export declare function fieldFamily(field: FieldOptions): ColumnFamily | undefined;
51
49
  /** Whether the column is NOT NULL: every column is, a key included, unless it declares `nullable()`. */
@@ -83,19 +83,15 @@ export function aggregateField(aggregate) {
83
83
  export function isDatabaseWritten(field) {
84
84
  return field.computed !== undefined;
85
85
  }
86
- /** Whether the field is the whole primary key, the only kind a serial stands for and a column may declare. */
87
- export function isSoleIdField(meta, field) {
88
- return field.isId === true && meta.ids.length === 1;
89
- }
90
86
  /**
91
- * Whether the database generates this column's value: a numeric key nothing else fills. `onInsert` fills
92
- * it from the application and `references` from the row it shares its key with; a `columnType` only
93
- * states its width. The one answer the create statement and the diff both read.
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.
94
90
  */
95
- export function isAutoIncrement(field, isPrimaryKey) {
91
+ export function isAutoIncrement(field, soleKey) {
96
92
  if (field.autoIncrement !== undefined)
97
93
  return field.autoIncrement;
98
- return isPrimaryKey && columnFamily(field.type) === 'numeric' && !field.onInsert && !field.references;
94
+ return soleKey && columnFamily(field.type) === 'numeric' && !field.onInsert;
99
95
  }
100
96
  /** The column family of a field, from its `columnType` if set, else from its `type`. */
101
97
  export function fieldFamily(field) {
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.106.1",
6
+ "version": "0.107.0",
7
7
  "type": "module",
8
8
  "engines": {
9
9
  "node": ">=22.18"
@@ -123,13 +123,13 @@
123
123
  }
124
124
  },
125
125
  "devDependencies": {
126
- "@electric-sql/pglite": "0.5.11",
127
- "@electric-sql/pglite-pgvector": "0.0.12",
126
+ "@electric-sql/pglite": "0.5.12",
127
+ "@electric-sql/pglite-pgvector": "0.0.13",
128
128
  "@libsql/client": "^0.18.0",
129
129
  "@neondatabase/serverless": "^1.2.0",
130
- "@nestjs/common": "^12.2.0",
131
- "@nestjs/core": "^12.2.0",
132
- "@nestjs/testing": "^12.2.0",
130
+ "@nestjs/common": "^12.3.2",
131
+ "@nestjs/core": "^12.3.2",
132
+ "@nestjs/testing": "^12.3.2",
133
133
  "@tursodatabase/database": "^0.8.3",
134
134
  "@tursodatabase/serverless": "^1.4.1",
135
135
  "@types/better-sqlite3": "^9.6.0",
@@ -141,7 +141,7 @@
141
141
  "express": "^5.3.0",
142
142
  "mariadb": "^3.5.4",
143
143
  "mongodb": "^7.7.0",
144
- "mssql": "^12.7.11",
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",
@@ -79,6 +79,7 @@ export class Post {
79
79
 
80
80
  - A column is a builder: `f.string()`, `f.text()`, `f.uuid()`, `f.number()`, `f.bigint()`, `f.decimal()`, `f.decimal(precision)`, `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 column type, and `f.references(() => Target)` for a foreign key, which takes the target's key type. Only the methods a column's type takes exist: `.length()` is a string's, `.precision()` a number's or a date's. A bound holds in either order around `.columnType('char')`, but not around a `sql` type, which carries its own.
81
81
  - A column is NOT NULL unless `.nullable()`; its property then admits `null` (`title?: string | null`).
82
+ - A JSON column's property is `Json<T>`, where `T` is the payload: `settings?: Json<{ theme?: string }> | null`, or `Json<z.infer<typeof Settings>>` for a schema. A plain object type reads as a relation, and `$where`, `$sort` and the update operators refuse it.
82
83
  - Declare a NOT NULL column with `!` (`email!: string`). Declare `?` for anything else an insert may omit: nullable columns, `.eager(false)` fields, and relations. A computed field is present on a default read, so it is not optional. uql fills a single-column key and a version.
83
84
  - A NOT NULL field a default fills (`.default()`, `.onInsert()`) is `!` and listed in the class's `[filledKey]?: 'stock' | 'createdAt'`: inserts may omit it, reads always have it.
84
85
  - `.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.
@@ -93,6 +94,39 @@ export class Post {
93
94
  - JSON path index: read the path off the column's ref, `index([user.settings.theme])` for text, `index([{ column: user.settings.rating, type: Number }])` for any other value, `type: [String]` for an array's elements. MySQL keys a text path or element as `CHAR(n)`, `{ column: user.tags, type: [String], charLength: 64 }`, and a `TEXT` column by a prefix, `{ column: post.body, prefixLength: 64 }`.
94
95
  - Triggers run in the database: `@Entity({ triggers: (post, trigger) => [trigger({ on: 'afterUpdate', of: [post.status], run })] })`, where `run` returns a body built from `insertInto`, `upsertInto`, `updateTable`, `deleteFrom` and `refuse(message)`. A trigger's writes skip uql's fills and entity filters. MongoDB has no triggers: https://uql-orm.dev/entities/triggers.md
95
96
 
97
+ ### Choosing a form
98
+
99
+ Both forms are supported, mix them per entity, and produce the same queries and types.
100
+
101
+ - Decorators
102
+ - Pros
103
+ - A named class type shows on hover.
104
+ - A column can be a foreign key (`@Field(f.references(() => User))`), so entities may reference each other in any order.
105
+ - No `.relations()` ordering rules.
106
+ - Shared structure through base classes (`StampedEntity`, `WorkspaceScoped`) that carry fields and relations.
107
+ - The familiar form from TypeORM and MikroORM.
108
+ - Cons
109
+ - Each field is written twice, as a builder and as a TypeScript property (`@Field(f.string()) name!: string`).
110
+ - The TC39 decorator transform is required: Node needs `tsx`, and some bundlers need a Babel step.
111
+ - Without `@Entity({ name })`, the table name comes from the class name, which a minifier can change.
112
+ - Higher type-check cost on the benchmark model (9,297 vs 5,110 instantiations).
113
+ - Cannot be declared at run time.
114
+ - `uql-codemod` cannot convert it into a schema.
115
+ - Schema
116
+ - Pros
117
+ - The row type is derived from the builders, with nothing written twice.
118
+ - Shorter: 19 to 30% fewer lines in the two apps this was measured on.
119
+ - Lower type-check cost on the benchmark model.
120
+ - Shared relation helpers, and derived fields declared with their relations.
121
+ - Plain data: no transform, and it can be built at run time (a CMS content type).
122
+ - The form for projects that cannot enable TC39 decorators, such as legacy-decorator NestJS and Angular.
123
+ - Cons
124
+ - Relations are thunks declared after the columns, and `.relations()` comes last (only `.filters()` may follow it).
125
+ - No column-level foreign keys: a shared key is a relation helper, and an eager read across two entities can create an inference cycle (TS7022).
126
+ - Each entity needs a `type X = InstanceType<typeof X>` alias for its name.
127
+ - No class to annotate or extend: inheritance uses `extends` on a base schema.
128
+ - Newer and less used.
129
+
96
130
  ### Schema entities
97
131
 
98
132
  The same entities declared as data, the row type derived:
@@ -146,7 +180,7 @@ export const Book = defineEntity({
146
180
  ```
147
181
 
148
182
  - Each field is a column builder, as in the decorated form. The row follows from them: a key, a version and a NOT NULL column are always present, a `.nullable()` one reads `| null`; a default (`.default()`, `.onInsert()`, `.autoIncrement()`) makes it optional on insert; `f.enum()` gives the literal union. No `!`, `?` or brands to write.
149
- - The other options are sections chained after `defineEntity`, each called at most once: `computed`, `indexes`, `checks`, `triggers`, `filters` and `hooks` read the columns; `relations` comes last, but for a `filters` that reads through them: `.relations(...).filters({ byActiveAuthor: { where: { author: { active: true } } } })`. `defineEntity` itself takes `name` (the class name, which a naming strategy derives the table from), `table`, `schema`, `extends` and `fields`.
183
+ - The other options are sections chained after `defineEntity`, each called at most once: `computed`, `indexes`, `checks`, `triggers`, `filters` and `hooks` read the columns; `relations` comes last, but for a `filters` that reads through them: `.relations(...).filters({ byActiveAuthor: { where: { author: { active: true } } } })`. `defineEntity` itself takes `name` (the class name, which a naming strategy derives the table from), `table`, `schema`, `extends`, `abstract` and `fields`.
150
184
  - Each relation is a thunk, `author: () => rel.manyToOne(...)`, so entities pointing at each other can sit in either order and in different files. A schema's foreign key is a relation: `manyToOne` names its `references` column, whose type is checked against the target's key; the column itself stays a plain field. `oneToMany(Book)` with no options is mapped by the one relation of `Book` pointing back.
151
185
  - `relations`' second callback declares the derived fields: each value is a thunk, read lazily, of an aggregate over a to-many (`() => author.books.count()`) or a column expression. The callback's refs are the entity's own columns and its relations, so one expression can combine them.
152
186
  - A hook is a function of the row and `{ querier, onCommit }`.
@@ -232,6 +266,8 @@ A `findManyStream` holds its querier until the loop ends, and other statements o
232
266
 
233
267
  ## Migrations
234
268
 
269
+ Upgrading an existing project: `npx uql-codemod --dry-run`, then `npx uql-codemod`, which rewrites what it can and reports the rest. What changed by version: https://uql-orm.dev/upgrade-guide.md
270
+
235
271
  `npx uql-migrate` reads `uql.config.ts` (`bun --bun uql-migrate` on Bun):
236
272
 
237
273
  - `sync`: applies what the entities imply. Development only.