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
|
@@ -9,6 +9,11 @@ import { type TransactionScope } from './transaction.js';
|
|
|
9
9
|
*/
|
|
10
10
|
/** What an upsert reports of a row: the value a driver answers for a lone key, or the key the read back names. */
|
|
11
11
|
export type UpsertedId<E> = PrimaryKey | WrittenId<E>;
|
|
12
|
+
/** An `UPDATE` and a `DELETE` of one statement each, reporting the rows they wrote with the fields `keys` names. */
|
|
13
|
+
export type WritesReturning = {
|
|
14
|
+
update<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts: QueryOptions, keys: readonly FieldKey<E>[]): Promise<E[]>;
|
|
15
|
+
delete<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts: QueryOptions, keys: readonly FieldKey<E>[]): Promise<E[]>;
|
|
16
|
+
};
|
|
12
17
|
/** Base class for all database queriers. */
|
|
13
18
|
export declare abstract class AbstractQuerier implements Querier {
|
|
14
19
|
#private;
|
|
@@ -114,10 +119,10 @@ export declare abstract class AbstractQuerier implements Querier {
|
|
|
114
119
|
* transaction with only the fields it lists.
|
|
115
120
|
*/
|
|
116
121
|
private writeReturning;
|
|
117
|
-
/** The rows `q` matches with the fields `keys` names and their keys, through `afterLoad` as a read's are. */
|
|
118
|
-
private readReturning;
|
|
119
122
|
/** The rows `ids` names, in their order, each with only the fields `keys` names. */
|
|
120
123
|
private readWritten;
|
|
124
|
+
/** What `returning` reports of `rows`: each through `afterLoad`, as a read's are, then only the fields `keys` names. */
|
|
125
|
+
private returned;
|
|
121
126
|
/**
|
|
122
127
|
* Writes `rows` and their relations: the to-ones they hold the keys of first, so each row inserts
|
|
123
128
|
* pointing at its own, then the rows, then their children by the keys the rows got. An insert, and the
|
|
@@ -129,15 +134,25 @@ export declare abstract class AbstractQuerier implements Querier {
|
|
|
129
134
|
updateOneById<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true>(entity: Type<E>, id: EntityId<E>, payload: UpdateWrite<E>, opts?: QueryOptions & WriteOptions<E, S, V>): Promise<ReturningResult<S, number, QueryFindResult<E, S, V> | undefined>>;
|
|
130
135
|
updateMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true>(entity: Type<E>, q: QuerySearch<E>, payload: UpdateWrite<E>, opts?: QueryOptions & WriteOptions<E, S, V>): Promise<ReturningResult<S, number, QueryFindResult<E, S, V>[]>>;
|
|
131
136
|
/**
|
|
132
|
-
* The number of rows the update changed, or the rows `returning` reads back:
|
|
133
|
-
*
|
|
137
|
+
* The number of rows the update changed, or the rows `returning` reads back: settled first and held, so the
|
|
138
|
+
* update writes those rows and no other, whatever a payload or another writer does to what `$where` reads.
|
|
134
139
|
*/
|
|
135
140
|
private updateWhere;
|
|
136
|
-
/**
|
|
141
|
+
/**
|
|
142
|
+
* An update of one statement reporting the rows it wrote, between the update hooks. A payload writing no
|
|
143
|
+
* column writes nothing, so the rows it names are read instead.
|
|
144
|
+
*/
|
|
145
|
+
private updateReturning;
|
|
146
|
+
/**
|
|
147
|
+
* Updates the rows `q` matches, or the ones `settled` already names, between the update hooks, atomically
|
|
148
|
+
* where the payload writes relations too.
|
|
149
|
+
*/
|
|
137
150
|
private updateMatching;
|
|
138
151
|
/**
|
|
139
152
|
* The write every update runs, matching the version `lockKey` names where one is being held. Only a
|
|
140
|
-
* restore passes none: it writes no content, so there is no update of anyone's to lose.
|
|
153
|
+
* restore passes none: it writes no content, so there is no update of anyone's to lose. A versioned row is
|
|
154
|
+
* named by its one id in `q`, so the lock path writes `q` and ignores `settled`. Elsewhere `settled` names
|
|
155
|
+
* the rows to write, in batches the engine's bind budget allows.
|
|
141
156
|
*/
|
|
142
157
|
private updateRows;
|
|
143
158
|
/**
|
|
@@ -147,6 +162,8 @@ export declare abstract class AbstractQuerier implements Querier {
|
|
|
147
162
|
* still costs one statement. Best effort by nature - the row can change again while we ask.
|
|
148
163
|
*/
|
|
149
164
|
private throwStaleVersion;
|
|
165
|
+
/** What every update does to its row before its statement: writes the to-ones it holds, fills and guards it. */
|
|
166
|
+
private prepareUpdate;
|
|
150
167
|
/** The UPDATE, skipped where the payload writes no column, reporting `unwritten` instead. */
|
|
151
168
|
private updateColumns;
|
|
152
169
|
/**
|
|
@@ -155,14 +172,22 @@ export declare abstract class AbstractQuerier implements Querier {
|
|
|
155
172
|
*/
|
|
156
173
|
protected settlesWrite<E extends object>(entity: Type<E>, q: QuerySearch<E>): boolean;
|
|
157
174
|
/**
|
|
158
|
-
* `write` over `rows` in lists of as many as one statement names by `keyCount` keys, summing what each changed
|
|
159
|
-
*
|
|
175
|
+
* `write` over `rows` in lists of as many as one statement names by `keyCount` keys, summing what each changed,
|
|
176
|
+
* inside its caller's transaction, so a write split to fit the engine still lands whole.
|
|
160
177
|
*/
|
|
161
|
-
|
|
178
|
+
private writeBatches;
|
|
162
179
|
/** Runs a write of several statements as one: in a transaction of its own, or the one already open. */
|
|
163
180
|
protected atomically<T>(write: () => Promise<T>): Promise<T>;
|
|
164
|
-
/** The ids `q` matches, in its own order and page. */
|
|
165
|
-
|
|
181
|
+
/** The ids `q` matches, in its own order and page, held as {@link readForWrite} holds them. */
|
|
182
|
+
private settleIds;
|
|
183
|
+
/**
|
|
184
|
+
* The rows a write reads before it writes, held until the open transaction ends where the engine has row
|
|
185
|
+
* locks, so a racing writer waits for the commit; outside a transaction a lock would hold nothing. Elsewhere
|
|
186
|
+
* the transaction is the guard: libSQL and Turso take the write lock at `BEGIN`, SQLite and MongoDB fail the racer.
|
|
187
|
+
*/
|
|
188
|
+
private readForWrite;
|
|
189
|
+
/** How the engine writes rows and reports them in one statement, or `undefined` where a write reads them first. */
|
|
190
|
+
protected get writesReturning(): WritesReturning | undefined;
|
|
166
191
|
/** Runs one UPDATE over `q`, which names its rows by id wherever {@link updateMany} settled them. */
|
|
167
192
|
protected abstract internalUpdateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
|
|
168
193
|
restoreOneById<E extends object>(entity: Type<E>, id: EntityId<E>): Promise<number>;
|
|
@@ -177,7 +202,8 @@ export declare abstract class AbstractQuerier implements Querier {
|
|
|
177
202
|
/**
|
|
178
203
|
* An upsert as a read, then writes: the rows the conflict names are read through the filters, those found update
|
|
179
204
|
* as `updateMany` does and the rest insert, so either branch writes its relations and a guarded row stays its
|
|
180
|
-
* tenant's. A row inserted concurrently fails on its key. See
|
|
205
|
+
* tenant's. A found row is held until the write, and a row inserted concurrently fails on its key. See
|
|
206
|
+
* architecture/security-filter-writes.md.
|
|
181
207
|
*/
|
|
182
208
|
private readThenUpsert;
|
|
183
209
|
/** Upserts `payload`, answering each row's key in payload order where the engine reports every one. */
|
|
@@ -188,8 +214,15 @@ export declare abstract class AbstractQuerier implements Querier {
|
|
|
188
214
|
$entity: Type<E>;
|
|
189
215
|
}, opts?: QueryOptions): Promise<number>;
|
|
190
216
|
deleteMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions & WriteOptions<E, S, V>): Promise<ReturningResult<S, number, QueryFindResult<E, S, V>[]>>;
|
|
191
|
-
/** The number of rows deleted, or the rows `returning` reads as they were
|
|
217
|
+
/** The number of rows deleted, or the rows `returning` reads as they were: held before the delete, which deletes those. */
|
|
192
218
|
private deleteWhere;
|
|
219
|
+
/** Whether an update is its one statement over `q`: no version to lock, relation to write or page to settle first. */
|
|
220
|
+
private updatesByFilter;
|
|
221
|
+
/** Whether a delete is its one statement over `q`: no hook, cascade or page needs its rows read first. */
|
|
222
|
+
private deletesByFilter;
|
|
223
|
+
/** Whether a delete hook listens on the entity, so a delete reads each row whole to hand it over. */
|
|
224
|
+
private watchesDelete;
|
|
225
|
+
/** Deletes the rows `q` matches, or the ones `read` holds, reading them first where a hook, cascade or page needs them. */
|
|
193
226
|
private deleteRows;
|
|
194
227
|
/** Runs one DELETE (or soft-delete stamp) over `q`, which names its rows by id wherever {@link deleteMany} settled them. */
|
|
195
228
|
protected abstract internalDeleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
|
|
@@ -210,7 +243,8 @@ export declare abstract class AbstractQuerier implements Querier {
|
|
|
210
243
|
private insertChildren;
|
|
211
244
|
/**
|
|
212
245
|
* Makes `value` the children of each parent `ids` names, which it owns: the rows it lists are saved,
|
|
213
|
-
* keeping what each does not write, and the parent's other children (a junction's other links) go.
|
|
246
|
+
* keeping what each does not write, and the parent's other children (a junction's other links) go. Inside
|
|
247
|
+
* the transaction the update holds.
|
|
214
248
|
*/
|
|
215
249
|
private replaceChildren;
|
|
216
250
|
/** A many-to-many's links: the targets are saved, the parent's links to any other go, and the missing ones are added. */
|
|
@@ -281,9 +315,10 @@ export declare abstract class AbstractQuerier implements Querier {
|
|
|
281
315
|
*/
|
|
282
316
|
private emitLoaded;
|
|
283
317
|
/**
|
|
284
|
-
* The ids of `rows`, read through the filters by the columns an upsert matches them on
|
|
285
|
-
* statement that could not report them in payload order, or before a
|
|
286
|
-
* read row matches, or that two do, keeps `undefined`: a missing id is honest
|
|
318
|
+
* The ids of `rows`, read through the filters by the columns an upsert matches them on, and held as
|
|
319
|
+
* {@link readForWrite} holds them: after a statement that could not report them in payload order, or before a
|
|
320
|
+
* guarded upsert. A row that no read row matches, or that two do, keeps `undefined`: a missing id is honest
|
|
321
|
+
* where a guessed one is not.
|
|
287
322
|
*/
|
|
288
323
|
protected idsByConflict<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, rows: EntityData<E>[]): Promise<(WrittenId<E> | undefined)[]>;
|
|
289
324
|
/**
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { getMeta, idOf, namesKey, relationOf } from '../entity/index.js';
|
|
2
|
+
import { SAVEPOINT_PREFIX } from '../dialect/aliases.js';
|
|
2
3
|
import { namesRows } from '../dialect/operators.js';
|
|
3
4
|
import { parseQueryLock } from '../type/index.js';
|
|
4
5
|
import { childrenExcept, childrenOf, chunk, clone, entityName, fillOnFields, filterFieldKeys, forEachRequestedRelation, getKeys, hasKeys, getRelationRequestSummary, guardWrite, idOnlyQuery, keyJoins, keySet, isPagedQuery, isScalarId, LoggerWrapper, normalizeScalarFieldSelection, parentJoins, pointAt, queryLoggerFor, parseRelationAtKey, parseRelationQueryValue, rowKey, runHooks, securityConditions, someKey, targetJoins, whereEach, whereIds, whereKeysIn, whereWith, withoutSoftDeleteFilter, cascadingRelations, holdsForeignKey, } from '../util/index.js';
|
|
@@ -139,6 +140,10 @@ function returnedKeys(meta, returning) {
|
|
|
139
140
|
function deletableRows(opts) {
|
|
140
141
|
return opts?.hardDelete ? { ...opts, filters: withoutSoftDeleteFilter(opts.filters) } : opts;
|
|
141
142
|
}
|
|
143
|
+
/** Whether an update of `row` writes a column, its `onUpdate` fills included: one that writes none sends nothing. */
|
|
144
|
+
function writesColumns(meta, row) {
|
|
145
|
+
return filterFieldKeys(meta, row, 'onUpdate').length > 0;
|
|
146
|
+
}
|
|
142
147
|
/** `row` with only the fields `keys` names. */
|
|
143
148
|
function pickFields(row, keys) {
|
|
144
149
|
const picked = {};
|
|
@@ -160,8 +165,6 @@ function ownedRelations(meta) {
|
|
|
160
165
|
function listedRows(value) {
|
|
161
166
|
return value == null ? [] : Array.isArray(value) ? value : [value];
|
|
162
167
|
}
|
|
163
|
-
/** What a savepoint the querier names is called, its depth appended. */
|
|
164
|
-
const SAVEPOINT_PREFIX = '_uql_sp';
|
|
165
168
|
/** Runs the callbacks a transaction gathered for its commit, in the order they were registered. */
|
|
166
169
|
async function runCallbacks(callbacks) {
|
|
167
170
|
for (const callback of callbacks) {
|
|
@@ -376,15 +379,6 @@ export class AbstractQuerier {
|
|
|
376
379
|
const keys = returnedKeys(getMeta(entity), opts?.returning);
|
|
377
380
|
return keys ? this.atomically(async () => this.readWritten(entity, await write(), keys)) : write();
|
|
378
381
|
}
|
|
379
|
-
/** The rows `q` matches with the fields `keys` names and their keys, through `afterLoad` as a read's are. */
|
|
380
|
-
async readReturning(entity, q, keys, opts) {
|
|
381
|
-
const $select = keySet([...keys, ...getMeta(entity).ids]);
|
|
382
|
-
const rows = await this.internalFindMany(entity, { ...q, $select }, opts);
|
|
383
|
-
if (this.hasHook(entity, 'afterLoad')) {
|
|
384
|
-
await this.emitHook(entity, 'afterLoad', rows);
|
|
385
|
-
}
|
|
386
|
-
return rows;
|
|
387
|
-
}
|
|
388
382
|
/** The rows `ids` names, in their order, each with only the fields `keys` names. */
|
|
389
383
|
async readWritten(entity, ids, keys, opts) {
|
|
390
384
|
const meta = getMeta(entity);
|
|
@@ -397,15 +391,19 @@ export class AbstractQuerier {
|
|
|
397
391
|
}
|
|
398
392
|
// The rows this write wrote, whatever a filter says of them: a soft-deleted one inserted is still written.
|
|
399
393
|
const read = { ...opts, filters: withoutSoftDeleteFilter(opts?.filters) };
|
|
394
|
+
const $select = keySet([...keys, ...meta.ids]);
|
|
400
395
|
const rows = [];
|
|
401
396
|
for (const batch of chunk(known, this.dialect.keyListCapacity(meta.ids.length))) {
|
|
402
|
-
rows.push(...(await this.
|
|
397
|
+
rows.push(...(await this.internalFindMany(entity, { $select, $where: whereIds(meta, batch) }, read)));
|
|
403
398
|
}
|
|
404
399
|
const byKey = new Map(rows.map((row) => [rowKey(row, meta.ids), row]));
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
400
|
+
const ordered = known.flatMap((id) => byKey.get(rowKey(whereIds(meta, id), meta.ids)) ?? []);
|
|
401
|
+
return this.returned(entity, ordered, keys);
|
|
402
|
+
}
|
|
403
|
+
/** What `returning` reports of `rows`: each through `afterLoad`, as a read's are, then only the fields `keys` names. */
|
|
404
|
+
async returned(entity, rows, keys) {
|
|
405
|
+
await this.emitLoaded(entity, rows, undefined);
|
|
406
|
+
return rows.map((row) => pickFields(row, keys));
|
|
409
407
|
}
|
|
410
408
|
/**
|
|
411
409
|
* Writes `rows` and their relations: the to-ones they hold the keys of first, so each row inserts
|
|
@@ -429,8 +427,8 @@ export class AbstractQuerier {
|
|
|
429
427
|
return this.updateWhere(entity, q, payload, opts);
|
|
430
428
|
}
|
|
431
429
|
/**
|
|
432
|
-
* The number of rows the update changed, or the rows `returning` reads back:
|
|
433
|
-
*
|
|
430
|
+
* The number of rows the update changed, or the rows `returning` reads back: settled first and held, so the
|
|
431
|
+
* update writes those rows and no other, whatever a payload or another writer does to what `$where` reads.
|
|
434
432
|
*/
|
|
435
433
|
async updateWhere(entity, q, payload, opts) {
|
|
436
434
|
assertNamesRows(entity, 'updateMany', q, opts);
|
|
@@ -440,27 +438,49 @@ export class AbstractQuerier {
|
|
|
440
438
|
if (!keys) {
|
|
441
439
|
return this.updateMatching(entity, q, payload, opts);
|
|
442
440
|
}
|
|
441
|
+
const { writesReturning } = this;
|
|
442
|
+
if (writesReturning && this.updatesByFilter(entity, q, payload)) {
|
|
443
|
+
return this.updateReturning(writesReturning, entity, q, payload, rest, keys);
|
|
444
|
+
}
|
|
443
445
|
return this.atomically(async () => {
|
|
444
446
|
const ids = await this.settleIds(entity, q, rest);
|
|
445
|
-
await this.updateMatching(entity, q, payload, rest);
|
|
447
|
+
await this.updateMatching(entity, q, payload, rest, ids);
|
|
446
448
|
return this.readWritten(entity, ids, keys, rest);
|
|
447
449
|
});
|
|
448
450
|
}
|
|
449
|
-
/**
|
|
450
|
-
|
|
451
|
+
/**
|
|
452
|
+
* An update of one statement reporting the rows it wrote, between the update hooks. A payload writing no
|
|
453
|
+
* column writes nothing, so the rows it names are read instead.
|
|
454
|
+
*/
|
|
455
|
+
updateReturning(writes, entity, q, payload, opts, keys) {
|
|
456
|
+
const meta = getMeta(entity);
|
|
457
|
+
const read = [...keys, ...meta.ids];
|
|
458
|
+
return this.hooked(entity, 'Update', [payload], async ([row]) => {
|
|
459
|
+
await this.prepareUpdate(entity, row);
|
|
460
|
+
const rows = writesColumns(meta, row)
|
|
461
|
+
? await writes.update(entity, q, row, opts, read)
|
|
462
|
+
: await this.internalFindMany(entity, { ...q, $select: keySet(read) }, opts);
|
|
463
|
+
return this.returned(entity, rows, keys);
|
|
464
|
+
});
|
|
465
|
+
}
|
|
466
|
+
/**
|
|
467
|
+
* Updates the rows `q` matches, or the ones `settled` already names, between the update hooks, atomically
|
|
468
|
+
* where the payload writes relations too.
|
|
469
|
+
*/
|
|
470
|
+
updateMatching(entity, q, payload, opts, settled) {
|
|
451
471
|
const meta = getMeta(entity);
|
|
452
|
-
const update = () => this.hooked(entity, 'Update', [payload], ([row]) => this.updateRows(entity, q, row, opts, meta.version));
|
|
472
|
+
const update = () => this.hooked(entity, 'Update', [payload], ([row]) => this.updateRows(entity, q, row, opts, meta.version, settled));
|
|
453
473
|
return writesRelations(meta, [payload]) ? this.atomically(update) : update();
|
|
454
474
|
}
|
|
455
475
|
/**
|
|
456
476
|
* The write every update runs, matching the version `lockKey` names where one is being held. Only a
|
|
457
|
-
* restore passes none: it writes no content, so there is no update of anyone's to lose.
|
|
477
|
+
* restore passes none: it writes no content, so there is no update of anyone's to lose. A versioned row is
|
|
478
|
+
* named by its one id in `q`, so the lock path writes `q` and ignores `settled`. Elsewhere `settled` names
|
|
479
|
+
* the rows to write, in batches the engine's bind budget allows.
|
|
458
480
|
*/
|
|
459
|
-
async updateRows(entity, q, row, opts, lockKey) {
|
|
481
|
+
async updateRows(entity, q, row, opts, lockKey, settled) {
|
|
460
482
|
const meta = getMeta(entity);
|
|
461
|
-
await this.
|
|
462
|
-
fillOnFields(meta, [row], 'onUpdate');
|
|
463
|
-
guardWrite(meta, [row], 'update');
|
|
483
|
+
await this.prepareUpdate(entity, row);
|
|
464
484
|
const relKeys = ownedRelations(meta).filter((key) => Object.hasOwn(row, key));
|
|
465
485
|
const settles = !!relKeys.length || this.settlesWrite(entity, q);
|
|
466
486
|
if (lockKey) {
|
|
@@ -470,18 +490,20 @@ export class AbstractQuerier {
|
|
|
470
490
|
const changes = await this.updateColumns(entity, lock.q, row, opts, 0);
|
|
471
491
|
return changes || this.throwStaleVersion(entity, lockKey, q, lock.expected, opts);
|
|
472
492
|
}
|
|
473
|
-
if (!settles) {
|
|
493
|
+
if (!settles && !settled) {
|
|
474
494
|
return this.updateColumns(entity, q, row, opts, 0);
|
|
475
495
|
}
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
496
|
+
return this.atomically(async () => {
|
|
497
|
+
const ids = settled ?? (await this.settleIds(entity, q, opts));
|
|
498
|
+
if (!ids.length) {
|
|
499
|
+
return 0;
|
|
500
|
+
}
|
|
501
|
+
const changes = await this.writeBatches(ids, meta.ids.length, (batch) => this.updateColumns(entity, { $where: whereIds(meta, batch) }, row, opts, batch.length));
|
|
502
|
+
for (const relKey of relKeys) {
|
|
503
|
+
await this.replaceChildren(entity, relKey, ids, row[relKey]);
|
|
504
|
+
}
|
|
505
|
+
return changes;
|
|
506
|
+
});
|
|
485
507
|
}
|
|
486
508
|
/**
|
|
487
509
|
* Why an update matched no row. The filter named the row by its id, so reading by that id alone
|
|
@@ -500,10 +522,16 @@ export class AbstractQuerier {
|
|
|
500
522
|
: `'${entityName(meta)}' moved on: the payload carries '${key}' ${String(expected)}, the row is at ${String(actual)}`;
|
|
501
523
|
throw new UqlOptimisticLockError(message, expected, actual);
|
|
502
524
|
}
|
|
525
|
+
/** What every update does to its row before its statement: writes the to-ones it holds, fills and guards it. */
|
|
526
|
+
async prepareUpdate(entity, row) {
|
|
527
|
+
const meta = getMeta(entity);
|
|
528
|
+
await this.writeHeldReferences(entity, [row]);
|
|
529
|
+
fillOnFields(meta, [row], 'onUpdate');
|
|
530
|
+
guardWrite(meta, [row], 'update');
|
|
531
|
+
}
|
|
503
532
|
/** The UPDATE, skipped where the payload writes no column, reporting `unwritten` instead. */
|
|
504
533
|
async updateColumns(entity, q, row, opts, unwritten) {
|
|
505
|
-
|
|
506
|
-
return writes ? this.internalUpdateMany(entity, q, row, opts) : unwritten;
|
|
534
|
+
return writesColumns(getMeta(entity), row) ? this.internalUpdateMany(entity, q, row, opts) : unwritten;
|
|
507
535
|
}
|
|
508
536
|
/**
|
|
509
537
|
* Whether a write has to name the rows `q` matches by their ids: no engine pages or orders an update or
|
|
@@ -514,30 +542,39 @@ export class AbstractQuerier {
|
|
|
514
542
|
return isPagedQuery(q) || (!dialect.features.correlatedWrites && dialect.constrainsRelations(entity, q.$where));
|
|
515
543
|
}
|
|
516
544
|
/**
|
|
517
|
-
* `write` over `rows` in lists of as many as one statement names by `keyCount` keys, summing what each changed
|
|
518
|
-
*
|
|
545
|
+
* `write` over `rows` in lists of as many as one statement names by `keyCount` keys, summing what each changed,
|
|
546
|
+
* inside its caller's transaction, so a write split to fit the engine still lands whole.
|
|
519
547
|
*/
|
|
520
548
|
async writeBatches(rows, keyCount, write) {
|
|
521
|
-
|
|
522
|
-
const
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
}
|
|
527
|
-
return changes;
|
|
528
|
-
};
|
|
529
|
-
return batches.length > 1 ? this.atomically(each) : each();
|
|
549
|
+
let changes = 0;
|
|
550
|
+
for (const batch of chunk(rows, this.dialect.keyListCapacity(keyCount))) {
|
|
551
|
+
changes += await write(batch);
|
|
552
|
+
}
|
|
553
|
+
return changes;
|
|
530
554
|
}
|
|
531
555
|
/** Runs a write of several statements as one: in a transaction of its own, or the one already open. */
|
|
532
556
|
atomically(write) {
|
|
533
557
|
return this.scopeHere() ? write() : this.transaction(write);
|
|
534
558
|
}
|
|
535
|
-
/** The ids `q` matches, in its own order and page. */
|
|
559
|
+
/** The ids `q` matches, in its own order and page, held as {@link readForWrite} holds them. */
|
|
536
560
|
async settleIds(entity, q, opts) {
|
|
537
561
|
const meta = getMeta(entity);
|
|
538
|
-
const rows = await this.
|
|
562
|
+
const rows = await this.readForWrite(entity, idOnlyQuery(meta, q), opts);
|
|
539
563
|
return rows.map((row) => idOf(meta, row));
|
|
540
564
|
}
|
|
565
|
+
/**
|
|
566
|
+
* The rows a write reads before it writes, held until the open transaction ends where the engine has row
|
|
567
|
+
* locks, so a racing writer waits for the commit; outside a transaction a lock would hold nothing. Elsewhere
|
|
568
|
+
* the transaction is the guard: libSQL and Turso take the write lock at `BEGIN`, SQLite and MongoDB fail the racer.
|
|
569
|
+
*/
|
|
570
|
+
readForWrite(entity, q, opts) {
|
|
571
|
+
const held = this.dialect.features.rowLocks && this.scopeHere() ? { ...q, $lock: true } : q;
|
|
572
|
+
return this.internalFindMany(entity, held, opts);
|
|
573
|
+
}
|
|
574
|
+
/** How the engine writes rows and reports them in one statement, or `undefined` where a write reads them first. */
|
|
575
|
+
get writesReturning() {
|
|
576
|
+
return undefined;
|
|
577
|
+
}
|
|
541
578
|
async restoreOneById(entity, id) {
|
|
542
579
|
assertIdValue(entity, id);
|
|
543
580
|
return this.restoreMany(entity, { $where: whereIds(getMeta(entity), id) });
|
|
@@ -580,7 +617,8 @@ export class AbstractQuerier {
|
|
|
580
617
|
/**
|
|
581
618
|
* An upsert as a read, then writes: the rows the conflict names are read through the filters, those found update
|
|
582
619
|
* as `updateMany` does and the rest insert, so either branch writes its relations and a guarded row stays its
|
|
583
|
-
* tenant's. A row inserted concurrently fails on its key. See
|
|
620
|
+
* tenant's. A found row is held until the write, and a row inserted concurrently fails on its key. See
|
|
621
|
+
* architecture/security-filter-writes.md.
|
|
584
622
|
*/
|
|
585
623
|
async readThenUpsert(entity, conflictPaths, rows, update) {
|
|
586
624
|
const meta = getMeta(entity);
|
|
@@ -589,7 +627,7 @@ export class AbstractQuerier {
|
|
|
589
627
|
return [];
|
|
590
628
|
}
|
|
591
629
|
const keys = getKeys(conflictPaths);
|
|
592
|
-
|
|
630
|
+
return this.atomically(async () => {
|
|
593
631
|
const ids = await this.idsByConflict(entity, conflictPaths, rows);
|
|
594
632
|
for (const [index, row] of rows.entries()) {
|
|
595
633
|
// An empty `update` leaves a found row as it is, as `DO NOTHING` does.
|
|
@@ -606,10 +644,7 @@ export class AbstractQuerier {
|
|
|
606
644
|
}
|
|
607
645
|
// A found row's key is adopted by the caller; an inserted one carries the key its insert wrote.
|
|
608
646
|
return ids;
|
|
609
|
-
};
|
|
610
|
-
return rows.length > 1 || writesRelations(meta, [...rows, ...(update ? [update] : [])])
|
|
611
|
-
? this.atomically(write)
|
|
612
|
-
: write();
|
|
647
|
+
});
|
|
613
648
|
}
|
|
614
649
|
async deleteOneById(entity, id, opts) {
|
|
615
650
|
assertIdValue(entity, id);
|
|
@@ -620,7 +655,7 @@ export class AbstractQuerier {
|
|
|
620
655
|
const [entity, q, opts] = entityArgs(args);
|
|
621
656
|
return this.deleteWhere(entity, q, opts);
|
|
622
657
|
}
|
|
623
|
-
/** The number of rows deleted, or the rows `returning` reads as they were
|
|
658
|
+
/** The number of rows deleted, or the rows `returning` reads as they were: held before the delete, which deletes those. */
|
|
624
659
|
async deleteWhere(entity, q, opts) {
|
|
625
660
|
assertNamesRows(entity, 'deleteMany', q, opts);
|
|
626
661
|
const meta = getMeta(entity);
|
|
@@ -629,27 +664,51 @@ export class AbstractQuerier {
|
|
|
629
664
|
if (!keys) {
|
|
630
665
|
return this.deleteRows(entity, q, opts);
|
|
631
666
|
}
|
|
667
|
+
const read = [...keys, ...meta.ids];
|
|
668
|
+
// A soft delete stamps the rows, which a `RETURNING` would report stamped rather than as they were.
|
|
669
|
+
const { writesReturning } = this;
|
|
670
|
+
if (writesReturning && (rest.hardDelete || !meta.softDelete) && this.deletesByFilter(entity, q)) {
|
|
671
|
+
return this.returned(entity, await writesReturning.delete(entity, q, rest, read), keys);
|
|
672
|
+
}
|
|
673
|
+
// A delete hook receives whole rows; without one, only the keys `returning` names and the ids are read.
|
|
674
|
+
const $select = this.watchesDelete(entity) ? undefined : keySet(read);
|
|
632
675
|
return this.atomically(async () => {
|
|
633
|
-
const rows = await this.
|
|
634
|
-
|
|
635
|
-
|
|
676
|
+
const rows = await this.readForWrite(entity, { ...q, $select }, deletableRows(rest));
|
|
677
|
+
// `afterLoad` sees copies, as a read's rows, so a delete hook still gets each row as it was read.
|
|
678
|
+
const reported = await this.returned(entity, clone(rows), keys);
|
|
679
|
+
await this.deleteRows(entity, q, rest, rows);
|
|
680
|
+
return reported;
|
|
636
681
|
});
|
|
637
682
|
}
|
|
638
|
-
|
|
683
|
+
/** Whether an update is its one statement over `q`: no version to lock, relation to write or page to settle first. */
|
|
684
|
+
updatesByFilter(entity, q, payload) {
|
|
639
685
|
const meta = getMeta(entity);
|
|
640
|
-
|
|
641
|
-
|
|
642
|
-
|
|
686
|
+
return !meta.version && !writesRelations(meta, [payload]) && !this.settlesWrite(entity, q);
|
|
687
|
+
}
|
|
688
|
+
/** Whether a delete is its one statement over `q`: no hook, cascade or page needs its rows read first. */
|
|
689
|
+
deletesByFilter(entity, q) {
|
|
690
|
+
const meta = getMeta(entity);
|
|
691
|
+
return !this.watchesDelete(entity) && !cascadingRelations(meta, 'delete').length && !this.settlesWrite(entity, q);
|
|
692
|
+
}
|
|
693
|
+
/** Whether a delete hook listens on the entity, so a delete reads each row whole to hand it over. */
|
|
694
|
+
watchesDelete(entity) {
|
|
695
|
+
return this.hasHook(entity, 'beforeDelete') || this.hasHook(entity, 'afterDelete');
|
|
696
|
+
}
|
|
697
|
+
/** Deletes the rows `q` matches, or the ones `read` holds, reading them first where a hook, cascade or page needs them. */
|
|
698
|
+
async deleteRows(entity, q, opts, read) {
|
|
699
|
+
const meta = getMeta(entity);
|
|
700
|
+
if (!read && this.deletesByFilter(entity, q)) {
|
|
643
701
|
return this.internalDeleteMany(entity, q, opts);
|
|
644
702
|
}
|
|
645
|
-
const
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
|
|
652
|
-
|
|
703
|
+
const cascades = cascadingRelations(meta, 'delete').length > 0;
|
|
704
|
+
const watched = this.watchesDelete(entity);
|
|
705
|
+
return this.atomically(async () => {
|
|
706
|
+
// A hook receives the rows themselves; the ids read off them name the same rows a second read might not.
|
|
707
|
+
const doomed = read ?? (await this.readForWrite(entity, watched ? q : idOnlyQuery(meta, q), deletableRows(opts)));
|
|
708
|
+
if (!doomed.length) {
|
|
709
|
+
return 0;
|
|
710
|
+
}
|
|
711
|
+
const ids = doomed.map((row) => idOf(meta, row));
|
|
653
712
|
await this.emitHook(entity, 'beforeDelete', doomed);
|
|
654
713
|
const changes = await this.writeBatches(ids, meta.ids.length, async (batch) => {
|
|
655
714
|
// Children first: they hold the foreign key, which a schema without `ON DELETE CASCADE` enforces.
|
|
@@ -660,8 +719,7 @@ export class AbstractQuerier {
|
|
|
660
719
|
});
|
|
661
720
|
await this.emitHook(entity, 'afterDelete', doomed);
|
|
662
721
|
return changes;
|
|
663
|
-
};
|
|
664
|
-
return cascades ? this.atomically(remove) : remove();
|
|
722
|
+
});
|
|
665
723
|
}
|
|
666
724
|
async saveOne(entity, payload, opts) {
|
|
667
725
|
const [written] = await this.writeReturning(entity, () => this.saveIds(entity, [payload]), opts);
|
|
@@ -754,7 +812,8 @@ export class AbstractQuerier {
|
|
|
754
812
|
}
|
|
755
813
|
/**
|
|
756
814
|
* Makes `value` the children of each parent `ids` names, which it owns: the rows it lists are saved,
|
|
757
|
-
* keeping what each does not write, and the parent's other children (a junction's other links) go.
|
|
815
|
+
* keeping what each does not write, and the parent's other children (a junction's other links) go. Inside
|
|
816
|
+
* the transaction the update holds.
|
|
758
817
|
*/
|
|
759
818
|
async replaceChildren(entity, relKey, ids, value) {
|
|
760
819
|
const relOpts = relationOf(getMeta(entity), relKey);
|
|
@@ -1011,9 +1070,10 @@ export class AbstractQuerier {
|
|
|
1011
1070
|
await this.emitHook(entity, 'afterLoad', rows);
|
|
1012
1071
|
}
|
|
1013
1072
|
/**
|
|
1014
|
-
* The ids of `rows`, read through the filters by the columns an upsert matches them on
|
|
1015
|
-
* statement that could not report them in payload order, or before a
|
|
1016
|
-
* read row matches, or that two do, keeps `undefined`: a missing id is honest
|
|
1073
|
+
* The ids of `rows`, read through the filters by the columns an upsert matches them on, and held as
|
|
1074
|
+
* {@link readForWrite} holds them: after a statement that could not report them in payload order, or before a
|
|
1075
|
+
* guarded upsert. A row that no read row matches, or that two do, keeps `undefined`: a missing id is honest
|
|
1076
|
+
* where a guessed one is not.
|
|
1017
1077
|
*/
|
|
1018
1078
|
async idsByConflict(entity, conflictPaths, rows) {
|
|
1019
1079
|
const meta = getMeta(entity);
|
|
@@ -1024,7 +1084,7 @@ export class AbstractQuerier {
|
|
|
1024
1084
|
const found = [];
|
|
1025
1085
|
for (const batch of chunk(distinct, this.dialect.keyListCapacity(keys.length))) {
|
|
1026
1086
|
const q = { $select: keySet([...meta.ids, ...keys]), $where: whereKeysIn(keys, batch) };
|
|
1027
|
-
found.push(await this.
|
|
1087
|
+
found.push(await this.readForWrite(entity, q, { filters: withoutSoftDeleteFilter(undefined) }));
|
|
1028
1088
|
}
|
|
1029
1089
|
const byConflict = new Map();
|
|
1030
1090
|
for (const row of found.flat()) {
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import type { AbstractSqlDialect } from '../dialect/index.js';
|
|
2
2
|
import type { EntityData, ExtraOptions, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryPage, QueryGroupMap, QueryOptions, QuerySearch, QueryUpdateResult, RawRow, SavepointCommand, SqlQuerier, SqlStatement, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
|
|
3
3
|
import type { BuildUpdateResultPayload } from '../util/sql.util.js';
|
|
4
|
-
import { AbstractQuerier, type UpsertedId } from './abstractQuerier.js';
|
|
4
|
+
import { AbstractQuerier, type UpsertedId, type WritesReturning } from './abstractQuerier.js';
|
|
5
5
|
export declare abstract class AbstractSqlQuerier extends AbstractQuerier implements SqlQuerier {
|
|
6
6
|
#private;
|
|
7
7
|
readonly dialect: AbstractSqlDialect;
|
|
@@ -83,6 +83,10 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
|
|
|
83
83
|
protected internalAggregate<E extends object, G extends QueryGroupMap<E>, A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): Promise<QueryAggregateResult<E, G, A>[]>;
|
|
84
84
|
internalInsertMany<E extends object>(entity: Type<E>, rows: EntityData<E>[]): Promise<void>;
|
|
85
85
|
internalUpdateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
|
|
86
|
+
/** `UPDATE` and `DELETE` with a `RETURNING` read as a read's rows are, where the engine has it. */
|
|
87
|
+
protected get writesReturning(): WritesReturning | undefined;
|
|
88
|
+
/** The rows the write `build` renders reports, `RETURNING` the fields `keys` names. */
|
|
89
|
+
private reportedRows;
|
|
86
90
|
protected internalUpsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E[], update?: UpdatePayload<E>): Promise<(UpsertedId<E> | undefined)[] | undefined>;
|
|
87
91
|
private runUpsert;
|
|
88
92
|
protected internalDeleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
|
|
@@ -278,6 +278,21 @@ export class AbstractSqlQuerier extends AbstractQuerier {
|
|
|
278
278
|
const { changes = 0 } = await this.exec((ctx) => this.dialect.update(ctx, entity, q, payload, opts));
|
|
279
279
|
return changes;
|
|
280
280
|
}
|
|
281
|
+
/** `UPDATE` and `DELETE` with a `RETURNING` read as a read's rows are, where the engine has it. */
|
|
282
|
+
get writesReturning() {
|
|
283
|
+
return this.dialect.features.writeReturning ? this.#returningWrites : undefined;
|
|
284
|
+
}
|
|
285
|
+
#returningWrites = {
|
|
286
|
+
update: (entity, q, payload, opts, keys) => this.reportedRows(entity, keys, (ctx) => this.dialect.update(ctx, entity, q, payload, opts)),
|
|
287
|
+
delete: (entity, q, opts, keys) => this.reportedRows(entity, keys, (ctx) => this.dialect.delete(ctx, entity, q, opts)),
|
|
288
|
+
};
|
|
289
|
+
/** The rows the write `build` renders reports, `RETURNING` the fields `keys` names. */
|
|
290
|
+
reportedRows(entity, keys, build) {
|
|
291
|
+
return this.readRows((ctx) => {
|
|
292
|
+
build(ctx);
|
|
293
|
+
return this.dialect.returning(ctx, entity, keys);
|
|
294
|
+
});
|
|
295
|
+
}
|
|
281
296
|
async internalUpsertMany(entity, conflictPaths, payload, update) {
|
|
282
297
|
if (!payload.length) {
|
|
283
298
|
return [];
|
|
@@ -364,7 +379,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
|
|
|
364
379
|
* case it overrides all three. The bookkeeping around them stays above, written once.
|
|
365
380
|
*/
|
|
366
381
|
async internalBegin(opts) {
|
|
367
|
-
for (const sql of this.dialect.getBeginTransactionStatements(opts
|
|
382
|
+
for (const sql of this.dialect.getBeginTransactionStatements(opts)) {
|
|
368
383
|
await this.runTransactionCommand(sql);
|
|
369
384
|
}
|
|
370
385
|
}
|
|
@@ -1,5 +1,4 @@
|
|
|
1
|
-
|
|
2
|
-
const CURSOR_ALIAS = '_uql_cursor';
|
|
1
|
+
import { CURSOR_ALIAS } from '../dialect/aliases.js';
|
|
3
2
|
/** Rows per round trip, matching `pg-query-stream`'s own default so both paths read the same. */
|
|
4
3
|
const FETCH_SIZE = 100;
|
|
5
4
|
let cursorSeq = 0;
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type { ExtraOptions, RawRow } from '../type/index.js';
|
|
1
|
+
import type { ExtraOptions, RawRow, TransactionOptions } from '../type/index.js';
|
|
2
2
|
import { AbstractSqliteQuerier, type SqliteBindValue } from './abstractSqliteQuerier.js';
|
|
3
3
|
import type { SqliteDialect } from './sqliteDialect.js';
|
|
4
4
|
export type HranaInValue = SqliteBindValue | ArrayBuffer | Date;
|
|
@@ -47,7 +47,7 @@ export declare class HranaQuerier extends AbstractSqliteQuerier {
|
|
|
47
47
|
rows: RawRow[];
|
|
48
48
|
changes: number;
|
|
49
49
|
}>;
|
|
50
|
-
protected internalBegin(): Promise<void>;
|
|
50
|
+
protected internalBegin(opts?: TransactionOptions): Promise<void>;
|
|
51
51
|
/**
|
|
52
52
|
* Both drop the handle before the call, not after: one that outlived a failed commit would carry
|
|
53
53
|
* every later statement into a transaction the server may already have ended.
|
|
@@ -21,8 +21,8 @@ export class HranaQuerier extends AbstractSqliteQuerier {
|
|
|
21
21
|
const res = await (this.tx ?? this.client).execute({ sql: query, args: values });
|
|
22
22
|
return { rows: res.rows, changes: res.rowsAffected };
|
|
23
23
|
}
|
|
24
|
-
async internalBegin() {
|
|
25
|
-
this.tx = await this.client.transaction('write');
|
|
24
|
+
async internalBegin(opts) {
|
|
25
|
+
this.tx = await this.client.transaction(opts?.readOnly ? 'read' : 'write');
|
|
26
26
|
}
|
|
27
27
|
/**
|
|
28
28
|
* Both drop the handle before the call, not after: one that outlived a failed commit would carry
|
|
@@ -31,9 +31,15 @@ export function extendSqlite(db, extensions = []) {
|
|
|
31
31
|
db.function?.('regexp', { deterministic: true }, regexp);
|
|
32
32
|
return db;
|
|
33
33
|
}
|
|
34
|
-
|
|
34
|
+
const CASELESS_FLAG = '(?i)';
|
|
35
|
+
/** `value REGEXP pattern`: NULL where the value is, as an operator answers; a leading `(?i)` folds case, as other engines read it. */
|
|
35
36
|
function regexp(pattern, value) {
|
|
36
|
-
|
|
37
|
+
if (value === null) {
|
|
38
|
+
return null;
|
|
39
|
+
}
|
|
40
|
+
const source = String(pattern);
|
|
41
|
+
const caseless = source.startsWith(CASELESS_FLAG);
|
|
42
|
+
return Number(new RegExp(caseless ? source.slice(CASELESS_FLAG.length) : source, caseless ? 'i' : '').test(String(value)));
|
|
37
43
|
}
|
|
38
44
|
/** A pool for a database file opened in this process, configured the same way whichever driver's {@link createDb} opens it. */
|
|
39
45
|
export class AbstractLocalSqliteQuerierPool extends AbstractSharedHandleQuerierPool {
|