uql-orm 0.95.0 → 0.96.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 (80) hide show
  1. package/dist/browser/uql-browser.min.js +2 -2
  2. package/dist/browser/uql-browser.min.js.map +3 -3
  3. package/dist/d1/d1Querier.d.ts +2 -0
  4. package/dist/d1/d1Querier.js +4 -0
  5. package/dist/dialect/abstractSqlDialect.d.ts +4 -4
  6. package/dist/dialect/abstractSqlDialect.js +28 -20
  7. package/dist/dialect/mysqlLikeSqlDialect.js +3 -6
  8. package/dist/dialect/pgLikeSqlDialect.d.ts +2 -2
  9. package/dist/dialect/pgLikeSqlDialect.js +4 -4
  10. package/dist/dialect/queryContext.d.ts +0 -2
  11. package/dist/dialect/queryContext.js +0 -6
  12. package/dist/libsql/libsqlDialect.d.ts +4 -1
  13. package/dist/libsql/libsqlDialect.js +4 -1
  14. package/dist/libsql/libsqlQuerierPool.d.ts +1 -1
  15. package/dist/libsql/libsqlQuerierPool.js +1 -1
  16. package/dist/maria/mariadbQuerier.d.ts +4 -0
  17. package/dist/maria/mariadbQuerier.js +14 -2
  18. package/dist/maria/mariadbQuerierPool.js +1 -1
  19. package/dist/migrate/bin.js +2 -4
  20. package/dist/migrate/cli.js +8 -4
  21. package/dist/migrate/codegen/entityTypes.js +6 -15
  22. package/dist/migrate/ddl/indexDdl.d.ts +1 -6
  23. package/dist/migrate/ddl/indexDdl.js +0 -10
  24. package/dist/migrate/ddl/mysqlIndexDdl.d.ts +5 -5
  25. package/dist/migrate/ddl/mysqlIndexDdl.js +11 -6
  26. package/dist/migrate/ddl/tableDdl.d.ts +8 -2
  27. package/dist/migrate/ddl/tableDdl.js +11 -3
  28. package/dist/migrate/drift/driftDetector.js +2 -10
  29. package/dist/migrate/introspection/sqliteIntrospector.d.ts +1 -1
  30. package/dist/migrate/introspection/sqliteIntrospector.js +4 -7
  31. package/dist/migrate/migrator.d.ts +2 -4
  32. package/dist/migrate/migrator.js +12 -20
  33. package/dist/migrate/schemaGenerator.d.ts +5 -0
  34. package/dist/migrate/schemaGenerator.js +18 -9
  35. package/dist/mongo/mongoDialect.d.ts +2 -2
  36. package/dist/mongo/mongoDialect.js +2 -3
  37. package/dist/mongo/mongoIntrospector.js +3 -4
  38. package/dist/mongo/mongoMigrationStorage.d.ts +2 -3
  39. package/dist/mongo/mongoMigrationStorage.js +2 -3
  40. package/dist/mongo/mongoSchemaGenerator.d.ts +6 -4
  41. package/dist/mongo/mongoSchemaGenerator.js +5 -10
  42. package/dist/mongo/mongodbQuerier.js +1 -1
  43. package/dist/mssql/mssqlDialect.d.ts +1 -1
  44. package/dist/mssql/mssqlDialect.js +1 -1
  45. package/dist/mssql/mssqlQuerier.d.ts +6 -3
  46. package/dist/mssql/mssqlQuerier.js +6 -8
  47. package/dist/mssql/mssqlQuerierPool.d.ts +1 -5
  48. package/dist/mssql/mssqlQuerierPool.js +21 -10
  49. package/dist/mysql/mysql2Querier.d.ts +5 -1
  50. package/dist/mysql/mysql2Querier.js +8 -5
  51. package/dist/mysql/mysql2QuerierPool.d.ts +0 -1
  52. package/dist/mysql/mysql2QuerierPool.js +6 -18
  53. package/dist/pglite/pgliteQuerier.d.ts +2 -2
  54. package/dist/pglite/pgliteQuerier.js +1 -1
  55. package/dist/postgres/abstractPgQuerierPool.d.ts +3 -2
  56. package/dist/postgres/abstractPgQuerierPool.js +3 -0
  57. package/dist/postgres/pgQuerier.d.ts +1 -0
  58. package/dist/querier/abstractQuerier.d.ts +10 -5
  59. package/dist/querier/abstractQuerier.js +44 -37
  60. package/dist/querier/abstractSqlQuerier.d.ts +4 -3
  61. package/dist/querier/abstractSqlQuerier.js +46 -41
  62. package/dist/schema/indexColumns.d.ts +8 -0
  63. package/dist/schema/indexColumns.js +28 -0
  64. package/dist/schema/indexDifferences.js +4 -7
  65. package/dist/schema/schemaASTBuilder.js +18 -23
  66. package/dist/schema/sqlExpression.d.ts +2 -2
  67. package/dist/schema/sqlExpression.js +2 -2
  68. package/dist/sqlite/hranaQuerier.d.ts +5 -6
  69. package/dist/sqlite/sqliteDialect.d.ts +1 -1
  70. package/dist/sqlite/sqliteDialect.js +1 -1
  71. package/dist/turso/tursoDialect.d.ts +3 -3
  72. package/dist/turso/tursoDialect.js +5 -10
  73. package/dist/type/dialect.d.ts +7 -3
  74. package/dist/type/entity.d.ts +2 -2
  75. package/dist/type/migration.d.ts +2 -9
  76. package/dist/util/object.util.js +3 -0
  77. package/dist/util/sql.util.d.ts +0 -2
  78. package/dist/util/sql.util.js +0 -6
  79. package/package.json +6 -6
  80. package/skills/uql-orm/SKILL.md +2 -2
