uql-orm 0.106.0 → 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);
@@ -1,5 +1,5 @@
1
1
  import type { ColumnNode, EnumValues, ForeignKeyAction } from '../../schema/types.js';
2
- import type { IndexEntry, Except, FieldOptions, IndexColumnInput, IndexOptions, IndexSchema, QuerySql } from '../../type/index.js';
2
+ import type { IndexEntry, Except, FieldOptions, IndexColumnInput, IndexOptions } from '../../type/index.js';
3
3
  import type { ForeignKeySchema } from '../../type/migration.js';
4
4
  export type ColumnDefinition = Except<ColumnNode, 'table'>;
5
5
  /**
@@ -20,14 +20,12 @@ export interface FullColumnDefinition extends ColumnDefinition {
20
20
  index?: string | boolean;
21
21
  }
22
22
  /**
23
- * An index as the builder records it, with the entries and options an entity's `indexes` entry takes: its SQL kept as `raw`
24
- * until a generator renders it for the engine the migration runs on.
23
+ * An index as the builder records it: its options as declared, its SQL kept as `raw` until a generator renders it for
24
+ * the engine the migration runs on, and an unnamed one named then, from its predicate as written.
25
25
  */
26
- export type IndexDefinition = Except<IndexSchema, 'name' | 'entries' | 'where'> & {
27
- /** As declared; an unnamed index is named when it is rendered, from its predicate as written. */
28
- readonly name?: string;
26
+ export type IndexDefinition = IndexOptions & {
29
27
  readonly entries: readonly IndexEntry[];
30
- readonly where?: QuerySql;
28
+ readonly unique: boolean;
31
29
  /** Whether an unnamed index takes the `_uk` kind. Only `table.unique` sets it: earlier migrations installed `_uk` there, so `index` keeps `_idx`. */
32
30
  readonly uniqueName?: boolean;
33
31
  };
@@ -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);
@@ -34,6 +34,6 @@ export declare function indexDefinition(columns: readonly IndexColumnInput[], {
34
34
  * An index the builder recorded, its SQL rendered by `render` into the text the schema holds, and named
35
35
  * from that text the way an entity's is.
36
36
  */
37
- export declare function renderIndexDefinition(table: string, { uniqueName, ...index }: IndexDefinition, render: (sql: QuerySql) => string): IndexSchema;
37
+ export declare function renderIndexDefinition(table: string, { uniqueName, where, ...index }: IndexDefinition, render: (sql: QuerySql) => string): IndexSchema;
38
38
  /** The foreign key a column-level `references` declares, or nothing. Shared for the same reason. */
39
39
  export declare function columnForeignKey(col: FullColumnDefinition): ForeignKeySchema | undefined;
@@ -1,6 +1,6 @@
1
1
  import { createTableNode, keyOfColumns } from '../../schema/schemaAST.js';
2
- import { namedIndex, enumCheck } from '../../util/ddlExpression.util.js';
3
- import { normalizeIndexColumn, renderIndexColumn } from '../../util/indexEntry.util.js';
2
+ import { enumCheck, renderIndex } from '../../util/ddlExpression.util.js';
3
+ import { normalizeIndexColumn } from '../../util/indexEntry.util.js';
4
4
  import { derivedIndexName, splitQualifiedName } from '../../util/sql.util.js';
5
5
  /**
6
6
  * A migration builder's table definition as the AST nodes the generators render from, so a hand-written
@@ -61,12 +61,8 @@ export function indexDefinition(columns, { name, unique = false, ...options } =
61
61
  * An index the builder recorded, its SQL rendered by `render` into the text the schema holds, and named
62
62
  * from that text the way an entity's is.
63
63
  */
64
- export function renderIndexDefinition(table, { uniqueName, ...index }, render) {
65
- return {
66
- ...index,
67
- ...namedIndex(index.name, table, index.entries, () => index.where && render(index.where), uniqueName),
68
- entries: index.entries.map((entry) => renderIndexColumn(entry, render)),
69
- };
64
+ export function renderIndexDefinition(table, { uniqueName, where, ...index }, render) {
65
+ return renderIndex(table, index, render, () => where && render(where), uniqueName);
70
66
  }
71
67
  /** The foreign key a column-level `references` declares, or nothing. Shared for the same reason. */
72
68
  export function columnForeignKey(col) {
@@ -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;
@@ -15,4 +15,4 @@ export declare class MongoSchemaIntrospector implements SchemaIntrospector {
15
15
  private withDb;
16
16
  }
17
17
  /** A key as the entity declares it: the field, then the path inside it, so the two compare and name alike. */
18
- export declare function documentEntry(key: string): IndexEntry<string>;
18
+ export declare function documentEntry(key: string): IndexEntry<never>;
@@ -8,7 +8,7 @@ import { sides } from '../migrate/schemaChange.js';
8
8
  import { indexChanges } from '../schema/indexDifferences.js';
9
9
  import { QuerySql, } from '../type/index.js';
10
10
  import { indexDistance, unsupportedVectorMetric } from '../type/vector.js';
11
- import { declaredIndexes, namedIndex } from '../util/ddlExpression.util.js';
11
+ import { declaredIndexes, renderIndex } from '../util/ddlExpression.util.js';
12
12
  import { findVectorIndex, fulltextConfig, fulltextWeights, indexedDistance } from '../util/dialect.util.js';
13
13
  import { entryKeys, entryModifiers, renamedEntry } from '../util/indexEntry.util.js';
14
14
  import { definedEntries, hasKeys } from '../util/object.util.js';
@@ -67,13 +67,10 @@ export class MongoSchemaGenerator extends MongoDialect {
67
67
  const [first] = declared;
68
68
  const vectorKey = options.type === 'vectorSearch' && typeof first?.column === 'string' ? first.column : undefined;
69
69
  const vector = vectorKey === undefined ? undefined : meta.fields[vectorKey];
70
- const named = namedIndex(options.name, collectionName, entries, (label) => where && this.indexFilter(where, meta.entity, label));
70
+ const index = renderIndex(collectionName, { ...options, entries }, refuseSql, (label) => where && this.indexFilter(where, meta.entity, label));
71
71
  return {
72
- ...options,
73
- ...named,
74
- name: vector ? this.vectorSearchIndexName(options.name, documentPath(entries[0])) : named.name,
75
- entries,
76
- unique: options.unique ?? false,
72
+ ...index,
73
+ name: vector ? this.vectorSearchIndexName(options.name, documentPath(entries[0])) : index.name,
77
74
  distance: vectorKey === undefined
78
75
  ? options.distance
79
76
  : indexedDistance(meta, vectorKey, findVectorIndex(meta, vectorKey)),
@@ -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,8 +1,8 @@
1
- import { fieldOf, foreignKeysOf, getMeta } from '../entity/metadata/definition.js';
2
- import { declaredIndexes, namedIndex, enumCheck, ownedCheck } from '../util/ddlExpression.util.js';
1
+ import { fieldOf, foreignKeysOf, getMeta, ownsSoleKey } from '../entity/metadata/definition.js';
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';
5
- import { entryColumn, entryColumns, renamedEntry, renderIndexColumn } from '../util/indexEntry.util.js';
4
+ import { isInlinedExpression } from '../util/field.util.js';
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';
8
8
  import { UqlUsageError } from '../util/uqlError.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 }),
@@ -176,16 +176,10 @@ function addCompositeIndex(ctx, table, meta, { entries, include, where, ...optio
176
176
  });
177
177
  if (!resolved.length)
178
178
  return;
179
- const named = namedIndex(options.name, table.name, resolved, (label) => where && ctx.compileIndexPredicate(where, meta.entity, label));
180
- ctx.ast.addIndex({
181
- ...options,
182
- ...named,
183
- table,
184
- entries: resolved.map((entry) => renderIndexColumn(entry, (sql) => ctx.compileDdl(sql, meta.entity))),
185
- // An `include` column is named like any other, so a custom naming has to reach it too.
186
- include: include?.map((column) => fieldColumn(ctx, meta, column) ?? column),
187
- unique: options.unique ?? false,
188
- });
179
+ const index = renderIndex(table.name,
180
+ // An `include` column is named like any other, so a custom naming has to reach it too.
181
+ { ...options, entries: resolved, include: include?.map((column) => fieldColumn(ctx, meta, column) ?? column) }, (sql) => ctx.compileDdl(sql, meta.entity), (label) => where && ctx.compileIndexPredicate(where, meta.entity, label));
182
+ ctx.ast.addIndex({ ...index, table });
189
183
  if (ctx.textScoreIndexes) {
190
184
  addTextScoreIndexes(ctx, table, options.type, resolved);
191
185
  }
@@ -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;
@@ -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, Except, ExactlyOne, IsEqual, Merge, IsJson, JsonBrand, IsMany, Json, JsonScalar, Scalar, Type, AbstractType, Unpacked, Writable } from './utility.js';
8
+ import type { AtLeastOne, ExactlyOne, 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;
@@ -577,21 +577,21 @@ export type HookFunction = {
577
577
  * cosine; a `fulltext` one may name the text-search `config` it parses with; and any other index neither.
578
578
  */
579
579
  export type IndexTypeOptions = {
580
- type: VectorIndexType;
581
- distance: VectorDistance;
582
- config?: never;
580
+ readonly type: VectorIndexType;
581
+ readonly distance: VectorDistance;
582
+ readonly config?: never;
583
583
  } | {
584
- type: 'vectorSearch';
585
- distance?: VectorDistance;
586
- config?: never;
584
+ readonly type: 'vectorSearch';
585
+ readonly distance?: VectorDistance;
586
+ readonly config?: never;
587
587
  } | {
588
- type: 'fulltext';
589
- distance?: never;
590
- config?: string;
588
+ readonly type: 'fulltext';
589
+ readonly distance?: never;
590
+ readonly config?: string;
591
591
  } | {
592
- type?: Exclude<IndexType, VectorIndexType | 'vectorSearch' | 'fulltext'>;
593
- distance?: never;
594
- config?: never;
592
+ readonly type?: Exclude<IndexType, VectorIndexType | 'vectorSearch' | 'fulltext'>;
593
+ readonly distance?: never;
594
+ readonly config?: never;
595
595
  };
596
596
  /** What an index entry carries besides what it indexes, at every layer. */
597
597
  export type IndexEntryModifiers = {
@@ -709,19 +709,25 @@ type IndexEntryTarget = (ColumnLengths & {
709
709
  * @example `{ columns: (user) => [user.settings.theme, { column: user.settings.rating, type: Number }] }`
710
710
  */
711
711
  export type EntityIndexColumnInput = QuerySql | JsonPathRef<string> | JsonPathRef<UntypedJson> | (IndexEntryModifiers & IndexEntryTarget);
712
+ /**
713
+ * What an index states the same at every layer. Each layer adds its own `include` and `where` beside it, so nothing
714
+ * maps over `IndexTypeOptions`' arms: `type` and `distance` stay a discriminated pair at no instantiation cost.
715
+ */
716
+ export type IndexKnobs = {
717
+ /** Custom index name */
718
+ readonly name?: string;
719
+ /** Whether index is unique; omit or `false` for a non-unique index (default). */
720
+ readonly unique?: boolean;
721
+ } & VectorIndexOptions & IndexTypeOptions;
712
722
  /** An index as metadata keeps it. */
713
723
  export type EntityIndexMeta<E = object> = {
714
724
  /** The indexed entries, in order. */
715
- entries: readonly IndexEntry[];
716
- /** Custom index name */
717
- name?: string;
718
- /** Whether index is unique; omit or `false` for a non-unique index (default). */
719
- unique?: boolean;
720
- /** Partial index predicate, compiled when the schema is built. */
721
- where?: EntityWhereMeta<E>;
725
+ readonly entries: readonly IndexEntry[];
722
726
  /** Columns stored in the index beyond its key, so a query reading only these needs no row. Postgres-wire only. */
723
- include?: readonly string[];
724
- } & VectorIndexOptions & IndexTypeOptions;
727
+ readonly include?: readonly string[];
728
+ /** Partial index predicate, compiled when the schema is built. */
729
+ readonly where?: EntityWhereMeta<E>;
730
+ } & IndexKnobs;
725
731
  export type EntityMeta<E> = {
726
732
  readonly entity: AbstractType<E>;
727
733
  /** The table, which is the class's own name where the entity named none - see {@link derivedName}. */
@@ -765,6 +771,8 @@ export type EntityMeta<E> = {
765
771
  stage?: 'declared' | 'settled' | 'resolved';
766
772
  /** The fields a read answers with where it names none, set once resolved: see `defaultReadKeys`. */
767
773
  readKeys?: readonly FieldKey<E>[];
774
+ /** The fields holding another entity's key, set once resolved: see `referenceKeys`. */
775
+ referenceKeys?: ReadonlySet<string>;
768
776
  };
769
777
  /** When the database writes a stamp: as the row is inserted, as it is updated, or both. */
770
778
  export type StampEvent = 'insert' | 'update';
@@ -912,24 +920,22 @@ export type EntityOptions<E = unknown> = {
912
920
  /** Triggers the database runs, in the order written. See {@link TriggerOptions}. */
913
921
  readonly triggers?: TriggerSection<E>;
914
922
  };
915
- /**
916
- * Everything an index carries beyond its columns, as the migration builder's `table.index(...)` takes it,
917
- * and through {@link EntityIndexOptions} an entity's `indexes`. `Except` (not plain `Omit`) keeps
918
- * `type`/`distance` a discriminated pair: omitting `distance` on a vector index type is a compile error.
919
- */
920
- export type IndexOptions = Except<EntityIndexMeta, 'entries' | 'where'> & {
923
+ /** Everything an index carries beyond its columns, as the migration builder's `table.index(...)` takes it. */
924
+ export type IndexOptions = IndexKnobs & {
925
+ /** Columns stored in the index beyond its key, so a query reading only these needs no row. Postgres-wire only. */
926
+ readonly include?: readonly string[];
921
927
  /** Partial-index predicate, as `sql` with no interpolation: the migration builder has no entity to compile one against. */
922
928
  readonly where?: QuerySql;
923
929
  };
924
930
  /** {@link IndexOptions} on an entity, `include` and `where` read off the section's refs as its columns are. */
925
- export type EntityIndexOptions<E> = Merge<IndexOptions, {
931
+ export type EntityIndexOptions<E> = IndexKnobs & {
926
932
  readonly include?: readonly ColumnRef<FieldKey<E>>[];
927
933
  /**
928
934
  * Partial-index predicate, written as the predicate the query passes: a planner matches the two by
929
935
  * shape, so a hand-written `sql` that means the same thing leaves the index unused.
930
936
  */
931
937
  readonly where?: EntityPredicate<E> | QuerySql;
932
- }>;
938
+ };
933
939
  /** An index as registration reads it: its columns, read off the refs, and its options. */
934
940
  export type EntityIndexInput<E> = EntityIndexOptions<E> & {
935
941
  readonly columns: readonly EntityIndexColumnInput[];
@@ -45,13 +45,13 @@ export declare function unsupportedVectorMetric(engine: EngineName, distance: Ve
45
45
  */
46
46
  export type VectorIndexOptions = {
47
47
  /** Distance metric for vector indexes - maps to operator class. */
48
- distance?: VectorDistance;
48
+ readonly distance?: VectorDistance;
49
49
  /** HNSW: max connections per node. */
50
- m?: number;
50
+ readonly m?: number;
51
51
  /** HNSW: construction search depth. */
52
- efConstruction?: number;
52
+ readonly efConstruction?: number;
53
53
  /** IVFFlat: number of inverted lists. */
54
- lists?: number;
54
+ readonly lists?: number;
55
55
  };
56
56
  /** The metric a search or an index measures by where nothing names one: every engine with vectors has it. */
57
57
  export declare const DEFAULT_VECTOR_DISTANCE: VectorDistance;
@@ -1,5 +1,5 @@
1
1
  import type { CheckSchema, EnumValues } from '../schema/types.js';
2
- import type { EntityIndexMeta, EntityMeta, IndexEntry, QuerySql } from '../type/index.js';
2
+ import type { EntityIndexMeta, EntityMeta, IndexEntry, IndexKnobs, IndexSchema, QuerySql } from '../type/index.js';
3
3
  /**
4
4
  * Every index an entity declares: each `index()` or `unique()` column as the one-column
5
5
  * index it is, then its `indexes`. A unique column is a unique index, the one spelling of uniqueness
@@ -7,13 +7,13 @@ import type { EntityIndexMeta, EntityMeta, IndexEntry, QuerySql } from '../type/
7
7
  */
8
8
  export declare function declaredIndexes<E>(meta: EntityMeta<E>): EntityIndexMeta<E>[];
9
9
  /**
10
- * An index's rendered predicate and the name it is created by, settled together: `render` gets the name without the
10
+ * An index as the schema holds it, its entries' SQL rendered by `renderSql`. `renderWhere` gets the name without the
11
11
  * predicate's hash to label its errors, then the name takes the hash of what it rendered.
12
12
  */
13
- export declare function namedIndex(name: string | undefined, table: string, entries: readonly IndexEntry<unknown>[], render: (label: string) => string | undefined, unique?: boolean): {
14
- readonly name: string;
15
- readonly where: string | undefined;
16
- };
13
+ export declare function renderIndex(table: string, { entries, unique, ...index }: IndexKnobs & {
14
+ readonly entries: readonly IndexEntry[];
15
+ readonly include?: readonly string[];
16
+ }, renderSql: (sql: QuerySql) => string, renderWhere: (label: string) => string | undefined, uniqueName?: boolean): IndexSchema;
17
17
  /**
18
18
  * The name an index is created and read by: its own, else one derived from its table, entries, uniqueness and
19
19
  * rendered predicate. A caller renders the predicate first, since an unnamed partial index's name carries its hash.
@@ -1,4 +1,4 @@
1
- import { indexEntryNamePart } from './indexEntry.util.js';
1
+ import { indexEntryNamePart, renderIndexColumn } from './indexEntry.util.js';
2
2
  import { definedEntries } from './object.util.js';
3
3
  import { sql } from './sql.js';
4
4
  import { derivedIndexName, ownedName } from './sql.util.js';
@@ -20,12 +20,18 @@ export function declaredIndexes(meta) {
20
20
  return [...fieldIndexes, ...(meta.indexes ?? [])];
21
21
  }
22
22
  /**
23
- * An index's rendered predicate and the name it is created by, settled together: `render` gets the name without the
23
+ * An index as the schema holds it, its entries' SQL rendered by `renderSql`. `renderWhere` gets the name without the
24
24
  * predicate's hash to label its errors, then the name takes the hash of what it rendered.
25
25
  */
26
- export function namedIndex(name, table, entries, render, unique) {
27
- const where = render(declaredIndexName(name, table, entries, { unique }));
28
- return { name: declaredIndexName(name, table, entries, { unique, where }), where };
26
+ export function renderIndex(table, { entries, unique = false, ...index }, renderSql, renderWhere, uniqueName) {
27
+ const where = renderWhere(declaredIndexName(index.name, table, entries, { unique: uniqueName }));
28
+ return {
29
+ ...index,
30
+ name: declaredIndexName(index.name, table, entries, { unique: uniqueName, where }),
31
+ where,
32
+ entries: entries.map((entry) => renderIndexColumn(entry, renderSql)),
33
+ unique,
34
+ };
29
35
  }
30
36
  /**
31
37
  * The name an index is created and read by: its own, else one derived from its table, entries, uniqueness and
@@ -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.0",
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.