uql-orm 0.102.1 → 0.102.3

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 (34) hide show
  1. package/dist/browser/uql-browser.min.js +2 -2
  2. package/dist/browser/uql-browser.min.js.map +2 -2
  3. package/dist/cockroachdb/cockroachDialect.d.ts +1 -1
  4. package/dist/cockroachdb/cockroachDialect.js +1 -1
  5. package/dist/dialect/abstractSqlDialect.d.ts +14 -13
  6. package/dist/dialect/abstractSqlDialect.js +33 -32
  7. package/dist/dialect/aliases.d.ts +5 -3
  8. package/dist/dialect/aliases.js +7 -3
  9. package/dist/dialect/jsonSql.d.ts +4 -0
  10. package/dist/dialect/jsonSql.js +9 -0
  11. package/dist/dialect/mysqlLikeSqlDialect.d.ts +2 -1
  12. package/dist/dialect/mysqlLikeSqlDialect.js +8 -3
  13. package/dist/dialect/pgLikeSqlDialect.d.ts +4 -3
  14. package/dist/dialect/pgLikeSqlDialect.js +10 -7
  15. package/dist/dialect/queryJoins.d.ts +1 -1
  16. package/dist/mariadb/mariaDialect.d.ts +2 -2
  17. package/dist/mariadb/mariaDialect.js +2 -2
  18. package/dist/mongodb/mongoDialect.d.ts +26 -20
  19. package/dist/mongodb/mongoDialect.js +178 -126
  20. package/dist/mssql/mssqlDialect.d.ts +8 -6
  21. package/dist/mssql/mssqlDialect.js +32 -20
  22. package/dist/sqlite/sqliteDialect.d.ts +1 -1
  23. package/dist/sqlite/sqliteDialect.js +3 -3
  24. package/dist/turso/tursoLocalDialect.d.ts +2 -2
  25. package/dist/turso/tursoLocalDialect.js +7 -5
  26. package/dist/type/entity.d.ts +25 -11
  27. package/dist/type/queryAggregate.d.ts +3 -6
  28. package/dist/type/utility.d.ts +2 -0
  29. package/dist/util/dialect.util.d.ts +13 -13
  30. package/dist/util/dialect.util.js +47 -13
  31. package/dist/util/object.util.d.ts +3 -3
  32. package/dist/util/object.util.js +1 -1
  33. package/package.json +3 -3
  34. package/skills/uql-orm/SKILL.md +1 -1
@@ -1,25 +1,40 @@
1
1
  import { ObjectId } from 'mongodb';
2
2
  import { AbstractDialect } from '../dialect/abstractDialect.js';
3
- import { AGGREGATE_VALUE_ALIAS, REL_NESTED_KEY, REL_TEMP_PREFIX, SUM_COUNT_ALIAS, nullsSortField, sortAggregateField, TEXT_SCORE_ALIAS, } from '../dialect/aliases.js';
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
4
  import { betweenBounds, GROUP_OPS, groupClauses, isGroupOp, LIKE_OPS, likeRegex, whereOperators, } 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, foldJsonUpdate, writesKeys, isJsonUpdateOp, isOperatorMap, isOperatorObject, isRecord, isVectorSearch, normalizeScalarFieldSelection, parentJoins, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortDirection, rankedTextSearch, someKey, targetJoins, textSortOf, vectorDistanceOf, } from '../util/index.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
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';
14
+ /** The field a lookup puts a relation's rows on, prefixed so a stored field of the same name (a Mongoose `ref`) survives. */
15
+ function relationField(relKey) {
16
+ return `${REL_FIELD_PREFIX}${relKey}`;
17
+ }
18
+ /** Where a join's rows are on the queried document: its relation's field, under its parent's. */
19
+ function joinedPath(join) {
20
+ return join.parent ? `${joinedPath(join.parent)}.${relationField(join.key)}` : relationField(join.key);
21
+ }
22
+ const mergeLookups = (lookups) => ({
23
+ stages: lookups.flatMap((lookup) => lookup.stages),
24
+ temps: lookups.flatMap((lookup) => lookup.temps),
25
+ });
26
+ const unsetOf = (temps) => temps.length ? [{ $unset: temps }] : [];
14
27
  /** A scalar field's operator as the aggregation operator computing it. */
15
28
  const MONGO_ARITHMETIC = { $inc: '$add', $mul: '$multiply' };
16
29
  /**
17
- * One array key's writes at `path`, as SQL writes them: the pull, then each append onto `[]` in place of a
30
+ * One array's writes at `path`, as SQL writes them: the pulls, then each append onto `[]` in place of a
18
31
  * missing or null array, a `unique` one only where the array lacks its item; a value that is no array stays.
19
32
  */
