uql-orm 0.102.0 → 0.102.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) 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 +49 -27
  5. package/dist/dialect/abstractSqlDialect.js +83 -42
  6. package/dist/dialect/aliases.d.ts +10 -0
  7. package/dist/dialect/aliases.js +26 -16
  8. package/dist/dialect/jsonSql.d.ts +14 -7
  9. package/dist/dialect/jsonSql.js +16 -10
  10. package/dist/dialect/mysqlLikeSqlDialect.d.ts +5 -8
  11. package/dist/dialect/mysqlLikeSqlDialect.js +14 -12
  12. package/dist/dialect/pgLikeSqlDialect.d.ts +21 -13
  13. package/dist/dialect/pgLikeSqlDialect.js +41 -30
  14. package/dist/dialect/queryJoins.d.ts +1 -1
  15. package/dist/mariadb/mariaDialect.d.ts +2 -2
  16. package/dist/mariadb/mariaDialect.js +2 -2
  17. package/dist/mongodb/mongoDialect.d.ts +10 -13
  18. package/dist/mongodb/mongoDialect.js +139 -96
  19. package/dist/mssql/mssqlDialect.d.ts +22 -10
  20. package/dist/mssql/mssqlDialect.js +54 -35
  21. package/dist/mysql/mysqlDialect.js +1 -1
  22. package/dist/querier/abstractQuerier.js +1 -2
  23. package/dist/querier/cursorStream.js +1 -2
  24. package/dist/sqlite/localSqliteQuerierPool.js +8 -2
  25. package/dist/sqlite/sqliteDialect.d.ts +4 -4
  26. package/dist/sqlite/sqliteDialect.js +10 -8
  27. package/dist/turso/tursoLocalDialect.d.ts +3 -1
  28. package/dist/turso/tursoLocalDialect.js +9 -0
  29. package/dist/type/entity.d.ts +34 -12
  30. package/dist/type/utility.d.ts +2 -0
  31. package/dist/util/dialect.util.d.ts +29 -2
  32. package/dist/util/dialect.util.js +154 -4
  33. package/dist/util/field.util.d.ts +2 -0
  34. package/dist/util/field.util.js +5 -0
  35. package/dist/util/object.util.d.ts +3 -1
  36. package/dist/util/object.util.js +4 -0
  37. package/package.json +7 -7
  38. package/skills/uql-orm/SKILL.md +3 -3
