uql-orm 0.104.1 → 0.105.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.
Files changed (143) hide show
  1. package/README.md +24 -10
  2. package/dist/browser/uql-browser.min.js +2 -2
  3. package/dist/browser/uql-browser.min.js.map +7 -7
  4. package/dist/dialect/abstractSqlDialect.d.ts +6 -4
  5. package/dist/dialect/abstractSqlDialect.js +35 -32
  6. package/dist/dialect/aliases.d.ts +2 -0
  7. package/dist/dialect/aliases.js +2 -0
  8. package/dist/dialect/jsonSql.js +2 -2
  9. package/dist/dialect/mysqlLikeSqlDialect.d.ts +1 -1
  10. package/dist/dialect/mysqlLikeSqlDialect.js +1 -1
  11. package/dist/dialect/operators.js +2 -4
  12. package/dist/dialect/queryJoins.d.ts +2 -0
  13. package/dist/dialect/vectorSqlDialect.d.ts +1 -1
  14. package/dist/dialect/vectorSqlDialect.js +1 -1
  15. package/dist/entity/column.d.ts +3 -0
  16. package/dist/entity/column.js +3 -0
  17. package/dist/entity/columnOptionsBuilder.d.ts +54 -0
  18. package/dist/entity/columnOptionsBuilder.js +108 -0
  19. package/dist/entity/decorator/bag.d.ts +4 -4
  20. package/dist/entity/decorator/entity.d.ts +2 -19
  21. package/dist/entity/decorator/entity.js +3 -37
  22. package/dist/entity/decorator/members.d.ts +46 -76
  23. package/dist/entity/decorator/members.js +18 -7
  24. package/dist/entity/index.d.ts +2 -1
  25. package/dist/entity/index.js +2 -1
  26. package/dist/entity/metadata/definition.d.ts +10 -24
  27. package/dist/entity/metadata/definition.js +329 -147
  28. package/dist/entity/metadata/schemaFixture/animal.d.ts +54 -0
  29. package/dist/entity/metadata/schemaFixture/animal.js +7 -0
  30. package/dist/entity/metadata/schemaFixture/author.d.ts +140 -0
  31. package/dist/entity/metadata/schemaFixture/author.js +25 -0
  32. package/dist/entity/metadata/schemaFixture/book.d.ts +192 -0
  33. package/dist/entity/metadata/schemaFixture/book.js +22 -0
  34. package/dist/http/query.js +12 -13
  35. package/dist/index.d.ts +2 -2
  36. package/dist/index.js +2 -1
  37. package/dist/mariadb/mariaDialect.js +1 -1
  38. package/dist/mariadb/mariadbQuerier.js +1 -3
  39. package/dist/migrate/builder/columnBuilder.d.ts +20 -68
  40. package/dist/migrate/builder/columnBuilder.js +104 -110
  41. package/dist/migrate/builder/migrationBuilder.d.ts +3 -3
  42. package/dist/migrate/builder/migrationBuilder.js +7 -6
  43. package/dist/migrate/builder/tableBuilder.d.ts +3 -55
  44. package/dist/migrate/builder/tableBuilder.js +88 -204
  45. package/dist/migrate/builder/types.d.ts +52 -151
  46. package/dist/migrate/builder/types.js +0 -6
  47. package/dist/migrate/codegen/entityCodeGenerator.d.ts +2 -2
  48. package/dist/migrate/codegen/entityCodeGenerator.js +24 -24
  49. package/dist/migrate/codegen/fieldOptionsSource.d.ts +3 -1
  50. package/dist/migrate/codegen/fieldOptionsSource.js +35 -34
  51. package/dist/migrate/codegen/indexEntrySource.d.ts +16 -0
  52. package/dist/migrate/codegen/{indexDecoratorSource.js → indexEntrySource.js} +54 -27
  53. package/dist/migrate/ddl/defaultSql.js +7 -6
  54. package/dist/migrate/ddl/indexCapabilities.d.ts +8 -7
  55. package/dist/migrate/ddl/indexCapabilities.js +26 -13
  56. package/dist/migrate/ddl/indexDdl.d.ts +13 -13
  57. package/dist/migrate/ddl/indexDdl.js +33 -30
  58. package/dist/migrate/ddl/mysqlIndexDdl.d.ts +6 -11
  59. package/dist/migrate/ddl/mysqlIndexDdl.js +17 -28
  60. package/dist/migrate/ddl/pgIndexDdl.d.ts +2 -2
  61. package/dist/migrate/ddl/sqliteIndexDdl.d.ts +2 -2
  62. package/dist/migrate/drift/driftDetector.js +2 -2
  63. package/dist/migrate/generator/definitionToNode.d.ts +8 -2
  64. package/dist/migrate/generator/definitionToNode.js +4 -5
  65. package/dist/migrate/introspection/abstractSqlSchemaIntrospector.js +11 -2
  66. package/dist/migrate/introspection/jsonIndexEntry.d.ts +6 -0
  67. package/dist/migrate/introspection/jsonIndexEntry.js +120 -0
  68. package/dist/migrate/introspection/mysqlIntrospector.d.ts +4 -4
  69. package/dist/migrate/introspection/mysqlIntrospector.js +25 -21
  70. package/dist/migrate/introspection/postgresIntrospector.d.ts +1 -1
  71. package/dist/migrate/introspection/postgresIntrospector.js +3 -4
  72. package/dist/migrate/introspection/sqliteIntrospector.js +24 -9
  73. package/dist/migrate/introspection/tableSchemaAST.js +5 -1
  74. package/dist/migrate/schemaChange.d.ts +3 -3
  75. package/dist/migrate/schemaChange.js +3 -2
  76. package/dist/migrate/schemaGenerator.js +1 -1
  77. package/dist/migrate/storage/databaseStorage.js +4 -4
  78. package/dist/mongodb/mongoDialect.d.ts +33 -36
  79. package/dist/mongodb/mongoDialect.js +118 -32
  80. package/dist/mongodb/mongoIntrospector.d.ts +3 -1
  81. package/dist/mongodb/mongoIntrospector.js +11 -5
  82. package/dist/mongodb/mongoSchemaGenerator.js +35 -27
  83. package/dist/mongodb/mongodbQuerier.d.ts +1 -11
  84. package/dist/mongodb/mongodbQuerier.js +9 -43
  85. package/dist/querier/abstractQuerier.d.ts +0 -1
  86. package/dist/querier/abstractQuerier.js +1 -20
  87. package/dist/querier/keyset.js +3 -3
  88. package/dist/schema/declaredColumn.d.ts +11 -0
  89. package/dist/schema/declaredColumn.js +21 -0
  90. package/dist/schema/indexColumns.d.ts +0 -3
  91. package/dist/schema/indexColumns.js +11 -7
  92. package/dist/schema/indexDifferences.d.ts +10 -5
  93. package/dist/schema/indexDifferences.js +42 -28
  94. package/dist/schema/schemaASTBuilder.js +28 -36
  95. package/dist/schema/schemaASTDiffer.js +8 -4
  96. package/dist/schema/sqlExpression.d.ts +21 -17
  97. package/dist/schema/sqlExpression.js +11 -23
  98. package/dist/type/column.d.ts +328 -0
  99. package/dist/type/column.js +2 -0
  100. package/dist/type/config.d.ts +1 -1
  101. package/dist/type/dialect.d.ts +2 -1
  102. package/dist/type/dialect.js +1 -0
  103. package/dist/type/entity.d.ts +290 -279
  104. package/dist/type/entity.js +6 -1
  105. package/dist/type/index.d.ts +2 -0
  106. package/dist/type/index.js +2 -0
  107. package/dist/type/migration.d.ts +5 -5
  108. package/dist/type/query.d.ts +44 -40
  109. package/dist/type/query.js +2 -3
  110. package/dist/type/queryAggregate.d.ts +22 -12
  111. package/dist/type/querySql.d.ts +20 -4
  112. package/dist/type/querySql.js +27 -9
  113. package/dist/type/schemaEntity.d.ts +190 -0
  114. package/dist/type/schemaEntity.js +1 -0
  115. package/dist/type/utility.d.ts +0 -6
  116. package/dist/type/vector.d.ts +1 -1
  117. package/dist/util/ddlExpression.util.d.ts +12 -13
  118. package/dist/util/ddlExpression.util.js +12 -21
  119. package/dist/util/dialect.util.d.ts +11 -5
  120. package/dist/util/dialect.util.js +31 -37
  121. package/dist/util/field.util.d.ts +10 -9
  122. package/dist/util/field.util.js +14 -10
  123. package/dist/util/fieldOption.util.d.ts +11 -95
  124. package/dist/util/fieldOption.util.js +49 -16
  125. package/dist/util/hook.util.d.ts +2 -14
  126. package/dist/util/hook.util.js +3 -16
  127. package/dist/util/index.d.ts +1 -0
  128. package/dist/util/index.js +1 -0
  129. package/dist/util/indexEntry.util.d.ts +45 -0
  130. package/dist/util/indexEntry.util.js +138 -0
  131. package/dist/util/relationQuery.util.d.ts +0 -1
  132. package/dist/util/relationQuery.util.js +0 -5
  133. package/dist/util/sql.d.ts +10 -7
  134. package/dist/util/sql.js +34 -16
  135. package/dist/util/sql.util.d.ts +4 -5
  136. package/dist/util/sql.util.js +7 -16
  137. package/dist/util/string.util.d.ts +2 -0
  138. package/dist/util/string.util.js +4 -0
  139. package/dist/util/uqlError.d.ts +1 -1
  140. package/dist/util/uqlError.js +1 -1
  141. package/package.json +1 -1
  142. package/skills/uql-orm/SKILL.md +76 -25
  143. package/dist/migrate/codegen/indexDecoratorSource.d.ts +0 -16
