uql-orm 0.107.2 → 0.108.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 (90) hide show
  1. package/README.md +0 -1
  2. package/dist/browser/uql-browser.min.js +2 -2
  3. package/dist/browser/uql-browser.min.js.map +5 -5
  4. package/dist/cockroachdb/cockroachDialect.d.ts +1 -4
  5. package/dist/cockroachdb/cockroachDialect.js +1 -5
  6. package/dist/dialect/abstractSqlDialect.d.ts +84 -43
  7. package/dist/dialect/abstractSqlDialect.js +270 -192
  8. package/dist/dialect/aliases.d.ts +2 -0
  9. package/dist/dialect/aliases.js +2 -0
  10. package/dist/dialect/jsonSql.d.ts +9 -7
  11. package/dist/dialect/jsonSql.js +16 -10
  12. package/dist/dialect/mergeSqlDialect.d.ts +5 -7
  13. package/dist/dialect/mergeSqlDialect.js +20 -19
  14. package/dist/dialect/mysqlLikeSqlDialect.d.ts +12 -6
  15. package/dist/dialect/mysqlLikeSqlDialect.js +34 -12
  16. package/dist/dialect/operators.d.ts +7 -1
  17. package/dist/dialect/operators.js +37 -2
  18. package/dist/dialect/pgLikeSqlDialect.d.ts +4 -4
  19. package/dist/dialect/pgLikeSqlDialect.js +8 -7
  20. package/dist/entity/index.d.ts +1 -1
  21. package/dist/entity/index.js +1 -1
  22. package/dist/entity/metadata/definedFixture/author.d.ts +4 -4
  23. package/dist/entity/metadata/definedFixture/book.d.ts +5 -5
  24. package/dist/entity/metadata/definition.d.ts +2 -0
  25. package/dist/entity/metadata/definition.js +19 -11
  26. package/dist/index.d.ts +1 -1
  27. package/dist/index.js +1 -1
  28. package/dist/mariadb/mariaDialect.d.ts +2 -2
  29. package/dist/mariadb/mariaDialect.js +3 -2
  30. package/dist/migrate/codegen/fieldOptionsSource.js +28 -7
  31. package/dist/migrate/ddl/defaultSql.d.ts +3 -2
  32. package/dist/migrate/ddl/defaultSql.js +8 -12
  33. package/dist/migrate/ddl/mysqlTableDdl.js +1 -1
  34. package/dist/migrate/ddl/tableDdl.d.ts +1 -1
  35. package/dist/migrate/drift/driftDetector.js +10 -3
  36. package/dist/migrate/introspection/abstractSqlSchemaIntrospector.d.ts +2 -2
  37. package/dist/migrate/introspection/mssqlIntrospector.d.ts +2 -2
  38. package/dist/migrate/introspection/mysqlIntrospector.d.ts +2 -2
  39. package/dist/migrate/introspection/postgresIntrospector.d.ts +2 -2
  40. package/dist/migrate/introspection/sqliteIntrospector.d.ts +2 -2
  41. package/dist/migrate/migrator.js +2 -1
  42. package/dist/migrate/schemaChange.d.ts +0 -2
  43. package/dist/migrate/schemaChange.js +1 -4
  44. package/dist/migrate/schemaGenerator.d.ts +2 -2
  45. package/dist/migrate/triggerSql.js +11 -15
  46. package/dist/mongodb/mongoDialect.d.ts +6 -1
  47. package/dist/mongodb/mongoDialect.js +90 -46
  48. package/dist/mongodb/mongoSchemaGenerator.js +2 -2
  49. package/dist/mongodb/mongodbQuerier.d.ts +7 -9
  50. package/dist/mongodb/mongodbQuerier.js +54 -47
  51. package/dist/mssql/mssqlDialect.d.ts +9 -9
  52. package/dist/mssql/mssqlDialect.js +51 -28
  53. package/dist/mssql/mssqlWireTypes.d.ts +1 -4
  54. package/dist/mssql/mssqlWireTypes.js +19 -10
  55. package/dist/querier/abstractQuerier.d.ts +53 -29
  56. package/dist/querier/abstractQuerier.js +154 -102
  57. package/dist/querier/abstractSqlQuerier.d.ts +41 -10
  58. package/dist/querier/abstractSqlQuerier.js +145 -79
  59. package/dist/schema/declaredColumn.js +2 -2
  60. package/dist/schema/schemaASTDiffer.d.ts +3 -3
  61. package/dist/schema/sqlExpression.d.ts +7 -5
  62. package/dist/schema/sqlExpression.js +20 -16
  63. package/dist/schema/types.d.ts +8 -2
  64. package/dist/sqlite/sqliteDialect.js +1 -2
  65. package/dist/type/definedEntity.d.ts +5 -5
  66. package/dist/type/dialect.d.ts +26 -15
  67. package/dist/type/entity.d.ts +14 -8
  68. package/dist/type/query.d.ts +7 -2
  69. package/dist/type/queryAggregate.d.ts +4 -4
  70. package/dist/type/querySql.d.ts +4 -1
  71. package/dist/type/querySql.js +5 -1
  72. package/dist/type/queryWhere.d.ts +16 -11
  73. package/dist/type/universalQuerier.d.ts +7 -7
  74. package/dist/util/ddlExpression.util.d.ts +5 -0
  75. package/dist/util/ddlExpression.util.js +9 -2
  76. package/dist/util/dialect.util.d.ts +14 -6
  77. package/dist/util/dialect.util.js +17 -13
  78. package/dist/util/field.util.d.ts +12 -0
  79. package/dist/util/field.util.js +17 -1
  80. package/dist/util/fieldOption.util.js +5 -1
  81. package/dist/util/object.util.d.ts +4 -0
  82. package/dist/util/object.util.js +13 -0
  83. package/dist/util/query.util.d.ts +5 -3
  84. package/dist/util/query.util.js +7 -2
  85. package/dist/util/sql.d.ts +25 -7
  86. package/dist/util/sql.js +58 -18
  87. package/dist/util/triggerWrite.d.ts +7 -4
  88. package/dist/util/triggerWrite.js +5 -4
  89. package/package.json +1 -1
  90. package/skills/uql-orm/SKILL.md +118 -118
