uql-orm 0.100.2 → 0.100.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/README.md +8 -70
- package/dist/bunSql/bunSqlQuerierPool.js +3 -1
- package/dist/dialect/abstractSqlDialect.d.ts +27 -22
- package/dist/dialect/abstractSqlDialect.js +54 -59
- package/dist/dialect/hydrateColumn.d.ts +4 -5
- package/dist/dialect/hydrateColumn.js +2 -8
- package/dist/dialect/mysqlLikeSqlDialect.d.ts +4 -4
- package/dist/dialect/mysqlLikeSqlDialect.js +7 -6
- package/dist/dialect/pgLikeSqlDialect.d.ts +8 -2
- package/dist/dialect/pgLikeSqlDialect.js +11 -3
- package/dist/http/fetchHandler.d.ts +1 -1
- package/dist/http/fetchHandler.js +1 -1
- package/dist/mariadb/mariaDialect.d.ts +2 -2
- package/dist/mariadb/mariaDialect.js +1 -0
- package/dist/migrate/cli-config.d.ts +2 -4
- package/dist/migrate/cli-config.js +4 -4
- package/dist/mongodb/mongoDialect.js +9 -7
- package/dist/mssql/mssqlDialect.d.ts +2 -2
- package/dist/mssql/mssqlDialect.js +1 -0
- package/dist/pglite/pgliteQuerierPool.js +6 -12
- package/dist/postgres/abstractPgQuerierPool.d.ts +0 -1
- package/dist/postgres/abstractPgQuerierPool.js +0 -3
- package/dist/postgres/pgQuerier.d.ts +6 -0
- package/dist/postgres/pgQuerier.js +10 -0
- package/dist/postgres/pgWireTypes.d.ts +11 -7
- package/dist/postgres/pgWireTypes.js +47 -11
- package/dist/querier/abstractPoolQuerier.d.ts +2 -0
- package/dist/querier/abstractPoolQuerier.js +5 -1
- package/dist/querier/abstractQuerier.d.ts +1 -5
- package/dist/querier/abstractQuerier.js +18 -17
- package/dist/querier/abstractSqlQuerier.d.ts +3 -13
- package/dist/querier/abstractSqlQuerier.js +24 -84
- package/dist/querier/rowReader.d.ts +8 -0
- package/dist/querier/rowReader.js +88 -0
- package/dist/sqlite/sqliteDialect.d.ts +2 -2
- package/dist/sqlite/sqliteDialect.js +2 -1
- package/dist/util/dialect.util.d.ts +2 -11
- package/dist/util/dialect.util.js +8 -21
- package/dist/util/query.util.js +16 -8
- package/dist/util/sql.util.d.ts +0 -5
- package/dist/util/sql.util.js +0 -33
- package/dist/util/wideNumber.d.ts +4 -3
- package/dist/util/wideNumber.js +17 -6
- package/package.json +2 -3
- package/skills/uql-orm/SKILL.md +2 -2
|
@@ -1,13 +1,12 @@
|
|
|
1
1
|
import { AGGREGATE_VALUE_ALIAS, TOTAL_ALIAS } from '../dialect/aliases.js';
|
|
2
|
-
import { decodeColumn } from '../dialect/hydrateColumn.js';
|
|
3
2
|
import { getMeta, namesKey } from '../entity/index.js';
|
|
4
|
-
import {
|
|
5
|
-
import { buildUpdateResult, chunk, clone, getInsertFieldKeys, insertShapeOf, isAutoIncrement, isRecord, obtainAttrsPaths, unflatObject, } from '../util/index.js';
|
|
3
|
+
import { buildUpdateResult, chunk, clone, getInsertFieldKeys, insertShapeOf, isAutoIncrement } from '../util/index.js';
|
|
6
4
|
import { statementOf } from '../util/raw.js';
|
|
7
5
|
import { UqlUsageError } from '../util/uqlError.js';
|
|
8
6
|
import { AbstractQuerier } from './abstractQuerier.js';
|
|
9
7
|
import { streamViaCursor } from './cursorStream.js';
|
|
10
8
|
import { enrichError } from './queryError.js';
|
|
9
|
+
import { rowReader } from './rowReader.js';
|
|
11
10
|
/**
|
|
12
11
|
* Row indexes split by whether the row names its key, the one thing that changes what an insert can
|
|
13
12
|
* report; coarser than {@link groupByInsertShape} on purpose, since an insert fills a missing column with `DEFAULT`.
|
|
@@ -47,8 +46,13 @@ function groupByInsertShape(meta, payload) {
|
|
|
47
46
|
*/
|
|
48
47
|
function chunkWithinLimits(meta, payload, group, maxBindValues, maxRows = Infinity) {
|
|
49
48
|
const width = (indexes) => getInsertFieldKeys(meta, indexes.map((index) => payload[index])).length;
|
|
50
|
-
const
|
|
51
|
-
|
|
49
|
+
const groupWidth = width(group);
|
|
50
|
+
if (!groupWidth) {
|
|
51
|
+
return chunk(group, 1);
|
|
52
|
+
}
|
|
53
|
+
const chunks = chunk(group, Math.max(1, Math.min(maxRows, Math.floor(maxBindValues / groupWidth))));
|
|
54
|
+
// A split can leave a chunk whose rows name no column; one chunk is the whole group, which names some.
|
|
55
|
+
return chunks.length === 1 ? chunks : chunks.flatMap((indexes) => (width(indexes) ? [indexes] : chunk(indexes, 1)));
|
|
52
56
|
}
|
|
53
57
|
export class AbstractSqlQuerier extends AbstractQuerier {
|
|
54
58
|
dialect;
|
|
@@ -118,7 +122,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
|
|
|
118
122
|
this.assertBindBudget(values);
|
|
119
123
|
return this.serialize(async () => {
|
|
120
124
|
await this.lazyConnect();
|
|
121
|
-
return this.timed(sql, values, () => task(sql,
|
|
125
|
+
return this.timed(sql, values, () => task(sql, values));
|
|
122
126
|
});
|
|
123
127
|
}
|
|
124
128
|
/**
|
|
@@ -141,7 +145,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
|
|
|
141
145
|
}
|
|
142
146
|
}
|
|
143
147
|
async internalFindMany(entity, q, opts) {
|
|
144
|
-
return
|
|
148
|
+
return this.selectRows(entity, q, opts);
|
|
145
149
|
}
|
|
146
150
|
/** Every row `q` matches past its page, deduplicated where it reads `$distinct`. */
|
|
147
151
|
countUnpaged(entity, q, opts) {
|
|
@@ -164,8 +168,9 @@ export class AbstractSqlQuerier extends AbstractQuerier {
|
|
|
164
168
|
for (const row of rows) {
|
|
165
169
|
delete row[TOTAL_ALIAS];
|
|
166
170
|
}
|
|
167
|
-
return [rows
|
|
171
|
+
return [rows, total];
|
|
168
172
|
}
|
|
173
|
+
/** The rows a read of `entity` matches, each as its statement reads it. */
|
|
169
174
|
async selectRows(entity, q, opts, totalAlias) {
|
|
170
175
|
// Guarded rather than awaited unconditionally, here and in the stream below: an `await` on this
|
|
171
176
|
// path defers a microtask on every read, which reorders the two statements `findManyAndCount`
|
|
@@ -173,7 +178,15 @@ export class AbstractSqlQuerier extends AbstractQuerier {
|
|
|
173
178
|
if (q.$candidates !== undefined) {
|
|
174
179
|
await this.applyVectorTuning(entity, q);
|
|
175
180
|
}
|
|
176
|
-
return this.
|
|
181
|
+
return this.readRows((ctx) => this.dialect.find(ctx, entity, q, opts, totalAlias));
|
|
182
|
+
}
|
|
183
|
+
/** The rows of a read the dialect builds, each as the terms it returns say. */
|
|
184
|
+
async readRows(build) {
|
|
185
|
+
let terms = [];
|
|
186
|
+
const rows = await this.query((ctx) => {
|
|
187
|
+
terms = build(ctx);
|
|
188
|
+
});
|
|
189
|
+
return rows.map(rowReader(terms));
|
|
177
190
|
}
|
|
178
191
|
/**
|
|
179
192
|
* The one read not going through `all`, so it checks its budget and connects on its own; its values go as
|
|
@@ -181,13 +194,12 @@ export class AbstractSqlQuerier extends AbstractQuerier {
|
|
|
181
194
|
*/
|
|
182
195
|
async *internalFindManyStream(entity, q, opts) {
|
|
183
196
|
const ctx = this.dialect.createContext();
|
|
184
|
-
this.dialect.find(ctx, entity, q, opts);
|
|
197
|
+
const read = rowReader(this.dialect.find(ctx, entity, q, opts));
|
|
185
198
|
this.assertBindBudget(ctx.values);
|
|
186
199
|
if (q.$candidates !== undefined) {
|
|
187
200
|
await this.applyVectorTuning(entity, q);
|
|
188
201
|
}
|
|
189
202
|
await this.lazyConnect();
|
|
190
|
-
const read = this.rowReader(entity);
|
|
191
203
|
for await (const row of this.timedStream(ctx.sql, ctx.values, this.internalStream(ctx.sql, ctx.values))) {
|
|
192
204
|
yield read(row);
|
|
193
205
|
}
|
|
@@ -204,68 +216,6 @@ export class AbstractSqlQuerier extends AbstractQuerier {
|
|
|
204
216
|
}
|
|
205
217
|
yield* streamViaCursor((sql, params) => this.internalAll(sql, params), query, values, !!this.scopeHere());
|
|
206
218
|
}
|
|
207
|
-
/**
|
|
208
|
-
* How each row of one statement becomes the entity's, for a read, a stream and a to-many alike: its dotted
|
|
209
|
-
* columns nested as the first row names them, and its values decoded as `hydratableFields` says, resolved
|
|
210
|
-
* once. Both live with the dialect, because a `sparsevec` is only sparse on Postgres.
|
|
211
|
-
*/
|
|
212
|
-
rowReader(entity) {
|
|
213
|
-
const meta = getMeta(entity);
|
|
214
|
-
const fields = this.dialect.hydratableFields(entity);
|
|
215
|
-
let attrsPaths;
|
|
216
|
-
return (row) => {
|
|
217
|
-
attrsPaths ??= obtainAttrsPaths(row);
|
|
218
|
-
const found = unflatObject(row, attrsPaths);
|
|
219
|
-
this.hydrateFields(meta, fields, found);
|
|
220
|
-
return found;
|
|
221
|
-
};
|
|
222
|
-
}
|
|
223
|
-
/**
|
|
224
|
-
* One row of {@link rowReader}. A related row arrives as its parent's statement read it: a to-one
|
|
225
|
-
* joined and unflattened, there only when its key is, since an unmatched join still fills a computed
|
|
226
|
-
* column or a to-many's empty array; a to-many as a JSON array, which a driver may hand over as text.
|
|
227
|
-
* Each is an object of its own, so the walk reaches none twice.
|
|
228
|
-
*/
|
|
229
|
-
hydrateFields(meta, fields, dto) {
|
|
230
|
-
const row = dto;
|
|
231
|
-
for (const [key, kind] of fields) {
|
|
232
|
-
const value = row[key];
|
|
233
|
-
if (value != null) {
|
|
234
|
-
row[key] = decodeColumn(value, kind);
|
|
235
|
-
}
|
|
236
|
-
}
|
|
237
|
-
// A tally read inside the statement comes back as its driver reads a COUNT, which on some is text.
|
|
238
|
-
const counts = row[COUNT_RESULT_KEY];
|
|
239
|
-
if (isRecord(counts)) {
|
|
240
|
-
for (const relKey in counts) {
|
|
241
|
-
counts[relKey] = Number(counts[relKey]);
|
|
242
|
-
}
|
|
243
|
-
}
|
|
244
|
-
// The value is read before the relation's target is resolved: a query that populated nothing
|
|
245
|
-
// still walks every relation the entity declares, and `rel.entity()` is a call per row per
|
|
246
|
-
// relation that only the populated ones need.
|
|
247
|
-
for (const key in meta.relations) {
|
|
248
|
-
const value = row[key];
|
|
249
|
-
const rel = meta.relations[key];
|
|
250
|
-
if (!value || !rel)
|
|
251
|
-
continue;
|
|
252
|
-
const relEntity = rel.entity();
|
|
253
|
-
if (isRecord(value)) {
|
|
254
|
-
const relMeta = getMeta(relEntity);
|
|
255
|
-
if (value[relMeta.ids[0]] == null) {
|
|
256
|
-
delete row[key];
|
|
257
|
-
}
|
|
258
|
-
else {
|
|
259
|
-
this.hydrateFields(relMeta, this.dialect.hydratableFields(relEntity), value);
|
|
260
|
-
}
|
|
261
|
-
}
|
|
262
|
-
else {
|
|
263
|
-
// A to-many's rows, as flat as a statement's own.
|
|
264
|
-
const rows = Array.isArray(value) ? value : JSON.parse(String(value));
|
|
265
|
-
row[key] = rows.map(this.rowReader(relEntity));
|
|
266
|
-
}
|
|
267
|
-
}
|
|
268
|
-
}
|
|
269
219
|
/**
|
|
270
220
|
* Runs a statement whose one row carries a {@link AGGREGATE_VALUE_ALIAS} column. `Number` because `COUNT(*)` is BIGINT and
|
|
271
221
|
* a caller supplying their own `types` replaces the decoding the pools do at the wire, and reads a `NULL`
|
|
@@ -282,17 +232,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
|
|
|
282
232
|
return this.runCount((ctx) => this.dialect.estimatedCount(ctx, entity));
|
|
283
233
|
}
|
|
284
234
|
async internalAggregate(entity, q, opts) {
|
|
285
|
-
|
|
286
|
-
const hydratable = this.dialect.hydratableAggregates(entity, q);
|
|
287
|
-
for (const row of rows) {
|
|
288
|
-
const cells = row;
|
|
289
|
-
for (const [alias, kind] of hydratable) {
|
|
290
|
-
if (cells[alias] != null) {
|
|
291
|
-
cells[alias] = decodeColumn(cells[alias], kind);
|
|
292
|
-
}
|
|
293
|
-
}
|
|
294
|
-
}
|
|
295
|
-
return rows;
|
|
235
|
+
return this.readRows((ctx) => this.dialect.aggregate(ctx, entity, q, opts));
|
|
296
236
|
}
|
|
297
237
|
async internalInsertMany(entity, rows) {
|
|
298
238
|
const meta = getMeta(entity);
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import type { SelectTerm } from '../dialect/abstractSqlDialect.js';
|
|
2
|
+
import type { RawRow } from '../type/index.js';
|
|
3
|
+
/**
|
|
4
|
+
* How each row of one statement becomes the entity's, from the terms its SQL was written with: its dotted
|
|
5
|
+
* columns nested, a joined row kept only where its key is, a to-many's rows read by their own terms, and each
|
|
6
|
+
* value the driver leaves to the field decoded. Resolved once per statement, so a row pays for no discovery.
|
|
7
|
+
*/
|
|
8
|
+
export declare function rowReader<T>(terms: readonly SelectTerm[]): (row: RawRow) => T;
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
import { DECODERS } from '../dialect/hydrateColumn.js';
|
|
2
|
+
import { isRecord } from '../util/index.js';
|
|
3
|
+
const TOP = [];
|
|
4
|
+
const slotAt = (path) => ({ parent: path.slice(0, -1), key: path[path.length - 1] });
|
|
5
|
+
/**
|
|
6
|
+
* How each row of one statement becomes the entity's, from the terms its SQL was written with: its dotted
|
|
7
|
+
* columns nested, a joined row kept only where its key is, a to-many's rows read by their own terms, and each
|
|
8
|
+
* value the driver leaves to the field decoded. Resolved once per statement, so a row pays for no discovery.
|
|
9
|
+
*/
|
|
10
|
+
export function rowReader(terms) {
|
|
11
|
+
const dotted = new Map();
|
|
12
|
+
const joined = [];
|
|
13
|
+
const mapped = [];
|
|
14
|
+
for (const { key, kind, kinds, rows, joinedKey } of terms) {
|
|
15
|
+
for (const [field, fieldKind] of kinds ?? []) {
|
|
16
|
+
mapped.push({ parent: TOP, key: field, map: DECODERS[fieldKind] });
|
|
17
|
+
}
|
|
18
|
+
if (key === undefined) {
|
|
19
|
+
continue;
|
|
20
|
+
}
|
|
21
|
+
const path = key.split('.');
|
|
22
|
+
const slot = slotAt(path);
|
|
23
|
+
if (path.length > 1) {
|
|
24
|
+
dotted.set(key, path);
|
|
25
|
+
if (joinedKey) {
|
|
26
|
+
joined.push({ ...slotAt(slot.parent), idKey: slot.key });
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
if (rows) {
|
|
30
|
+
const read = rowReader(rows);
|
|
31
|
+
mapped.push({ ...slot, map: (value) => (Array.isArray(value) ? value : JSON.parse(String(value))).map(read) });
|
|
32
|
+
}
|
|
33
|
+
if (kind) {
|
|
34
|
+
mapped.push({ ...slot, map: DECODERS[kind] });
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
const [firstDotted] = dotted.keys();
|
|
38
|
+
return (raw) => {
|
|
39
|
+
// All of a row's columns are flat or none is: SQL Server's `FOR JSON` nests a related row itself.
|
|
40
|
+
const row = firstDotted !== undefined && firstDotted in raw ? nest(raw, dotted) : raw;
|
|
41
|
+
for (const { parent, key, idKey } of joined) {
|
|
42
|
+
const holder = holderAt(row, parent);
|
|
43
|
+
const joinedRow = holder?.[key];
|
|
44
|
+
if (holder && isRecord(joinedRow) && joinedRow[idKey] == null) {
|
|
45
|
+
delete holder[key];
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
for (const { parent, key, map } of mapped) {
|
|
49
|
+
const holder = holderAt(row, parent);
|
|
50
|
+
const value = holder?.[key];
|
|
51
|
+
if (holder && value != null) {
|
|
52
|
+
holder[key] = map(value);
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
// A raw row becomes the entity here, as a parsed JSON value does: its shape is what the statement selected.
|
|
56
|
+
return row;
|
|
57
|
+
};
|
|
58
|
+
}
|
|
59
|
+
/** `row` with its dotted columns nested under the paths `dotted` names. */
|
|
60
|
+
function nest(row, dotted) {
|
|
61
|
+
const nested = {};
|
|
62
|
+
for (const column in row) {
|
|
63
|
+
const path = dotted.get(column);
|
|
64
|
+
if (!path) {
|
|
65
|
+
nested[column] = row[column];
|
|
66
|
+
continue;
|
|
67
|
+
}
|
|
68
|
+
let target = nested;
|
|
69
|
+
for (let i = 0; i < path.length - 1; i++) {
|
|
70
|
+
const next = target[path[i]];
|
|
71
|
+
target = isRecord(next) ? next : (target[path[i]] = {});
|
|
72
|
+
}
|
|
73
|
+
target[path[path.length - 1]] = row[column];
|
|
74
|
+
}
|
|
75
|
+
return nested;
|
|
76
|
+
}
|
|
77
|
+
/** The object at `path` in `row`, `row` itself for an empty one, if every step to it is one. */
|
|
78
|
+
function holderAt(row, path) {
|
|
79
|
+
let target = row;
|
|
80
|
+
for (const step of path) {
|
|
81
|
+
const next = target[step];
|
|
82
|
+
if (!isRecord(next)) {
|
|
83
|
+
return undefined;
|
|
84
|
+
}
|
|
85
|
+
target = next;
|
|
86
|
+
}
|
|
87
|
+
return target;
|
|
88
|
+
}
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { AbstractSqlDialect, type DerivedRelation, type RelationRows } from '../dialect/abstractSqlDialect.js';
|
|
1
|
+
import { AbstractSqlDialect, type DerivedRelation, type RelationRows, type SelectTerm } from '../dialect/abstractSqlDialect.js';
|
|
2
2
|
import { type JsonAccessMode, 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 } from '../type/index.js';
|
|
4
4
|
/** What SQLite and the engines derived from it have. */
|
|
@@ -43,7 +43,7 @@ export declare class SqliteDialect extends AbstractSqlDialect {
|
|
|
43
43
|
/** SQLite's own spelling of no limit. */
|
|
44
44
|
protected readonly unboundedLimit = "-1";
|
|
45
45
|
/** `json_group_array` of each row's object, ordered by the sort terms carried out beside them. */
|
|
46
|
-
protected appendRelationArray(ctx: QueryContext, rows: RelationRows):
|
|
46
|
+
protected appendRelationArray(ctx: QueryContext, rows: RelationRows): readonly SelectTerm[];
|
|
47
47
|
/**
|
|
48
48
|
* `json_object` of each key and its column. A row wider than one call takes inserts the rest into it,
|
|
49
49
|
* addressing each key as one path segment.
|
|
@@ -137,8 +137,9 @@ export class SqliteDialect extends AbstractSqlDialect {
|
|
|
137
137
|
unboundedLimit = '-1';
|
|
138
138
|
/** `json_group_array` of each row's object, ordered by the sort terms carried out beside them. */
|
|
139
139
|
appendRelationArray(ctx, rows) {
|
|
140
|
-
const { from, pairs, order } = this.derivedRelation(ctx, rows);
|
|
140
|
+
const { terms, from, pairs, order } = this.derivedRelation(ctx, rows);
|
|
141
141
|
ctx.append(`(SELECT json_group_array(${this.jsonObject(pairs)}${order ? ` ORDER BY ${order}` : ''}) FROM ${from})`);
|
|
142
|
+
return terms;
|
|
142
143
|
}
|
|
143
144
|
/**
|
|
144
145
|
* `json_object` of each key and its column. A row wider than one call takes inserts the rest into it,
|
|
@@ -22,17 +22,8 @@ export declare function getFieldCallbackValue(val: OnFieldCallback): string | nu
|
|
|
22
22
|
export declare function getSoftDeleteValue(field: FieldOptions): string | number | bigint | boolean | Date | import("../type/utility.js").JsonBrand | QueryRaw | readonly number[] | readonly import("../type/utility.js").JsonBrand[] | Uint8Array<ArrayBufferLike>;
|
|
23
23
|
/** Fills each field `callbackKey` generates on `payload` in place, where the caller left it unset. */
|
|
24
24
|
export declare function fillOnFields<E, R extends EntityData<E> | UpdatePayload<E>>(meta: EntityMeta<E>, payload: R | R[], callbackKey: CallbackKey): R[];
|
|
25
|
-
/**
|
|
26
|
-
|
|
27
|
-
* `payload`'s keys are read, so any keys-bearing object works (an entity, an update payload,
|
|
28
|
-
* or `meta.relations` itself to enumerate every cascadable relation).
|
|
29
|
-
*/
|
|
30
|
-
export declare function filterPersistableRelationKeys<E>(meta: EntityMeta<E>, payload: object, action: CascadeType): RelationKey<E>[];
|
|
31
|
-
/**
|
|
32
|
-
* Whether deleting this entity has to delete anything else, which is the reason a delete resolves the
|
|
33
|
-
* matching ids before issuing anything: a child is reached through the ids of its parent.
|
|
34
|
-
*/
|
|
35
|
-
export declare function cascadesOnDelete<E>(meta: EntityMeta<E>): boolean;
|
|
25
|
+
/** The relations a write cascades `action` to, in declaration order. */
|
|
26
|
+
export declare function cascadingRelations<E>(meta: EntityMeta<E>, action: CascadeType): RelationKey<E>[];
|
|
36
27
|
export declare function isCascadable(action: CascadeType, configuration?: boolean | CascadeType): boolean;
|
|
37
28
|
/**
|
|
38
29
|
* Whether `q` carries an ordering or a page, so a write has to settle its rows with a read and name
|
|
@@ -50,7 +50,7 @@ export function getInsertFieldKeys(meta, payloads) {
|
|
|
50
50
|
for (const record of payloads) {
|
|
51
51
|
addInsertFieldKeys(meta, record, seen, keys);
|
|
52
52
|
}
|
|
53
|
-
return [...keys, ...
|
|
53
|
+
return [...keys, ...filledKeys(meta, 'onInsert').filter((key) => !seen.has(key))];
|
|
54
54
|
}
|
|
55
55
|
export function getFieldCallbackValue(val) {
|
|
56
56
|
return typeof val === 'function' ? val() : val;
|
|
@@ -65,9 +65,7 @@ export function getSoftDeleteValue(field) {
|
|
|
65
65
|
/** Fills each field `callbackKey` generates on `payload` in place, where the caller left it unset. */
|
|
66
66
|
export function fillOnFields(meta, payload, callbackKey) {
|
|
67
67
|
const payloads = Array.isArray(payload) ? payload : [payload];
|
|
68
|
-
|
|
69
|
-
// are values a caller meant, and a falsy one was silently never filled.
|
|
70
|
-
const keys = fieldKeys(meta, (field) => field[callbackKey] !== undefined);
|
|
68
|
+
const keys = filledKeys(meta, callbackKey);
|
|
71
69
|
if (keys.length === 0) {
|
|
72
70
|
return payloads;
|
|
73
71
|
}
|
|
@@ -80,24 +78,13 @@ export function fillOnFields(meta, payload, callbackKey) {
|
|
|
80
78
|
}
|
|
81
79
|
return payloads;
|
|
82
80
|
}
|
|
83
|
-
/**
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
* or `meta.relations` itself to enumerate every cascadable relation).
|
|
87
|
-
*/
|
|
88
|
-
export function filterPersistableRelationKeys(meta, payload, action) {
|
|
89
|
-
const keys = getKeys(payload);
|
|
90
|
-
return keys.filter((key) => {
|
|
91
|
-
const relOpts = meta.relations[key];
|
|
92
|
-
return relOpts && isCascadable(action, relOpts.cascade);
|
|
93
|
-
});
|
|
81
|
+
/** The fields `callbackKey` fills where the caller left them unset. By presence: `onInsert: 0` is a value meant. */
|
|
82
|
+
function filledKeys(meta, callbackKey) {
|
|
83
|
+
return fieldKeys(meta, (field) => field[callbackKey] !== undefined);
|
|
94
84
|
}
|
|
95
|
-
/**
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
*/
|
|
99
|
-
export function cascadesOnDelete(meta) {
|
|
100
|
-
return filterPersistableRelationKeys(meta, meta.relations, 'delete').length > 0;
|
|
85
|
+
/** The relations a write cascades `action` to, in declaration order. */
|
|
86
|
+
export function cascadingRelations(meta, action) {
|
|
87
|
+
return getKeys(meta.relations).filter((key) => isCascadable(action, meta.relations[key]?.cascade));
|
|
101
88
|
}
|
|
102
89
|
export function isCascadable(action, configuration) {
|
|
103
90
|
if (typeof configuration === 'boolean') {
|
package/dist/util/query.util.js
CHANGED
|
@@ -65,28 +65,36 @@ export function assertWhere(meta, where) {
|
|
|
65
65
|
* as no condition at all: `{ email: maybeEmail }` reading any row. `what` names the map in the error.
|
|
66
66
|
*/
|
|
67
67
|
export function assertNoUndefined(map, what) {
|
|
68
|
-
const path = undefinedPath(map
|
|
68
|
+
const path = undefinedPath(map);
|
|
69
69
|
if (path) {
|
|
70
70
|
throw new UqlUsageError(`${what} holds undefined at '${path.join('.')}': leave the key out not to filter by it, or name null`);
|
|
71
71
|
}
|
|
72
72
|
}
|
|
73
|
-
/**
|
|
74
|
-
|
|
73
|
+
/**
|
|
74
|
+
* The path to the first `undefined` in a plain object or array, read depth first. Built on the way back out,
|
|
75
|
+
* so a filter holding none, which is every one that runs, allocates nothing.
|
|
76
|
+
*/
|
|
77
|
+
function undefinedPath(value) {
|
|
75
78
|
if (value === undefined) {
|
|
76
|
-
return
|
|
79
|
+
return [];
|
|
77
80
|
}
|
|
78
|
-
if (!
|
|
81
|
+
if (!isWalkable(value)) {
|
|
79
82
|
return undefined;
|
|
80
83
|
}
|
|
81
|
-
for (const
|
|
82
|
-
const found = undefinedPath(
|
|
84
|
+
for (const key in value) {
|
|
85
|
+
const found = undefinedPath(value[key]);
|
|
83
86
|
if (found) {
|
|
87
|
+
found.unshift(key);
|
|
84
88
|
return found;
|
|
85
89
|
}
|
|
86
90
|
}
|
|
87
91
|
return undefined;
|
|
88
92
|
}
|
|
89
|
-
|
|
93
|
+
/** An array or a plain object: what a filter nests, and not a `Date`, a `raw` or a driver's value. */
|
|
94
|
+
function isWalkable(value) {
|
|
95
|
+
if (Array.isArray(value)) {
|
|
96
|
+
return true;
|
|
97
|
+
}
|
|
90
98
|
if (!isRecord(value)) {
|
|
91
99
|
return false;
|
|
92
100
|
}
|
package/dist/util/sql.util.d.ts
CHANGED
|
@@ -1,10 +1,5 @@
|
|
|
1
1
|
import type { InsertIdSource, QueryUpdateResult, RawRow } from '../type/index.js';
|
|
2
2
|
import type { PrimaryKey } from '../type/utility.js';
|
|
3
|
-
/** A row with its dotted columns nested, by paths read once off its statement's first row: the row itself where none is. */
|
|
4
|
-
export declare function unflatObject<T extends object>(row: RawRow, attrsPaths: Record<string, string[]>): T;
|
|
5
|
-
export declare function obtainAttrsPaths<T extends object>(row: T): {
|
|
6
|
-
[k: string]: string[];
|
|
7
|
-
};
|
|
8
3
|
/**
|
|
9
4
|
* A name behind its namespace, or bare where there is none: the one place the two are joined, so a
|
|
10
5
|
* table's key, its statement operand and its escaped form cannot spell it differently. Never the
|
package/dist/util/sql.util.js
CHANGED
|
@@ -1,38 +1,5 @@
|
|
|
1
1
|
import { OWNED_PREFIX } from '../dialect/aliases.js';
|
|
2
|
-
import { hasKeys, isRecord } from './object.util.js';
|
|
3
2
|
import { fnv1a } from './string.util.js';
|
|
4
|
-
/** A row with its dotted columns nested, by paths read once off its statement's first row: the row itself where none is. */
|
|
5
|
-
export function unflatObject(row, attrsPaths) {
|
|
6
|
-
if (!hasKeys(attrsPaths)) {
|
|
7
|
-
return row;
|
|
8
|
-
}
|
|
9
|
-
const dto = {};
|
|
10
|
-
for (const col in row) {
|
|
11
|
-
const attrPath = attrsPaths[col];
|
|
12
|
-
if (attrPath) {
|
|
13
|
-
let target = dto;
|
|
14
|
-
for (let i = 0; i < attrPath.length - 1; i++) {
|
|
15
|
-
const seg = attrPath[i];
|
|
16
|
-
const next = target[seg];
|
|
17
|
-
target = isRecord(next) ? next : (target[seg] = {});
|
|
18
|
-
}
|
|
19
|
-
target[attrPath[attrPath.length - 1]] = row[col];
|
|
20
|
-
}
|
|
21
|
-
else {
|
|
22
|
-
dto[col] = row[col];
|
|
23
|
-
}
|
|
24
|
-
}
|
|
25
|
-
return dto;
|
|
26
|
-
}
|
|
27
|
-
export function obtainAttrsPaths(row) {
|
|
28
|
-
const paths = {};
|
|
29
|
-
for (const col in row) {
|
|
30
|
-
if (col.includes('.')) {
|
|
31
|
-
paths[col] = col.split('.');
|
|
32
|
-
}
|
|
33
|
-
}
|
|
34
|
-
return paths;
|
|
35
|
-
}
|
|
36
3
|
/**
|
|
37
4
|
* A name behind its namespace, or bare where there is none: the one place the two are joined, so a
|
|
38
5
|
* table's key, its statement operand and its escaped form cannot spell it differently. Never the
|
|
@@ -7,9 +7,10 @@ import type { RawRow } from '../type/index.js';
|
|
|
7
7
|
*/
|
|
8
8
|
export declare function decodeWideNumber(value: string | bigint): number | string;
|
|
9
9
|
/**
|
|
10
|
-
* {@link decodeWideNumber} over every `bigint` cell of a row,
|
|
11
|
-
* one (`bun:sql`, `mariadb`, and every SQLite driver but D1). In
|
|
12
|
-
* object, and a copy per row cost more than the decode it carried.
|
|
10
|
+
* {@link decodeWideNumber} over every `bigint` cell of a row, an array's elements included, for the
|
|
11
|
+
* drivers that hand a BIGINT back as one (`bun:sql`, `mariadb`, and every SQLite driver but D1). In
|
|
12
|
+
* place: the row is the driver's fresh object, and a copy per row cost more than the decode it carried.
|
|
13
|
+
* One argument, so it maps rows as is.
|
|
13
14
|
*/
|
|
14
15
|
export declare function decodeBigInts(row: RawRow): RawRow;
|
|
15
16
|
/** {@link decodeBigInts}, keeping the cells `exact` names: what MongoDB reads a `BigInt` field into. */
|
package/dist/util/wideNumber.js
CHANGED
|
@@ -9,9 +9,10 @@ export function decodeWideNumber(value) {
|
|
|
9
9
|
return Math.abs(decoded) <= Number.MAX_SAFE_INTEGER ? decoded : String(value);
|
|
10
10
|
}
|
|
11
11
|
/**
|
|
12
|
-
* {@link decodeWideNumber} over every `bigint` cell of a row,
|
|
13
|
-
* one (`bun:sql`, `mariadb`, and every SQLite driver but D1). In
|
|
14
|
-
* object, and a copy per row cost more than the decode it carried.
|
|
12
|
+
* {@link decodeWideNumber} over every `bigint` cell of a row, an array's elements included, for the
|
|
13
|
+
* drivers that hand a BIGINT back as one (`bun:sql`, `mariadb`, and every SQLite driver but D1). In
|
|
14
|
+
* place: the row is the driver's fresh object, and a copy per row cost more than the decode it carried.
|
|
15
|
+
* One argument, so it maps rows as is.
|
|
15
16
|
*/
|
|
16
17
|
export function decodeBigInts(row) {
|
|
17
18
|
return decodeBigIntsExcept(row, () => false);
|
|
@@ -19,10 +20,20 @@ export function decodeBigInts(row) {
|
|
|
19
20
|
/** {@link decodeBigInts}, keeping the cells `exact` names: what MongoDB reads a `BigInt` field into. */
|
|
20
21
|
export function decodeBigIntsExcept(row, exact) {
|
|
21
22
|
for (const key in row) {
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
row[key] = decodeWideNumber(value);
|
|
23
|
+
if (!exact(key)) {
|
|
24
|
+
row[key] = decodeBigIntsIn(row[key]);
|
|
25
25
|
}
|
|
26
26
|
}
|
|
27
27
|
return row;
|
|
28
28
|
}
|
|
29
|
+
function decodeBigIntsIn(value) {
|
|
30
|
+
if (typeof value === 'bigint') {
|
|
31
|
+
return decodeWideNumber(value);
|
|
32
|
+
}
|
|
33
|
+
if (Array.isArray(value)) {
|
|
34
|
+
value.forEach((element, index) => {
|
|
35
|
+
value[index] = decodeBigIntsIn(element);
|
|
36
|
+
});
|
|
37
|
+
}
|
|
38
|
+
return value;
|
|
39
|
+
}
|
package/package.json
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "uql-orm",
|
|
3
3
|
"homepage": "https://uql-orm.dev",
|
|
4
|
-
"description": "JSON-native TypeScript ORM for Bun, Browsers, Edge,
|
|
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.100.
|
|
6
|
+
"version": "0.100.3",
|
|
7
7
|
"type": "module",
|
|
8
8
|
"engines": {
|
|
9
9
|
"node": ">=24"
|
|
@@ -196,7 +196,6 @@
|
|
|
196
196
|
"d1",
|
|
197
197
|
"cloudflare",
|
|
198
198
|
"bun",
|
|
199
|
-
"deno",
|
|
200
199
|
"node",
|
|
201
200
|
"nodejs",
|
|
202
201
|
"edge",
|
package/skills/uql-orm/SKILL.md
CHANGED
|
@@ -20,7 +20,7 @@ The full docs are Markdown at https://uql-orm.dev/llms.txt, one page per URL. Re
|
|
|
20
20
|
npm install uql-orm pg # or mysql2, mariadb, better-sqlite3, mongodb, @libsql/client, ...
|
|
21
21
|
```
|
|
22
22
|
|
|
23
|
-
ESM only. Node 24+, Bun
|
|
23
|
+
ESM only. Node 24+, Bun or an edge runtime, TypeScript 5.7+. Decorators are the TC39 standard: never enable `experimentalDecorators` or `emitDecoratorMetadata`, never import `reflect-metadata`. In `tsconfig.json`, `module` is `nodenext` or `preserve`, and `target` is a dated one (`es2022`+), not `esnext`.
|
|
24
24
|
|
|
25
25
|
Node's type stripping runs no decorators: on Node, add `tsx` (`npm i -D tsx`), which `uql-migrate` imports `uql.config.ts` through. Next.js compiles TC39 decorators only through a `babel.config.json` with `@babel/plugin-proposal-decorators` at `version: '2023-11'`. A bundle that minifies class names (Next's server build, or any bundler's `minify`) needs `@Entity({ name: 'todo' })`: a table name is the class name otherwise.
|
|
26
26
|
|
|
@@ -118,7 +118,7 @@ const users = await pool.findMany(User, {
|
|
|
118
118
|
- 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 `raw` of the field's type (`{ total: { $inc: newRow.amount } }` in a trigger). JSON fields take `$set`, `$unset`, `$push`, `$pull`.
|
|
119
119
|
- `$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.
|
|
120
120
|
- `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`.
|
|
121
|
-
- ``pool.all`SELECT ... WHERE id = ${id}` `` runs a `SELECT` and ``pool.run`...` `` a write: 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)`). `raw` builds a fragment to embed anywhere a value or field goes, or to compose a statement, and `raw.join(fragments, ' AND ')` joins them. `raw.text(sql)` runs trusted SQL held in a string, binding nothing: never build it from user input. Migrations write ``querier.run`CREATE TABLE ...` ``. `raw` is a tag, so ``raw(`...`)`` does not compile. A field read off `refs(Entity)` carries its type: on its own as a value it fits only a field of that type.
|
|
121
|
+
- ``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)`). `raw` builds a fragment to embed anywhere a value or field goes, or to compose a statement, and `raw.join(fragments, ' AND ')` joins them. `raw.text(sql)` runs trusted SQL held in a string, binding nothing: never build it from user input. Migrations write ``querier.run`CREATE TABLE ...` ``. `raw` is a tag, so ``raw(`...`)`` does not compile. A field read off `refs(Entity)` carries its type: on its own as a value it fits only a field of that type.
|
|
122
122
|
|
|
123
123
|
## Connections and transactions
|
|
124
124
|
|