@@ -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, 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, jsonSetCall, 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';
@@ -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, unless) {
231
+ return `JSON_INSERT(${array}, ${skippablePath(`'$[#]'`, unless)}, ${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
+ /** 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;
10
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,4 +11,12 @@ export class TursoLocalDialect extends TursoDialect {
10
11
  ['inner', { fn: 'vector_distance_dot' }],
11
12
  ]);
12
13
  maxFunctionArgs = Infinity;
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);
18
+ }
19
+ const path = skippablePath(`'$.a[#]'`, unless);
20
+ return `JSON_SET(JSON_OBJECT('a', JSON(${array})), ${path}, ${this.jsonScalarParam(ctx, value)}) -> '$.a'`;
21
+ }
13
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;
@@ -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,26 +119,46 @@ 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. */
122
+ /** The keys of `T` holding an array, each mapped to its element type: what `$push` and `$pull` address. */
121
123
  export type JsonArrayFields<T> = {
122
124
  [K in keyof T as IsMany<T[K]> extends true ? K & string : never]?: Unpacked<NonNullable<T[K]>>;
123
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]>>>;
129
+ };
124
130
  /**
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.
131
+ * A JSON field's update operators, applied in order on every engine, `$pull`, `$set`, `$push`, `$addToSet`,
132
+ * `$unset`, each seeing what the one before wrote; see the JSON guide.
127
133
  * @example `{ kind: { $set: { public: 1 }, $push: { tags: 'x' }, $unset: ['private'] } }`
128
134
  */
129
135
  export type JsonUpdateOp<T = unknown> = {
130
- readonly $set?: Partial<T>;
131
- readonly $unset?: unknown extends T ? readonly string[] : readonly (keyof T & string)[];
136
+ readonly $set?: Partial<T> & {
137
+ readonly [P in JsonNestedPaths<T>]?: PathValue<T, P>;
138
+ };
139
+ readonly $unset?: unknown extends T ? readonly string[] : readonly ((keyof T & string) | JsonNestedPaths<T>)[];
132
140
  readonly $push?: JsonArrayFields<T>;
133
141
  readonly $pull?: JsonArrayFields<T>;
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>[];
134
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>;
135
157
  /**
136
- * The {@link JsonUpdateOp} a field takes: `never` on a non-JSON field, and on a JSON array, whose
137
- * 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.
138
160
  */
139
- 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>;
140
162
  /**
141
163
  * A scalar field's update operator, as {@link JsonUpdateOp} is a JSON field's, computed in the statement:
142
164
  * `$inc` adds, `$mul` multiplies, a NULL counting as 0 on every engine. One per field, since their order
@@ -8,6 +8,8 @@ export type MongoId = {
8
8
  * collapse to `any` without it, switching every key check off.
9
9
  */
10
10
  export type Scalar = string | number | boolean | bigint | Date | RegExp | Uint8Array | MongoId;
11
+ /** A value a JSON document holds whole and every engine compares by equality, as `$addToSet` needs. */
12
+ export type JsonScalar = string | number | boolean;
11
13
  /**
12
14
  * Scalar types with a meaningful ordering, accepted by `$lt`/`$lte`/`$gt`/`$gte`/`$between`.
13
15
  */
@@ -1,5 +1,5 @@
1
1
  import type { IndexType } from '../schema/types.js';
2
- import { type AggregateCall, type CascadeType, type EntityData, type EntityIndexMeta, type EntityMeta, type FieldKey, type FieldOptions, type FieldUpdateOp, type JsonUpdateOp, type OnFieldCallback, type QueryAggMap, type QueryExclude, type QueryGroupMap, type QueryOptions, QuerySql, type QuerySearch, type QuerySelect, type QuerySelectValue, type QuerySortDirection, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryVectorQuery, type QueryVectorSearch, type QueryWhere, type RelationKey, type UpdatePayload, type VectorDistance } from '../type/index.js';
2
+ import { type AggregateCall, type CascadeType, type EntityData, type EntityIndexMeta, type EntityMeta, type FieldKey, type FieldOptions, type FieldUpdateOp, type JsonArrayUpdateOp, type JsonUpdateOp, type OnFieldCallback, type QueryAggMap, type QueryExclude, type QueryGroupMap, type QueryOptions, QuerySql, type QuerySearch, type QuerySelect, type QuerySelectValue, type QuerySortDirection, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryVectorQuery, type QueryVectorSearch, type QueryWhere, type RelationKey, type UpdatePayload, type VectorDistance } from '../type/index.js';
3
3
  export type CallbackKey = keyof Pick<FieldOptions, 'onInsert' | 'onUpdate'>;
4
4
  /** The keys of `payload` a write persists as columns. */
5
5
  export declare function filterFieldKeys<E>(meta: EntityMeta<E>, payload: EntityData<E> | UpdatePayload<E>, callbackKey: CallbackKey): FieldKey<E>[];
@@ -66,7 +66,33 @@ 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;
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
+ type JsonAppend = {
72
+ readonly item: unknown;
73
+ readonly unique: boolean;
74
+ };
75
+ /** One array's writes, in order: each pull removes every element equal to it, then each append adds one. */
76
+ export type JsonArrayWrites = {
77
+ readonly pulls: readonly unknown[];
78
+ readonly appends: readonly JsonAppend[];
79
+ };
80
+ /** A JSON update with each path written once: the value set at each, each array key's writes, and the paths removed. */
81
+ export type JsonWrites = {
82
+ readonly set: Readonly<Record<string, unknown>>;
83
+ readonly arrays: Readonly<Record<string, JsonArrayWrites>>;
84
+ readonly unset: readonly string[];
85
+ };
86
+ /** Whether the writes put a key into the document, so a NULL column must first become an object. */
87
+ export declare function writesKeys({ set, arrays }: JsonWrites): boolean;
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;
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,165 @@ 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
+ /** 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
+ }
251
+ /**
252
+ * A JSON update as one write per path, its operators applied in order: `$pull`, `$set` in key order, `$push`,
253
+ * `$addToSet`, `$unset`. Where one reaches a value another wrote, the result is worked out here, so every engine
254
+ * writes each path once and reads only what is stored. A `$set` of `undefined` writes nothing.
255
+ */
256
+ function foldJsonUpdate(value) {
257
+ const set = new Map();
258
+ const arrays = new Map();
259
+ const unset = new Set();
260
+ for (const [key, item] of Object.entries(value.$pull ?? {})) {
261
+ arrays.set(jsonKey(key), { pulls: [item], appends: [] });
262
+ }
263
+ for (const [path, item] of Object.entries(value.$set ?? {})) {
264
+ if (item !== undefined) {
265
+ const keys = jsonPathKeys(path);
266
+ arrays.delete(keys[0]);
267
+ dropWithin(set, path);
268
+ const owner = ownerOf(set, keys);
269
+ if (owner) {
270
+ set.set(owner.path, withPath(owner.path, set.get(owner.path), owner.rest, item));
271
+ }
272
+ else {
273
+ set.set(path, item);
274
+ }
275
+ }
276
+ }
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);
282
+ }
283
+ for (const path of value.$unset ?? []) {
284
+ const keys = jsonPathKeys(path);
285
+ dropWithin(set, path);
286
+ arrays.delete(path);
287
+ const owner = ownerOf(set, keys);
288
+ if (owner) {
289
+ set.set(owner.path, withoutPath(owner.path, set.get(owner.path), owner.rest));
290
+ }
291
+ else {
292
+ unset.add(path);
293
+ }
294
+ }
295
+ return { set: Object.fromEntries(set), arrays: Object.fromEntries(arrays), unset: [...unset] };
296
+ }
297
+ /** `item` appended at `key`: onto the array a `$set` wrote there, or else among the key's array writes. */
298
+ function appendTo(set, arrays, key, item, unique) {
299
+ if (set.has(key)) {
300
+ const written = set.get(key);
301
+ assertNotSql(key, written);
302
+ if (written === null) {
303
+ set.set(key, [item]);
304
+ }
305
+ else if (Array.isArray(written) && !(unique && written.includes(item))) {
306
+ set.set(key, [...written, item]);
307
+ }
308
+ return;
309
+ }
310
+ if ([...set.keys()].some((path) => path.startsWith(`${key}.`))) {
311
+ return;
312
+ }
313
+ const write = arrays.get(key) ?? { pulls: [], appends: [] };
314
+ arrays.set(key, write);
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`);
327
+ }
328
+ return item;
329
+ }
330
+ /** Removes `path` and every path inside it from `set`. */
331
+ function dropWithin(set, path) {
332
+ for (const written of set.keys()) {
333
+ if (written === path || written.startsWith(`${path}.`)) {
334
+ set.delete(written);
335
+ }
336
+ }
337
+ }
338
+ /** The path in `set` holding the value `keys` lead into, and the keys left below it. */
339
+ function ownerOf(set, keys) {
340
+ for (let depth = 1; depth < keys.length; depth++) {
341
+ const path = keys.slice(0, depth).join('.');
342
+ if (set.has(path)) {
343
+ return { path, rest: keys.slice(depth) };
344
+ }
345
+ }
346
+ return undefined;
347
+ }
348
+ /** `value` with `item` at `keys`, a value that is no object becoming one, as a dotted `$set` makes it. */
349
+ function withPath(path, value, [key, ...rest], item) {
350
+ assertNotSql(path, value);
351
+ const object = isRecord(value) ? value : {};
352
+ const inner = Object.hasOwn(object, key) ? object[key] : undefined;
353
+ return { ...object, [key]: rest.length > 0 ? withPath(path, inner, rest, item) : item };
354
+ }
355
+ /** `value` without `keys`, as it is where they lead nowhere. */
356
+ function withoutPath(path, value, [key, ...rest]) {
357
+ assertNotSql(path, value);
358
+ if (!isRecord(value) || !Object.hasOwn(value, key)) {
359
+ return value;
360
+ }
361
+ const { [key]: inner, ...others } = value;
362
+ return rest.length > 0 ? { ...others, [key]: withoutPath(path, inner, rest) } : others;
363
+ }
364
+ /** Refuses an operator inside a value `sql` sets, whose result the statement cannot know. */
365
+ function assertNotSql(path, value) {
366
+ if (value instanceof QuerySql) {
367
+ throw new UqlUsageError(`'${path}' is set by sql, so no other operator can write inside it`);
368
+ }
369
+ }
220
370
  /** `satisfies` ties this to {@link FieldUpdateOp}, so renaming an operator breaks it at compile time. */