@@ -2,6 +2,8 @@ import type { AnyMigrationOperation } from '../migrate/builder/types.js';
2
2
  import type { TableNode } from '../schema/types.js';
3
3
  import { type CreateSchemaOptions, type EntityWhereMeta, type IndexSchema, type NamingStrategy, type SchemaDiff, type SchemaGenerator, type Type } from '../type/index.js';
4
4
  import { MongoDialect } from './mongoDialect.js';
5
+ /** MongoDB runs no trigger within a write, and a write to an entity declaring one is refused, so there is none to reconcile. */
6
+ declare const noTriggers: () => string[];
5
7
  export declare class MongoSchemaGenerator extends MongoDialect implements SchemaGenerator {
6
8
  /** Takes no default foreign key action, since a document store has no foreign keys. */
7
9
  constructor(namingStrategy?: NamingStrategy);
@@ -36,10 +38,9 @@ export declare class MongoSchemaGenerator extends MongoDialect implements Schema
36
38
  generateDropTable(tableName: string): string;
37
39
  /** A collection's indexes: each dropped, then each created, an alter as both. */
38
40
  generateAlterTable(diff: SchemaDiff): string[];
39
- /** MongoDB runs no trigger within a write, and a write to an entity declaring one is refused, so there is none to reconcile. */
40
- generateTriggers(): string[];
41
- generateTriggersDown(): string[];
42
- generateTriggerDrops(): string[];
41
+ readonly generateTriggers: typeof noTriggers;
42
+ readonly generateTriggersDown: typeof noTriggers;
43
+ readonly generateTriggerDrops: typeof noTriggers;
43
44
  private dropIndexCommand;
44
45
  /** An index as MongoDB's key spec (`-1` descending, `'text'` full-text), refusing the SQL-only options. */
45
46
  generateCreateIndex(tableName: string, index: IndexSchema): string;
@@ -50,3 +51,4 @@ export declare class MongoSchemaGenerator extends MongoDialect implements Schema
50
51
  generateOperation(operation: AnyMigrationOperation): string[];
51
52
  diffSchema(entity: Type<object>, currentTable: TableNode | undefined): SchemaDiff | undefined;
52
53
  }
54
+ export {};
@@ -23,6 +23,8 @@ const ATLAS_SIMILARITY = {
23
23
  l2: 'euclidean',
24
24
  inner: 'dotProduct',
25
25
  };
