uql-orm 0.93.1 → 0.95.0

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 (67) hide show
  1. package/README.md +3 -0
  2. package/dist/browser/uql-browser.min.js +1 -1
  3. package/dist/browser/uql-browser.min.js.map +4 -4
  4. package/dist/dialect/abstractDialect.d.ts +2 -0
  5. package/dist/dialect/abstractDialect.js +4 -0
  6. package/dist/dialect/abstractSqlDialect.d.ts +13 -8
  7. package/dist/dialect/abstractSqlDialect.js +29 -12
  8. package/dist/dialect/mergeSqlDialect.d.ts +2 -2
  9. package/dist/dialect/mergeSqlDialect.js +1 -1
  10. package/dist/dialect/mysqlLikeSqlDialect.d.ts +3 -2
  11. package/dist/dialect/mysqlLikeSqlDialect.js +5 -2
  12. package/dist/dialect/pgLikeSqlDialect.d.ts +2 -0
  13. package/dist/dialect/pgLikeSqlDialect.js +4 -0
  14. package/dist/dialect/queryContext.d.ts +2 -0
  15. package/dist/dialect/queryContext.js +6 -0
  16. package/dist/maria/mariadbQuerier.d.ts +2 -1
  17. package/dist/maria/mariadbQuerier.js +2 -8
  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/migrate/drift/driftDetector.js +7 -2
  23. package/dist/mongo/mongoDialect.d.ts +1 -0
  24. package/dist/mongo/mongoDialect.js +0 -1
  25. package/dist/mongo/mongodbQuerier.d.ts +3 -3
  26. package/dist/mongo/mongodbQuerier.js +5 -13
  27. package/dist/mssql/mssqlDialect.d.ts +5 -4
  28. package/dist/mssql/mssqlDialect.js +5 -4
  29. package/dist/mssql/mssqlQuerier.d.ts +2 -2
  30. package/dist/mssql/mssqlQuerier.js +1 -3
  31. package/dist/mysql/mysql2Querier.d.ts +1 -1
  32. package/dist/mysql/mysql2Querier.js +1 -9
  33. package/dist/pglite/index.d.ts +1 -0
  34. package/dist/pglite/index.js +1 -0
  35. package/dist/pglite/pgliteDialect.d.ts +6 -0
  36. package/dist/pglite/pgliteDialect.js +6 -0
  37. package/dist/pglite/pgliteQuerierPool.d.ts +2 -2
  38. package/dist/pglite/pgliteQuerierPool.js +2 -2
  39. package/dist/postgres/pgQuerier.d.ts +2 -4
  40. package/dist/postgres/pgQuerier.js +1 -9
  41. package/dist/querier/abstractQuerier.d.ts +33 -15
  42. package/dist/querier/abstractQuerier.js +116 -33
  43. package/dist/querier/abstractQuerierPool.d.ts +1 -1
  44. package/dist/querier/abstractQuerierPool.js +1 -1
  45. package/dist/querier/abstractSqlQuerier.d.ts +17 -12
  46. package/dist/querier/abstractSqlQuerier.js +61 -65
  47. package/dist/querier/cursorStream.d.ts +1 -1
  48. package/dist/schema/sqlExpression.d.ts +4 -1
  49. package/dist/schema/sqlExpression.js +20 -2
  50. package/dist/sqlite/abstractSqliteQuerier.d.ts +1 -1
  51. package/dist/sqlite/sqliteDialect.d.ts +1 -0
  52. package/dist/sqlite/sqliteDialect.js +1 -0
  53. package/dist/type/dialect.d.ts +3 -3
  54. package/dist/type/entity.d.ts +4 -4
  55. package/dist/type/querier.d.ts +1 -1
  56. package/dist/type/query.d.ts +1 -12
  57. package/dist/type/universalQuerier.d.ts +10 -6
  58. package/dist/util/object.util.d.ts +2 -0
  59. package/dist/util/object.util.js +8 -0
  60. package/dist/util/query.util.d.ts +3 -1
  61. package/dist/util/query.util.js +7 -0
  62. package/dist/util/sql.util.d.ts +2 -4
  63. package/dist/util/sql.util.js +10 -19
  64. package/dist/util/triggerWrite.d.ts +3 -3
  65. package/dist/util/triggerWrite.js +2 -2
  66. package/package.json +1 -1
  67. package/skills/uql-orm/SKILL.md +8 -3