20
- function arrayWrite(path, { pull, appends }) {
33
+ function arrayWrite(path, { pulls, appends }) {
21
34
  const stored = `$${path}`;
22
- const kept = (array) => pull ? { $filter: { input: array, cond: { $ne: ['$$this', { $literal: pull.item }] } } } : array;
35
+ const kept = (array) => pulls.length > 0
36
+ ? { $filter: { input: array, cond: { $not: [{ $in: ['$$this', { $literal: pulls }] }] } } }
37
+ : array;
23
38
  if (appends.length === 0) {
24
39
  return { $cond: [{ $isArray: stored }, kept(stored), stored] };
25
40
  }
@@ -193,34 +208,30 @@ export class MongoDialect extends AbstractDialect {
193
208
  /**
194
209
  * The stages every pipeline starts with: the `$lookup` each relation condition needs, into a temporary
195
210
  * field so `$or` keeps its meaning, the `$match` reading them, and the temporaries taken back out. Each
196
- * relation aggregate the `$where` or `named` reads is left on the document, once, under its column.
211
+ * relation aggregate the `$where` or `fields` reads is left on the document, once, under its column.
212
+ * `lookup` keeps the temporaries used, so a later lookup neither repeats nor reuses one.
197
213
  */
198
- matchStages(entity, where = {}, opts = {}, named = []) {
214
+ matchStages(entity, where = {}, opts = {}, fields = [], lookup = { stages: [], temps: [] }) {
199
215
  const meta = getMeta(entity);
200
- const lookups = { stages: [], temps: [] };
201
- for (const key of named) {
202
- this.appendAggregateField(meta, key, lookups);
216
+ for (const key of fields) {
217
+ this.appendAggregateField(meta, key, lookup);
203
218
  }
204
- const filter = this.renderFilter(entity, this.scopedWhere(meta, where, opts), lookups);
205
- return [
206
- ...lookups.stages,
207
- ...(hasKeys(filter) ? [{ $match: filter }] : []),
208
- ...(lookups.temps.length ? [{ $unset: lookups.temps }] : []),
209
- ];
219
+ const filter = this.renderFilter(entity, this.scopedWhere(meta, where, opts), lookup);
220
+ return [...lookup.stages, ...(hasKeys(filter) ? [{ $match: filter }] : []), ...unsetOf(lookup.temps)];
210
221
  }
211
222
  /**
212
223
  * Renders a `$where` tree without applying entity filters (used for same-scope group-operator
213
224
  * recursion). A relation, or a relation aggregate, needs `$lookup` stages, so it is only accepted
214
- * when `lookups` is given - a plain `find`/`updateMany` filter has nowhere to put them.
225
+ * when `lookup` is given - a plain `find`/`updateMany` filter has nowhere to put them.
215
226
  */
216
- renderFilter(entity, where = {}, lookups) {
227
+ renderFilter(entity, where = {}, lookup) {
217
228
  const meta = getMeta(entity);
218
229
  const filter = {};
219
230
  for (const [rawKey, rawVal] of Object.entries(where)) {
220
231
  let key = rawKey;
221
232
  let val = rawVal;
222
233
  if (isGroupOp(key)) {
223
- this.appendLogicalOperator(filter, entity, key, val, lookups);
234
+ this.appendLogicalOperator(filter, entity, key, val, lookup);
224
235
  }
225
236
  else if (key === '$text') {
226
237
  // MongoDB's text index declares which fields it covers, so `$fields` cannot narrow the search
@@ -230,19 +241,19 @@ export class MongoDialect extends AbstractDialect {
230
241
  }
231
242
  else if (meta.relations[key]) {
232
243
  assertNoRaw(val, '$where');
233
- if (!lookups) {
244
+ if (!lookup) {
234
245
  throw new UqlUsageError(`filtering by relation '${key}' is not supported here on MongoDB`);
235
246
  }
236
- this.appendRelationLookup(filter, meta, key, val, lookups);
247
+ andExpr(filter, this.relationExpression(meta, key, val, lookup));
237
248
  }
238
249
  else {
239
250
  assertNoRaw(val, '$where');
240
251
  this.assertKnownPathRoot(meta, key);
241
252
  if (aggregateOf(meta.fields[key])) {
242
- if (!lookups) {
253
+ if (!lookup) {
243
254
  throw new UqlUsageError(`filtering by relation aggregate '${key}' is not supported here on MongoDB`);
244
255
  }
245
- this.appendAggregateField(meta, key, lookups);
256
+ this.appendAggregateField(meta, key, lookup);
246
257
  }
247
258
  const keyed = this.holdsKeys(meta, key);
248
259
  key = this.pathOf(meta, key);
@@ -274,12 +285,12 @@ export class MongoDialect extends AbstractDialect {
274
285
  * Renders `$and`/`$or`/`$not`/`$nor` into `filter`, both negations as MongoDB's `$nor` (a `$not`'s clauses
275
286
  * wrapped in one `$and`), dropping empty clauses, since MongoDB refuses an empty operator.
276
287
  */
277
- appendLogicalOperator(filter, entity, key, val, lookups) {
288
+ appendLogicalOperator(filter, entity, key, val, lookup) {
278
289
  const { join, negate } = GROUP_OPS[key];
279
290
  const parts = groupClauses(key, val)
280
291
  .map((filterIt) => {
281
292
  assertNoRaw(filterIt, '$where');
282
- return this.renderFilter(entity, filterIt, lookups);
293
+ return this.renderFilter(entity, filterIt, lookup);
283
294
  })
284
295
  .filter((part) => Object.keys(part).length > 0);
285
296
  if (!parts.length) {
@@ -293,24 +304,19 @@ export class MongoDialect extends AbstractDialect {
293
304
  filter['$nor'] = [...(filter['$nor'] ?? []), ...negated];
294
305
  }
295
306
  /**
296
- * Emits the correlated `$lookup` for one relation condition, and adds to `filter` the condition testing
297
- * its result: presence of a row for a plain relation filter, a comparison against the row count for
298
- * `$size`. The target's (and, for ManyToMany, the junction's) own filters scope the lookup, so a
299
- * relation subquery can no more read out-of-scope rows than a direct query on the target can.
307
+ * One relation condition as an expression over the correlated `$lookup` it adds to `lookup`: a row exists
308
+ * for a plain filter, the row count compared for a `$size`. The target's (and, for ManyToMany, the
309
+ * junction's) own filters scope the lookup, so a relation subquery can no more read out-of-scope rows
310
+ * than a direct query on the target can.
300
311
  */
301
- appendRelationLookup(filter, meta, relKey, val, lookups) {
302
- const temp = `${REL_TEMP_PREFIX}${lookups.temps.length}`;
312
+ relationExpression(meta, relKey, val, lookup) {
303
313
  const sizeVal = parseRelationSize(val);
314
+ const temp = relTempField('cond', lookup.temps.length);
304
315
  const tail = sizeVal === undefined ? [{ $limit: 1 }] : [{ $count: AGGREGATE_VALUE_ALIAS }];
305
316
  const where = (sizeVal === undefined ? val : {});
306
- lookups.temps.push(temp);
307
- lookups.stages.push(this.relationLookup(meta, meta.relations[relKey], where, temp, tail));
308
- if (sizeVal === undefined) {
309
- filter[`${temp}.0`] = { $exists: true };
310
- }
311
- else {
312
- andExpr(filter, compareCount(this.tally(temp), sizeVal));
313
- }
317
+ lookup.temps.push(temp);
318
+ lookup.stages.push(this.relationLookup(meta, meta.relations[relKey], where, temp, tail));
319
+ return sizeVal === undefined ? { $gt: [{ $size: `$${temp}` }, 0] } : compareCount(this.tally(temp), sizeVal);
314
320
  }
315
321
  /**
316
322
  * The correlated `$lookup` for the target rows of one relation `where` narrows, as `temp`: straight at
@@ -529,7 +535,7 @@ export class MongoDialect extends AbstractDialect {
529
535
  // pipeline actually produces cannot drift apart - `$sort` contributes its own to-one joins here
530
536
  // exactly as it does on the SQL dialects.
531
537
  const joins = resolveQueryJoins(meta, { $populate: populate, $sort: sort });
532
- this.collectSort(meta, sort, joins, '', nearest, columns, placed);
538
+ this.collectSort(meta, sort, joins, { path: '' }, nearest, columns, placed);
533
539
  const flags = Object.fromEntries(placed.map((path) => [nullsSortField(path), { $cond: [{ $eq: [{ $ifNull: [`$${path}`, null] }, null] }, 1, 0] }]));
534
540
  return {
535
541
  // A vector distance is the primary ordering wherever it appears, as on the SQL dialects.
@@ -538,13 +544,16 @@ export class MongoDialect extends AbstractDialect {
538
544
  fields: placed.map(nullsSortField),
539
545
  };
540
546
  }
541
- /** Walks `$sort` against the metadata of the entity each level addresses, as the SQL dialects do. */
542
- collectSort(meta, sort, joins, path, nearest, out, placed) {
547
+ /**
548
+ * Walks `$sort` against the metadata of the entity each level addresses, as the SQL dialects do. `at` is where the
549
+ * level is: the relations walked to it (`path`, ending in a dot), and the join its rows came from, if any.
550
+ */
551
+ collectSort(meta, sort, joins, at, nearest, out, placed) {
543
552
  for (const [key, value] of Object.entries(sort ?? {})) {
544
553
  const relation = meta.relations[key];
545
554
  if (key === '$text') {
546
- if (path) {
547
- throw new UqlUsageError(`$sort by $text is only supported on the queried entity, not on relation '${path.slice(0, -1)}'`);
555
+ if (at.path) {
556
+ throw new UqlUsageError(`$sort by $text is only supported on the queried entity, not on relation '${at.path.slice(0, -1)}'`);
548
557
  }
549
558
  const { order, project } = textSortOf(sort);
550
559
  out[project ?? TEXT_SCORE_ALIAS] = sortDirection(order);
@@ -556,26 +565,26 @@ export class MongoDialect extends AbstractDialect {
556
565
  if (isVectorSearch(value)) {
557
566
  throw new UqlUsageError(`cannot $sort by a second vector '${key}' on MongoDB: $vectorSearch ranks by one`);
558
567
  }
559
- const docPath = path + this.pathOf(meta, key);
568
+ const field = (at.join ? `${joinedPath(at.join)}.` : '') + this.pathOf(meta, key);
560
569
  const { desc, nulls } = parseSortDirection(value);
561
570
  if (nulls) {
562
- placed.push(docPath);
571
+ placed.push(field);
563
572
  // The flag holds 1 for a null, so ordering by it descending brings the null block to the front.
564
- out[nullsSortField(docPath)] = nulls === 'first' ? -1 : 1;
573
+ out[nullsSortField(field)] = nulls === 'first' ? -1 : 1;
565
574
  }
566
- out[docPath] = desc ? -1 : 1;
575
+ out[field] = desc ? -1 : 1;
567
576
  continue;
568
577
  }
569
578
  // A `$lookup` is what puts the relation's fields on the document, and only `$populate` asks for
570
579
  // one: ordering by a relation nothing looked up reads a field that is not there, which MongoDB
571
580
  // ranks as all-equal rather than rejecting. The SQL dialects can add the join themselves.
572
- const relPath = `${path}${key}`;
581
+ const relPath = `${at.path}${key}`;
573
582
  const { aggregates, rest } = relationSortTerms(key, relPath, value);
574
583
  for (const { spec, direction } of aggregates) {
575
584
  // The value rides on a field {@link sortAggregateStages} adds, which only the queried entity's
576
585
  // own pipeline has: a nested one is built inside its parent's `$lookup`, where there is no
577
586
  // parent document left to hang it off.
578
- if (path) {
587
+ if (at.path) {
579
588
  throw new UqlUsageError(`$sort by '${relPath}.${spec.field ?? '$count'}' is only supported on the queried entity`);
580
589
  }
581
590
  if (spec.search) {
@@ -589,7 +598,7 @@ export class MongoDialect extends AbstractDialect {
589
598
  continue;
590
599
  }
591
600
  const { join, sort: relationSort } = resolveSortableJoin(relation, relPath, rest, joins, `cannot $sort by relation '${relPath}' on MongoDB unless it is populated: only $populate adds its fields to the document`);
592
- this.collectSort(join.meta, relationSort, joins, `${relPath}.`, nearest, out, placed);
601
+ this.collectSort(join.meta, relationSort, joins, { path: `${relPath}.`, join }, nearest, out, placed);
593
602
  }
594
603
  }
595
604
  /**
@@ -601,8 +610,8 @@ export class MongoDialect extends AbstractDialect {
601
610
  const meta = getMeta(entity);
602
611
  const specs = Object.entries(sort ?? {}).flatMap(([key, value]) => meta.relations[key] ? relationSortTerms(key, key, value).aggregates.map(({ spec }) => spec) : []);
603
612
  const fields = specs.map(sortAggregateField);
604
- const stages = specs.flatMap((spec, index) => this.aggregateStages(meta, spec, `${REL_TEMP_PREFIX}${fields[index]}`, fields[index]));
605
- return { stages, fields };
613
+ const lookups = specs.map((spec, index) => this.aggregateStages(meta, spec, relTempField('sort', fields[index]), fields[index]));
614
+ return { ...mergeLookups(lookups), fields };
606
615
  }
607
616
  /** Whether a read answers with a relation aggregate, which only the pipeline can build. */
608
617
  readsAggregates(entity, q) {
@@ -619,14 +628,15 @@ export class MongoDialect extends AbstractDialect {
619
628
  * {@link aggregateStages} builds from the same spec SQL renders as a subquery. Once however many
620
629
  * clauses read it; a key computing none adds nothing.
621
630
  */
622
- appendAggregateField(meta, key, lookups) {
631
+ appendAggregateField(meta, key, lookup) {
623
632
  const spec = aggregateOf(meta.fields[key]);
624
- const temp = `${REL_TEMP_PREFIX}${key}`;
625
- if (!spec || lookups.temps.includes(temp)) {
633
+ const temp = relTempField('field', key);
634
+ if (!spec || lookup.temps.includes(temp)) {
626
635
  return;
627
636
  }
628
- lookups.temps.push(temp);
629
- lookups.stages.push(...this.aggregateStages(meta, spec, temp, this.columnOf(meta, key)));
637
+ const { stages, temps } = this.aggregateStages(meta, spec, temp, this.columnOf(meta, key));
638
+ lookup.stages.push(...stages);
639
+ lookup.temps.push(...temps);
630
640
  }
631
641
  /**
632
642
  * One relation aggregate on the document under `field`: the correlated lookup that reads the related
@@ -660,10 +670,13 @@ export class MongoDialect extends AbstractDialect {
660
670
  }
661
671
  : { $count: AGGREGATE_VALUE_ALIAS },
662
672
  ];
663
- return [
664
- this.relationLookup(meta, relOpts, spec.where ?? {}, temp, tail),
665
- { $addFields: { [field]: this.tally(temp, spec.op) } },
666
- ];
673
+ return {
674
+ stages: [
675
+ this.relationLookup(meta, relOpts, spec.where ?? {}, temp, tail),
676
+ { $addFields: { [field]: this.tally(temp, spec.op) } },
677
+ ],
678
+ temps: [temp],
679
+ };
667
680
  }
668
681
  /**
669
682
  * The value a lookup left in `temp`, which holds no row at all where nothing matched: `0` for the
@@ -680,25 +693,21 @@ export class MongoDialect extends AbstractDialect {
680
693
  */
681
694
  relationReadStages(entity, q) {
682
695
  const meta = getMeta(entity);
683
- const stages = [];
684
- const temps = [];
685
- for (const relKey of getRelationRequestSummary(meta, q.$populate).toManyKeys) {
686
- stages.push(...this.toManyLookup(meta, relKey, parseRelationAtKey(relKey, q.$populate).query, temps));
687
- }
688
- for (const { relKey, where } of countedRelations(meta, q.$count)) {
689
- const temp = `${REL_TEMP_PREFIX}count_${relKey}`;
690
- temps.push(temp);
696
+ const toMany = getRelationRequestSummary(meta, q.$populate).toManyKeys.map((relKey) => this.toManyLookup(meta, relKey, parseRelationAtKey(relKey, q.$populate).query));
697
+ const counts = countedRelations(meta, q.$count).map(({ relKey, where }) => {
698
+ const temp = relTempField('count', relKey);
691
699
  const spec = { relation: relKey, op: '$count', where };
692
- stages.push(...this.aggregateStages(meta, spec, temp, `${COUNT_RESULT_KEY}.${relKey}`));
693
- }
694
- return temps.length ? [...stages, { $unset: temps }] : stages;
700
+ return this.aggregateStages(meta, spec, temp, `${COUNT_RESULT_KEY}.${relKey}`);
701
+ });
702
+ const { stages, temps } = mergeLookups([...toMany, ...counts]);
703
+ return [...stages, ...unsetOf(temps)];
695
704
  }
696
705
  /**
697
706
  * A to-many's rows as a lookup running their own read, whose filters, ordering and page apply per
698
707
  * parent inside it. A many-to-many reads its targets, each once, by the ids its junction pairs the
699
708
  * parent with, parked in a temporary field of the parent's.
700
709
  */
701
- toManyLookup(meta, relKey, query, temps) {
710
+ toManyLookup(meta, relKey, query) {
702
711
  const relOpts = relationOf(meta, relKey);
703
712
  const relEntity = relOpts.entity();
704
713
  const relMeta = getMeta(relEntity);
@@ -706,29 +715,36 @@ export class MongoDialect extends AbstractDialect {
706
715
  const pipeline = read.length ? { pipeline: read } : {};
707
716
  const from = this.resolveTableName(relMeta);
708
717
  if (!relOpts.through) {
709
- return [{ $lookup: { from, ...this.joinKeys(meta, relMeta, relOpts), ...pipeline, as: relKey } }];
718
+ return {
719
+ stages: [
720
+ { $lookup: { from, ...this.joinKeys(meta, relMeta, relOpts), ...pipeline, as: relationField(relKey) } },
721
+ ],
722
+ temps: [],
723
+ };
710
724
  }
711
725
  const junction = this.junctionOf(meta, relOpts, relMeta, relOpts.through());
712
- const temp = `${REL_TEMP_PREFIX}${relKey}`;
713
- temps.push(temp);
714
- return [
715
- {
716
- $lookup: {
717
- ...junction.lookup,
718
- pipeline: [...junction.scope, { $project: { [junction.target]: 1 } }],
719
- as: temp,
726
+ const temp = relTempField('rel', relKey);
727
+ return {
728
+ temps: [temp],
729
+ stages: [
730
+ {
731
+ $lookup: {
732
+ ...junction.lookup,
733
+ pipeline: [...junction.scope, { $project: { [junction.target]: 1 } }],
734
+ as: temp,
735
+ },
720
736
  },
721
- },
722
- {
723
- $lookup: {
724
- from,
725
- localField: `${temp}.${junction.target}`,
726
- foreignField: ID_KEY,
727
- ...pipeline,
728
- as: relKey,
737
+ {
738
+ $lookup: {
739
+ from,
740
+ localField: `${temp}.${junction.target}`,
741
+ foreignField: ID_KEY,
742
+ ...pipeline,
743
+ as: relationField(relKey),
744
+ },
729
745
  },
730
- },
731
- ];
746
+ ],
747
+ };
732
748
  }
733
749
  /** Whether a `$sort` reads a relation, which is what forces the lookups to run before it. */
734
750
  sortsRelations(entity, sort) {
@@ -812,9 +828,14 @@ export class MongoDialect extends AbstractDialect {
812
828
  // A `$lookup` the ordering asked for puts a field on the document the caller never requested,
813
829
  // which is the one way this differs from a SQL join. Taken back out once the `$sort` that needed
814
830
  // it has run, so ordering by an unpopulated relation costs the same nothing it does there.
815
- const sortOnly = [...joins.values()].filter((join) => !join.projected).map((join) => join.path);
816
- const dropped = [...sortOnly, ...aggregated.fields, ...ordering.fields];
817
- const unset = dropped.length ? [{ $unset: dropped }] : [];
831
+ const sortOnly = [...joins.values()].filter((join) => !join.projected);
832
+ const dropped = [
833
+ ...sortOnly.map((join) => joinedPath(join)),
834
+ ...aggregated.temps,
835
+ ...aggregated.fields,
836
+ ...ordering.fields,
837
+ ];
838
+ const unset = unsetOf(dropped);
818
839
  // The grouping collapses rows onto the columns it projects, which leaves nothing for an ordering
819
840
  // that reads a lookup those columns do not carry. Refused rather than answered all-equal, and in
820
841
  // the same terms the SQL dialects refuse `SELECT DISTINCT` ordered by an unselected column.
@@ -822,7 +843,7 @@ export class MongoDialect extends AbstractDialect {
822
843
  throw new UqlUsageError(`cannot $sort by a relation's aggregate with $distinct: the grouping keeps only the columns it projects`);
823
844
  }
824
845
  if (q.$distinct && sortOnly.length) {
825
- throw new UqlUsageError(`cannot $sort by relation '${sortOnly[0]}' with $distinct unless '${sortOnly[0]}' is populated: the grouping keeps only the columns it projects`);
846
+ throw new UqlUsageError(`cannot $sort by relation '${sortOnly[0].path}' with $distinct unless '${sortOnly[0].path}' is populated: the grouping keeps only the columns it projects`);
826
847
  }
827
848
  // `$distinct` inverts the usual order twice over: the projection decides which columns make two
828
849
  // rows the same, so it has to run *before* the grouping, and the grouping collapses rows, so the
@@ -871,8 +892,9 @@ export class MongoDialect extends AbstractDialect {
871
892
  return undefined;
872
893
  }
873
894
  const projection = this.select(entity, q.$select, q.$exclude);
874
- for (const relKey of getRelationRequestSummary(getMeta(entity), q.$populate).requestedKeys) {
875
- projection[relKey] = 1;
895
+ const meta = getMeta(entity);
896
+ for (const relKey of getRelationRequestSummary(meta, q.$populate).requestedKeys) {
897
+ projection[relationField(relKey)] = 1;
876
898
  }
877
899
  if (q.$count) {
878
900
  projection[COUNT_RESULT_KEY] = 1;
@@ -912,11 +934,13 @@ export class MongoDialect extends AbstractDialect {
912
934
  from: this.resolveTableName(join.meta),
913
935
  ...this.joinKeys(parentMeta, join.meta, join.relation),
914
936
  ...(lookupPipeline.length ? { pipeline: lookupPipeline } : {}),
915
- as: join.key,
937
+ as: relationField(join.key),
916
938
  },
917
939
  });
918
940
  // `$required` drops parents with no match, the aggregation equivalent of an INNER JOIN.
919
- pipeline.push({ $unwind: { path: `$${join.key}`, preserveNullAndEmptyArrays: !join.required } });
941
+ pipeline.push({
942
+ $unwind: { path: `$${relationField(join.key)}`, preserveNullAndEmptyArrays: !join.required },
943
+ });
920
944
  }
921
945
  return pipeline;
922
946
  }
@@ -948,6 +972,19 @@ export class MongoDialect extends AbstractDialect {
948
972
  }
949
973
  return renamed;
950
974
  }
975
+ /** Each relation's key, the field its rows are read from, and its entity, memoized per entity for `normalizeId`. */
976
+ relationReads(meta) {
977
+ let reads = this.#relationReads.get(meta);
978
+ if (!reads) {
979
+ reads = definedEntries(meta.relations).map(([key, relation]) => ({
980
+ key,
981
+ field: relationField(key),
982
+ meta: getMeta(relation.entity()),
983
+ }));
984
+ this.#relationReads.set(meta, reads);
985
+ }
986
+ return reads;
987
+ }
951
988
  referenceKeys(meta) {
952
989
  let keys = this.#referenceKeys.get(meta);
953
990
  if (!keys) {
@@ -959,6 +996,7 @@ export class MongoDialect extends AbstractDialect {
959
996
  // Keyed by the meta object itself; entity metadata is immutable once defined.
960
997
  #renamedColumns = new WeakMap();
961
998
  #referenceKeys = new WeakMap();
999
+ #relationReads = new WeakMap();
962
1000
  normalizeIds(meta, docs) {
963
1001
  return docs.map((doc) => this.normalizeId(meta, doc));
964
1002
  }
@@ -993,10 +1031,10 @@ export class MongoDialect extends AbstractDialect {
993
1031
  // A 64-bit integer, which the pool reads as a `bigint`: kept for a `BigInt` field, and elsewhere the
994
1032
  // number it is where exact and its exact text past 2^53, as every SQL driver decodes one.
995
1033
  decodeBigIntsExcept(res, (key) => meta.fields[key]?.type === BigInt);
996
- for (const [relKey, relation] of definedEntries(meta.relations)) {
997
- const value = res[relKey];
1034
+ for (const { key: relKey, field, meta: relMeta } of this.relationReads(meta)) {
1035
+ const value = res[field];
1036
+ delete res[field];
998
1037
  if (value) {
999
- const relMeta = getMeta(relation.entity());
1000
1038
  res[relKey] = Array.isArray(value)
1001
1039
  ? this.normalizeIds(relMeta, value)
1002
1040
  : this.normalizeId(relMeta, value);
@@ -1062,15 +1100,20 @@ export class MongoDialect extends AbstractDialect {
1062
1100
  assignments[key] = { [MONGO_ARITHMETIC[op]]: [{ $ifNull: [`$${key}`, 0] }, { $literal: operand }] };
1063
1101
  }
1064
1102
  else if (isJsonUpdateOp(value)) {
1065
- const writes = foldJsonUpdate(value);
1066
- Object.assign(assignments, jsonAssignments(key, writes));
1067
- unset.push(...writes.unset.map((path) => `${key}.${path}`));
1103
+ const update = foldJson(value);
1104
+ if ('array' in update) {
1105
+ assignments[key] = arrayWrite(key, update.array);
1106
+ }
1107
+ else {
1108
+ Object.assign(assignments, jsonAssignments(key, update.object));
1109
+ unset.push(...update.object.unset.map((path) => `${key}.${path}`));
1110
+ }
1068
1111
  }
1069
1112
  else {
1070
1113
  assignments[key] = { $literal: value };
1071
1114
  }
1072
1115
  }
1073
- return [...(hasKeys(assignments) ? [{ $set: assignments }] : []), ...(unset.length > 0 ? [{ $unset: unset }] : [])];
1116
+ return [...(hasKeys(assignments) ? [{ $set: assignments }] : []), ...unsetOf(unset)];
1074
1117
  }
1075
1118
  /** Refuses a key left to MongoDB that it cannot mint: only an `ObjectId`, read back as a string, so not a `Number`. */
1076
1119
  assertMintableKey(meta, field) {
@@ -1115,9 +1158,13 @@ export class MongoDialect extends AbstractDialect {
1115
1158
  buildAggregateStages(entity, q, opts) {
1116
1159
  const meta = getMeta(entity);
1117
1160
  const { joins, where } = resolveGroupJoins(meta, q);
1118
- const { groupId, accumulators, columns, named } = this.buildGroupSpec(meta, parseGroupMap(q.$group, q.$select), joins);
1161
+ const matched = { stages: [], temps: [] };
1162
+ const match = this.matchStages(entity, where, opts, [], matched);
1163
+ const { groupId, accumulators, columns, lookups } = this.buildGroupSpec(meta, parseGroupMap(q.$group, q.$select), joins, matched.temps);
1119
1164
  const pipeline = [
1120
- ...this.matchStages(entity, where, opts, named),
1165
+ ...match,
1166
+ // What the `$group` reads off each matched row through a lookup, the temporaries it then drops.
1167
+ ...lookups,
1121
1168
  ...this.lookupStages(meta, joins),
1122
1169
  { $group: { _id: hasKeys(groupId) ? groupId : null, ...accumulators } },
1123
1170
  // `$group` answers with `_id` even when grouping by nothing, and with what `columns` read to the end.
@@ -1148,29 +1195,30 @@ export class MongoDialect extends AbstractDialect {
1148
1195
  /**
1149
1196
  * Resolve parsed group entries into the `_id` keys and accumulators of a `$group` stage, and the
1150
1197
  * `columns` its `$project` reads each result from: a group key out of `_id`, a DISTINCT set by its
1151
- * size, and a `$sum` as null where it read no value, as SQL answers it. `named` is every field it reads,
1152
- * filters included, so each relation aggregate among them is put on the document first.
1198
+ * size, and a `$sum` as null where it read no value, as SQL answers it. `lookups` puts on each matched
1199
+ * row what the group reads through one: a relation aggregate, and an aggregate's relation condition,
1200
+ * past the `matched` temporaries, whose relation aggregates are on the row already.
1153
1201
  */
1154
- buildGroupSpec(meta, groupEntries, joins) {
1202
+ buildGroupSpec(meta, groupEntries, joins, matched) {
1155
1203
  if (!groupEntries.length) {
1156
1204
  throw new UqlUsageError('aggregate requires at least one $group column or $select function');
1157
1205
  }
1158
1206
  const groupId = {};
1159
1207
  const accumulators = {};
1160
1208
  const columns = {};
1161
- const named = [];
1209
+ const lookup = { stages: [], temps: [...matched] };
1162
1210
  for (const entry of groupEntries) {
1163
1211
  // Aliases stay as the caller wrote them ($project maps them back); the *refs* address columns.
1164
1212
  if (entry.kind === 'key') {
1165
- groupId[entry.alias] = `$${this.groupedPath(meta, joins, entry.path, named)}`;
1213
+ groupId[entry.alias] = `$${this.groupedPath(meta, joins, entry.path, lookup)}`;
1166
1214
  columns[entry.alias] = `$_id.${entry.alias}`;
1167
1215
  continue;
1168
1216
  }
1169
1217
  const { field } = entry;
1170
1218
  if (field !== undefined) {
1171
- named.push(field);
1219
+ this.appendAggregateField(meta, field, lookup);
1172
1220
  }
1173
- const test = entry.where && this.whereExpression(meta, entry.where, named);
1221
+ const test = entry.where && this.whereExpression(meta, entry.where, lookup);
1174
1222
  // What the accumulator reads from a row its own `$where` passes, and from one it does not.
1175
1223
  const read = (passed, failed) => (test ? { $cond: [test, passed, failed] } : passed);
1176
1224
  columns[entry.alias] = 1;
@@ -1198,40 +1246,44 @@ export class MongoDialect extends AbstractDialect {
1198
1246
  columns[entry.alias] = { $cond: [{ $eq: [`$${counted}`, 0] }, null, `$${entry.alias}`] };
1199
1247
  }
1200
1248
  }
1201
- return { groupId, accumulators, columns, named };
1249
+ return { groupId, accumulators, columns, lookups: lookup.stages };
1202
1250
  }
1203
1251
  /** The field a grouped path reads, on the document or on the joined one its lookup unwound. */
1204
- groupedPath(meta, joins, path, named) {
1252
+ groupedPath(meta, joins, path, lookup) {
1205
1253
  const { key, join } = groupPathField(joins, path);
1206
1254
  if (!join) {
1207
- named.push(key);
1255
+ this.appendAggregateField(meta, key, lookup);
1208
1256
  return this.columnOf(meta, key);
1209
1257
  }
1210
1258
  if (aggregateOf(join.meta.fields[key])) {
1211
1259
  throw new UqlUsageError(`cannot $group by '${path.join('.')}' on MongoDB: a joined row's relation aggregate is not read`);
1212
1260
  }
1213
- return `${join.path}.${this.columnOf(join.meta, key)}`;
1261
+ return `${joinedPath(join)}.${this.columnOf(join.meta, key)}`;
1214
1262
  }
1215
1263
  /**
1216
1264
  * An aggregate's own `$where` as the expression a `$cond` tests, which a query filter is not: the
1217
- * comparisons and the logical operators translate, anything else is refused by name. `named` gathers
1218
- * the fields it reads, so a relation aggregate among them is on the document first.
1265
+ * comparisons, the logical operators and relations translate, anything else is refused by name. `lookup`
1266
+ * gathers the lookups it tests: a relation condition's, and a relation aggregate's it compares.
1219
1267
  */
1220
- whereExpression(meta, where, named) {
1268
+ whereExpression(meta, where, lookup) {
1221
1269
  const terms = getKeys(where).map((key) => {
1222
1270
  if (isGroupOp(key)) {
1223
1271
  const { join, negate } = GROUP_OPS[key];
1224
1272
  const clauses = groupClauses(key, where[key]).map((clause) => {
1225
1273
  assertNoRaw(clause, 'an aggregate $where');
1226
- return this.whereExpression(meta, clause, named);
1274
+ return this.whereExpression(meta, clause, lookup);
1227
1275
  });
1228
1276
  return negate ? { $not: [{ [join]: clauses }] } : { [join]: clauses };
1229
1277
  }
1278
+ if (meta.relations[key]) {
1279
+ assertNoRaw(where[key], 'an aggregate $where');
1280
+ return this.relationExpression(meta, key, where[key], lookup);
1281
+ }
1230
1282
  if (key.startsWith('$')) {
1231
1283
  throw new UqlUsageError(`aggregate $where operator '${key}' is not supported on MongoDB`);
1232
1284
  }
1233
1285
  const val = where[key];
1234
- named.push(key);
1286
+ this.appendAggregateField(meta, key, lookup);
1235
1287
  const wire = this.holdsKeys(meta, key) ? (value) => this.toWireId(value) : (value) => value;
1236
1288
  return this.fieldExpression(`$${this.pathOf(meta, key)}`, val, wire);
1237
1289
  });
@@ -135,7 +135,10 @@ export declare class MsSqlDialect extends MergeSqlDialect {
135
135
  */
136
136
  protected jsonWriteParam(ctx: QueryContext, value: unknown): string;
137
137
  protected jsonElemFrom(slot: JsonSlot, alias: string): string;
138
- /** `JSON_QUERY` answers an array or an object as written, and a scalar as NULL, so its first character tells which. */
138
+ /**
139
+ * Its first character: the one `JSON_QUERY` answers, NULL for a scalar, or the document's own first past any
140
+ * whitespace, since `JSON_QUERY` refuses a document that is a scalar and copying it costs its length.
141
+ */
139
142
  protected jsonIs(slot: JsonSlot, kind: JsonContainer): string;
140
143
  /** `OPENJSON` answers a JSON null as NULL, as it does a key that is not there. */
141
144
  protected jsonIsNull(slot: JsonSlot): string;
@@ -161,13 +164,12 @@ export declare class MsSqlDialect extends MergeSqlDialect {
161
164
  * `JSON_QUERY` refuses, is never written back.
162
165
  */
163
166
  protected jsonWriteKeys(expr: string, writes: readonly JsonKeyWrite[]): string;
164
- protected jsonAppended(ctx: QueryContext, array: string, value: unknown): string;
167
+ protected jsonAppended(ctx: QueryContext, array: string, value: unknown, unless?: string): string;
165
168
  /** Assigning NULL to a path deletes it in lax mode, which is the default. */
166
169
  protected jsonUnset(_ctx: QueryContext, expr: string, unset: readonly string[]): string;
167
170
  /**
168
- * The surviving elements re-aggregated into an array, there being no remove-by-value. `OPENJSON` hands
169
- * back a string element unquoted and a null one as SQL NULL, so each survivor is re-encoded from its
170
- * reported `type`, and a null is told apart by `IS NULL`, which `<>` cannot do.
171
+ * The surviving elements re-aggregated into an array, there being no remove-by-value. `OPENJSON` hands back a
172
+ * string element unquoted and a null one as SQL NULL, so each survivor is re-encoded from its reported `type`.
171
173
  */
172
- protected jsonKept(ctx: QueryContext, slot: JsonSlot, item: unknown): string;
174
+ protected jsonKeptAggregate(): string;
173
175
  }