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.
- package/dist/browser/uql-browser.min.js +2 -2
- package/dist/browser/uql-browser.min.js.map +2 -2
- package/dist/cockroachdb/cockroachDialect.d.ts +1 -1
- package/dist/cockroachdb/cockroachDialect.js +1 -1
- package/dist/dialect/abstractSqlDialect.d.ts +14 -13
- package/dist/dialect/abstractSqlDialect.js +33 -32
- package/dist/dialect/aliases.d.ts +5 -3
- package/dist/dialect/aliases.js +7 -3
- package/dist/dialect/jsonSql.d.ts +4 -0
- package/dist/dialect/jsonSql.js +9 -0
- package/dist/dialect/mysqlLikeSqlDialect.d.ts +2 -1
- package/dist/dialect/mysqlLikeSqlDialect.js +8 -3
- package/dist/dialect/pgLikeSqlDialect.d.ts +4 -3
- package/dist/dialect/pgLikeSqlDialect.js +10 -7
- package/dist/dialect/queryJoins.d.ts +1 -1
- package/dist/mariadb/mariaDialect.d.ts +2 -2
- package/dist/mariadb/mariaDialect.js +2 -2
- package/dist/mongodb/mongoDialect.d.ts +26 -20
- package/dist/mongodb/mongoDialect.js +178 -126
- package/dist/mssql/mssqlDialect.d.ts +8 -6
- package/dist/mssql/mssqlDialect.js +32 -20
- package/dist/sqlite/sqliteDialect.d.ts +1 -1
- package/dist/sqlite/sqliteDialect.js +3 -3
- package/dist/turso/tursoLocalDialect.d.ts +2 -2
- package/dist/turso/tursoLocalDialect.js +7 -5
- package/dist/type/entity.d.ts +25 -11
- package/dist/type/queryAggregate.d.ts +3 -6
- package/dist/type/utility.d.ts +2 -0
- package/dist/util/dialect.util.d.ts +13 -13
- package/dist/util/dialect.util.js +47 -13
- package/dist/util/object.util.d.ts +3 -3
- package/dist/util/object.util.js +1 -1
- package/package.json +3 -3
- 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,
|
|
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
|
|
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
|
|
66
|
+
return OPENJSON_TYPE.number;
|
|
59
67
|
}
|
|
60
|
-
return typeof value === 'boolean' ?
|
|
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
|
-
/**
|
|
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
|
-
|
|
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} =
|
|
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 =
|
|
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
|
-
*
|
|
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
|
-
|
|
436
|
+
jsonKeptAggregate() {
|
|
424
437
|
const val = this.jsonElemDoc(JSON_PULL_ALIAS);
|
|
425
438
|
const encoded = `CASE ${JSON_PULL_ALIAS}.${this.#elem.type}` +
|
|
426
|
-
` WHEN
|
|
427
|
-
` WHEN
|
|
439
|
+
` WHEN ${OPENJSON_TYPE.null} THEN 'null'` +
|
|
440
|
+
` WHEN ${OPENJSON_TYPE.string} THEN '"' + STRING_ESCAPE(${val}, 'json') + '"'` +
|
|
428
441
|
` ELSE ${val} END`;
|
|
429
|
-
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
|
|
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
|
}
|
package/dist/type/entity.d.ts
CHANGED
|
@@ -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
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
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?:
|
|
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
|
|
145
|
-
*
|
|
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 ?
|
|
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,
|
|
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?:
|
|
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
|
|
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> = {
|
package/dist/type/utility.d.ts
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
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
|
-
|
|
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), {
|
|
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
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
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
|
-
|
|
293
|
-
|
|
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
|
-
/**
|
|
3
|
-
export declare function isJsonScalar(value: unknown): value is
|
|
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[][];
|
package/dist/util/object.util.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
/**
|
|
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.
|
|
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.
|
|
148
|
-
"mysql2": "^3.24.
|
|
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",
|
package/skills/uql-orm/SKILL.md
CHANGED
|
@@ -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.
|