uql-orm 0.102.1 → 0.102.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. package/dist/browser/uql-browser.min.js +2 -2
  2. package/dist/browser/uql-browser.min.js.map +2 -2
  3. package/dist/cockroachdb/cockroachDialect.d.ts +1 -1
  4. package/dist/cockroachdb/cockroachDialect.js +1 -1
  5. package/dist/dialect/abstractSqlDialect.d.ts +14 -13
  6. package/dist/dialect/abstractSqlDialect.js +33 -32
  7. package/dist/dialect/aliases.d.ts +5 -3
  8. package/dist/dialect/aliases.js +7 -3
  9. package/dist/dialect/jsonSql.d.ts +4 -0
  10. package/dist/dialect/jsonSql.js +9 -0
  11. package/dist/dialect/mysqlLikeSqlDialect.d.ts +2 -1
  12. package/dist/dialect/mysqlLikeSqlDialect.js +8 -3
  13. package/dist/dialect/pgLikeSqlDialect.d.ts +4 -3
  14. package/dist/dialect/pgLikeSqlDialect.js +10 -7
  15. package/dist/dialect/queryJoins.d.ts +1 -1
  16. package/dist/mariadb/mariaDialect.d.ts +2 -2
  17. package/dist/mariadb/mariaDialect.js +2 -2
  18. package/dist/mongodb/mongoDialect.d.ts +26 -20
  19. package/dist/mongodb/mongoDialect.js +178 -126
  20. package/dist/mssql/mssqlDialect.d.ts +8 -6
  21. package/dist/mssql/mssqlDialect.js +32 -20
  22. package/dist/sqlite/sqliteDialect.d.ts +1 -1
  23. package/dist/sqlite/sqliteDialect.js +3 -3
  24. package/dist/turso/tursoLocalDialect.d.ts +2 -2
  25. package/dist/turso/tursoLocalDialect.js +7 -5
  26. package/dist/type/entity.d.ts +25 -11
  27. package/dist/type/queryAggregate.d.ts +3 -6
  28. package/dist/type/utility.d.ts +2 -0
  29. package/dist/util/dialect.util.d.ts +13 -13
  30. package/dist/util/dialect.util.js +47 -13
  31. package/dist/util/object.util.d.ts +3 -3
  32. package/dist/util/object.util.js +1 -1
  33. package/package.json +3 -3
  34. package/skills/uql-orm/SKILL.md +1 -1
@@ -1,7 +1,7 @@
1
1
  import { ANSI_SQL_VALUES, fromRows, relationTermKey, isolationSetBefore, } from '../dialect/abstractSqlDialect.js';
2
- import { AGGREGATE_VALUE_ALIAS, JSON_PULL_ALIAS, JSON_SKIP_KEY, OUTPUT_TABLE } from '../dialect/aliases.js';
2
+ import { AGGREGATE_VALUE_ALIAS, JSON_PULL_ALIAS, OUTPUT_TABLE } from '../dialect/aliases.js';
3
3
  import { BYTES_PREFIX } from '../dialect/hydrateColumn.js';
4
- import { jsonArraySlotArgs, jsonPath, jsonSlotArgs, } from '../dialect/jsonSql.js';
4
+ import { skippablePath, jsonArraySlotArgs, jsonPath, jsonSlotArgs, } from '../dialect/jsonSql.js';
5
5
  import { MergeSqlDialect } from '../dialect/mergeSqlDialect.js';
6
6
  import { getMeta } from '../entity/index.js';
7
7
  import { canonicalToSql, resolveColumnCanonicalType } from '../schema/canonicalType.js';
@@ -9,7 +9,7 @@ import { QuerySql } from '../type/index.js';
9
9
  import { parseQueryLock } from '../type/index.js';
10
10
  import { bytesToHex } from '../util/bytes.js';
11
11
  import { isAutoIncrement, isExactDecimal, jsonPathKeys } from '../util/field.util.js';
12
- import { assertNonNegativeInteger } from '../util/index.js';
12
+ import { assertNonNegativeInteger, isOperatorMap } from '../util/index.js';
13
13
  import { escapeSingleQuotes } from '../util/sqlLiteral.js';
14
14
  import { UqlUsageError } from '../util/uqlError.js';
15
15
  /** What SQL Server has. */
@@ -52,12 +52,20 @@ const MSSQL_FEATURES = {
52
52
  },
53
53
  namedLocks: 'transaction',
54
54
  };
