uql-orm 0.102.1 → 0.102.2

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.
@@ -113,7 +113,10 @@ export declare class MongoDialect extends AbstractDialect {
113
113
  * by ahead of the value itself.
114
114
  */
115
115
  sortPlan<E extends Document>(entity: Type<E>, { $sort: sort, $populate: populate, $where: where }: Query<E>): MongoSortPlan;
116
- /** Walks `$sort` against the metadata of the entity each level addresses, as the SQL dialects do. */
116
+ /**
117
+ * Walks `$sort` against the metadata of the entity each level addresses, as the SQL dialects do. `at` is where the
118
+ * level is: the relations walked to it (`path`, ending in a dot), and the join its rows came from, if any.
119
+ */
117
120
  private collectSort;
118
121
  /**
119
122
  * The stages a `$sort` by a relation's aggregate needs - its size, or its row nearest a vector: one
@@ -206,6 +209,8 @@ export declare class MongoDialect extends AbstractDialect {
206
209
  private joinKeys;
207
210
  /** `[column, key]` for the fields whose stored name differs from their property name, memoized per entity. */
208
211
  private renamedColumns;
212
+ /** Each relation's key, the field its rows are read from, and its entity, memoized per entity for `normalizeId`. */
213
+ private relationReads;
209
214
  private referenceKeys;
210
215
  normalizeIds<E extends Document>(meta: EntityMeta<E>, docs: Document[]): E[];
211
216
  /** `doc` is the wire shape - `_id`, stored names, `ObjectId`s - and what comes back is the code's. */
@@ -1,25 +1,35 @@
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, REL_TEMP_PREFIX, 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
+ }
14
22
  /** A scalar field's operator as the aggregation operator computing it. */
15
23
  const MONGO_ARITHMETIC = { $inc: '$add', $mul: '$multiply' };
16
24
  /**
17
- * One array key's writes at `path`, as SQL writes them: the pull, then each append onto `[]` in place of a
25
+ * One array's writes at `path`, as SQL writes them: the pulls, then each append onto `[]` in place of a
18
26
  * missing or null array, a `unique` one only where the array lacks its item; a value that is no array stays.
19
27
  */