221
371
  const FIELD_UPDATE_OPS = ['$inc', '$mul'];
222
372
  /** 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
- import type { EntityMeta } from '../type/index.js';
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;
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
+ /** Whether `value` is a {@link JsonScalar}, which `$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.2",
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",
@@ -107,7 +107,7 @@ const users = await pool.findMany(User, {
107
107
  - The keys are `$select`, `$exclude`, `$where`, `$populate`, `$count`, `$distinct`, `$sort`, `$skip`, `$limit`; `$count: { posts: true }` tallies a to-many under `_count` without loading it.
108
108
  - `$sort` takes `'asc'`/`1` or `'desc'`/`-1`, and `'ascNullsLast'`, `'ascNullsFirst'`, `'descNullsFirst'` or `'descNullsLast'` to say where nulls land, which reads the same on every engine (emulated where there is no `NULLS FIRST`). Unqualified, each engine keeps its own answer: Postgres sorts nulls last on `asc`, the rest sort them first.
109
109
  - `findManyPage(User, { $sort: { createdAt: -1, id: 1 }, $limit: 20, $after })` pages by cursor, so page 1,000 costs what page 1 does, and answers `{ items, startCursor, endCursor, hasNextPage, hasPrevPage }`: pass `endCursor` as `$after`, or `startCursor` as `$before` to go back. `$sort` must include the key or a unique `nullable: false` field, uses the entity's own fields, and takes no `$skip`. A nullable leading sort key pages correctly but cannot use an index.
110
- - `$where` takes a value for equality or an operator map: `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$nin`, `$between`, `$like`, `$ilike`, `$regex`, `$startsWith`, `$endsWith`, `$includes`, `$isNull`, `$isNotNull`. `$and`, `$or`, `$not` and `$nor` combine clauses.
110
+ - `$where` takes a value for equality or an operator map: `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$nin`, `$between`, `$like`, `$ilike`, `$regex`, `$startsWith`, `$endsWith`, `$includes`, `$isNull`, `$isNotNull`. `$regex` is case-sensitive unless it opens with `(?i)`, which an embedded libSQL file refuses. `$and`, `$or`, `$not` and `$nor` combine clauses.
111
111
  - An `undefined` anywhere in `$where` throws instead of filtering by nothing: leave the key out not to filter by it (`...(email && { email })`), or name `null`.
112
112
  - NULL compares the way the engine compares it: on SQL, `$ne`, `$nin`, `$not` and `$nor` leave out a NULL row, where MongoDB keeps it. Name NULL where you want it, `{ $or: [{ col: { $ne: 'a' } }, { col: null }] }`; ask for NULL with `{ col: null }` and its absence with `{ col: { $ne: null } }`.
113
113
  - `$text: { $value }` in `$where` searches text on every engine with full-text search, through the entity's `@Index(..., { type: 'fulltext', config })`, whose columns may carry a `weight`. `$sort: { $text: 'desc' }` ranks by relevance, and `{ $text: { $project: 'score' } }` also returns it, typed with `WithProjection<E, 'score'>`.
@@ -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`, `$unset`, `$push`, `$pull`.
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.
@@ -158,5 +158,5 @@ Checks, an enum's included, and triggers are part of the diff: uql owns the `_uq
158
158
  - Computed fields and stamps: https://uql-orm.dev/entities/computed-fields.md
159
159
  - Triggers: https://uql-orm.dev/entities/triggers.md
160
160
  - Every method's signature: https://uql-orm.dev/querying/methods.md
161
- - Coming from Prisma, Drizzle, TypeORM or MikroORM: https://uql-orm.dev/switching-to-uql.md
161
+ - Coming from Prisma, Drizzle, TypeORM, MikroORM or Mongoose: https://uql-orm.dev/switching-to-uql.md; moving data off MongoDB: https://uql-orm.dev/mongodb.md#moving-to-sql
162
162
  - Breaking changes by version: https://uql-orm.dev/upgrade-guide.md