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.
Files changed (43) hide show
  1. package/README.md +3 -0
  2. package/dist/browser/uql-browser.min.js +2 -2
  3. package/dist/browser/uql-browser.min.js.map +4 -4
  4. package/dist/d1/d1Querier.d.ts +2 -0
  5. package/dist/d1/d1Querier.js +4 -0
  6. package/dist/dialect/abstractSqlDialect.d.ts +6 -6
  7. package/dist/dialect/abstractSqlDialect.js +8 -8
  8. package/dist/dialect/mergeSqlDialect.d.ts +2 -2
  9. package/dist/dialect/mergeSqlDialect.js +1 -1
  10. package/dist/dialect/mysqlLikeSqlDialect.d.ts +2 -2
  11. package/dist/dialect/mysqlLikeSqlDialect.js +4 -7
  12. package/dist/dialect/pgLikeSqlDialect.d.ts +2 -2
  13. package/dist/dialect/pgLikeSqlDialect.js +4 -4
  14. package/dist/dialect/queryContext.d.ts +0 -2
  15. package/dist/dialect/queryContext.js +0 -6
  16. package/dist/maria/mariadbQuerier.d.ts +4 -0
  17. package/dist/maria/mariadbQuerier.js +14 -2
  18. package/dist/migrate/cli-config.d.ts +9 -0
  19. package/dist/migrate/cli-config.js +24 -6
  20. package/dist/migrate/cli.js +9 -2
  21. package/dist/migrate/ddl/defaultSql.js +3 -1
  22. package/dist/mongo/mongodbQuerier.d.ts +3 -3
  23. package/dist/mongo/mongodbQuerier.js +2 -3
  24. package/dist/mssql/mssqlDialect.d.ts +3 -3
  25. package/dist/mssql/mssqlDialect.js +3 -3
  26. package/dist/pglite/pgliteQuerier.d.ts +2 -2
  27. package/dist/querier/abstractQuerier.d.ts +22 -17
  28. package/dist/querier/abstractQuerier.js +72 -46
  29. package/dist/querier/abstractSqlQuerier.d.ts +3 -3
  30. package/dist/querier/abstractSqlQuerier.js +39 -33
  31. package/dist/schema/sqlExpression.d.ts +2 -2
  32. package/dist/schema/sqlExpression.js +2 -2
  33. package/dist/type/dialect.d.ts +3 -3
  34. package/dist/type/entity.d.ts +2 -2
  35. package/dist/type/query.d.ts +1 -12
  36. package/dist/type/universalQuerier.d.ts +9 -5
  37. package/dist/util/object.util.js +3 -0
  38. package/dist/util/sql.util.d.ts +0 -2
  39. package/dist/util/sql.util.js +0 -6
  40. package/dist/util/triggerWrite.d.ts +3 -3
  41. package/dist/util/triggerWrite.js +2 -2
  42. package/package.json +1 -1
  43. 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
- * Loads the config with a plain `import()`, leaving TypeScript to the runtime: uql bundles no transpiler,
7
- * since only the project knows its decorator spec. Node's type stripping handles no decorators.
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 mod = (await import(pathToFileURL(path).href).catch((cause) => {
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 with `node --import tsx` ' +
14
- '(`npm i -D tsx`). A JavaScript config, or passing the config inline, needs neither.', { cause });
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) {
@@ -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
- logger: console.log,
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
- console.log(statements.length ? `\n${statements.join('\n')}` : '\nSchema is already in sync.');
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, UpsertOptions } from '../type/index.js';
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, { update }: UpsertOptions<E>): Promise<{
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[], { update }: UpsertOptions<E>): Promise<{
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, { update }) {
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, { update }) {
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, UpsertOptions, VectorDistance, VectorMetric } from '../type/index.js';
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 column list and `VALUES`. */
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[], opts?: UpsertOptions<E>): void;
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 column list and `VALUES`. */
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, opts) {
185
- this.writeRows(ctx, getMeta(entity), payload, () => super.upsert(ctx, entity, conflictPaths, payload, opts));
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: PostgresDialect, extra?: ExtraOptions | undefined);
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, UpsertOptions, WrittenId } from '../type/index.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, 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`, holding the querier from the first row asked for until the loop ends. Most drivers queue a
59
- * statement behind an open read, which a loop awaiting it never finishes, so `serialize` refuses one
60
- * meanwhile, on every engine alike, and `release` closes the stream first.
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 guarded upsert. */
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>, opts?: UpsertOptions<E>): Promise<QueryUpsertOneResult<E>>;
143
- upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: readonly EntityWrite<E>[], opts?: UpsertOptions<E>): Promise<QueryUpsertManyResult<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 on an entity a `security` filter guards. `ON CONFLICT` updates the conflicting row whoever
146
- * it belongs to, so the rows the conflict names are read through the filter: those found update, the
147
- * rest insert, where another tenant's row fails on its key. See architecture/security-filter-writes.md.
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 guardedUpsert;
150
- protected abstract internalUpsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E, opts: UpsertOptions<E>): Promise<QueryUpdateResult>;
151
- protected abstract internalUpsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E[], opts: UpsertOptions<E>): Promise<QueryUpdateResult>;
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
- protected insertRelations<E extends object>(entity: Type<E>, rows: E[]): Promise<void>;
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 rows = this.internalFindManyStream(entity, q, opts);
212
- return this.holdWhileReading(this.listensForLoad(entity, q.$populate) ? this.loadedEach(entity, rows, q.$populate) : rows);
213
- }
214
- /** `afterLoad` on each row before the loop sees it, as `findMany` runs it on each row it read. */
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`, holding the querier from the first row asked for until the loop ends. Most drivers queue a
223
- * statement behind an open read, which a loop awaiting it never finishes, so `serialize` refuses one
224
- * meanwhile, on every engine alike, and `release` closes the stream first.
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
- yield* rows;
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 guarded upsert. */
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
- let changes = 0;
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, opts = {}) {
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 } = securityConditions(meta).length
420
- ? await this.guardedUpsert(entity, conflictPaths, rows, opts)
421
- : await this.internalUpsertOne(entity, conflictPaths, rows[0], opts);
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, opts = {}) {
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 } = securityConditions(meta).length
432
- ? await this.guardedUpsert(entity, conflictPaths, rows, opts)
433
- : await this.internalUpsertMany(entity, conflictPaths, rows, opts);
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 on an entity a `security` filter guards. `ON CONFLICT` updates the conflicting row whoever
440
- * it belongs to, so the rows the conflict names are read through the filter: those found update, the
441
- * rest insert, where another tenant's row fails on its key. See architecture/security-filter-writes.md.
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 guardedUpsert(entity, conflictPaths, rows, { update }) {
444
- guardWrite(getMeta(entity), rows, 'insert');
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
- changes += await this.updateColumns(entity, { $where: whereEach(keys, (key) => row[key]) }, update ?? conflictAssignments(row, conflictPaths), undefined, 0);
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
- // One row is one statement after the read, so it needs no transaction of its own.
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
- let changes = 0;
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
- changes += await this.internalDeleteMany(entity, { $where: whereIds(meta, batch) }, opts);
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
- // Only a batch carrying both kinds is more than one statement; `transaction` is re-entrant, so
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
- for (const batch of chunk(writes, this.dialect.keyListCapacity(1))) {
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
- const distinct = [...new Map(rows.map((row) => [rowKey(row, keys), row])).values()];
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, UpsertOptions } from '../type/index.js';
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, opts: UpsertOptions<E>): Promise<QueryUpdateResult>;
94
- protected internalUpsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E[], opts: UpsertOptions<E>): Promise<QueryUpdateResult>;
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;