uql-orm 0.102.3 → 0.102.4

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.
@@ -253,13 +253,26 @@ export declare class MongoDialect extends AbstractDialect {
253
253
  /** The field a grouped path reads, on the document or on the joined one its lookup unwound. */
254
254
  private groupedPath;
255
255
  /**
256
- * An aggregate's own `$where` as the expression a `$cond` tests, which a query filter is not: the
257
- * comparisons, the logical operators and relations translate, anything else is refused by name. `lookup`
258
- * gathers the lookups it tests: a relation condition's, and a relation aggregate's it compares.
256
+ * An aggregate's own `$where` as the expression a `$cond` tests, matching the rows {@link renderFilter}
257
+ * would: a `$match` cannot sit inside a `$group`, and `$text`, bound to the pipeline's first stage, is
258
+ * refused by name. `lookup` gathers the lookups it tests: a relation condition's, and a relation aggregate's.
259
259
  */
260
260
  private whereExpression;
261
- /** One field's condition as an expression: a value it equals, a list it is in, or a map of comparisons. */
261
+ /**
262
+ * One field's condition as an expression, read as {@link transformOperators} reads it in a query: a value
263
+ * it equals, a list it is in, or operators. `wire` converts what a key field is compared with.
264
+ */
262
265
  private fieldExpression;
266
+ /**
267
+ * What `ref` satisfies to hold `value`, as {@link held} reads it in a query: an array each of its
268
+ * elements, an object each of its keys as a path, anything else as a field condition.
269
+ */
270
+ private heldExpression;
271
+ /**
272
+ * `$all`, as {@link allHolding} reads it: the array at `ref` has an element holding each value, a scalar
273
+ * by `$in`, which stops at the first match where testing each element would map them all.
274
+ */
275
+ private allHeld;
263
276
  private buildHavingFilter;
264
277
  /**
265
278
  * Separate vector sort entries from regular sort entries.
@@ -1,13 +1,13 @@
1
1
  import { ObjectId } from 'mongodb';
2
2
  import { AbstractDialect } from '../dialect/abstractDialect.js';
3
3
  import { AGGREGATE_VALUE_ALIAS, REL_NESTED_KEY, REL_FIELD_PREFIX, relTempField, SUM_COUNT_ALIAS, nullsSortField, sortAggregateField, TEXT_SCORE_ALIAS, } from '../dialect/aliases.js';
4
- import { betweenBounds, GROUP_OPS, groupClauses, isGroupOp, LIKE_OPS, likeRegex, whereOperators, } from '../dialect/operators.js';
4
+ import { betweenBounds, inOperands, 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
9
  import { aggregateOf, isSelectList, assertAggregateColumns, assertNoUndefined, assertNonNegativeInteger, columnFamily, countedRelations, entityName, fieldUpdateOf, fillOnFields, filterFieldKeys, findVectorIndex, findVectorSort, definedEntries, getKeys, holdsForeignKey, jsonPathKeys, getRelationRequestSummary, hasKeys, isFieldUpdateOp, isJsonObject, foldJson, writesKeys, isJsonUpdateOp, isOperatorMap, isOperatorObject, isRecord, isVectorSearch, normalizeScalarFieldSelection, parentJoins, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortDirection, rankedTextSearch, someKey, targetJoins, textSortOf, vectorDistanceOf, } from '../util/index.js';
10
- import { UqlUsageError } from '../util/uqlError.js';
10
+ import { kindOf, 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';
@@ -133,27 +133,67 @@ function andExpr(filter, expr) {
133
133
  filter['$expr'] = filter['$expr'] ? { $and: [filter['$expr'], expr] } : expr;
134
134
  }
135
135
  /**
136
- * `$size` against bounds, which MongoDB's own `$size` takes only as a number: the array at `path` counted
137
- * in an `$expr`, which no other value satisfies. `$and` may evaluate every operand, so the count reads an
138
- * empty array in place of any other value.
136
+ * `value` as an expression reads it, verbatim: bare, a string could name a field (`'$name'`), an object
137
+ * an operator, and an array its elements' expressions. A number reads as itself.
139
138
  */
140
- function arraySize(path, size) {
141
- const value = `$${path}`;
142
- const count = { $size: { $cond: [{ $isArray: value }, value, []] } };
143
- return { $and: [{ $isArray: value }, compareCount(count, size)] };
139
+ function literal(value) {
140
+ return typeof value === 'number' ? value : { $literal: value };
141
+ }
142
+ /** Every term true: the term itself when it is the only one. */
143
+ function allOf(terms) {
144
+ return terms.length === 1 ? terms[0] : { $and: terms };
145
+ }
146
+ /**
147
+ * The array at `ref` has `size` elements, or a count in its bounds: an expression, since MongoDB's own
148
+ * `$size` takes only a number. No other value has a size, and `$and` may evaluate every operand, so the
149
+ * count reads an empty array in place of one.
150
+ */
151
+ function arraySize(ref, size) {
152
+ const count = { $size: { $cond: [{ $isArray: ref }, ref, []] } };
153
+ return { $and: [{ $isArray: ref }, compareCount(count, size)] };
144
154
  }
145
155
  /** `count` compared with `size`, a number or its bounds, as an aggregation expression. */
146
156
  function compareCount(count, size) {
147
157
  if (typeof size === 'number') {
148
158
  return { $eq: [count, size] };
149
159
  }
150
- const comparisons = Object.entries(size).flatMap(([op, bound]) => op === '$between' && Array.isArray(bound)
151
- ? [{ $gte: [count, bound[0]] }, { $lte: [count, bound[1]] }]
152
- : [{ [op]: [count, bound] }]);
160
+ if (!isRecord(size)) {
161
+ throw new UqlUsageError(`$size expects a number or bounds, got ${kindOf(size)}`);
162
+ }
163
+ const comparisons = Object.entries(size).flatMap(([op, bound]) => {
164
+ if (op !== '$between') {
165
+ return [{ [op]: [count, literal(bound)] }];
166
+ }
167
+ const [min, max] = betweenBounds(bound);
168
+ return [{ $gte: [count, literal(min)] }, { $lte: [count, literal(max)] }];
169
+ });
153
170
  if (!comparisons.length) {
154
171
  throw new UqlUsageError('$size needs at least one comparison');
155
172
  }
156
- return comparisons.length === 1 ? comparisons[0] : { $and: comparisons };
173
+ return allOf(comparisons);
174
+ }
175
+ /** Whether the array at `ref` has an element `test` passes, reading it as `$$this`. No other value has one. */
176
+ function anyElement(ref, test) {
177
+ return { $cond: [{ $isArray: ref }, { $anyElementTrue: [{ $map: { input: ref, in: test } }] }, false] };
178
+ }
179
+ /**
180
+ * Whether `ref` holds a value of `operand`'s type, the only one a query's ordering compares it with: an
181
+ * expression orders across types, every string above a number and a null below it.
182
+ */
183
+ function sameType(ref, operand) {
184
+ return typeof operand === 'number' || typeof operand === 'bigint'
185
+ ? { $isNumber: ref }
186
+ : { $eq: [{ $type: ref }, { $type: literal(operand) }] };
187
+ }
188
+ /** Whether the string at `ref` matches `regex`. Any other value matches none, where `$regexMatch` would fail. */
189
+ function regexMatch(ref, regex, insensitive = false) {
190
+ const match = { $regexMatch: { input: ref, regex: literal(regex), ...(insensitive && { options: 'i' }) } };
191
+ return { $cond: [{ $eq: [{ $type: ref }, 'string'] }, match, false] };
192
+ }
193
+ /** Atlas offers only a similarity threshold, on the index's own scale: converting a distance would mean guessing the metric. */
194
+ function nearRefusal() {
195
+ return new UqlUsageError('$near is not supported on MongoDB: Atlas scores by index-defined similarity, not distance. ' +
196
+ "Project the score with $sort's $project and filter on it instead.");
157
197
  }
158
198
  /** MongoDB native operators - pass through as-is. */
159
199
  const NATIVE_OPS = new Set([
@@ -272,7 +312,7 @@ export class MongoDialect extends AbstractDialect {
272
312
  filter[key] = operators(val);
273
313
  }
274
314
  else {
275
- andExpr(filter, arraySize(key, size));
315
+ andExpr(filter, arraySize(`$${key}`, size));
276
316
  if (hasKeys(ops)) {
277
317
  filter[key] = operators(ops);
278
318
  }
@@ -398,8 +438,9 @@ export class MongoDialect extends AbstractDialect {
398
438
  result[op] = this.held(val);
399
439
  continue;
400
440
  }
401
- // `$not` wraps a condition too, so a uql-only operator inside it (`$isNull`, `$startsWith`) is mapped.
402
- if (op === '$not' && isOperatorObject(val)) {
441
+ // `$not` wraps a condition too: a value or a list as the operator it means, which native `$not` refuses,
442
+ // and a uql-only operator inside it (`$isNull`, `$startsWith`) mapped.
443
+ if (op === '$not') {
403
444
  result[op] = this.transformOperators(val, refusal);
404
445
  continue;
405
446
  }
@@ -437,10 +478,7 @@ export class MongoDialect extends AbstractDialect {
437
478
  result[val ? '$ne' : '$eq'] = null;
438
479
  break;
439
480
  case '$near':
440
- // Atlas offers only a similarity threshold, on the index's own scale, which UQL neither emits nor
441
- // reads: converting a distance would mean guessing the metric, so this refuses.
442
- throw new UqlUsageError('$near is not supported on MongoDB: Atlas scores by index-defined similarity, not distance. ' +
443
- "Project the score with $sort's $project and filter on it instead.");
481
+ throw nearRefusal();
444
482
  }
445
483
  }
446
484
  return result;
@@ -1261,9 +1299,9 @@ export class MongoDialect extends AbstractDialect {
1261
1299
  return `${joinedPath(join)}.${this.columnOf(join.meta, key)}`;
1262
1300
  }
1263
1301
  /**
1264
- * An aggregate's own `$where` as the expression a `$cond` tests, which a query filter is not: the
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.
1302
+ * An aggregate's own `$where` as the expression a `$cond` tests, matching the rows {@link renderFilter}
1303
+ * would: a `$match` cannot sit inside a `$group`, and `$text`, bound to the pipeline's first stage, is
1304
+ * refused by name. `lookup` gathers the lookups it tests: a relation condition's, and a relation aggregate's.
1267
1305
  */
1268
1306
  whereExpression(meta, where, lookup) {
1269
1307
  const terms = getKeys(where).map((key) => {
@@ -1275,57 +1313,102 @@ export class MongoDialect extends AbstractDialect {
1275
1313
  });
1276
1314
  return negate ? { $not: [{ [join]: clauses }] } : { [join]: clauses };
1277
1315
  }
1316
+ const val = where[key];
1317
+ assertNoRaw(val, 'an aggregate $where');
1278
1318
  if (meta.relations[key]) {
1279
- assertNoRaw(where[key], 'an aggregate $where');
1280
- return this.relationExpression(meta, key, where[key], lookup);
1319
+ return this.relationExpression(meta, key, val, lookup);
1281
1320
  }
1282
1321
  if (key.startsWith('$')) {
1283
1322
  throw new UqlUsageError(`aggregate $where operator '${key}' is not supported on MongoDB`);
1284
1323
  }
1285
- const val = where[key];
1324
+ this.assertKnownPathRoot(meta, key);
1286
1325
  this.appendAggregateField(meta, key, lookup);
1287
- const wire = this.holdsKeys(meta, key) ? (value) => this.toWireId(value) : (value) => value;
1326
+ const wire = this.holdsKeys(meta, key) ? (value) => this.toWireId(value) : undefined;
1288
1327
  return this.fieldExpression(`$${this.pathOf(meta, key)}`, val, wire);
1289
1328
  });
1290
- return terms.length === 1 ? terms[0] : { $and: terms };
1329
+ return allOf(terms);
1291
1330
  }
1292
- /** One field's condition as an expression: a value it equals, a list it is in, or a map of comparisons. */
1293
- fieldExpression(ref, val, wire) {
1294
- const equals = (value) => (value === null ? isNullExpr(ref) : { $eq: [ref, wire(value)] });
1295
- if (!isOperatorMap(val)) {
1296
- return Array.isArray(val) ? { $in: [ref, wire(val)] } : equals(val);
1331
+ /**
1332
+ * One field's condition as an expression, read as {@link transformOperators} reads it in a query: a value
1333
+ * it equals, a list it is in, or operators. `wire` converts what a key field is compared with.
1334
+ */
1335
+ fieldExpression(ref, val, wire = (value) => value) {
1336
+ const equals = (value) => (value === null ? isNullExpr(ref) : { $eq: [ref, literal(wire(value))] });
1337
+ const within = (op, values) => ({
1338
+ $in: [{ $ifNull: [ref, null] }, literal(wire(inOperands(op, values)))],
1339
+ });
1340
+ const ordered = (op, operand) => {
1341
+ const value = wire(operand);
1342
+ return { $and: [sameType(ref, value), { [op]: [ref, literal(value)] }] };
1343
+ };
1344
+ if (!isOperatorObject(val)) {
1345
+ return Array.isArray(val) ? within('$in', val) : equals(val);
1297
1346
  }
1298
- // A null or missing field compares below every value in an expression, where SQL leaves it unmatched.
1299
- const present = { $not: [isNullExpr(ref)] };
1300
1347
  const terms = Object.entries(val).map(([op, operand]) => {
1348
+ const like = LIKE_OPS.get(op);
1349
+ if (like) {
1350
+ return regexMatch(ref, likeRegex(like.pattern(String(operand))), like.insensitive);
1351
+ }
1301
1352
  switch (op) {
1302
1353
  case '$eq':
1303
1354
  return equals(operand);
1304
1355
  case '$ne':
1305
1356
  return { $not: [equals(operand)] };
1357
+ case '$not':
1358
+ return { $not: [this.fieldExpression(ref, operand, wire)] };
1306
1359
  case '$gt':
1307
1360
  case '$gte':
1308
- return { [op]: [ref, wire(operand)] };
1309
1361
  case '$lt':
1310
1362
  case '$lte':
1311
- return { $and: [present, { [op]: [ref, wire(operand)] }] };
1312
- case '$in':
1313
- return { $in: [ref, wire(operand)] };
1314
- case '$nin':
1315
- return { $not: [{ $in: [ref, wire(operand)] }] };
1363
+ return ordered(op, operand);
1316
1364
  case '$between': {
1317
- const [min, max] = operand;
1318
- return { $and: [{ $gte: [ref, wire(min)] }, { $lte: [ref, wire(max)] }] };
1365
+ const [min, max] = betweenBounds(operand);
1366
+ return { $and: [ordered('$gte', min), ordered('$lte', max)] };
1319
1367
  }
1368
+ case '$in':
1369
+ return within(op, operand);
1370
+ case '$nin':
1371
+ return { $not: [within(op, operand)] };
1320
1372
  case '$isNull':
1321
- return operand ? isNullExpr(ref) : present;
1322
1373
  case '$isNotNull':
1323
- return operand ? present : isNullExpr(ref);
1374
+ return (op === '$isNull') === Boolean(operand) ? equals(null) : { $not: [equals(null)] };
1375
+ case '$regex':
1376
+ return regexMatch(ref, String(operand));
1377
+ case '$size':
1378
+ return arraySize(ref, operand);
1379
+ case '$all':
1380
+ return this.allHeld(ref, inOperands(op, operand));
1381
+ case '$elemMatch':
1382
+ return this.allHeld(ref, [operand]);
1383
+ case '$near':
1384
+ throw nearRefusal();
1324
1385
  default:
1325
- throw new UqlUsageError(`aggregate $where operator '${op}' is not supported on MongoDB`);
1386
+ throw new UqlUsageError(`unknown operator: ${op}`);
1326
1387
  }
1327
1388
  });
1328
- return terms.length === 1 ? terms[0] : { $and: terms };
1389
+ return allOf(terms);
1390
+ }
1391
+ /**
1392
+ * What `ref` satisfies to hold `value`, as {@link held} reads it in a query: an array each of its
1393
+ * elements, an object each of its keys as a path, anything else as a field condition.
1394
+ */
1395
+ heldExpression(ref, value) {
1396
+ if (Array.isArray(value)) {
1397
+ return this.allHeld(ref, value);
1398
+ }
1399
+ if (isJsonObject(value)) {
1400
+ return allOf(Object.entries(value).map(([key, item]) => this.heldExpression(`${ref}.${key}`, item)));
1401
+ }
1402
+ return this.fieldExpression(ref, value);
1403
+ }
1404
+ /**
1405
+ * `$all`, as {@link allHolding} reads it: the array at `ref` has an element holding each value, a scalar
1406
+ * by `$in`, which stops at the first match where testing each element would map them all.
1407
+ */
1408
+ allHeld(ref, values) {
1409
+ return allOf(values.map((value) => isOperatorMap(value) || Array.isArray(value)
1410
+ ? anyElement(ref, this.heldExpression('$$this', value))
1411
+ : { $cond: [{ $isArray: ref }, { $in: [literal(value), ref] }, false] }));
1329
1412
  }
1330
1413
  buildHavingFilter(having) {
1331
1414
  const filter = {};
package/package.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "homepage": "https://uql-orm.dev",
4
4
  "description": "JSON-native TypeScript ORM for Bun, Browsers, Edge, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, SQL Server, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
5
5
  "license": "MIT",
6
- "version": "0.102.3",
6
+ "version": "0.102.4",
7
7
  "type": "module",
8
8
  "engines": {
9
9
  "node": ">=22.18"