uql-orm 0.94.0 → 0.95.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/README.md +3 -0
- package/dist/browser/uql-browser.min.js +2 -2
- package/dist/browser/uql-browser.min.js.map +4 -4
- package/dist/d1/d1Querier.d.ts +2 -0
- package/dist/d1/d1Querier.js +4 -0
- package/dist/dialect/abstractSqlDialect.d.ts +6 -6
- package/dist/dialect/abstractSqlDialect.js +8 -8
- package/dist/dialect/mergeSqlDialect.d.ts +2 -2
- package/dist/dialect/mergeSqlDialect.js +1 -1
- package/dist/dialect/mysqlLikeSqlDialect.d.ts +2 -2
- package/dist/dialect/mysqlLikeSqlDialect.js +4 -7
- package/dist/dialect/pgLikeSqlDialect.d.ts +2 -2
- package/dist/dialect/pgLikeSqlDialect.js +4 -4
- package/dist/dialect/queryContext.d.ts +0 -2
- package/dist/dialect/queryContext.js +0 -6
- package/dist/maria/mariadbQuerier.d.ts +4 -0
- package/dist/maria/mariadbQuerier.js +14 -2
- package/dist/migrate/cli-config.d.ts +9 -0
- package/dist/migrate/cli-config.js +24 -6
- package/dist/migrate/cli.js +9 -2
- package/dist/migrate/ddl/defaultSql.js +3 -1
- package/dist/mongo/mongodbQuerier.d.ts +3 -3
- package/dist/mongo/mongodbQuerier.js +2 -3
- package/dist/mssql/mssqlDialect.d.ts +3 -3
- package/dist/mssql/mssqlDialect.js +3 -3
- package/dist/pglite/pgliteQuerier.d.ts +2 -2
- package/dist/querier/abstractQuerier.d.ts +22 -17
- package/dist/querier/abstractQuerier.js +72 -46
- package/dist/querier/abstractSqlQuerier.d.ts +3 -3
- package/dist/querier/abstractSqlQuerier.js +39 -33
- package/dist/schema/sqlExpression.d.ts +2 -2
- package/dist/schema/sqlExpression.js +2 -2
- package/dist/type/dialect.d.ts +3 -3
- package/dist/type/entity.d.ts +2 -2
- package/dist/type/query.d.ts +1 -12
- package/dist/type/universalQuerier.d.ts +9 -5
- package/dist/util/object.util.js +3 -0
- package/dist/util/sql.util.d.ts +0 -2
- package/dist/util/sql.util.js +0 -6
- package/dist/util/triggerWrite.d.ts +3 -3
- package/dist/util/triggerWrite.js +2 -2
- package/package.json +1 -1
- package/skills/uql-orm/SKILL.md +6 -3
|
@@ -1,18 +1,36 @@
|
|
|
1
1
|
import { stat } from 'node:fs/promises';
|
|
2
|
+
import { createRequire } from 'node:module';
|
|
2
3
|
import { resolve } from 'node:path';
|
|
3
4
|
import { pathToFileURL } from 'node:url';
|
|
4
5
|
import { UqlUsageError } from '../util/uqlError.js';
|
|
5
6
|
/**
|
|
6
|
-
*
|
|
7
|
-
*
|
|
7
|
+
* The project's own `tsx/esm/api` where Node must load a TypeScript config: Node's type stripping runs
|
|
8
|
+
* no decorators, and Bun and Deno transform them natively. uql bundles no transpiler, so the project's
|
|
9
|
+
* loader reads the project's `tsconfig.json`.
|
|
8
10
|
*/
|
|
11
|
+
export function tsxApiFor(path, versions) {
|
|
12
|
+
if (!/\.[mc]?ts$/.test(path) || versions.bun || versions.deno) {
|
|
13
|
+
return undefined;
|
|
14
|
+
}
|
|
15
|
+
try {
|
|
16
|
+
return createRequire(path).resolve('tsx/esm/api');
|
|
17
|
+
}
|
|
18
|
+
catch {
|
|
19
|
+
return undefined;
|
|
20
|
+
}
|
|
21
|
+
}
|
|
9
22
|
async function importConfig(path) {
|
|
10
|
-
const
|
|
23
|
+
const url = pathToFileURL(path).href;
|
|
24
|
+
const tsxApi = tsxApiFor(path, process.versions);
|
|
25
|
+
const loading = tsxApi
|
|
26
|
+
? import(pathToFileURL(tsxApi).href).then((api) => api.tsImport(url, import.meta.url))
|
|
27
|
+
: import(url);
|
|
28
|
+
const mod = await loading.catch((cause) => {
|
|
11
29
|
throw new UqlUsageError(`Could not import ${path}: ${cause?.message}\n` +
|
|
12
30
|
'If it reaches entity classes, their decorators need a runtime that transforms TypeScript, not ' +
|
|
13
|
-
'just one that strips its types. Run the CLI with `bun`, or
|
|
14
|
-
'
|
|
15
|
-
})
|
|
31
|
+
'just one that strips its types. Run the CLI with `bun`, or install tsx (`npm i -D tsx`), which the ' +
|
|
32
|
+
'CLI uses when it finds one. See https://uql-orm.dev/migrations#running-the-cli', { cause });
|
|
33
|
+
});
|
|
16
34
|
return mod.default ?? mod;
|
|
17
35
|
}
|
|
18
36
|
export async function loadConfig(customPath) {
|
package/dist/migrate/cli.js
CHANGED
|
@@ -31,7 +31,8 @@ export async function main(args = process.argv.slice(2)) {
|
|
|
31
31
|
const options = {
|
|
32
32
|
migrationsPath: config.migrationsPath ?? './migrations',
|
|
33
33
|
tableName: config.tableName,
|
|
34
|
-
|
|
34
|
+
// A dry run's stdout is the SQL alone, so what the migrator notes on the way goes to stderr.
|
|
35
|
+
logger: filteredArgs.includes('--dry-run') ? console.error : console.log,
|
|
35
36
|
entities: config.entities,
|
|
36
37
|
defaultForeignKeyAction: config.defaultForeignKeyAction,
|
|
37
38
|
};
|
|
@@ -199,9 +200,15 @@ export async function runSync(migrator, args, config) {
|
|
|
199
200
|
const safe = !args.includes('--unsafe');
|
|
200
201
|
const options = { force, safe, drop: !safe };
|
|
201
202
|
// Ahead of the warning and the run: `--dry-run` means the same whatever else was asked for, `--force` included.
|
|
203
|
+
// Its stdout is only SQL, so it can be appended to a migration file another tool applies.
|
|
202
204
|
if (args.includes('--dry-run')) {
|
|
203
205
|
const statements = await migrator.planSync(options);
|
|
204
|
-
|
|
206
|
+
if (statements.length) {
|
|
207
|
+
console.log(statements.join('\n'));
|
|
208
|
+
}
|
|
209
|
+
else {
|
|
210
|
+
console.error('Schema is already in sync.');
|
|
211
|
+
}
|
|
205
212
|
return;
|
|
206
213
|
}
|
|
207
214
|
if (force) {
|
|
@@ -47,8 +47,10 @@ export function sameDefault(desired, current, dialect) {
|
|
|
47
47
|
reprinted(formatDefaultValue(want, dialect)) === reprinted(formatDefaultValue(have, dialect)));
|
|
48
48
|
}
|
|
49
49
|
// Compared as text, since a catalogue may report a number either as a number or as its text.
|
|
50
|
-
return writtenDefault(want) === writtenDefault(have);
|
|
50
|
+
return writtenDefault(storedLiteral(want, dialect)) === writtenDefault(storedLiteral(have, dialect));
|
|
51
51
|
}
|
|
52
|
+
/** A boolean as the engine stores it: the integer {@link defaultLiteral} writes where it has no booleans. */
|
|
53
|
+
const storedLiteral = (value, dialect) => typeof value === 'boolean' && dialect.booleanLiteral !== 'native' ? Number(value) : value;
|
|
52
54
|
/**
|
|
53
55
|
* Reads SQL a catalogue reports as the value uql exports that renders alike, so a declared `currentTimestamp`
|
|
54
56
|
* compares equal and `generate:from-db` writes it by name; any other SQL is kept as it is.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import type { Document, MongoClient } from 'mongodb';
|
|
2
2
|
import { AbstractQuerier } from '../querier/index.js';
|
|
3
|
-
import type { EntityData, ExtraOptions, PrimaryKey, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryPage, QueryGroupMap, QueryOptions, QuerySearch, TransactionOptions, Type, UpdatePayload
|
|
3
|
+
import type { EntityData, ExtraOptions, PrimaryKey, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryPage, QueryGroupMap, QueryOptions, QuerySearch, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
|
|
4
4
|
import type { MongoDialect } from './mongoDialect.js';
|
|
5
5
|
import type { MongoQuerier } from './mongoQuerier.js';
|
|
6
6
|
export declare class MongodbQuerier extends AbstractQuerier implements MongoQuerier {
|
|
@@ -61,12 +61,12 @@ export declare class MongodbQuerier extends AbstractQuerier implements MongoQuer
|
|
|
61
61
|
private upsertWithUpdate;
|
|
62
62
|
/** The id and whether it was created, read off the document a `findOneAndUpdate` upsert wrote. */
|
|
63
63
|
private upserted;
|
|
64
|
-
protected internalUpsertOne<E extends Document>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E,
|
|
64
|
+
protected internalUpsertOne<E extends Document>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E, update?: UpdatePayload<E>): Promise<{
|
|
65
65
|
ids: (PrimaryKey | undefined)[];
|
|
66
66
|
changes: number;
|
|
67
67
|
created: boolean;
|
|
68
68
|
}>;
|
|
69
|
-
protected internalUpsertMany<E extends Document>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E[],
|
|
69
|
+
protected internalUpsertMany<E extends Document>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E[], update?: UpdatePayload<E>): Promise<{
|
|
70
70
|
ids: (PrimaryKey | undefined)[];
|
|
71
71
|
changes: number;
|
|
72
72
|
} | {
|
|
@@ -188,7 +188,6 @@ export class MongodbQuerier extends AbstractQuerier {
|
|
|
188
188
|
for (let index = 0; index < rows.length; index++) {
|
|
189
189
|
rows[index][idKey] = ids[index];
|
|
190
190
|
}
|
|
191
|
-
await this.insertRelations(entity, rows);
|
|
192
191
|
});
|
|
193
192
|
}
|
|
194
193
|
async internalUpdateMany(entity, qm, payload, opts) {
|
|
@@ -241,7 +240,7 @@ export class MongodbQuerier extends AbstractQuerier {
|
|
|
241
240
|
// `updatedExisting` is false when a new document was inserted (upserted).
|
|
242
241
|
return { id, created: res.lastErrorObject?.['updatedExisting'] === false };
|
|
243
242
|
}
|
|
244
|
-
async internalUpsertOne(entity, conflictPaths, payload,
|
|
243
|
+
async internalUpsertOne(entity, conflictPaths, payload, update) {
|
|
245
244
|
refuseTriggers(entity);
|
|
246
245
|
if (update) {
|
|
247
246
|
const { id, created, changes } = await this.upsertWithUpdate(entity, conflictPaths, payload, update);
|
|
@@ -264,7 +263,7 @@ export class MongodbQuerier extends AbstractQuerier {
|
|
|
264
263
|
return { ids: [id], changes: id === undefined ? 0 : 1, created };
|
|
265
264
|
});
|
|
266
265
|
}
|
|
267
|
-
async internalUpsertMany(entity, conflictPaths, payload,
|
|
266
|
+
async internalUpsertMany(entity, conflictPaths, payload, update) {
|
|
268
267
|
refuseTriggers(entity);
|
|
269
268
|
if (update) {
|
|
270
269
|
const ids = [];
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { type RelationRows } from '../dialect/abstractSqlDialect.js';
|
|
2
2
|
import { type JsonAccessMode, type JsonSlot } from '../dialect/jsonSql.js';
|
|
3
3
|
import { MergeSqlDialect } from '../dialect/mergeSqlDialect.js';
|
|
4
|
-
import type { EntityMeta, FieldOptions, Query, QueryConflictPaths, QueryContext, QueryOptions, QueryPager, SqlDialectFeatures, SqlValues, TriggerRows, Type,
|
|
4
|
+
import type { EntityMeta, FieldOptions, Query, QueryConflictPaths, QueryContext, QueryOptions, QueryPager, SqlDialectFeatures, SqlValues, TriggerRows, Type, UpdatePayload, VectorDistance, VectorMetric } from '../type/index.js';
|
|
5
5
|
/** Microsoft SQL Server 2017 and up. Identifiers are `"`-quoted, the ANSI spelling `tedious` enables. */
|
|
6
6
|
export declare class MsSqlDialect extends MergeSqlDialect {
|
|
7
7
|
#private;
|
|
@@ -27,7 +27,7 @@ export declare class MsSqlDialect extends MergeSqlDialect {
|
|
|
27
27
|
/** The server's 2100 per request, less the two `sp_executesql` takes for the statement and its parameter list. */
|
|
28
28
|
readonly maxBindValues = 2098;
|
|
29
29
|
readonly maxInsertRows = 1000;
|
|
30
|
-
/** `OUTPUT` has no trailing form: it sits between the
|
|
30
|
+
/** `OUTPUT` has no trailing form: it sits between the target and its rows. */
|
|
31
31
|
readonly returningPosition = "after-target";
|
|
32
32
|
/** `OUTPUT` reads the written row off the `INSERTED` pseudo-table. */
|
|
33
33
|
protected readonly returnedRowPrefix = "INSERTED.";
|
|
@@ -74,7 +74,7 @@ export declare class MsSqlDialect extends MergeSqlDialect {
|
|
|
74
74
|
* carrying a trigger, and through a table it works whether one is there or not.
|
|
75
75
|
*/
|
|
76
76
|
returningId<E>(meta: EntityMeta<E>): string;
|
|
77
|
-
upsert<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[],
|
|
77
|
+
upsert<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[], update?: UpdatePayload<E>): void;
|
|
78
78
|
/**
|
|
79
79
|
* A statement writing rows, `write`, wrapped in what SQL Server needs around one. The table variable its
|
|
80
80
|
* `OUTPUT` fills, typed as the id column is, and the read handing that back, uncounted so the batch
|
|
@@ -102,7 +102,7 @@ export class MsSqlDialect extends MergeSqlDialect {
|
|
|
102
102
|
/** The server's 2100 per request, less the two `sp_executesql` takes for the statement and its parameter list. */
|
|
103
103
|
maxBindValues = 2098;
|
|
104
104
|
maxInsertRows = 1000;
|
|
105
|
-
/** `OUTPUT` has no trailing form: it sits between the
|
|
105
|
+
/** `OUTPUT` has no trailing form: it sits between the target and its rows. */
|
|
106
106
|
returningPosition = 'after-target';
|
|
107
107
|
/** `OUTPUT` reads the written row off the `INSERTED` pseudo-table. */
|
|
108
108
|
returnedRowPrefix = 'INSERTED.';
|
|
@@ -181,8 +181,8 @@ export class MsSqlDialect extends MergeSqlDialect {
|
|
|
181
181
|
const expression = this.returningIdExpression(meta);
|
|
182
182
|
return expression ? this.mergeReturning(expression) : '';
|
|
183
183
|
}
|
|
184
|
-
upsert(ctx, entity, conflictPaths, payload,
|
|
185
|
-
this.writeRows(ctx, getMeta(entity), payload, () => super.upsert(ctx, entity, conflictPaths, payload,
|
|
184
|
+
upsert(ctx, entity, conflictPaths, payload, update) {
|
|
185
|
+
this.writeRows(ctx, getMeta(entity), payload, () => super.upsert(ctx, entity, conflictPaths, payload, update));
|
|
186
186
|
}
|
|
187
187
|
/**
|
|
188
188
|
* A statement writing rows, `write`, wrapped in what SQL Server needs around one. The table variable its
|
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
import type { PostgresDialect } from '../postgres/postgresDialect.js';
|
|
2
1
|
import { AbstractSqlQuerier } from '../querier/index.js';
|
|
3
2
|
import type { ExtraOptions } from '../type/index.js';
|
|
3
|
+
import type { PgliteDialect } from './pgliteDialect.js';
|
|
4
4
|
/** The two methods uql uses of `@electric-sql/pglite`, stated so its published types do not depend on a pre-1.0 package. */
|
|
5
5
|
export type PgliteDatabase = {
|
|
6
6
|
query<T>(query: string, params?: unknown[]): Promise<{
|
|
@@ -18,7 +18,7 @@ export type PgliteDatabase = {
|
|
|
18
18
|
export declare class PgliteQuerier extends AbstractSqlQuerier {
|
|
19
19
|
readonly db: PgliteDatabase;
|
|
20
20
|
readonly extra?: ExtraOptions | undefined;
|
|
21
|
-
constructor(db: PgliteDatabase, dialect:
|
|
21
|
+
constructor(db: PgliteDatabase, dialect: PgliteDialect, extra?: ExtraOptions | undefined);
|
|
22
22
|
internalAll<T>(query: string, values?: unknown[]): Promise<T[]>;
|
|
23
23
|
internalRun(query: string, values?: unknown[]): Promise<import("../type/query.js").QueryUpdateResult>;
|
|
24
24
|
/** The handle belongs to the pool, which hands out one querier per unit of work over it. */
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { AbstractDialect } from '../dialect/abstractDialect.js';
|
|
2
|
-
import type { CursorPage, EntityData, EntityId, EntityWrite, ExtraOptions, FieldKey, Querier, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryKeysetProjected, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, PrimaryKey, QueryUpdateResult, QueryUpsertOneResult, QueryUpsertManyResult, RelationKey, TransactionOptions, Type, UpdatePayload, UpdateWrite,
|
|
2
|
+
import type { CursorPage, EntityData, EntityId, EntityWrite, ExtraOptions, FieldKey, Querier, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryKeysetProjected, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, PrimaryKey, QueryUpdateResult, QueryUpsertOneResult, QueryUpsertManyResult, RelationKey, TransactionOptions, Type, UpdatePayload, UpdateWrite, WrittenId } from '../type/index.js';
|
|
3
3
|
import { LoggerWrapper } from '../util/index.js';
|
|
4
4
|
/** Base class for all database queriers. */
|
|
5
5
|
export declare abstract class AbstractQuerier implements Querier {
|
|
@@ -52,12 +52,10 @@ export declare abstract class AbstractQuerier implements Querier {
|
|
|
52
52
|
$entity: Type<E>;
|
|
53
53
|
}, opts?: QueryOptions): AsyncIterable<QueryFindResult<E, S, V, X, P, C>>;
|
|
54
54
|
findManyStream<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P, C>, opts?: QueryOptions): AsyncIterable<QueryFindResult<E, S, V, X, P, C>>;
|
|
55
|
-
/** `afterLoad` on each row before the loop sees it, as `findMany` runs it on each row it read. */
|
|
56
|
-
private loadedEach;
|
|
57
55
|
/**
|
|
58
|
-
* `rows`,
|
|
59
|
-
*
|
|
60
|
-
*
|
|
56
|
+
* `rows`, each through `loaded` (guarded, so an unhooked row costs no turn) before the loop sees it, holding the
|
|
57
|
+
* querier from the first row asked for until the loop ends. Most drivers queue a statement behind an open read,
|
|
58
|
+
* which a loop awaiting it never finishes, so `serialize` refuses one meanwhile, and `release` closes the stream.
|
|
61
59
|
*/
|
|
62
60
|
private holdWhileReading;
|
|
63
61
|
protected abstract internalFindManyStream<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): AsyncIterable<E>;
|
|
@@ -101,9 +99,9 @@ export declare abstract class AbstractQuerier implements Querier {
|
|
|
101
99
|
* same rows the statement wrote.
|
|
102
100
|
*/
|
|
103
101
|
insertMany<E extends object>(entity: Type<E>, payload: readonly EntityWrite<E>[]): Promise<(WrittenId<E> | undefined)[]>;
|
|
104
|
-
/** Fills and guards `rows`, then writes them: an insert, and the insert half of a
|
|
102
|
+
/** Fills and guards `rows`, then writes them and their relations: an insert, and the insert half of a read upsert. */
|
|
105
103
|
private insertRows;
|
|
106
|
-
/** Writes `rows`, and onto each one the key the database generated for it, where it can tell. */
|
|
104
|
+
/** Writes `rows`, its columns only, and onto each one the key the database generated for it, where it can tell. */
|
|
107
105
|
protected abstract internalInsertMany<E extends object>(entity: Type<E>, rows: EntityData<E>[]): Promise<void>;
|
|
108
106
|
updateOneById<E extends object>(entity: Type<E>, id: EntityId<E>, payload: UpdateWrite<E>, opts?: QueryOptions): Promise<number>;
|
|
109
107
|
/** Settles the rows first where the update cascades, so a payload changing what `$where` reads still names them. */
|
|
@@ -127,6 +125,13 @@ export declare abstract class AbstractQuerier implements Querier {
|
|
|
127
125
|
* delete, and one without {@link DialectFeatures.correlatedWrites} cannot read a relation in its filter.
|
|
128
126
|
*/
|
|
129
127
|
protected settlesWrite<E extends object>(entity: Type<E>, q: QuerySearch<E>): boolean;
|
|
128
|
+
/**
|
|
129
|
+
* `write` over `rows` in lists of as many as one statement names by `keyCount` keys, summing what each changed:
|
|
130
|
+
* in one transaction where there are several, so a write split to fit the engine still lands whole.
|
|
131
|
+
*/
|
|
132
|
+
protected writeBatches<T>(rows: readonly T[], keyCount: number, write: (batch: T[]) => Promise<number>): Promise<number>;
|
|
133
|
+
/** Runs a write split into several statements as one, in a transaction that joins an open one. */
|
|
134
|
+
protected atomically<T>(write: () => Promise<T>): Promise<T>;
|
|
130
135
|
/** The ids `q` matches, in its own order and page. */
|
|
131
136
|
protected settleIds<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<EntityId<E>[]>;
|
|
132
137
|
/** Runs one UPDATE over `q`, which names its rows by id wherever {@link updateMany} settled them. */
|
|
@@ -139,16 +144,16 @@ export declare abstract class AbstractQuerier implements Querier {
|
|
|
139
144
|
*/
|
|
140
145
|
private unversionedUpdate;
|
|
141
146
|
/** Fires `beforeUpsert`/`afterUpsert`: which branch a row takes is the database's to decide, so neither the insert's nor the update's pair fits. */
|
|
142
|
-
upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityWrite<E>,
|
|
143
|
-
upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: readonly EntityWrite<E>[],
|
|
147
|
+
upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityWrite<E>, update?: UpdateWrite<E>): Promise<QueryUpsertOneResult<E>>;
|
|
148
|
+
upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: readonly EntityWrite<E>[], update?: UpdateWrite<E>): Promise<QueryUpsertManyResult<E>>;
|
|
144
149
|
/**
|
|
145
|
-
* An upsert
|
|
146
|
-
*
|
|
147
|
-
*
|
|
150
|
+
* An upsert as a read, then writes: the rows the conflict names are read through the filters, those found update
|
|
151
|
+
* as `updateMany` does and the rest insert, so either branch writes its relations and a guarded row stays its
|
|
152
|
+
* tenant's. A row inserted concurrently fails on its key. See architecture/security-filter-writes.md.
|
|
148
153
|
*/
|
|
149
|
-
private
|
|
150
|
-
protected abstract internalUpsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E,
|
|
151
|
-
protected abstract internalUpsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E[],
|
|
154
|
+
private readThenUpsert;
|
|
155
|
+
protected abstract internalUpsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E, update?: UpdatePayload<E>): Promise<QueryUpdateResult>;
|
|
156
|
+
protected abstract internalUpsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E[], update?: UpdatePayload<E>): Promise<QueryUpdateResult>;
|
|
152
157
|
deleteOneById<E extends object>(entity: Type<E>, id: EntityId<E>, opts?: QueryOptions): Promise<number>;
|
|
153
158
|
/** Delete records matching the query, the entity passed first or as `$entity`; soft-deletes unless `opts.hardDelete`. */
|
|
154
159
|
deleteMany<E extends object>(q: QuerySearch<E> & {
|
|
@@ -165,7 +170,7 @@ export declare abstract class AbstractQuerier implements Querier {
|
|
|
165
170
|
*/
|
|
166
171
|
saveMany<E extends object>(entity: Type<E>, payload: readonly EntityWrite<E>[]): Promise<(WrittenId<E> | undefined)[]>;
|
|
167
172
|
/** Writes each inserted row's relations, one set of statements per relation whatever the number of rows. */
|
|
168
|
-
|
|
173
|
+
private insertRelations;
|
|
169
174
|
/** `EntityId` because a settled composite row is an object, which {@link childrenOf} reads each foreign key column out of. */
|
|
170
175
|
private deleteRelations;
|
|
171
176
|
/**
|
|
@@ -87,6 +87,15 @@ function assertLockableUpdate(meta, q, settles) {
|
|
|
87
87
|
function writtenIds(meta, rows) {
|
|
88
88
|
return rows.map((row) => (namesKey(meta, row) ? idOf(meta, row) : undefined));
|
|
89
89
|
}
|
|
90
|
+
/**
|
|
91
|
+
* Whether an upsert has to read before it writes: `ON CONFLICT` updates a guarded row whatever tenant it belongs
|
|
92
|
+
* to, and writes no relation.
|
|
93
|
+
*/
|
|
94
|
+
function upsertsByReading(meta, rows, update) {
|
|
95
|
+
const relates = (payload) => filterPersistableRelationKeys(meta, payload, 'persist').length > 0;
|
|
96
|
+
return (securityConditions(meta).length > 0 ||
|
|
97
|
+
(relates(meta.relations) && (rows.some(relates) || (update !== undefined && relates(update)))));
|
|
98
|
+
}
|
|
90
99
|
/** What `ON CONFLICT` assigns a row it finds by default: the payload, less the columns it matched on. */
|
|
91
100
|
function conflictAssignments(row, conflictPaths) {
|
|
92
101
|
const assigned = { ...row };
|
|
@@ -208,22 +217,17 @@ export class AbstractQuerier {
|
|
|
208
217
|
findManyStream(...args) {
|
|
209
218
|
const [entity, q, opts] = entityArgs(args);
|
|
210
219
|
this.validateReadQuery(entity, q);
|
|
211
|
-
const
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
async *loadedEach(entity, rows, populate) {
|
|
216
|
-
for await (const row of rows) {
|
|
217
|
-
await this.emitLoaded(entity, [row], populate);
|
|
218
|
-
yield row;
|
|
219
|
-
}
|
|
220
|
+
const loaded = this.listensForLoad(entity, q.$populate)
|
|
221
|
+
? (row) => this.emitLoaded(entity, [row], q.$populate)
|
|
222
|
+
: undefined;
|
|
223
|
+
return this.holdWhileReading(this.internalFindManyStream(entity, q, opts), loaded);
|
|
220
224
|
}
|
|
221
225
|
/**
|
|
222
|
-
* `rows`,
|
|
223
|
-
*
|
|
224
|
-
*
|
|
226
|
+
* `rows`, each through `loaded` (guarded, so an unhooked row costs no turn) before the loop sees it, holding the
|
|
227
|
+
* querier from the first row asked for until the loop ends. Most drivers queue a statement behind an open read,
|
|
228
|
+
* which a loop awaiting it never finishes, so `serialize` refuses one meanwhile, and `release` closes the stream.
|
|
225
229
|
*/
|
|
226
|
-
holdWhileReading(rows) {
|
|
230
|
+
holdWhileReading(rows, loaded) {
|
|
227
231
|
const read = async function* (querier) {
|
|
228
232
|
if (querier.#stream) {
|
|
229
233
|
throw new UqlUsageError(STREAM_HOLDS_QUERIER);
|
|
@@ -231,7 +235,12 @@ export class AbstractQuerier {
|
|
|
231
235
|
querier.#stream = stream;
|
|
232
236
|
try {
|
|
233
237
|
await querier.taskQueue;
|
|
234
|
-
|
|
238
|
+
for await (const row of rows) {
|
|
239
|
+
if (loaded) {
|
|
240
|
+
await loaded(row);
|
|
241
|
+
}
|
|
242
|
+
yield row;
|
|
243
|
+
}
|
|
235
244
|
}
|
|
236
245
|
finally {
|
|
237
246
|
querier.#stream = undefined;
|
|
@@ -305,12 +314,13 @@ export class AbstractQuerier {
|
|
|
305
314
|
return writtenIds(meta, rows);
|
|
306
315
|
});
|
|
307
316
|
}
|
|
308
|
-
/** Fills and guards `rows`, then writes them: an insert, and the insert half of a
|
|
317
|
+
/** Fills and guards `rows`, then writes them and their relations: an insert, and the insert half of a read upsert. */
|
|
309
318
|
async insertRows(entity, rows) {
|
|
310
319
|
const meta = getMeta(entity);
|
|
311
320
|
fillOnFields(meta, rows, 'onInsert');
|
|
312
321
|
guardWrite(meta, rows, 'insert');
|
|
313
322
|
await this.internalInsertMany(entity, rows);
|
|
323
|
+
await this.insertRelations(entity, rows);
|
|
314
324
|
}
|
|
315
325
|
async updateOneById(entity, id, payload, opts) {
|
|
316
326
|
assertIdValue(entity, id);
|
|
@@ -345,10 +355,7 @@ export class AbstractQuerier {
|
|
|
345
355
|
if (!ids.length) {
|
|
346
356
|
return 0;
|
|
347
357
|
}
|
|
348
|
-
|
|
349
|
-
for (const batch of chunk(ids, this.dialect.keyListCapacity(meta.ids.length))) {
|
|
350
|
-
changes += await this.updateColumns(entity, { $where: whereIds(meta, batch) }, row, opts, batch.length);
|
|
351
|
-
}
|
|
358
|
+
const changes = await this.writeBatches(ids, meta.ids.length, (batch) => this.updateColumns(entity, { $where: whereIds(meta, batch) }, row, opts, batch.length));
|
|
352
359
|
for (const relKey of relKeys) {
|
|
353
360
|
await this.saveRelation(entity, relKey, ids.map((id) => ({ id, value: row[relKey] })), true);
|
|
354
361
|
}
|
|
@@ -384,6 +391,25 @@ export class AbstractQuerier {
|
|
|
384
391
|
const { dialect } = this;
|
|
385
392
|
return isPagedQuery(q) || (!dialect.features.correlatedWrites && dialect.constrainsRelations(entity, q.$where));
|
|
386
393
|
}
|
|
394
|
+
/**
|
|
395
|
+
* `write` over `rows` in lists of as many as one statement names by `keyCount` keys, summing what each changed:
|
|
396
|
+
* in one transaction where there are several, so a write split to fit the engine still lands whole.
|
|
397
|
+
*/
|
|
398
|
+
async writeBatches(rows, keyCount, write) {
|
|
399
|
+
const batches = chunk(rows, this.dialect.keyListCapacity(keyCount));
|
|
400
|
+
const each = async () => {
|
|
401
|
+
let changes = 0;
|
|
402
|
+
for (const batch of batches) {
|
|
403
|
+
changes += await write(batch);
|
|
404
|
+
}
|
|
405
|
+
return changes;
|
|
406
|
+
};
|
|
407
|
+
return batches.length > 1 ? this.atomically(each) : each();
|
|
408
|
+
}
|
|
409
|
+
/** Runs a write split into several statements as one, in a transaction that joins an open one. */
|
|
410
|
+
atomically(write) {
|
|
411
|
+
return this.transaction(write);
|
|
412
|
+
}
|
|
387
413
|
/** The ids `q` matches, in its own order and page. */
|
|
388
414
|
async settleIds(entity, q, opts) {
|
|
389
415
|
const meta = getMeta(entity);
|
|
@@ -412,36 +438,37 @@ export class AbstractQuerier {
|
|
|
412
438
|
return this.hooked(entity, 'Update', [payload], ([row]) => this.updateRows(entity, q, row, opts, undefined));
|
|
413
439
|
}
|
|
414
440
|
/** Fires `beforeUpsert`/`afterUpsert`: which branch a row takes is the database's to decide, so neither the insert's nor the update's pair fits. */
|
|
415
|
-
async upsertOne(entity, conflictPaths, payload,
|
|
441
|
+
async upsertOne(entity, conflictPaths, payload, update) {
|
|
416
442
|
const meta = getMeta(entity);
|
|
417
443
|
assertUnversioned(meta, "'upsertOne'");
|
|
418
444
|
return this.hooked(entity, 'Upsert', [payload], async (rows) => {
|
|
419
|
-
const { ids, changes, created } =
|
|
420
|
-
? await this.
|
|
421
|
-
: await this.internalUpsertOne(entity, conflictPaths, rows[0],
|
|
445
|
+
const { ids, changes, created } = upsertsByReading(meta, rows, update)
|
|
446
|
+
? await this.readThenUpsert(entity, conflictPaths, rows, update)
|
|
447
|
+
: await this.internalUpsertOne(entity, conflictPaths, rows[0], update);
|
|
422
448
|
adoptReportedIds(meta, rows, ids);
|
|
423
449
|
const [id] = writtenIds(meta, rows);
|
|
424
450
|
return { id, changes, created };
|
|
425
451
|
});
|
|
426
452
|
}
|
|
427
|
-
async upsertMany(entity, conflictPaths, payload,
|
|
453
|
+
async upsertMany(entity, conflictPaths, payload, update) {
|
|
428
454
|
const meta = getMeta(entity);
|
|
429
455
|
assertUnversioned(meta, "'upsertMany'");
|
|
430
456
|
return this.hooked(entity, 'Upsert', payload, async (rows) => {
|
|
431
|
-
const { ids, changes } =
|
|
432
|
-
? await this.
|
|
433
|
-
: await this.internalUpsertMany(entity, conflictPaths, rows,
|
|
457
|
+
const { ids, changes } = upsertsByReading(meta, rows, update)
|
|
458
|
+
? await this.readThenUpsert(entity, conflictPaths, rows, update)
|
|
459
|
+
: await this.internalUpsertMany(entity, conflictPaths, rows, update);
|
|
434
460
|
adoptReportedIds(meta, rows, ids);
|
|
435
461
|
return { ids: writtenIds(meta, rows), changes };
|
|
436
462
|
});
|
|
437
463
|
}
|
|
438
464
|
/**
|
|
439
|
-
* An upsert
|
|
440
|
-
*
|
|
441
|
-
*
|
|
465
|
+
* An upsert as a read, then writes: the rows the conflict names are read through the filters, those found update
|
|
466
|
+
* as `updateMany` does and the rest insert, so either branch writes its relations and a guarded row stays its
|
|
467
|
+
* tenant's. A row inserted concurrently fails on its key. See architecture/security-filter-writes.md.
|
|
442
468
|
*/
|
|
443
|
-
async
|
|
444
|
-
|
|
469
|
+
async readThenUpsert(entity, conflictPaths, rows, update) {
|
|
470
|
+
const meta = getMeta(entity);
|
|
471
|
+
guardWrite(meta, rows, 'insert');
|
|
445
472
|
if (!rows.length) {
|
|
446
473
|
return { changes: 0 };
|
|
447
474
|
}
|
|
@@ -452,7 +479,10 @@ export class AbstractQuerier {
|
|
|
452
479
|
for (const [index, row] of rows.entries()) {
|
|
453
480
|
// An empty `update` leaves a found row as it is, as `DO NOTHING` does.
|
|
454
481
|
if (ids[index] !== undefined && (update === undefined || hasKeys(update))) {
|
|
455
|
-
|
|
482
|
+
const q = { $where: whereEach(keys, (key) => row[key]) };
|
|
483
|
+
// A copy each: the update fills its `onUpdate` fields into what it is handed.
|
|
484
|
+
const assigned = update ? { ...update } : conflictAssignments(row, conflictPaths);
|
|
485
|
+
changes += await this.updateRows(entity, q, assigned, undefined, undefined);
|
|
456
486
|
}
|
|
457
487
|
}
|
|
458
488
|
const inserts = rows.filter((_, index) => ids[index] === undefined);
|
|
@@ -464,8 +494,7 @@ export class AbstractQuerier {
|
|
|
464
494
|
// A found row's key is adopted by the caller; an inserted one carries the key its insert wrote.
|
|
465
495
|
return { changes, created, ids };
|
|
466
496
|
};
|
|
467
|
-
|
|
468
|
-
return rows.length === 1 ? write() : this.transaction(write);
|
|
497
|
+
return rows.length === 1 ? write() : this.atomically(write);
|
|
469
498
|
}
|
|
470
499
|
async deleteOneById(entity, id, opts) {
|
|
471
500
|
assertIdValue(entity, id);
|
|
@@ -489,14 +518,13 @@ export class AbstractQuerier {
|
|
|
489
518
|
return 0;
|
|
490
519
|
}
|
|
491
520
|
await this.emitHook(entity, 'beforeDelete', doomed);
|
|
492
|
-
|
|
493
|
-
for (const batch of chunk(ids, this.dialect.keyListCapacity(meta.ids.length))) {
|
|
521
|
+
const changes = await this.writeBatches(ids, meta.ids.length, async (batch) => {
|
|
494
522
|
// Children first: they hold the foreign key, which a schema without `ON DELETE CASCADE` enforces.
|
|
495
523
|
if (cascades) {
|
|
496
524
|
await this.deleteRelations(entity, batch, opts);
|
|
497
525
|
}
|
|
498
|
-
|
|
499
|
-
}
|
|
526
|
+
return this.internalDeleteMany(entity, { $where: whereIds(meta, batch) }, opts);
|
|
527
|
+
});
|
|
500
528
|
await this.emitHook(entity, 'afterDelete', doomed);
|
|
501
529
|
return changes;
|
|
502
530
|
}
|
|
@@ -549,9 +577,7 @@ export class AbstractQuerier {
|
|
|
549
577
|
}
|
|
550
578
|
}
|
|
551
579
|
};
|
|
552
|
-
|
|
553
|
-
// this is free inside a caller's own.
|
|
554
|
-
await (toInsert.length && toUpsert.length ? this.transaction(write) : write());
|
|
580
|
+
await (toInsert.length && toUpsert.length ? this.atomically(write) : write());
|
|
555
581
|
return ids;
|
|
556
582
|
}
|
|
557
583
|
/** Writes each inserted row's relations, one set of statements per relation whatever the number of rows. */
|
|
@@ -593,9 +619,7 @@ export class AbstractQuerier {
|
|
|
593
619
|
const holder = relOpts.through ? relOpts.through() : relEntity;
|
|
594
620
|
const parentColumn = soleParentColumn(relOpts);
|
|
595
621
|
if (isUpdate) {
|
|
596
|
-
|
|
597
|
-
await this.deleteMany(holder, { $where: { [parentColumn]: batch.map(({ id }) => id) } });
|
|
598
|
-
}
|
|
622
|
+
await this.writeBatches(writes, 1, (batch) => this.deleteMany(holder, { $where: { [parentColumn]: batch.map(({ id }) => id) } }));
|
|
599
623
|
}
|
|
600
624
|
// Each parent gets its own copies, so a row listed for two parents is written twice.
|
|
601
625
|
const children = writes.flatMap(({ id, value }) => [value ?? []].flat().map((row) => ({ id, row })));
|
|
@@ -690,7 +714,9 @@ export class AbstractQuerier {
|
|
|
690
714
|
const meta = getMeta(entity);
|
|
691
715
|
const [idKey] = meta.ids;
|
|
692
716
|
const keys = getKeys(conflictPaths);
|
|
693
|
-
|
|
717
|
+
// A null key never conflicts, so no row is read back for it, whether one key names the row or several.
|
|
718
|
+
const named = rows.filter((row) => keys.every((key) => row[key] != null));
|
|
719
|
+
const distinct = [...new Map(named.map((row) => [rowKey(row, keys), row])).values()];
|
|
694
720
|
const found = [];
|
|
695
721
|
for (const batch of chunk(distinct, this.dialect.keyListCapacity(keys.length))) {
|
|
696
722
|
const q = { $select: keySet([idKey, ...keys]), $where: whereKeysIn(keys, batch) };
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { AbstractSqlDialect } from '../dialect/index.js';
|
|
2
|
-
import type { EntityData, ExtraOptions, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryPage, QueryGroupMap, QueryOptions, QuerySearch, QueryUpdateResult, RawRow, SqlQuerier, TransactionOptions, Type, UpdatePayload
|
|
2
|
+
import type { EntityData, ExtraOptions, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryPage, QueryGroupMap, QueryOptions, QuerySearch, QueryUpdateResult, RawRow, SqlQuerier, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
|
|
3
3
|
import type { BuildUpdateResultPayload } from '../util/sql.util.js';
|
|
4
4
|
import { AbstractQuerier } from './abstractQuerier.js';
|
|
5
5
|
export declare abstract class AbstractSqlQuerier extends AbstractQuerier implements SqlQuerier {
|
|
@@ -90,8 +90,8 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
|
|
|
90
90
|
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>[]>;
|
|
91
91
|
internalInsertMany<E extends object>(entity: Type<E>, rows: EntityData<E>[]): Promise<void>;
|
|
92
92
|
internalUpdateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
|
|
93
|
-
protected internalUpsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E,
|
|
94
|
-
protected internalUpsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E[],
|
|
93
|
+
protected internalUpsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E, update?: UpdatePayload<E>): Promise<QueryUpdateResult>;
|
|
94
|
+
protected internalUpsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E[], update?: UpdatePayload<E>): Promise<QueryUpdateResult>;
|
|
95
95
|
private runUpsert;
|
|
96
96
|
protected internalDeleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
|
|
97
97
|
get hasOpenTransaction(): boolean;
|