@@ -2,7 +2,7 @@ import { AGGREGATE_VALUE_ALIAS } from '../dialect/aliases.js';
2
2
  import { hasRequiredJoin } from '../dialect/queryJoins.js';
3
3
  import { getMeta, soleIdOf } from '../entity/index.js';
4
4
  import { AbstractQuerier } from '../querier/index.js';
5
- import { clone, getKeys, deletionOf, hasKeys, hasTriggers, populatesRelations, textSortOf, vectorCandidates, whereEach, upsertKeepsOwnKey, } from '../util/index.js';
5
+ import { clone, getKeys, deletionOf, hasKeys, hasTriggers, whereEach, upsertKeepsOwnKey } from '../util/index.js';
6
6
  import { UqlUsageError } from '../util/uqlError.js';
7
7
  /**
8
8
  * `$limit: 0` asks for no rows, the way it does on every SQL dialect - but MongoDB reads `limit(0)`
@@ -65,34 +65,16 @@ export class MongodbQuerier extends AbstractQuerier {
65
65
  * for a read and a stream alike, so both load the same relations.
66
66
  */
67
67
  readCursor(entity, q, opts, session) {
68
- const vectorSort = this.dialect.extractVectorSort(q.$sort);
69
- const pipeline = vectorSort
70
- ? this.buildVectorPipeline(entity, q, vectorSort, opts)
71
- : this.readsThroughPipeline(entity, q) && this.dialect.aggregationPipeline(entity, q, opts);
72
- return pipeline
73
- ? this.collection(entity).aggregate(pipeline, { session })
74
- : this.buildFindCursor(entity, q, opts, session);
75
- }
76
- /**
77
- * Whether a read needs stages a `find` cursor cannot express: a lookup to populate, count, filter or
78
- * order by a relation, one to build a relation aggregate, and the grouping `$distinct` is.
79
- */
80
- readsThroughPipeline(entity, q) {
81
- return (!!q.$distinct ||
82
- hasKeys(q.$count) ||
83
- populatesRelations(getMeta(entity), q.$populate) ||
84
- this.dialect.constrainsRelations(entity, q.$where) ||
85
- this.dialect.sortsRelations(entity, q.$sort) ||
86
- this.dialect.readsAggregates(entity, q) ||
87
- // A placement is a field the pipeline adds and orders by; a `find` cursor can add none.
88
- hasKeys(this.dialect.sortPlan(entity, q).fields) ||
89
- textSortOf(q.$sort) !== undefined);
68
+ const read = this.dialect.readPlan(entity, q, opts);
69
+ return 'pipeline' in read
70
+ ? this.collection(entity).aggregate(read.pipeline, { session })
71
+ : this.buildFindCursor(entity, q, read.sort, opts, session);
90
72
  }
