uql-orm 0.102.6 → 0.103.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 (109) hide show
  1. package/README.md +1 -1
  2. package/dist/browser/uql-browser.min.js +2 -2
  3. package/dist/browser/uql-browser.min.js.map +3 -3
  4. package/dist/bunSql/bunSqlQuerier.d.ts +9 -3
  5. package/dist/bunSql/bunSqlQuerier.js +7 -15
  6. package/dist/cockroachdb/crdbQuerierPool.d.ts +2 -2
  7. package/dist/context/context.d.ts +0 -6
  8. package/dist/context/context.js +1 -7
  9. package/dist/d1/d1Querier.d.ts +18 -14
  10. package/dist/d1/d1Querier.js +21 -8
  11. package/dist/d1/d1QuerierPool.d.ts +0 -1
  12. package/dist/d1/d1QuerierPool.js +0 -1
  13. package/dist/d1/d1SqliteDialect.d.ts +2 -0
  14. package/dist/d1/d1SqliteDialect.js +3 -0
  15. package/dist/dialect/abstractDialect.d.ts +3 -0
  16. package/dist/dialect/abstractDialect.js +6 -2
  17. package/dist/dialect/abstractSqlDialect.d.ts +26 -7
  18. package/dist/dialect/abstractSqlDialect.js +89 -60
  19. package/dist/dialect/mysqlLikeSqlDialect.js +6 -1
  20. package/dist/dialect/operators.d.ts +9 -3
  21. package/dist/dialect/operators.js +32 -9
  22. package/dist/dialect/vectorSqlDialect.js +2 -2
  23. package/dist/entity/metadata/definition.d.ts +11 -1
  24. package/dist/entity/metadata/definition.js +18 -0
  25. package/dist/mariadb/mariadbQuerier.d.ts +5 -2
  26. package/dist/mariadb/mariadbQuerier.js +5 -10
  27. package/dist/migrate/ddl/defaultSql.js +1 -1
  28. package/dist/migrate/ddl/indexDdl.d.ts +3 -3
  29. package/dist/migrate/ddl/indexDdl.js +7 -7
  30. package/dist/migrate/ddl/mysqlIndexDdl.js +2 -2
  31. package/dist/migrate/ddl/tableDdl.js +2 -2
  32. package/dist/migrate/indexPredicate.d.ts +4 -3
  33. package/dist/migrate/indexPredicate.js +5 -5
  34. package/dist/migrate/introspection/abstractSqlSchemaIntrospector.js +2 -6
  35. package/dist/migrate/schemaGenerator.js +1 -1
  36. package/dist/migrate/triggerSql.js +7 -5
  37. package/dist/mongodb/mongoDialect.js +17 -41
  38. package/dist/mongodb/mongoSchemaGenerator.js +12 -12
  39. package/dist/mongodb/mongodbQuerier.d.ts +4 -3
  40. package/dist/mongodb/mongodbQuerier.js +75 -102
  41. package/dist/mssql/mssqlDialect.js +4 -9
  42. package/dist/mssql/mssqlQuerier.d.ts +9 -3
  43. package/dist/mssql/mssqlQuerier.js +9 -11
  44. package/dist/mysql/mysql2Querier.d.ts +11 -2
  45. package/dist/mysql/mysql2Querier.js +4 -7
  46. package/dist/neon/index.d.ts +2 -0
  47. package/dist/neon/index.js +2 -0
  48. package/dist/neon/neonDialect.d.ts +7 -0
  49. package/dist/neon/neonDialect.js +8 -0
  50. package/dist/neon/neonQuerier.d.ts +26 -0
  51. package/dist/neon/neonQuerier.js +42 -0
  52. package/dist/neon/neonQuerierPool.d.ts +16 -6
  53. package/dist/neon/neonQuerierPool.js +48 -5
  54. package/dist/pglite/pgliteQuerier.d.ts +9 -5
  55. package/dist/pglite/pgliteQuerier.js +7 -11
  56. package/dist/postgres/abstractPgQuerierPool.d.ts +6 -6
  57. package/dist/postgres/pgExecution.d.ts +8 -0
  58. package/dist/postgres/pgExecution.js +3 -0
  59. package/dist/postgres/pgQuerier.d.ts +8 -11
  60. package/dist/postgres/pgQuerier.js +5 -9
  61. package/dist/postgres/pgQuerierPool.d.ts +2 -2
  62. package/dist/querier/abstractQuerier.d.ts +24 -20
  63. package/dist/querier/abstractQuerier.js +79 -58
  64. package/dist/querier/abstractQuerierPool.d.ts +2 -4
  65. package/dist/querier/abstractQuerierPool.js +2 -0
  66. package/dist/querier/abstractSqlQuerier.d.ts +46 -30
  67. package/dist/querier/abstractSqlQuerier.js +141 -119
  68. package/dist/querier/queryError.d.ts +2 -0
  69. package/dist/querier/queryError.js +9 -0
  70. package/dist/querier/transaction.js +3 -7
  71. package/dist/schema/canonicalType.d.ts +3 -3
  72. package/dist/schema/canonicalType.js +4 -10
  73. package/dist/sqlite/bindValues.d.ts +10 -0
  74. package/dist/sqlite/bindValues.js +8 -0
  75. package/dist/sqlite/hranaQuerier.d.ts +17 -11
  76. package/dist/sqlite/hranaQuerier.js +16 -5
  77. package/dist/sqlite/index.d.ts +1 -1
  78. package/dist/sqlite/index.js +0 -1
  79. package/dist/sqlite/localSqliteQuerierPool.js +19 -9
  80. package/dist/sqlite/sqliteQuerier.d.ts +9 -4
  81. package/dist/sqlite/sqliteQuerier.js +14 -8
  82. package/dist/turso/tursoQuerierPool.d.ts +0 -2
  83. package/dist/turso/tursoQuerierPool.js +0 -2
  84. package/dist/turso/tursoSessionQuerier.d.ts +19 -7
  85. package/dist/turso/tursoSessionQuerier.js +31 -20
  86. package/dist/type/dialect.d.ts +3 -0
  87. package/dist/type/querier.d.ts +12 -0
  88. package/dist/type/querier.js +10 -0
  89. package/dist/type/vector.d.ts +2 -1
  90. package/dist/type/vector.js +2 -2
  91. package/dist/util/asyncScope.d.ts +11 -0
  92. package/dist/util/asyncScope.js +29 -0
  93. package/dist/util/dialect.util.d.ts +21 -6
  94. package/dist/util/dialect.util.js +34 -9
  95. package/dist/util/filters.util.d.ts +5 -4
  96. package/dist/util/filters.util.js +4 -7
  97. package/dist/util/logger.js +2 -6
  98. package/dist/util/object.util.d.ts +7 -0
  99. package/dist/util/object.util.js +17 -0
  100. package/dist/util/query.util.d.ts +3 -2
  101. package/dist/util/sql.js +1 -1
  102. package/dist/util/sql.util.d.ts +18 -16
  103. package/dist/util/sql.util.js +8 -6
  104. package/package.json +5 -8
  105. package/skills/uql-orm/SKILL.md +4 -2
  106. package/dist/context/context.browser.d.ts +0 -12
  107. package/dist/context/context.browser.js +0 -33
  108. package/dist/sqlite/abstractSqliteQuerier.d.ts +0 -28
  109. package/dist/sqlite/abstractSqliteQuerier.js +0 -36
