uql-orm 0.101.6 → 0.102.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/browser/uql-browser.min.js +2 -2
- package/dist/browser/uql-browser.min.js.map +3 -3
- package/dist/dialect/abstractDialect.js +2 -1
- package/dist/dialect/abstractSqlDialect.d.ts +54 -24
- package/dist/dialect/abstractSqlDialect.js +102 -52
- package/dist/dialect/aliases.d.ts +8 -0
- package/dist/dialect/aliases.js +24 -16
- package/dist/dialect/jsonSql.d.ts +10 -7
- package/dist/dialect/jsonSql.js +7 -10
- package/dist/dialect/mysqlLikeSqlDialect.d.ts +6 -10
- package/dist/dialect/mysqlLikeSqlDialect.js +13 -13
- package/dist/dialect/pgLikeSqlDialect.d.ts +20 -13
- package/dist/dialect/pgLikeSqlDialect.js +38 -29
- package/dist/libsql/libsqlDialect.d.ts +5 -0
- package/dist/libsql/libsqlDialect.js +5 -0
- package/dist/mongodb/mongoDialect.d.ts +4 -12
- package/dist/mongodb/mongoDialect.js +70 -70
- package/dist/mssql/mssqlDialect.d.ts +24 -14
- package/dist/mssql/mssqlDialect.js +42 -32
- package/dist/mysql/mysqlDialect.js +1 -1
- package/dist/querier/abstractQuerier.d.ts +52 -17
- package/dist/querier/abstractQuerier.js +141 -81
- package/dist/querier/abstractSqlQuerier.d.ts +5 -1
- package/dist/querier/abstractSqlQuerier.js +16 -1
- package/dist/querier/cursorStream.js +1 -2
- package/dist/sqlite/hranaQuerier.d.ts +2 -2
- package/dist/sqlite/hranaQuerier.js +2 -2
- package/dist/sqlite/localSqliteQuerierPool.js +8 -2
- package/dist/sqlite/sqliteDialect.d.ts +8 -7
- package/dist/sqlite/sqliteDialect.js +15 -9
- package/dist/turso/tursoLocalDialect.d.ts +3 -1
- package/dist/turso/tursoLocalDialect.js +7 -0
- package/dist/type/dialect.d.ts +6 -0
- package/dist/type/entity.d.ts +18 -10
- package/dist/type/querier.d.ts +6 -0
- package/dist/util/dialect.util.d.ts +27 -0
- package/dist/util/dialect.util.js +120 -4
- package/dist/util/field.util.d.ts +2 -0
- package/dist/util/field.util.js +5 -0
- package/dist/util/object.util.d.ts +2 -0
- package/dist/util/object.util.js +4 -0
- package/package.json +7 -7
- package/skills/uql-orm/SKILL.md +5 -5
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { AbstractSqlDialect, type DerivedRelation, type RelationRows, type SelectTerm } from '../dialect/abstractSqlDialect.js';
|
|
2
|
-
import { type JsonAccessMode, type JsonSlot } from '../dialect/jsonSql.js';
|
|
3
|
-
import { type EntityMeta, type FieldOptions, type Query, type QueryContext, type QueryTextSearchOptions, type QueryWhere, type SqlDialectFeatures, type SqlValues, type VectorDistance, type VectorMetric } from '../type/index.js';
|
|
2
|
+
import { type JsonAccessMode, type JsonContainer, type JsonSlot } from '../dialect/jsonSql.js';
|
|
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;
|
|
6
6
|
export declare class SqliteDialect extends AbstractSqlDialect {
|
|
@@ -8,8 +8,9 @@ export declare class SqliteDialect extends AbstractSqlDialect {
|
|
|
8
8
|
readonly dialectName = "sqlite";
|
|
9
9
|
readonly escapeIdChar = "`";
|
|
10
10
|
readonly autoIncrementSuffix = "PRIMARY KEY AUTOINCREMENT";
|
|
11
|
-
readonly beginTransactionCommand
|
|
12
|
-
|
|
11
|
+
readonly beginTransactionCommand: string;
|
|
12
|
+
/** No level to set: SQLite serializes writers. A read-only transaction defers its lock to its first write. */
|
|
13
|
+
getBeginTransactionStatements({ readOnly }?: TransactionOptions): string[];
|
|
13
14
|
readonly booleanLiteral = "integer";
|
|
14
15
|
/**
|
|
15
16
|
* The clock and today in the same text as a bound `Date`, where `CURRENT_TIMESTAMP` writes whole seconds and
|
|
@@ -69,7 +70,8 @@ export declare class SqliteDialect extends AbstractSqlDialect {
|
|
|
69
70
|
protected jsonLength(slot: JsonSlot): string;
|
|
70
71
|
/** `JSON_EACH` walks the array at the path itself, each element's `fullkey` naming it from the column. */
|
|
71
72
|
protected jsonElemFrom(slot: JsonSlot, alias: string): string;
|
|
72
|
-
protected
|
|
73
|
+
protected jsonIs(slot: JsonSlot, kind: JsonContainer): string;
|
|
74
|
+
protected jsonIsNull(slot: JsonSlot): string;
|
|
73
75
|
/** An object element's `value` is its JSON text, which its fields are paths into. */
|
|
74
76
|
protected jsonElemDoc(alias: string): string;
|
|
75
77
|
/**
|
|
@@ -85,6 +87,5 @@ export declare class SqliteDialect extends AbstractSqlDialect {
|
|
|
85
87
|
protected jsonCast(operand: string): string;
|
|
86
88
|
/** `JSON` keeps each element's JSON type in the array, which answers `[]` for no rows. */
|
|
87
89
|
protected jsonArrayOf(elem: string): string;
|
|
88
|
-
|
|
89
|
-
protected jsonPush(ctx: QueryContext, expr: string, push: Record<string, unknown>): string;
|
|
90
|
+
protected jsonAppended(ctx: QueryContext, array: string, value: unknown): string;
|
|
90
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,
|
|
3
|
+
import { chainedCall, groupsPerCall, jsonPath, jsonArraySlotArgs, jsonSlotArgs, } from '../dialect/jsonSql.js';
|
|
4
4
|
import { QuerySql, } from '../type/index.js';
|
|
5
5
|
import { indexDistance, isVectorIndexType } from '../type/vector.js';
|
|
6
6
|
import { declaredIndexName } from '../util/ddlExpression.util.js';
|
|
@@ -31,6 +31,7 @@ export const SQLITE_FEATURES = {
|
|
|
31
31
|
serverSideCursors: false,
|
|
32
32
|
correlatedWrites: true,
|
|
33
33
|
rowLocks: false,
|
|
34
|
+
writeReturning: true,
|
|
34
35
|
nullsSortLowest: true,
|
|
35
36
|
nullsOrdering: 'clause',
|
|
36
37
|
textScoreIndexes: false,
|
|
@@ -56,7 +57,10 @@ export class SqliteDialect extends AbstractSqlDialect {
|
|
|
56
57
|
escapeIdChar = '`';
|
|
57
58
|
autoIncrementSuffix = 'PRIMARY KEY AUTOINCREMENT';
|
|
58
59
|
beginTransactionCommand = 'BEGIN TRANSACTION';
|
|
59
|
-
|
|
60
|
+
/** No level to set: SQLite serializes writers. A read-only transaction defers its lock to its first write. */
|
|
61
|
+
getBeginTransactionStatements({ readOnly } = {}) {
|
|
62
|
+
return [readOnly ? 'BEGIN DEFERRED' : this.beginTransactionCommand];
|
|
63
|
+
}
|
|
60
64
|
booleanLiteral = 'integer';
|
|
61
65
|
/**
|
|
62
66
|
* The clock and today in the same text as a bound `Date`, where `CURRENT_TIMESTAMP` writes whole seconds and
|
|
@@ -178,14 +182,17 @@ export class SqliteDialect extends AbstractSqlDialect {
|
|
|
178
182
|
ctx.append(`-BM25(${this.escapedTableName(meta)})`);
|
|
179
183
|
}
|
|
180
184
|
jsonLength(slot) {
|
|
181
|
-
return `JSON_ARRAY_LENGTH(${jsonArraySlotArgs(slot, this.
|
|
185
|
+
return `JSON_ARRAY_LENGTH(${jsonArraySlotArgs(slot, this.jsonIs(slot, 'array'))})`;
|
|
182
186
|
}
|
|
183
187
|
/** `JSON_EACH` walks the array at the path itself, each element's `fullkey` naming it from the column. */
|
|
184
188
|
jsonElemFrom(slot, alias) {
|
|
185
|
-
return `JSON_EACH(${jsonArraySlotArgs(slot, this.
|
|
189
|
+
return `JSON_EACH(${jsonArraySlotArgs(slot, this.jsonIs(slot, 'array'))}) ${alias}`;
|
|
190
|
+
}
|
|
191
|
+
jsonIs(slot, kind) {
|
|
192
|
+
return `JSON_TYPE(${jsonSlotArgs(slot)}) = '${kind}'`;
|
|
186
193
|
}
|
|
187
|
-
|
|
188
|
-
return `JSON_TYPE(${jsonSlotArgs(slot)}) = '
|
|
194
|
+
jsonIsNull(slot) {
|
|
195
|
+
return `COALESCE(JSON_TYPE(${jsonSlotArgs(slot)}), 'null') = 'null'`;
|
|
189
196
|
}
|
|
190
197
|
/** An object element's `value` is its JSON text, which its fields are paths into. */
|
|
191
198
|
jsonElemDoc(alias) {
|
|
@@ -220,8 +227,7 @@ export class SqliteDialect extends AbstractSqlDialect {
|
|
|
220
227
|
jsonArrayOf(elem) {
|
|
221
228
|
return `JSON_GROUP_ARRAY(JSON(${elem}))`;
|
|
222
229
|
}
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
return jsonSetCall((value) => this.jsonScalarParam(ctx, value), expr, push, this.maxFunctionArgs, '[#]');
|
|
230
|
+
jsonAppended(ctx, array, value) {
|
|
231
|
+
return `JSON_INSERT(${array}, '$[#]', ${this.jsonScalarParam(ctx, value)})`;
|
|
226
232
|
}
|
|
227
233
|
}
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type { VectorDistance, VectorMetric } from '../type/index.js';
|
|
1
|
+
import type { QueryContext, VectorDistance, VectorMetric } from '../type/index.js';
|
|
2
2
|
import { TursoDialect } from './tursoDialect.js';
|
|
3
3
|
/**
|
|
4
4
|
* SQLite Dialect specialization for the embedded Turso engine, the Rust engine alone: it adds a
|
|
@@ -7,4 +7,6 @@ import { TursoDialect } from './tursoDialect.js';
|
|
|
7
7
|
export declare class TursoLocalDialect extends TursoDialect {
|
|
8
8
|
readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorMetric>;
|
|
9
9
|
readonly maxFunctionArgs: number;
|
|
10
|
+
/** The engine appends nothing for a JSON null at a bare array's `[#]`, and does under a key, so a null goes under one. */
|
|
11
|
+
protected jsonAppended(ctx: QueryContext, array: string, value: unknown): string;
|
|
10
12
|
}
|
|
@@ -10,4 +10,11 @@ export class TursoLocalDialect extends TursoDialect {
|
|
|
10
10
|
['inner', { fn: 'vector_distance_dot' }],
|
|
11
11
|
]);
|
|
12
12
|
maxFunctionArgs = Infinity;
|
|
13
|
+
/** The engine appends nothing for a JSON null at a bare array's `[#]`, and does under a key, so a null goes under one. */
|
|
14
|
+
jsonAppended(ctx, array, value) {
|
|
15
|
+
if (value !== null) {
|
|
16
|
+
return super.jsonAppended(ctx, array, value);
|
|
17
|
+
}
|
|
18
|
+
return `JSON_SET(JSON_OBJECT('a', ${array}), '$.a[#]', ${this.jsonScalarParam(ctx, value)}) -> '$.a'`;
|
|
19
|
+
}
|
|
13
20
|
}
|
package/dist/type/dialect.d.ts
CHANGED
|
@@ -134,6 +134,12 @@ export interface DialectFeatures {
|
|
|
134
134
|
* such a write reads the ids of the rows it names first.
|
|
135
135
|
*/
|
|
136
136
|
readonly correlatedWrites: boolean;
|
|
137
|
+
/**
|
|
138
|
+
* Whether an `UPDATE` and a `DELETE` report the rows they wrote (`RETURNING`), so a write `returning` them
|
|
139
|
+
* in one statement reads them off it: the Postgres and SQLite families. MariaDB returns from a `DELETE`
|
|
140
|
+
* only, and SQL Server's `OUTPUT` fails on a table with a trigger, so both read their rows first.
|
|
141
|
+
*/
|
|
142
|
+
readonly writeReturning: boolean;
|
|
137
143
|
/**
|
|
138
144
|
* What the engine's row locks can do, or `false` where it has none: the SQLite family locks the
|
|
139
145
|
* database and MongoDB has no row lock at all, so both refuse `$lock` rather than ignoring it. One
|
package/dist/type/entity.d.ts
CHANGED
|
@@ -97,11 +97,13 @@ type JsonFieldKey<E> = {
|
|
|
97
97
|
}[JsonColumnKey<E>];
|
|
98
98
|
/**
|
|
99
99
|
* The dot-paths into a JSON payload: any suffix on an untyped one, none past a scalar, an array's
|
|
100
|
-
* element's, and an object's keys five levels deep, below which any suffix is accepted.
|
|
100
|
+
* element's unless `Arrays` is false, and an object's keys five levels deep, below which any suffix is accepted.
|
|
101
101
|
*/
|
|
102
|
-
type DeepJsonKeys<T, D extends unknown[] = []> = unknown extends T ? string : NonNullable<T> extends Scalar ? never : NonNullable<T> extends readonly (infer U)[] ? DeepJsonKeys<U, D> : D['length'] extends 5 ? string : {
|
|
103
|
-
[K in keyof NonNullable<T> & string]: K | `${K}.${DeepJsonKeys<NonNullable<T>[K], [...D, unknown]>}`;
|
|
102
|
+
type DeepJsonKeys<T, D extends unknown[] = [], Arrays = true> = unknown extends T ? string : NonNullable<T> extends Scalar ? never : NonNullable<T> extends readonly (infer U)[] ? Arrays extends true ? DeepJsonKeys<U, D, Arrays> : never : D['length'] extends 5 ? string : {
|
|
103
|
+
[K in keyof NonNullable<T> & string]: K | `${K}.${DeepJsonKeys<NonNullable<T>[K], [...D, unknown], Arrays>}`;
|
|
104
104
|
}[keyof NonNullable<T> & string];
|
|
105
|
+
/** The dotted paths into `T`'s nested objects, never through an array: what a dotted `$set` and `$unset` name. */
|
|
106
|
+
type JsonNestedPaths<T> = Extract<DeepJsonKeys<T, [], false>, `${string}.${string}`>;
|
|
105
107
|
/**
|
|
106
108
|
* The dot-paths into an entity's JSON columns: `kind?: Json<{ theme: { color: string } }>` gives
|
|
107
109
|
* `'kind.theme' | 'kind.theme.color'`, `items?: Json<{ id: string }>[]` gives `'items.id'`, and an
|
|
@@ -117,20 +119,26 @@ export type JsonFieldPaths<E> = {
|
|
|
117
119
|
type PathValue<T, P extends string> = unknown extends T ? unknown : NonNullable<T> extends readonly (infer U)[] ? PathValue<NonNullable<U>, P> : P extends `${infer K}.${infer Rest}` ? K extends keyof NonNullable<T> ? PathValue<NonNullable<T>[K], Rest> : unknown : P extends keyof NonNullable<T> ? NonNullable<T>[P] : unknown;
|
|
118
120
|
/** The value at a JSON dot-path of `E`, `unknown` where it cannot be resolved, which keeps an untyped path permissive. */
|
|
119
121
|
export type JsonFieldPathValue<E, P extends string> = P extends `${infer F}.${infer Rest}` ? F extends JsonFieldKey<E> ? PathValue<JsonPayload<E[F]>, Rest> : unknown : unknown;
|
|
120
|
-
/**
|
|
121
|
-
|
|
122
|
-
|
|
122
|
+
/**
|
|
123
|
+
* The keys of `T` holding an array of `Element`, each mapped to its element type: what `$push` and `$pull`
|
|
124
|
+
* address, and with scalar elements, `$addToSet`.
|
|
125
|
+
*/
|
|
126
|
+
export type JsonArrayFields<T, Element = unknown> = {
|
|
127
|
+
[K in keyof T as IsMany<T[K]> extends true ? Unpacked<NonNullable<T[K]>> extends Element ? K & string : never : never]?: Unpacked<NonNullable<T[K]>>;
|
|
123
128
|
};
|
|
124
129
|
/**
|
|
125
|
-
* A JSON field's update operators, applied `$pull`, `$set`, `$push`, `$
|
|
126
|
-
*
|
|
130
|
+
* A JSON field's update operators, applied in order on every engine, `$pull`, `$set`, `$push`, `$addToSet`,
|
|
131
|
+
* `$unset`, each seeing what the one before wrote; see the JSON guide.
|
|
127
132
|
* @example `{ kind: { $set: { public: 1 }, $push: { tags: 'x' }, $unset: ['private'] } }`
|
|
128
133
|
*/
|
|
129
134
|
export type JsonUpdateOp<T = unknown> = {
|
|
130
|
-
readonly $set?: Partial<T
|
|
131
|
-
|
|
135
|
+
readonly $set?: Partial<T> & {
|
|
136
|
+
readonly [P in JsonNestedPaths<T>]?: PathValue<T, P>;
|
|
137
|
+
};
|
|
138
|
+
readonly $unset?: unknown extends T ? readonly string[] : readonly ((keyof T & string) | JsonNestedPaths<T>)[];
|
|
132
139
|
readonly $push?: JsonArrayFields<T>;
|
|
133
140
|
readonly $pull?: JsonArrayFields<T>;
|
|
141
|
+
readonly $addToSet?: JsonArrayFields<T, string | number | boolean>;
|
|
134
142
|
};
|
|
135
143
|
/**
|
|
136
144
|
* The {@link JsonUpdateOp} a field takes: `never` on a non-JSON field, and on a JSON array, whose
|
package/dist/type/querier.d.ts
CHANGED
|
@@ -21,6 +21,12 @@ export type TransactionOptions = {
|
|
|
21
21
|
* failed start leaves it on the connection: set it per transaction that needs it.
|
|
22
22
|
*/
|
|
23
23
|
readonly isolationLevel?: IsolationLevel;
|
|
24
|
+
/**
|
|
25
|
+
* A transaction that only reads, so the engine refuses its writes where it has the mode (Postgres,
|
|
26
|
+
* CockroachDB, MySQL, MariaDB, libSQL's client), and the SQLite family takes no write lock for it.
|
|
27
|
+
* SQL Server and MongoDB have no such mode and ignore it.
|
|
28
|
+
*/
|
|
29
|
+
readonly readOnly?: boolean;
|
|
24
30
|
};
|
|
25
31
|
export type DialectName = SqlDialectName | 'mongodb';
|
|
26
32
|
/**
|
|
@@ -67,6 +67,32 @@ export declare function vectorDistanceOf<E>(meta: EntityMeta<E>, key: string, se
|
|
|
67
67
|
export declare function hasVectorNear(where: unknown): boolean;
|
|
68
68
|
/** Type guard: checks whether an update payload value is a JSON operator object. */
|
|
69
69
|
export declare function isJsonUpdateOp(value: unknown): value is JsonUpdateOp;
|
|
70
|
+
/** An item one array key's writes append, `unique` where it goes in only if the stored array lacks it. */
|
|
71
|
+
type JsonAppend = {
|
|
72
|
+
readonly item: unknown;
|
|
73
|
+
readonly unique: boolean;
|
|
74
|
+
};
|
|
75
|
+
/** One array key's writes, in order: `pull` removes every element equal to its item, then each append adds one. */
|
|
76
|
+
export type JsonArrayWrites = {
|
|
77
|
+
readonly pull?: {
|
|
78
|
+
readonly item: unknown;
|
|
79
|
+
};
|
|
80
|
+
readonly appends: readonly JsonAppend[];
|
|
81
|
+
};
|
|
82
|
+
/** A JSON update with each path written once: the value set at each, each array key's writes, and the paths removed. */
|
|
83
|
+
export type JsonWrites = {
|
|
84
|
+
readonly set: Readonly<Record<string, unknown>>;
|
|
85
|
+
readonly arrays: Readonly<Record<string, JsonArrayWrites>>;
|
|
86
|
+
readonly unset: readonly string[];
|
|
87
|
+
};
|
|
88
|
+
/** Whether the writes put a key into the document, so a NULL column must first become an object. */
|
|
89
|
+
export declare function writesKeys({ set, arrays }: JsonWrites): boolean;
|
|
90
|
+
/**
|
|
91
|
+
* A JSON update as one write per path, its operators applied in order: `$pull`, `$set` in key order, `$push`,
|
|
92
|
+
* `$addToSet`, `$unset`. Where one reaches a value another wrote, the result is worked out here, so every engine
|
|
93
|
+
* writes each path once and reads only what is stored. A `$set` of `undefined` writes nothing.
|
|
94
|
+
*/
|
|
95
|
+
export declare function foldJsonUpdate(value: JsonUpdateOp): JsonWrites;
|
|
70
96
|
/** Type guard: checks whether an update payload value is a scalar field's operator. */
|
|
71
97
|
export declare function isFieldUpdateOp(value: unknown): value is FieldUpdateOp;
|
|
72
98
|
/**
|
|
@@ -187,3 +213,4 @@ export declare function rankedTextSearch<E>(where: QueryWhere<E> | undefined): Q
|
|
|
187
213
|
* where neither says, rather than guessed: every engine answers a guess with an error of its own.
|
|
188
214
|
*/
|
|
189
215
|
export declare function textSearchFields<E>(meta: EntityMeta<E>, search: QueryTextSearchOptions<E>): readonly string[];
|
|
216
|
+
export {};
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
import { getContext } from '../context/context.js';
|
|
2
2
|
import { QuerySql, resolveAggregateOp, SOFT_DELETE_FILTER, } from '../type/index.js';
|
|
3
3
|
import { DEFAULT_VECTOR_DISTANCE, VECTOR_INDEX_TYPES } from '../type/vector.js';
|
|
4
|
-
import { defaultReadKeys, fieldKeys, isDatabaseWritten } from './field.util.js';
|
|
5
|
-
import { entityName, getKeys, hasKeys, isOperatorObject, isRecord, someKey } from './object.util.js';
|
|
4
|
+
import { defaultReadKeys, fieldKeys, isDatabaseWritten, jsonKey, jsonPathKeys } from './field.util.js';
|
|
5
|
+
import { entityName, getKeys, hasKeys, isJsonScalar, isOperatorObject, isRecord, someKey } from './object.util.js';
|
|
6
6
|
import { assertNoUndefined, whereAnd } from './query.util.js';
|
|
7
7
|
import { UqlSecurityError, UqlUsageError } from './uqlError.js';
|
|
8
8
|
/** The keys of `payload` a write persists as columns. */
|
|
@@ -208,15 +208,131 @@ function indexCoversColumn(index, key) {
|
|
|
208
208
|
}
|
|
209
209
|
/** `satisfies` ties this to {@link JsonUpdateOp}, so renaming an operator breaks it at compile time. */
|
|
210
210
|
const JSON_UPDATE_OPS = [
|
|
211
|
+
'$pull',
|
|
211
212
|
'$set',
|
|
212
|
-
'$unset',
|
|
213
213
|
'$push',
|
|
214
|
-
'$
|
|
214
|
+
'$addToSet',
|
|
215
|
+
'$unset',
|
|
215
216
|
];
|
|
216
217
|
/** Type guard: checks whether an update payload value is a JSON operator object. */
|
|
217
218
|
export function isJsonUpdateOp(value) {
|
|
218
219
|
return isRecord(value) && someKey(value, (key) => JSON_UPDATE_OPS.includes(key));
|
|
219
220
|
}
|
|
221
|
+
/** Whether the writes put a key into the document, so a NULL column must first become an object. */
|
|
222
|
+
export function writesKeys({ set, arrays }) {
|
|
223
|
+
return hasKeys(set) || Object.values(arrays).some((write) => write.appends.length > 0);
|
|
224
|
+
}
|
|
225
|
+
/**
|
|
226
|
+
* A JSON update as one write per path, its operators applied in order: `$pull`, `$set` in key order, `$push`,
|
|
227
|
+
* `$addToSet`, `$unset`. Where one reaches a value another wrote, the result is worked out here, so every engine
|
|
228
|
+
* writes each path once and reads only what is stored. A `$set` of `undefined` writes nothing.
|
|
229
|
+
*/
|
|
230
|
+
export function foldJsonUpdate(value) {
|
|
231
|
+
const set = new Map();
|
|
232
|
+
const arrays = new Map();
|
|
233
|
+
const unset = new Set();
|
|
234
|
+
for (const [key, item] of Object.entries(value.$pull ?? {})) {
|
|
235
|
+
arrays.set(jsonKey(key), { pull: { item }, appends: [] });
|
|
236
|
+
}
|
|
237
|
+
for (const [path, item] of Object.entries(value.$set ?? {})) {
|
|
238
|
+
if (item !== undefined) {
|
|
239
|
+
const keys = jsonPathKeys(path);
|
|
240
|
+
arrays.delete(keys[0]);
|
|
241
|
+
dropWithin(set, path);
|
|
242
|
+
const owner = ownerOf(set, keys);
|
|
243
|
+
if (owner) {
|
|
244
|
+
set.set(owner.path, withPath(owner.path, set.get(owner.path), owner.rest, item));
|
|
245
|
+
}
|
|
246
|
+
else {
|
|
247
|
+
set.set(path, item);
|
|
248
|
+
}
|
|
249
|
+
}
|
|
250
|
+
}
|
|
251
|
+
for (const op of ['$push', '$addToSet']) {
|
|
252
|
+
for (const [key, item] of Object.entries(value[op] ?? {})) {
|
|
253
|
+
const unique = op === '$addToSet';
|
|
254
|
+
if (unique && !isJsonScalar(item)) {
|
|
255
|
+
throw new UqlUsageError(`$addToSet on '${key}' takes a string, a finite number or a boolean`);
|
|
256
|
+
}
|
|
257
|
+
appendTo(set, arrays, jsonKey(key), item, unique);
|
|
258
|
+
}
|
|
259
|
+
}
|
|
260
|
+
for (const path of value.$unset ?? []) {
|
|
261
|
+
const keys = jsonPathKeys(path);
|
|
262
|
+
dropWithin(set, path);
|
|
263
|
+
arrays.delete(path);
|
|
264
|
+
const owner = ownerOf(set, keys);
|
|
265
|
+
if (owner) {
|
|
266
|
+
set.set(owner.path, withoutPath(owner.path, set.get(owner.path), owner.rest));
|
|
267
|
+
}
|
|
268
|
+
else {
|
|
269
|
+
unset.add(path);
|
|
270
|
+
}
|
|
271
|
+
}
|
|
272
|
+
return { set: Object.fromEntries(set), arrays: Object.fromEntries(arrays), unset: [...unset] };
|
|
273
|
+
}
|
|
274
|
+
/** `item` appended at `key`: onto the array a `$set` wrote there, or else among the key's array writes. */
|
|
275
|
+
function appendTo(set, arrays, key, item, unique) {
|
|
276
|
+
if (set.has(key)) {
|
|
277
|
+
const written = set.get(key);
|
|
278
|
+
assertNotSql(key, written);
|
|
279
|
+
if (written === null) {
|
|
280
|
+
set.set(key, [item]);
|
|
281
|
+
}
|
|
282
|
+
else if (Array.isArray(written) && !(unique && written.includes(item))) {
|
|
283
|
+
set.set(key, [...written, item]);
|
|
284
|
+
}
|
|
285
|
+
return;
|
|
286
|
+
}
|
|
287
|
+
if ([...set.keys()].some((path) => path.startsWith(`${key}.`))) {
|
|
288
|
+
return;
|
|
289
|
+
}
|
|
290
|
+
const write = arrays.get(key) ?? { appends: [] };
|
|
291
|
+
arrays.set(key, write);
|
|
292
|
+
if (!(unique && write.appends.some((append) => append.item === item))) {
|
|
293
|
+
write.appends.push({ item, unique: unique && write.pull?.item !== item });
|
|
294
|
+
}
|
|
295
|
+
}
|
|
296
|
+
/** Removes `path` and every path inside it from `set`. */
|
|
297
|
+
function dropWithin(set, path) {
|
|
298
|
+
for (const written of set.keys()) {
|
|
299
|
+
if (written === path || written.startsWith(`${path}.`)) {
|
|
300
|
+
set.delete(written);
|
|
301
|
+
}
|
|
302
|
+
}
|
|
303
|
+
}
|
|
304
|
+
/** The path in `set` holding the value `keys` lead into, and the keys left below it. */
|
|
305
|
+
function ownerOf(set, keys) {
|
|
306
|
+
for (let depth = 1; depth < keys.length; depth++) {
|
|
307
|
+
const path = keys.slice(0, depth).join('.');
|
|
308
|
+
if (set.has(path)) {
|
|
309
|
+
return { path, rest: keys.slice(depth) };
|
|
310
|
+
}
|
|
311
|
+
}
|
|
312
|
+
return undefined;
|
|
313
|
+
}
|
|
314
|
+
/** `value` with `item` at `keys`, a value that is no object becoming one, as a dotted `$set` makes it. */
|
|
315
|
+
function withPath(path, value, [key, ...rest], item) {
|
|
316
|
+
assertNotSql(path, value);
|
|
317
|
+
const object = isRecord(value) ? value : {};
|
|
318
|
+
const inner = Object.hasOwn(object, key) ? object[key] : undefined;
|
|
319
|
+
return { ...object, [key]: rest.length > 0 ? withPath(path, inner, rest, item) : item };
|
|
320
|
+
}
|
|
321
|
+
/** `value` without `keys`, as it is where they lead nowhere. */
|
|
322
|
+
function withoutPath(path, value, [key, ...rest]) {
|
|
323
|
+
assertNotSql(path, value);
|
|
324
|
+
if (!isRecord(value) || !Object.hasOwn(value, key)) {
|
|
325
|
+
return value;
|
|
326
|
+
}
|
|
327
|
+
const { [key]: inner, ...others } = value;
|
|
328
|
+
return rest.length > 0 ? { ...others, [key]: withoutPath(path, inner, rest) } : others;
|
|
329
|
+
}
|
|
330
|
+
/** Refuses an operator inside a value `sql` sets, whose result the statement cannot know. */
|
|
331
|
+
function assertNotSql(path, value) {
|
|
332
|
+
if (value instanceof QuerySql) {
|
|
333
|
+
throw new UqlUsageError(`'${path}' is set by sql, so no other operator can write inside it`);
|
|
334
|
+
}
|
|
335
|
+
}
|
|
220
336
|
/** `satisfies` ties this to {@link FieldUpdateOp}, so renaming an operator breaks it at compile time. */
|
|
221
337
|
const FIELD_UPDATE_OPS = ['$inc', '$mul'];
|
|
222
338
|
/** Type guard: checks whether an update payload value is a scalar field's operator. */
|
|
@@ -68,3 +68,5 @@ export declare function defaultReadKeys<E>(meta: EntityMeta<E>): FieldKey<E>[];
|
|
|
68
68
|
export declare function jsonKey(key: string): string;
|
|
69
69
|
/** The keys of a dotted JSON path (`settings.theme`), each a {@link jsonKey}. */
|
|
70
70
|
export declare function jsonPathKeys(path: string): string[];
|
|
71
|
+
/** The paths a dotted JSON path passes through, outermost first, not counting the path itself. */
|
|
72
|
+
export declare function ancestorPaths(path: string): string[];
|
package/dist/util/field.util.js
CHANGED
|
@@ -138,3 +138,8 @@ export function jsonKey(key) {
|
|
|
138
138
|
export function jsonPathKeys(path) {
|
|
139
139
|
return path.split('.').map(jsonKey);
|
|
140
140
|
}
|
|
141
|
+
/** The paths a dotted JSON path passes through, outermost first, not counting the path itself. */
|
|
142
|
+
export function ancestorPaths(path) {
|
|
143
|
+
const keys = jsonPathKeys(path);
|
|
144
|
+
return keys.slice(0, -1).map((_, depth) => keys.slice(0, depth + 1).join('.'));
|
|
145
|
+
}
|
|
@@ -1,4 +1,6 @@
|
|
|
1
1
|
import type { EntityMeta } from '../type/index.js';
|
|
2
|
+
/** A value a JSON document holds whole, and `$addToSet` and an `=` on a JSON path compare by equality. */
|
|
3
|
+
export declare function isJsonScalar(value: unknown): value is string | number | boolean;
|
|
2
4
|
export declare function clone<T>(value: T): T;
|
|
3
5
|
/** `items` in consecutive lists of at most `size`, in order: one list where `size` is unbounded. */
|
|
4
6
|
export declare function chunk<T>(items: readonly T[], size: number): T[][];
|
package/dist/util/object.util.js
CHANGED
|
@@ -1,3 +1,7 @@
|
|
|
1
|
+
/** A value a JSON document holds whole, and `$addToSet` and an `=` on a JSON path compare by equality. */
|
|
2
|
+
export function isJsonScalar(value) {
|
|
3
|
+
return typeof value === 'string' || typeof value === 'boolean' || Number.isFinite(value);
|
|
4
|
+
}
|
|
1
5
|
export function clone(value) {
|
|
2
6
|
if (typeof value !== 'object' || value === null) {
|
|
3
7
|
return value;
|
package/package.json
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
"homepage": "https://uql-orm.dev",
|
|
4
4
|
"description": "JSON-native TypeScript ORM for Bun, Browsers, Edge, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, SQL Server, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
|
|
5
5
|
"license": "MIT",
|
|
6
|
-
"version": "0.
|
|
6
|
+
"version": "0.102.1",
|
|
7
7
|
"type": "module",
|
|
8
8
|
"engines": {
|
|
9
9
|
"node": ">=22.18"
|
|
@@ -126,14 +126,14 @@
|
|
|
126
126
|
}
|
|
127
127
|
},
|
|
128
128
|
"devDependencies": {
|
|
129
|
-
"@electric-sql/pglite": "0.5.
|
|
130
|
-
"@electric-sql/pglite-pgvector": "0.0.
|
|
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.
|
|
134
|
-
"@nestjs/core": "^12.1.
|
|
135
|
-
"@nestjs/testing": "^12.1.
|
|
136
|
-
"@tursodatabase/database": "^0.8.
|
|
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",
|
package/skills/uql-orm/SKILL.md
CHANGED
|
@@ -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'>`.
|
|
@@ -116,9 +116,9 @@ const users = await pool.findMany(User, {
|
|
|
116
116
|
- A query is plain data, so it can be built dynamically, stored, or sent from a browser to `uql-orm/http`, whose handler serves only the entities its required `include` names.
|
|
117
117
|
- Methods: `findMany`, `findOne`, `findOneById`, `findManyAndCount`, `findManyPage`, `findManyStream`, `count`, `exists`, `aggregate`, `insertOne`, `insertMany`, `updateOneById`, `updateMany`, `saveOne`, `saveMany`, `upsertOne`, `upsertMany`, `deleteOneById`, `deleteMany`. Each takes the entity class first.
|
|
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
|
-
- 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.
|
|
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
|
|
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`.
|
|
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.
|
|
@@ -134,7 +134,7 @@ await pool.transaction(async (querier) => {
|
|
|
134
134
|
});
|
|
135
135
|
```
|
|
136
136
|
|
|
137
|
-
The callback commits when it returns and rolls back when it throws; `beginTransaction` / `commitTransaction` / `rollbackTransaction` are for a transaction that opens in one place and ends in another. Inside the callback, a `pool` call runs on the callback's querier, so it is part of the transaction. A `transaction()` inside another is a savepoint, whose failure undoes its own writes alone (MongoDB, with none, refuses it). A transaction holds its connection: a statement from outside its callback waits for it. `querier.onCommit(fn)` (or a hook's `onCommit`) runs `fn` after the outermost commit, never on a rollback: use it for mails and queued jobs. A querier from `pool.getQuerier()` is yours to release: bind it with `await using`.
|
|
137
|
+
The callback commits when it returns and rolls back when it throws; `beginTransaction` / `commitTransaction` / `rollbackTransaction` are for a transaction that opens in one place and ends in another. Inside the callback, a `pool` call runs on the callback's querier, so it is part of the transaction. A `transaction()` inside another is a savepoint, whose failure undoes its own writes alone (MongoDB, with none, refuses it). A transaction holds its connection: a statement from outside its callback waits for it. `{ readOnly: true }` opens a transaction that only reads: Postgres, CockroachDB, MySQL and MariaDB refuse its writes, and libSQL and Turso skip the write lock they otherwise take at `BEGIN`. `querier.onCommit(fn)` (or a hook's `onCommit`) runs `fn` after the outermost commit, never on a rollback: use it for mails and queued jobs. A querier from `pool.getQuerier()` is yours to release: bind it with `await using`.
|
|
138
138
|
|
|
139
139
|
A `findManyStream` holds its querier until the loop ends, which refuses any other statement meanwhile: inside the loop, run them on another connection; inside a transaction, or on SQLite and PGlite (one shared connection), run them after the loop. That includes an `@AfterLoad` querying through its `querier` on a streamed row. A statement binding more values than the engine takes (100 on D1, 2098 on SQL Server) is refused too: split a long `$in`.
|
|
140
140
|
|
|
@@ -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
|
|
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
|