@@ -6,7 +6,7 @@ import { aggregateColumnField, groupPathField, resolveGroupJoins, relationSortTe
6
6
  import { assertSoleId, fieldOf, getMeta, relationOf, soleIdOf } from '../entity/index.js';
7
7
  import { referenceKeys } from '../entity/metadata/definition.js';
8
8
  import { COUNT_RESULT_KEY } from '../type/query.js';
9
- import { QuerySql } from '../type/querySql.js';
9
+ import { ColumnRef, QuerySql, REF_ENTITY, REF_KEY } from '../type/querySql.js';
10
10
  import { aggregateOf, isSelectList, assertAggregateColumns, assertNoUndefined, assertNonNegativeInteger, columnFamily, countedRelations, entityName, fieldUpdateOf, fillOnFields, filterFieldKeys, findVectorIndex, findVectorSort, definedEntries, getKeys, holdsForeignKey, jsonPathKeys, getRelationRequestSummary, hasKeys, isFieldUpdateOp, isJsonObject, foldJson, writesKeys, isJsonUpdateOp, isOperatorMap, isOperatorObject, isRecord, isVectorSearch, normalizeScalarFieldSelection, parentJoins, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortDirection, rankedTextSearch, someKey, targetJoins, textSortOf, indexedDistance, vectorDistanceOf, vectorCandidates, populatesRelations, cachedIn, } from '../util/index.js';
11
11
  import { UqlUsageError } from '../util/uqlError.js';
12
12
  import { decodeBigIntsExcept } from '../util/wideNumber.js';
@@ -96,8 +96,8 @@ export const mongoDialectFeatures = {
96
96
  supportsUnsigned: false,
97
97
  serverSideCursors: false,
98
98
  correlatedWrites: false,
99
- rowLocks: false, // its concurrency control is the transaction plus atomic document updates
100
- writeReturning: false,
99
+ rowLocks: false, // its concurrency control is atomic document updates, plus a transaction the caller opens
100
+ reportsWrites: [],
101
101
  nullsSortLowest: true,
102
102
  };
103
103
  /** What `toWireId` converts: the hex spelling of an `ObjectId`, and nothing looser. */
@@ -111,6 +111,38 @@ function assertNoRaw(value, place) {
111
111
  throw rawRefusal(place);
112
112
  }
113
113
  }
114
+ /** Whether a field's condition compares it with SQL anywhere, a ref most often: in a list or under an operator. */
115
+ function holdsSql(value) {
116
+ if (value instanceof QuerySql) {
117
+ return true;
118
+ }
119
+ if (Array.isArray(value)) {
120
+ return value.some((element) => element instanceof QuerySql);
121
+ }
122
+ return (isOperatorObject(value) || isJsonObject(value)) && Object.values(value).some(holdsSql);
123
+ }
124
+ /**
125
+ * A field's condition split into what only an expression states, a comparison with SQL (a ref most often) or a
126
+ * bounded `$size`, where MongoDB's own takes a number alone, and the rest, which a query operator matches on the
127
+ * field's index; a value that is SQL is all the first.
128
+ */
129
+ function splitExpressed(val) {
130
+ if (!isOperatorObject(val)) {
131
+ return holdsSql(val) ? { expressed: val } : { rest: val };
132
+ }
133
+ const expressed = [];
134
+ const rest = [];
135
+ for (const [op, operand] of Object.entries(val)) {
136
+ (holdsSql(operand) || (op === '$size' && isRecord(operand)) ? expressed : rest).push([op, operand]);
137
+ }
138
+ if (!expressed.length) {
139
+ return { rest: val };
140
+ }
141
+ return {
142
+ expressed: Object.fromEntries(expressed),
143
+ rest: rest.length ? Object.fromEntries(rest) : undefined,
144
+ };
145
+ }
114
146
  /** How a declared column type reads in a message: `Number`, `uuid` - not its whole source. */