26
+ /** MongoDB runs no trigger within a write, and a write to an entity declaring one is refused, so there is none to reconcile. */
27
+ const noTriggers = () => [];
26
28
  export class MongoSchemaGenerator extends MongoDialect {
27
29
  /** Takes no default foreign key action, since a document store has no foreign keys. */
28
30
  constructor(namingStrategy) {
@@ -116,16 +118,9 @@ export class MongoSchemaGenerator extends MongoDialect {
116
118
  ...sides(diff.indexes, 'to').map((index) => this.generateCreateIndex(diff.tableName, index)),
117
119
  ];
118
120
  }
119
- /** MongoDB runs no trigger within a write, and a write to an entity declaring one is refused, so there is none to reconcile. */
120
- generateTriggers() {
121
- return [];
122
- }
123
- generateTriggersDown() {
124
- return [];
125
- }
126
- generateTriggerDrops() {
127
- return [];
128
- }
121
+ generateTriggers = noTriggers;
122
+ generateTriggersDown = noTriggers;
123
+ generateTriggerDrops = noTriggers;
129
124
  dropIndexCommand(tableName, index) {
130
125
  return index.type === 'vectorSearch'
131
126
  ? serializeMongoCommand({ action: 'dropSearchIndex', collection: tableName, name: index.name })
@@ -260,7 +260,7 @@ export class MongodbQuerier extends AbstractQuerier {
260
260
  }));
261
261
  // Read off the document as written, which carries its `_id` on either branch.
262
262
  const { id, created } = this.upserted(res);
263
- return { ids: [id], changes: id === undefined ? 0 : 1, created };
263
+ return { ids: [id], changes: 1, created };
264
264
  });
265
265
  }