@@ -19,14 +19,8 @@ export class MariadbQuerier extends AbstractPoolQuerier {
19
19
  return this.buildUpdateResult({ rows, changes, upsertStatus: res.affectedRows });
20
20
  }
21
21
  async *internalStream(query, values) {
22
- const stream = this.getConn().queryStream(query, toBindValues(values));
23
- try {
24
- for await (const row of stream) {
25
- yield decodeBigInts(row);
26
- }
27
- }
28
- finally {
29
- stream.destroy();
22
+ for await (const row of this.getConn().queryStream(query, toBindValues(values))) {
23
+ yield decodeBigInts(row);
30
24
  }
31
25
  }
32
26
  /**
@@ -1,2 +1,11 @@
1
1
  import type { Config } from '../type/index.js';
2
+ /**
3
+ * The project's own `tsx/esm/api` where Node must load a TypeScript config: Node's type stripping runs
4
+ * no decorators, and Bun and Deno transform them natively. uql bundles no transpiler, so the project's
5
+ * loader reads the project's `tsconfig.json`.
6
+ */
7
+ export declare function tsxApiFor(path: string, versions: {
8
+ bun?: string;
9
+ deno?: string;
10
+ }): string | undefined;
2
11
  export declare function loadConfig(customPath?: string): Promise<Config>;
@@ -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.
@@ -6,6 +6,7 @@
6
6
  */
7
7
  import { canonicalToSql, engineType } from '../../schema/canonicalType.js';
8
8
  import { defaultsEqualAsWritten, diffSchemas, referentialActions } from '../../schema/schemaASTDiffer.js';
9
+ import { SqlExpression, writtenDefault } from '../../schema/sqlExpression.js';
9
10
  function resolveOptions(options) {
10
11
  return {
11
12
  checkTypes: options.checkTypes ?? true,
@@ -156,8 +157,8 @@ function addAlterColumnDrifts(colDiff, drifts, opts) {
156
157
  severity: 'info',
157
158
  table: colDiff.table,
158
159
  column: colDiff.column,
159
- expected: String(colDiff.to.defaultValue ?? 'NULL'),
160
- actual: String(colDiff.from.defaultValue ?? 'NULL'),
160
+ expected: shownDefault(colDiff.to.defaultValue),
161
+ actual: shownDefault(colDiff.from.defaultValue),
161
162
  details: `Default mismatch for "${colDiff.column}"`,
162
163
  suggestion: 'Align the default in the entity or the database',
163
164
  });
@@ -245,6 +246,10 @@ function detectRelationshipDrifts(diff) {
245
246
  }
246
247
  return drifts;
247
248
  }
249
+ /** A default as a report shows it: SQL as its SQL, a JSON document as JSON rather than `[object Object]`. */
250
+ function shownDefault(value) {
251
+ return value == null ? 'NULL' : SqlExpression.isExpression(value) ? String(value) : writtenDefault(value);
252
+ }
248
253
  /** Both actions spelled out, so a side that left one unstated reads the same as one that stated the default. */
249
254
  function formatActions(rel) {
250
255
  const { onDelete, onUpdate } = referentialActions(rel);
@@ -209,6 +209,7 @@ export declare class MongoDialect extends AbstractDialect {
209
209
  private referenceKeys;
210
210
  normalizeIds<E extends Document>(meta: EntityMeta<E>, docs: Document[]): E[];
211
211
  /** `doc` is the wire shape - `_id`, stored names, `ObjectId`s - and what comes back is the code's. */
212
+ normalizeId<E extends Document>(meta: EntityMeta<E>, doc: Document): E;
212
213
  normalizeId<E extends Document>(meta: EntityMeta<E>, doc: Document | undefined): E | undefined;
213
214
  /** An aggregate's rows with each 64-bit integer decoded as a document's is: a `bigint` only where the column reads a `BigInt` field. */
214
215
  normalizeAggregateRows<E extends Document, const G extends QueryGroupMap<E>, const A extends QueryAggMap<E>, R extends Document>(entity: Type<E>, q: QueryAggregate<E, G, A>, rows: R[]): R[];
@@ -912,7 +912,6 @@ export class MongoDialect extends AbstractDialect {
912
912
  normalizeIds(meta, docs) {
913
913
  return docs.map((doc) => this.normalizeId(meta, doc));
914
914
  }
915
- /** `doc` is the wire shape - `_id`, stored names, `ObjectId`s - and what comes back is the code's. */
916
915
  normalizeId(meta, doc) {
917
916
  if (!doc) {
918
917
  return doc;
@@ -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
  } | {
@@ -1,7 +1,7 @@
1
1
  import { AGGREGATE_VALUE_ALIAS } from '../dialect/aliases.js';
2
2
  import { hasRequiredJoin } from '../dialect/queryJoins.js';
3
3
  import { fieldOf, getMeta, namesKey, soleIdOf } from '../entity/index.js';
4
- import { AbstractQuerier, enrichError } from '../querier/index.js';
4
+ import { AbstractQuerier } from '../querier/index.js';
5
5
  import { clone, getKeys, getSoftDeleteValue, hasKeys, hasTriggers, populatesRelations, textSortOf, vectorCandidates, withoutSoftDeleteFilter, whereEach, } from '../util/index.js';
6
6
  import { UqlUsageError } from '../util/uqlError.js';
7
7
  /**
@@ -53,15 +53,8 @@ export class MongodbQuerier extends AbstractQuerier {
53
53
  return;
54
54
  }
55
55
  const meta = getMeta(entity);
56
- const cursor = this.readCursor(entity, q, opts);
57
- try {
58
- for await (const doc of cursor) {
59
- const [normalized] = this.dialect.normalizeIds(meta, [doc]);
60
- yield normalized;
61
- }
62
- }
63
- catch (err) {
64
- throw enrichError(err, this.logger, 'internalFindManyStream');
56
+ for await (const doc of this.timedStream('internalFindManyStream', undefined, this.readCursor(entity, q, opts))) {
57
+ yield this.dialect.normalizeId(meta, doc);
65
58
  }
66
59
  }
67
60
  /**
@@ -195,7 +188,6 @@ export class MongodbQuerier extends AbstractQuerier {
195
188
  for (let index = 0; index < rows.length; index++) {
196
189
  rows[index][idKey] = ids[index];
197
190
  }
198
- await this.insertRelations(entity, rows);
199
191
  });
200
192
  }
201
193
  async internalUpdateMany(entity, qm, payload, opts) {
@@ -248,7 +240,7 @@ export class MongodbQuerier extends AbstractQuerier {
248
240
  // `updatedExisting` is false when a new document was inserted (upserted).
249
241
  return { id, created: res.lastErrorObject?.['updatedExisting'] === false };
250
242
  }
251
- async internalUpsertOne(entity, conflictPaths, payload, { update }) {
243
+ async internalUpsertOne(entity, conflictPaths, payload, update) {
252
244
  refuseTriggers(entity);
253
245
  if (update) {
254
246
  const { id, created, changes } = await this.upsertWithUpdate(entity, conflictPaths, payload, update);
@@ -271,7 +263,7 @@ export class MongodbQuerier extends AbstractQuerier {
271
263
  return { ids: [id], changes: id === undefined ? 0 : 1, created };
272
264
  });
273
265
  }
274
- async internalUpsertMany(entity, conflictPaths, payload, { update }) {
266
+ async internalUpsertMany(entity, conflictPaths, payload, update) {
275
267
  refuseTriggers(entity);
276
268
  if (update) {
277
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;
@@ -24,8 +24,9 @@ export declare class MsSqlDialect extends MergeSqlDialect {
24
24
  readonly sqlValues: SqlValues;
25
25
  /** Only where the statement touched a row the trigger selects, since it fires once per statement, even for none. */
26
26
  protected refusal(message: string, rows?: TriggerRows): string;
27
- /** [The hard server limit](https://github.com/yiisoft/yii2/issues/10371), not a driver preference. */
28
- readonly maxBindValues = 2100;
27
+ /** The server's 2100 per request, less the two `sp_executesql` takes for the statement and its parameter list. */
28
+ readonly maxBindValues = 2098;
29
+ readonly maxInsertRows = 1000;
29
30
  /** `OUTPUT` has no trailing form: it sits between the column list and `VALUES`. */
30
31
  readonly returningPosition = "after-target";
31
32
  /** `OUTPUT` reads the written row off the `INSERTED` pseudo-table. */
@@ -73,7 +74,7 @@ export declare class MsSqlDialect extends MergeSqlDialect {
73
74
  * carrying a trigger, and through a table it works whether one is there or not.
74
75
  */
75
76
  returningId<E>(meta: EntityMeta<E>): string;
76
- 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;
77
78
  /**
78
79
  * A statement writing rows, `write`, wrapped in what SQL Server needs around one. The table variable its
79
80
  * `OUTPUT` fills, typed as the id column is, and the read handing that back, uncounted so the batch
@@ -99,8 +99,9 @@ export class MsSqlDialect extends MergeSqlDialect {
99
99
  const touched = rows ? `IF EXISTS (SELECT 1${fromRows(rows)}) ` : '';
100
100
  return `${touched}THROW 50000, ${message}, 1;`;
101
101
  }
102
- /** [The hard server limit](https://github.com/yiisoft/yii2/issues/10371), not a driver preference. */
103
- maxBindValues = 2100;
102
+ /** The server's 2100 per request, less the two `sp_executesql` takes for the statement and its parameter list. */
103
+ maxBindValues = 2098;
104
+ maxInsertRows = 1000;
104
105
  /** `OUTPUT` has no trailing form: it sits between the column list and `VALUES`. */
105
106
  returningPosition = 'after-target';
106
107
  /** `OUTPUT` reads the written row off the `INSERTED` pseudo-table. */
@@ -180,8 +181,8 @@ export class MsSqlDialect extends MergeSqlDialect {
180
181
  const expression = this.returningIdExpression(meta);
181
182
  return expression ? this.mergeReturning(expression) : '';
182
183
  }
183
- upsert(ctx, entity, conflictPaths, payload, opts) {
184
- 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));
185
186
  }
186
187
  /**
187
188
  * A statement writing rows, `write`, wrapped in what SQL Server needs around one. The table variable its
@@ -11,7 +11,7 @@ type MsSqlResult = {
11
11
  rowsAffected: number[];
12
12
  };
13
13
  /** The part of the `Readable` a request streams into that a querier drives. */
14
- type MsSqlRowStream = AsyncIterable<unknown> & {
14
+ type MsSqlRowStream = AsyncIterable<RawRow> & {
15
15
  destroy(error: Error): unknown;
16
16
  on(event: 'error', listener: (error: Error) => void): unknown;
17
17
  };
@@ -49,7 +49,7 @@ export declare class MsSqlQuerier extends AbstractPoolQuerier<MsSqlConnection> {
49
49
  * rows arrive only as fast as they are read. A failure the driver reports through the promise alone
50
50
  * would leave the loop waiting for rows, so it ends the stream instead.
51
51
  */
52
- internalStream<T>(query: string, values?: unknown[]): AsyncGenerator<Awaited<T>, void, unknown>;
52
+ internalStream(query: string, values?: unknown[]): AsyncGenerator<RawRow, void, any>;
53
53
  /**
54
54
  * `mssql` owns its pool and hands out a `Request` per call, so a `BEGIN TRANSACTION` sent as text
55
55
  * would open one on a connection the next call may not be given. Its `Transaction` object is the
@@ -46,9 +46,7 @@ export class MsSqlQuerier extends AbstractPoolQuerier {
46
46
  rows.destroy(err instanceof Error ? err : new Error(String(err)));
47
47
  });
48
48
  try {
49
- for await (const row of rows) {
50
- yield row;
51
- }
49
+ yield* rows;
52
50
  }
53
51
  finally {
54
52
  // The cancel reports itself as an error on the stream, and the loop that would hear it is gone.
@@ -3,6 +3,6 @@ import { AbstractPoolQuerier } from '../querier/abstractPoolQuerier.js';
3
3
  export declare class MySql2Querier extends AbstractPoolQuerier<PoolConnection> {
4
4
  internalAll<T>(query: string, values?: unknown[]): Promise<T[]>;
5
5
  internalRun(query: string, values?: unknown[]): Promise<import("../index.js").QueryUpdateResult>;
6
- internalStream<T>(query: string, values?: unknown[]): AsyncGenerator<Awaited<T>, void, unknown>;
6
+ internalStream(query: string, values?: unknown[]): AsyncGenerator<any, void, any>;
7
7
  protected releaseConn(conn: PoolConnection, discard: boolean): Promise<void>;
8
8
  }
@@ -14,15 +14,7 @@ export class MySql2Querier extends AbstractPoolQuerier {
14
14
  }
15
15
  async *internalStream(query, values) {
16
16
  const rawConn = this.getConn().connection;
17
- const stream = rawConn.query(query, values).stream();
18
- try {
19
- for await (const row of stream) {
20
- yield row;
21
- }
22
- }
23
- finally {
24
- stream.destroy();
25
- }
17
+ yield* rawConn.query(query, values).stream();
26
18
  }
27
19
  async releaseConn(conn, discard) {
28
20
  // mysql2 resets nothing on release, so a connection the pool takes back after a failed rollback
@@ -1,2 +1,3 @@
1
+ export * from './pgliteDialect.js';
1
2
  export * from './pgliteQuerier.js';
2
3
  export * from './pgliteQuerierPool.js';
@@ -1,2 +1,3 @@
1
+ export * from './pgliteDialect.js';
1
2
  export * from './pgliteQuerier.js';
2
3
  export * from './pgliteQuerierPool.js';
@@ -0,0 +1,6 @@
1
+ import { PostgresDialect } from '../postgres/postgresDialect.js';
2
+ /** Postgres as PGlite runs it, which binds fewer values per statement than a server. */
3
+ export declare class PgliteDialect extends PostgresDialect {
4
+ /** Past 32767 PGlite answers no rows, and wrong ones from then on, where a server takes 65535. */
5
+ readonly maxBindValues: number;
6
+ }
@@ -0,0 +1,6 @@
1
+ import { PostgresDialect } from '../postgres/postgresDialect.js';
2
+ /** Postgres as PGlite runs it, which binds fewer values per statement than a server. */
3
+ export class PgliteDialect extends PostgresDialect {
4
+ /** Past 32767 PGlite answers no rows, and wrong ones from then on, where a server takes 65535. */
5
+ maxBindValues = 32767;
6
+ }
@@ -1,7 +1,7 @@
1
1
  import type { PGliteOptions } from '@electric-sql/pglite';
2
- import { PostgresDialect } from '../postgres/postgresDialect.js';
3
2
  import { AbstractSharedHandleQuerierPool } from '../querier/abstractSharedHandleQuerierPool.js';
4
3
  import type { ExtraOptions } from '../type/index.js';
4
+ import { PgliteDialect } from './pgliteDialect.js';
5
5
  import { type PgliteDatabase, PgliteQuerier } from './pgliteQuerier.js';
6
6
  /** PGlite's own options but `dataDir`, the pool's first argument; `extensions: { vector }` enables pgvector. Type-only. */
7
7
  export type PglitePoolOptions = Omit<PGliteOptions, 'dataDir'>;
@@ -10,7 +10,7 @@ export type PglitePoolOptions = Omit<PGliteOptions, 'dataDir'>;
10
10
  * the open transaction, so a unit of work needing its own needs its own pool. Transactions are plain
11
11
  * statements, so pass `relaxedDurability` on a persistent `dataDir` to skip a flush per statement.
12
12
  */
13
- export declare class PgliteQuerierPool extends AbstractSharedHandleQuerierPool<PgliteDatabase, PgliteQuerier, PostgresDialect> {
13
+ export declare class PgliteQuerierPool extends AbstractSharedHandleQuerierPool<PgliteDatabase, PgliteQuerier, PgliteDialect> {
14
14
  readonly dataDir: string;
15
15
  readonly opts?: PglitePoolOptions | undefined;
16
16
  constructor(dataDir?: string, opts?: PglitePoolOptions | undefined, extra?: ExtraOptions);
@@ -1,8 +1,8 @@
1
1
  import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
2
- import { PostgresDialect } from '../postgres/postgresDialect.js';
3
2
  import { AbstractSharedHandleQuerierPool } from '../querier/abstractSharedHandleQuerierPool.js';
4
3
  import { decodeDate } from '../util/date.js';
5
4
  import { decodeWideNumber } from '../util/wideNumber.js';
5
+ import { PgliteDialect } from './pgliteDialect.js';
6
6
  import { PgliteQuerier } from './pgliteQuerier.js';
7
7
  /**
8
8
  * A pool for PGlite, Postgres in WASM in this process, on one connection. A second `BEGIN` silently joins
@@ -13,7 +13,7 @@ export class PgliteQuerierPool extends AbstractSharedHandleQuerierPool {
13
13
  dataDir;
14
14
  opts;
15
15
  constructor(dataDir = 'memory://', opts, extra) {
16
- super(new PostgresDialect(dialectOptionsFrom(extra)), extra);
16
+ super(new PgliteDialect(dialectOptionsFrom(extra)), extra);
17
17
  this.dataDir = dataDir;
18
18
  this.opts = opts;
19
19
  }
@@ -5,9 +5,7 @@ export interface PgAnyClient {
5
5
  rows: RawRow[];
6
6
  rowCount: number | null;
7
7
  }>;
8
- query(stream: object): AsyncIterable<RawRow> & {
9
- destroy(): void;
10
- };
8
+ query(stream: object): AsyncIterable<RawRow>;
11
9
  /** Any truthy argument makes `pg-pool` evict the client instead of returning it to the idle list. */
12
10
  release(discard?: boolean): void | Promise<void>;
13
11
  }
@@ -18,6 +16,6 @@ export interface PgAnyClient {
18
16
  export declare class PgQuerier<C extends PgAnyClient = PgAnyClient> extends AbstractPoolQuerier<C> {
19
17
  internalAll<T>(query: string, values?: unknown[]): Promise<T[]>;
20
18
  internalRun(query: string, values?: unknown[]): Promise<import("../type/query.js").QueryUpdateResult>;
21
- internalStream<T>(query: string, values?: unknown[]): AsyncGenerator<Awaited<T>, void, unknown>;
19
+ internalStream(query: string, values?: unknown[]): AsyncGenerator<RawRow, void, any>;
22
20
  protected releaseConn(conn: C, discard: boolean): Promise<void>;
23
21
  }
@@ -14,15 +14,7 @@ export class PgQuerier extends AbstractPoolQuerier {
14
14
  }
15
15
  async *internalStream(query, values) {
16
16
  const { default: QueryStream } = await import('pg-query-stream');
17
- const stream = this.getConn().query(new QueryStream(query, values));
18
- try {
19
- for await (const row of stream) {
20
- yield row;
21
- }
22
- }
23
- finally {
24
- stream.destroy();
25
- }
17
+ yield* this.getConn().query(new QueryStream(query, values));
26
18
  }
27
19
  async releaseConn(conn, discard) {
28
20
  await conn.release(discard);
@@ -1,8 +1,9 @@
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 {
6
+ #private;
6
7
  readonly extra?: ExtraOptions | undefined;
7
8
  /**
8
9
  * Internal promise used to queue database operations.
@@ -43,11 +44,22 @@ export declare abstract class AbstractQuerier implements Querier {
43
44
  * or pipeline. [The design](../../../../architecture/relations-in-one-statement.md).
44
45
  */
45
46
  protected abstract internalFindMany<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<E[]>;
46
- /** Stream records with the relations and counts `findMany` reads, the entity passed first or as `$entity`. No hooks fire. */
47
+ /**
48
+ * Stream records with the relations and counts `findMany` reads, the entity passed first or as `$entity`.
49
+ * `afterLoad` runs on each row as it arrives, and the querier runs nothing else until the loop ends.
50
+ */
47
51
  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>(q: QueryProjected<E, S, V, X, P, C> & {
48
52
  $entity: Type<E>;
49
53
  }, opts?: QueryOptions): AsyncIterable<QueryFindResult<E, S, V, X, P, C>>;
50
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
+ /**
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.
61
+ */
62
+ private holdWhileReading;
51
63
  protected abstract internalFindManyStream<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): AsyncIterable<E>;
52
64
  /** Find many records and count every match, the entity passed first or as the query's `$entity`. */
53
65
  findManyAndCount<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>(q: QueryProjected<E, S, V, X, P, C> & {
@@ -89,9 +101,9 @@ export declare abstract class AbstractQuerier implements Querier {
89
101
  * same rows the statement wrote.
90
102
  */
91
103
  insertMany<E extends object>(entity: Type<E>, payload: readonly EntityWrite<E>[]): Promise<(WrittenId<E> | undefined)[]>;
92
- /** Fills and guards `rows`, then writes them: an insert, and the insert half of a guarded upsert. */
104
+ /** Fills and guards `rows`, then writes them and their relations: an insert, and the insert half of a read upsert. */
93
105
  private insertRows;
94
- /** Writes `rows`, and onto each one the key the database generated for it, where it can tell. */
106
+ /** Writes `rows`, its columns only, and onto each one the key the database generated for it, where it can tell. */
95
107
  protected abstract internalInsertMany<E extends object>(entity: Type<E>, rows: EntityData<E>[]): Promise<void>;
96
108
  updateOneById<E extends object>(entity: Type<E>, id: EntityId<E>, payload: UpdateWrite<E>, opts?: QueryOptions): Promise<number>;
97
109
  /** Settles the rows first where the update cascades, so a payload changing what `$where` reads still names them. */
@@ -127,16 +139,16 @@ export declare abstract class AbstractQuerier implements Querier {
127
139
  */
128
140
  private unversionedUpdate;
129
141
  /** 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. */
130
- upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityWrite<E>, opts?: UpsertOptions<E>): Promise<QueryUpsertOneResult<E>>;
131
- upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: readonly EntityWrite<E>[], opts?: UpsertOptions<E>): Promise<QueryUpsertManyResult<E>>;
142
+ upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityWrite<E>, update?: UpdateWrite<E>): Promise<QueryUpsertOneResult<E>>;
143
+ upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: readonly EntityWrite<E>[], update?: UpdateWrite<E>): Promise<QueryUpsertManyResult<E>>;
132
144
  /**
133
- * An upsert on an entity a `security` filter guards. `ON CONFLICT` updates the conflicting row whoever
134
- * it belongs to, so the rows the conflict names are read through the filter: those found update, the
135
- * rest insert, where another tenant's row fails on its key. See architecture/security-filter-writes.md.
145
+ * An upsert as a read, then writes: the rows the conflict names are read through the filters, those found update
146
+ * as `updateMany` does and the rest insert, so either branch writes its relations and a guarded row stays its
147
+ * tenant's. A row inserted concurrently fails on its key. See architecture/security-filter-writes.md.
136
148
  */
137
- private guardedUpsert;
138
- protected abstract internalUpsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E, opts: UpsertOptions<E>): Promise<QueryUpdateResult>;
139
- protected abstract internalUpsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E[], opts: UpsertOptions<E>): Promise<QueryUpdateResult>;
149
+ private readThenUpsert;
150
+ protected abstract internalUpsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E, update?: UpdatePayload<E>): Promise<QueryUpdateResult>;
151
+ protected abstract internalUpsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E[], update?: UpdatePayload<E>): Promise<QueryUpdateResult>;
140
152
  deleteOneById<E extends object>(entity: Type<E>, id: EntityId<E>, opts?: QueryOptions): Promise<number>;
141
153
  /** Delete records matching the query, the entity passed first or as `$entity`; soft-deletes unless `opts.hardDelete`. */
142
154
  deleteMany<E extends object>(q: QuerySearch<E> & {
@@ -153,7 +165,7 @@ export declare abstract class AbstractQuerier implements Querier {
153
165
  */
154
166
  saveMany<E extends object>(entity: Type<E>, payload: readonly EntityWrite<E>[]): Promise<(WrittenId<E> | undefined)[]>;
155
167
  /** Writes each inserted row's relations, one set of statements per relation whatever the number of rows. */
156
- protected insertRelations<E extends object>(entity: Type<E>, rows: E[]): Promise<void>;
168
+ private insertRelations;
157
169
  /** `EntityId` because a settled composite row is an object, which {@link childrenOf} reads each foreign key column out of. */
158
170
  private deleteRelations;
159
171
  /**
@@ -197,6 +209,11 @@ export declare abstract class AbstractQuerier implements Querier {
197
209
  protected serialize<T>(task: () => Promise<T>): Promise<T>;
198
210
  /** Runs `task`, logs `query` with its duration, and tags a failure with it: a method, since a decorator would lose the generics. */
199
211
  protected timed<T>(query: string, values: readonly unknown[] | undefined, task: () => Promise<T>): Promise<T>;
212
+ /**
213
+ * `rows` as {@link timed} runs a statement: logged once they end, timed to the first row since the
214
+ * time after it is the loop's, and a failure tagged with `query`.
215
+ */
216
+ protected timedStream<T>(query: string, values: readonly unknown[] | undefined, rows: AsyncIterable<T>): AsyncGenerator<T>;
200
217
  beginTransaction(opts?: TransactionOptions): Promise<void>;
201
218
  /** Strict: this is the check that catches a forgotten `beginTransaction`. */
202
219
  commitTransaction(): Promise<void>;
@@ -210,8 +227,9 @@ export declare abstract class AbstractQuerier implements Querier {
210
227
  /** Commits the open transaction on the engine, or rolls it back when `commit` is false. */
211
228
  protected abstract endTransaction(commit: boolean): Promise<void>;
212
229
  /**
213
- * Rolls back an unfinished transaction, then hands the connection back, discarding it if the rollback
214
- * failed. Never throws first, since `await using` has no other way to release.
230
+ * Closes a stream left open and rolls back an unfinished transaction, then hands the connection back,
231
+ * discarding it if either failed: the pool would otherwise take one still reading. Never throws first,
232
+ * since `await using` has no other way to release.
215
233
  */
216
234
  release(): Promise<void>;
217
235
  [Symbol.asyncDispose](): Promise<void>;