91
73
  buildScalarProjection(entity, q) {
92
- return this.dialect.select(entity, q.$select, q.$exclude);
74
+ return this.dialect.select(entity, q.$select);
93
75
  }
94
- /** Build a MongoDB FindCursor with filter, projection, sort, skip, and limit from the query. */
95
- buildFindCursor(entity, q, opts, session) {
76
+ /** Build a MongoDB FindCursor with filter, projection, skip, and limit from the query, ordered by `sort`. */
77
+ buildFindCursor(entity, q, sort, opts, session) {
96
78
  const cursor = this.collection(entity).find({}, { session });
97
79
  const filter = this.dialect.where(entity, q.$where, opts);
98
80
  if (hasKeys(filter)) {
@@ -102,7 +84,6 @@ export class MongodbQuerier extends AbstractQuerier {
102
84
  if (hasKeys(select)) {
103
85
  cursor.project(select);
104
86
  }
105
- const sort = this.dialect.sort(entity, q);
106
87
  if (hasKeys(sort)) {
107
88
  cursor.sort(sort);
108
89
  }
@@ -115,21 +96,6 @@ export class MongodbQuerier extends AbstractQuerier {
115
96
  }
116
97
  return cursor;
117
98
  }
118
- /**
119
- * Build an aggregation pipeline for vector similarity search.
120
- * `$vectorSearch` is always the first stage; `$where` is merged into its `filter`.
121
- */
122
- buildVectorPipeline(entity, q, vectorSort, opts) {
123
- const scoreAlias = vectorSort.vectorSearch.$project;
124
- return [
125
- this.dialect.buildVectorSearchStage(entity, vectorSort.vectorKey, vectorSort.vectorSearch, q.$where, q.$limit ?? 10, opts, vectorCandidates(q)),
126
- // `$vectorSearch` has already applied `$limit`, so the pager is its own.
127
- ...this.dialect.readStages(entity, q, {
128
- sort: this.dialect.sortPlan(entity, { ...q, $sort: vectorSort.regularSort }),
129
- score: scoreAlias ? { field: scoreAlias, meta: 'vectorSearchScore' } : undefined,
130
- }),
131
- ];
132
- }
133
99
  async internalAggregate(entity, q, opts) {
134
100
  const pipeline = this.dialect.buildAggregateStages(entity, q, opts);
135
101
  const rows = await this.execute('internalAggregate', (session) => this.collection(entity).aggregate(pipeline, { session }).toArray());
@@ -266,7 +232,7 @@ export class MongodbQuerier extends AbstractQuerier {
266
232
  const { deletedCount } = await this.execute('internalDeleteMany', (session) => this.collection(entity).deleteMany(filter, { session }));
267
233
  return deletedCount;
268
234
  }
269
- // The mapped column, which reads filter on: a `@Field({ name })` mismatch would leave the row visible.
235
+ // The mapped column, which reads filter on: a `.name()` mismatch would leave the row visible.
270
236
  const column = this.dialect.resolveColumnName(stamp.key, stamp.field);
271
237
  const update = { $set: { [column]: stamp.value() } };
272
238
  const { matchedCount } = await this.execute('internalDeleteMany', (session) => this.collection(entity).updateMany(filter, update, { session }));
@@ -33,7 +33,6 @@ export declare abstract class AbstractQuerier implements Querier {
33
33
  * each backend's read, so the rule reaches a find, a stream and a paged count alike.
34
34
  */
35
35
  private assertLockable;
36
- private validateProjectionQueryRecursive;
37
36
  findOneById<E extends object, const Q extends QueryOne<E> = {}>(entity: Type<E>, id: EntityId<E>, q?: Captured<QueryOne<E>, Q>, opts?: QueryOptions): Promise<QueryFindResult<E, Q> | undefined>;
38
37
  /** Find one record, the entity passed first or as the query's `$entity`. */
39
38
  findOne<E extends object, const Q extends QueryOne<E> & {
@@ -2,7 +2,7 @@ import { getMeta, idOf, namesKey, relationOf } from '../entity/index.js';
2
2
  import { SAVEPOINT_PREFIX } from '../dialect/aliases.js';
3
3
  import { namesRows } from '../dialect/operators.js';
4
4
  import { parseQueryLock } from '../type/index.js';
5
- import { childrenExcept, childrenOf, chunk, clone, entityName, fillOnFields, filterFieldKeys, forEachRequestedRelation, getKeys, omitKeys, deletionOf, hasKeys, getRelationRequestSummary, guardWrite, idOnlyQuery, keyJoins, keySet, isPagedQuery, isScalarId, LoggerWrapper, normalizeScalarFieldSelection, parentJoins, pointAt, queryLoggerFor, parseRelationAtKey, parseRelationQueryValue, rowKey, runHooks, securityConditions, someKey, targetJoins, whereEach, whereIds, whereKeysIn, whereWith, withDeleted, cascadingRelations, holdsForeignKey, } from '../util/index.js';
5
+ import { childrenExcept, childrenOf, chunk, clone, entityName, fillOnFields, filterFieldKeys, getKeys, omitKeys, deletionOf, hasKeys, getRelationRequestSummary, guardWrite, idOnlyQuery, keyJoins, keySet, isPagedQuery, isScalarId, LoggerWrapper, normalizeScalarFieldSelection, parentJoins, pointAt, queryLoggerFor, parseRelationAtKey, rowKey, runHooks, securityConditions, someKey, targetJoins, whereEach, whereIds, whereKeysIn, whereWith, withDeleted, cascadingRelations, holdsForeignKey, } from '../util/index.js';
6
6
  import { UqlOptimisticLockError, UqlUsageError } from '../util/uqlError.js';
7
7
  import { keysetRead } from './keyset.js';
8
8
  import { enrichError } from './queryError.js';
@@ -208,7 +208,6 @@ export class AbstractQuerier {
208
208
  /** What every read is checked for before it runs, whichever backend runs it. */
209
209
  validateReadQuery(entity, q) {
210
210
  this.assertLockable(entity, q);
211
- this.validateProjectionQueryRecursive(entity, q, entityName(getMeta(entity)));
212
211
  }
213
212
  /**
214
213
  * Refuses a `$lock` the engine cannot take, then one outside a transaction, where the lock would
@@ -224,24 +223,6 @@ export class AbstractQuerier {
224
223
  throw new UqlUsageError('$lock requires an open transaction');
225
224
  }
226
225
  }
227
- validateProjectionQueryRecursive(entity, q, path) {
228
- const meta = getMeta(entity);
229
- if (q.$select && q.$exclude) {
230
- for (const [key, value] of Object.entries(q.$select)) {
231
- if (key in meta.fields && value) {
232
- throw new UqlUsageError(`Cannot combine $select and $exclude when $select includes positive scalar fields (${key}) at ${path}. Use either $select (whitelist) or $exclude (subtractive) in a single query.`);
233
- }
234
- }
235
- }
236
- forEachRequestedRelation(meta, q.$populate, (relKey, relValue) => {
237
- const relOpts = relationOf(meta, relKey);
238
- const relEntity = relOpts.entity();
239
- const parsed = parseRelationQueryValue(relValue);
240
- if (parsed.nested) {
241
- this.validateProjectionQueryRecursive(relEntity, parsed.query, `${path}.${relKey}`);
242
- }
243
- });
244
- }
245
226
  async findOneById(entity, id, q = {}, opts) {
246
227
  assertIdValue(entity, id);
247
228
  return this.findOne(entity, { ...q, $where: { ...q.$where, ...whereIds(getMeta(entity), id) } }, opts);
@@ -25,7 +25,7 @@ export function keysetRead(meta, q, nullsSortLowest) {
25
25
  const query = {
26
26
  ...rest,
27
27
  // Rewrite the projection as an explicit `$select` that adds the sort keys it left out, which the cursor needs.
28
- ...(carried.length > 0 && { $select: keySet([...projected, ...carried]), $exclude: undefined }),
28
+ ...(carried.length > 0 && { $select: keySet([...projected, ...carried]) }),
29
29
  $sort: backward ? sortOf(order.map(inverted).map((key) => [key.key, spelling(key)])) : rest.$sort,
30
30
  $where: cursor === undefined
31
31
  ? rest.$where
@@ -119,7 +119,7 @@ function totalPrefix(meta, order) {
119
119
  meta.ids,
120
120
  ...declaredIndexes(meta)
121
121
  .filter((index) => index.unique && !index.where)
122
- .map((index) => index.columns.map(({ column }) => column))
122
+ .map((index) => index.entries.map(({ column }) => column))
123
123
  .filter((columns) => columns.every((column) => typeof column === 'string' && notNull(column))),
124
124
  ].filter((columns) => columns.length > 0);
125
125
  const seen = new Set();
@@ -190,7 +190,7 @@ function projectedKeys(meta, q) {
190
190
  if (isSelectList(q.$select)) {
191
191
  throw new UqlUsageError(`a page of '${entityName(meta)}' selects fields, which its cursor is read off`);
192
192
  }
193
- return normalizeScalarFieldSelection(meta, q.$select, q.$exclude);
193
+ return normalizeScalarFieldSelection(meta, q.$select);
194
194
  }
195
195
  /** Hashes the entity and each sort key's direction and placement, so a cursor only works with the sort it came from. */
196
196
  function fingerprintOf(meta, order) {
@@ -0,0 +1,11 @@
1
+ import type { Except, FieldMeta, QuerySql } from '../type/index.js';
2
+ import type { ColumnNode } from './types.js';
3
+ /**
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.
6
+ */
7
+ export declare function declaredColumn(field: FieldMeta, { name, soleKey, compile, }: {
8
+ readonly name: string;
9
+ readonly soleKey: boolean;
10
+ readonly compile: (sql: QuerySql) => string;
11
+ }): Except<ColumnNode, 'table'>;
@@ -0,0 +1,21 @@
1
+ import { declaresNotNull, isAutoIncrement } from '../util/field.util.js';
2
+ import { resolveColumnCanonicalType } from './canonicalType.js';
3
+ import { schemaDefault } from './sqlExpression.js';
4
+ /**
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.
7
+ */
8
+ export function declaredColumn(field, { name, soleKey, compile, }) {
9
+ return {
10
+ name,
11
+ type: resolveColumnCanonicalType(field),
12
+ nullable: !declaresNotNull(field),
13
+ defaultValue: schemaDefault(field.defaultValue, compile),
14
+ isPrimaryKey: field.isId === true,
15
+ isAutoIncrement: isAutoIncrement(field, soleKey),
16
+ isUnique: field.unique ?? false,
17
+ // A stamp is filled by a trigger, so it is a column like any other; only `stored: true` generates.
18
+ generatedAs: field.stored === true && field.computed ? compile(field.computed) : undefined,
19
+ comment: field.comment,
20
+ };
21
+ }
@@ -1,9 +1,6 @@
1
- import type { IndexColumnSchema } from '../type/index.js';
2
1
  import type { ColumnNode, IndexNode } from './types.js';
3
2
  /** The table columns an index's entries resolve to, in order; an expression entry resolves to none. */
4
3
  export declare function indexColumns(index: IndexNode): ColumnNode[];
5
- /** Whether an entry is its column as stored, rather than an expression or a path the engine reprints in its own words. */
6
- export declare function isColumnEntry(entry: IndexColumnSchema): boolean;
7
4
  /**
8
5
  * The columns an index can look every row up by, in order, as far as its entries are whole columns: none
9
6
  * where it holds only some rows (partial) or is of a type an equality lookup does not read.
@@ -1,10 +1,7 @@
1
+ import { entryColumns, wholeColumn } from '../util/indexEntry.util.js';
1
2
  /** The table columns an index's entries resolve to, in order; an expression entry resolves to none. */
2
3
  export function indexColumns(index) {
3
- return index.entries.flatMap((entry) => (entry.expression ? [] : (index.table.columns.get(entry.column) ?? [])));
4
- }
5
- /** Whether an entry is its column as stored, rather than an expression or a path the engine reprints in its own words. */
6
- export function isColumnEntry(entry) {
7
- return !entry.expression && !entry.jsonPath && !entry.jsonArray;
4
+ return entryColumns(index.entries).flatMap((column) => index.table.columns.get(column) ?? []);
8
5
  }
9
6
  /** Whether an equality lookup reads each index type; the rest answer text, vector or range questions. Total, so a new type says. */
10
7
  const ANSWERS_LOOKUP = {
@@ -27,6 +24,13 @@ export function lookupColumns(index) {
27
24
  if (index.where !== undefined || !ANSWERS_LOOKUP[index.type ?? 'btree']) {
28
25
  return [];
29
26
  }
30
- const whole = index.entries.findIndex((entry) => !isColumnEntry(entry) || entry.length !== undefined);
31
- return index.entries.slice(0, whole === -1 ? undefined : whole).map((entry) => entry.column);
27
+ const columns = [];
28
+ for (const entry of index.entries) {
29
+ const column = wholeColumn(entry);
30
+ if (column === undefined) {
31
+ break;
32
+ }
33
+ columns.push(column);
34
+ }
35
+ return columns;
32
36
  }
@@ -1,5 +1,5 @@
1
1
  import type { IndexSchema } from '../type/index.js';
2
- import type { IndexNode } from './types.js';
2
+ import type { IndexNode, TableNode } from './types.js';
3
3
  /**
4
4
  * What an introspector reports about an index, and so all a diff may compare; apart from `IndexFeature`, what an engine emits.
5
5
  * `vector` is whether it is a vector index at all, for an engine with one vector index whatever type declared it;
@@ -39,12 +39,17 @@ export type IndexChange<I> = {
39
39
  readonly to: I;
40
40
  readonly description: string;
41
41
  };
42
+ /** The indexes `current` lacks, every one it has that none declared, and the ones to rebuild, as `facets` see them. */
43
+ export declare function pairedIndexChanges<I extends IndexSchema>(declared: readonly I[], current: readonly IndexNode[], facets: ReadonlySet<IndexFacet>): {
44
+ readonly created: I[];
45
+ readonly dropped: IndexNode[];
46
+ readonly rebuilt: IndexChange<I>[];
47
+ };
42
48
  /**
43
- * The indexes a table lacks, the ones it no longer needs, and the ones to rebuild, differing in what
44
- * `facets` let the engine report. Only an unpaired index uql named, or whose name the entity claims, is
45
- * dropped: any other may have been made outside the ORM, so it is `kept`.
49
+ * {@link pairedIndexChanges} on `table`, dropping only an unpaired index uql named, or whose name the entity
50
+ * claims: any other may have been made outside the ORM, so it is `kept`.
46
51
  */
47
- export declare function indexChanges<I extends IndexSchema>(table: string, declared: readonly I[], current: readonly IndexNode[], facets: ReadonlySet<IndexFacet>): {
52
+ export declare function indexChanges<I extends IndexSchema>(declared: readonly I[], table: Pick<TableNode, 'name' | 'indexes' | 'indexFacets'>): {
48
53
  changes: IndexChange<I>[];
49
54
  kept: IndexNode[];
50
55
  };
@@ -1,17 +1,15 @@
1
1
  import { indexDistance, isVectorIndexType } from '../type/vector.js';
2
+ import { declaredIndexName } from '../util/ddlExpression.util.js';
2
3
  import { fulltextConfig } from '../util/dialect.util.js';
3
- import { isDerivedIndexName } from '../util/sql.util.js';
4
- import { isColumnEntry } from './indexColumns.js';
4
+ import { indexEntryNamePart, isStored, storedColumns } from '../util/indexEntry.util.js';
5
+ import { NAME_HASH_LENGTH, TABLE_SEPARATOR } from '../util/sql.util.js';
5
6
  import { matchByKey } from './matchByKey.js';
6
7
  /**
7
8
  * Whether the table has this index already, by shape rather than name, uniqueness included. An index
8
9
  * over an expression, whose text the engine reprints, falls back to its name.
9
10
  */
10
11
  export function indexSignature(index) {
11
- const comparable = index.entries.every(isColumnEntry);
12
- const identity = comparable
13
- ? index.entries.map((entry) => entry.column).join(',')
14
- : `name:${indexNameStem(index.name)}`;
12
+ const identity = storedColumns(index.entries)?.join(',') ?? `name:${indexNameStem(index.name)}`;
15
13
  return `${index.unique ? 'unique' : 'plain'}(${identity})`;
16
14
  }
17
15
  /**
@@ -21,7 +19,7 @@ export function indexSignature(index) {
21
19
  export function indexNameStem(name) {
22
20
  const withoutSuffix = name.replace(KIND_SUFFIX, '');
23
21
  const bare = withoutSuffix === name ? name.replace(KIND_PREFIX, '') : withoutSuffix;
24
- return bare.replace(/__/g, '_');
22
+ return bare.replaceAll(TABLE_SEPARATOR, '_');
25
23
  }
26
24
  /**
27
25
  * Pairs by name, then what is left by shape: an index the database has under another name is still
@@ -44,33 +42,50 @@ function splitPartial(indexes) {
44
42
  partial: indexes.filter((index) => index.where !== undefined),
45
43
  };
46
44
  }
47
- /**
48
- * The indexes a table lacks, the ones it no longer needs, and the ones to rebuild, differing in what
49
- * `facets` let the engine report. Only an unpaired index uql named, or whose name the entity claims, is
50
- * dropped: any other may have been made outside the ORM, so it is `kept`.
51
- */
52
- export function indexChanges(table, declared, current, facets) {
45
+ /** The indexes `current` lacks, every one it has that none declared, and the ones to rebuild, as `facets` see them. */
46
+ export function pairedIndexChanges(declared, current, facets) {
53
47
  const { created, dropped, matched } = pairIndexes(declared, current);
54
- const claimed = new Set(declared.map((index) => index.name));
55
- const owned = (index) => claimed.has(index.name) || hasDerivedName(table, index);
56
48
  const rebuilt = matched.flatMap(([to, from]) => {
57
49
  const differences = describeIndexDifferences(to, from, facets);
58
50
  return differences.length ? [{ from, to, description: differences.join(', ') }] : [];
59
51
  });
52
+ return { created, dropped, rebuilt };
53
+ }
54
+ /**
55
+ * {@link pairedIndexChanges} on `table`, dropping only an unpaired index uql named, or whose name the entity
56
+ * claims: any other may have been made outside the ORM, so it is `kept`.
57
+ */
58
+ export function indexChanges(declared, table) {
59
+ const { created, dropped, rebuilt } = pairedIndexChanges(declared, table.indexes, table.indexFacets);
60
+ const claimed = new Set(declared.map((index) => index.name));
61
+ const isOwned = (index) => claimed.has(index.name) || hasDerivedName(table.name, index);
62
+ const { owned = [], kept = [] } = Object.groupBy(dropped, (index) => (isOwned(index) ? 'owned' : 'kept'));
60
63
  return {
61
- changes: [...created.map((to) => ({ to })), ...dropped.filter(owned).map((from) => ({ from })), ...rebuilt],
62
- kept: dropped.filter((index) => !owned(index)),
64
+ changes: [...created.map((to) => ({ to })), ...owned.map((from) => ({ from })), ...rebuilt],
65
+ kept,
63
66
  };
64
67
  }
65
68
  /**
66
- * Whether uql named the index itself, from its own columns: `Order__total_idx`, its unique `_uk`, or
67
- * `idx_Order_total`, which a database an older uql created holds.
69
+ * Whether uql named the index itself, from the entries the database reports: the name it would derive for them, with
70
+ * the predicate's hash read off the name and a unique one's `_uk` as the migration builder names it, or as an earlier
71
+ * uql derived it: `expr<n>` for a JSON path, or `idx_<table>_<parts>`.
68
72
  */
69
73
  function hasDerivedName(table, index) {
70
- const parts = index.entries.map((entry, at) => (isColumnEntry(entry) ? entry.column : `expr${at}`));
71
- return isDerivedIndexName(table, parts, index.name);
74
+ const name = index.where === undefined ? index.name : index.name.replace(PREDICATE_HASH, '');
75
+ const earlier = index.entries.map((entry) => entry.json === undefined ? entry : { expression: '' });
76
+ return [index.entries, earlier].some((entries) => {
77
+ const parts = entries.map(indexEntryNamePart);
78
+ return (name === declaredIndexName(undefined, table, entries) ||
79
+ (index.unique && name === declaredIndexName(undefined, table, entries, { unique: true })) ||
80
+ name === `idx_${table}_${parts.join('_')}`);
81
+ });
72
82
  }
73
- /** What this version emits. */
83
+ /** The hash a partial index's derived name carries before its kind. */
84
+ const PREDICATE_HASH = new RegExp(`_[0-9a-f]{${NAME_HASH_LENGTH}}(?=_(?:idx|uk)$)`);
85
+ /**
86
+ * The kind a name ends in: `pk`, `fk`, `idx` and `uk` are what uql derives, and `ck` and `uq` are read too, though
87
+ * no name it derives ends in them.
88
+ */
74
89
  const KIND_SUFFIX = /_(?:idx|fk|ck|pk|uk|uq)$/i;
75
90
  /**
76
91
  * What it only ever *reads*: a database an older uql created holds `idx_User_email`, and one it did not
@@ -85,12 +100,11 @@ const KIND_PREFIX = /^(?:idx|fk|ck|pk|uk|uq)_/i;
85
100
  */
86
101
  export function describeIndexDifferences(source, target, facets) {
87
102
  const differences = [];
88
- const comparableEntries = [...source.entries, ...target.entries].every(isColumnEntry);
89
- if (comparableEntries) {
90
- const [sourceColumns, targetColumns] = [source, target].map((index) => textFieldOrder(index, facets, index.entries.map((entry) => entrySignature(entry, facets))).join(', '));
91
- if (sourceColumns !== targetColumns) {
92
- differences.push(`columns: (${targetColumns}) -> (${sourceColumns})`);
93
- }
103
+ const [sourceColumns, targetColumns] = [source, target].map((index) => isStored(index.entries)
104
+ ? textFieldOrder(index, facets, index.entries.map((entry) => entrySignature(entry, facets))).join(', ')
105
+ : undefined);
106
+ if (sourceColumns !== undefined && targetColumns !== undefined && sourceColumns !== targetColumns) {
107
+ differences.push(`columns: (${targetColumns}) -> (${sourceColumns})`);
94
108
  }
95
109
  if (facets.has('textIndex') && source.type === 'fulltext' && target.type === 'fulltext') {
96
110
  const [expected, actual] = [fulltextConfig(source), fulltextConfig(target)];
@@ -1,14 +1,14 @@
1
1
  import { fieldOf, foreignKeysOf, getMeta } from '../entity/metadata/definition.js';
2
- import { declaredIndexes, declaredIndexName, enumCheck, ownedCheck, renderIndexColumn, } from '../util/ddlExpression.util.js';
2
+ import { declaredIndexes, namedIndex, enumCheck, ownedCheck } from '../util/ddlExpression.util.js';
3
3
  import { fulltextWeights, textWeightSteps } from '../util/dialect.util.js';
4
- import { declaresNotNull, isAutoIncrement, isInlinedExpression, isSoleIdField } from '../util/field.util.js';
4
+ import { isInlinedExpression, isSoleIdField } from '../util/field.util.js';
5
+ import { entryColumn, entryColumns, renamedEntry, renderIndexColumn } from '../util/indexEntry.util.js';
5
6
  import { definedEntries, entityName } from '../util/object.util.js';
6
7
  import { derivedForeignKeyName, derivedIndexName } from '../util/sql.util.js';
7
8
  import { UqlUsageError } from '../util/uqlError.js';
8
- import { resolveColumnCanonicalType } from './canonicalType.js';
9
+ import { declaredColumn } from './declaredColumn.js';
9
10
  import { lookupColumns } from './indexColumns.js';
10
11
  import { createTableNode, keyOfColumns, SchemaAST } from './schemaAST.js';
11
- import { schemaDefault } from './sqlExpression.js';
12
12
  import { DEFAULT_FOREIGN_KEY_ACTION, } from './types.js';
13
13
  /**
14
14
  * Build a SchemaAST from entity classes (decorated with `@Entity`, `@Field`, etc.).
@@ -46,11 +46,9 @@ export function buildSchemaAST(entities, options = {}) {
46
46
  function refuseDdl() {
47
47
  throw new UqlUsageError('building the schema of an entity that declares SQL (a check, a stored computed column, an index expression or predicate) needs a dialect to render it: pass `compileDdl`, as `SqlSchemaGenerator.buildAST` does');
48
48
  }
49
- /** The entries a vector index of `meta` covers: the members it names, and any expression. */
49
+ /** The members a vector index of `meta` covers by name. */
50
50
  function vectorIndexedEntries(meta) {
51
- return new Set((meta.indexes ?? [])
52
- .filter((index) => index.type === 'vector')
53
- .flatMap((index) => index.columns.map((entry) => entry.column)));
51
+ return new Set((meta.indexes ?? []).filter((index) => index.type === 'vector').flatMap((index) => entryColumns(index.entries)));
54
52
  }
55
53
  /**
56
54
  * Add a table from entity metadata.
@@ -67,20 +65,13 @@ function addTableFromEntity(ctx, meta) {
67
65
  if (isInlinedExpression(field))
68
66
  continue;
69
67
  const columnName = ctx.resolveColumnName(key, field);
70
- const type = resolveColumnCanonicalType(field);
71
- const isPrimaryKey = field.isId === true;
72
- const isSoleKey = isSoleIdField(meta, field);
73
68
  const column = {
74
- name: columnName,
75
- type,
76
- nullable: !declaresNotNull(field) && !notNull.has(key),
77
- defaultValue: schemaDefault(field.defaultValue, (sql) => ctx.compileDdl(sql, meta.entity)),
78
- isPrimaryKey,
79
- isAutoIncrement: isAutoIncrement(field, isSoleKey),
80
- isUnique: field.unique ?? false,
81
- // A stamp is filled by a trigger, so it is a column like any other; only `stored: true` generates.
82
- generatedAs: field.stored === true && field.computed ? ctx.compileDdl(field.computed, meta.entity) : undefined,
83
- comment: field.comment,
69
+ ...declaredColumn(field, {
70
+ name: columnName,
71
+ soleKey: isSoleIdField(meta, field),
72
+ compile: (sql) => ctx.compileDdl(sql, meta.entity),
73
+ }),
74
+ ...(notNull.has(key) && { nullable: false }),
84
75
  table,
85
76
  };
86
77
  columns.set(columnName, column);
@@ -93,7 +84,7 @@ function addTableFromEntity(ctx, meta) {
93
84
  }
94
85
  /**
95
86
  * Add a relationship for each foreign key the entity holds, whether a relation declares it or a bare
96
- * `@Field({ references })` does.
87
+ * `f.references()` does.
97
88
  */
98
89
  function addRelationshipsFromEntity(ctx, meta, table) {
99
90
  for (const foreignKey of foreignKeysOf(meta)) {
@@ -122,15 +113,15 @@ function addRelationshipsFromEntity(ctx, meta, table) {
122
113
  type: foreignKey.cardinality === 'm1' ? 'ManyToOne' : 'OneToOne',
123
114
  from: { table, columns: localColumns },
124
115
  to: { table: relatedTable, columns: foreignColumns },
125
- // Falls back to the FK column's own `onDelete`, which is what makes a bare `@Field({
126
- // references, onDelete })` work with no relation declared at all.
116
+ // Falls back to the FK column's own `onDelete`, which is what makes a bare
117
+ // `f.references(() => X).onDelete(...)` work with no relation declared at all.
127
118
  onDelete: foreignKey.onDelete ?? meta.fields[foreignKey.references[0].local]?.onDelete ?? ctx.defaultForeignKeyAction,
128
119
  onUpdate: foreignKey.onUpdate ?? ctx.defaultForeignKeyAction,
129
120
  });
130
121
  }
131
122
  }
132
123
  /**
133
- * Add indexes from field options (`@Field({ index })`), from `@Index`, and for every foreign
124
+ * Add indexes from field options (`.index()`), from `indexes`, and for every foreign
134
125
  * key none of those already serves.
135
126
  */
136
127
  function addIndexesFromEntity(ctx, meta, table) {
@@ -173,27 +164,27 @@ function fieldColumn(ctx, meta, key) {
173
164
  * names resolved, so the generator renders exactly what was declared. Every option not resolved here is
174
165
  * spread through, so an option added to indexes later cannot be lost.
175
166
  */
176
- function addCompositeIndex(ctx, table, meta, { columns, include, where, ...options }) {
167
+ function addCompositeIndex(ctx, table, meta, { entries, include, where, ...options }) {
177
168
  // An entry survives if it is an expression (nothing to resolve) or names a column that exists;
178
169
  // an index left with none is dropped, as one naming only unknown columns is.
179
- const resolved = columns.flatMap((entry) => {
180
- if (typeof entry.column !== 'string')
170
+ const resolved = entries.flatMap((entry) => {
171
+ const key = entryColumn(entry);
172
+ if (key === undefined)
181
173
  return [entry];
182
- const column = fieldColumn(ctx, meta, entry.column);
183
- return column && table.columns.has(column) ? [{ ...entry, column }] : [];
174
+ const column = fieldColumn(ctx, meta, key);
175
+ return column && table.columns.has(column) ? [renamedEntry(entry, () => column)] : [];
184
176
  });
185
177
  if (!resolved.length)
186
178
  return;
187
- const predicate = where && ctx.compileIndexPredicate(where, meta.entity, declaredIndexName(options.name, table.name, resolved));
179
+ const named = namedIndex(options.name, table.name, resolved, (label) => where && ctx.compileIndexPredicate(where, meta.entity, label));
188
180
  ctx.ast.addIndex({
189
181
  ...options,
190
- name: declaredIndexName(options.name, table.name, resolved, { where: predicate }),
182
+ ...named,
191
183
  table,
192
184
  entries: resolved.map((entry) => renderIndexColumn(entry, (sql) => ctx.compileDdl(sql, meta.entity))),
193
185
  // An `include` column is named like any other, so a custom naming has to reach it too.
194
186
  include: include?.map((column) => fieldColumn(ctx, meta, column) ?? column),
195
187
  unique: options.unique ?? false,
196
- where: predicate,
197
188
  });
198
189
  if (ctx.textScoreIndexes) {
199
190
  addTextScoreIndexes(ctx, table, options.type, resolved);
@@ -206,11 +197,12 @@ function addTextScoreIndexes(ctx, table, type, entries) {
206
197
  return;
207
198
  const { extra } = textWeightSteps(weights);
208
199
  entries.forEach((entry, at) => {
209
- if (extra[at] && typeof entry.column === 'string') {
200
+ const { column } = entry;
201
+ if (extra[at] && column !== undefined) {
210
202
  ctx.ast.addIndex({
211
- name: derivedIndexName(table.name, [entry.column, 'score']),
203
+ name: derivedIndexName(table.name, [column, 'score']),
212
204
  table,
213
- entries: [{ column: entry.column }],
205
+ entries: [{ column }],
214
206
  unique: false,
215
207
  type: 'fulltext',
216
208
  });
@@ -1,6 +1,6 @@
1
1
  import { isOwnedName, qualifyName } from '../util/sql.util.js';
2
2
  import { areTypesEqual, isBreakingTypeChange } from './canonicalType.js';
3
- import { indexChanges } from './indexDifferences.js';
3
+ import { pairedIndexChanges } from './indexDifferences.js';
4
4
  import { matchByKey, pairUnique } from './matchByKey.js';
5
5
  import { writtenDefault } from './sqlExpression.js';
6
6
  import { DEFAULT_FOREIGN_KEY_ACTION } from './types.js';
@@ -131,9 +131,13 @@ function matchTables(desired, actual, opts) {
131
131
  * name when there is one.
132
132
  */
133
133
  function diffTableIndexes(source, target) {
134
- const { changes, kept } = indexChanges(source.name, source.indexes, target.indexes, target.indexFacets);
135
- const drops = kept.map((from) => ({ from }));
136
- return [...changes, ...drops].map((change) => ({
134
+ const { created, dropped, rebuilt } = pairedIndexChanges(source.indexes, target.indexes, target.indexFacets);
135
+ const changes = [
136
+ ...created.map((to) => ({ to })),
137
+ ...rebuilt,
138
+ ...dropped.map((from) => ({ from })),
139
+ ];
140
+ return changes.map((change) => ({
137
141
  ...change,
138
142
  table: source.name,
139
143
  name: change.to === undefined ? change.from.name : change.to.name,
@@ -1,24 +1,27 @@
1
1
  import { QuerySql, type SqlValueName } from '../type/index.js';
2
+ declare const EXPRESSION: unique symbol;
2
3
  /**
3
- * The kind of a {@link SqlExpression}: a value uql exports by name, which `formatDefaultValue` spells for the
4
- * engine at DDL time, or `raw`, carrying its own SQL.
4
+ * A column default that is SQL rather than a literal: a value uql exports by name, which each engine spells for the
5
+ * column it fills, or raw SQL carrying its own text. Built by `SqlExpression`, branded by a symbol JSON cannot carry.
5
6
  */
6
- export type SqlExpressionKind = SqlValueName | 'sql';
7
- /**
8
- * A column default that is SQL rather than a literal, whether an entity or a migration declares it or
9
- * introspection reads it back. It is a class, not a plain object, so a JSON default cannot pass for one.
10
- */
11
- export declare class SqlExpression {
12
- readonly kind: SqlExpressionKind;
13
- readonly sql?: string | undefined;
14
- /** `sql` is set only for the `sql` kind, which carries its own text verbatim. */
15
- constructor(kind: SqlExpressionKind, sql?: string | undefined);
16
- static isExpression(value: unknown): value is SqlExpression;
7
+ export type SqlExpression = {
8
+ readonly [EXPRESSION]: true;
9
+ } & ({
10
+ readonly kind: SqlValueName;
11
+ readonly sql?: undefined;
12
+ } | {
13
+ readonly kind: 'sql';
14
+ readonly sql: string;
15
+ });
16
+ export declare const SqlExpression: {
17
+ named: (kind: SqlValueName) => SqlExpression;
18
+ raw: (sql: string) => SqlExpression;
17
19
  /** Wraps `sql` in parentheses, which every engine accepts for a default expression and SQLite and MySQL require. */
18
- static parenthesized(sql: string): SqlExpression;
19
- /** Its SQL, or its kind, as diffs and drift reports show it. */
20
- toString(): string;
21
- }
20
+ parenthesized: (sql: string) => SqlExpression;
21
+ isExpression: (value: unknown) => value is SqlExpression;
22
+ };
23
+ /** Its SQL, or its kind, as diffs and drift reports show it. */
24
+ export declare function sqlExpressionText(expression: SqlExpression): string;
22
25
  /**
23
26
  * A default in schema form: a value uql exports (`currentTimestamp`) becomes its kind, so each engine spells it
24
27
  * for the column it fills; other `raw` becomes the SQL `compile` renders, parenthesized; a literal is kept.
@@ -29,3 +32,4 @@ export declare function schemaDefault(value: unknown, compile: (sql: QuerySql) =
29
32
  * holding a JSON object or list as JSON with its keys in order, equal as documents, since `jsonb` reprints them.
30
33
  */
31
34
  export declare function writtenDefault(value: unknown): string;
35
+ export {};