@@ -1,8 +1,9 @@
1
- import type { DialectName, EntityWhereMeta } from '../type/index.js';
1
+ import type { AbstractDialect } from '../dialect/abstractDialect.js';
2
+ import type { EngineName, EntityWhereMeta } from '../type/index.js';
2
3
  /**
3
4
  * Refuses a partial index's predicate reaching past what the engine takes, before it compiles to what
4
5
  * only the server would reject, naming the operator as its author wrote it. A `sql` one is left to the server.
5
6
  */
6
- export declare function assertIndexPredicate<E>(where: EntityWhereMeta<E>, dialectName: DialectName, indexName: string): void;
7
+ export declare function assertIndexPredicate<E>(where: EntityWhereMeta<E>, dialect: Pick<AbstractDialect, 'dialectName' | 'engineName'>, indexName: string): void;
7
8
  /** What refusing any part of a partial index's predicate reports. */
8
- export declare function refusedIndexPredicate(dialectName: string, part: string, indexName: string): TypeError;
9
+ export declare function refusedIndexPredicate(engine: EngineName, part: string, indexName: string): TypeError;
@@ -22,16 +22,16 @@ const PREDICATE_GRAMMARS = {
22
22
  * Refuses a partial index's predicate reaching past what the engine takes, before it compiles to what
23
23
  * only the server would reject, naming the operator as its author wrote it. A `sql` one is left to the server.
24
24
  */
25
- export function assertIndexPredicate(where, dialectName, indexName) {
26
- const grammar = PREDICATE_GRAMMARS[dialectName];
25
+ export function assertIndexPredicate(where, dialect, indexName) {
26
+ const grammar = PREDICATE_GRAMMARS[dialect.dialectName];
27
27
  const refused = grammar && !(where instanceof QuerySql) ? refusedOperator(where, grammar) : undefined;
28
28
  if (refused) {
29
- throw refusedIndexPredicate(dialectName, refused, indexName);
29
+ throw refusedIndexPredicate(dialect.engineName, refused, indexName);
30
30
  }
31
31
  }
32
32
  /** What refusing any part of a partial index's predicate reports. */
33
- export function refusedIndexPredicate(dialectName, part, indexName) {
34
- return new UqlUsageError(`${dialectName} does not support ${part} in a partial index predicate (index "${indexName}")`);
33
+ export function refusedIndexPredicate(engine, part, indexName) {
34
+ return new UqlUsageError(`${engine} does not support ${part} in a partial index predicate (index "${indexName}")`);
35
35
  }
36
36
  /** The first part of `where` outside `grammar`, depth-first; a `sql` clause is left alone. */
37
37
  function refusedOperator(where, grammar) {
@@ -1,5 +1,6 @@
1
1
  import { SqlExpression } from '../../schema/sqlExpression.js';
2
2
  import { FOREIGN_KEY_ACTIONS } from '../../schema/types.js';
3
+ import { cachedIn } from '../../util/object.util.js';
3
4
  import { sql } from '../../util/sql.js';
4
5
  import { isOwnedName } from '../../util/sql.util.js';
5
6
  import { withSqlQuerierForMigrations } from '../acquireQuerierForMigrations.js';
@@ -161,11 +162,6 @@ function createTableRowReader(querier) {
161
162
  const sent = new Map();
162
163
  return (sql) => {
163
164
  const key = JSON.stringify(querier.dialect.compile(sql));
164
- let rows = sent.get(key);
165
- if (!rows) {
166
- rows = querier.all(sql);
167
- sent.set(key, rows);
168
- }
169
- return rows;
165
+ return cachedIn(sent, key, () => querier.all(sql));
170
166
  };
171
167
  }
@@ -60,7 +60,7 @@ export class SqlSchemaGenerator {
60
60
  resolveColumnName: (key, field) => dialect.resolveColumnName(key, field),
61
61
  compileDdl: (sql, entity) => dialect.compileDdl(sql, entity),
62
62
  compileIndexPredicate: (where, entity, indexName) => {
63
- assertIndexPredicate(where, dialect.dialectName, indexName);
63
+ assertIndexPredicate(where, dialect, indexName);
64
64
  return dialect.compileDdl(where, entity);
65
65
  },
66
66
  defaultForeignKeyAction: this.defaultForeignKeyAction,
@@ -50,7 +50,7 @@ function triggerStatements(dialect, meta, trigger, name) {
50
50
  const [timing, operation] = EVENT_PARTS[trigger.on];
51
51
  const before = timing === 'BEFORE';
52
52
  if (trigger.deferred && !features.deferrable) {
53
- throw new UqlUsageError(`${dialect.dialectName} cannot defer a trigger to commit, which ${meta.entity.name} asks for; only Postgres can`);
53
+ throw new UqlUsageError(`${dialect.engineName} cannot defer a trigger to commit, which ${meta.entity.name} asks for; only PostgreSQL can`);
54
54
  }
55
55
  const { fires } = features;
56
56
  const perStatement = fires === 'eachStatement';
@@ -59,7 +59,7 @@ function triggerStatements(dialect, meta, trigger, name) {
59
59
  const filter = triggerFilter(dialect, meta, trigger, rows, names);
60
60
  const body = triggerBody(dialect, meta, trigger, before)(...rows);
61
61
  if (perStatement && filter && !(body instanceof TriggerWriteSql)) {
62
- throw new UqlUsageError(`${dialect.dialectName} fires a trigger once per statement, so 'of' and 'where' narrow only what ` +
62
+ throw new UqlUsageError(`${dialect.engineName} fires a trigger once per statement, so 'of' and 'where' narrow only what ` +
63
63
  `insertInto, updateTable or deleteFrom reads, and '${meta.entity.name}' has one running its own SQL. ` +
64
64
  'Keep the body to those writes, or filter inserted and deleted in that SQL.');
65
65
  }
@@ -110,14 +110,16 @@ const EVENT_PARTS = {
110
110
  */
111
111
  function triggerBody(dialect, meta, trigger, before) {
112
112
  if (before && !dialect.features.triggers.before) {
113
- throw new UqlUsageError(`${dialect.dialectName} has no BEFORE trigger, only AFTER and INSTEAD OF, so '${trigger.on}' cannot be ` +
113
+ throw new UqlUsageError(`${dialect.engineName} has no BEFORE trigger, only AFTER and INSTEAD OF, so '${trigger.on}' cannot be ` +
114
114
  'rendered there. Use the matching after event, which sees the row already written.');
115
115
  }
116
116
  const { run } = trigger;
117
117
  const body = typeof run === 'function' ? run : (run[dialect.dialectName] ?? run[dialect.dialectFamily]);
118
118
  if (!body) {
119
- throw new UqlUsageError(`'${meta.entity.name}' has a trigger with no body for ${dialect.dialectName}, the engine in use. ` +
120
- 'Write one for it, or one body for every engine.');
119
+ const { dialectName, dialectFamily } = dialect;
120
+ const keys = dialectFamily === dialectName ? `'${dialectName}'` : `'${dialectName}' or '${dialectFamily}'`;
121
+ throw new UqlUsageError(`'${meta.entity.name}' has a trigger with no body for ${dialect.engineName}, the engine in use. ` +
122
+ `Add one under ${keys}, or write one body for every engine.`);
121
123
  }
122
124
  return body;
123
125
  }
@@ -1,13 +1,13 @@
1
1
  import { ObjectId } from 'mongodb';
2
2
  import { AbstractDialect } from '../dialect/abstractDialect.js';
3
3
  import { AGGREGATE_VALUE_ALIAS, REL_NESTED_KEY, REL_FIELD_PREFIX, relTempField, SUM_COUNT_ALIAS, nullsSortField, sortAggregateField, TEXT_SCORE_ALIAS, } from '../dialect/aliases.js';
4
- import { betweenBounds, inOperands, GROUP_OPS, groupClauses, isGroupOp, LIKE_OPS, likeRegex, whereOperators, } from '../dialect/operators.js';
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
7
  import { COUNT_RESULT_KEY } from '../type/query.js';
8
8
  import { QuerySql } from '../type/querySql.js';
9
- 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, vectorDistanceOf, } from '../util/index.js';
10
- import { kindOf, UqlUsageError } from '../util/uqlError.js';
9
+ 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, vectorDistanceOf, cachedIn, } from '../util/index.js';
10
+ import { UqlUsageError } from '../util/uqlError.js';
11
11
  import { decodeBigIntsExcept } from '../util/wideNumber.js';
12
12
  import { textLanguage } from './textLanguage.js';
13
13
  import { vectorDistanceExpr } from './vectorDistance.js';
@@ -154,22 +154,13 @@ function arraySize(ref, size) {
154
154
  }
155
155
  /** `count` compared with `size`, a number or its bounds, as an aggregation expression. */
156
156
  function compareCount(count, size) {
157
- if (typeof size === 'number') {
158
- return { $eq: [count, size] };
159
- }
160
- if (!isRecord(size)) {
161
- throw new UqlUsageError(`$size expects a number or bounds, got ${kindOf(size)}`);
162
- }
163
- const comparisons = Object.entries(size).flatMap(([op, bound]) => {
157
+ const comparisons = sizeComparisons(size).flatMap(([op, bound]) => {
164
158
  if (op !== '$between') {
165
159
  return [{ [op]: [count, literal(bound)] }];
166
160
  }
167
161
  const [min, max] = betweenBounds(bound);
168
162
  return [{ $gte: [count, literal(min)] }, { $lte: [count, literal(max)] }];
169
163
  });
170
- if (!comparisons.length) {
171
- throw new UqlUsageError('$size needs at least one comparison');
172
- }
173
164
  return allOf(comparisons);
174
165
  }
175
166
  /** Whether the array at `ref` has an element `test` passes, reading it as `$$this`. No other value has one. */
@@ -1001,35 +992,20 @@ export class MongoDialect extends AbstractDialect {
1001
992
  }
1002
993
  /** `[column, key]` for the fields whose stored name differs from their property name, memoized per entity. */
1003
994
  renamedColumns(meta) {
1004
- let renamed = this.#renamedColumns.get(meta);
1005
- if (!renamed) {
1006
- renamed = getKeys(meta.fields)
1007
- .map((key) => [this.columnOf(meta, key), key])
1008
- .filter(([column, key]) => column !== key);
1009
- this.#renamedColumns.set(meta, renamed);
1010
- }
1011
- return renamed;
995
+ return cachedIn(this.#renamedColumns, meta, () => getKeys(meta.fields)
996
+ .map((key) => [this.columnOf(meta, key), key])
997
+ .filter(([column, key]) => column !== key));
1012
998
  }
1013
999
  /** Each relation's key, the field its rows are read from, and its entity, memoized per entity for `normalizeId`. */
1014
1000
  relationReads(meta) {
1015
- let reads = this.#relationReads.get(meta);
1016
- if (!reads) {
1017
- reads = definedEntries(meta.relations).map(([key, relation]) => ({
1018
- key,
1019
- field: relationField(key),
1020
- meta: getMeta(relation.entity()),
1021
- }));
1022
- this.#relationReads.set(meta, reads);
1023
- }
1024
- return reads;
1001
+ return cachedIn(this.#relationReads, meta, () => definedEntries(meta.relations).map(([key, relation]) => ({
1002
+ key,
1003
+ field: relationField(key),
1004
+ meta: getMeta(relation.entity()),
1005
+ })));
1025
1006
  }
1026
1007
  referenceKeys(meta) {
1027
- let keys = this.#referenceKeys.get(meta);
1028
- if (!keys) {
1029
- keys = getKeys(meta.fields).filter((key) => meta.fields[key]?.references);
1030
- this.#referenceKeys.set(meta, keys);
1031
- }
1032
- return keys;
1008
+ return cachedIn(this.#referenceKeys, meta, () => getKeys(meta.fields).filter((key) => meta.fields[key]?.references));
1033
1009
  }
1034
1010
  // Keyed by the meta object itself; entity metadata is immutable once defined.
1035
1011
  #renamedColumns = new WeakMap();
@@ -1170,9 +1146,8 @@ export class MongoDialect extends AbstractDialect {
1170
1146
  // Keys are resolved per document so heterogeneous payloads keep every provided field.
1171
1147
  const inserting = callbackKey === 'onInsert';
1172
1148
  return payloads.map((it) => {
1173
- // The key is `_id` on an insert and immutable on an update, so it is left out of one. It used
1174
- // to land under its own name beside the `_id` the driver minted: a supplied id, or one an
1175
- // `onInsert` generated, was written and unreachable by the value the caller held.
1149
+ // The key is `_id` on an insert and immutable on an update, so it is left out of one: written under its
1150
+ // own name beside the `_id` the driver minted, it would be unreachable by the value the caller held.
1176
1151
  const named = inserting && it[idKey] != null;
1177
1152
  if (inserting && !named) {
1178
1153
  // Nothing named the key, so the database is being asked to mint one.
@@ -1182,11 +1157,12 @@ export class MongoDialect extends AbstractDialect {
1182
1157
  for (const key of filterFieldKeys(meta, it, callbackKey)) {
1183
1158
  if (key === idKey)
1184
1159
  continue;
1185
- const field = meta.fields[key];
1160
+ const field = fieldOf(meta, key);
1186
1161
  const value = it[key];
1187
1162
  assertNoRaw(value, 'a write');
1188
1163
  doc[this.resolveColumnName(key, field)] = field.references ? this.toWireId(value) : value;
1189
1164
  }
1165
+ // Keyed by column, which the driver's types read as `E`'s keys: they name the same fields.
1190
1166
  return doc;
1191
1167
  });
1192
1168
  }
@@ -84,13 +84,13 @@ export class MongoSchemaGenerator extends MongoDialect {
84
84
  */
85
85
  indexFilter(where, entity, indexName) {
86
86
  if (where instanceof QuerySql) {
87
- throw new UqlUsageError(`mongodb does not support partial indexes from a SQL predicate (index "${indexName}")`);
87
+ throw new UqlUsageError(`${this.engineName} does not support partial indexes from a SQL predicate (index "${indexName}")`);
88
88
  }
89
- assertIndexPredicate(where, this.dialectName, indexName);
89
+ assertIndexPredicate(where, this, indexName);
90
90
  const filter = this.renderFilter(entity, where);
91
91
  const refused = refusedFilterValue(filter);
92
92
  if (refused) {
93
- throw refusedIndexPredicate(this.dialectName, refused, indexName);
93
+ throw refusedIndexPredicate(this.engineName, refused, indexName);
94
94
  }
95
95
  return JSON.stringify(filter);
96
96
  }
@@ -108,12 +108,12 @@ export class MongoSchemaGenerator extends MongoDialect {
108
108
  /** A check's filter, refused where it is SQL or holds what a migration cannot carry as JSON. */
109
109
  checkFilter(where, entity, collectionName) {
110
110
  if (where instanceof QuerySql) {
111
- throw new UqlUsageError(`mongodb does not support checks from a SQL predicate (collection "${collectionName}")`);
111
+ throw new UqlUsageError(`${this.engineName} does not support checks from a SQL predicate (collection "${collectionName}")`);
112
112
  }
113
113
  const filter = this.renderFilter(entity, where);
114
114
  const refused = refusedFilterValue(filter, true);
115
115
  if (refused) {
116
- throw new UqlUsageError(`mongodb does not support ${refused} in a check (collection "${collectionName}")`);
116
+ throw new UqlUsageError(`${this.engineName} does not support ${refused} in a check (collection "${collectionName}")`);
117
117
  }
118
118
  return filter;
119
119
  }
@@ -139,11 +139,11 @@ export class MongoSchemaGenerator extends MongoDialect {
139
139
  }
140
140
  /** An index as MongoDB's key spec (`-1` descending, `'text'` full-text), refusing the SQL-only options. */
141
141
  generateCreateIndex(tableName, index) {
142
- assertIndexType(index, MONGO_INDEX_TYPES, this.dialectName);
142
+ assertIndexType(index, MONGO_INDEX_TYPES, this.engineName);
143
143
  if (index.type === 'vectorSearch') {
144
144
  return this.generateCreateSearchIndex(tableName, index);
145
145
  }
146
- assertIndexFeatures(index, MONGO_INDEX_FEATURES, this.dialectName);
146
+ assertIndexFeatures(index, MONGO_INDEX_FEATURES, this.engineName);
147
147
  const key = {};
148
148
  for (const entry of index.entries) {
149
149
  key[entry.column] = index.type === 'fulltext' ? 'text' : entry.order === 'desc' ? -1 : 1;
@@ -165,7 +165,7 @@ export class MongoSchemaGenerator extends MongoDialect {
165
165
  }
166
166
  /** An Atlas vector search index: its vector field first, then each field a `$vectorSearch` pre-filters on. */
167
167
  generateCreateSearchIndex(tableName, index) {
168
- assertIndexFeatures(index, new Set(), this.dialectName);
168
+ assertIndexFeatures(index, new Set(), this.engineName);
169
169
  const [vector, ...filters] = index.entries;
170
170
  if (!vector || index.dimensions === undefined) {
171
171
  throw new UqlUsageError(`an Atlas vector search index states its field's dimensions (index "${index.name}")`);
@@ -173,7 +173,7 @@ export class MongoSchemaGenerator extends MongoDialect {
173
173
  const distance = indexDistance(index);
174
174
  const similarity = ATLAS_SIMILARITY[distance];
175
175
  if (!similarity) {
176
- throw unsupportedVectorMetric(this.dialectName, distance, index.name);
176
+ throw unsupportedVectorMetric(this.engineName, distance, index.name);
177
177
  }
178
178
  return serializeMongoCommand({
179
179
  action: 'createSearchIndex',
@@ -197,7 +197,7 @@ export class MongoSchemaGenerator extends MongoDialect {
197
197
  case 'createTable': {
198
198
  const { name, columns, indexes } = operation.table;
199
199
  if (columns.length) {
200
- throw new UqlUsageError(`mongodb does not support columns in a migration (collection "${name}")`);
200
+ throw new UqlUsageError(`${this.engineName} does not support columns in a migration (collection "${name}")`);
201
201
  }
202
202
  return this.createCollection(name, indexes.map((index) => render(name, index)));
203
203
  }
@@ -210,7 +210,7 @@ export class MongoSchemaGenerator extends MongoDialect {
210
210
  case 'dropIndex':
211
211
  return [dropIndex(operation.tableName, operation.indexName)];
212
212
  default:
213
- throw new UqlUsageError(`mongodb does not support ${operation.type} in a migration`);
213
+ throw new UqlUsageError(`${this.engineName} does not support ${operation.type} in a migration`);
214
214
  }
215
215
  }
216
216
  diffSchema(entity, currentTable) {
@@ -230,7 +230,7 @@ export class MongoSchemaGenerator extends MongoDialect {
230
230
  }
231
231
  /** A collection has no SQL to render a check, a computed column or an index expression into. */
232
232
  function refuseSql() {
233
- throw new UqlUsageError('mongodb has no SQL to render a check, a computed column or an index expression into');
233
+ throw new UqlUsageError('MongoDB has no SQL to render a check, a computed column or an index expression into');
234
234
  }
235
235
  /** The command dropping an index, a search index by its own. */
236
236
  function dropIndex(collection, name, type) {
@@ -12,6 +12,7 @@ export declare class MongodbQuerier extends AbstractQuerier implements MongoQuer
12
12
  /** The open transaction's session, for a raw call through `db` to run inside it: `{ session: querier.session }`. */
13
13
  get session(): ClientSession | undefined;
14
14
  constructor(dialect: MongoDialect, conn: MongoClient, extra?: ExtraOptions | undefined);
15
+ /** Runs `task` on the open transaction's session, if any, after everything queued before it, timed as `label`. */
15
16
  private execute;
16
17
  protected internalFindMany<E extends Document>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<E[]>;
17
18
  protected internalFindManyStream<E extends Document>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): AsyncGenerator<E, void, unknown>;
@@ -57,9 +58,9 @@ export declare class MongodbQuerier extends AbstractQuerier implements MongoQuer
57
58
  private upsertUpdate;
58
59
  private buildConflictFilter;
59
60
  /**
60
- * An upsert whose conflicting document takes `update`, which no single call pairs with inserting the payload:
61
- * `$setOnInsert` and `$inc` on one field conflict. So the row inserts if absent, and a document it found,
62
- * a concurrent one included, then takes `update`.
61
+ * An upsert of `row` whose found document takes `update`, which no single call pairs with inserting the payload:
62
+ * `$setOnInsert` and `$inc` on one field conflict. So the row inserts if absent, and a document it found, a
63
+ * concurrent one included, then takes `update`.
63
64
  */
64
65
  private upsertWithUpdate;
65
66
  protected internalUpsertMany<E extends Document>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E[], update?: UpdatePayload<E>): Promise<(UpsertedId<E> | undefined)[]>;
@@ -1,8 +1,8 @@
1
1
  import { AGGREGATE_VALUE_ALIAS } from '../dialect/aliases.js';
2
2
  import { hasRequiredJoin } from '../dialect/queryJoins.js';
3
- import { fieldOf, getMeta, namesKey, soleIdOf } from '../entity/index.js';
3
+ import { getMeta, soleIdOf } from '../entity/index.js';
4
4
  import { AbstractQuerier } from '../querier/index.js';
5
- import { clone, getKeys, getSoftDeleteValue, hasKeys, hasTriggers, populatesRelations, textSortOf, vectorCandidates, withoutSoftDeleteFilter, whereEach, } from '../util/index.js';
5
+ import { clone, getKeys, deletionOf, hasKeys, hasTriggers, populatesRelations, textSortOf, vectorCandidates, 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)`
@@ -38,26 +38,24 @@ export class MongodbQuerier extends AbstractQuerier {
38
38
  this.conn = conn;
39
39
  this.extra = extra;
40
40
  }
41
- async execute(task) {
42
- return this.serialize(async () => {
43
- return task(this.#session);
44
- });
41
+ /** Runs `task` on the open transaction's session, if any, after everything queued before it, timed as `label`. */
42
+ execute(label, task) {
43
+ return this.serialize(() => this.timed(label, undefined, () => task(this.#session)));
45
44
  }
46
45
  async internalFindMany(entity, q, opts) {
47
46
  if (asksForNoRows(q)) {
48
47
  return [];
49
48
  }
50
- return this.timed('internalFindMany', undefined, async () => {
51
- const cursor = this.readCursor(entity, q, opts);
52
- return this.dialect.normalizeIds(getMeta(entity), await this.execute(() => cursor.toArray()));
53
- });
49
+ const docs = await this.execute('internalFindMany', (session) => this.readCursor(entity, q, opts, session).toArray());
50
+ return this.dialect.normalizeIds(getMeta(entity), docs);
54
51
  }
55
52
  async *internalFindManyStream(entity, q, opts) {
56
53
  if (asksForNoRows(q)) {
57
54
  return;
58
55
  }
59
56
  const meta = getMeta(entity);
60
- for await (const doc of this.timedStream('internalFindManyStream', undefined, this.readCursor(entity, q, opts))) {
57
+ const cursor = this.readCursor(entity, q, opts, this.#session);
58
+ for await (const doc of this.timedStream('internalFindManyStream', undefined, cursor)) {
61
59
  yield this.dialect.normalizeId(meta, doc);
62
60
  }
63
61
  }
@@ -66,14 +64,14 @@ export class MongodbQuerier extends AbstractQuerier {
66
64
  * lookup, a grouping, a vector search - and the plain `find` cursor for everything else. One routing
67
65
  * for a read and a stream alike, so both load the same relations.
68
66
  */
69
- readCursor(entity, q, opts) {
67
+ readCursor(entity, q, opts, session) {
70
68
  const vectorSort = this.dialect.extractVectorSort(q.$sort);
71
69
  const pipeline = vectorSort
72
70
  ? this.buildVectorPipeline(entity, q, vectorSort, opts)
73
71
  : this.readsThroughPipeline(entity, q) && this.dialect.aggregationPipeline(entity, q, opts);
74
72
  return pipeline
75
- ? this.collection(entity).aggregate(pipeline, { session: this.#session })
76
- : this.buildFindCursor(entity, q, opts);
73
+ ? this.collection(entity).aggregate(pipeline, { session })
74
+ : this.buildFindCursor(entity, q, opts, session);
77
75
  }
78
76
  /**
79
77
  * Whether a read needs stages a `find` cursor cannot express: a lookup to populate, count, filter or
@@ -94,8 +92,8 @@ export class MongodbQuerier extends AbstractQuerier {
94
92
  return this.dialect.select(entity, q.$select, q.$exclude);
95
93
  }
96
94
  /** Build a MongoDB FindCursor with filter, projection, sort, skip, and limit from the query. */
97
- buildFindCursor(entity, q, opts) {
98
- const cursor = this.collection(entity).find({}, { session: this.#session });
95
+ buildFindCursor(entity, q, opts, session) {
96
+ const cursor = this.collection(entity).find({}, { session });
99
97
  const filter = this.dialect.where(entity, q.$where, opts);
100
98
  if (hasKeys(filter)) {
101
99
  cursor.filter(filter);
@@ -133,11 +131,9 @@ export class MongodbQuerier extends AbstractQuerier {
133
131
  ];
134
132
  }
135
133
  async internalAggregate(entity, q, opts) {
136
- return this.timed('internalAggregate', undefined, async () => {
137
- const pipeline = this.dialect.buildAggregateStages(entity, q, opts);
138
- const rows = await this.execute((session) => this.collection(entity).aggregate(pipeline, { session }).toArray());
139
- return this.dialect.normalizeAggregateRows(entity, q, rows);
140
- });
134
+ const pipeline = this.dialect.buildAggregateStages(entity, q, opts);
135
+ const rows = await this.execute('internalAggregate', (session) => this.collection(entity).aggregate(pipeline, { session }).toArray());
136
+ return this.dialect.normalizeAggregateRows(entity, q, rows);
141
137
  }
142
138
  /**
143
139
  * A `$required` relation drops parents that have no match, and `$distinct` collapses them, so both
@@ -151,7 +147,7 @@ export class MongodbQuerier extends AbstractQuerier {
151
147
  const { $sort: _sort, $skip: _skip, $limit: _limit, ...unpaged } = q;
152
148
  const [founds, counted] = await Promise.all([
153
149
  this.internalFindMany(entity, q, opts),
154
- this.execute((session) => this.collection(entity)
150
+ this.execute('internalFindManyAndCount', (session) => this.collection(entity)
155
151
  .aggregate([...this.dialect.aggregationPipeline(entity, unpaged, opts), { $count: AGGREGATE_VALUE_ALIAS }], { session })
156
152
  .toArray()),
157
153
  ]);
@@ -162,47 +158,39 @@ export class MongodbQuerier extends AbstractQuerier {
162
158
  if (asksForNoRows(q)) {
163
159
  return 0;
164
160
  }
165
- return this.timed('internalCount', undefined, async () => {
166
- const pipeline = [
167
- ...this.dialect.matchStages(entity, q.$where, opts),
168
- ...this.dialect.pagerStages(q),
169
- { $count: AGGREGATE_VALUE_ALIAS },
170
- ];
171
- const [counted] = await this.execute((session) => this.collection(entity)
172
- .aggregate(pipeline, { session })
173
- .toArray());
174
- return counted?.[AGGREGATE_VALUE_ALIAS] ?? 0;
175
- });
161
+ const pipeline = [
162
+ ...this.dialect.matchStages(entity, q.$where, opts),
163
+ ...this.dialect.pagerStages(q),
164
+ { $count: AGGREGATE_VALUE_ALIAS },
165
+ ];
166
+ const [counted] = await this.execute('internalCount', (session) => this.collection(entity).aggregate(pipeline, { session }).toArray());
167
+ return counted?.[AGGREGATE_VALUE_ALIAS] ?? 0;
176
168
  }
177
169
  /**
178
170
  * The collection's metadata count, which the driver exposes as its own call and which takes no
179
171
  * filter - the reason {@link UniversalQuerier.estimatedCount} takes none either.
180
172
  */
181
173
  async estimatedCount(entity) {
182
- return this.timed('estimatedCount', undefined, async () => this.execute((session) => this.collection(entity).estimatedDocumentCount({ session })));
174
+ return this.execute('estimatedCount', (session) => this.collection(entity).estimatedDocumentCount({ session }));
183
175
  }
184
176
  async internalInsertMany(entity, rows) {
185
177
  refuseTriggers(entity);
186
- return this.timed('internalInsertMany', undefined, async () => {
187
- const meta = getMeta(entity);
188
- const persistables = this.dialect.getPersistables(meta, rows, 'onInsert');
189
- const { insertedIds } = await this.execute((session) => this.collection(entity).insertMany(persistables, { session }));
190
- const ids = Object.values(insertedIds).map((id) => this.dialect.fromWireId(id));
191
- const idKey = soleIdOf(meta, 'insert');
192
- for (let index = 0; index < rows.length; index++) {
193
- rows[index][idKey] = ids[index];
194
- }
195
- });
178
+ const meta = getMeta(entity);
179
+ const persistables = this.dialect.getPersistables(meta, rows, 'onInsert');
180
+ const { insertedIds } = await this.execute('internalInsertMany', (session) => this.collection(entity).insertMany(persistables, { session }));
181
+ const ids = Object.values(insertedIds).map((id) => this.dialect.fromWireId(id));
182
+ const idKey = soleIdOf(meta, 'insert');
183
+ for (let index = 0; index < rows.length; index++) {
184
+ rows[index][idKey] = ids[index];
185
+ }
196
186
  }
197
187
  async internalUpdateMany(entity, qm, payload, opts) {
198
188
  refuseTriggers(entity);
199
- return this.timed('internalUpdateMany', undefined, async () => {
200
- const persistable = this.dialect.getPersistable(getMeta(entity), payload, 'onUpdate');
201
- const filter = this.dialect.where(entity, qm.$where, opts);
202
- const update = this.dialect.getUpdateFilter(persistable);
203
- const { matchedCount } = await this.execute((session) => this.collection(entity).updateMany(filter, update, { session }));
204
- return matchedCount;
205
- });
189
+ const persistable = this.dialect.getPersistable(getMeta(entity), payload, 'onUpdate');
190
+ const filter = this.dialect.where(entity, qm.$where, opts);
191
+ const update = this.dialect.getUpdateFilter(persistable);
192
+ const { matchedCount } = await this.execute('internalUpdateMany', (session) => this.collection(entity).updateMany(filter, update, { session }));
193
+ return matchedCount;
206
194
  }
207
195
  /**
208
196
  * What an upsert writes, as SQL's does: a found document takes the payload and the `onUpdate` fills, and only
@@ -225,13 +213,14 @@ export class MongodbQuerier extends AbstractQuerier {
225
213
  return this.dialect.where(entity, whereEach(getKeys(conflictPaths), (key) => item[key]));
226
214
  }
227
215
  /**
228
- * An upsert whose conflicting document takes `update`, which no single call pairs with inserting the payload:
229
- * `$setOnInsert` and `$inc` on one field conflict. So the row inserts if absent, and a document it found,
230
- * a concurrent one included, then takes `update`.
216
+ * An upsert of `row` whose found document takes `update`, which no single call pairs with inserting the payload:
217
+ * `$setOnInsert` and `$inc` on one field conflict. So the row inserts if absent, and a document it found, a
218
+ * concurrent one included, then takes `update`.
231
219
  */
232
220
  async upsertWithUpdate(entity, conflictPaths, row, update) {
233
221
  const persistable = this.dialect.getPersistable(getMeta(entity), clone(row), 'onInsert');
234
- const res = await this.execute((session) => this.collection(entity).findOneAndUpdate(this.buildConflictFilter(entity, conflictPaths, row), { $setOnInsert: persistable }, { upsert: true, returnDocument: 'after', includeResultMetadata: true, session }));
222
+ const filter = this.buildConflictFilter(entity, conflictPaths, row);
223
+ const res = await this.execute('upsertMany', (session) => this.collection(entity).findOneAndUpdate(filter, { $setOnInsert: persistable }, { upsert: true, returnDocument: 'after', includeResultMetadata: true, session }));
235
224
  // `updatedExisting` is false where the document was inserted; an empty `update` leaves a found one
236
225
  // as it is, as `DO NOTHING` does.
237
226
  if (res.lastErrorObject?.['updatedExisting'] && hasKeys(update)) {
@@ -248,63 +237,47 @@ export class MongodbQuerier extends AbstractQuerier {
248
237
  }
249
238
  return ids;
250
239
  }
251
- return this.timed('upsertMany', undefined, async () => {
252
- if (!payload.length) {
253
- return [];
254
- }
255
- const meta = getMeta(entity);
256
- // Asked before `getPersistable` fills an `onInsert` key into rows it may only update.
257
- const unnamed = payload.map((row) => !namesKey(meta, row));
258
- const operations = payload.map((item) => ({
259
- updateOne: {
260
- filter: this.buildConflictFilter(entity, conflictPaths, item),
261
- update: this.upsertUpdate(meta, item),
262
- upsert: true,
263
- },
264
- }));
265
- const res = await this.execute((session) => this.collection(entity).bulkWrite(operations, { session }));
266
- // `upsertedIds` names only the documents inserted, keyed by operation index, so each lands on
267
- // its own row; an updated document's `_id` is read back by the conflict fields instead.
268
- const reported = payload.map((_, index) => {
269
- const id = res.upsertedIds[index];
270
- return id === undefined ? undefined : this.dialect.fromWireId(id);
271
- });
272
- const unplaced = reported.some((id, index) => id === undefined && unnamed[index]);
273
- const found = unplaced ? await this.idsByConflict(entity, conflictPaths, payload) : [];
274
- return reported.map((id, index) => id ?? found[index]);
240
+ if (!payload.length) {
241
+ return [];
242
+ }
243
+ const meta = getMeta(entity);
244
+ const kept = payload.map((row) => upsertKeepsOwnKey(meta, conflictPaths, row));
245
+ const operations = payload.map((item) => ({
246
+ updateOne: {
247
+ filter: this.buildConflictFilter(entity, conflictPaths, item),
248
+ update: this.upsertUpdate(meta, item),
249
+ upsert: true,
250
+ },
251
+ }));
252
+ const res = await this.execute('upsertMany', (session) => this.collection(entity).bulkWrite(operations, { session }));
253
+ // `upsertedIds` names only the documents inserted, keyed by operation index, so each lands on
254
+ // its own row; an updated document's `_id` is read back by the conflict fields instead.
255
+ const reported = payload.map((_, index) => {
256
+ const id = res.upsertedIds[index];
257
+ return id === undefined ? undefined : this.dialect.fromWireId(id);
275
258
  });
259
+ return this.withUnreportedIds(entity, conflictPaths, payload, reported, kept);
276
260
  }
277
261
  async internalDeleteMany(entity, qm, opts = {}) {
278
262
  refuseTriggers(entity);
279
- return this.timed('internalDeleteMany', undefined, async () => {
280
- const meta = getMeta(entity);
281
- // Soft-delete (stamp) unless `hardDelete` is requested or the entity has no soft-delete field.
282
- const softDelete = opts.hardDelete ? undefined : meta.softDelete;
283
- if (!softDelete) {
284
- const filter = this.dialect.where(entity, qm.$where, {
285
- ...opts,
286
- filters: withoutSoftDeleteFilter(opts.filters),
287
- });
288
- const { deletedCount } = await this.execute((session) => this.collection(entity).deleteMany(filter, { session }));
289
- return deletedCount;
290
- }
291
- const field = fieldOf(meta, softDelete);
292
- // The mapped column, which reads filter on: a `@Field({ name })` mismatch would leave the row visible.
293
- const column = this.dialect.resolveColumnName(softDelete, field);
294
- const update = { $set: { [column]: getSoftDeleteValue(field) } };
295
- const filter = this.dialect.where(entity, qm.$where, opts);
296
- const { matchedCount } = await this.execute((session) => this.collection(entity).updateMany(filter, update, { session }));
297
- return matchedCount;
298
- });
263
+ const { stamp, opts: read } = deletionOf(getMeta(entity), opts);
264
+ const filter = this.dialect.where(entity, qm.$where, read);
265
+ if (!stamp) {
266
+ const { deletedCount } = await this.execute('internalDeleteMany', (session) => this.collection(entity).deleteMany(filter, { session }));
267
+ return deletedCount;
268
+ }
269
+ // The mapped column, which reads filter on: a `@Field({ name })` mismatch would leave the row visible.
270
+ const column = this.dialect.resolveColumnName(stamp.key, stamp.field);
271
+ const update = { $set: { [column]: stamp.value() } };
272
+ const { matchedCount } = await this.execute('internalDeleteMany', (session) => this.collection(entity).updateMany(filter, update, { session }));
273
+ return matchedCount;
299
274
  }
300
275
  get hasOpenTransaction() {
301
276
  return !!this.#session?.inTransaction();
302
277
  }
303
278
  /** Every read and write goes through here, which makes it where a released querier is caught. */
304
279
  collection(entity) {
305
- if (this.released) {
306
- throw new UqlUsageError('querier already released');
307
- }
280
+ this.assertActive();
308
281
  const { name } = getMeta(entity);
309
282
  return this.db.collection(name);
310
283
  }