uql-orm 0.101.6 → 0.102.1

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 (43) hide show
  1. package/dist/browser/uql-browser.min.js +2 -2
  2. package/dist/browser/uql-browser.min.js.map +3 -3
  3. package/dist/dialect/abstractDialect.js +2 -1
  4. package/dist/dialect/abstractSqlDialect.d.ts +54 -24
  5. package/dist/dialect/abstractSqlDialect.js +102 -52
  6. package/dist/dialect/aliases.d.ts +8 -0
  7. package/dist/dialect/aliases.js +24 -16
  8. package/dist/dialect/jsonSql.d.ts +10 -7
  9. package/dist/dialect/jsonSql.js +7 -10
  10. package/dist/dialect/mysqlLikeSqlDialect.d.ts +6 -10
  11. package/dist/dialect/mysqlLikeSqlDialect.js +13 -13
  12. package/dist/dialect/pgLikeSqlDialect.d.ts +20 -13
  13. package/dist/dialect/pgLikeSqlDialect.js +38 -29
  14. package/dist/libsql/libsqlDialect.d.ts +5 -0
  15. package/dist/libsql/libsqlDialect.js +5 -0
  16. package/dist/mongodb/mongoDialect.d.ts +4 -12
  17. package/dist/mongodb/mongoDialect.js +70 -70
  18. package/dist/mssql/mssqlDialect.d.ts +24 -14
  19. package/dist/mssql/mssqlDialect.js +42 -32
  20. package/dist/mysql/mysqlDialect.js +1 -1
  21. package/dist/querier/abstractQuerier.d.ts +52 -17
  22. package/dist/querier/abstractQuerier.js +141 -81
  23. package/dist/querier/abstractSqlQuerier.d.ts +5 -1
  24. package/dist/querier/abstractSqlQuerier.js +16 -1
  25. package/dist/querier/cursorStream.js +1 -2
  26. package/dist/sqlite/hranaQuerier.d.ts +2 -2
  27. package/dist/sqlite/hranaQuerier.js +2 -2
  28. package/dist/sqlite/localSqliteQuerierPool.js +8 -2
  29. package/dist/sqlite/sqliteDialect.d.ts +8 -7
  30. package/dist/sqlite/sqliteDialect.js +15 -9
  31. package/dist/turso/tursoLocalDialect.d.ts +3 -1
  32. package/dist/turso/tursoLocalDialect.js +7 -0
  33. package/dist/type/dialect.d.ts +6 -0
  34. package/dist/type/entity.d.ts +18 -10
  35. package/dist/type/querier.d.ts +6 -0
  36. package/dist/util/dialect.util.d.ts +27 -0
  37. package/dist/util/dialect.util.js +120 -4
  38. package/dist/util/field.util.d.ts +2 -0
  39. package/dist/util/field.util.js +5 -0
  40. package/dist/util/object.util.d.ts +2 -0
  41. package/dist/util/object.util.js +4 -0
  42. package/package.json +7 -7
  43. package/skills/uql-orm/SKILL.md +5 -5
@@ -6,7 +6,7 @@ import { escapePgSqlLiteral, PG_UTC } from '../util/sqlLiteral.js';
6
6
  import { ANSI_SQL_VALUES, AbstractSqlDialect, } from './abstractSqlDialect.js';
7
7
  import { JSON_PULL_ALIAS, RELATION_ROW_ALIAS } from './aliases.js';
8
8
  import { BYTES_PREFIX } from './hydrateColumn.js';
9
- import { jsonSetTarget } from './jsonSql.js';
9
+ import {} from './jsonSql.js';
10
10
  import { resolveVectorCast, toSparsevecLiteral } from './vectorCast.js';
11
11
  /** Each metric's pgvector distance operator, and the infix of the operator class its index is built with. */
