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 +1 -1
- package/dist/dialect/abstractSqlDialect.js +3 -3
- package/dist/entity/metadata/definition.d.ts +10 -0
- package/dist/entity/metadata/definition.js +25 -4
- package/dist/migrate/builder/types.d.ts +5 -7
- package/dist/migrate/codegen/fieldOptionsSource.js +8 -1
- package/dist/migrate/generator/definitionToNode.d.ts +1 -1
- package/dist/migrate/generator/definitionToNode.js +4 -8
- package/dist/mongodb/mongoDialect.d.ts +0 -1
- package/dist/mongodb/mongoDialect.js +4 -7
- package/dist/mongodb/mongoIntrospector.d.ts +1 -1
- package/dist/mongodb/mongoSchemaGenerator.js +4 -7
- package/dist/mssql/mssqlDialect.js +5 -5
- package/dist/querier/abstractSqlQuerier.js +3 -3
- package/dist/schema/declaredColumn.d.ts +1 -1
- package/dist/schema/declaredColumn.js +1 -1
- package/dist/schema/schemaASTBuilder.js +9 -15
- package/dist/sqlite/sqliteQuerier.d.ts +1 -1
- package/dist/type/entity.d.ts +36 -30
- package/dist/type/vector.d.ts +4 -4
- package/dist/util/ddlExpression.util.d.ts +6 -6
- package/dist/util/ddlExpression.util.js +11 -5
- package/dist/util/field.util.d.ts +4 -6
- package/dist/util/field.util.js +5 -9
- package/package.json +7 -7
- package/skills/uql-orm/SKILL.md +37 -1
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 {
|
|
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 &&
|
|
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
|
|
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
|
|
24
|
-
*
|
|
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 =
|
|
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
|
|
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
|
|
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 {
|
|
3
|
-
import { normalizeIndexColumn
|
|
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
|
|
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 ||
|
|
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)] =
|
|
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<
|
|
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,
|
|
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
|
|
70
|
+
const index = renderIndex(collectionName, { ...options, entries }, refuseSql, (label) => where && this.indexFilter(where, meta.entity, label));
|
|
71
71
|
return {
|
|
72
|
-
...
|
|
73
|
-
|
|
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 {
|
|
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
|
-
|
|
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[
|
|
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,
|
|
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 =
|
|
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
|
|
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
|
|
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,
|
|
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
|
|
5
|
-
import { entryColumn, entryColumns, renamedEntry
|
|
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:
|
|
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
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
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;
|
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,
|
|
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
|
-
|
|
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
|
-
|
|
917
|
-
|
|
918
|
-
|
|
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> =
|
|
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[];
|
package/dist/type/vector.d.ts
CHANGED
|
@@ -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
|
|
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
|
|
14
|
-
readonly
|
|
15
|
-
readonly
|
|
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
|
|
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
|
|
27
|
-
const where =
|
|
28
|
-
return {
|
|
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:
|
|
45
|
-
*
|
|
46
|
-
*
|
|
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,
|
|
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()`. */
|
package/dist/util/field.util.js
CHANGED
|
@@ -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:
|
|
92
|
-
*
|
|
93
|
-
*
|
|
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,
|
|
91
|
+
export function isAutoIncrement(field, soleKey) {
|
|
96
92
|
if (field.autoIncrement !== undefined)
|
|
97
93
|
return field.autoIncrement;
|
|
98
|
-
return
|
|
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.
|
|
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.
|
|
127
|
-
"@electric-sql/pglite-pgvector": "0.0.
|
|
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
|
|
131
|
-
"@nestjs/core": "^12.2
|
|
132
|
-
"@nestjs/testing": "^12.2
|
|
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.
|
|
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",
|
package/skills/uql-orm/SKILL.md
CHANGED
|
@@ -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.
|