266
266
  async internalUpsertMany(entity, conflictPaths, payload, update) {
@@ -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.";
@@ -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.';
@@ -12,7 +12,7 @@ type MsSqlResult = {
12
12
  };
13
13
  /** The part of the `Readable` a request streams into that a querier drives. */
14
14
  type MsSqlRowStream = AsyncIterable<RawRow> & {
15
- destroy(error: Error): unknown;
15
+ destroy(error: unknown): unknown;
16
16
  on(event: 'error', listener: (error: Error) => void): unknown;
17
17
  };
18
18
  /** The part of an `mssql` `Request` a querier drives. */
@@ -59,7 +59,10 @@ export declare class MsSqlQuerier extends AbstractPoolQuerier<MsSqlConnection> {
59
59
  protected internalBegin(opts?: TransactionOptions): Promise<void>;
60
60
  protected internalCommit(): Promise<void>;
61
61
  protected internalRollback(): Promise<void>;
62
- /** The pool owns the socket; releasing a querier only drops this one's claim on it. */
63
- protected releaseConn(_conn: MsSqlConnection, _discard: boolean): Promise<void>;
62
+ /**
63
+ * The pool owns the socket, so there is nothing to hand back: `release` has already rolled back a
64
+ * transaction left open, and commit and rollback both drop the `Transaction` they end.
65
+ */
66
+ protected releaseConn(): Promise<void>;
64
67
  }
65
68
  export {};
@@ -43,7 +43,7 @@ export class MsSqlQuerier extends AbstractPoolQuerier {
43
43
  const request = this.#request(values);
44
44
  const rows = request.toReadableStream();
45
45
  const completed = request.query(query).catch((err) => {
46
- rows.destroy(err instanceof Error ? err : new Error(String(err)));
46
+ rows.destroy(err);
47
47
  });
48
48
  try {
49
49
  yield* rows;
@@ -76,13 +76,11 @@ export class MsSqlQuerier extends AbstractPoolQuerier {
76
76
  this.#transaction = undefined;
77
77
  await transaction?.rollback();
78
78
  }
79
- /** The pool owns the socket; releasing a querier only drops this one's claim on it. */
80
- async releaseConn(_conn, _discard) {
81
- const transaction = this.#transaction;
82
- this.#transaction = undefined;
83
- // A querier handed back mid-transaction would otherwise leave it open on a pooled connection.
84
- await transaction?.rollback().catch(() => undefined);
85
- }
79
+ /**
80
+ * The pool owns the socket, so there is nothing to hand back: `release` has already rolled back a
81
+ * transaction left open, and commit and rollback both drop the `Transaction` they end.
82
+ */
83
+ async releaseConn() { }
86
84
  }
87
85
  /** The driver's constant for each level UQL names; total, so a new level is a compile error here. */
88
86
  const ISOLATION = {
@@ -7,11 +7,7 @@ export declare class MsSqlQuerierPool extends AbstractSqlQuerierPool<MsSqlQuerie
7
7
  #private;
8
8
  readonly pool: ConnectionPool;
9
9
  constructor(opts: MsSqlConfig, extra?: ExtraOptions);
10
- /**
11
- * `mssql` connects the pool as a whole rather than per checkout, so the promise is shared. A
12
- * failed one is dropped rather than kept: memoized, a single transient failure would be handed to
13
- * every later caller for the life of the pool.
14
- */
15
10
  getQuerier(): Promise<MsSqlQuerier>;
11
+ /** `mssql` refuses to close a pool mid-connect, so the connect under way settles first. */
16
12
  end(): Promise<void>;
17
13
  }
@@ -2,33 +2,44 @@ import { ConnectionPool } from 'mssql';
2
2
  import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
3
3
  import { AbstractSqlQuerierPool } from '../querier/index.js';
4
4
  import { attachPoolErrorHandler } from '../util/index.js';
5
+ import { UqlUsageError } from '../util/uqlError.js';
5
6
  import { MsSqlDialect } from './mssqlDialect.js';
6
7
  import { MsSqlQuerier } from './mssqlQuerier.js';
7
8
  export class MsSqlQuerierPool extends AbstractSqlQuerierPool {
8
9
  pool;
9
- #connected;
10
+ /** The whole pool's one connect, shared by every querier; `ended` once closed, since `mssql` would reconnect it. */
11
+ #connection;
10
12
  constructor(opts, extra) {
11
13
  super(new MsSqlDialect(dialectOptionsFrom(extra)), extra);
12
14
  this.pool = new ConnectionPool(opts);
13
15
  attachPoolErrorHandler(this.pool, 'Idle SQL Server pool connection encountered an error', extra?.logger);
14
16
  }
15
- /**
16
- * `mssql` connects the pool as a whole rather than per checkout, so the promise is shared. A
17
- * failed one is dropped rather than kept: memoized, a single transient failure would be handed to
18
- * every later caller for the life of the pool.
19
- */
20
17
  async getQuerier() {
21
18
  return new MsSqlQuerier(() => this.#connect(), this.dialect, this.extra);
22
19
  }
20
+ /** A failed connect is forgotten rather than handed to every later caller, unless `end` came first. */
23
21
  #connect() {
24
- this.#connected ??= this.pool.connect().catch((err) => {
25
- this.#connected = undefined;
22
+ const current = this.#connection;
23
+ if (current) {
24
+ if (current === 'ended') {
25
+ return Promise.reject(new UqlUsageError('Cannot use a pool after calling end on it'));
26
+ }
27
+ return current;
28
+ }
29
+ const connecting = this.pool.connect().catch((err) => {
30
+ if (this.#connection === connecting) {
31
+ this.#connection = undefined;
32
+ }
26
33
  throw err;
27
34
  });
28
- return this.#connected;
35
+ this.#connection = connecting;
36
+ return connecting;
29
37
  }
38
+ /** `mssql` refuses to close a pool mid-connect, so the connect under way settles first. */
30
39
  async end() {
31
- this.#connected = undefined;
40
+ const connecting = this.#connection;
41
+ this.#connection = 'ended';
42
+ await Promise.allSettled([connecting]);
32
43
  await this.pool.close();
33
44
  }
34
45
  }
@@ -1,5 +1,9 @@
1
- import type { PoolConnection } from 'mysql2/promise';
1
+ import type { PoolConnection } from 'mysql2';
2
2
  import { AbstractPoolQuerier } from '../querier/abstractPoolQuerier.js';
3
+ /**
4
+ * Holds the driver's own connection rather than its promise wrapper, whose types name the connection
5
+ * inside it a promise one too: streaming is the own connection's alone.
6
+ */
3
7
  export declare class MySql2Querier extends AbstractPoolQuerier<PoolConnection> {
4
8
  internalAll<T>(query: string, values?: unknown[]): Promise<T[]>;
5
9
  internalRun(query: string, values?: unknown[]): Promise<import("../index.js").QueryUpdateResult>;
@@ -1,11 +1,15 @@
1
1
  import { AbstractPoolQuerier } from '../querier/abstractPoolQuerier.js';
2
+ /**
3
+ * Holds the driver's own connection rather than its promise wrapper, whose types name the connection
4
+ * inside it a promise one too: streaming is the own connection's alone.
5
+ */
2
6
  export class MySql2Querier extends AbstractPoolQuerier {
3
7
  async internalAll(query, values) {
4
- const [res] = await this.getConn().query(query, values);
8
+ const [res] = await this.getConn().promise().query(query, values);
5
9
  return res;
6
10
  }
7
11
  async internalRun(query, values) {
8
- const [res] = (await this.getConn().query(query, values));
12
+ const [res] = await this.getConn().promise().query(query, values);
9
13
  return this.buildUpdateResult({
10
14
  changes: res.affectedRows,
11
15
  id: res.insertId,
@@ -13,8 +17,7 @@ export class MySql2Querier extends AbstractPoolQuerier {
13
17
  });
14
18
  }
15
19
  async *internalStream(query, values) {
16
- const rawConn = this.getConn().connection;
17
- yield* rawConn.query(query, values).stream();
20
+ yield* this.getConn().query(query, values).stream();
18
21
  }
19
22
  async releaseConn(conn, discard) {
20
23
  // mysql2 resets nothing on release, so a connection the pool takes back after a failed rollback
@@ -23,6 +26,6 @@ export class MySql2Querier extends AbstractPoolQuerier {
23
26
  conn.destroy();
24
27
  return;
25
28
  }
26
- await conn.release();
29
+ conn.release();
27
30
  }
28
31
  }
@@ -4,7 +4,6 @@ import type { ExtraOptions } from '../type/index.js';
4
4
  import { MySql2Querier } from './mysql2Querier.js';
5
5
  import { MySqlDialect } from './mysqlDialect.js';
6
6
  export declare class MySql2QuerierPool extends AbstractSqlQuerierPool<MySql2Querier, MySqlDialect> {
7
- #private;
8
7
  readonly pool: Pool;
9
8
  constructor(opts: PoolOptions, extra?: ExtraOptions);
10
9
  getQuerier(): Promise<MySql2Querier>;
@@ -1,3 +1,4 @@
1
+ import { promisify } from 'node:util';
1
2
  import { createPool } from 'mysql2/promise';
2
3
  import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
3
4
  import { AbstractSqlQuerierPool } from '../querier/index.js';
@@ -5,32 +6,19 @@ import { MySql2Querier } from './mysql2Querier.js';
5
6
  import { MySqlDialect } from './mysqlDialect.js';
6
7
  export class MySql2QuerierPool extends AbstractSqlQuerierPool {
7
8
  pool;
8
- #utcSessions = new WeakSet();
9
9
  constructor(opts, extra) {
10
10
  super(new MySqlDialect(dialectOptionsFrom(extra)), extra);
11
11
  // A BIGINT past 2^53 as its exact text rather than a rounded number, the rule every driver here
12
12
  // decodes by (`decodeWideNumber`); within that range it stays a number, and DECIMAL is untouched.
13
13
  // A date reads as the UTC it holds, whichever zone the process runs in.
14
14
  this.pool = createPool({ supportBigNumbers: true, timezone: 'Z', ...opts });
15
+ // The session in UTC too, so `NOW()` agrees with a bound date: queued as each connection opens, ahead of
16
+ // any statement on it. One that fails has lost its connection, which the next statement reports.
17
+ this.pool.pool.on('connection', (connection) => connection.query("SET time_zone = '+00:00'", () => { }));
15
18
  }
16
19
  async getQuerier() {
17
- return new MySql2Querier(() => this.#connection(), this.dialect, this.extra);
18
- }
19
- /** A connection whose session is UTC too, so `NOW()` agrees with a bound date: set once per connection. */
20
- async #connection() {
21
- const connection = await this.pool.getConnection();
22
- if (this.#utcSessions.has(connection.connection)) {
23
- return connection;
24
- }
25
- try {
26
- await connection.query("SET time_zone = '+00:00'");
27
- }
28
- catch (error) {
29
- connection.release();
30
- throw error;
31
- }
32
- this.#utcSessions.add(connection.connection);
33
- return connection;
20
+ const { pool } = this.pool;
21
+ return new MySql2Querier(promisify(pool.getConnection.bind(pool)), this.dialect, this.extra);
34
22
  }
35
23
  async end() {
36
24
  await this.pool.end();
@@ -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. */
@@ -21,7 +21,7 @@ export class PgliteQuerier extends AbstractSqlQuerier {
21
21
  const res = await this.db.query(query, values);
22
22
  // `affectedRows`, not `rowCount`: PGlite derives the former from the command tag of a write only,
23
23
  // where the latter also counts a `SELECT`'s rows and is absent altogether from a DDL tag.
24
- return this.buildUpdateResult({ rows: res.rows, changes: res.affectedRows ?? 0 });
24
+ return this.buildUpdateResult({ rows: res.rows, changes: res.affectedRows });
25
25
  }
26
26
  /** The handle belongs to the pool, which hands out one querier per unit of work over it. */
27
27
  async internalRelease() { }
@@ -1,11 +1,12 @@
1
1
  import type { AbstractSqlDialect } from '../dialect/index.js';
2
2
  import { AbstractSqlQuerierPool } from '../querier/index.js';
3
3
  import type { ExtraOptions } from '../type/index.js';
4
- import { type ErrorEmittingPool } from '../util/index.js';
5
4
  import { type PgAnyClient, PgQuerier } from './pgQuerier.js';
6
- export interface PgAnyPool<C extends PgAnyClient> extends ErrorEmittingPool {
5
+ export interface PgAnyPool<C extends PgAnyClient> {
7
6
  connect: () => Promise<C>;
8
7
  end: () => Promise<void>;
8
+ on(event: 'error', listener: (err: Error) => void): unknown;
9
+ on(event: 'connect', listener: (client: C) => void): unknown;
9
10
  }
10
11
  /** A Postgres-wire pool of {@link PgQuerier}s, attaching the error handler that keeps a dropped connection from crashing the process. */
11
12
  export declare abstract class AbstractPgQuerierPool<C extends PgAnyClient, D extends AbstractSqlDialect> extends AbstractSqlQuerierPool<PgQuerier<C>, D> {
@@ -8,6 +8,9 @@ export class AbstractPgQuerierPool extends AbstractSqlQuerierPool {
8
8
  super(dialect, extra);
9
9
  this.pool = pool;
10
10
  attachPoolErrorHandler(pool, 'Idle Postgres pool client encountered an error', extra?.logger);
11
+ // A client the server drops while a querier holds it emits `error` with no statement to report it to,
12
+ // which unheard ends the process. The next statement on it fails instead, and the pool evicts it.
13
+ pool.on('connect', (client) => client.on('error', () => { }));
11
14
  }
12
15
  async getQuerier() {
13
16
  return new PgQuerier(() => this.pool.connect(), this.dialect, this.extra);
@@ -6,6 +6,7 @@ export interface PgAnyClient {
6
6
  rowCount: number | null;
7
7
  }>;
8
8
  query(stream: object): AsyncIterable<RawRow>;
9
+ on(event: 'error', listener: (err: Error) => void): unknown;
9
10
  /** Any truthy argument makes `pg-pool` evict the client instead of returning it to the idle list. */
10
11
  release(discard?: boolean): void | Promise<void>;
11
12
  }
@@ -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>;
@@ -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. */
@@ -217,22 +217,17 @@ export class AbstractQuerier {
217
217
  findManyStream(...args) {
218
218
  const [entity, q, opts] = entityArgs(args);
219
219
  this.validateReadQuery(entity, q);
220
- const rows = this.internalFindManyStream(entity, q, opts);
221
- return this.holdWhileReading(this.listensForLoad(entity, q.$populate) ? this.loadedEach(entity, rows, q.$populate) : rows);
222
- }
223
- /** `afterLoad` on each row before the loop sees it, as `findMany` runs it on each row it read. */
224
- async *loadedEach(entity, rows, populate) {
225
- for await (const row of rows) {
226
- await this.emitLoaded(entity, [row], populate);
227
- yield row;
228
- }
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);
229
224
  }
230
225
  /**
231
- * `rows`, holding the querier from the first row asked for until the loop ends. Most drivers queue a
232
- * statement behind an open read, which a loop awaiting it never finishes, so `serialize` refuses one
233
- * 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.
234
229
  */
235
- holdWhileReading(rows) {
230
+ holdWhileReading(rows, loaded) {
236
231
  const read = async function* (querier) {
237
232
  if (querier.#stream) {
238
233
  throw new UqlUsageError(STREAM_HOLDS_QUERIER);
@@ -240,7 +235,12 @@ export class AbstractQuerier {
240
235
  querier.#stream = stream;
241
236
  try {
242
237
  await querier.taskQueue;
243
- yield* rows;
238
+ for await (const row of rows) {
239
+ if (loaded) {
240
+ await loaded(row);
241
+ }
242
+ yield row;
243
+ }
244
244
  }
245
245
  finally {
246
246
  querier.#stream = undefined;
@@ -355,10 +355,7 @@ export class AbstractQuerier {
355
355
  if (!ids.length) {
356
356
  return 0;
357
357
  }
358
- let changes = 0;
359
- for (const batch of chunk(ids, this.dialect.keyListCapacity(meta.ids.length))) {
360
- changes += await this.updateColumns(entity, { $where: whereIds(meta, batch) }, row, opts, batch.length);
361
- }
358
+ const changes = await this.writeBatches(ids, meta.ids.length, (batch) => this.updateColumns(entity, { $where: whereIds(meta, batch) }, row, opts, batch.length));
362
359
  for (const relKey of relKeys) {
363
360
  await this.saveRelation(entity, relKey, ids.map((id) => ({ id, value: row[relKey] })), true);
364
361
  }
@@ -394,6 +391,25 @@ export class AbstractQuerier {
394
391
  const { dialect } = this;
395
392
  return isPagedQuery(q) || (!dialect.features.correlatedWrites && dialect.constrainsRelations(entity, q.$where));
396
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
+ }
397
413
  /** The ids `q` matches, in its own order and page. */
398
414
  async settleIds(entity, q, opts) {
399
415
  const meta = getMeta(entity);
@@ -478,8 +494,7 @@ export class AbstractQuerier {
478
494
  // A found row's key is adopted by the caller; an inserted one carries the key its insert wrote.
479
495
  return { changes, created, ids };
480
496
  };
481
- // One row writes as an insert or an update of it does, with no transaction of its own.
482
- return rows.length === 1 ? write() : this.transaction(write);
497
+ return rows.length === 1 ? write() : this.atomically(write);
483
498
  }
484
499
  async deleteOneById(entity, id, opts) {
485
500
  assertIdValue(entity, id);
@@ -503,14 +518,13 @@ export class AbstractQuerier {
503
518
  return 0;
504
519
  }
505
520
  await this.emitHook(entity, 'beforeDelete', doomed);
506
- let changes = 0;
507
- for (const batch of chunk(ids, this.dialect.keyListCapacity(meta.ids.length))) {
521
+ const changes = await this.writeBatches(ids, meta.ids.length, async (batch) => {
508
522
  // Children first: they hold the foreign key, which a schema without `ON DELETE CASCADE` enforces.
509
523
  if (cascades) {
510
524
  await this.deleteRelations(entity, batch, opts);
511
525
  }
512
- changes += await this.internalDeleteMany(entity, { $where: whereIds(meta, batch) }, opts);
513
- }
526
+ return this.internalDeleteMany(entity, { $where: whereIds(meta, batch) }, opts);
527
+ });
514
528
  await this.emitHook(entity, 'afterDelete', doomed);
515
529
  return changes;
516
530
  }
@@ -563,9 +577,7 @@ export class AbstractQuerier {
563
577
  }
564
578
  }
565
579
  };
566
- // Only a batch carrying both kinds is more than one statement; `transaction` is re-entrant, so
567
- // this is free inside a caller's own.
568
- await (toInsert.length && toUpsert.length ? this.transaction(write) : write());
580
+ await (toInsert.length && toUpsert.length ? this.atomically(write) : write());
569
581
  return ids;
570
582
  }
571
583
  /** Writes each inserted row's relations, one set of statements per relation whatever the number of rows. */
@@ -607,9 +619,7 @@ export class AbstractQuerier {
607
619
  const holder = relOpts.through ? relOpts.through() : relEntity;
608
620
  const parentColumn = soleParentColumn(relOpts);
609
621
  if (isUpdate) {
610
- for (const batch of chunk(writes, this.dialect.keyListCapacity(1))) {
611
- await this.deleteMany(holder, { $where: { [parentColumn]: batch.map(({ id }) => id) } });
612
- }
622
+ await this.writeBatches(writes, 1, (batch) => this.deleteMany(holder, { $where: { [parentColumn]: batch.map(({ id }) => id) } }));
613
623
  }
614
624
  // Each parent gets its own copies, so a row listed for two parents is written twice.
615
625
  const children = writes.flatMap(({ id, value }) => [value ?? []].flat().map((row) => ({ id, row })));
@@ -704,7 +714,9 @@ export class AbstractQuerier {
704
714
  const meta = getMeta(entity);
705
715
  const [idKey] = meta.ids;
706
716
  const keys = getKeys(conflictPaths);
707
- 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()];
708
720
  const found = [];
709
721
  for (const batch of chunk(distinct, this.dialect.keyListCapacity(keys.length))) {
710
722
  const q = { $select: keySet([idKey, ...keys]), $where: whereKeysIn(keys, batch) };
@@ -738,12 +750,7 @@ export class AbstractQuerier {
738
750
  if (!this.hasHook(entity, event))
739
751
  return;
740
752
  for (const listener of this.extra?.listeners ?? []) {
741
- const fn = listener[event];
742
- if (fn) {
743
- const result = fn({ entity, querier: this, payloads, event });
744
- if (result instanceof Promise)
745
- await result;
746
- }
753
+ await listener[event]?.({ entity, querier: this, payloads, event });
747
754
  }
748
755
  await runHooks(entity, event, payloads, { querier: this });
749
756
  }
@@ -23,7 +23,8 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
23
23
  /**
24
24
  * The `auto_increment_increment` stride used to infer the ids of a multi-row insert from the
25
25
  * single id the driver reports (MySQL, which has no `RETURNING`). It is 1 on a standalone server
26
- * but can be higher on a cluster (e.g. Galera). Only called for `firstId` dialects.
26
+ * but can be higher on a cluster (e.g. Galera), and `buildUpdateResult` takes any other as 1.
27
+ * Only called for `firstId` dialects.
27
28
  */
28
29
  protected loadInsertIdIncrement(): Promise<number>;
29
30
  /**
@@ -81,8 +82,8 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
81
82
  private hydrateFields;
82
83
  /**
83
84
  * Runs a statement whose one row carries a {@link AGGREGATE_VALUE_ALIAS} column. `Number` because `COUNT(*)` is BIGINT and
84
- * a caller supplying their own `types` replaces the decoding the pools do at the wire; `?? 0` because
85
- * a catalog that does not know the table answers with no row, which is nothing counted.
85
+ * a caller supplying their own `types` replaces the decoding the pools do at the wire, and reads a `NULL`
86
+ * as 0; no row is 0 too, since a catalog that does not know the table answers with none.
86
87
  */
87
88
  private runCount;
88
89
  protected internalCount<E extends object>(entity: Type<E>, q: QueryPage<E>, opts?: QueryOptions): Promise<number>;