12
12
  export const PG_VECTOR_METRICS = new Map([
@@ -33,6 +33,7 @@ export const PG_FEATURES = {
33
33
  serverSideCursors: true,
34
34
  correlatedWrites: true,
35
35
  rowLocks: { of: true, withWindow: false, placement: 'suffix' },
36
+ writeReturning: true,
36
37
  nullsSortLowest: false,
37
38
  nullsOrdering: 'clause',
38
39
  textScoreIndexes: false,
@@ -205,12 +206,15 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
205
206
  jsonElemFrom(slot, alias) {
206
207
  return `JSONB_ARRAY_ELEMENTS(${this.jsonArray(slot)}) AS ${alias}`;
207
208
  }
208
- jsonIsArray(slot) {
209
- return `JSONB_TYPEOF(${this.jsonValue(slot)}) = 'array'`;
209
+ jsonIs(slot, kind) {
210
+ return `JSONB_TYPEOF(${this.jsonValue(slot)}) = '${kind}'`;
211
+ }
212
+ jsonIsNull(slot) {
213
+ return `COALESCE(JSONB_TYPEOF(${this.jsonValue(slot)}), 'null') = 'null'`;
210
214
  }
211
215
  /** The array at `slot`, NULL where the value there is none: the array functions fail the whole read on one. */
212
216
  jsonArray(slot) {
213
- return `CASE WHEN ${this.jsonIsArray(slot)} THEN ${this.jsonValue(slot)} END`;
217
+ return `CASE WHEN ${this.jsonIs(slot, 'array')} THEN ${this.jsonValue(slot)} END`;
214
218
  }
215
219
  jsonElemDoc(alias) {
216
220
  return alias;
@@ -274,36 +278,41 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
274
278
  ctx.addValue(vectorType === 'sparsevec' ? toSparsevecLiteral(value) : `[${value.join(',')}]`);
275
279
  ctx.append(`::${vectorType}`);
276
280
  }
277
- /**
278
- * `create_if_missing => false` keeps an absent key (and a NULL column) untouched, and a value that is no
279
- * array is set back as it is; `WITH ORDINALITY` keeps the surviving elements in their original order.
280
- */
281
- jsonPullKey(ctx, expr, escapedCol, key, value) {
282
- const slot = { base: escapedCol, path: key };
283
- const kept = `SELECT JSONB_AGG(${JSON_PULL_ALIAS}.val ORDER BY ${JSON_PULL_ALIAS}.ord) FROM JSONB_ARRAY_ELEMENTS(${this.jsonValue(slot)}) WITH ORDINALITY AS ${JSON_PULL_ALIAS}(val, ord) WHERE ${JSON_PULL_ALIAS}.val <> ${this.jsonVal(ctx, value)}`;
284
- const pulled = `CASE WHEN ${this.jsonIsArray(slot)} THEN COALESCE((${kept}), '[]'::jsonb) ELSE COALESCE(${this.jsonValue(slot)}, 'null') END`;
285
- return `JSONB_SET(${expr}, '{"${key}"}', ${pulled}, false)`;
281
+ /** `WITH ORDINALITY` keeps the surviving elements in their original order. */
282
+ jsonKept(ctx, slot, item) {
283
+ return `SELECT JSONB_AGG(${JSON_PULL_ALIAS}.val ORDER BY ${JSON_PULL_ALIAS}.ord) FROM JSONB_ARRAY_ELEMENTS(${this.jsonValue(slot)}) WITH ORDINALITY AS ${JSON_PULL_ALIAS}(val, ord) WHERE ${JSON_PULL_ALIAS}.val <> ${this.jsonbOf(ctx, item)}`;
284
+ }
285
+ /** Each key or dotted path set as `jsonb`, which `JSONB_SET` takes and nothing else. */
286
+ jsonSet(ctx, expr, set) {
287
+ return Object.entries(set).reduce((acc, [path, value]) => this.jsonSetKey(acc, path, this.jsonbOf(ctx, value)), expr);
286
288
  }
287
289
  /**
288
- * The plain values merge as one bound object; a `sql()` one is an SQL expression rather than JSON,
289
- * so it merges through `JSONB_BUILD_OBJECT` and is evaluated in place - stringified with the rest,
290
- * it would land as `{}`.
290
+ * A value as `jsonb` inside a document: a null one JSON's, as `JSONB_SET` and a comparison need, and a `sql()`
291
+ * one read back out of an object, since `TO_JSONB` refuses an untyped literal.
291
292
  */
292
- jsonSet(ctx, expr, set, field) {
293
- const entries = Object.entries(set);
294
- const merged = this.jsonVal(ctx, Object.fromEntries(entries.filter(([, value]) => !(value instanceof QuerySql))));
295
- const raws = entries.flatMap(([key, value]) => value instanceof QuerySql ? [` || JSONB_BUILD_OBJECT('${key}', ${this.rawFragment(ctx, value)})`] : []);
296
- return `${jsonSetTarget(expr, field, `'{}'::jsonb`)} || ${merged}${raws.join('')}`;
297
- }
298
- /** The only fragment that references `expr` twice - safe here because placeholders are numbered. */
299
- jsonPush(ctx, expr, push) {
300
- return Object.entries(push).reduce((acc, [key, value]) => {
301
- const ph = this.jsonVal(ctx, value);
302
- return `JSONB_SET(${acc}, '{"${key}"}', COALESCE((${acc})->'${key}', '[]'::jsonb) || JSONB_BUILD_ARRAY(${ph}))`;
303
- }, expr);
293
+ jsonbOf(ctx, value) {
294
+ if (value instanceof QuerySql) {
295
+ return `JSONB_BUILD_OBJECT('v', ${this.rawFragment(ctx, value)})->'v'`;
296
+ }
297
+ return value === null ? `'null'::jsonb` : this.jsonVal(ctx, value);
298
+ }
299
+ /** `JSONB_BUILD_ARRAY` takes any type, and a NULL as JSON's null. */
300
+ jsonAppended(ctx, array, value) {
301
+ return `${array} || JSONB_BUILD_ARRAY(${this.jsonVal(ctx, value)})`;
302
+ }
303
+ jsonEmptyObject = `'{}'::jsonb`;
304
+ jsonEmptyArray = `'[]'::jsonb`;
305
+ /** `JSONB_SET` takes one path, so each key wraps the last. */
306
+ jsonWriteKeys(expr, writes, { create }) {
307
+ return writes.reduce((acc, [slot, value]) => this.jsonSetKey(acc, slot.path, this.jsonOrStored(slot, value), { create }), expr);
308
+ }
309
+ /** A replace hands an absent key's NULL back, which `JSONB_SET` would answer for the whole document. */
310
+ jsonSetKey(expr, path, value, { create = true } = {}) {
311
+ const set = create ? value : `COALESCE(${value}, 'null'::jsonb), false`;
312
+ return `JSONB_SET(${expr}, '${toPgArray(jsonPathKeys(path))}', ${set})`;
304
313
  }
305
314
  jsonUnset(ctx, expr, unset) {
306
- return `(${expr}) - ${this.addValue(ctx, [...unset])}::text[]`;
315
+ return unset.reduce((acc, path) => `(${acc}) #- '${toPgArray(jsonPathKeys(path))}'`, expr);
307
316
  }
308
317
  /** Postgres binds JSON with a numbered placeholder and an explicit cast, per driver capability. */
309
318
  jsonScalarParam(ctx, value) {
@@ -10,6 +10,11 @@ export declare const LIBSQL_FEATURES: SqlDialectFeatures;
10
10
  */
11
11
  export declare class LibsqlDialect extends SqliteDialect {
12
12
  readonly features: SqlDialectFeatures;
13
+ /**
14
+ * Every transaction a write one, as `@libsql/client`'s `transaction('write')` opens it: a deferred one that
15
+ * reads, then writes, cannot upgrade while another connection writes, and fails rather than waiting.
16
+ */
17
+ readonly beginTransactionCommand = "BEGIN IMMEDIATE";
13
18
  /** libSQL's built-in vector functions, and the metric its DiskANN index names; no `inner` (only the Rust engine has it) and no `l1`. */
14
19
  readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorMetric>;
15
20
  }
@@ -9,6 +9,11 @@ export const LIBSQL_FEATURES = { ...SQLITE_FEATURES, orderedJsonAggregates: fals
9
9
  */
10
10
  export class LibsqlDialect extends SqliteDialect {
11
11
  features = LIBSQL_FEATURES;
12
+ /**
13
+ * Every transaction a write one, as `@libsql/client`'s `transaction('write')` opens it: a deferred one that
14
+ * reads, then writes, cannot upgrade while another connection writes, and fails rather than waiting.
15
+ */
16
+ beginTransactionCommand = 'BEGIN IMMEDIATE';
12
17
  /** libSQL's built-in vector functions, and the metric its DiskANN index names; no `inner` (only the Rust engine has it) and no `l1`. */
13
18
  vectorMetrics = new Map([
14
19
  ['cosine', { fn: 'vector_distance_cos', index: 'cosine' }],
@@ -1,4 +1,4 @@
1
- import { type Document, type Filter, type Sort, type UpdateFilter } from 'mongodb';
1
+ import { type Document, type Filter, type Sort } from 'mongodb';
2
2
  import { AbstractDialect } from '../dialect/abstractDialect.js';
3
3
  import type { DialectFeatures, EntityData, EntityMeta, Query, QueryAggMap, QueryAggregate, QueryExclude, QueryGroupMap, QueryOptions, QueryPager, QuerySelectValue, QuerySortMap, QueryVectorSearch, QueryWhere, Type } from '../type/index.js';
4
4
  import { type CallbackKey } from '../util/index.js';
@@ -225,19 +225,11 @@ export declare class MongoDialect extends AbstractDialect {
225
225
  /** The seam out of the driver: an `ObjectId` becomes its hex string, the type the code declares. */
226
226
  fromWireId(value: unknown): unknown;
227
227
  getPersistable<E extends Document>(meta: EntityMeta<E>, payload: EntityData<E>, callbackKey: CallbackKey): Partial<E>;
228
- /** One MongoDB update document's operators, grouped by kind and keyed by dotted path. */
229
- private groupUpdateOperators;
230
228
  /**
231
- * Turn a persistable payload into a MongoDB update, mapping UQL's JSON operators onto their native
232
- * equivalents: `$set` becomes dotted-path assignments, `$unset`/`$push`/`$pull` map one-to-one.
233
- * Plain field values are assigned with `$set`.
229
+ * A payload as one update pipeline, so every engine's answer holds: a `null` or missing document or array
230
+ * counts as empty, and values go in as `$literal`, so `$x` stays data.
234
231
  */
235
- getUpdateFilter<E extends Document>(persistable: Partial<E>): UpdateFilter<E> | Document[];
236
- /**
237
- * An update as one pipeline, since MongoDB refuses two operators on one path: each path composed as
238
- * `$pull`, `$set`, `$push`, then `$unset`, as SQL does, with values as `$literal` so `$x` stays data.
239
- */
240
- private getUpdatePipeline;
232
+ getUpdateFilter<E extends Document>(persistable: Partial<E>): Document[];
241
233
  /** Refuses a key left to MongoDB that it cannot mint: only an `ObjectId`, read back as a string, so not a `Number`. */
242
234
  private assertMintableKey;
243
235
  getPersistables<E extends Document>(meta: EntityMeta<E>, payload: EntityData<E> | EntityData<E>[], callbackKey: CallbackKey): Partial<E>[];
@@ -6,13 +6,66 @@ import { aggregateColumnField, groupPathField, resolveGroupJoins, relationSortTe
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, jsonKey, jsonPathKeys, getRelationRequestSummary, hasKeys, isFieldUpdateOp, isJsonObject, 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, foldJsonUpdate, 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
14
  /** A scalar field's operator as the aggregation operator computing it. */
15
15
  const MONGO_ARITHMETIC = { $inc: '$add', $mul: '$multiply' };
16
+ /**
17
+ * One array key's writes at `path`, as SQL writes them: the pull, then each append onto `[]` in place of a
18
+ * missing or null array, a `unique` one only where the array lacks its item; a value that is no array stays.
19
+ */
20
+ function arrayWrite(path, { pull, appends }) {
21
+ const stored = `$${path}`;
22
+ const kept = (array) => pull ? { $filter: { input: array, cond: { $ne: ['$$this', { $literal: pull.item }] } } } : array;
23
+ if (appends.length === 0) {
24
+ return { $cond: [{ $isArray: stored }, kept(stored), stored] };
25
+ }
26
+ const array = { $ifNull: [stored, []] };
27
+ const addends = appends.map(({ item, unique }) => {
28
+ const literal = [{ $literal: item }];
29
+ return unique ? { $cond: [{ $in: [{ $literal: item }, array] }, [], literal] } : literal;
30
+ });
31
+ return { $cond: [{ $isArray: array }, { $concatArrays: [kept(array), ...addends] }, stored] };
32
+ }
33
+ /** The value at `path`: a `$literal` one as it is, or the object of its nested children, merged in. */
34
+ function assignedAt(path, node) {
35
+ return '$literal' in node ? node : mergedObject(path, node);
36
+ }
37
+ /** The object at `path` with `children` merged in: as SQL, a stored value that is no object counts as `{}`. */
38
+ function mergedObject(path, children) {
39
+ return {
40
+ $mergeObjects: [
41
+ { $cond: [{ $eq: [{ $type: `$${path}` }, 'object'] }, `$${path}`, {}] },
42
+ Object.fromEntries(Object.entries(children).map(([key, child]) => [key, assignedAt(`${path}.${key}`, child)])),
43
+ ],
44
+ };
45
+ }
46
+ /**
47
+ * A JSON column's one assignment: each path's write merged into its object, the nested `$set` paths under one
48
+ * key merged into that key's. A column that is no object becomes one where a key is written, and else stays.
49
+ */
50
+ function jsonAssignments(column, writes) {
51
+ // Prototype-free, so a key such as `__proto__` is a key of the document and not an object's prototype.
52
+ const nested = Object.create(null);
53
+ for (const [key, item] of Object.entries(writes.set)) {
54
+ const keys = jsonPathKeys(key);
55
+ const parent = keys.slice(0, -1).reduce((node, part) => (node[part] ??= Object.create(null)), nested);
56
+ parent[keys[keys.length - 1]] = { $literal: item };
57
+ }
58
+ const children = Object.fromEntries([
59
+ ...Object.entries(nested).map(([key, node]) => [key, assignedAt(`${column}.${key}`, node)]),
60
+ ...Object.entries(writes.arrays).map(([key, write]) => [key, arrayWrite(`${column}.${key}`, write)]),
61
+ ]);
62
+ if (!hasKeys(children)) {
63
+ return {};
64
+ }
65
+ const isObject = { $eq: [{ $type: `$${column}` }, 'object'] };
66
+ const otherwise = writesKeys(writes) ? children : `$${column}`;
67
+ return { [column]: { $cond: [isObject, { $mergeObjects: [`$${column}`, children] }, otherwise] } };
68
+ }
16
69
  /** Default {@link DialectFeatures} for MongoDB. */
17
70
  export const mongoDialectFeatures = {
18
71
  indexIfNotExists: false,
@@ -28,6 +81,7 @@ export const mongoDialectFeatures = {
28
81
  serverSideCursors: false,
29
82
  correlatedWrites: false,
30
83
  rowLocks: false, // its concurrency control is the transaction plus atomic document updates
84
+ writeReturning: false,
31
85
  nullsSortLowest: true,
32
86
  };
33
87
  /** What `toWireId` converts: the hex spelling of an `ObjectId`, and nothing looser. */
@@ -994,83 +1048,29 @@ export class MongoDialect extends AbstractDialect {
994
1048
  getPersistable(meta, payload, callbackKey) {
995
1049
  return this.getPersistables(meta, payload, callbackKey)[0];
996
1050
  }
997
- /** One MongoDB update document's operators, grouped by kind and keyed by dotted path. */
998
- groupUpdateOperators(persistable) {
999
- const set = {};
1000
- const push = {};
1001
- const pull = {};
1002
- const arithmetic = {};
1003
- const unset = new Set();
1051
+ /**
1052
+ * A payload as one update pipeline, so every engine's answer holds: a `null` or missing document or array
1053
+ * counts as empty, and values go in as `$literal`, so `$x` stays data.
1054
+ */
1055
+ getUpdateFilter(persistable) {
1056
+ const assignments = {};
1057
+ const unset = [];
1004
1058
  for (const [key, value] of Object.entries(persistable)) {
1005
1059
  if (isFieldUpdateOp(value)) {
1006
1060
  const [op, operand] = fieldUpdateOf(key, value);
1007
1061
  assertNoRaw(operand, 'a write');
1008
- arithmetic[key] = { [MONGO_ARITHMETIC[op]]: [{ $ifNull: [`$${key}`, 0] }, { $literal: operand }] };
1009
- continue;
1010
- }
1011
- if (!isJsonUpdateOp(value)) {
1012
- set[key] = value;
1013
- continue;
1062
+ assignments[key] = { [MONGO_ARITHMETIC[op]]: [{ $ifNull: [`$${key}`, 0] }, { $literal: operand }] };
1014
1063
  }
1015
- [...getKeys(value.$set), ...getKeys(value.$push), ...getKeys(value.$pull), ...(value.$unset ?? [])].forEach(jsonKey);
1016
- for (const [path, v] of Object.entries(value.$set ?? {})) {
1017
- set[`${key}.${path}`] = v;
1064
+ 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}`));
1018
1068
  }
1019
- for (const path of value.$unset ?? []) {
1020
- unset.add(`${key}.${path}`);
1021
- }
1022
- for (const [path, v] of Object.entries(value.$push ?? {})) {
1023
- push[`${key}.${path}`] = v;
1024
- }
1025
- for (const [path, v] of Object.entries(value.$pull ?? {})) {
1026
- pull[`${key}.${path}`] = v;
1027
- }
1028
- }
1029
- return { set, push, pull, arithmetic, unset };
1030
- }
1031
- /**
1032
- * Turn a persistable payload into a MongoDB update, mapping UQL's JSON operators onto their native
1033
- * equivalents: `$set` becomes dotted-path assignments, `$unset`/`$push`/`$pull` map one-to-one.
1034
- * Plain field values are assigned with `$set`.
1035
- */
1036
- getUpdateFilter(persistable) {
1037
- const groups = this.groupUpdateOperators(persistable);
1038
- const { set, push, pull, arithmetic, unset } = groups;
1039
- const exprKeys = [...Object.keys(pull), ...Object.keys(set), ...Object.keys(push)];
1040
- // Native `$pull` fails on a value that is no array, native `$inc`/`$mul` on a `null`, and MongoDB
1041
- // rejects two operators targeting one path in a single update document: each forces the pipeline form.
1042
- const allPaths = [...exprKeys, ...unset];
1043
- if (hasKeys(pull) || hasKeys(arithmetic) || new Set(allPaths).size < allPaths.length) {
1044
- return this.getUpdatePipeline(groups, new Set(exprKeys));
1045
- }
1046
- return {
1047
- ...(hasKeys(set) && { $set: set }),
1048
- ...(hasKeys(push) && { $push: push }),
1049
- ...(unset.size > 0 && { $unset: Object.fromEntries([...unset].map((path) => [path, ''])) }),
1050
- };
1051
- }
1052
- /**
1053
- * An update as one pipeline, since MongoDB refuses two operators on one path: each path composed as
1054
- * `$pull`, `$set`, `$push`, then `$unset`, as SQL does, with values as `$literal` so `$x` stays data.
1055
- */
1056
- getUpdatePipeline({ set, push, pull, arithmetic, unset }, exprPaths) {
1057
- const assignments = { ...arithmetic };
1058
- for (const path of exprPaths) {
1059
- let expr = { $ifNull: [`$${path}`, []] };
1060
- if (path in pull) {
1061
- expr = { $filter: { input: expr, cond: { $ne: ['$$this', { $literal: pull[path] }] } } };
1062
- }
1063
- if (path in set) {
1064
- expr = { $literal: set[path] };
1065
- }
1066
- if (path in push) {
1067
- expr = { $concatArrays: [expr, [{ $literal: push[path] }]] };
1069
+ else {
1070
+ assignments[key] = { $literal: value };
1068
1071
  }
1069
- // Only `$set` and `$push` create a key. A `$pull` alone leaves any value that is no array as it is,
1070
- // and an absent one absent, since a pipeline `$set` of a missing field adds none.
1071
- assignments[path] = path in set || path in push ? expr : { $cond: [{ $isArray: `$${path}` }, expr, `$${path}`] };
1072
1072
  }
1073
- return [{ $set: assignments }, ...(unset.size > 0 ? [{ $unset: [...unset] }] : [])];
1073
+ return [...(hasKeys(assignments) ? [{ $set: assignments }] : []), ...(unset.length > 0 ? [{ $unset: unset }] : [])];
1074
1074
  }
1075
1075
  /** Refuses a key left to MongoDB that it cannot mint: only an `ObjectId`, read back as a string, so not a `Number`. */
1076
1076
  assertMintableKey(meta, field) {
@@ -1,7 +1,7 @@
1
1
  import { type RelationRows, type SelectTerm } from '../dialect/abstractSqlDialect.js';
2
- import { type JsonAccessMode, type JsonSlot } from '../dialect/jsonSql.js';
2
+ import { type JsonAccessMode, type JsonContainer, type JsonKeyWrite, type JsonSlot } from '../dialect/jsonSql.js';
3
3
  import { MergeSqlDialect } from '../dialect/mergeSqlDialect.js';
4
- import type { EntityMeta, SavepointCommand, FieldOptions, Query, QueryConflictPaths, QueryContext, QueryOptions, QueryPager, SqlDialectFeatures, SqlValues, TriggerRows, Type, UpdatePayload, VectorDistance, VectorMetric } from '../type/index.js';
4
+ import type { EntityMeta, SavepointCommand, FieldOptions, Query, QueryConflictPaths, QueryContext, QueryOptions, QueryPager, SqlDialectFeatures, SqlValues, TriggerRows, Type, UpdatePayload, VectorDistance, VectorMetric, TransactionOptions } from '../type/index.js';
5
5
  /** Microsoft SQL Server 2017 and up. Identifiers are `"`-quoted, the ANSI spelling `tedious` enables. */
6
6
  export declare class MsSqlDialect extends MergeSqlDialect {
7
7
  #private;
@@ -14,10 +14,10 @@ export declare class MsSqlDialect extends MergeSqlDialect {
14
14
  /** SQL Server saves a transaction under a name and rolls back to it, and releases none: the commit does. */
15
15
  savepointStatement(command: SavepointCommand, name: string): string;
16
16
  /**
17
- * T-SQL has no inline form, so the level is set before the `BEGIN`. What a driver that sends these
18
- * as statements would run; `MsSqlQuerier` opens its transactions through the driver instead.
17
+ * T-SQL has no inline form, so the level is set before the `BEGIN`, and no read-only transaction. What a
18
+ * driver that sends these as statements would run; `MsSqlQuerier` opens its transactions through the driver.
19
19
  */
20
- readonly isolationLevelStrategy = "setBefore";
20
+ getBeginTransactionStatements({ isolationLevel }?: TransactionOptions): string[];
21
21
  readonly booleanLiteral = "integer";
22
22
  /**
23
23
  * The clock in UTC, since `CURRENT_TIMESTAMP` is local time in the server's zone. No v7: `NEWSEQUENTIALID()` is
@@ -135,8 +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. */
139
- protected jsonIsArray(slot: JsonSlot): string;
138
+ /** `JSON_QUERY` answers an array or an object as written, and a scalar as NULL, so its first character tells which. */
139
+ protected jsonIs(slot: JsonSlot, kind: JsonContainer): string;
140
+ /** `OPENJSON` answers a JSON null as NULL, as it does a key that is not there. */
141
+ protected jsonIsNull(slot: JsonSlot): string;
140
142
  /** An object element's `value` is its JSON text, which its fields are paths into. */
141
143
  protected jsonElemDoc(alias: string): string;
142
144
  /**
@@ -149,15 +151,23 @@ export declare class MsSqlDialect extends MergeSqlDialect {
149
151
  /** SQL Server orders JSON as the text `OPENJSON` reads, so a number sorts by its value first. */
150
152
  protected readonly jsonSortModes: readonly JsonAccessMode[];
151
153
  /** `JSON_MODIFY` takes one path per call, so several keys chain into one expression. */
152
- protected jsonSet(ctx: QueryContext, expr: string, set: Record<string, unknown>, _field?: FieldOptions): string;
153
- /** `'append '` prefixing the path extends the array there, creating it where there is none. */
154
- protected jsonPush(ctx: QueryContext, expr: string, push: Record<string, unknown>): string;
154
+ protected jsonSet(ctx: QueryContext, expr: string, set: Record<string, unknown>): string;
155
+ /** Text, which `JSON_MODIFY` reads as JSON once `JSON_QUERY` marks it. */
156
+ protected readonly jsonEmptyObject = "'{}'";
157
+ protected readonly jsonEmptyArray = "'[]'";
158
+ /**
159
+ * The value chooses the path, not the document: a NULL one, where the stored value stays, goes to a key that is
160
+ * not there, which `JSON_MODIFY` leaves alone. So the document is read once per key, and a stored scalar, which
161
+ * `JSON_QUERY` refuses, is never written back.
162
+ */
163
+ protected jsonWriteKeys(expr: string, writes: readonly JsonKeyWrite[]): string;
164
+ protected jsonAppended(ctx: QueryContext, array: string, value: unknown): string;
155
165
  /** Assigning NULL to a path deletes it in lax mode, which is the default. */
156
166
  protected jsonUnset(_ctx: QueryContext, expr: string, unset: readonly string[]): string;
157
167
  /**
158
- * The surviving elements are re-aggregated into an array and written back whole - there is no
159
- * remove-by-value. `JSON_QUERY` is what marks the rebuilt text as JSON rather than a string. Only an
160
- * array is rewritten: `JSON_MODIFY` would create an absent key, and any other value stays as it is.
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.
161
171
  */
162
- protected jsonPullKey(ctx: QueryContext, expr: string, escapedCol: string, key: string, value: unknown): string;
172
+ protected jsonKept(ctx: QueryContext, slot: JsonSlot, item: unknown): string;
163
173
  }
@@ -1,7 +1,7 @@
1
- import { ANSI_SQL_VALUES, fromRows, relationTermKey, } from '../dialect/abstractSqlDialect.js';
2
- import { AGGREGATE_VALUE_ALIAS, JSON_PULL_ALIAS } from '../dialect/aliases.js';
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';
3
3
  import { BYTES_PREFIX } from '../dialect/hydrateColumn.js';
4
- import { jsonArraySlotArgs, jsonPath, jsonSlotArgs } from '../dialect/jsonSql.js';
4
+ import { 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';
@@ -30,6 +30,7 @@ const MSSQL_FEATURES = {
30
30
  serverSideCursors: false,
31
31
  correlatedWrites: true,
32
32
  rowLocks: { of: true, withWindow: true, placement: 'tableHint' },
33
+ writeReturning: false,
33
34
  nullsSortLowest: true,
34
35
  nullsOrdering: 'case',
35
36
  textScoreIndexes: false,
@@ -58,8 +59,6 @@ function openJsonType(value) {
58
59
  }
59
60
  return typeof value === 'boolean' ? 3 : 1;
60
61
  }
61
- /** The table variable an `OUTPUT` fills, `_uql`-prefixed as every name uql invents is. */
62
- const OUTPUT_TABLE = '@_uql_output';
63
62
  /** The one key column and its field, or nothing on a composite key. */
64
63
  function soleId(meta) {
65
64
  const [key] = meta.ids;
@@ -90,10 +89,12 @@ export class MsSqlDialect extends MergeSqlDialect {
90
89
  return statements[command];
91
90
  }
92
91
  /**
93
- * T-SQL has no inline form, so the level is set before the `BEGIN`. What a driver that sends these
94
- * as statements would run; `MsSqlQuerier` opens its transactions through the driver instead.
92
+ * T-SQL has no inline form, so the level is set before the `BEGIN`, and no read-only transaction. What a
93
+ * driver that sends these as statements would run; `MsSqlQuerier` opens its transactions through the driver.
95
94
  */
96
- isolationLevelStrategy = 'setBefore';
95
+ getBeginTransactionStatements({ isolationLevel } = {}) {
96
+ return isolationSetBefore(isolationLevel, this.beginTransactionCommand);
97
+ }
97
98
  booleanLiteral = 'integer';
98
99
  /**
99
100
  * The clock in UTC, since `CURRENT_TIMESTAMP` is local time in the server's zone. No v7: `NEWSEQUENTIALID()` is
@@ -350,11 +351,15 @@ export class MsSqlDialect extends MergeSqlDialect {
350
351
  return `JSON_QUERY(${this.addValue(ctx, JSON.stringify(value))})`;
351
352
  }
352
353
  jsonElemFrom(slot, alias) {
353
- return `OPENJSON(${jsonArraySlotArgs(slot, this.jsonIsArray(slot))}) ${alias}`;
354
+ return `OPENJSON(${jsonArraySlotArgs(slot, this.jsonIs(slot, 'array'))}) ${alias}`;
355
+ }
356
+ /** `JSON_QUERY` answers an array or an object as written, and a scalar as NULL, so its first character tells which. */
357
+ jsonIs(slot, kind) {
358
+ return `LEFT(JSON_QUERY(${jsonSlotArgs(slot)}), 1) = '${kind === 'array' ? '[' : '{'}'`;
354
359
  }
355
- /** `JSON_QUERY` answers an array or an object as written, and a scalar as NULL. */
356
- jsonIsArray(slot) {
357
- return `LEFT(JSON_QUERY(${jsonSlotArgs(slot)}), 1) = '['`;
360
+ /** `OPENJSON` answers a JSON null as NULL, as it does a key that is not there. */
361
+ jsonIsNull(slot) {
362
+ return `${this.jsonValue(slot)} IS NULL`;
358
363
  }
359
364
  /** An object element's `value` is its JSON text, which its fields are paths into. */
360
365
  jsonElemDoc(alias) {
@@ -376,47 +381,52 @@ export class MsSqlDialect extends MergeSqlDialect {
376
381
  return `${equal} AND ${type} = ${openJsonType(value)}`;
377
382
  }
378
383
  jsonLength(slot) {
379
- return `(SELECT COUNT(*) FROM OPENJSON(${jsonArraySlotArgs(slot, this.jsonIsArray(slot))}))`;
384
+ return `(SELECT COUNT(*) FROM OPENJSON(${jsonArraySlotArgs(slot, this.jsonIs(slot, 'array'))}))`;
380
385
  }
381
386
  /** SQL Server orders JSON as the text `OPENJSON` reads, so a number sorts by its value first. */
382
387
  jsonSortModes = ['numeric', 'text'];
383
388
  /** `JSON_MODIFY` takes one path per call, so several keys chain into one expression. */
384
- jsonSet(ctx, expr, set, _field) {
389
+ jsonSet(ctx, expr, set) {
385
390
  for (const [key, value] of Object.entries(set)) {
386
391
  if (value === null) {
387
392
  throw new UqlUsageError(`mssql cannot $set '${key}' to null: JSON_MODIFY deletes the key instead. Use $unset, or store a JSON null through a whole-column write.`);
388
393
  }
389
394
  }
390
- return Object.entries(set).reduce((acc, [key, value]) => `JSON_MODIFY(${acc}, ${jsonPath(key)}, ${this.jsonWriteParam(ctx, value)})`, `COALESCE(${expr}, '{}')`);
395
+ return Object.entries(set).reduce((acc, [key, value]) => `JSON_MODIFY(${acc}, ${jsonPath(key)}, ${this.jsonWriteParam(ctx, value)})`, expr);
396
+ }
397
+ /** Text, which `JSON_MODIFY` reads as JSON once `JSON_QUERY` marks it. */
398
+ jsonEmptyObject = `'{}'`;
399
+ jsonEmptyArray = `'[]'`;
400
+ /**
401
+ * The value chooses the path, not the document: a NULL one, where the stored value stays, goes to a key that is
402
+ * not there, which `JSON_MODIFY` leaves alone. So the document is read once per key, and a stored scalar, which
403
+ * `JSON_QUERY` refuses, is never written back.
404
+ */
405
+ jsonWriteKeys(expr, writes) {
406
+ return writes.reduce((acc, [slot, value]) => {
407
+ const path = `CASE WHEN ${value} IS NULL THEN ${jsonPath(JSON_SKIP_KEY)} ELSE ${jsonPath(slot.path)} END`;
408
+ return `JSON_MODIFY(${acc}, ${path}, JSON_QUERY(${value}))`;
409
+ }, expr);
391
410
  }
392
- /** `'append '` prefixing the path extends the array there, creating it where there is none. */
393
- jsonPush(ctx, expr, push) {
394
- return Object.entries(push).reduce((acc, [key, value]) => `JSON_MODIFY(${acc}, 'append ${jsonPath(key).slice(1, -1)}', ${this.jsonWriteParam(ctx, value)})`, `COALESCE(${expr}, '{}')`);
411
+ jsonAppended(ctx, array, value) {
412
+ return `JSON_MODIFY(${array}, 'append $', ${this.jsonWriteParam(ctx, value)})`;
395
413
  }
396
414
  /** Assigning NULL to a path deletes it in lax mode, which is the default. */
397
415
  jsonUnset(_ctx, expr, unset) {
398
416
  return unset.reduce((acc, key) => `JSON_MODIFY(${acc}, ${jsonPath(key)}, NULL)`, expr);
399
417
  }
400
418
  /**
401
- * The surviving elements are re-aggregated into an array and written back whole - there is no
402
- * remove-by-value. `JSON_QUERY` is what marks the rebuilt text as JSON rather than a string. Only an
403
- * array is rewritten: `JSON_MODIFY` would create an absent key, and any other value stays as it is.
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.
404
422
  */
405
- jsonPullKey(ctx, expr, escapedCol, key, value) {
406
- const slot = { base: escapedCol, path: key };
423
+ jsonKept(ctx, slot, item) {
407
424
  const val = this.jsonElemDoc(JSON_PULL_ALIAS);
408
- // `OPENJSON` hands back a string element unquoted and a null one as SQL NULL, so each survivor is
409
- // re-encoded from its reported `type` before the array is put back together - concatenated raw,
410
- // the result is text the engine then refuses to parse as JSON.
411
425
  const encoded = `CASE ${JSON_PULL_ALIAS}.${this.#elem.type}` +
412
426
  ` WHEN 0 THEN 'null'` +
413
427
  ` WHEN 1 THEN '"' + STRING_ESCAPE(${val}, 'json') + '"'` +
414
428
  ` ELSE ${val} END`;
415
- // `IS NULL OR` because a JSON null element reads back as SQL NULL, and `<>` against one is
416
- // unknown rather than true - which silently dropped every null from the array it rebuilt.
417
- const kept = `SELECT '[' + STRING_AGG(${encoded}, ',') + ']' FROM ${this.jsonElemFrom(slot, JSON_PULL_ALIAS)}` +
418
- ` WHERE ${val} IS NULL OR ${val} <> ${this.jsonScalarParam(ctx, value)}`;
419
- const pulled = `JSON_MODIFY(${expr}, ${jsonPath(key)}, JSON_QUERY(COALESCE((${kept}), '[]')))`;
420
- return `CASE WHEN ${this.jsonIsArray(slot)} THEN ${pulled} ELSE ${expr} 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}`;
421
431
  }
422
432
  }
@@ -18,7 +18,7 @@ export class MySqlDialect extends MysqlLikeSqlDialect {
18
18
  */
19
19
  jsonAny(ctx, slot, values) {
20
20
  const overlaps = `JSON_OVERLAPS(${this.jsonValue(slot)}, ${this.addValue(ctx, JSON.stringify(values))})`;
21
- return `(${this.jsonIsArray(slot)} AND ${overlaps})`;
21
+ return `(${this.jsonIs(slot, 'array')} AND ${overlaps})`;
22
22
  }
23
23
  /**
24
24
  * A `SET_VAR` hint, which MySQL reads only right after the statement's own `SELECT` keyword - before