20
- function arrayWrite(path, { pull, appends }) {
28
+ function arrayWrite(path, { pulls, appends }) {
21
29
  const stored = `$${path}`;
22
- const kept = (array) => pull ? { $filter: { input: array, cond: { $ne: ['$$this', { $literal: pull.item }] } } } : array;
30
+ const kept = (array) => pulls.length > 0
31
+ ? { $filter: { input: array, cond: { $not: [{ $in: ['$$this', { $literal: pulls }] }] } } }
32
+ : array;
23
33
  if (appends.length === 0) {
24
34
  return { $cond: [{ $isArray: stored }, kept(stored), stored] };
25
35
  }
@@ -529,7 +539,7 @@ export class MongoDialect extends AbstractDialect {
529
539
  // pipeline actually produces cannot drift apart - `$sort` contributes its own to-one joins here
530
540
  // exactly as it does on the SQL dialects.
531
541
  const joins = resolveQueryJoins(meta, { $populate: populate, $sort: sort });
532
- this.collectSort(meta, sort, joins, '', nearest, columns, placed);
542
+ this.collectSort(meta, sort, joins, { path: '' }, nearest, columns, placed);
533
543
  const flags = Object.fromEntries(placed.map((path) => [nullsSortField(path), { $cond: [{ $eq: [{ $ifNull: [`$${path}`, null] }, null] }, 1, 0] }]));
534
544
  return {
535
545
  // A vector distance is the primary ordering wherever it appears, as on the SQL dialects.
@@ -538,13 +548,16 @@ export class MongoDialect extends AbstractDialect {
538
548
  fields: placed.map(nullsSortField),
539
549
  };
540
550
  }
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) {
551
+ /**
552
+ * Walks `$sort` against the metadata of the entity each level addresses, as the SQL dialects do. `at` is where the
553
+ * level is: the relations walked to it (`path`, ending in a dot), and the join its rows came from, if any.
554
+ */
555
+ collectSort(meta, sort, joins, at, nearest, out, placed) {
543
556
  for (const [key, value] of Object.entries(sort ?? {})) {
544
557
  const relation = meta.relations[key];
545
558
  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)}'`);
559
+ if (at.path) {
560
+ throw new UqlUsageError(`$sort by $text is only supported on the queried entity, not on relation '${at.path.slice(0, -1)}'`);
548
561
  }
549
562
  const { order, project } = textSortOf(sort);
550
563
  out[project ?? TEXT_SCORE_ALIAS] = sortDirection(order);
@@ -556,26 +569,26 @@ export class MongoDialect extends AbstractDialect {
556
569
  if (isVectorSearch(value)) {
557
570
  throw new UqlUsageError(`cannot $sort by a second vector '${key}' on MongoDB: $vectorSearch ranks by one`);
558
571
  }
559
- const docPath = path + this.pathOf(meta, key);
572
+ const field = (at.join ? `${joinedPath(at.join)}.` : '') + this.pathOf(meta, key);
560
573
  const { desc, nulls } = parseSortDirection(value);
561
574
  if (nulls) {
562
- placed.push(docPath);
575
+ placed.push(field);
563
576
  // 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;
577
+ out[nullsSortField(field)] = nulls === 'first' ? -1 : 1;
565
578
  }
566
- out[docPath] = desc ? -1 : 1;
579
+ out[field] = desc ? -1 : 1;
567
580
  continue;
568
581
  }
569
582
  // A `$lookup` is what puts the relation's fields on the document, and only `$populate` asks for
570
583
  // one: ordering by a relation nothing looked up reads a field that is not there, which MongoDB
571
584
  // ranks as all-equal rather than rejecting. The SQL dialects can add the join themselves.
572
- const relPath = `${path}${key}`;
585
+ const relPath = `${at.path}${key}`;
573
586
  const { aggregates, rest } = relationSortTerms(key, relPath, value);
574
587
  for (const { spec, direction } of aggregates) {
575
588
  // The value rides on a field {@link sortAggregateStages} adds, which only the queried entity's
576
589
  // own pipeline has: a nested one is built inside its parent's `$lookup`, where there is no
577
590
  // parent document left to hang it off.
578
- if (path) {
591
+ if (at.path) {
579
592
  throw new UqlUsageError(`$sort by '${relPath}.${spec.field ?? '$count'}' is only supported on the queried entity`);
580
593
  }
581
594
  if (spec.search) {
@@ -589,7 +602,7 @@ export class MongoDialect extends AbstractDialect {
589
602
  continue;
590
603
  }
591
604
  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);
605
+ this.collectSort(join.meta, relationSort, joins, { path: `${relPath}.`, join }, nearest, out, placed);
593
606
  }
594
607
  }
595
608
  /**
@@ -706,7 +719,16 @@ export class MongoDialect extends AbstractDialect {
706
719
  const pipeline = read.length ? { pipeline: read } : {};
707
720
  const from = this.resolveTableName(relMeta);
708
721
  if (!relOpts.through) {
709
- return [{ $lookup: { from, ...this.joinKeys(meta, relMeta, relOpts), ...pipeline, as: relKey } }];
722
+ return [
723
+ {
724
+ $lookup: {
725
+ from,
726
+ ...this.joinKeys(meta, relMeta, relOpts),
727
+ ...pipeline,
728
+ as: relationField(relKey),
729
+ },
730
+ },
731
+ ];
710
732
  }
711
733
  const junction = this.junctionOf(meta, relOpts, relMeta, relOpts.through());
712
734
  const temp = `${REL_TEMP_PREFIX}${relKey}`;
@@ -725,7 +747,7 @@ export class MongoDialect extends AbstractDialect {
725
747
  localField: `${temp}.${junction.target}`,
726
748
  foreignField: ID_KEY,
727
749
  ...pipeline,
728
- as: relKey,
750
+ as: relationField(relKey),
729
751
  },
730
752
  },
731
753
  ];
@@ -812,8 +834,8 @@ export class MongoDialect extends AbstractDialect {
812
834
  // A `$lookup` the ordering asked for puts a field on the document the caller never requested,
813
835
  // which is the one way this differs from a SQL join. Taken back out once the `$sort` that needed
814
836
  // 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];
837
+ const sortOnly = [...joins.values()].filter((join) => !join.projected);
838
+ const dropped = [...sortOnly.map((join) => joinedPath(join)), ...aggregated.fields, ...ordering.fields];
817
839
  const unset = dropped.length ? [{ $unset: dropped }] : [];
818
840
  // The grouping collapses rows onto the columns it projects, which leaves nothing for an ordering
819
841
  // that reads a lookup those columns do not carry. Refused rather than answered all-equal, and in
@@ -822,7 +844,7 @@ export class MongoDialect extends AbstractDialect {
822
844
  throw new UqlUsageError(`cannot $sort by a relation's aggregate with $distinct: the grouping keeps only the columns it projects`);
823
845
  }
824
846
  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`);
847
+ 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
848
  }
827
849
  // `$distinct` inverts the usual order twice over: the projection decides which columns make two
828
850
  // rows the same, so it has to run *before* the grouping, and the grouping collapses rows, so the
@@ -871,8 +893,9 @@ export class MongoDialect extends AbstractDialect {
871
893
  return undefined;
872
894
  }
873
895
  const projection = this.select(entity, q.$select, q.$exclude);
874
- for (const relKey of getRelationRequestSummary(getMeta(entity), q.$populate).requestedKeys) {
875
- projection[relKey] = 1;
896
+ const meta = getMeta(entity);
897
+ for (const relKey of getRelationRequestSummary(meta, q.$populate).requestedKeys) {
898
+ projection[relationField(relKey)] = 1;
876
899
  }
877
900
  if (q.$count) {
878
901
  projection[COUNT_RESULT_KEY] = 1;
@@ -912,11 +935,13 @@ export class MongoDialect extends AbstractDialect {
912
935
  from: this.resolveTableName(join.meta),
913
936
  ...this.joinKeys(parentMeta, join.meta, join.relation),
914
937
  ...(lookupPipeline.length ? { pipeline: lookupPipeline } : {}),
915
- as: join.key,
938
+ as: relationField(join.key),
916
939
  },
917
940
  });
918
941
  // `$required` drops parents with no match, the aggregation equivalent of an INNER JOIN.
919
- pipeline.push({ $unwind: { path: `$${join.key}`, preserveNullAndEmptyArrays: !join.required } });
942
+ pipeline.push({
943
+ $unwind: { path: `$${relationField(join.key)}`, preserveNullAndEmptyArrays: !join.required },
944
+ });
920
945
  }
921
946
  return pipeline;
922
947
  }
@@ -948,6 +973,19 @@ export class MongoDialect extends AbstractDialect {
948
973
  }
949
974
  return renamed;
950
975
  }
976
+ /** Each relation's key, the field its rows are read from, and its entity, memoized per entity for `normalizeId`. */
977
+ relationReads(meta) {
978
+ let reads = this.#relationReads.get(meta);
979
+ if (!reads) {
980
+ reads = definedEntries(meta.relations).map(([key, relation]) => ({
981
+ key,
982
+ field: relationField(key),
983
+ meta: getMeta(relation.entity()),
984
+ }));
985
+ this.#relationReads.set(meta, reads);
986
+ }
987
+ return reads;
988
+ }
951
989
  referenceKeys(meta) {
952
990
  let keys = this.#referenceKeys.get(meta);
953
991
  if (!keys) {
@@ -959,6 +997,7 @@ export class MongoDialect extends AbstractDialect {
959
997
  // Keyed by the meta object itself; entity metadata is immutable once defined.
960
998
  #renamedColumns = new WeakMap();
961
999
  #referenceKeys = new WeakMap();
1000
+ #relationReads = new WeakMap();
962
1001
  normalizeIds(meta, docs) {
963
1002
  return docs.map((doc) => this.normalizeId(meta, doc));
964
1003
  }
@@ -993,10 +1032,10 @@ export class MongoDialect extends AbstractDialect {
993
1032
  // A 64-bit integer, which the pool reads as a `bigint`: kept for a `BigInt` field, and elsewhere the
994
1033
  // number it is where exact and its exact text past 2^53, as every SQL driver decodes one.
995
1034
  decodeBigIntsExcept(res, (key) => meta.fields[key]?.type === BigInt);
996
- for (const [relKey, relation] of definedEntries(meta.relations)) {
997
- const value = res[relKey];
1035
+ for (const { key: relKey, field, meta: relMeta } of this.relationReads(meta)) {
1036
+ const value = res[field];
1037
+ delete res[field];
998
1038
  if (value) {
999
- const relMeta = getMeta(relation.entity());
1000
1039
  res[relKey] = Array.isArray(value)
1001
1040
  ? this.normalizeIds(relMeta, value)
1002
1041
  : this.normalizeId(relMeta, value);
@@ -1062,9 +1101,14 @@ export class MongoDialect extends AbstractDialect {
1062
1101
  assignments[key] = { [MONGO_ARITHMETIC[op]]: [{ $ifNull: [`$${key}`, 0] }, { $literal: operand }] };
1063
1102
  }
1064
1103
  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}`));
1104
+ const update = foldJson(value);
1105
+ if ('array' in update) {
1106
+ assignments[key] = arrayWrite(key, update.array);
1107
+ }
1108
+ else {
1109
+ Object.assign(assignments, jsonAssignments(key, update.object));
1110
+ unset.push(...update.object.unset.map((path) => `${key}.${path}`));
1111
+ }
1068
1112
  }
1069
1113
  else {
1070
1114
  assignments[key] = { $literal: value };
@@ -1210,7 +1254,7 @@ export class MongoDialect extends AbstractDialect {
1210
1254
  if (aggregateOf(join.meta.fields[key])) {
1211
1255
  throw new UqlUsageError(`cannot $group by '${path.join('.')}' on MongoDB: a joined row's relation aggregate is not read`);
1212
1256
  }
1213
- return `${join.path}.${this.columnOf(join.meta, key)}`;
1257
+ return `${joinedPath(join)}.${this.columnOf(join.meta, key)}`;
1214
1258
  }
1215
1259
  /**
1216
1260
  * An aggregate's own `$where` as the expression a `$cond` tests, which a query filter is not: the
@@ -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
  }
@@ -1,7 +1,7 @@
1
1
  import { ANSI_SQL_VALUES, fromRows, relationTermKey, isolationSetBefore, } from '../dialect/abstractSqlDialect.js';
2
- import { AGGREGATE_VALUE_ALIAS, JSON_PULL_ALIAS, JSON_SKIP_KEY, OUTPUT_TABLE } from '../dialect/aliases.js';
2
+ import { AGGREGATE_VALUE_ALIAS, JSON_PULL_ALIAS, OUTPUT_TABLE } from '../dialect/aliases.js';
3
3
  import { BYTES_PREFIX } from '../dialect/hydrateColumn.js';
4
- import { jsonArraySlotArgs, jsonPath, jsonSlotArgs, } from '../dialect/jsonSql.js';
4
+ import { skippablePath, jsonArraySlotArgs, jsonPath, jsonSlotArgs, } from '../dialect/jsonSql.js';
5
5
  import { MergeSqlDialect } from '../dialect/mergeSqlDialect.js';
6
6
  import { getMeta } from '../entity/index.js';
7
7
  import { canonicalToSql, resolveColumnCanonicalType } from '../schema/canonicalType.js';
@@ -9,7 +9,7 @@ import { QuerySql } from '../type/index.js';
9
9
  import { parseQueryLock } from '../type/index.js';
10
10
  import { bytesToHex } from '../util/bytes.js';
11
11
  import { isAutoIncrement, isExactDecimal, jsonPathKeys } from '../util/field.util.js';
12
- import { assertNonNegativeInteger } from '../util/index.js';
12
+ import { assertNonNegativeInteger, isOperatorMap } from '../util/index.js';
13
13
  import { escapeSingleQuotes } from '../util/sqlLiteral.js';
14
14
  import { UqlUsageError } from '../util/uqlError.js';
15
15
  /** What SQL Server has. */
@@ -52,12 +52,20 @@ const MSSQL_FEATURES = {
52
52
  },
53
53
  namedLocks: 'transaction',
54
54
  };
55
- /** The `type` `OPENJSON` reports for the JSON scalar an element is compared with; anything else binds as a string. */
55
+ /** The `type` `OPENJSON` reports for each JSON kind. */
56
+ const OPENJSON_TYPE = { null: 0, string: 1, number: 2, boolean: 3, array: 4, object: 5 };
57
+ /** The `type` `OPENJSON` reports for an element of `value`'s JSON type; anything else binds as a string. */
56
58
  function openJsonType(value) {
59
+ if (Array.isArray(value)) {
60
+ return OPENJSON_TYPE.array;
61
+ }
62
+ if (isOperatorMap(value)) {
63
+ return OPENJSON_TYPE.object;
64
+ }
57
65
  if (typeof value === 'number') {
58
- return 2;
66
+ return OPENJSON_TYPE.number;
59
67
  }
60
- return typeof value === 'boolean' ? 3 : 1;
68
+ return typeof value === 'boolean' ? OPENJSON_TYPE.boolean : OPENJSON_TYPE.string;
61
69
  }
62
70
  /** The one key column and its field, or nothing on a composite key. */
63
71
  function soleId(meta) {
@@ -353,9 +361,15 @@ export class MsSqlDialect extends MergeSqlDialect {
353
361
  jsonElemFrom(slot, alias) {
354
362
  return `OPENJSON(${jsonArraySlotArgs(slot, this.jsonIs(slot, 'array'))}) ${alias}`;
355
363
  }
356
- /** `JSON_QUERY` answers an array or an object as written, and a scalar as NULL, so its first character tells which. */
364
+ /**
365
+ * Its first character: the one `JSON_QUERY` answers, NULL for a scalar, or the document's own first past any
366
+ * whitespace, since `JSON_QUERY` refuses a document that is a scalar and copying it costs its length.
367
+ */
357
368
  jsonIs(slot, kind) {
358
- return `LEFT(JSON_QUERY(${jsonSlotArgs(slot)}), 1) = '${kind === 'array' ? '[' : '{'}'`;
369
+ const first = slot.path
370
+ ? `LEFT(JSON_QUERY(${jsonSlotArgs(slot)}), 1)`
371
+ : `SUBSTRING(${slot.base}, PATINDEX(N'%[^ ' + CHAR(9) + CHAR(10) + CHAR(13) + N']%', ${slot.base}), 1)`;
372
+ return `${first} = '${kind === 'array' ? '[' : '{'}'`;
359
373
  }
360
374
  /** `OPENJSON` answers a JSON null as NULL, as it does a key that is not there. */
361
375
  jsonIsNull(slot) {
@@ -373,7 +387,7 @@ export class MsSqlDialect extends MergeSqlDialect {
373
387
  jsonElemEquals(ctx, _slot, alias, value) {
374
388
  const type = `${alias}.${this.#elem.type}`;
375
389
  if (value === null) {
376
- return `${type} = 0`;
390
+ return `${type} = ${OPENJSON_TYPE.null}`;
377
391
  }
378
392
  const elem = this.jsonElemDoc(alias);
379
393
  const param = this.jsonScalarParam(ctx, value);
@@ -404,29 +418,27 @@ export class MsSqlDialect extends MergeSqlDialect {
404
418
  */
405
419
  jsonWriteKeys(expr, writes) {
406
420
  return writes.reduce((acc, [slot, value]) => {
407
- const path = `CASE WHEN ${value} IS NULL THEN ${jsonPath(JSON_SKIP_KEY)} ELSE ${jsonPath(slot.path)} END`;
421
+ const path = skippablePath(jsonPath(slot.path), `${value} IS NULL`);
408
422
  return `JSON_MODIFY(${acc}, ${path}, JSON_QUERY(${value}))`;
409
423
  }, expr);
410
424
  }
411
- jsonAppended(ctx, array, value) {
412
- return `JSON_MODIFY(${array}, 'append $', ${this.jsonWriteParam(ctx, value)})`;
425
+ jsonAppended(ctx, array, value, unless) {
426
+ return `JSON_MODIFY(${array}, ${skippablePath(`'append $'`, unless)}, ${this.jsonWriteParam(ctx, value)})`;
413
427
  }
414
428
  /** Assigning NULL to a path deletes it in lax mode, which is the default. */
415
429
  jsonUnset(_ctx, expr, unset) {
416
430
  return unset.reduce((acc, key) => `JSON_MODIFY(${acc}, ${jsonPath(key)}, NULL)`, expr);
417
431
  }
418
432
  /**
419
- * The surviving elements re-aggregated into an array, there being no remove-by-value. `OPENJSON` hands
420
- * back a string element unquoted and a null one as SQL NULL, so each survivor is re-encoded from its
421
- * reported `type`, and a null is told apart by `IS NULL`, which `<>` cannot do.
433
+ * The surviving elements re-aggregated into an array, there being no remove-by-value. `OPENJSON` hands back a
434
+ * string element unquoted and a null one as SQL NULL, so each survivor is re-encoded from its reported `type`.
422
435
  */
423
- jsonKept(ctx, slot, item) {
436
+ jsonKeptAggregate() {
424
437
  const val = this.jsonElemDoc(JSON_PULL_ALIAS);
425
438
  const encoded = `CASE ${JSON_PULL_ALIAS}.${this.#elem.type}` +
426
- ` WHEN 0 THEN 'null'` +
427
- ` WHEN 1 THEN '"' + STRING_ESCAPE(${val}, 'json') + '"'` +
439
+ ` WHEN ${OPENJSON_TYPE.null} THEN 'null'` +
440
+ ` WHEN ${OPENJSON_TYPE.string} THEN '"' + STRING_ESCAPE(${val}, 'json') + '"'` +
428
441
  ` ELSE ${val} END`;
429
- const differs = item === null ? `${val} IS NOT NULL` : `${val} IS NULL OR ${val} <> ${this.jsonScalarParam(ctx, item)}`;
430
- return `SELECT '[' + STRING_AGG(${encoded}, ',') + ']' FROM ${this.jsonElemFrom(slot, JSON_PULL_ALIAS)} WHERE ${differs}`;
442
+ return `'[' + STRING_AGG(${encoded}, ',') + ']'`;
431
443
  }
432
444
  }
@@ -87,5 +87,5 @@ export declare class SqliteDialect extends AbstractSqlDialect {
87
87
  protected jsonCast(operand: string): string;
88
88
  /** `JSON` keeps each element's JSON type in the array, which answers `[]` for no rows. */
89
89
  protected jsonArrayOf(elem: string): string;
90
- protected jsonAppended(ctx: QueryContext, array: string, value: unknown): string;
90
+ protected jsonAppended(ctx: QueryContext, array: string, value: unknown, unless?: string): string;
91
91
  }
@@ -1,6 +1,6 @@
1
1
  import { ANSI_SQL_VALUES, AbstractSqlDialect, } from '../dialect/abstractSqlDialect.js';
2
2
  import { BYTES_PREFIX } from '../dialect/hydrateColumn.js';
3
- import { chainedCall, groupsPerCall, jsonPath, jsonArraySlotArgs, jsonSlotArgs, } from '../dialect/jsonSql.js';
3
+ import { chainedCall, groupsPerCall, jsonPath, skippablePath, jsonArraySlotArgs, jsonSlotArgs, } from '../dialect/jsonSql.js';
4
4
  import { QuerySql, } from '../type/index.js';
5
5
  import { indexDistance, isVectorIndexType } from '../type/vector.js';
6
6
  import { declaredIndexName } from '../util/ddlExpression.util.js';
@@ -227,7 +227,7 @@ export class SqliteDialect extends AbstractSqlDialect {
227
227
  jsonArrayOf(elem) {
228
228
  return `JSON_GROUP_ARRAY(JSON(${elem}))`;
229
229
  }
230
- jsonAppended(ctx, array, value) {
231
- return `JSON_INSERT(${array}, '$[#]', ${this.jsonScalarParam(ctx, value)})`;
230
+ jsonAppended(ctx, array, value, unless) {
231
+ return `JSON_INSERT(${array}, ${skippablePath(`'$[#]'`, unless)}, ${this.jsonScalarParam(ctx, value)})`;
232
232
  }
233
233
  }
@@ -7,6 +7,6 @@ import { TursoDialect } from './tursoDialect.js';
7
7
  export declare class TursoLocalDialect extends TursoDialect {
8
8
  readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorMetric>;
9
9
  readonly maxFunctionArgs: number;
10
- /** The engine appends nothing for a JSON null at a bare array's `[#]`, and does under a key, so a null goes under one. */
11
- protected jsonAppended(ctx: QueryContext, array: string, value: unknown): string;
10
+ /** At a bare array's `[#]` the engine appends nothing for `true`, `false` or `null`, so those go under a key. */
11
+ protected jsonAppended(ctx: QueryContext, array: string, value: unknown, unless?: string): string;
12
12
  }
@@ -1,3 +1,4 @@
1
+ import { skippablePath } from '../dialect/jsonSql.js';
1
2
  import { TursoDialect } from './tursoDialect.js';
2
3
  /**
3
4
  * SQLite Dialect specialization for the embedded Turso engine, the Rust engine alone: it adds a
@@ -10,11 +11,12 @@ export class TursoLocalDialect extends TursoDialect {
10
11
  ['inner', { fn: 'vector_distance_dot' }],
11
12
  ]);
12
13
  maxFunctionArgs = Infinity;
13
- /** The engine appends nothing for a JSON null at a bare array's `[#]`, and does under a key, so a null goes under one. */
14
- jsonAppended(ctx, array, value) {
15
- if (value !== null) {
16
- return super.jsonAppended(ctx, array, value);
14
+ /** At a bare array's `[#]` the engine appends nothing for `true`, `false` or `null`, so those go under a key. */
15
+ jsonAppended(ctx, array, value, unless) {
16
+ if (typeof value !== 'boolean' && value !== null) {
17
+ return super.jsonAppended(ctx, array, value, unless);
17
18
  }
18
- return `JSON_SET(JSON_OBJECT('a', ${array}), '$.a[#]', ${this.jsonScalarParam(ctx, value)}) -> '$.a'`;
19
+ const path = skippablePath(`'$.a[#]'`, unless);
20
+ return `JSON_SET(JSON_OBJECT('a', JSON(${array})), ${path}, ${this.jsonScalarParam(ctx, value)}) -> '$.a'`;
19
21
  }
20
22
  }
@@ -3,7 +3,7 @@ import type { SqlDialectName } from './dialect.js';
3
3
  import type { FilterOptions, RelationQuery } from './query.js';
4
4
  import type { ColumnRef, QuerySql, SqlFor, RelationAggregate } from './querySql.js';
5
5
  import type { QueryWhere } from './queryWhere.js';
6
- import type { AtLeastOne, Except, ExactlyOne, IsEqual, IsJson, JsonBrand, IsMany, Json, Scalar, Type, Unpacked, Writable } from './utility.js';
6
+ import type { AtLeastOne, Except, ExactlyOne, IsEqual, IsJson, JsonBrand, IsMany, Json, JsonScalar, Scalar, Type, Unpacked, Writable } from './utility.js';
7
7
  import type { VectorDistance, VectorIndexOptions, VectorIndexType } from './vector.js';
8
8
  /** Brands the property an entity is identified by, where it is not `id`, `_id` or `uuid`. */
9
9
  export declare const idKey: unique symbol;
@@ -119,12 +119,13 @@ export type JsonFieldPaths<E> = {
119
119
  type PathValue<T, P extends string> = unknown extends T ? unknown : NonNullable<T> extends readonly (infer U)[] ? PathValue<NonNullable<U>, P> : P extends `${infer K}.${infer Rest}` ? K extends keyof NonNullable<T> ? PathValue<NonNullable<T>[K], Rest> : unknown : P extends keyof NonNullable<T> ? NonNullable<T>[P] : unknown;
120
120
  /** The value at a JSON dot-path of `E`, `unknown` where it cannot be resolved, which keeps an untyped path permissive. */
121
121
  export type JsonFieldPathValue<E, P extends string> = P extends `${infer F}.${infer Rest}` ? F extends JsonFieldKey<E> ? PathValue<JsonPayload<E[F]>, Rest> : unknown : unknown;
122
- /**
123
- * The keys of `T` holding an array of `Element`, each mapped to its element type: what `$push` and `$pull`
124
- * address, and with scalar elements, `$addToSet`.
125
- */
126
- export type JsonArrayFields<T, Element = unknown> = {
127
- [K in keyof T as IsMany<T[K]> extends true ? Unpacked<NonNullable<T[K]>> extends Element ? K & string : never : never]?: Unpacked<NonNullable<T[K]>>;
122
+ /** The keys of `T` holding an array, each mapped to its element type: what `$push` and `$pull` address. */
123
+ export type JsonArrayFields<T> = {
124
+ [K in keyof T as IsMany<T[K]> extends true ? K & string : never]?: Unpacked<NonNullable<T[K]>>;
125
+ };
126
+ /** The keys of `T` holding an array with an element `$addToSet` takes, each mapped to that element. */
127
+ type JsonSetFields<T> = {
128
+ [K in keyof T as IsMany<T[K]> extends true ? [JsonSetElement<Unpacked<NonNullable<T[K]>>>] extends [never] ? never : K & string : never]?: JsonSetElement<Unpacked<NonNullable<T[K]>>>;
128
129
  };
129
130
  /**
130
131
  * A JSON field's update operators, applied in order on every engine, `$pull`, `$set`, `$push`, `$addToSet`,
@@ -138,13 +139,26 @@ export type JsonUpdateOp<T = unknown> = {
138
139
  readonly $unset?: unknown extends T ? readonly string[] : readonly ((keyof T & string) | JsonNestedPaths<T>)[];
139
140
  readonly $push?: JsonArrayFields<T>;
140
141
  readonly $pull?: JsonArrayFields<T>;
141
- readonly $addToSet?: JsonArrayFields<T, string | number | boolean>;
142
+ readonly $addToSet?: JsonSetFields<T>;
143
+ };
144
+ /**
145
+ * A JSON array column's update operators, each taking a list of elements, applied in order on every engine:
146
+ * `$pull` each, `$push` each, then `$addToSet` each the array lacks. A NULL column counts as an empty array,
147
+ * and a stored value that is no array stays as it is.
148
+ * @example `{ tags: { $pull: ['stale'], $addToSet: ['new'] } }`
149
+ */
150
+ export type JsonArrayUpdateOp<T = unknown> = {
151
+ readonly $pull?: readonly T[];
152
+ readonly $push?: readonly T[];
153
+ readonly $addToSet?: readonly JsonSetElement<T>[];
142
154
  };
155
+ /** What `$addToSet` takes from an array of `T`: its scalars, any scalar where `T` is untyped. */
156
+ type JsonSetElement<T> = unknown extends T ? JsonScalar : Extract<T, JsonScalar>;
143
157
  /**
144
- * The {@link JsonUpdateOp} a field takes: `never` on a non-JSON field, and on a JSON array, whose
145
- * operators would address keys it does not have (engines disagree on what that does).
158
+ * The update operators a field takes: {@link JsonArrayUpdateOp} on a JSON array, `Json<T[]>` or `Json<T>[]`,
159
+ * {@link JsonUpdateOp} on any other JSON field, and `never` on a field that is no JSON.
146
160
  */
147
- type JsonUpdateOpFor<V, T = UnwrapJson<NonNullable<V>>> = [T] extends [never] ? never : IsMany<T> extends true ? never : JsonUpdateOp<T>;
161
+ type JsonUpdateOpFor<V, T = UnwrapJson<NonNullable<V>>> = [T] extends [never] ? IsJsonColumn<V> extends true ? JsonArrayUpdateOp<JsonPayload<V>> : never : IsMany<T> extends true ? JsonArrayUpdateOp<Unpacked<T>> : JsonUpdateOp<T>;
148
162
  /**
149
163
  * A scalar field's update operator, as {@link JsonUpdateOp} is a JSON field's, computed in the statement:
150
164
  * `$inc` adds, `$mul` multiplies, a NULL counting as 0 on every engine. One per field, since their order
@@ -8,6 +8,8 @@ export type MongoId = {
8
8
  * collapse to `any` without it, switching every key check off.
9
9
  */
10
10
  export type Scalar = string | number | boolean | bigint | Date | RegExp | Uint8Array | MongoId;
11
+ /** A value a JSON document holds whole and every engine compares by equality, as `$addToSet` needs. */
12
+ export type JsonScalar = string | number | boolean;
11
13
  /**
12
14
  * Scalar types with a meaningful ordering, accepted by `$lt`/`$lte`/`$gt`/`$gte`/`$between`.
13
15
  */
@@ -1,5 +1,5 @@
1
1
  import type { IndexType } from '../schema/types.js';
2
- import { type AggregateCall, type CascadeType, type EntityData, type EntityIndexMeta, type EntityMeta, type FieldKey, type FieldOptions, type FieldUpdateOp, type JsonUpdateOp, type OnFieldCallback, type QueryAggMap, type QueryExclude, type QueryGroupMap, type QueryOptions, QuerySql, type QuerySearch, type QuerySelect, type QuerySelectValue, type QuerySortDirection, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryVectorQuery, type QueryVectorSearch, type QueryWhere, type RelationKey, type UpdatePayload, type VectorDistance } from '../type/index.js';
2
+ import { type AggregateCall, type CascadeType, type EntityData, type EntityIndexMeta, type EntityMeta, type FieldKey, type FieldOptions, type FieldUpdateOp, type JsonArrayUpdateOp, type JsonUpdateOp, type OnFieldCallback, type QueryAggMap, type QueryExclude, type QueryGroupMap, type QueryOptions, QuerySql, type QuerySearch, type QuerySelect, type QuerySelectValue, type QuerySortDirection, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryVectorQuery, type QueryVectorSearch, type QueryWhere, type RelationKey, type UpdatePayload, type VectorDistance } from '../type/index.js';
3
3
  export type CallbackKey = keyof Pick<FieldOptions, 'onInsert' | 'onUpdate'>;
4
4
  /** The keys of `payload` a write persists as columns. */
5
5
  export declare function filterFieldKeys<E>(meta: EntityMeta<E>, payload: EntityData<E> | UpdatePayload<E>, callbackKey: CallbackKey): FieldKey<E>[];
@@ -66,17 +66,15 @@ export declare function vectorDistanceOf<E>(meta: EntityMeta<E>, key: string, se
66
66
  */
67
67
  export declare function hasVectorNear(where: unknown): boolean;
68
68
  /** Type guard: checks whether an update payload value is a JSON operator object. */
69
- export declare function isJsonUpdateOp(value: unknown): value is JsonUpdateOp;
70
- /** An item one array key's writes append, `unique` where it goes in only if the stored array lacks it. */
69
+ export declare function isJsonUpdateOp(value: unknown): value is JsonUpdateOp | JsonArrayUpdateOp;
70
+ /** An item one array's writes append, `unique` where it goes in only if the stored array lacks it. */
71
71
  type JsonAppend = {
72
72
  readonly item: unknown;
73
73
  readonly unique: boolean;
74
74
  };
75
- /** One array key's writes, in order: `pull` removes every element equal to its item, then each append adds one. */
75
+ /** One array's writes, in order: each pull removes every element equal to it, then each append adds one. */
76
76
  export type JsonArrayWrites = {
77
- readonly pull?: {
78
- readonly item: unknown;
79
- };
77
+ readonly pulls: readonly unknown[];
80
78
  readonly appends: readonly JsonAppend[];
81
79
  };
82
80
  /** A JSON update with each path written once: the value set at each, each array key's writes, and the paths removed. */
@@ -87,12 +85,14 @@ export type JsonWrites = {
87
85
  };
88
86
  /** Whether the writes put a key into the document, so a NULL column must first become an object. */
89
87
  export declare function writesKeys({ set, arrays }: JsonWrites): boolean;
90
- /**
91
- * A JSON update as one write per path, its operators applied in order: `$pull`, `$set` in key order, `$push`,
92
- * `$addToSet`, `$unset`. Where one reaches a value another wrote, the result is worked out here, so every engine
93
- * writes each path once and reads only what is stored. A `$set` of `undefined` writes nothing.
94
- */
95
- export declare function foldJsonUpdate(value: JsonUpdateOp): JsonWrites;
88
+ /** A JSON update as its writes: those of an array column, or those of an object's keys. */
89
+ export type JsonUpdate = {
90
+ readonly array: JsonArrayWrites;
91
+ } | {
92
+ readonly object: JsonWrites;
93
+ };
94
+ /** A JSON update folded as an array column's, where its operands are lists of elements, else as an object's. */
95
+ export declare function foldJson(value: JsonUpdateOp | JsonArrayUpdateOp): JsonUpdate;
96
96
  /** Type guard: checks whether an update payload value is a scalar field's operator. */
97
97
  export declare function isFieldUpdateOp(value: unknown): value is FieldUpdateOp;
98
98
  /**