uql-orm 0.102.0 → 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 (34) 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 +42 -21
  5. package/dist/dialect/abstractSqlDialect.js +79 -39
  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 +4 -8
  11. package/dist/dialect/mysqlLikeSqlDialect.js +8 -11
  12. package/dist/dialect/pgLikeSqlDialect.d.ts +20 -13
  13. package/dist/dialect/pgLikeSqlDialect.js +37 -29
  14. package/dist/mongodb/mongoDialect.d.ts +4 -12
  15. package/dist/mongodb/mongoDialect.js +69 -70
  16. package/dist/mssql/mssqlDialect.d.ts +20 -10
  17. package/dist/mssql/mssqlDialect.js +35 -28
  18. package/dist/mysql/mysqlDialect.js +1 -1
  19. package/dist/querier/abstractQuerier.js +1 -2
  20. package/dist/querier/cursorStream.js +1 -2
  21. package/dist/sqlite/localSqliteQuerierPool.js +8 -2
  22. package/dist/sqlite/sqliteDialect.d.ts +4 -4
  23. package/dist/sqlite/sqliteDialect.js +10 -8
  24. package/dist/turso/tursoLocalDialect.d.ts +3 -1
  25. package/dist/turso/tursoLocalDialect.js +7 -0
  26. package/dist/type/entity.d.ts +18 -10
  27. package/dist/util/dialect.util.d.ts +27 -0
  28. package/dist/util/dialect.util.js +120 -4
  29. package/dist/util/field.util.d.ts +2 -0
  30. package/dist/util/field.util.js +5 -0
  31. package/dist/util/object.util.d.ts +2 -0
  32. package/dist/util/object.util.js +4 -0
  33. package/package.json +7 -7
  34. package/skills/uql-orm/SKILL.md +3 -3
@@ -1,5 +1,5 @@
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
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. */
@@ -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
1
  import { ANSI_SQL_VALUES, fromRows, relationTermKey, isolationSetBefore, } from '../dialect/abstractSqlDialect.js';
2
- import { AGGREGATE_VALUE_ALIAS, JSON_PULL_ALIAS } from '../dialect/aliases.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';
@@ -59,8 +59,6 @@ function openJsonType(value) {
59
59
  }
60
60
  return typeof value === 'boolean' ? 3 : 1;
61
61
  }
62
- /** The table variable an `OUTPUT` fills, `_uql`-prefixed as every name uql invents is. */
63
- const OUTPUT_TABLE = '@_uql_output';
64
62
  /** The one key column and its field, or nothing on a composite key. */