55
- /** The `type` `OPENJSON` reports for the JSON scalar an element is compared with; anything else binds as a string. */
55
+ /** The `type` `OPENJSON` reports for each JSON kind. */
56
+ const OPENJSON_TYPE = { null: 0, string: 1, number: 2, boolean: 3, array: 4, object: 5 };
57
+ /** The `type` `OPENJSON` reports for an element of `value`'s JSON type; anything else binds as a string. */
56
58
  function openJsonType(value) {
59
+ if (Array.isArray(value)) {
60
+ return OPENJSON_TYPE.array;
61
+ }
62
+ if (isOperatorMap(value)) {
63
+ return OPENJSON_TYPE.object;
64
+ }
57
65
  if (typeof value === 'number') {
58
- return 2;
66
+ return OPENJSON_TYPE.number;
59
67
  }
60
- return typeof value === 'boolean' ? 3 : 1;
68
+ return typeof value === 'boolean' ? OPENJSON_TYPE.boolean : OPENJSON_TYPE.string;
61
69
  }
62
70
  /** The one key column and its field, or nothing on a composite key. */
63
71
  function soleId(meta) {
@@ -353,9 +361,15 @@ export class MsSqlDialect extends MergeSqlDialect {
353
361
  jsonElemFrom(slot, alias) {
354
362
  return `OPENJSON(${jsonArraySlotArgs(slot, this.jsonIs(slot, 'array'))}) ${alias}`;
355
363
  }
356
- /** `JSON_QUERY` answers an array or an object as written, and a scalar as NULL, so its first character tells which. */
364
+ /**
365
+ * Its first character: the one `JSON_QUERY` answers, NULL for a scalar, or the document's own first past any
366
+ * whitespace, since `JSON_QUERY` refuses a document that is a scalar and copying it costs its length.
367
+ */
357
368
  jsonIs(slot, kind) {
358
- return `LEFT(JSON_QUERY(${jsonSlotArgs(slot)}), 1) = '${kind === 'array' ? '[' : '{'}'`;
369
+ const first = slot.path
370
+ ? `LEFT(JSON_QUERY(${jsonSlotArgs(slot)}), 1)`
371
+ : `SUBSTRING(${slot.base}, PATINDEX(N'%[^ ' + CHAR(9) + CHAR(10) + CHAR(13) + N']%', ${slot.base}), 1)`;
372
+ return `${first} = '${kind === 'array' ? '[' : '{'}'`;
359
373
  }
360
374
  /** `OPENJSON` answers a JSON null as NULL, as it does a key that is not there. */
361
375
  jsonIsNull(slot) {
@@ -373,7 +387,7 @@ export class MsSqlDialect extends MergeSqlDialect {
373
387
  jsonElemEquals(ctx, _slot, alias, value) {
374
388
  const type = `${alias}.${this.#elem.type}`;
375
389
  if (value === null) {
376
- return `${type} = 0`;
390
+ return `${type} = ${OPENJSON_TYPE.null}`;
377
391
  }
378
392
  const elem = this.jsonElemDoc(alias);
379
393
  const param = this.jsonScalarParam(ctx, value);
@@ -404,29 +418,27 @@ export class MsSqlDialect extends MergeSqlDialect {
404
418
  */
405
419
  jsonWriteKeys(expr, writes) {
406
420
  return writes.reduce((acc, [slot, value]) => {
407
- const path = `CASE WHEN ${value} IS NULL THEN ${jsonPath(JSON_SKIP_KEY)} ELSE ${jsonPath(slot.path)} END`;
421
+ const path = skippablePath(jsonPath(slot.path), `${value} IS NULL`);
408
422
  return `JSON_MODIFY(${acc}, ${path}, JSON_QUERY(${value}))`;
409
423
  }, expr);
410
424
  }
411
- jsonAppended(ctx, array, value) {
412
- return `JSON_MODIFY(${array}, 'append $', ${this.jsonWriteParam(ctx, value)})`;
425
+ jsonAppended(ctx, array, value, unless) {
426
+ return `JSON_MODIFY(${array}, ${skippablePath(`'append $'`, unless)}, ${this.jsonWriteParam(ctx, value)})`;
413
427
  }
414
428
  /** Assigning NULL to a path deletes it in lax mode, which is the default. */
415
429
  jsonUnset(_ctx, expr, unset) {
416
430
  return unset.reduce((acc, key) => `JSON_MODIFY(${acc}, ${jsonPath(key)}, NULL)`, expr);
417
431
  }
418
432
  /**
419
- * The surviving elements re-aggregated into an array, there being no remove-by-value. `OPENJSON` hands
420
- * back a string element unquoted and a null one as SQL NULL, so each survivor is re-encoded from its
421
- * reported `type`, and a null is told apart by `IS NULL`, which `<>` cannot do.
433
+ * The surviving elements re-aggregated into an array, there being no remove-by-value. `OPENJSON` hands back a
434
+ * string element unquoted and a null one as SQL NULL, so each survivor is re-encoded from its reported `type`.
422
435
  */
423
- jsonKept(ctx, slot, item) {
436
+ jsonKeptAggregate() {
424
437
  const val = this.jsonElemDoc(JSON_PULL_ALIAS);
425
438
  const encoded = `CASE ${JSON_PULL_ALIAS}.${this.#elem.type}` +
426
- ` WHEN 0 THEN 'null'` +
427
- ` WHEN 1 THEN '"' + STRING_ESCAPE(${val}, 'json') + '"'` +
439
+ ` WHEN ${OPENJSON_TYPE.null} THEN 'null'` +
440
+ ` WHEN ${OPENJSON_TYPE.string} THEN '"' + STRING_ESCAPE(${val}, 'json') + '"'` +
428
441
  ` ELSE ${val} END`;
429
- const differs = item === null ? `${val} IS NOT NULL` : `${val} IS NULL OR ${val} <> ${this.jsonScalarParam(ctx, item)}`;
430
- return `SELECT '[' + STRING_AGG(${encoded}, ',') + ']' FROM ${this.jsonElemFrom(slot, JSON_PULL_ALIAS)} WHERE ${differs}`;
442
+ return `'[' + STRING_AGG(${encoded}, ',') + ']'`;
431
443
  }
432
444
  }
@@ -87,5 +87,5 @@ export declare class SqliteDialect extends AbstractSqlDialect {
87
87
  protected jsonCast(operand: string): string;
88
88
  /** `JSON` keeps each element's JSON type in the array, which answers `[]` for no rows. */
89
89
  protected jsonArrayOf(elem: string): string;
90
- protected jsonAppended(ctx: QueryContext, array: string, value: unknown): string;
90
+ protected jsonAppended(ctx: QueryContext, array: string, value: unknown, unless?: string): string;
91
91
  }
@@ -1,6 +1,6 @@
1
1
  import { ANSI_SQL_VALUES, AbstractSqlDialect, } from '../dialect/abstractSqlDialect.js';
2
2
  import { BYTES_PREFIX } from '../dialect/hydrateColumn.js';
3
- import { chainedCall, groupsPerCall, jsonPath, jsonArraySlotArgs, jsonSlotArgs, } from '../dialect/jsonSql.js';
3
+ import { chainedCall, groupsPerCall, jsonPath, skippablePath, jsonArraySlotArgs, jsonSlotArgs, } from '../dialect/jsonSql.js';
4
4
  import { QuerySql, } from '../type/index.js';
5
5
  import { indexDistance, isVectorIndexType } from '../type/vector.js';
6
6
  import { declaredIndexName } from '../util/ddlExpression.util.js';
@@ -227,7 +227,7 @@ export class SqliteDialect extends AbstractSqlDialect {
227
227
  jsonArrayOf(elem) {
228
228
  return `JSON_GROUP_ARRAY(JSON(${elem}))`;
229
229
  }
230
- jsonAppended(ctx, array, value) {
231
- return `JSON_INSERT(${array}, '$[#]', ${this.jsonScalarParam(ctx, value)})`;
230
+ jsonAppended(ctx, array, value, unless) {
231
+ return `JSON_INSERT(${array}, ${skippablePath(`'$[#]'`, unless)}, ${this.jsonScalarParam(ctx, value)})`;
232
232
  }
233
233
  }
@@ -7,6 +7,6 @@ import { TursoDialect } from './tursoDialect.js';
7
7
  export declare class TursoLocalDialect extends TursoDialect {
8
8
  readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorMetric>;
9
9
  readonly maxFunctionArgs: number;
10
- /** The engine appends nothing for a JSON null at a bare array's `[#]`, and does under a key, so a null goes under one. */
11
- protected jsonAppended(ctx: QueryContext, array: string, value: unknown): string;
10
+ /** At a bare array's `[#]` the engine appends nothing for `true`, `false` or `null`, so those go under a key. */
11
+ protected jsonAppended(ctx: QueryContext, array: string, value: unknown, unless?: string): string;
12
12
  }
@@ -1,3 +1,4 @@
1
+ import { skippablePath } from '../dialect/jsonSql.js';
1
2
  import { TursoDialect } from './tursoDialect.js';
2
3
  /**
3
4
  * SQLite Dialect specialization for the embedded Turso engine, the Rust engine alone: it adds a
@@ -10,11 +11,12 @@ export class TursoLocalDialect extends TursoDialect {
10
11
  ['inner', { fn: 'vector_distance_dot' }],
11
12
  ]);
12
13
  maxFunctionArgs = Infinity;
13
- /** The engine appends nothing for a JSON null at a bare array's `[#]`, and does under a key, so a null goes under one. */
14
- jsonAppended(ctx, array, value) {
15
- if (value !== null) {
16
- return super.jsonAppended(ctx, array, value);
14
+ /** At a bare array's `[#]` the engine appends nothing for `true`, `false` or `null`, so those go under a key. */
15
+ jsonAppended(ctx, array, value, unless) {
16
+ if (typeof value !== 'boolean' && value !== null) {
17
+ return super.jsonAppended(ctx, array, value, unless);
17
18
  }
18
- return `JSON_SET(JSON_OBJECT('a', ${array}), '$.a[#]', ${this.jsonScalarParam(ctx, value)}) -> '$.a'`;
19
+ const path = skippablePath(`'$.a[#]'`, unless);
20
+ return `JSON_SET(JSON_OBJECT('a', JSON(${array})), ${path}, ${this.jsonScalarParam(ctx, value)}) -> '$.a'`;
19
21
  }
20
22
  }
@@ -3,7 +3,7 @@ import type { SqlDialectName } from './dialect.js';
3
3
  import type { FilterOptions, RelationQuery } from './query.js';
4
4
  import type { ColumnRef, QuerySql, SqlFor, RelationAggregate } from './querySql.js';
5
5
  import type { QueryWhere } from './queryWhere.js';
6
- import type { AtLeastOne, Except, ExactlyOne, IsEqual, IsJson, JsonBrand, IsMany, Json, Scalar, Type, Unpacked, Writable } from './utility.js';
6
+ import type { AtLeastOne, Except, ExactlyOne, IsEqual, IsJson, JsonBrand, IsMany, Json, JsonScalar, Scalar, Type, Unpacked, Writable } from './utility.js';
7
7
  import type { VectorDistance, VectorIndexOptions, VectorIndexType } from './vector.js';
8
8
  /** Brands the property an entity is identified by, where it is not `id`, `_id` or `uuid`. */
9
9
  export declare const idKey: unique symbol;
@@ -119,12 +119,13 @@ export type JsonFieldPaths<E> = {
119
119
  type PathValue<T, P extends string> = unknown extends T ? unknown : NonNullable<T> extends readonly (infer U)[] ? PathValue<NonNullable<U>, P> : P extends `${infer K}.${infer Rest}` ? K extends keyof NonNullable<T> ? PathValue<NonNullable<T>[K], Rest> : unknown : P extends keyof NonNullable<T> ? NonNullable<T>[P] : unknown;
120
120
  /** The value at a JSON dot-path of `E`, `unknown` where it cannot be resolved, which keeps an untyped path permissive. */
121
121
  export type JsonFieldPathValue<E, P extends string> = P extends `${infer F}.${infer Rest}` ? F extends JsonFieldKey<E> ? PathValue<JsonPayload<E[F]>, Rest> : unknown : unknown;
122
- /**
123
- * The keys of `T` holding an array of `Element`, each mapped to its element type: what `$push` and `$pull`
124
- * address, and with scalar elements, `$addToSet`.
125
- */
126
- export type JsonArrayFields<T, Element = unknown> = {
127
- [K in keyof T as IsMany<T[K]> extends true ? Unpacked<NonNullable<T[K]>> extends Element ? K & string : never : never]?: Unpacked<NonNullable<T[K]>>;
122
+ /** The keys of `T` holding an array, each mapped to its element type: what `$push` and `$pull` address. */
123
+ export type JsonArrayFields<T> = {
124
+ [K in keyof T as IsMany<T[K]> extends true ? K & string : never]?: Unpacked<NonNullable<T[K]>>;
125
+ };
126
+ /** The keys of `T` holding an array with an element `$addToSet` takes, each mapped to that element. */
127
+ type JsonSetFields<T> = {
128
+ [K in keyof T as IsMany<T[K]> extends true ? [JsonSetElement<Unpacked<NonNullable<T[K]>>>] extends [never] ? never : K & string : never]?: JsonSetElement<Unpacked<NonNullable<T[K]>>>;
128
129
  };
129
130
  /**
130
131
  * A JSON field's update operators, applied in order on every engine, `$pull`, `$set`, `$push`, `$addToSet`,
@@ -138,13 +139,26 @@ export type JsonUpdateOp<T = unknown> = {
138
139
  readonly $unset?: unknown extends T ? readonly string[] : readonly ((keyof T & string) | JsonNestedPaths<T>)[];
139
140
  readonly $push?: JsonArrayFields<T>;
140
141
  readonly $pull?: JsonArrayFields<T>;
141
- readonly $addToSet?: JsonArrayFields<T, string | number | boolean>;
142
+ readonly $addToSet?: JsonSetFields<T>;
143
+ };
144
+ /**
145
+ * A JSON array column's update operators, each taking a list of elements, applied in order on every engine:
146
+ * `$pull` each, `$push` each, then `$addToSet` each the array lacks. A NULL column counts as an empty array,
147
+ * and a stored value that is no array stays as it is.
148
+ * @example `{ tags: { $pull: ['stale'], $addToSet: ['new'] } }`
149
+ */
150
+ export type JsonArrayUpdateOp<T = unknown> = {
151
+ readonly $pull?: readonly T[];
152
+ readonly $push?: readonly T[];
153
+ readonly $addToSet?: readonly JsonSetElement<T>[];
142
154
  };
155
+ /** What `$addToSet` takes from an array of `T`: its scalars, any scalar where `T` is untyped. */
156
+ type JsonSetElement<T> = unknown extends T ? JsonScalar : Extract<T, JsonScalar>;
143
157
  /**
144
- * The {@link JsonUpdateOp} a field takes: `never` on a non-JSON field, and on a JSON array, whose
145
- * operators would address keys it does not have (engines disagree on what that does).
158
+ * The update operators a field takes: {@link JsonArrayUpdateOp} on a JSON array, `Json<T[]>` or `Json<T>[]`,
159
+ * {@link JsonUpdateOp} on any other JSON field, and `never` on a field that is no JSON.
146
160
  */
147
- type JsonUpdateOpFor<V, T = UnwrapJson<NonNullable<V>>> = [T] extends [never] ? never : IsMany<T> extends true ? never : JsonUpdateOp<T>;
161
+ type JsonUpdateOpFor<V, T = UnwrapJson<NonNullable<V>>> = [T] extends [never] ? IsJsonColumn<V> extends true ? JsonArrayUpdateOp<JsonPayload<V>> : never : IsMany<T> extends true ? JsonArrayUpdateOp<Unpacked<T>> : JsonUpdateOp<T>;
148
162
  /**
149
163
  * A scalar field's update operator, as {@link JsonUpdateOp} is a JSON field's, computed in the statement:
150
164
  * `$inc` adds, `$mul` multiplies, a NULL counting as 0 on every engine. One per field, since their order
@@ -1,6 +1,5 @@
1
1
  import type { FieldKey, FieldKeyOf, RelationKey, RelationTarget } from './entity.js';
2
2
  import type { QueryPager, QuerySelect, QuerySortDirection } from './query.js';
3
- import type { QuerySql } from './querySql.js';
4
3
  import type { QueryWhere, QueryWhereFieldValue } from './queryWhere.js';
5
4
  import type { ExactlyOne, IsMany, RejectKeys } from './utility.js';
6
5
  /** The columns `$group` names by a literal `true`, so an uninferred `$group`, its own constraint, names none. */
@@ -67,18 +66,16 @@ type QueryAggregateArgMap<E> = Record<'$count', QueryAggregateArg<E>> & Record<T
67
66
  /**
68
67
  * An aggregate over one field, exactly one op per entry: `{ $sum: { amount: true } }` is `SUM("amount")`,
69
68
  * `{ $countDistinct: { id: true } }` is `COUNT(DISTINCT "id")`, and only `$count` takes `'*'`. Its own
70
- * `$where` narrows the rows it reads to those matching, over the entity's own fields.
69
+ * `$where` narrows the rows it reads to those matching, as a query's `$where` does.
71
70
  */
72
71
  export type QueryAggregateFn<E> = ExactlyOne<QueryAggregateArgMap<E>> & {
73
- readonly $where?: QueryAggregateWhere<E>;
72
+ readonly $where?: QueryWhere<E>;
74
73
  };
75
- /** What an aggregate's own `$where` reads: the entity's fields, since a relation there is a subquery inside it. */
76
- type QueryAggregateWhere<E> = QueryWhere<E, QuerySql, FieldKey<E>>;
77
74
  /** An aggregate's `$where` naming a key it does not have, refused: a captured `$select` skips the excess-property check. */
78
75
  type AggregateWhereKeys<E, Fn> = Fn extends {
79
76
  readonly $where: infer W;
80
77
  } ? {
81
- readonly $where: RejectKeys<Exclude<keyof W, keyof QueryAggregateWhere<E>>>;
78
+ readonly $where: RejectKeys<Exclude<keyof W, keyof QueryWhere<E>>>;
82
79
  } : unknown;
83
80
  /** A single-key `{ [op]: Arg }` shape for each op in `Ops`, matched to infer that op's result or its argument. */
84
81
  type FnWithOp<Ops extends string, Arg = unknown> = {
@@ -8,6 +8,8 @@ export type MongoId = {
8
8
  * collapse to `any` without it, switching every key check off.
9
9
  */
10
10
  export type Scalar = string | number | boolean | bigint | Date | RegExp | Uint8Array | MongoId;
11
+ /** A value a JSON document holds whole and every engine compares by equality, as `$addToSet` needs. */
12
+ export type JsonScalar = string | number | boolean;
11
13
  /**
12
14
  * Scalar types with a meaningful ordering, accepted by `$lt`/`$lte`/`$gt`/`$gte`/`$between`.
13
15
  */
@@ -1,5 +1,5 @@
1
1
  import type { IndexType } from '../schema/types.js';
2
- import { type AggregateCall, type CascadeType, type EntityData, type EntityIndexMeta, type EntityMeta, type FieldKey, type FieldOptions, type FieldUpdateOp, type JsonUpdateOp, type OnFieldCallback, type QueryAggMap, type QueryExclude, type QueryGroupMap, type QueryOptions, QuerySql, type QuerySearch, type QuerySelect, type QuerySelectValue, type QuerySortDirection, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryVectorQuery, type QueryVectorSearch, type QueryWhere, type RelationKey, type UpdatePayload, type VectorDistance } from '../type/index.js';
2
+ import { type AggregateCall, type CascadeType, type EntityData, type EntityIndexMeta, type EntityMeta, type FieldKey, type FieldOptions, type FieldUpdateOp, type JsonArrayUpdateOp, type JsonUpdateOp, type OnFieldCallback, type QueryAggMap, type QueryExclude, type QueryGroupMap, type QueryOptions, QuerySql, type QuerySearch, type QuerySelect, type QuerySelectValue, type QuerySortDirection, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryVectorQuery, type QueryVectorSearch, type QueryWhere, type RelationKey, type UpdatePayload, type VectorDistance } from '../type/index.js';
3
3
  export type CallbackKey = keyof Pick<FieldOptions, 'onInsert' | 'onUpdate'>;
4
4
  /** The keys of `payload` a write persists as columns. */
5
5
  export declare function filterFieldKeys<E>(meta: EntityMeta<E>, payload: EntityData<E> | UpdatePayload<E>, callbackKey: CallbackKey): FieldKey<E>[];
@@ -66,17 +66,15 @@ export declare function vectorDistanceOf<E>(meta: EntityMeta<E>, key: string, se
66
66
  */
67
67
  export declare function hasVectorNear(where: unknown): boolean;
68
68
  /** Type guard: checks whether an update payload value is a JSON operator object. */
69
- export declare function isJsonUpdateOp(value: unknown): value is JsonUpdateOp;
70
- /** An item one array key's writes append, `unique` where it goes in only if the stored array lacks it. */
69
+ export declare function isJsonUpdateOp(value: unknown): value is JsonUpdateOp | JsonArrayUpdateOp;
70
+ /** An item one array's writes append, `unique` where it goes in only if the stored array lacks it. */
71
71
  type JsonAppend = {
72
72
  readonly item: unknown;
73
73
  readonly unique: boolean;
74
74
  };
75
- /** One array key's writes, in order: `pull` removes every element equal to its item, then each append adds one. */
75
+ /** One array's writes, in order: each pull removes every element equal to it, then each append adds one. */
76
76
  export type JsonArrayWrites = {
77
- readonly pull?: {
78
- readonly item: unknown;
79
- };
77
+ readonly pulls: readonly unknown[];
80
78
  readonly appends: readonly JsonAppend[];
81
79
  };
82
80
  /** A JSON update with each path written once: the value set at each, each array key's writes, and the paths removed. */
@@ -87,12 +85,14 @@ export type JsonWrites = {
87
85
  };
88
86
  /** Whether the writes put a key into the document, so a NULL column must first become an object. */
89
87
  export declare function writesKeys({ set, arrays }: JsonWrites): boolean;
90
- /**
91
- * A JSON update as one write per path, its operators applied in order: `$pull`, `$set` in key order, `$push`,
92
- * `$addToSet`, `$unset`. Where one reaches a value another wrote, the result is worked out here, so every engine
93
- * writes each path once and reads only what is stored. A `$set` of `undefined` writes nothing.
94
- */
95
- export declare function foldJsonUpdate(value: JsonUpdateOp): JsonWrites;
88
+ /** A JSON update as its writes: those of an array column, or those of an object's keys. */
89
+ export type JsonUpdate = {
90
+ readonly array: JsonArrayWrites;
91
+ } | {
92
+ readonly object: JsonWrites;
93
+ };
94
+ /** A JSON update folded as an array column's, where its operands are lists of elements, else as an object's. */
95
+ export declare function foldJson(value: JsonUpdateOp | JsonArrayUpdateOp): JsonUpdate;
96
96
  /** Type guard: checks whether an update payload value is a scalar field's operator. */
97
97
  export declare function isFieldUpdateOp(value: unknown): value is FieldUpdateOp;
98
98
  /**
@@ -222,17 +222,43 @@ export function isJsonUpdateOp(value) {
222
222
  export function writesKeys({ set, arrays }) {
223
223
  return hasKeys(set) || Object.values(arrays).some((write) => write.appends.length > 0);
224
224
  }
225
+ /** A JSON update folded as an array column's, where its operands are lists of elements, else as an object's. */
226
+ export function foldJson(value) {
227
+ return isJsonArrayUpdate(value) ? { array: foldJsonArrayUpdate(value) } : { object: foldJsonUpdate(value) };
228
+ }
229
+ /** Whether a JSON update writes the column as an array, its operands lists of elements rather than maps of keys. */
230
+ function isJsonArrayUpdate(value) {
231
+ return [value.$pull, value.$push, value.$addToSet].some(Array.isArray);
232
+ }
233
+ /**
234
+ * A JSON array column's update as its writes: each `$pull`, then each `$push`, then each `$addToSet` once. Its
235
+ * operands are lists, so one that is a map of keys means the update was written for an object.
236
+ */
237
+ function foldJsonArrayUpdate(value) {
238
+ const { $pull = [], $push = [], $addToSet = [], ...others } = value;
239
+ if (hasKeys(others) || ![$pull, $push, $addToSet].every(Array.isArray)) {
240
+ throw new UqlUsageError('a JSON array takes $pull, $push and $addToSet, each a list of elements');
241
+ }
242
+ const write = { pulls: [...$pull], appends: [] };
243
+ for (const item of $push) {
244
+ append(write, item, false);
245
+ }
246
+ for (const item of $addToSet) {
247
+ append(write, assertSetElement('$addToSet', item), true);
248
+ }
249
+ return write;
250
+ }
225
251
  /**
226
252
  * A JSON update as one write per path, its operators applied in order: `$pull`, `$set` in key order, `$push`,
227
253
  * `$addToSet`, `$unset`. Where one reaches a value another wrote, the result is worked out here, so every engine
228
254
  * writes each path once and reads only what is stored. A `$set` of `undefined` writes nothing.
229
255
  */
230
- export function foldJsonUpdate(value) {
256
+ function foldJsonUpdate(value) {
231
257
  const set = new Map();
232
258
  const arrays = new Map();
233
259
  const unset = new Set();
234
260
  for (const [key, item] of Object.entries(value.$pull ?? {})) {
235
- arrays.set(jsonKey(key), { pull: { item }, appends: [] });
261
+ arrays.set(jsonKey(key), { pulls: [item], appends: [] });
236
262
  }
237
263
  for (const [path, item] of Object.entries(value.$set ?? {})) {
238
264
  if (item !== undefined) {
@@ -248,14 +274,11 @@ export function foldJsonUpdate(value) {
248
274
  }
249
275
  }
250
276
  }
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
- }
277
+ for (const [key, item] of Object.entries(value.$push ?? {})) {
278
+ appendTo(set, arrays, jsonKey(key), item, false);
279
+ }
280
+ for (const [key, item] of Object.entries(value.$addToSet ?? {})) {
281
+ appendTo(set, arrays, jsonKey(key), assertSetElement(`$addToSet on '${key}'`, item), true);
259
282
  }
260
283
  for (const path of value.$unset ?? []) {
261
284
  const keys = jsonPathKeys(path);
@@ -287,11 +310,22 @@ function appendTo(set, arrays, key, item, unique) {
287
310
  if ([...set.keys()].some((path) => path.startsWith(`${key}.`))) {
288
311
  return;
289
312
  }
290
- const write = arrays.get(key) ?? { appends: [] };
313
+ const write = arrays.get(key) ?? { pulls: [], appends: [] };
291
314
  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 });
315
+ append(write, item, unique);
316
+ }
317
+ /** `item` appended to `write`: a `unique` one only once, and unguarded where a pull removed it. */
318
+ function append(write, item, unique) {
319
+ if (!(unique && write.appends.some((appended) => appended.item === item))) {
320
+ write.appends.push({ item, unique: unique && !write.pulls.includes(item) });
321
+ }
322
+ }
323
+ /** `item`, refused unless a scalar: the one element every engine compares alike, which `$addToSet` needs. */
324
+ function assertSetElement(operator, item) {
325
+ if (!isJsonScalar(item)) {
326
+ throw new UqlUsageError(`${operator} takes a string, a finite number or a boolean`);
294
327
  }
328
+ return item;
295
329
  }
296
330
  /** Removes `path` and every path inside it from `set`. */
297
331
  function dropWithin(set, path) {
@@ -1,6 +1,6 @@
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;
1
+ import type { EntityMeta, JsonScalar } from '../type/index.js';
2
+ /** Whether `value` is a {@link JsonScalar}, which `$addToSet` and an `=` on a JSON path compare by equality. */
3
+ export declare function isJsonScalar(value: unknown): value is JsonScalar;
4
4
  export declare function clone<T>(value: T): T;
5
5
  /** `items` in consecutive lists of at most `size`, in order: one list where `size` is unbounded. */
6
6
  export declare function chunk<T>(items: readonly T[], size: number): T[][];
@@ -1,4 +1,4 @@
1
- /** A value a JSON document holds whole, and `$addToSet` and an `=` on a JSON path compare by equality. */
1
+ /** Whether `value` is a {@link JsonScalar}, which `$addToSet` and an `=` on a JSON path compare by equality. */
2
2
  export function isJsonScalar(value) {
3
3
  return typeof value === 'string' || typeof value === 'boolean' || Number.isFinite(value);
4
4
  }
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.1",
6
+ "version": "0.102.3",
7
7
  "type": "module",
8
8
  "engines": {
9
9
  "node": ">=22.18"
@@ -144,8 +144,8 @@
144
144
  "express": "^5.3.0",
145
145
  "mariadb": "^3.5.4",
146
146
  "mongodb": "^7.7.0",
147
- "mssql": "^12.7.4",
148
- "mysql2": "^3.24.5",
147
+ "mssql": "^12.7.5",
148
+ "mysql2": "^3.24.6",
149
149
  "pg": "^8.23.1",
150
150
  "pg-query-stream": "^4.17.1",
151
151
  "rxjs": "^7.8.2",
@@ -118,7 +118,7 @@ const users = await pool.findMany(User, {
118
118
  - `upsertOne(Entity, { email: true }, row, update?)`: a conflicting row takes `update`, an update's payload with its operators (`{ uses: { $inc: 1 } }`), instead of `row`; a new one inserts `row`. An empty `{}` leaves a conflicting row as it is: insert if absent. Cascaded relations write on either branch, a found row's replaced, as `updateMany` does. It resolves to the row's id.
119
119
  - Every write takes `{ returning: { id: true, createdAt: true } }` as its last argument and then resolves to those rows (an update or delete by id: the row or `undefined`), read back in the same transaction; without it, inserts, saves and upserts resolve to ids, updates and deletes to a count. An update or delete writes exactly the rows it reports: on Postgres, CockroachDB and the SQLite family a plain one is a single statement whose `RETURNING` reports them; elsewhere, or paged, through a relation, versioned, or with hooks or cascades on a delete, it reads them first in a transaction that holds them, so a racing writer waits for the commit (SQLite and MongoDB fail it with a retryable error instead).
120
120
  - `updateMany` and `deleteMany` naming no rows - no `$where` holding a value (an empty group holds none), no `$limit` - throw; `{ unfiltered: true }` means the whole table.
121
- - An update takes `{ stock: { $inc: -1 } }` to add, or `$mul` to multiply, in the statement, a NULL counting as 0, so a guard in `$where` (`stock: { $gte: 1 }`) makes a decrement race-safe. On SQL the step may be a ref or `sql` of the field's type (`{ total: { $inc: newRow.amount } }` in a trigger). JSON fields take `$set` and `$unset`, of keys or dotted paths (`settings: { $set: { 'billing.plan': 'pro' } }`, creating the parents), `$push`, `$pull`, and `$addToSet` (a scalar the array lacks), applied in that order on one value: `$pull`, `$set`, `$push`, `$addToSet`, `$unset`.
121
+ - An update takes `{ stock: { $inc: -1 } }` to add, or `$mul` to multiply, in the statement, a NULL counting as 0, so a guard in `$where` (`stock: { $gte: 1 }`) makes a decrement race-safe. On SQL the step may be a ref or `sql` of the field's type (`{ total: { $inc: newRow.amount } }` in a trigger). JSON fields take `$set` and `$unset`, of keys or dotted paths (`settings: { $set: { 'billing.plan': 'pro' } }`, creating the parents), `$push`, `$pull`, and `$addToSet` (a scalar the array lacks), applied in that order on one value: `$pull`, `$set`, `$push`, `$addToSet`, `$unset`. A JSON array column (`tags?: Json<string[]>`) takes `$pull`, `$push` and `$addToSet` with lists of elements: `{ tags: { $pull: ['old'], $addToSet: ['new'] } }`.
122
122
  - `$lock: true` locks the rows a read returns (`{ $wait: 'skip' | 'nowait' }` says what to do about a row someone else holds) and needs an open transaction; SQLite, libSQL, Turso, D1 and MongoDB have no row lock and refuse it.
123
123
  - `queryErrorKind(err)` names any failure the same on every engine - `uniqueViolation`, `foreignKeyViolation`, `notNullViolation`, `checkViolation`, `optimisticLock`, `retryable`, `usage`, `security` - so catch by kind rather than by a driver's code or an `instanceof`. Every error UQL raises itself is a `UqlError`.
124
124
  - ``pool.all`SELECT ... WHERE id = ${id}` `` runs a `SELECT` and ``pool.run`...` `` a write, one statement per call: both are tags, each interpolated value bound: a scalar, `null` or a list of them, never `undefined` or a plain object (bind `JSON.stringify(doc)`). `sql` builds a fragment to embed anywhere a value or field goes, or to compose a statement, and `sql.join(fragments, ' AND ')` joins them. `sql.text(sql)` runs trusted SQL held in a string, binding nothing: never build it from user input. Migrations write ``querier.run /*sql*/ `CREATE TABLE ...` ``, the comment being what es6-string-html highlights as SQL. `sql` is a tag, so ``sql(`...`)`` does not compile. `raw` is its deprecated former name. A field read off `refs(Entity)` carries its type: on its own as a value it fits only a field of that type.