uql-orm 0.104.1 → 0.105.1

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 (161) hide show
  1. package/README.md +24 -10
  2. package/dist/browser/querier/httpQuerier.d.ts +3 -3
  3. package/dist/browser/type/clientQuerier.d.ts +1 -1
  4. package/dist/browser/uql-browser.min.js +2 -2
  5. package/dist/browser/uql-browser.min.js.map +9 -9
  6. package/dist/cockroachdb/cockroachDialect.d.ts +2 -2
  7. package/dist/dialect/abstractDialect.d.ts +3 -3
  8. package/dist/dialect/abstractSqlDialect.d.ts +39 -37
  9. package/dist/dialect/abstractSqlDialect.js +35 -32
  10. package/dist/dialect/aliases.d.ts +2 -0
  11. package/dist/dialect/aliases.js +2 -0
  12. package/dist/dialect/jsonSql.js +2 -2
  13. package/dist/dialect/mergeSqlDialect.d.ts +2 -2
  14. package/dist/dialect/mysqlLikeSqlDialect.d.ts +7 -7
  15. package/dist/dialect/mysqlLikeSqlDialect.js +1 -1
  16. package/dist/dialect/operators.js +2 -4
  17. package/dist/dialect/queryJoins.d.ts +4 -2
  18. package/dist/dialect/vectorSqlDialect.d.ts +1 -1
  19. package/dist/dialect/vectorSqlDialect.js +1 -1
  20. package/dist/entity/column.d.ts +3 -0
  21. package/dist/entity/column.js +3 -0
  22. package/dist/entity/columnOptionsBuilder.d.ts +54 -0
  23. package/dist/entity/columnOptionsBuilder.js +108 -0
  24. package/dist/entity/decorator/bag.d.ts +5 -5
  25. package/dist/entity/decorator/entity.d.ts +3 -20
  26. package/dist/entity/decorator/entity.js +3 -37
  27. package/dist/entity/decorator/members.d.ts +46 -76
  28. package/dist/entity/decorator/members.js +18 -7
  29. package/dist/entity/index.d.ts +2 -1
  30. package/dist/entity/index.js +2 -1
  31. package/dist/entity/metadata/definition.d.ts +15 -26
  32. package/dist/entity/metadata/definition.js +344 -148
  33. package/dist/entity/metadata/schemaFixture/animal.d.ts +54 -0
  34. package/dist/entity/metadata/schemaFixture/animal.js +7 -0
  35. package/dist/entity/metadata/schemaFixture/author.d.ts +140 -0
  36. package/dist/entity/metadata/schemaFixture/author.js +25 -0
  37. package/dist/entity/metadata/schemaFixture/book.d.ts +192 -0
  38. package/dist/entity/metadata/schemaFixture/book.js +23 -0
  39. package/dist/http/contract.d.ts +2 -2
  40. package/dist/http/handler.d.ts +2 -2
  41. package/dist/http/query.js +12 -13
  42. package/dist/index.d.ts +2 -2
  43. package/dist/index.js +2 -1
  44. package/dist/mariadb/mariaDialect.d.ts +2 -2
  45. package/dist/mariadb/mariaDialect.js +1 -1
  46. package/dist/mariadb/mariadbQuerier.js +1 -3
  47. package/dist/migrate/builder/columnBuilder.d.ts +20 -68
  48. package/dist/migrate/builder/columnBuilder.js +104 -110
  49. package/dist/migrate/builder/migrationBuilder.d.ts +3 -3
  50. package/dist/migrate/builder/migrationBuilder.js +7 -6
  51. package/dist/migrate/builder/tableBuilder.d.ts +3 -55
  52. package/dist/migrate/builder/tableBuilder.js +88 -204
  53. package/dist/migrate/builder/types.d.ts +52 -151
  54. package/dist/migrate/builder/types.js +0 -6
  55. package/dist/migrate/codegen/entityCodeGenerator.d.ts +2 -2
  56. package/dist/migrate/codegen/entityCodeGenerator.js +24 -24
  57. package/dist/migrate/codegen/entityTypes.d.ts +2 -2
  58. package/dist/migrate/codegen/fieldOptionsSource.d.ts +3 -1
  59. package/dist/migrate/codegen/fieldOptionsSource.js +35 -34
  60. package/dist/migrate/codegen/indexEntrySource.d.ts +16 -0
  61. package/dist/migrate/codegen/{indexDecoratorSource.js → indexEntrySource.js} +54 -27
  62. package/dist/migrate/ddl/defaultSql.js +7 -6
  63. package/dist/migrate/ddl/indexCapabilities.d.ts +8 -7
  64. package/dist/migrate/ddl/indexCapabilities.js +26 -13
  65. package/dist/migrate/ddl/indexDdl.d.ts +13 -13
  66. package/dist/migrate/ddl/indexDdl.js +33 -30
  67. package/dist/migrate/ddl/mysqlIndexDdl.d.ts +6 -11
  68. package/dist/migrate/ddl/mysqlIndexDdl.js +17 -28
  69. package/dist/migrate/ddl/pgIndexDdl.d.ts +2 -2
  70. package/dist/migrate/ddl/sqliteIndexDdl.d.ts +2 -2
  71. package/dist/migrate/drift/driftDetector.js +2 -2
  72. package/dist/migrate/generator/definitionToNode.d.ts +8 -2
  73. package/dist/migrate/generator/definitionToNode.js +4 -5
  74. package/dist/migrate/introspection/abstractSqlSchemaIntrospector.js +11 -2
  75. package/dist/migrate/introspection/jsonIndexEntry.d.ts +6 -0
  76. package/dist/migrate/introspection/jsonIndexEntry.js +120 -0
  77. package/dist/migrate/introspection/mysqlIntrospector.d.ts +4 -4
  78. package/dist/migrate/introspection/mysqlIntrospector.js +25 -21
  79. package/dist/migrate/introspection/postgresIntrospector.d.ts +1 -1
  80. package/dist/migrate/introspection/postgresIntrospector.js +3 -4
  81. package/dist/migrate/introspection/sqliteIntrospector.js +24 -9
  82. package/dist/migrate/introspection/tableSchemaAST.js +5 -1
  83. package/dist/migrate/migrator.d.ts +2 -2
  84. package/dist/migrate/schemaChange.d.ts +3 -3
  85. package/dist/migrate/schemaChange.js +3 -2
  86. package/dist/migrate/schemaGenerator.d.ts +5 -5
  87. package/dist/migrate/schemaGenerator.js +1 -1
  88. package/dist/migrate/storage/databaseStorage.js +4 -4
  89. package/dist/mongodb/mongoDialect.d.ts +41 -44
  90. package/dist/mongodb/mongoDialect.js +118 -32
  91. package/dist/mongodb/mongoIntrospector.d.ts +3 -1
  92. package/dist/mongodb/mongoIntrospector.js +11 -5
  93. package/dist/mongodb/mongoSchemaGenerator.d.ts +4 -4
  94. package/dist/mongodb/mongoSchemaGenerator.js +35 -27
  95. package/dist/mongodb/mongodbQuerier.d.ts +1 -11
  96. package/dist/mongodb/mongodbQuerier.js +9 -43
  97. package/dist/mssql/mssqlDialect.d.ts +4 -4
  98. package/dist/postgres/postgresDialect.d.ts +2 -2
  99. package/dist/querier/abstractQuerier.d.ts +0 -1
  100. package/dist/querier/abstractQuerier.js +1 -20
  101. package/dist/querier/abstractSqlQuerier.d.ts +1 -1
  102. package/dist/querier/keyset.js +3 -3
  103. package/dist/schema/declaredColumn.d.ts +11 -0
  104. package/dist/schema/declaredColumn.js +21 -0
  105. package/dist/schema/indexColumns.d.ts +0 -3
  106. package/dist/schema/indexColumns.js +11 -7
  107. package/dist/schema/indexDifferences.d.ts +10 -5
  108. package/dist/schema/indexDifferences.js +42 -28
  109. package/dist/schema/schemaASTBuilder.d.ts +4 -4
  110. package/dist/schema/schemaASTBuilder.js +28 -36
  111. package/dist/schema/schemaASTDiffer.js +8 -4
  112. package/dist/schema/sqlExpression.d.ts +21 -17
  113. package/dist/schema/sqlExpression.js +11 -23
  114. package/dist/type/column.d.ts +328 -0
  115. package/dist/type/column.js +2 -0
  116. package/dist/type/config.d.ts +3 -3
  117. package/dist/type/dialect.d.ts +15 -14
  118. package/dist/type/dialect.js +1 -0
  119. package/dist/type/entity.d.ts +292 -281
  120. package/dist/type/entity.js +6 -1
  121. package/dist/type/index.d.ts +2 -0
  122. package/dist/type/index.js +2 -0
  123. package/dist/type/migration.d.ts +11 -11
  124. package/dist/type/querier.d.ts +2 -2
  125. package/dist/type/query.d.ts +44 -40
  126. package/dist/type/query.js +2 -3
  127. package/dist/type/queryAggregate.d.ts +22 -12
  128. package/dist/type/querySql.d.ts +22 -6
  129. package/dist/type/querySql.js +27 -9
  130. package/dist/type/schemaEntity.d.ts +194 -0
  131. package/dist/type/schemaEntity.js +1 -0
  132. package/dist/type/utility.d.ts +4 -7
  133. package/dist/type/vector.d.ts +1 -1
  134. package/dist/util/ddlExpression.util.d.ts +12 -13
  135. package/dist/util/ddlExpression.util.js +12 -21
  136. package/dist/util/dialect.util.d.ts +11 -5
  137. package/dist/util/dialect.util.js +31 -37
  138. package/dist/util/field.util.d.ts +10 -9
  139. package/dist/util/field.util.js +14 -10
  140. package/dist/util/fieldOption.util.d.ts +11 -95
  141. package/dist/util/fieldOption.util.js +49 -16
  142. package/dist/util/hook.util.d.ts +3 -15
  143. package/dist/util/hook.util.js +3 -16
  144. package/dist/util/index.d.ts +1 -0
  145. package/dist/util/index.js +1 -0
  146. package/dist/util/indexEntry.util.d.ts +45 -0
  147. package/dist/util/indexEntry.util.js +138 -0
  148. package/dist/util/relationQuery.util.d.ts +0 -1
  149. package/dist/util/relationQuery.util.js +0 -5
  150. package/dist/util/sql.d.ts +13 -10
  151. package/dist/util/sql.js +34 -16
  152. package/dist/util/sql.util.d.ts +4 -5
  153. package/dist/util/sql.util.js +7 -16
  154. package/dist/util/string.util.d.ts +2 -0
  155. package/dist/util/string.util.js +4 -0
  156. package/dist/util/triggerWrite.d.ts +5 -5
  157. package/dist/util/uqlError.d.ts +1 -1
  158. package/dist/util/uqlError.js +1 -1
  159. package/package.json +1 -1
  160. package/skills/uql-orm/SKILL.md +76 -25
  161. package/dist/migrate/codegen/indexDecoratorSource.d.ts +0 -16