65
63
  function soleId(meta) {
66
64
  const [key] = meta.ids;
@@ -353,11 +351,15 @@ export class MsSqlDialect extends MergeSqlDialect {
353
351
  return `JSON_QUERY(${this.addValue(ctx, JSON.stringify(value))})`;
354
352
  }
355
353
  jsonElemFrom(slot, alias) {
356
- return `OPENJSON(${jsonArraySlotArgs(slot, this.jsonIsArray(slot))}) ${alias}`;
354
+ return `OPENJSON(${jsonArraySlotArgs(slot, this.jsonIs(slot, 'array'))}) ${alias}`;
357
355
  }
358
- /** `JSON_QUERY` answers an array or an object as written, and a scalar as NULL. */
359
- jsonIsArray(slot) {
360
- return `LEFT(JSON_QUERY(${jsonSlotArgs(slot)}), 1) = '['`;
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' ? '[' : '{'}'`;
359
+ }
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`;
361
363
  }
362
364
  /** An object element's `value` is its JSON text, which its fields are paths into. */
363
365
  jsonElemDoc(alias) {
@@ -379,47 +381,52 @@ export class MsSqlDialect extends MergeSqlDialect {
379
381
  return `${equal} AND ${type} = ${openJsonType(value)}`;
380
382
  }
381
383
  jsonLength(slot) {
382
- return `(SELECT COUNT(*) FROM OPENJSON(${jsonArraySlotArgs(slot, this.jsonIsArray(slot))}))`;
384
+ return `(SELECT COUNT(*) FROM OPENJSON(${jsonArraySlotArgs(slot, this.jsonIs(slot, 'array'))}))`;
383
385
  }
384
386
  /** SQL Server orders JSON as the text `OPENJSON` reads, so a number sorts by its value first. */
385
387
  jsonSortModes = ['numeric', 'text'];
386
388
  /** `JSON_MODIFY` takes one path per call, so several keys chain into one expression. */
387
- jsonSet(ctx, expr, set, _field) {
389
+ jsonSet(ctx, expr, set) {
388
390
  for (const [key, value] of Object.entries(set)) {
389
391
  if (value === null) {
390
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.`);
391
393
  }
392
394
  }
393
- 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);
394
410
  }
395
- /** `'append '` prefixing the path extends the array there, creating it where there is none. */
396
- jsonPush(ctx, expr, push) {
397
- 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)})`;
398
413
  }
399
414
  /** Assigning NULL to a path deletes it in lax mode, which is the default. */
400
415
  jsonUnset(_ctx, expr, unset) {
401
416
  return unset.reduce((acc, key) => `JSON_MODIFY(${acc}, ${jsonPath(key)}, NULL)`, expr);
402
417
  }
403
418
  /**
404
- * The surviving elements are re-aggregated into an array and written back whole - there is no
405
- * remove-by-value. `JSON_QUERY` is what marks the rebuilt text as JSON rather than a string. Only an
406
- * 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.
407
422
  */
408
- jsonPullKey(ctx, expr, escapedCol, key, value) {
409
- const slot = { base: escapedCol, path: key };
423
+ jsonKept(ctx, slot, item) {
410
424
  const val = this.jsonElemDoc(JSON_PULL_ALIAS);
411
- // `OPENJSON` hands back a string element unquoted and a null one as SQL NULL, so each survivor is
412
- // re-encoded from its reported `type` before the array is put back together - concatenated raw,
413
- // the result is text the engine then refuses to parse as JSON.
414
425
  const encoded = `CASE ${JSON_PULL_ALIAS}.${this.#elem.type}` +
415
426
  ` WHEN 0 THEN 'null'` +
416
427
  ` WHEN 1 THEN '"' + STRING_ESCAPE(${val}, 'json') + '"'` +
417
428
  ` ELSE ${val} END`;
418
- // `IS NULL OR` because a JSON null element reads back as SQL NULL, and `<>` against one is
419
- // unknown rather than true - which silently dropped every null from the array it rebuilt.
420
- const kept = `SELECT '[' + STRING_AGG(${encoded}, ',') + ']' FROM ${this.jsonElemFrom(slot, JSON_PULL_ALIAS)}` +
421
- ` WHERE ${val} IS NULL OR ${val} <> ${this.jsonScalarParam(ctx, value)}`;
422
- const pulled = `JSON_MODIFY(${expr}, ${jsonPath(key)}, JSON_QUERY(COALESCE((${kept}), '[]')))`;
423
- 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}`;
424
431
  }
425
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
@@ -1,4 +1,5 @@
1
1
  import { getMeta, idOf, namesKey, relationOf } from '../entity/index.js';
2
+ import { SAVEPOINT_PREFIX } from '../dialect/aliases.js';
2
3
  import { namesRows } from '../dialect/operators.js';
3
4
  import { parseQueryLock } from '../type/index.js';
4
5
  import { childrenExcept, childrenOf, chunk, clone, entityName, fillOnFields, filterFieldKeys, forEachRequestedRelation, getKeys, hasKeys, getRelationRequestSummary, guardWrite, idOnlyQuery, keyJoins, keySet, isPagedQuery, isScalarId, LoggerWrapper, normalizeScalarFieldSelection, parentJoins, pointAt, queryLoggerFor, parseRelationAtKey, parseRelationQueryValue, rowKey, runHooks, securityConditions, someKey, targetJoins, whereEach, whereIds, whereKeysIn, whereWith, withoutSoftDeleteFilter, cascadingRelations, holdsForeignKey, } from '../util/index.js';
@@ -164,8 +165,6 @@ function ownedRelations(meta) {
164
165
  function listedRows(value) {
165
166
  return value == null ? [] : Array.isArray(value) ? value : [value];
166
167
  }
167
- /** What a savepoint the querier names is called, its depth appended. */
168
- const SAVEPOINT_PREFIX = '_uql_sp';
169
168
  /** Runs the callbacks a transaction gathered for its commit, in the order they were registered. */
170
169
  async function runCallbacks(callbacks) {
171
170
  for (const callback of callbacks) {
@@ -1,5 +1,4 @@
1
- /** The cursor a stream declares. Suffixed per call, so two streams on one connection cannot collide. */
2
- const CURSOR_ALIAS = '_uql_cursor';
1
+ import { CURSOR_ALIAS } from '../dialect/aliases.js';
3
2
  /** Rows per round trip, matching `pg-query-stream`'s own default so both paths read the same. */
4
3
  const FETCH_SIZE = 100;
5
4
  let cursorSeq = 0;
@@ -31,9 +31,15 @@ export function extendSqlite(db, extensions = []) {
31
31
  db.function?.('regexp', { deterministic: true }, regexp);
32
32
  return db;
33
33
  }
34
- /** `value REGEXP pattern`: NULL where the value is, as an operator answers. */
34
+ const CASELESS_FLAG = '(?i)';
35
+ /** `value REGEXP pattern`: NULL where the value is, as an operator answers; a leading `(?i)` folds case, as other engines read it. */
35
36
  function regexp(pattern, value) {
36
- return value === null ? null : Number(new RegExp(String(pattern)).test(String(value)));
37
+ if (value === null) {
38
+ return null;
39
+ }
40
+ const source = String(pattern);
41
+ const caseless = source.startsWith(CASELESS_FLAG);
42
+ return Number(new RegExp(caseless ? source.slice(CASELESS_FLAG.length) : source, caseless ? 'i' : '').test(String(value)));
37
43
  }
38
44
  /** A pool for a database file opened in this process, configured the same way whichever driver's {@link createDb} opens it. */
39
45
  export class AbstractLocalSqliteQuerierPool extends AbstractSharedHandleQuerierPool {
@@ -1,5 +1,5 @@
1
1
  import { AbstractSqlDialect, type DerivedRelation, 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 JsonSlot } from '../dialect/jsonSql.js';
3
3
  import { type EntityMeta, type FieldOptions, type Query, type QueryContext, type QueryTextSearchOptions, type QueryWhere, type SqlDialectFeatures, type SqlValues, type VectorDistance, type VectorMetric, type TransactionOptions } from '../type/index.js';
4
4
  /** What SQLite and the engines derived from it have. */
5
5
  export declare const SQLITE_FEATURES: SqlDialectFeatures;
@@ -70,7 +70,8 @@ export declare class SqliteDialect extends AbstractSqlDialect {
70
70
  protected jsonLength(slot: JsonSlot): string;
71
71
  /** `JSON_EACH` walks the array at the path itself, each element's `fullkey` naming it from the column. */
72
72
  protected jsonElemFrom(slot: JsonSlot, alias: string): string;
73
- protected jsonIsArray(slot: JsonSlot): string;
73
+ protected jsonIs(slot: JsonSlot, kind: JsonContainer): string;
74
+ protected jsonIsNull(slot: JsonSlot): string;
74
75
  /** An object element's `value` is its JSON text, which its fields are paths into. */
75
76
  protected jsonElemDoc(alias: string): string;
76
77
  /**
@@ -86,6 +87,5 @@ export declare class SqliteDialect extends AbstractSqlDialect {
86
87
  protected jsonCast(operand: string): string;
87
88
  /** `JSON` keeps each element's JSON type in the array, which answers `[]` for no rows. */
88
89
  protected jsonArrayOf(elem: string): string;
89
- /** `[#]` appends, creating the array where it is absent. */
90
- protected jsonPush(ctx: QueryContext, expr: string, push: Record<string, unknown>): string;
90
+ protected jsonAppended(ctx: QueryContext, array: string, value: unknown): 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, jsonSetCall, jsonPath, jsonArraySlotArgs, jsonSlotArgs, } from '../dialect/jsonSql.js';
3
+ import { chainedCall, groupsPerCall, jsonPath, 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';
@@ -182,14 +182,17 @@ export class SqliteDialect extends AbstractSqlDialect {
182
182
  ctx.append(`-BM25(${this.escapedTableName(meta)})`);
183
183
  }
184
184
  jsonLength(slot) {
185
- return `JSON_ARRAY_LENGTH(${jsonArraySlotArgs(slot, this.jsonIsArray(slot))})`;
185
+ return `JSON_ARRAY_LENGTH(${jsonArraySlotArgs(slot, this.jsonIs(slot, 'array'))})`;
186
186
  }
187
187
  /** `JSON_EACH` walks the array at the path itself, each element's `fullkey` naming it from the column. */
188
188
  jsonElemFrom(slot, alias) {
189
- return `JSON_EACH(${jsonArraySlotArgs(slot, this.jsonIsArray(slot))}) ${alias}`;
189
+ return `JSON_EACH(${jsonArraySlotArgs(slot, this.jsonIs(slot, 'array'))}) ${alias}`;
190
190
  }
191
- jsonIsArray(slot) {
192
- return `JSON_TYPE(${jsonSlotArgs(slot)}) = 'array'`;
191
+ jsonIs(slot, kind) {
192
+ return `JSON_TYPE(${jsonSlotArgs(slot)}) = '${kind}'`;
193
+ }
194
+ jsonIsNull(slot) {
195
+ return `COALESCE(JSON_TYPE(${jsonSlotArgs(slot)}), 'null') = 'null'`;
193
196
  }
194
197
  /** An object element's `value` is its JSON text, which its fields are paths into. */
195
198
  jsonElemDoc(alias) {
@@ -224,8 +227,7 @@ export class SqliteDialect extends AbstractSqlDialect {
224
227
  jsonArrayOf(elem) {
225
228
  return `JSON_GROUP_ARRAY(JSON(${elem}))`;
226
229
  }
227
- /** `[#]` appends, creating the array where it is absent. */
228
- jsonPush(ctx, expr, push) {
229
- return jsonSetCall((value) => this.jsonScalarParam(ctx, value), expr, push, this.maxFunctionArgs, '[#]');
230
+ jsonAppended(ctx, array, value) {
231
+ return `JSON_INSERT(${array}, '$[#]', ${this.jsonScalarParam(ctx, value)})`;
230
232
  }
231
233
  }
@@ -1,4 +1,4 @@
1
- import type { VectorDistance, VectorMetric } from '../type/index.js';
1
+ import type { QueryContext, VectorDistance, VectorMetric } from '../type/index.js';
2
2
  import { TursoDialect } from './tursoDialect.js';
3
3
  /**
4
4
  * SQLite Dialect specialization for the embedded Turso engine, the Rust engine alone: it adds a
@@ -7,4 +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
12
  }
@@ -10,4 +10,11 @@ export class TursoLocalDialect extends TursoDialect {
10
10
  ['inner', { fn: 'vector_distance_dot' }],
11
11
  ]);
12
12
  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);
17
+ }
18
+ return `JSON_SET(JSON_OBJECT('a', ${array}), '$.a[#]', ${this.jsonScalarParam(ctx, value)}) -> '$.a'`;
19
+ }
13
20
  }
@@ -97,11 +97,13 @@ type JsonFieldKey<E> = {
97
97
  }[JsonColumnKey<E>];
98
98
  /**
99
99
  * The dot-paths into a JSON payload: any suffix on an untyped one, none past a scalar, an array's
100
- * element's, and an object's keys five levels deep, below which any suffix is accepted.
100
+ * element's unless `Arrays` is false, and an object's keys five levels deep, below which any suffix is accepted.
101
101
  */
102
- type DeepJsonKeys<T, D extends unknown[] = []> = unknown extends T ? string : NonNullable<T> extends Scalar ? never : NonNullable<T> extends readonly (infer U)[] ? DeepJsonKeys<U, D> : D['length'] extends 5 ? string : {
103
- [K in keyof NonNullable<T> & string]: K | `${K}.${DeepJsonKeys<NonNullable<T>[K], [...D, unknown]>}`;
102
+ type DeepJsonKeys<T, D extends unknown[] = [], Arrays = true> = unknown extends T ? string : NonNullable<T> extends Scalar ? never : NonNullable<T> extends readonly (infer U)[] ? Arrays extends true ? DeepJsonKeys<U, D, Arrays> : never : D['length'] extends 5 ? string : {
103
+ [K in keyof NonNullable<T> & string]: K | `${K}.${DeepJsonKeys<NonNullable<T>[K], [...D, unknown], Arrays>}`;
104
104
  }[keyof NonNullable<T> & string];
105
+ /** The dotted paths into `T`'s nested objects, never through an array: what a dotted `$set` and `$unset` name. */
106
+ type JsonNestedPaths<T> = Extract<DeepJsonKeys<T, [], false>, `${string}.${string}`>;
105
107
  /**
106
108
  * The dot-paths into an entity's JSON columns: `kind?: Json<{ theme: { color: string } }>` gives
107
109
  * `'kind.theme' | 'kind.theme.color'`, `items?: Json<{ id: string }>[]` gives `'items.id'`, and an
@@ -117,20 +119,26 @@ export type JsonFieldPaths<E> = {
117
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;
118
120
  /** The value at a JSON dot-path of `E`, `unknown` where it cannot be resolved, which keeps an untyped path permissive. */
119
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;
120
- /** The array keys of `T`, each mapped to its element type: what `$push` and `$pull` address. */
121
- export type JsonArrayFields<T> = {
122
- [K in keyof T as IsMany<T[K]> extends true ? K & string : never]?: Unpacked<NonNullable<T[K]>>;
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]>>;
123
128
  };
124
129
  /**
125
- * A JSON field's update operators, applied `$pull`, `$set`, `$push`, `$unset` on every engine: `$set`
126
- * assigns top-level keys (no deep merge), `$pull` removes every equal element. See the JSON guide.
130
+ * A JSON field's update operators, applied in order on every engine, `$pull`, `$set`, `$push`, `$addToSet`,
131
+ * `$unset`, each seeing what the one before wrote; see the JSON guide.
127
132
  * @example `{ kind: { $set: { public: 1 }, $push: { tags: 'x' }, $unset: ['private'] } }`
128
133
  */
129
134
  export type JsonUpdateOp<T = unknown> = {
130
- readonly $set?: Partial<T>;
131
- readonly $unset?: unknown extends T ? readonly string[] : readonly (keyof T & string)[];
135
+ readonly $set?: Partial<T> & {
136
+ readonly [P in JsonNestedPaths<T>]?: PathValue<T, P>;
137
+ };
138
+ readonly $unset?: unknown extends T ? readonly string[] : readonly ((keyof T & string) | JsonNestedPaths<T>)[];
132
139
  readonly $push?: JsonArrayFields<T>;
133
140
  readonly $pull?: JsonArrayFields<T>;
141
+ readonly $addToSet?: JsonArrayFields<T, string | number | boolean>;
134
142
  };
135
143
  /**
136
144
  * The {@link JsonUpdateOp} a field takes: `never` on a non-JSON field, and on a JSON array, whose
@@ -67,6 +67,32 @@ export declare function vectorDistanceOf<E>(meta: EntityMeta<E>, key: string, se
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
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. */
71
+ type JsonAppend = {
72
+ readonly item: unknown;
73
+ readonly unique: boolean;
74
+ };
75
+ /** One array key's writes, in order: `pull` removes every element equal to its item, then each append adds one. */
76
+ export type JsonArrayWrites = {
77
+ readonly pull?: {
78
+ readonly item: unknown;
79
+ };
80
+ readonly appends: readonly JsonAppend[];
81
+ };
82
+ /** A JSON update with each path written once: the value set at each, each array key's writes, and the paths removed. */
83
+ export type JsonWrites = {
84
+ readonly set: Readonly<Record<string, unknown>>;
85
+ readonly arrays: Readonly<Record<string, JsonArrayWrites>>;
86
+ readonly unset: readonly string[];
87
+ };
88
+ /** Whether the writes put a key into the document, so a NULL column must first become an object. */
89
+ 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;
70
96
  /** Type guard: checks whether an update payload value is a scalar field's operator. */
71
97
  export declare function isFieldUpdateOp(value: unknown): value is FieldUpdateOp;
72
98
  /**
@@ -187,3 +213,4 @@ export declare function rankedTextSearch<E>(where: QueryWhere<E> | undefined): Q
187
213
  * where neither says, rather than guessed: every engine answers a guess with an error of its own.
188
214
  */
189
215
  export declare function textSearchFields<E>(meta: EntityMeta<E>, search: QueryTextSearchOptions<E>): readonly string[];
216
+ export {};
@@ -1,8 +1,8 @@
1
1
  import { getContext } from '../context/context.js';
2
2
  import { QuerySql, resolveAggregateOp, SOFT_DELETE_FILTER, } from '../type/index.js';
3
3
  import { DEFAULT_VECTOR_DISTANCE, VECTOR_INDEX_TYPES } from '../type/vector.js';
4
- import { defaultReadKeys, fieldKeys, isDatabaseWritten } from './field.util.js';
5
- import { entityName, getKeys, hasKeys, isOperatorObject, isRecord, someKey } from './object.util.js';
4
+ import { defaultReadKeys, fieldKeys, isDatabaseWritten, jsonKey, jsonPathKeys } from './field.util.js';
5
+ import { entityName, getKeys, hasKeys, isJsonScalar, isOperatorObject, isRecord, someKey } from './object.util.js';
6
6
  import { assertNoUndefined, whereAnd } from './query.util.js';
7
7
  import { UqlSecurityError, UqlUsageError } from './uqlError.js';
8
8
  /** The keys of `payload` a write persists as columns. */
@@ -208,15 +208,131 @@ function indexCoversColumn(index, key) {
208
208
  }
209
209
  /** `satisfies` ties this to {@link JsonUpdateOp}, so renaming an operator breaks it at compile time. */
210
210
  const JSON_UPDATE_OPS = [
211
+ '$pull',
211
212
  '$set',
212
- '$unset',
213
213
  '$push',
214
- '$pull',
214
+ '$addToSet',
215
+ '$unset',
215
216
  ];
216
217
  /** Type guard: checks whether an update payload value is a JSON operator object. */
217
218
  export function isJsonUpdateOp(value) {
218
219
  return isRecord(value) && someKey(value, (key) => JSON_UPDATE_OPS.includes(key));
219
220
  }
221
+ /** Whether the writes put a key into the document, so a NULL column must first become an object. */
222
+ export function writesKeys({ set, arrays }) {
223
+ return hasKeys(set) || Object.values(arrays).some((write) => write.appends.length > 0);
224
+ }
225
+ /**
226
+ * A JSON update as one write per path, its operators applied in order: `$pull`, `$set` in key order, `$push`,
227
+ * `$addToSet`, `$unset`. Where one reaches a value another wrote, the result is worked out here, so every engine
228
+ * writes each path once and reads only what is stored. A `$set` of `undefined` writes nothing.
229
+ */
230
+ export function foldJsonUpdate(value) {
231
+ const set = new Map();
232
+ const arrays = new Map();
233
+ const unset = new Set();
234
+ for (const [key, item] of Object.entries(value.$pull ?? {})) {
235
+ arrays.set(jsonKey(key), { pull: { item }, appends: [] });
236
+ }
237
+ for (const [path, item] of Object.entries(value.$set ?? {})) {
238
+ if (item !== undefined) {
239
+ const keys = jsonPathKeys(path);
240
+ arrays.delete(keys[0]);
241
+ dropWithin(set, path);
242
+ const owner = ownerOf(set, keys);
243
+ if (owner) {
244
+ set.set(owner.path, withPath(owner.path, set.get(owner.path), owner.rest, item));
245
+ }
246
+ else {
247
+ set.set(path, item);
248
+ }
249
+ }
250
+ }
251
+ for (const op of ['$push', '$addToSet']) {
252
+ for (const [key, item] of Object.entries(value[op] ?? {})) {
253
+ const unique = op === '$addToSet';
254
+ if (unique && !isJsonScalar(item)) {
255
+ throw new UqlUsageError(`$addToSet on '${key}' takes a string, a finite number or a boolean`);
256
+ }
257
+ appendTo(set, arrays, jsonKey(key), item, unique);
258
+ }
259
+ }
260
+ for (const path of value.$unset ?? []) {
261
+ const keys = jsonPathKeys(path);
262
+ dropWithin(set, path);
263
+ arrays.delete(path);
264
+ const owner = ownerOf(set, keys);
265
+ if (owner) {
266
+ set.set(owner.path, withoutPath(owner.path, set.get(owner.path), owner.rest));
267
+ }
268
+ else {
269
+ unset.add(path);
270
+ }
271
+ }
272
+ return { set: Object.fromEntries(set), arrays: Object.fromEntries(arrays), unset: [...unset] };
273
+ }
274
+ /** `item` appended at `key`: onto the array a `$set` wrote there, or else among the key's array writes. */
275
+ function appendTo(set, arrays, key, item, unique) {
276
+ if (set.has(key)) {
277
+ const written = set.get(key);
278
+ assertNotSql(key, written);
279
+ if (written === null) {
280
+ set.set(key, [item]);
281
+ }
282
+ else if (Array.isArray(written) && !(unique && written.includes(item))) {
283
+ set.set(key, [...written, item]);
284
+ }
285
+ return;
286
+ }
287
+ if ([...set.keys()].some((path) => path.startsWith(`${key}.`))) {
288
+ return;
289
+ }
290
+ const write = arrays.get(key) ?? { appends: [] };
291
+ arrays.set(key, write);
292
+ if (!(unique && write.appends.some((append) => append.item === item))) {
293
+ write.appends.push({ item, unique: unique && write.pull?.item !== item });
294
+ }
295
+ }
296
+ /** Removes `path` and every path inside it from `set`. */
297
+ function dropWithin(set, path) {
298
+ for (const written of set.keys()) {
299
+ if (written === path || written.startsWith(`${path}.`)) {
300
+ set.delete(written);
301
+ }
302
+ }
303
+ }
304
+ /** The path in `set` holding the value `keys` lead into, and the keys left below it. */
305
+ function ownerOf(set, keys) {
306
+ for (let depth = 1; depth < keys.length; depth++) {
307
+ const path = keys.slice(0, depth).join('.');
308
+ if (set.has(path)) {
309
+ return { path, rest: keys.slice(depth) };
310
+ }
311
+ }
312
+ return undefined;
313
+ }
314
+ /** `value` with `item` at `keys`, a value that is no object becoming one, as a dotted `$set` makes it. */
315
+ function withPath(path, value, [key, ...rest], item) {
316
+ assertNotSql(path, value);
317
+ const object = isRecord(value) ? value : {};
318
+ const inner = Object.hasOwn(object, key) ? object[key] : undefined;
319
+ return { ...object, [key]: rest.length > 0 ? withPath(path, inner, rest, item) : item };
320
+ }
321
+ /** `value` without `keys`, as it is where they lead nowhere. */
322
+ function withoutPath(path, value, [key, ...rest]) {
323
+ assertNotSql(path, value);
324
+ if (!isRecord(value) || !Object.hasOwn(value, key)) {
325
+ return value;
326
+ }
327
+ const { [key]: inner, ...others } = value;
328
+ return rest.length > 0 ? { ...others, [key]: withoutPath(path, inner, rest) } : others;
329
+ }
330
+ /** Refuses an operator inside a value `sql` sets, whose result the statement cannot know. */
331
+ function assertNotSql(path, value) {
332
+ if (value instanceof QuerySql) {
333
+ throw new UqlUsageError(`'${path}' is set by sql, so no other operator can write inside it`);
334
+ }
335
+ }
220
336
  /** `satisfies` ties this to {@link FieldUpdateOp}, so renaming an operator breaks it at compile time. */
221
337
  const FIELD_UPDATE_OPS = ['$inc', '$mul'];
222
338
  /** Type guard: checks whether an update payload value is a scalar field's operator. */
@@ -68,3 +68,5 @@ export declare function defaultReadKeys<E>(meta: EntityMeta<E>): FieldKey<E>[];
68
68
  export declare function jsonKey(key: string): string;
69
69
  /** The keys of a dotted JSON path (`settings.theme`), each a {@link jsonKey}. */
70
70
  export declare function jsonPathKeys(path: string): string[];
71
+ /** The paths a dotted JSON path passes through, outermost first, not counting the path itself. */
72
+ export declare function ancestorPaths(path: string): string[];
@@ -138,3 +138,8 @@ export function jsonKey(key) {
138
138
  export function jsonPathKeys(path) {
139
139
  return path.split('.').map(jsonKey);
140
140
  }
141
+ /** The paths a dotted JSON path passes through, outermost first, not counting the path itself. */
142
+ export function ancestorPaths(path) {
143
+ const keys = jsonPathKeys(path);
144
+ return keys.slice(0, -1).map((_, depth) => keys.slice(0, depth + 1).join('.'));
145
+ }
@@ -1,4 +1,6 @@
1
1
  import type { EntityMeta } from '../type/index.js';
2
+ /** A value a JSON document holds whole, and `$addToSet` and an `=` on a JSON path compare by equality. */
3
+ export declare function isJsonScalar(value: unknown): value is string | number | boolean;
2
4
  export declare function clone<T>(value: T): T;
3
5
  /** `items` in consecutive lists of at most `size`, in order: one list where `size` is unbounded. */
4
6
  export declare function chunk<T>(items: readonly T[], size: number): T[][];
@@ -1,3 +1,7 @@
1
+ /** A value a JSON document holds whole, and `$addToSet` and an `=` on a JSON path compare by equality. */
2
+ export function isJsonScalar(value) {
3
+ return typeof value === 'string' || typeof value === 'boolean' || Number.isFinite(value);
4
+ }
1
5
  export function clone(value) {
2
6
  if (typeof value !== 'object' || value === null) {
3
7
  return value;
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.0",
6
+ "version": "0.102.1",
7
7
  "type": "module",
8
8
  "engines": {
9
9
  "node": ">=22.18"
@@ -126,14 +126,14 @@
126
126
  }
127
127
  },
128
128
  "devDependencies": {
129
- "@electric-sql/pglite": "0.5.8",
130
- "@electric-sql/pglite-pgvector": "0.0.9",
129
+ "@electric-sql/pglite": "0.5.9",
130
+ "@electric-sql/pglite-pgvector": "0.0.10",
131
131
  "@libsql/client": "^0.18.0",
132
132
  "@neondatabase/serverless": "^1.2.0",
133
- "@nestjs/common": "^12.1.2",
134
- "@nestjs/core": "^12.1.2",
135
- "@nestjs/testing": "^12.1.2",
136
- "@tursodatabase/database": "^0.8.2",
133
+ "@nestjs/common": "^12.1.3",
134
+ "@nestjs/core": "^12.1.3",
135
+ "@nestjs/testing": "^12.1.3",
136
+ "@tursodatabase/database": "^0.8.3",
137
137
  "@tursodatabase/serverless": "^1.4.1",
138
138
  "@types/better-sqlite3": "^9.6.0",
139
139
  "@types/express": "^5.0.6",