115
147
  function declaredTypeName(type) {
116
148
  return typeof type === 'function' ? type.name : String(type);
@@ -170,12 +202,15 @@ function anyElement(ref, test) {
170
202
  }
171
203
  /**
172
204
  * Whether `ref` holds a value of `operand`'s type, the only one a query's ordering compares it with: an
173
- * expression orders across types, every string above a number and a null below it.
205
+ * expression orders across types, every string above a number and a null below it. Another field, `other`,
206
+ * may hold a number of another width, an int against a double, which still compares.
174
207
  */
175
- function sameType(ref, operand) {
176
- return typeof operand === 'number' || typeof operand === 'bigint'
177
- ? { $isNumber: ref }
178
- : { $eq: [{ $type: ref }, { $type: literal(operand) }] };
208
+ function sameType(ref, operand, other) {
209
+ if (typeof operand === 'number' || typeof operand === 'bigint') {
210
+ return { $isNumber: ref };
211
+ }
212
+ const typed = { $eq: [{ $type: ref }, { $type: other }] };
213
+ return operand instanceof ColumnRef ? { $or: [{ $and: [{ $isNumber: ref }, { $isNumber: other }] }, typed] } : typed;
179
214
  }
180
215
  /** Whether the string at `ref` matches `regex`. Any other value matches none, where `$regexMatch` would fail. */
181
216
  function regexMatch(ref, regex, insensitive = false) {
@@ -285,7 +320,6 @@ export class MongoDialect extends AbstractDialect {
285
320
  andExpr(filter, this.relationExpression(meta, key, val, lookup));
286
321
  }
287
322
  else {
288
- assertNoRaw(val, '$where');
289
323
  this.assertKnownPathRoot(meta, key);
290
324
  if (aggregateOf(meta.fields[key])) {
291
325
  if (!lookup) {
@@ -295,25 +329,17 @@ export class MongoDialect extends AbstractDialect {
295
329
  }
296
330
  const keyed = this.holdsKeys(meta, key);
297
331
  key = this.pathOf(meta, key);
298
- if (!isOperatorObject(val)) {
299
- const wire = keyed ? this.toWireId(val) : val;
300
- filter[key] = Array.isArray(wire) ? { $in: wire } : wire;
301
- continue;
332
+ const { expressed, rest } = splitExpressed(val);
333
+ if (expressed !== undefined) {
334
+ andExpr(filter, this.fieldExpression(`$${key}`, expressed, this.operandOf(meta, keyed, '$where')));
302
335
  }
303
- const operators = (ops) => {
304
- const native = this.transformOperators(ops);
305
- return keyed ? this.toWireOperands(native) : native;
306
- };
307
- // MongoDB's `$size` takes only a number, so bounds become an `$expr` beside the other operators.
308
- const { $size: size, ...ops } = val;
309
- if (!isRecord(size)) {
310
- filter[key] = operators(val);
336
+ if (isOperatorObject(rest)) {
337
+ const operators = this.transformOperators(rest);
338
+ filter[key] = keyed ? this.toWireOperands(operators) : operators;
311
339
  }
312
- else {
313
- andExpr(filter, arraySize(`$${key}`, size));
314
- if (hasKeys(ops)) {
315
- filter[key] = operators(ops);
316
- }
340
+ else if (expressed === undefined) {
341
+ const wire = keyed ? this.toWireId(rest) : rest;
342
+ filter[key] = Array.isArray(wire) ? { $in: wire } : wire;
317
343
  }
318
344
  }
319
345
  }
@@ -1368,8 +1394,8 @@ export class MongoDialect extends AbstractDialect {
1368
1394
  return negate ? { $not: [{ [join]: clauses }] } : { [join]: clauses };
1369
1395
  }
1370
1396
  const val = where[key];
1371
- assertNoRaw(val, 'an aggregate $where');
1372
1397
  if (meta.relations[key]) {
1398
+ assertNoRaw(val, 'an aggregate $where');
1373
1399
  return this.relationExpression(meta, key, val, lookup);
1374
1400
  }
1375
1401
  if (key.startsWith('$')) {
@@ -1377,23 +1403,23 @@ export class MongoDialect extends AbstractDialect {
1377
1403
  }
1378
1404
  this.assertKnownPathRoot(meta, key);
1379
1405
  this.appendAggregateField(meta, key, lookup);
1380
- const wire = this.holdsKeys(meta, key) ? (value) => this.toWireId(value) : undefined;
1381
- return this.fieldExpression(`$${this.pathOf(meta, key)}`, val, wire);
1406
+ const read = this.operandOf(meta, this.holdsKeys(meta, key), 'an aggregate $where');
1407
+ return this.fieldExpression(`$${this.pathOf(meta, key)}`, val, read);
1382
1408
  });
1383
1409
  return allOf(terms);
1384
1410
  }
1385
1411
  /**
1386
1412
  * One field's condition as an expression, read as {@link transformOperators} reads it in a query: a value
1387
- * it equals, a list it is in, or operators. `wire` converts what a key field is compared with.
1413
+ * it equals, a list it is in, or operators. `read` reads what the field is compared with.
1388
1414
  */
1389
- fieldExpression(ref, val, wire = (value) => value) {
1390
- const equals = (value) => (value === null ? isNullExpr(ref) : { $eq: [ref, literal(wire(value))] });
1415
+ fieldExpression(ref, val, read = literal) {
1416
+ const equals = (value) => (value === null ? isNullExpr(ref) : { $eq: [ref, read(value)] });
1391
1417
  const within = (op, values) => ({
1392
- $in: [{ $ifNull: [ref, null] }, literal(wire(inOperands(op, values)))],
1418
+ $in: [{ $ifNull: [ref, null] }, inOperands(op, values).map(read)],
1393
1419
  });
1394
- const ordered = (op, operand) => {
1395
- const value = wire(operand);
1396
- return { $and: [sameType(ref, value), { [op]: [ref, literal(value)] }] };
1420
+ const ordered = (op, value) => {
1421
+ const other = read(value);
1422
+ return { $and: [sameType(ref, value, other), { [op]: [ref, other] }] };
1397
1423
  };
1398
1424
  if (!isOperatorObject(val)) {
1399
1425
  return Array.isArray(val) ? within('$in', val) : equals(val);
@@ -1409,7 +1435,7 @@ export class MongoDialect extends AbstractDialect {
1409
1435
  case '$ne':
1410
1436
  return { $not: [equals(operand)] };
1411
1437
  case '$not':
1412
- return { $not: [this.fieldExpression(ref, operand, wire)] };
1438
+ return { $not: [this.fieldExpression(ref, operand, read)] };
1413
1439
  case '$gt':
1414
1440
  case '$gte':
1415
1441
  case '$lt':
@@ -1427,13 +1453,14 @@ export class MongoDialect extends AbstractDialect {
1427
1453
  case '$isNotNull':
1428
1454
  return (op === '$isNull') === Boolean(operand) ? equals(null) : { $not: [equals(null)] };
1429
1455
  case '$regex':
1456
+ assertNoRaw(operand, '$where');
1430
1457
  return regexMatch(ref, String(operand));
1431
1458
  case '$size':
1432
1459
  return arraySize(ref, operand);
1433
1460
  case '$all':
1434
- return this.allHeld(ref, inOperands(op, operand));
1461
+ return this.allHeld(ref, inOperands(op, operand), read);
1435
1462
  case '$elemMatch':
1436
- return this.allHeld(ref, [operand]);
1463
+ return this.allHeld(ref, [operand], read);
1437
1464
  case '$near':
1438
1465
  throw nearRefusal();
1439
1466
  default:
@@ -1442,27 +1469,44 @@ export class MongoDialect extends AbstractDialect {
1442
1469
  });
1443
1470
  return allOf(terms);
1444
1471
  }
1472
+ /**
1473
+ * How what a field of `meta` is compared with reads in an expression, the one reader of it on every path: a ref
1474
+ * as the field it names, of the same document; any other SQL refused; a value as itself, a key's in its wire form.
1475
+ */
1476
+ operandOf(meta, keyed, place) {
1477
+ return (value) => {
1478
+ if (!(value instanceof ColumnRef)) {
1479
+ assertNoRaw(value, place);
1480
+ return literal(keyed ? this.toWireId(value) : value);
1481
+ }
1482
+ const owner = value[REF_ENTITY];
1483
+ if (owner && owner !== meta.entity) {
1484
+ throw new UqlUsageError(`MongoDB compares a field of '${entityName(meta)}' with another of its own document, not of '${entityName(getMeta(owner))}'`);
1485
+ }
1486
+ return `$${this.pathOf(meta, value[REF_KEY])}`;
1487
+ };
1488
+ }
1445
1489
  /**
1446
1490
  * What `ref` satisfies to hold `value`, as {@link held} reads it in a query: an array each of its
1447
1491
  * elements, an object each of its keys as a path, anything else as a field condition.
1448
1492
  */
1449
- heldExpression(ref, value) {
1493
+ heldExpression(ref, value, read) {
1450
1494
  if (Array.isArray(value)) {
1451
- return this.allHeld(ref, value);
1495
+ return this.allHeld(ref, value, read);
1452
1496
  }
1453
1497
  if (isJsonObject(value)) {
1454
- return allOf(Object.entries(value).map(([key, item]) => this.heldExpression(`${ref}.${key}`, item)));
1498
+ return allOf(Object.entries(value).map(([key, item]) => this.heldExpression(`${ref}.${key}`, item, read)));
1455
1499
  }
1456
- return this.fieldExpression(ref, value);
1500
+ return this.fieldExpression(ref, value, read);
1457
1501
  }
1458
1502
  /**
1459
1503
  * `$all`, as {@link allHolding} reads it: the array at `ref` has an element holding each value, a scalar
1460
1504
  * by `$in`, which stops at the first match where testing each element would map them all.
1461
1505
  */
1462
- allHeld(ref, values) {
1506
+ allHeld(ref, values, read) {
1463
1507
  return allOf(values.map((value) => isOperatorMap(value) || Array.isArray(value)
1464
- ? anyElement(ref, this.heldExpression('$$this', value))
1465
- : { $cond: [{ $isArray: ref }, { $in: [literal(value), ref] }, false] }));
1508
+ ? anyElement(ref, this.heldExpression('$$this', value, read))
1509
+ : { $cond: [{ $isArray: ref }, { $in: [read(value), ref] }, false] }));
1466
1510
  }
1467
1511
  buildHavingFilter(having) {
1468
1512
  const filter = {};
@@ -8,7 +8,7 @@ import { sides } from '../migrate/schemaChange.js';
8
8
  import { indexChanges } from '../schema/indexDifferences.js';
9
9
  import { QuerySql, } from '../type/index.js';
10
10
  import { indexDistance, unsupportedVectorMetric } from '../type/vector.js';
11
- import { declaredIndexes, renderIndex } from '../util/ddlExpression.util.js';
11
+ import { declaredIndexes, renderIndex, sortedEnum } from '../util/ddlExpression.util.js';
12
12
  import { findVectorIndex, fulltextConfig, fulltextWeights, indexedDistance } from '../util/dialect.util.js';
13
13
  import { entryKeys, entryModifiers, renamedEntry } from '../util/indexEntry.util.js';
14
14
  import { definedEntries, hasKeys } from '../util/object.util.js';
@@ -101,7 +101,7 @@ export class MongoSchemaGenerator extends MongoDialect {
101
101
  validatorOf(meta, collectionName) {
102
102
  const clauses = [
103
103
  ...(meta.checks ?? []).map(({ where }) => this.checkFilter(where, meta.entity, collectionName)),
104
- ...definedEntries(meta.fields).flatMap(([key, field]) => field.enum ? [{ [this.columnOf(meta, key)]: { $in: [...field.enum, null] } }] : []),
104
+ ...definedEntries(meta.fields).flatMap(([key, field]) => field.enum ? [{ [this.columnOf(meta, key)]: { $in: [...sortedEnum(field.enum), null] } }] : []),
105
105
  ].filter(hasKeys);
106
106
  return clauses.length > 1 ? { $and: clauses } : clauses[0];
107
107
  }
@@ -1,7 +1,7 @@
1
1
  import type { ClientSession, Document, MongoClient } from 'mongodb';
2
2
  import type { UpsertedId } from '../querier/abstractQuerier.js';
3
3
  import { AbstractQuerier } from '../querier/index.js';
4
- import type { EntityData, ExtraOptions, Query, QueryAggregate, QueryConflictPaths, QueryPage, QueryOptions, QuerySearch, RawRow, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
4
+ import type { EntityData, ExtraOptions, Query, QueryAggregate, QueryUpsert, QueryPage, QueryOptions, QuerySearch, RawRow, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
5
5
  import type { MongoDialect } from './mongoDialect.js';
6
6
  import type { MongoQuerier } from './mongoQuerier.js';
7
7
  export declare class MongodbQuerier extends AbstractQuerier implements MongoQuerier {
@@ -41,24 +41,22 @@ export declare class MongodbQuerier extends AbstractQuerier implements MongoQuer
41
41
  estimatedCount<E extends Document>(entity: Type<E>): Promise<number>;
42
42
  internalInsertMany<E extends Document>(entity: Type<E>, rows: EntityData<E>[]): Promise<void>;
43
43
  internalUpdateMany<E extends Document>(entity: Type<E>, qm: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
44
+ /** The filter and update of an update of the documents matching `where` with `payload`, its `onUpdate` fills included. */
45
+ private updateOperation;
44
46
  /**
45
47
  * What an upsert writes, as SQL's does: a found document takes the payload and the `onUpdate` fills, and only
46
48
  * an inserted one the `onInsert` fills and the key, which is immutable, so in `$set` it would refuse every match.
49
+ * Updating a found document `apart`, it writes only an inserted one.
47
50
  */
48
51
  private upsertUpdate;
49
- private buildConflictFilter;
50
- /**
51
- * An upsert of `row` whose found document takes `update`, which no single call pairs with inserting the payload:
52
- * `$setOnInsert` and `$inc` on one field conflict. So the row inserts if absent, and a document it found, a
53
- * concurrent one included, then takes `update`.
54
- */
55
- private upsertWithUpdate;
56
- protected internalUpsertMany<E extends Document>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E[], update?: UpdatePayload<E>): Promise<(UpsertedId<E> | undefined)[]>;
52
+ protected internalUpsertMany<E extends Document>(entity: Type<E>, q: QueryUpsert<E>, payload: E[], update?: UpdatePayload<E>): Promise<(UpsertedId<E> | undefined)[]>;
57
53
  protected internalDeleteMany<E extends Document>(entity: Type<E>, qm: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
58
54
  get hasOpenTransaction(): boolean;
59
55
  /** Every read and write goes through here, which makes it where a released querier is caught. */
60
56
  collection<E extends Document>(entity: Type<E>): import("mongodb").Collection<E>;
61
57
  get db(): import("mongodb").Db;
58
+ /** Runs `write` as its steps: a multi-step write is atomic only inside a transaction the caller opens. */
59
+ protected atomically<T>(write: () => Promise<T>): Promise<T>;
62
60
  protected openTransaction(_opts?: TransactionOptions): Promise<void>;
63
61
  /**
64
62
  * The driver owns the transaction state here and settles it in its own `finally`, so a failed commit
@@ -1,8 +1,8 @@
1
1
  import { AGGREGATE_VALUE_ALIAS } from '../dialect/aliases.js';
2
2
  import { hasRequiredJoin } from '../dialect/queryJoins.js';
3
- import { getMeta, soleIdOf } from '../entity/index.js';
3
+ import { getMeta, namesEvery, soleIdOf } from '../entity/index.js';
4
4
  import { AbstractQuerier } from '../querier/index.js';
5
- import { clone, getKeys, deletionOf, hasKeys, hasTriggers, whereEach, upsertKeepsOwnKey } from '../util/index.js';
5
+ import { clone, deletionOf, foundRowWhere, foundRowAssigned, getKeys, hasKeys, hasTriggers, upsertKeepsOwnKey, withDeleted, } 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)`
@@ -152,21 +152,29 @@ export class MongodbQuerier extends AbstractQuerier {
152
152
  }
153
153
  async internalUpdateMany(entity, qm, payload, opts) {
154
154
  refuseTriggers(entity);
155
- const persistable = this.dialect.getPersistable(getMeta(entity), payload, 'onUpdate');
156
- const filter = this.dialect.where(entity, qm.$where, opts);
157
- const update = this.dialect.getUpdateFilter(persistable);
155
+ const { filter, update } = this.updateOperation(entity, qm.$where, payload, opts);
158
156
  const { matchedCount } = await this.execute('internalUpdateMany', (session) => this.collection(entity).updateMany(filter, update, { session }));
159
157
  return matchedCount;
160
158
  }
159
+ /** The filter and update of an update of the documents matching `where` with `payload`, its `onUpdate` fills included. */
160
+ updateOperation(entity, where, payload, opts) {
161
+ const persistable = this.dialect.getPersistable(getMeta(entity), payload, 'onUpdate');
162
+ return { filter: this.dialect.where(entity, where, opts), update: this.dialect.getUpdateFilter(persistable) };
163
+ }
161
164
  /**
162
165
  * What an upsert writes, as SQL's does: a found document takes the payload and the `onUpdate` fills, and only
163
166
  * an inserted one the `onInsert` fills and the key, which is immutable, so in `$set` it would refuse every match.
167
+ * Updating a found document `apart`, it writes only an inserted one.
164
168
  */
165
- upsertUpdate(meta, payload) {
166
- const updated = this.dialect.getPersistable(meta, clone(payload), 'onUpdate');
169
+ upsertUpdate(meta, payload, apart) {
167
170
  const inserted = this.dialect.getPersistable(meta, clone(payload), 'onInsert');
168
- const insertOnly = Object.fromEntries(Object.entries(inserted).filter(([column]) => !(column in updated)));
169
171
  const update = {};
172
+ if (apart) {
173
+ update['$setOnInsert'] = inserted;
174
+ return update;
175
+ }
176
+ const updated = this.dialect.getPersistable(meta, clone(payload), 'onUpdate');
177
+ const insertOnly = Object.fromEntries(Object.entries(inserted).filter(([column]) => !(column in updated)));
170
178
  if (hasKeys(updated)) {
171
179
  update['$set'] = updated;
172
180
  }
@@ -175,54 +183,49 @@ export class MongodbQuerier extends AbstractQuerier {
175
183
  }
176
184
  return update;
177
185
  }
178
- buildConflictFilter(entity, conflictPaths, item) {
179
- return this.dialect.where(entity, whereEach(getKeys(conflictPaths), (key) => item[key]));
180
- }
181
- /**
182
- * An upsert of `row` whose found document takes `update`, which no single call pairs with inserting the payload:
183
- * `$setOnInsert` and `$inc` on one field conflict. So the row inserts if absent, and a document it found, a
184
- * concurrent one included, then takes `update`.
185
- */
186
- async upsertWithUpdate(entity, conflictPaths, row, update) {
187
- const persistable = this.dialect.getPersistable(getMeta(entity), clone(row), 'onInsert');
188
- const filter = this.buildConflictFilter(entity, conflictPaths, row);
189
- const res = await this.execute('upsertMany', (session) => this.collection(entity).findOneAndUpdate(filter, { $setOnInsert: persistable }, { upsert: true, returnDocument: 'after', includeResultMetadata: true, session }));
190
- // `updatedExisting` is false where the document was inserted; an empty `update` leaves a found one
191
- // as it is, as `DO NOTHING` does.
192
- if (res.lastErrorObject?.['updatedExisting'] && hasKeys(update)) {
193
- await this.internalUpdateMany(entity, { $where: whereEach(getKeys(conflictPaths), (key) => row[key]) }, update);
194
- }
195
- return this.dialect.fromWireId(res.value?._id);
196
- }
197
- async internalUpsertMany(entity, conflictPaths, payload, update) {
186
+ async internalUpsertMany(entity, q, payload, update) {
198
187
  refuseTriggers(entity);
199
- if (update) {
200
- const ids = [];
201
- for (const row of payload) {
202
- ids.push(await this.upsertWithUpdate(entity, conflictPaths, row, update));
203
- }
204
- return ids;
205
- }
206
188
  if (!payload.length) {
207
189
  return [];
208
190
  }
191
+ // A found document is updated apart from the insert when the upsert has an update of its own, as `$setOnInsert`
192
+ // and `$inc` on one field conflict in one operation, or a `$where`. The two batches are not atomic on their own:
193
+ // a transaction the caller opens makes them so.
194
+ const apart = update !== undefined || q.$where !== undefined;
209
195
  const meta = getMeta(entity);
210
- const kept = payload.map((row) => upsertKeepsOwnKey(meta, conflictPaths, row));
211
- const operations = payload.map((item) => ({
212
- updateOne: {
213
- filter: this.buildConflictFilter(entity, conflictPaths, item),
214
- update: this.upsertUpdate(meta, item),
215
- upsert: true,
216
- },
217
- }));
218
- const res = await this.execute('upsertMany', (session) => this.collection(entity).bulkWrite(operations, { session }));
219
- // `upsertedIds` names only the documents inserted, keyed by operation index, so each lands on
196
+ const conflictKeys = q.$conflict;
197
+ const kept = payload.map((row) => upsertKeepsOwnKey(meta, conflictKeys, row));
198
+ // A row naming no conflict key conflicts with none, so it inserts, as `ON CONFLICT` inserts it; a soft-deleted
199
+ // document conflicts as any other does, its unique key holding across both.
200
+ const keys = getKeys(conflictKeys);
201
+ const upserts = payload.map((row) => !namesEvery(row, keys)
202
+ ? { insertOne: { document: this.dialect.getPersistable(meta, clone(row), 'onInsert') } }
203
+ : {
204
+ updateOne: {
205
+ filter: this.dialect.where(entity, foundRowWhere({ $conflict: conflictKeys }, row), withDeleted()),
206
+ update: this.upsertUpdate(meta, row, apart),
207
+ upsert: true,
208
+ },
209
+ });
210
+ const res = await this.execute('upsertMany', (session) => this.collection(entity).bulkWrite(upserts, { session }));
211
+ // `upsertedIds` and `insertedIds` name only the documents inserted, keyed by operation index, so each lands on
220
212
  // its own row; an updated document's `_id` is read back by the conflict fields instead.
221
213
  const reported = payload.map((_, index) => {
222
- const id = res.upsertedIds[index];
214
+ const id = res.upsertedIds[index] ?? res.insertedIds[index];
223
215
  return id === undefined ? undefined : this.dialect.fromWireId(id);
224
216
  });
225
- return this.withUnreportedIds(entity, conflictPaths, payload, reported, kept);
217
+ const updates = apart
218
+ ? payload.flatMap((row, index) => {
219
+ const assigned = reported[index] === undefined && foundRowAssigned(meta, conflictKeys, row, update);
220
+ return assigned
221
+ ? [{ updateOne: this.updateOperation(entity, foundRowWhere(q, row), assigned, withDeleted()) }]
222
+ : [];
223
+ })
224
+ : [];
225
+ if (updates.length) {
226
+ await this.execute('upsertMany', (session) => this.collection(entity).bulkWrite(updates, { session }));
227
+ }
228
+ return this.withUnreportedIds(entity, conflictKeys, payload, reported, kept);
226
229
  }
227
230
  async internalDeleteMany(entity, qm, opts = {}) {
228
231
  refuseTriggers(entity);
@@ -250,6 +253,10 @@ export class MongodbQuerier extends AbstractQuerier {
250
253
  get db() {
251
254
  return this.conn.db();
252
255
  }
256
+ /** Runs `write` as its steps: a multi-step write is atomic only inside a transaction the caller opens. */
257
+ atomically(write) {
258
+ return write();
259
+ }
253
260
  async openTransaction(_opts) {
254
261
  this.logger.logInfo('startTransaction');
255
262
  await this.#session?.endSession();
@@ -1,7 +1,7 @@
1
1
  import { type RelationRows, type SelectTerm } from '../dialect/abstractSqlDialect.js';
2
2
  import { type JsonAccessMode, type JsonContainer, type JsonKeyWrite, type JsonSlot } from '../dialect/jsonSql.js';
3
3
  import { MergeSqlDialect } from '../dialect/mergeSqlDialect.js';
4
- import type { EntityMeta, SavepointCommand, FieldOptions, Query, QueryConflictPaths, QueryContext, QueryOptions, QueryPager, SqlDialectFeatures, SqlValues, TriggerRows, AbstractType, UpdatePayload, VectorDistance, VectorMetric, TransactionOptions } from '../type/index.js';
4
+ import type { FieldKey, ReportedWrite, EntityMeta, SavepointCommand, FieldOptions, Query, QueryUpsert, QueryContext, QueryPager, SqlDialectFeatures, SqlValues, TriggerRows, AbstractType, UpdatePayload, VectorDistance, VectorMetric, TransactionOptions } from '../type/index.js';
5
5
  /** Microsoft SQL Server 2017 and up. Identifiers are `"`-quoted, the ANSI spelling `tedious` enables. */
6
6
  export declare class MsSqlDialect extends MergeSqlDialect {
7
7
  #private;
@@ -48,7 +48,7 @@ export declare class MsSqlDialect extends MergeSqlDialect {
48
48
  pager(ctx: QueryContext, opts: QueryPager & {
49
49
  $distinct?: boolean;
50
50
  }, sorted?: boolean): void;
51
- insert<E>(ctx: QueryContext, entity: AbstractType<E>, payload: E | E[], opts?: QueryOptions): void;
51
+ insert<E>(ctx: QueryContext, entity: AbstractType<E>, payload: E | E[], returning?: readonly FieldKey<E>[]): readonly SelectTerm[];
52
52
  /** The table to toggle, or nothing when no record writes a key the engine would have generated. */
53
53
  private identityInsertTarget;
54
54
  /** An exact decimal, converted before it crosses the wire, where `tedious` would round it. */
@@ -76,15 +76,15 @@ export declare class MsSqlDialect extends MergeSqlDialect {
76
76
  * carrying a trigger, and through a table it works whether one is there or not.
77
77
  */
78
78
  returningId<E>(meta: EntityMeta<E>): string;
79
- upsert<E>(ctx: QueryContext, entity: AbstractType<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[], update?: UpdatePayload<E>): void;
79
+ upsert<E>(ctx: QueryContext, entity: AbstractType<E>, q: QueryUpsert<E>, payload: E | E[], update?: UpdatePayload<E>, returning?: readonly FieldKey<E>[]): readonly SelectTerm[];
80
80
  /**
81
- * A statement writing rows, `write`, wrapped in what SQL Server needs around one. The table variable its
82
- * `OUTPUT` fills, typed as the id column is, and the read handing that back, uncounted so the batch
83
- * reports the rows written alone; none on a composite key, which has no id to hand back. And `SET
84
- * IDENTITY_INSERT` where a row states a key the engine would generate, turned off in the same batch.
81
+ * `OUTPUT` the columns `returning` reads `INTO` a table variable typed as they are, every stored one where it names an
82
+ * inlined field, then the fields read off it as off the table. Through a table, as `OUTPUT` straight back to the
83
+ * client fails on a table carrying a trigger.
85
84
  */
86
- private writeRows;
87
- protected mergeReturning(expression: string): string;
85
+ protected reportedWrite<E>(ctx: QueryContext, entity: AbstractType<E>, returning: readonly FieldKey<E>[] | undefined, write: ReportedWrite, render: (afterTarget: string) => void): readonly SelectTerm[];
86
+ /** `write` between `SET IDENTITY_INSERT` on and off, where a row states a key the engine would generate. */
87
+ private identityInserted;
88
88
  /** A row lock is a hint on the table here, which `rowLocks.placement` says instead of a trailing clause. */
89
89
  protected lockHint<E>(q: Query<E>): string;
90
90
  /**
@@ -1,5 +1,5 @@
1
1
  import { ANSI_SQL_VALUES, fromRows, relationTermKey, isolationSetBefore, } from '../dialect/abstractSqlDialect.js';
2
- import { AGGREGATE_VALUE_ALIAS, JSON_PULL_ALIAS, OUTPUT_TABLE } from '../dialect/aliases.js';
2
+ import { AGGREGATE_VALUE_ALIAS, JSON_PULL_ALIAS, OUTPUT_ALIAS, OUTPUT_TABLE } from '../dialect/aliases.js';
3
3
  import { BYTES_PREFIX } from '../dialect/hydrateColumn.js';
4
4
  import { skippablePath, jsonArraySlotArgs, jsonPath, jsonSlotArgs, } from '../dialect/jsonSql.js';
5
5
  import { MergeSqlDialect } from '../dialect/mergeSqlDialect.js';
@@ -9,8 +9,8 @@ import { canonicalToSql, resolveColumnCanonicalType } from '../schema/canonicalT
9
9
  import { QuerySql } from '../type/index.js';
10
10
  import { parseQueryLock } from '../type/index.js';
11
11
  import { bytesToHex } from '../util/bytes.js';
12
- import { isExactDecimal, jsonPathKeys } from '../util/field.util.js';
13
- import { assertNonNegativeInteger, isOperatorMap, RETURNED_ID } from '../util/index.js';
12
+ import { isExactDecimal, isInlinedExpression, jsonPathKeys } from '../util/field.util.js';
13
+ import { assertNonNegativeInteger, definedEntries, isOperatorMap, keySet, RETURNED_ID } from '../util/index.js';
14
14
  import { escapeSingleQuotes } from '../util/sqlLiteral.js';
15
15
  import { UqlUsageError } from '../util/uqlError.js';
16
16
  /** What SQL Server has. */
@@ -31,11 +31,10 @@ const MSSQL_FEATURES = {
31
31
  serverSideCursors: false,
32
32
  correlatedWrites: true,
33
33
  rowLocks: { of: true, withWindow: true, placement: 'tableHint' },
34
- writeReturning: false,
34
+ reportsWrites: ['insert', 'update', 'delete', 'upsert'],
35
35
  nullsSortLowest: true,
36
36
  nullsOrdering: 'case',
37
37
  textScoreIndexes: false,
38
- orderedUpsertReturning: false,
39
38
  orderedJsonAggregates: true,
40
39
  narrowVectorTypes: false,
41
40
  vectorTuningNeedsTransaction: false,
@@ -141,11 +140,23 @@ export class MsSqlDialect extends MergeSqlDialect {
141
140
  }
142
141
  super.pager(ctx, opts, sorted);
143
142
  }
144
- insert(ctx, entity, payload, opts) {
145
- this.writeRows(ctx, getMeta(entity), payload, () => {
146
- super.insert(ctx, entity, payload, opts);
143
+ insert(ctx, entity, payload, returning) {
144
+ const meta = getMeta(entity);
145
+ const id = returning ? undefined : soleId(meta);
146
+ const column = this.escapeId(RETURNED_ID);
147
+ if (id) {
148
+ ctx.append(`DECLARE ${OUTPUT_TABLE} TABLE (${column} ${canonicalToSql(resolveColumnCanonicalType(id.field), this)}); `);
149
+ }
150
+ const terms = this.identityInserted(ctx, meta, payload, () => {
151
+ const inserted = super.insert(ctx, entity, payload, returning);
147
152
  ctx.append(';');
153
+ return inserted;
148
154
  });
155
+ // Uncounted, so the batch reports the rows written alone.
156
+ if (id) {
157
+ ctx.append(` SET NOCOUNT ON; SELECT ${column} FROM ${OUTPUT_TABLE}; SET NOCOUNT OFF;`);
158
+ }
159
+ return terms;
149
160
  }
150
161
  /** The table to toggle, or nothing when no record writes a key the engine would have generated. */
151
162
  identityInsertTarget(meta, payload) {
@@ -193,37 +204,49 @@ export class MsSqlDialect extends MergeSqlDialect {
193
204
  */
194
205
  returningId(meta) {
195
206
  const expression = this.returningIdExpression(meta);
196
- return expression ? this.mergeReturning(expression) : '';
207
+ return expression ? `OUTPUT ${expression} INTO ${OUTPUT_TABLE}` : '';
197
208
  }
198
- upsert(ctx, entity, conflictPaths, payload, update) {
199
- this.writeRows(ctx, getMeta(entity), payload, () => super.upsert(ctx, entity, conflictPaths, payload, update));
209
+ upsert(ctx, entity, q, payload, update, returning) {
210
+ return this.identityInserted(ctx, getMeta(entity), payload, () => super.upsert(ctx, entity, q, payload, update, returning));
200
211
  }
201
212
  /**
202
- * A statement writing rows, `write`, wrapped in what SQL Server needs around one. The table variable its
203
- * `OUTPUT` fills, typed as the id column is, and the read handing that back, uncounted so the batch
204
- * reports the rows written alone; none on a composite key, which has no id to hand back. And `SET
205
- * IDENTITY_INSERT` where a row states a key the engine would generate, turned off in the same batch.
213
+ * `OUTPUT` the columns `returning` reads `INTO` a table variable typed as they are, every stored one where it names an
214
+ * inlined field, then the fields read off it as off the table. Through a table, as `OUTPUT` straight back to the
215
+ * client fails on a table carrying a trigger.
206
216
  */
207
- writeRows(ctx, meta, payload, write) {
208
- const id = soleId(meta);
209
- const column = this.escapeId(RETURNED_ID);
210
- const identity = this.identityInsertTarget(meta, payload);
211
- if (id) {
212
- ctx.append(`DECLARE ${OUTPUT_TABLE} TABLE (${column} ${canonicalToSql(resolveColumnCanonicalType(id.field), this)}); `);
217
+ reportedWrite(ctx, entity, returning, write, render) {
218
+ if (!returning) {
219
+ return super.reportedWrite(ctx, entity, returning, write, render);
213
220
  }
221
+ const source = write === 'delete' ? 'DELETED' : 'INSERTED';
222
+ const meta = getMeta(entity);
223
+ const named = new Set(returning);
224
+ const fields = definedEntries(meta.fields);
225
+ const inlined = fields.some(([key, field]) => named.has(key) && isInlinedExpression(field));
226
+ const columns = fields
227
+ .filter(([key, field]) => !isInlinedExpression(field) && (inlined || named.has(key)))
228
+ .map(([key, field]) => ({
229
+ name: this.escapedColumnName(meta, key),
230
+ type: canonicalToSql(resolveColumnCanonicalType(field), this),
231
+ }));
232
+ const names = columns.map(({ name }) => name).join(', ');
233
+ ctx.append(`DECLARE ${OUTPUT_TABLE} TABLE (${columns.map(({ name, type }) => `${name} ${type}`).join(', ')}); `);
234
+ render(`OUTPUT ${columns.map(({ name }) => `${source}.${name}`).join(', ')} INTO ${OUTPUT_TABLE} (${names})`);
235
+ const terms = this.selectTerms(ctx, entity, keySet(returning), { prefix: OUTPUT_ALIAS });
236
+ ctx.append(`; SELECT ${this.termsSql(terms)} FROM ${OUTPUT_TABLE} ${this.escapeId(OUTPUT_ALIAS)}`);
237
+ return terms;
238
+ }
239
+ /** `write` between `SET IDENTITY_INSERT` on and off, where a row states a key the engine would generate. */
240
+ identityInserted(ctx, meta, payload, write) {
241
+ const identity = this.identityInsertTarget(meta, payload);
214
242
  if (identity) {
215
243
  ctx.append(`SET IDENTITY_INSERT ${identity} ON; `);
216
244
  }
217
- write();
245
+ const terms = write();
218
246
  if (identity) {
219
247
  ctx.append(` SET IDENTITY_INSERT ${identity} OFF;`);
220
248
  }
221
- if (id) {
222
- ctx.append(` SET NOCOUNT ON; SELECT ${column} FROM ${OUTPUT_TABLE}; SET NOCOUNT OFF;`);
223
- }
224
- }
225
- mergeReturning(expression) {
226
- return `OUTPUT ${expression} INTO ${OUTPUT_TABLE}`;
249
+ return terms;
227
250
  }
228
251
  /** A row lock is a hint on the table here, which `rowLocks.placement` says instead of a trailing clause. */
229
252
  lockHint(q) {
@@ -2,9 +2,6 @@
2
2
  type ColumnTypes = Record<string, {
3
3
  readonly type: unknown;
4
4
  }>;
5
- /**
6
- * Decodes `BIGINT`, which `tedious` returns as text, by `decodeWideNumber`: `type: Number` maps to
7
- * BIGINT, so otherwise every generated key reads back as a string. At the wire, which every result crosses.
8
- */
5
+ /** Decodes the columns {@link DECODERS} names, at the wire, which every result crosses. */
9
6
  export declare function decodeWireTypes<T>(rows: T[] | undefined, columns: ColumnTypes | undefined): T[];
10
7
  export {};