@@ -118,7 +118,7 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
118
118
  *
119
119
  * The key's index and an `EXCLUDE`'s are left out. A `UNIQUE` constraint's index stays, as SQL Server
120
120
  * and the MySQL family report theirs: the diff reads one over a single column as that column's
121
- * uniqueness, and one over several as the unique `@Index` it is.
121
+ * uniqueness, and one over several as the unique index it is.
122
122
  */
123
123
  async getIndexes(read, tableName) {
124
124
  const rows = await read(sql `
@@ -230,7 +230,7 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
230
230
  return index;
231
231
  }
232
232
  const opsClass = index.entries.find((entry) => entry.opsClass)?.opsClass;
233
- const distance = this.dialect.indexedDistance(opsClass ? /_([a-z0-9]+)_ops$/.exec(opsClass)?.[1] : 'l2');
233
+ const distance = this.dialect.distanceOfMetric(opsClass ? /_([a-z0-9]+)_ops$/.exec(opsClass)?.[1] : 'l2');
234
234
  const entries = index.entries.map(({ opsClass: _opsClass, ...entry }) => entry);
235
235
  return distance ? { ...index, distance, entries } : index;
236
236
  }
@@ -315,8 +315,7 @@ const TEXT_INDEX_METHODS = new Set(['gin', 'inverted']);
315
315
  */
316
316
  function mapIndexEntry(row) {
317
317
  return {
318
- column: row.entry,
319
- ...(row.is_expression && { expression: true }),
318
+ ...(row.is_expression ? { expression: row.entry } : { column: row.entry }),
320
319
  order: row.descending ? 'desc' : 'asc',
321
320
  ...(row.nulls_first !== null && { nulls: row.nulls_first ? 'first' : 'last' }),
322
321
  ...(row.ops_class && { opsClass: row.ops_class }),
@@ -61,9 +61,10 @@ export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
61
61
  // The key's own index ('pk') is left out; a unique constraint's ('u') is reported as every engine reports one.
62
62
  for (const index of list.filter((it) => it.origin !== 'pk')) {
63
63
  const sql = statements.get(index.name) ?? '';
64
- // `PRAGMA index_info` names an expression entry `null`, its text kept only in `sqlite_master.sql`: it is
65
- // reported as the expression it is, as MySQL reports one, and libSQL's vector index is read off that text.
66
- const entries = (await this.getIndexColumns(read, index.name)).map(({ name }) => name === null ? { column: '', expression: true } : { column: name });
64
+ // `PRAGMA index_info` names an expression entry `null`, its text kept only in `sqlite_master.sql`, which is
65
+ // where it is read from, as libSQL's vector index is.
66
+ const written = indexEntries(sql);
67
+ const entries = (await this.getIndexColumns(read, index.name)).map(({ name }, at) => name === null ? { expression: written[at] ?? '' } : { column: name });
67
68
  indexes.push(this.vectorIndex(index.name, sql) ?? {
68
69
  name: index.name,
69
70
  entries,
@@ -110,7 +111,7 @@ export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
110
111
  entries: [{ column }],
111
112
  unique: false,
112
113
  type: 'vector',
113
- distance: this.dialect.indexedDistance(metric),
114
+ distance: this.dialect.distanceOfMetric(metric),
114
115
  };
115
116
  }
116
117
  getIndexColumns(read, indexName) {
@@ -170,16 +171,30 @@ export function generatedExpression(ddl, column) {
170
171
  }
171
172
  /** A `CREATE TABLE` body split at each comma outside any parentheses or quotes: one entry per column or constraint. */
172
173
  function tableEntries(ddl) {
173
- const body = ddl.slice(ddl.indexOf('(') + 1, ddl.lastIndexOf(')'));
174
- const entries = [];
174
+ return topLevelParts(ddl.slice(ddl.indexOf('(') + 1, ddl.lastIndexOf(')')));
175
+ }
176
+ /** A `CREATE INDEX` statement's entries as written, each without its order. */
177
+ function indexEntries(ddl) {
178
+ let open = -1;
179
+ scan(ddl, (char, index) => {
180
+ open = char === '(' ? index : open;
181
+ return open >= 0;
182
+ });
183
+ return open < 0
184
+ ? []
185
+ : topLevelParts(parenthesized(ddl.slice(open))).map((entry) => entry.replace(/\s+(?:ASC|DESC)$/i, ''));
186
+ }
187
+ /** `text` split at each comma outside any parentheses or quotes, each part trimmed. */
188
+ function topLevelParts(text) {
189
+ const parts = [];
175
190
  let start = 0;
176
- scan(body, (char, index, depth) => {
191
+ scan(text, (char, index, depth) => {
177
192
  if (char === ',' && depth === 0) {
178
- entries.push(body.slice(start, index));
193
+ parts.push(text.slice(start, index));
179
194
  start = index + 1;
180
195
  }
181
196
  });
182
- return [...entries, body.slice(start)];
197
+ return [...parts, text.slice(start)].map((part) => part.trim());
183
198
  }
184
199
  /** A partial index's predicate: what follows `WHERE` after its column list, as the statement gave it. */
185
200
  function indexPredicate(sql) {
@@ -1,6 +1,7 @@
1
1
  import { storedType } from '../../schema/canonicalType.js';
2
2
  import { createTableNode, SchemaAST } from '../../schema/schemaAST.js';
3
3
  import { DEFAULT_FOREIGN_KEY_ACTION, } from '../../schema/types.js';
4
+ import { entryColumn } from '../../util/indexEntry.util.js';
4
5
  import { derivedForeignKeyName, qualifyName } from '../../util/sql.util.js';
5
6
  import { renameIndexEntries } from '../schemaChange.js';
6
7
  /** The tables an introspector read, as a {@link SchemaAST}: every table first, so a foreign key reaches one read after it. */
@@ -77,7 +78,10 @@ function addRelationships(ast, nodes, schema, fromTable) {
77
78
  /** An expression has no column to resolve; an entry naming a column the table lacks is dropped, as the entity side does. */
78
79
  function addIndexes(ast, schema, table) {
79
80
  for (const index of schema.indexes ?? []) {
80
- const entries = index.entries.filter((entry) => entry.expression || table.columns.has(entry.column));
81
+ const entries = index.entries.filter((entry) => {
82
+ const column = entryColumn(entry);
83
+ return column === undefined || table.columns.has(column);
84
+ });
81
85
  if (entries.length > 0) {
82
86
  ast.addIndex({ ...index, table, entries });
83
87
  }
@@ -1,4 +1,4 @@
1
- import type { MigrationDefinition, MigrationResult, MigratorDialect, MigratorOptions, Querier, QuerierPool, SchemaDiff, SchemaGenerator, SchemaIntrospector, SqlQuerier, SyncOptions, Type } from '../type/index.js';
1
+ import type { MigrationDefinition, MigrationResult, MigratorDialect, MigratorOptions, Querier, QuerierPool, SchemaDiff, SchemaGenerator, SchemaIntrospector, SqlQuerier, SyncOptions, AbstractType } from '../type/index.js';
2
2
  import { LoggerWrapper } from '../util/index.js';
3
3
  import type { MigrationBuilder } from './builder/types.js';
4
4
  /**
@@ -9,7 +9,7 @@ export declare class Migrator {
9
9
  readonly migrationsPath: string;
10
10
  readonly logger: LoggerWrapper;
11
11
  private readonly _entities?;
12
- get entities(): Type<object>[];
12
+ get entities(): AbstractType<object>[];
13
13
  /** The generator given, or this dialect's once {@link getSchemaGenerator} has loaded it. */
14
14
  schemaGenerator?: SchemaGenerator;
15
15
  schemaIntrospector: SchemaIntrospector;
@@ -1,4 +1,4 @@
1
- import type { Alteration, Change, ColumnSchema, IndexColumnSchema, SchemaDiff } from '../type/index.js';
1
+ import type { Alteration, Change, ColumnSchema, IndexEntry, SchemaDiff } from '../type/index.js';
2
2
  /** Each change's end on `side`, where it has one: what a drop half removes (`from`), or an add half creates (`to`). */
3
3
  export declare function sides<T>(changes: readonly Change<T>[] | undefined, side: 'from' | 'to'): T[];
4
4
  /** What the changes add: each `to` with no `from`. */
@@ -35,5 +35,5 @@ export declare function nonEmpty<T>(items: readonly T[]): readonly T[] | undefin
35
35
  * either way, so a key, index or foreign key put back names a renamed column as the rename back leaves it.
36
36
  */
37
37
  export declare function reverseDiff(diff: SchemaDiff): SchemaDiff;
38
- /** Each column entry named by `nameOf`; an expression entry is SQL, left as written. */
39
- export declare function renameIndexEntries(entries: readonly IndexColumnSchema[], nameOf: (column: string) => string): IndexColumnSchema[];
38
+ /** Each entry's column named by `nameOf`; an expression entry is SQL, left as written. */
39
+ export declare function renameIndexEntries(entries: readonly IndexEntry<string>[], nameOf: (column: string) => string): IndexEntry<string>[];
@@ -1,3 +1,4 @@
1
+ import { renamedEntry } from '../util/indexEntry.util.js';
1
2
  /** Each change's end on `side`, where it has one: what a drop half removes (`from`), or an add half creates (`to`). */
2
3
  export function sides(changes, side) {
3
4
  return (changes ?? []).flatMap((change) => {
@@ -93,7 +94,7 @@ export function reverseDiff(diff) {
93
94
  function putBack({ from, to }, restore) {
94
95
  return { from: to, to: from && restore(from) };
95
96
  }
96
- /** Each column entry named by `nameOf`; an expression entry is SQL, left as written. */
97
+ /** Each entry's column named by `nameOf`; an expression entry is SQL, left as written. */
97
98
  export function renameIndexEntries(entries, nameOf) {
98
- return entries.map((entry) => (entry.expression ? entry : { ...entry, column: nameOf(entry.column) }));
99
+ return entries.map((entry) => renamedEntry(entry, nameOf));
99
100
  }
@@ -2,7 +2,7 @@ import type { AbstractSqlDialect } from '../dialect/index.js';
2
2
  import type { SchemaAST } from '../schema/schemaAST.js';
3
3
  import { type DiffOptions } from '../schema/schemaASTDiffer.js';
4
4
  import { type ForeignKeyAction, type TableNode } from '../schema/types.js';
5
- import type { CreateSchemaOptions, DialectFeatures, DropSchemaOptions, ForeignKeySchema, Rename, SchemaDiff, SchemaGenerator, Type } from '../type/index.js';
5
+ import type { CreateSchemaOptions, DialectFeatures, DropSchemaOptions, ForeignKeySchema, Rename, SchemaDiff, SchemaGenerator, AbstractType } from '../type/index.js';
6
6
  import type { AnyMigrationOperation, TableDefinition } from './builder/types.js';
7
7
  import { type IndexDdl, type TableDdl } from './ddl/index.js';
8
8
  /** The SQL schema generator, one for every SQL engine, its spellings taken from the dialect and its DDL classes. */
@@ -26,12 +26,12 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
26
26
  * The entity side as an AST, carrying this generator's default referential action. Named by the dialect's
27
27
  * resolvers rather than a naming strategy, which would also rename an explicit `@Entity({ name })`.
28
28
  */
29
- buildAST(entities: readonly Type<object>[]): SchemaAST;
29
+ buildAST(entities: readonly AbstractType<object>[]): SchemaAST;
30
30
  /**
31
31
  * Every `CREATE TABLE` for `entities`, then their foreign keys, since a relation graph is routinely
32
32
  * cyclic. SQLite keeps them inline: it cannot add one later, and resolves a forward reference lazily.
33
33
  */
34
- generateCreateSchema(entities: readonly Type<object>[], options?: CreateSchemaOptions): string[];
34
+ generateCreateSchema(entities: readonly AbstractType<object>[], options?: CreateSchemaOptions): string[];
35
35
  /**
36
36
  * One statement per distinct schema the tables being created live in, in first-seen order. Only
37
37
  * the tables actually being created, so a narrowed `only` does not declare namespaces it is not
@@ -42,7 +42,7 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
42
42
  * The inverse of {@link generateCreateSchema}: a table's drop takes its triggers along, so only what they
43
43
  * leave behind follows it.
44
44
  */
45
- generateDropSchema(entities: readonly Type<object>[], options?: DropSchemaOptions): string[];
45
+ generateDropSchema(entities: readonly AbstractType<object>[], options?: DropSchemaOptions): string[];
46
46
  /**
47
47
  * The tables of `entities` in dependency order, optionally narrowed to `only`. The AST always spans
48
48
  * every entity even when narrowed, so a relation pointing at a table outside the subset still
@@ -78,7 +78,7 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
78
78
  * How the entity differs from the table the database reported, compared by {@link diffTable}, the one
79
79
  * drift detection runs, with types normalized as the engine stores them.
80
80
  */
81
- diffSchema(entity: Type<object>, currentTable: TableNode | undefined, desiredAst?: SchemaAST, renamedColumns?: readonly Rename[]): SchemaDiff | undefined;
81
+ diffSchema(entity: AbstractType<object>, currentTable: TableNode | undefined, desiredAst?: SchemaAST, renamedColumns?: readonly Rename[]): SchemaDiff | undefined;
82
82
  /**
83
83
  * Both ends of rebuilding `actual` as `desired`. The new table is the entity's, keeping what it cannot
84
84
  * know of: the indexes, checks and triggers uql did not make, and foreign keys to tables no entity names.
@@ -246,7 +246,7 @@ export class SqlSchemaGenerator {
246
246
  return undefined;
247
247
  }
248
248
  const tableDiff = diffTable(desired, currentTable, this.diffOptions());
249
- const indexes = indexChanges(currentTable.name, desired.indexes, currentTable.indexes, currentTable.indexFacets);
249
+ const indexes = indexChanges(desired.indexes, currentTable);
250
250
  const columns = (tableDiff?.columns ?? []).map(({ from, to, isBreaking }) => ({
251
251
  from: from && this.columnNodeToSchema(from),
252
252
  to: to && this.columnNodeToSchema(to),
@@ -1,5 +1,5 @@
1
1
  import { currentTimestamp, sql } from '../../util/sql.js';
2
- import { TableDefinitionBuilder } from '../builder/tableBuilder.js';
2
+ import { tableBuilder } from '../builder/tableBuilder.js';
3
3
  import { SqlSchemaGenerator } from '../schemaGenerator.js';
4
4
  /** Where executed migrations are recorded when the config does not name a table. */
5
5
  export const DEFAULT_MIGRATIONS_TABLE = 'uql_migrations';
@@ -14,9 +14,9 @@ export const LOCK_RECORD = 'uql/lock';
14
14
  * default. Run under the migration lock, so two runs never race to create it.
15
15
  */
16
16
  export async function createMigrationsTable(querier, tableName) {
17
- const table = new TableDefinitionBuilder(tableName);
18
- table.string('name', { length: 255, primaryKey: true });
19
- table.timestamptz('executed_at', { defaultValue: currentTimestamp });
17
+ const table = tableBuilder(tableName);
18
+ table.string('name').id();
19
+ table.timestamptz('executed_at').default(currentTimestamp);
20
20
  const generator = new SqlSchemaGenerator(querier.dialect);
21
21
  for (const statement of generator.generateCreateTableFromDefinition(table.build(), { ifNotExists: true })) {
22
22
  await querier.run(sql.text(statement));
@@ -1,28 +1,12 @@
1
1
  import { type Document, type Filter, type Sort } from 'mongodb';
2
2
  import { AbstractDialect } from '../dialect/abstractDialect.js';
3
- import type { DialectFeatures, EntityData, EntityMeta, Query, QueryAggregate, QueryExclude, QueryOptions, QueryPager, QuerySelectValue, QuerySortMap, QueryVectorSearch, QueryWhere, Type } from '../type/index.js';
3
+ import type { DialectFeatures, EntityData, EntityMeta, Query, QueryAggregate, QueryOptions, QueryPager, QuerySelectValue, QuerySortMap, QueryWhere, AbstractType } from '../type/index.js';
4
4
  import { type CallbackKey } from '../util/index.js';
5
- /**
6
- * An ordering as the pipeline runs it: the `$sort`, the fields it needs on the document first - a
7
- * placement's null flags - and the ones to take back off after it. One object, so a caller cannot
8
- * order by a field it forgot to add, or leave one behind in the rows it answers with.
9
- */
10
- export type MongoSortPlan = {
5
+ /** How a read runs: its pipeline, or the ordering of the `find` cursor where one expresses it. */
6
+ export type MongoRead = {
7
+ readonly pipeline: MongoAggregationPipelineEntry<Document>[];
8
+ } | {
11
9
  readonly sort: Sort;
12
- readonly stages: MongoAggregationPipelineEntry<Document>[];
13
- readonly fields: string[];
14
- };
15
- /** What a read pipeline contributes to {@link MongoDialect.readStages} beyond the query itself. */
16
- type MongoReadStages = {
17
- /** Ordering, which runs after the lookups when it reads one of their fields. */
18
- readonly sort: MongoSortPlan;
19
- readonly pager?: MongoAggregationPipelineEntry<Document>[];
20
- /** A score the read answers as a field, a vector search's or a text search's; a temporary one leaves again. */
21
- readonly score?: {
22
- readonly field: string;
23
- readonly meta: 'vectorSearchScore' | 'textScore';
24
- readonly temporary?: boolean;
25
- };
26
10
  };
27
11
  /** Lookup stages, and the temp fields they fill, which the pipeline takes back out once read. */
28
12
  type Lookup = {
@@ -41,20 +25,20 @@ export declare class MongoDialect extends AbstractDialect {
41
25
  * the document does not use.
42
26
  */
43
27
  columnOf<E>(meta: EntityMeta<E>, key: string): string;
44
- where<E extends Document>(entity: Type<E>, where?: QueryWhere<E>, opts?: QueryOptions): Filter<E>;
28
+ where<E extends Document>(entity: AbstractType<E>, where?: QueryWhere<E>, opts?: QueryOptions): Filter<E>;
45
29
  /**
46
30
  * The stages every pipeline starts with: the `$lookup` each relation condition needs, into a temporary
47
31
  * field so `$or` keeps its meaning, the `$match` reading them, and the temporaries taken back out. Each
48
32
  * relation aggregate the `$where` or `fields` reads is left on the document, once, under its column.
49
33
  * `lookup` keeps the temporaries used, so a later lookup neither repeats nor reuses one.
50
34
  */
51
- matchStages<E extends Document>(entity: Type<E>, where?: QueryWhere<E>, opts?: QueryOptions, fields?: readonly string[], lookup?: Lookup): MongoAggregationPipelineEntry<Document>[];
35
+ matchStages<E extends Document>(entity: AbstractType<E>, where?: QueryWhere<E>, opts?: QueryOptions, fields?: readonly string[], lookup?: Lookup): MongoAggregationPipelineEntry<Document>[];
52
36
  /**
53
37
  * Renders a `$where` tree without applying entity filters (used for same-scope group-operator
54
38
  * recursion). A relation, or a relation aggregate, needs `$lookup` stages, so it is only accepted
55
39
  * when `lookup` is given - a plain `find`/`updateMany` filter has nowhere to put them.
56
40
  */
57
- protected renderFilter<E extends Document>(entity: Type<E>, where?: QueryWhere<E>, lookup?: Lookup): Filter<E>;
41
+ protected renderFilter<E extends Document>(entity: AbstractType<E>, where?: QueryWhere<E>, lookup?: Lookup): Filter<E>;
58
42
  /**
59
43
  * Renders `$and`/`$or`/`$not`/`$nor` into `filter`, both negations as MongoDB's `$nor` (a `$not`'s clauses
60
44
  * wrapped in one `$and`), dropping empty clauses, since MongoDB refuses an empty operator.
@@ -100,20 +84,20 @@ export declare class MongoDialect extends AbstractDialect {
100
84
  private allHolding;
101
85
  /** An object's keys as {@link held} reads each, a nested object's by its dotted path rather than whole. */
102
86
  private containment;
103
- select<E extends Document>(entity: Type<E>, select?: QuerySelectValue<E>, exclude?: QueryExclude<E>): Record<string, 0 | 1>;
87
+ select<E extends Document>(entity: AbstractType<E>, select?: QuerySelectValue<E>): Record<string, 0 | 1>;
104
88
  /**
105
89
  * The `$sort` stage. A relation key reads the document a `$lookup` unwound onto the parent, so - as
106
90
  * on the SQL dialects - it is only addressable when the statement joins that relation. Here that
107
91
  * means a *populated* one, at every level of the path: a lookup adds a field to the result, so one
108
92
  * added for the sort alone would change what the caller gets back.
109
93
  */
110
- sort<E extends Document>(entity: Type<E>, q: Query<E>): Sort;
94
+ private sort;
111
95
  /**
112
96
  * The ordering, and the paths whose nulls it places. MongoDB sorts null and missing lowest and takes
113
97
  * no placement, so one is emulated: {@link nullsSortStages} flags each path and the flag is ordered
114
- * by ahead of the value itself.
98
+ * by ahead of the value itself. `ranked` is a field holding a vector distance, ordered by first.
115
99
  */
116
- sortPlan<E extends Document>(entity: Type<E>, { $sort: sort, $populate: populate, $where: where }: Query<E>): MongoSortPlan;
100
+ private sortPlan;
117
101
  /**
118
102
  * Walks `$sort` against the metadata of the entity each level addresses, as the SQL dialects do. `at` is where the
119
103
  * level is: the relations walked to it (`path`, ending in a dot), and the join its rows came from, if any.
@@ -124,11 +108,9 @@ export declare class MongoDialect extends AbstractDialect {
124
108
  * correlated `$lookup` reading it per parent, and the `$set` that lifts it onto the document as the
125
109
  * field the `$sort` then orders by. A parent with no related row reads a zero tally and no distance.
126
110
  */
127
- sortAggregateStages<E extends Document>(entity: Type<E>, sort: QuerySortMap<E> | undefined): Lookup & {
111
+ sortAggregateStages<E extends Document>(entity: AbstractType<E>, sort: QuerySortMap<E> | undefined): Lookup & {
128
112
  readonly fields: string[];
129
113
  };
130
- /** Whether a read answers with a relation aggregate, which only the pipeline can build. */
131
- readsAggregates<E extends Document>(entity: Type<E>, q: Query<E>): boolean;
132
114
  /** The relation aggregates a read projects or sorts by; its `$where` puts its own on the document. */
133
115
  private aggregateKeys;
134
116
  /**
@@ -164,7 +146,7 @@ export declare class MongoDialect extends AbstractDialect {
164
146
  */
165
147
  private toManyLookup;
166
148
  /** Whether a `$sort` reads a relation, which is what forces the lookups to run before it. */
167
- sortsRelations<E extends Document>(entity: Type<E>, sort: QuerySortMap<E> | undefined): boolean;
149
+ sortsRelations<E extends Document>(entity: AbstractType<E>, sort: QuerySortMap<E> | undefined): boolean;
168
150
  /**
169
151
  * Aggregate results are keyed by `$group`/`$select` alias rather than by column, so an aggregate
170
152
  * `$sort` addresses those aliases as-is - the same reason the SQL dialects sort by alias there.
@@ -175,14 +157,34 @@ export declare class MongoDialect extends AbstractDialect {
175
157
  * embedded path (`kind.city` -> `<kind's column>.city`).
176
158
  */
177
159
  private pathOf;
178
- aggregationPipeline<E extends Document>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): MongoAggregationPipelineEntry<E>[];
160
+ /**
161
+ * How a read runs, its ordering and aggregates read once for both the routing and the run: the one place
162
+ * deciding how a read is scored and ranked, a root vector search through Atlas.
163
+ */
164
+ readPlan<E extends Document>(entity: AbstractType<E>, q: Query<E>, opts?: QueryOptions): MongoRead;
165
+ /**
166
+ * Whether a read needs stages a `find` cursor cannot express: a lookup to populate, count, filter or
167
+ * order by a relation, one to build a relation aggregate, and the grouping `$distinct` is.
168
+ */
169
+ private readsThroughPipeline;
170
+ /**
171
+ * Build an aggregation pipeline for vector similarity search.
172
+ * `$vectorSearch` is always the first stage; `$where` is merged into its `filter`.
173
+ */
174
+ private vectorSearchPipeline;
175
+ /** A read as a pipeline, whether or not a `find` cursor would express it. */
176
+ aggregationPipeline<E extends Document>(entity: AbstractType<E>, q: Query<E>, opts?: QueryOptions): MongoAggregationPipelineEntry<Document>[];
177
+ /** The pipeline of a read no `$vectorSearch` enters, given its ordering, aggregates and vector score. */
178
+ private scanPipeline;
179
+ /** A vector search's exact distance, by its metric, as a score to rank by: its `$project`, else a temporary field. */
180
+ private nearestScore;
179
181
  /** The `$skip`/`$limit` stages of a page, each checked: `/http` hands a page over untyped. */
180
182
  pagerStages(q: QueryPager): MongoAggregationPipelineEntry<Document>[];
181
183
  /**
182
184
  * What a read runs after its entry stage, in the one order that works: the lookups, then the sort and
183
185
  * page that may read them, then the projection. Shared with the `$vectorSearch` pipeline.
184
186
  */
185
- readStages<E extends Document>(entity: Type<E>, q: Query<E>, extra: MongoReadStages): MongoAggregationPipelineEntry<Document>[];
187
+ private readStages;
186
188
  /**
187
189
  * `$distinct` as a `$group` on the columns the query projects - the same set a SQL dialect puts
188
190
  * after `SELECT DISTINCT` - and the `$replaceRoot` that lifts the grouped key back to the top
@@ -194,7 +196,7 @@ export declare class MongoDialect extends AbstractDialect {
194
196
  * The projection a narrowing query asks for, widened by what the pipeline produced (each populated
195
197
  * relation and the tallies); last, once the lookups have read the join keys.
196
198
  */
197
- pipelineProjection<E extends Document>(entity: Type<E>, q: Query<E>): Record<string, 0 | 1> | undefined;
199
+ pipelineProjection<E extends Document>(entity: AbstractType<E>, q: Query<E>): Record<string, 0 | 1> | undefined;
198
200
  /**
199
201
  * The `$lookup`/`$unwind` pair for each relation joined below `parent`, its own relations nested
200
202
  * inside its pipeline and resolved before the projection that reads them.
@@ -217,7 +219,7 @@ export declare class MongoDialect extends AbstractDialect {
217
219
  normalizeId<E extends Document>(meta: EntityMeta<E>, doc: Document): E;
218
220
  normalizeId<E extends Document>(meta: EntityMeta<E>, doc: Document | undefined): E | undefined;
219
221
  /** An aggregate's rows with each 64-bit integer decoded as a document's is: a `bigint` only where the column reads a `BigInt` field. */
220
- normalizeAggregateRows<E extends Document, R extends Document>(entity: Type<E>, q: QueryAggregate<E>, rows: R[]): R[];
222
+ normalizeAggregateRows<E extends Document, R extends Document>(entity: AbstractType<E>, q: QueryAggregate<E>, rows: R[]): R[];
221
223
  /**
222
224
  * A key as MongoDB stores it: a 24-hex string as an `ObjectId`, so a write matches the filter looking for
223
225
  * it, and anything else as given. Only 24-hex, not any 12-byte string. Arrays convert element-wise.
@@ -241,7 +243,7 @@ export declare class MongoDialect extends AbstractDialect {
241
243
  /**
242
244
  * Build MongoDB aggregation pipeline stages from a QueryAggregate.
243
245
  */
244
- buildAggregateStages<E extends Document>(entity: Type<E>, q: QueryAggregate<E>, opts?: QueryOptions): MongoAggregationPipelineEntry<Document>[];
246
+ buildAggregateStages<E extends Document>(entity: AbstractType<E>, q: QueryAggregate<E>, opts?: QueryOptions): MongoAggregationPipelineEntry<Document>[];
245
247
  /**
246
248
  * Resolve parsed group entries into the `_id` keys and accumulators of a `$group` stage, and the
247
249
  * `columns` its `$project` reads each result from: a group key out of `_id`, a DISTINCT set by its
@@ -278,14 +280,14 @@ export declare class MongoDialect extends AbstractDialect {
278
280
  * Separate vector sort entries from regular sort entries.
279
281
  * Returns `undefined` if no vector sort is present.
280
282
  */
281
- extractVectorSort<E extends Document>(sort: QuerySortMap<E> | undefined): ExtractedVectorSort<E> | undefined;
283
+ private extractVectorSort;
282
284
  /** The Atlas index a `$vectorSearch` over `column` reads, and migrations create: its declared name, else `<column>_index`. */
283
285
  protected vectorSearchIndexName(name: string | undefined, column: string): string;
284
286
  /**
285
287
  * Build a `$vectorSearch` aggregation pipeline stage.
286
288
  * Merges `$where` into `$vectorSearch.filter` for optimal pre-filtering.
287
289
  */
288
- buildVectorSearchStage<E extends Document>(entity: Type<E>, key: string, search: QueryVectorSearch, where: QueryWhere<E> | undefined, limit: number, opts?: QueryOptions, candidates?: number): MongoAggregationPipelineEntry<Document>;
290
+ private buildVectorSearchStage;
289
291
  }
290
292
  export type MongoAggregationPipelineEntry<E extends Document> = {
291
293
  $lookup?: MongoAggregationLookup;
@@ -317,9 +319,4 @@ type MongoAggregationUnwind = {
317
319
  readonly path?: string;
318
320
  readonly preserveNullAndEmptyArrays?: boolean;
319
321
  };
320
- export type ExtractedVectorSort<E> = {
321
- readonly vectorKey: string;
322
- readonly vectorSearch: QueryVectorSearch;
323
- readonly regularSort: QuerySortMap<E>;
324
- };
325
322
  export {};