uql-orm 0.116.4 → 0.116.5

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.
@@ -3,6 +3,7 @@ import type { PrimaryKey, RawRow } from '../type/index.js';
3
3
  import type { SqlExecution } from '../util/sql.util.js';
4
4
  /** The header a `bun:sql` result carries next to its rows. */
5
5
  export type BunSqlHeader = {
6
+ command?: string;
6
7
  count?: number;
7
8
  affectedRows?: number | null;
8
9
  lastInsertRowid?: PrimaryKey;
@@ -21,7 +22,7 @@ export type BunSqlDialectName = 'postgres' | 'cockroachdb' | 'mysql' | 'mariadb'
21
22
  /**
22
23
  * A `bun:sql` result as the querier reads it: its rows, each BIGINT decoded exactly; the rows it touched,
23
24
  * `affectedRows` on MySQL (whose `count` is 0 on a write) then `count` on Postgres, `undefined` to leave it to
24
- * the rows; and a MySQL-family insert's id, by the same wide-integer rule.
25
+ * the rows; a MySQL-family insert's id, by the same wide-integer rule; and the command tag.
25
26
  */
26
27
  export declare function bunSqlExecution(res: BunSqlResult): SqlExecution;
27
28
  /**
@@ -3,11 +3,16 @@ import { decodeBigInts, decodeWideNumber } from '../util/wideNumber.js';
3
3
  /**
4
4
  * A `bun:sql` result as the querier reads it: its rows, each BIGINT decoded exactly; the rows it touched,
5
5
  * `affectedRows` on MySQL (whose `count` is 0 on a write) then `count` on Postgres, `undefined` to leave it to
6
- * the rows; and a MySQL-family insert's id, by the same wide-integer rule.
6
+ * the rows; a MySQL-family insert's id, by the same wide-integer rule; and the command tag.
7
7
  */
8
8
  export function bunSqlExecution(res) {
9
9
  const id = typeof res.lastInsertRowid === 'bigint' ? decodeWideNumber(res.lastInsertRowid) : res.lastInsertRowid;
10
- return { rows: Array.from(res, decodeBigInts), changes: res.affectedRows || res.count || undefined, id };
10
+ return {
11
+ rows: Array.from(res, decodeBigInts),
12
+ changes: res.affectedRows || res.count || undefined,
13
+ id,
14
+ command: res.command,
15
+ };
11
16
  }
12
17
  /**
13
18
  * Normalizes `SQL.Options` into what Bun's SQL engine expects for a given dialect: the adapter a
@@ -136,7 +136,9 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
136
136
  */
137
137
  readonly maxFunctionArgs: number;
138
138
  /** The statements opening a transaction, its modes inline in the `BEGIN` as the Postgres family takes them. */
139
- getBeginTransactionStatements({ isolationLevel, readOnly }?: TransactionOptions): string[];
139
+ getBeginTransactionStatements(opts?: TransactionOptions): string[];
140
+ /** A transaction's modes as the Postgres family spells them after `BEGIN` or `SET TRANSACTION`, `''` for none. */
141
+ transactionModes({ isolationLevel, readOnly }?: TransactionOptions): string;
140
142
  createContext(options?: QueryContextOptions): QueryContext;
141
143
  /** A statement as it is sent: the SQL `build` writes, or a `sql` renders, and the values it binds. */
142
144
  compile(build: QueryBuildFn | QuerySql): {
@@ -145,10 +145,14 @@ export class AbstractSqlDialect extends VectorSqlDialect {
145
145
  */
146
146
  maxFunctionArgs = Infinity;
147
147
  /** The statements opening a transaction, its modes inline in the `BEGIN` as the Postgres family takes them. */
148
- getBeginTransactionStatements({ isolationLevel, readOnly } = {}) {
148
+ getBeginTransactionStatements(opts) {
149
+ const modes = this.transactionModes(opts);
150
+ return [modes ? `${this.beginTransactionCommand} ${modes}` : this.beginTransactionCommand];
151
+ }
152
+ /** A transaction's modes as the Postgres family spells them after `BEGIN` or `SET TRANSACTION`, `''` for none. */
153
+ transactionModes({ isolationLevel, readOnly } = {}) {
149
154
  const modes = [isolationLevel && `ISOLATION LEVEL ${isolationLevel.toUpperCase()}`, readOnly && 'READ ONLY'];
150
- const inline = modes.filter((mode) => typeof mode === 'string');
151
- return [inline.length ? `${this.beginTransactionCommand} ${inline.join(', ')}` : this.beginTransactionCommand];
155
+ return modes.filter((mode) => typeof mode === 'string').join(', ');
152
156
  }
153
157
  createContext(options = {}) {
154
158
  return new SqlQueryContext(this, [], undefined, options.inlineValues);
@@ -41,7 +41,7 @@ export type MsSqlConnection = {
41
41
  * own pool and hands out `Request`s, so what UQL holds is the pool plus, once a transaction opens,
42
42
  * the `Transaction` every later request has to be bound to.
43
43
  */
44
- export declare class MsSqlQuerier extends AbstractPoolQuerier<MsSqlConnection> {
44
+ export declare class MsSqlQuerier extends AbstractPoolQuerier<MsSqlConnection, MsSqlTransaction> {
45
45
  #private;
46
46
  /**
47
47
  * `rowsAffected` carries one entry per statement, and a write runs in a batch of several - the table variable
@@ -61,8 +61,6 @@ export declare class MsSqlQuerier extends AbstractPoolQuerier<MsSqlConnection> {
61
61
  * the level goes to its `begin`: sent as a statement it would land on whichever connection served it.
62
62
  */
63
63
  protected internalBegin(opts?: TransactionOptions): Promise<void>;
64
- protected internalCommit(): Promise<void>;
65
- protected internalRollback(): Promise<void>;
66
64
  /**
67
65
  * The pool owns the socket, so there is nothing to hand back: `release` has already rolled back a
68
66
  * transaction left open, and commit and rollback both drop the `Transaction` they end.
@@ -8,14 +8,13 @@ import { decodeWireTypes } from './mssqlWireTypes.js';
8
8
  * the `Transaction` every later request has to be bound to.
9
9
  */
10
10
  export class MsSqlQuerier extends AbstractPoolQuerier {
11
- #transaction;
12
11
  /**
13
12
  * Values bind by name, `@p1` upward, matching {@link MsSqlDialect.placeholder}. `mssql` infers a type
14
13
  * from the JS value, right for a `Uint8Array` and harmlessly wrong for a bare `null` (`NVarChar`), but
15
14
  * a `Date` it binds as the legacy `DATETIME`, whose 1/300 s steps no `DATETIME2` column compares equal to.
16
15
  */
17
16
  #request(values) {
18
- const request = this.#transaction ? this.#transaction.request() : this.getConn().request();
17
+ const request = (this.tx ?? this.getConn()).request();
19
18
  values?.forEach((value, index) => {
20
19
  const name = `p${index + 1}`;
21
20
  return value instanceof Date ? request.input(name, mssql.DateTime2, value) : request.input(name, value);
@@ -63,17 +62,7 @@ export class MsSqlQuerier extends AbstractPoolQuerier {
63
62
  async internalBegin(opts) {
64
63
  const transaction = this.getConn().transaction();
65
64
  await transaction.begin(opts?.isolationLevel && mssql.ISOLATION_LEVEL[ISOLATION[opts.isolationLevel]]);
66
- this.#transaction = transaction;
67
- }
68
- async internalCommit() {
69
- const transaction = this.#transaction;
70
- this.#transaction = undefined;
71
- await transaction?.commit();
72
- }
73
- async internalRollback() {
74
- const transaction = this.#transaction;
75
- this.#transaction = undefined;
76
- await transaction?.rollback();
65
+ this.tx = transaction;
77
66
  }
78
67
  /**
79
68
  * The pool owns the socket, so there is nothing to hand back: `release` has already rolled back a
@@ -1,23 +1,52 @@
1
1
  import { type PgResult } from '../postgres/pgExecution.js';
2
- import { AbstractSqlQuerier } from '../querier/index.js';
3
- import type { ExtraOptions } from '../type/index.js';
2
+ import { AbstractSqlQuerier, type TransactionHandle } from '../querier/abstractSqlQuerier.js';
3
+ import type { ExtraOptions, TransactionOptions } from '../type/index.js';
4
4
  import type { SqlExecution } from '../util/sql.util.js';
5
5
  import type { PgliteDialect } from './pgliteDialect.js';
6
- /** The two methods uql uses of `@electric-sql/pglite`, stated so its published types do not depend on a pre-1.0 package. */
7
- export type PgliteDatabase = {
8
- query(query: string, params?: unknown[]): Promise<PgResult>;
6
+ type Decode = (text: string) => unknown;
7
+ /** How one statement's rows decode, by type OID, over the handle's own parsers. */
8
+ export type PgliteQueryOptions = {
9
+ readonly parsers: Readonly<Record<number, Decode>>;
10
+ };
11
+ /** What runs a statement on PGlite: the handle, or a transaction open on it. */
12
+ type PgliteExecutor = {
13
+ query(query: string, params?: unknown[], options?: PgliteQueryOptions): Promise<PgResult>;
14
+ };
15
+ /**
16
+ * The part of `@electric-sql/pglite` uql uses, stated so its published types do not depend on a pre-1.0 package:
17
+ * a `PGlite`, or a `PGliteWorker` sharing one across tabs.
18
+ */
19
+ export type PgliteDatabase = PgliteExecutor & {
20
+ readonly parsers: Readonly<Partial<Record<number, Decode>>>;
21
+ transaction<T>(run: (tx: PgliteOpenTransaction) => Promise<T>): Promise<T>;
9
22
  close(): Promise<void>;
10
23
  };
24
+ /** A transaction PGlite runs a callback in. */
25
+ type PgliteOpenTransaction = PgliteExecutor & {
26
+ rollback(): Promise<void>;
27
+ };
28
+ type PgliteTransaction = PgliteExecutor & TransactionHandle;
11
29
  /**
12
30
  * Querier for PGlite, Postgres compiled to WASM and run in this process.
13
31
  *
14
32
  * @remarks Extends {@link AbstractSqlQuerier} rather than `PgQuerier`, whose stream needs `pg-query-stream`,
15
- * which PGlite's client cannot run. `BEGIN`/`COMMIT` are plain statements on the single connection.
33
+ * which PGlite's client cannot run.
16
34
  */
17
- export declare class PgliteQuerier extends AbstractSqlQuerier {
35
+ export declare class PgliteQuerier extends AbstractSqlQuerier<PgliteTransaction> {
18
36
  readonly db: PgliteDatabase;
19
- constructor(db: PgliteDatabase, dialect: PgliteDialect, extra?: ExtraOptions);
37
+ /** Passed with each statement on a handle the pool did not open, whose own parsers stay its owner's. */
38
+ private readonly queryOptions?;
39
+ constructor(db: PgliteDatabase, dialect: PgliteDialect, extra?: ExtraOptions,
40
+ /** Passed with each statement on a handle the pool did not open, whose own parsers stay its owner's. */
41
+ queryOptions?: PgliteQueryOptions | undefined);
20
42
  /** Every querier of the pool is this one handle's session, so they share its transaction. */
21
43
  protected get connection(): object;
44
+ /** On the transaction its session holds, which only the flow holding it reaches here: every other waits its turn. */
22
45
  protected execute(sql: string, values?: unknown[]): Promise<SqlExecution>;
46
+ /**
47
+ * Through PGlite's own `transaction`, the one lock every caller of the handle respects, another tab's included.
48
+ * One that cannot take its modes is rolled back, or its lock would hold the handle for good.
49
+ */
50
+ protected internalBegin(opts?: TransactionOptions): Promise<void>;
23
51
  }
52
+ export {};
@@ -1,22 +1,73 @@
1
1
  import { pgExecution } from '../postgres/pgExecution.js';
2
- import { AbstractSqlQuerier } from '../querier/index.js';
2
+ import { AbstractSqlQuerier } from '../querier/abstractSqlQuerier.js';
3
+ import { slotOf } from '../querier/transaction.js';
3
4
  /**
4
5
  * Querier for PGlite, Postgres compiled to WASM and run in this process.
5
6
  *
6
7
  * @remarks Extends {@link AbstractSqlQuerier} rather than `PgQuerier`, whose stream needs `pg-query-stream`,
7
- * which PGlite's client cannot run. `BEGIN`/`COMMIT` are plain statements on the single connection.
8
+ * which PGlite's client cannot run.
8
9
  */
9
10
  export class PgliteQuerier extends AbstractSqlQuerier {
10
11
  db;
11
- constructor(db, dialect, extra) {
12
+ queryOptions;
13
+ constructor(db, dialect, extra,
14
+ /** Passed with each statement on a handle the pool did not open, whose own parsers stay its owner's. */
15
+ queryOptions) {
12
16
  super(dialect, extra);
13
17
  this.db = db;
18
+ this.queryOptions = queryOptions;
14
19
  }
15
20
  /** Every querier of the pool is this one handle's session, so they share its transaction. */
16
21
  get connection() {
17
22
  return this.db;
18
23
  }
24
+ /** On the transaction its session holds, which only the flow holding it reaches here: every other waits its turn. */
19
25
  async execute(sql, values) {
20
- return pgExecution(await this.db.query(sql, values));
26
+ const holder = slotOf(this.db).held?.scope.querier;
27
+ const on = (holder instanceof PgliteQuerier && holder.tx) || this.db;
28
+ return pgExecution(await on.query(sql, values, this.queryOptions));
21
29
  }
30
+ /**
31
+ * Through PGlite's own `transaction`, the one lock every caller of the handle respects, another tab's included.
32
+ * One that cannot take its modes is rolled back, or its lock would hold the handle for good.
33
+ */
34
+ async internalBegin(opts) {
35
+ const tx = await hold(this.db);
36
+ const modes = this.dialect.transactionModes(opts);
37
+ if (modes) {
38
+ try {
39
+ await tx.query(`SET TRANSACTION ${modes}`);
40
+ }
41
+ catch (err) {
42
+ await tx.rollback();
43
+ throw err;
44
+ }
45
+ }
46
+ this.tx = tx;
47
+ }
48
+ }
49
+ /**
50
+ * Opens a transaction on `db` that stays open until its handle ends it: PGlite's own runs a callback, which
51
+ * waits here for the commit or rollback. PGlite commits it, refusing one a failed statement aborted.
52
+ */
53
+ async function hold(db) {
54
+ const opened = Promise.withResolvers();
55
+ const decided = Promise.withResolvers();
56
+ const ended = db.transaction(async (tx) => {
57
+ opened.resolve(tx);
58
+ if (!(await decided.promise)) {
59
+ await tx.rollback();
60
+ }
61
+ });
62
+ ended.catch(opened.reject);
63
+ const tx = await opened.promise;
64
+ const end = (commit) => {
65
+ decided.resolve(commit);
66
+ return ended;
67
+ };
68
+ return {
69
+ query: (sql, values, options) => tx.query(sql, values, options),
70
+ commit: () => end(true),
71
+ rollback: () => end(false),
72
+ };
22
73
  }
@@ -5,15 +5,17 @@ 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 = Except<PGliteOptions, 'dataDir'>;
8
+ /** Opens the handle a pool runs on, as a `PGliteWorker` sharing one database across tabs: `() => PGliteWorker.create(worker)`. */
9
+ export type PgliteOpen = () => Promise<PgliteDatabase>;
8
10
  /**
9
- * A pool for PGlite, Postgres in WASM in this process, on one connection. A second `BEGIN` silently joins
10
- * the open transaction, so a unit of work needing its own needs its own pool. Transactions are plain
11
- * statements, so pass `relaxedDurability` on a persistent `dataDir` to skip a flush per statement.
11
+ * A pool for PGlite, Postgres in WASM, on one connection: a `dataDir` it opens, or a handle `open` answers. Its
12
+ * transactions hold PGlite's own lock, which every caller of the handle waits on, another tab's included. Pass
13
+ * `relaxedDurability` on a persistent `dataDir` to skip a flush per statement.
12
14
  */
13
15
  export declare class PgliteQuerierPool extends AbstractSharedHandleQuerierPool<PgliteDatabase, PgliteQuerier, PgliteDialect> {
14
- readonly dataDir: string;
15
- readonly opts?: PglitePoolOptions | undefined;
16
- constructor(dataDir?: string, opts?: PglitePoolOptions | undefined, extra?: ExtraOptions);
16
+ #private;
17
+ constructor(dataDir?: string, opts?: PglitePoolOptions, extra?: ExtraOptions);
18
+ constructor(open: PgliteOpen, extra?: ExtraOptions);
17
19
  protected openDb(): Promise<PgliteDatabase>;
18
20
  protected buildQuerier(db: PgliteDatabase): PgliteQuerier;
19
21
  }
@@ -1,32 +1,43 @@
1
1
  import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
2
- import { PG_DECODERS } from '../postgres/pgWireTypes.js';
2
+ import { PG_DECODERS, wireDecoders } from '../postgres/pgWireTypes.js';
3
3
  import { AbstractSharedHandleQuerierPool } from '../querier/abstractSharedHandleQuerierPool.js';
4
4
  import { PgliteDialect } from './pgliteDialect.js';
5
5
  import { PgliteQuerier } from './pgliteQuerier.js';
6
+ function openedByCaller(args) {
7
+ return typeof args[0] === 'function';
8
+ }
6
9
  /**
7
- * A pool for PGlite, Postgres in WASM in this process, on one connection. A second `BEGIN` silently joins
8
- * the open transaction, so a unit of work needing its own needs its own pool. Transactions are plain
9
- * statements, so pass `relaxedDurability` on a persistent `dataDir` to skip a flush per statement.
10
+ * A pool for PGlite, Postgres in WASM, on one connection: a `dataDir` it opens, or a handle `open` answers. Its
11
+ * transactions hold PGlite's own lock, which every caller of the handle waits on, another tab's included. Pass
12
+ * `relaxedDurability` on a persistent `dataDir` to skip a flush per statement.
10
13
  */
11
14
  export class PgliteQuerierPool extends AbstractSharedHandleQuerierPool {
12
- dataDir;
13
- opts;
14
- constructor(dataDir = 'memory://', opts, extra) {
15
+ #open;
16
+ /** uql's decoders, sent with each statement on a handle the caller opened, whose own parsers stay its owner's. */
17
+ #queryOptions;
18
+ constructor(...args) {
19
+ const byCaller = openedByCaller(args);
20
+ const extra = byCaller ? args[1] : args[2];
15
21
  super(new PgliteDialect(dialectOptionsFrom(extra)), extra);
16
- this.dataDir = dataDir;
17
- this.opts = opts;
22
+ this.#open = byCaller ? () => this.#decodingPerQuery(args[0]) : () => openPglite(args[0], args[1]);
23
+ }
24
+ openDb() {
25
+ return this.#open();
18
26
  }
19
- async openDb() {
20
- const { PGlite } = await import('@electric-sql/pglite');
21
- // Every Postgres-wire pool's decoders, which PGlite applies to an array's elements too; a caller's own
22
- // `parsers` still win. The declared return type is what checks {@link PgliteDatabase} against the real
23
- // driver, so no cast is needed below it.
24
- return PGlite.create(this.dataDir, {
25
- ...this.opts,
26
- parsers: { ...Object.fromEntries(PG_DECODERS), ...this.opts?.parsers },
27
- });
27
+ async #decodingPerQuery(open) {
28
+ const db = await open();
29
+ this.#queryOptions = { parsers: Object.fromEntries(wireDecoders((oid) => db.parsers[oid] ?? String)) };
30
+ return db;
28
31
  }
29
32
  buildQuerier(db) {
30
- return new PgliteQuerier(db, this.dialect, this.extra);
33
+ return new PgliteQuerier(db, this.dialect, this.extra, this.#queryOptions);
31
34
  }
32
35
  }
36
+ /**
37
+ * PGlite with every Postgres-wire pool's decoders, which it applies to an array's elements too, a caller's own
38
+ * `parsers` overriding them.
39
+ */
40
+ async function openPglite(dataDir = 'memory://', opts) {
41
+ const { PGlite } = await import('@electric-sql/pglite');
42
+ return PGlite.create(dataDir, { ...opts, parsers: { ...Object.fromEntries(PG_DECODERS), ...opts?.parsers } });
43
+ }
@@ -1,8 +1,9 @@
1
1
  import type { RawRow } from '../type/index.js';
2
2
  import type { SqlExecution } from '../util/sql.util.js';
3
- /** A Postgres-wire result as the querier reads it: its rows, and its command tag's count. */
3
+ /** A Postgres-wire result as the querier reads it: its rows, and its command tag, named and counted. */
4
4
  export type PgResult = {
5
5
  readonly rows: RawRow[];
6
6
  readonly rowCount?: number | null;
7
+ readonly command?: string | null;
7
8
  };
8
- export declare function pgExecution({ rows, rowCount }: PgResult): SqlExecution;
9
+ export declare function pgExecution({ rows, rowCount, command }: PgResult): SqlExecution;
@@ -1,3 +1,3 @@
1
- export function pgExecution({ rows, rowCount }) {
2
- return { rows, changes: rowCount };
1
+ export function pgExecution({ rows, rowCount, command }) {
2
+ return { rows, changes: rowCount, command };
3
3
  }
@@ -15,8 +15,13 @@ type Decode = (text: string) => unknown;
15
15
  */
16
16
  export declare const PG_DECODERS: ReadonlyMap<number, Decode>;
17
17
  /**
18
- * {@link PG_DECODERS} as `pg`'s text-format parsers, an array decoding each element as its scalar does.
19
- * At the wire, which every result crosses; per pool, never a global parser, and a caller's own `types` win.
18
+ * {@link PG_DECODERS} and each array of {@link ELEMENT_OIDS}, decoding each element as its scalar does, over the
19
+ * text parsers a driver answers by OID: its `TEXT[]` one splits the array, its own decodes a `NUMERIC`.
20
+ */
21
+ export declare function wireDecoders(textParser: (oid: number) => Decode): Map<number, Decode>;
22
+ /**
23
+ * {@link wireDecoders} as `pg`'s text-format parsers. At the wire, which every result crosses; per pool, never
24
+ * a global parser, and a caller's own `types` win.
20
25
  */
21
26
  export declare function wireTypes(types: PgTypes): CustomTypesConfig;
22
27
  export {};
@@ -33,16 +33,24 @@ const ELEMENT_OIDS = new Map([
33
33
  [OID.NUMERIC_ARRAY, OID.NUMERIC],
34
34
  ]);
35
35
  /**
36
- * {@link PG_DECODERS} as `pg`'s text-format parsers, an array decoding each element as its scalar does.
37
- * At the wire, which every result crosses; per pool, never a global parser, and a caller's own `types` win.
36
+ * {@link PG_DECODERS} and each array of {@link ELEMENT_OIDS}, decoding each element as its scalar does, over the
37
+ * text parsers a driver answers by OID: its `TEXT[]` one splits the array, its own decodes a `NUMERIC`.
38
38
  */
39
- export function wireTypes(types) {
40
- const splitArray = types.getTypeParser(OID.TEXT_ARRAY, 'text');
39
+ export function wireDecoders(textParser) {
40
+ const splitArray = textParser(OID.TEXT_ARRAY);
41
41
  const decoders = new Map(PG_DECODERS);
42
42
  for (const [arrayOid, oid] of ELEMENT_OIDS) {
43
- const decode = PG_DECODERS.get(oid) ?? types.getTypeParser(oid, 'text');
43
+ const decode = PG_DECODERS.get(oid) ?? textParser(oid);
44
44
  decoders.set(arrayOid, (text) => decodeElements(splitArray(text), decode));
45
45
  }
46
+ return decoders;
47
+ }
48
+ /**
49
+ * {@link wireDecoders} as `pg`'s text-format parsers. At the wire, which every result crosses; per pool, never
50
+ * a global parser, and a caller's own `types` win.
51
+ */
52
+ export function wireTypes(types) {
53
+ const decoders = wireDecoders((oid) => types.getTypeParser(oid, 'text'));
46
54
  return {
47
55
  // Text only: in binary mode an INT8 arrives as an 8-byte Buffer, and `Number(buffer)` is `NaN`.
48
56
  getTypeParser: (oid, format) => (format === 'text' && decoders.get(oid)) || types.getTypeParser(oid, format),
@@ -1,7 +1,7 @@
1
1
  import type { AbstractSqlDialect } from '../dialect/index.js';
2
2
  import type { ExtraOptions } from '../type/index.js';
3
- import { AbstractSqlQuerier } from './abstractSqlQuerier.js';
4
- export declare abstract class AbstractPoolQuerier<C> extends AbstractSqlQuerier {
3
+ import { AbstractSqlQuerier, type TransactionHandle } from './abstractSqlQuerier.js';
4
+ export declare abstract class AbstractPoolQuerier<C, Tx extends TransactionHandle = TransactionHandle> extends AbstractSqlQuerier<Tx> {
5
5
  protected readonly connect: () => Promise<C>;
6
6
  protected conn: C | undefined;
7
7
  protected getConn(): C;
@@ -2,10 +2,21 @@ import type { AbstractSqlDialect } from '../dialect/index.js';
2
2
  import type { EntityData, EntityMeta, ExtraOptions, WrittenId, Query, QueryAggregate, QueryUpsert, QueryPage, StatementOptions, QuerySearch, QueryUpdateResult, RawRow, SavepointCommand, SqlQuerier, SqlStatement, Type, TransactionOptions, UpdatePayload, BoundStatement, ReportedWrite } from '../type/index.js';
3
3
  import type { SqlExecution } from '../util/sql.util.js';
4
4
  import { AbstractQuerier, type ReportingWrites } from './abstractQuerier.js';
5
- export declare abstract class AbstractSqlQuerier extends AbstractQuerier implements SqlQuerier {
5
+ /**
6
+ * A transaction a driver holds as an object rather than statements: Hrana's session, `mssql`'s `Transaction`,
7
+ * PGlite's lock. Its `internalBegin` sets {@link AbstractSqlQuerier.tx}, of the type its querier names, and its
8
+ * statements run on it.
9
+ */
10
+ export type TransactionHandle = {
11
+ commit(): Promise<unknown>;
12
+ rollback(): Promise<unknown>;
13
+ };
14
+ export declare abstract class AbstractSqlQuerier<Tx extends TransactionHandle = TransactionHandle> extends AbstractQuerier implements SqlQuerier {
6
15
  #private;
7
16
  readonly dialect: AbstractSqlDialect;
8
17
  hasOpenTransaction: boolean;
18
+ /** The open transaction, where the driver holds it as a {@link TransactionHandle}. */
19
+ protected tx?: Tx;
9
20
  constructor(dialect: AbstractSqlDialect, extra?: ExtraOptions);
10
21
  /** Runs one statement on the driver: what it read, how many rows it changed, and any id its header reports. */
11
22
  protected abstract execute(sql: string, values?: unknown[]): Promise<SqlExecution>;
@@ -157,21 +168,15 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
157
168
  protected internalDeleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: StatementOptions): Promise<number>;
158
169
  protected openTransaction(opts?: TransactionOptions): Promise<void>;
159
170
  /**
160
- * A `COMMIT` that fails can leave the transaction open (SQLite answers `SQLITE_BUSY` and keeps it), so the
161
- * flag stays for the rollback after it. A `ROLLBACK` always ends it: one the server refuses, a deadlock
162
- * victim's on SQL Server, left nothing open to roll back.
171
+ * A handle is dropped before it ends: one outliving a failed end would carry every later statement into a
172
+ * transaction the server may have ended. A `ROLLBACK` always ends it, a deadlock victim's on SQL Server included;
173
+ * a `COMMIT` that fails can leave it open (SQLite's `SQLITE_BUSY`) for the rollback after it.
163
174
  */
164
175
  protected endTransaction(commit: boolean): Promise<void>;
165
176
  /** A rollback to a savepoint undoes the context bound inside it, so the next statement binds it again. */
166
177
  protected savepoint(command: SavepointCommand, name: string): Promise<void>;
167
- /**
168
- * How this driver opens, commits and rolls back: the dialect's statements, unless its transactions
169
- * are objects rather than statements - Hrana's session handle, `mssql`'s `Transaction` - in which
170
- * case it overrides all three. The bookkeeping around them stays above, written once.
171
- */
178
+ /** Opens a transaction on the engine: the dialect's statements, or a driver's {@link tx} it sets instead. */
172
179
  protected internalBegin(opts?: TransactionOptions): Promise<void>;
173
- protected internalCommit(): Promise<void>;
174
- protected internalRollback(): Promise<void>;
175
180
  /** Transaction statements skip `timed()`, so they attach their own query context to a failure. */
176
181
  private runTransactionCommand;
177
182
  }
@@ -9,7 +9,7 @@ import { sql, statementOf } from '../util/sql.js';
9
9
  import { UqlUsageError } from '../util/uqlError.js';
10
10
  import { AbstractQuerier } from './abstractQuerier.js';
11
11
  import { streamViaCursor } from './cursorStream.js';
12
- import { enrichError, failedIndexOf } from './queryError.js';
12
+ import { enrichError, failedIndexOf, isAbortedTransaction } from './queryError.js';
13
13
  import { rowReader } from './rowReader.js';
14
14
  /**
15
15
  * Row indexes split by whether the row names its key, the one thing that changes what an insert can
@@ -67,9 +67,15 @@ function inPayloadOrder(meta, rows, reported) {
67
67
  }
68
68
  /** Each role found held to a dialect's policies, by name (`undefined` the connection's own), answered once per pool. */
69
69
  const heldToPolicies = new WeakMap();
70
+ /** A commit the engine answered with a rollback: on the Postgres family, a failed statement aborts the transaction whole. */
71
+ function abortedCommitError(cause) {
72
+ return new UqlUsageError('the transaction rolled back instead of committing, as a statement in it failed: let the failure end it, or run that statement in a nested transaction, whose savepoint keeps the failure to itself', { cause });
73
+ }
70
74
  export class AbstractSqlQuerier extends AbstractQuerier {
71
75
  dialect;
72
76
  hasOpenTransaction = false;
77
+ /** The open transaction, where the driver holds it as a {@link TransactionHandle}. */
78
+ tx;
73
79
  #bound = NOTHING_BOUND;
74
80
  /** Cached `auto_increment_increment` stride; see {@link loadInsertIdIncrement}. */
75
81
  #insertIdIncrement;
@@ -316,7 +322,8 @@ export class AbstractSqlQuerier extends AbstractQuerier {
316
322
  * closes itself when the loop exits early.
317
323
  */
318
324
  async *internalStream(query, values) {
319
- if (!this.dialect.features.serverSideCursors) {
325
+ // A session the pool's queriers share would hold a cursor's transaction open under every other caller of it.
326
+ if (!this.dialect.features.serverSideCursors || this.connection !== this) {
320
327
  yield* (await this.execute(query, values)).rows;
321
328
  return;
322
329
  }
@@ -521,18 +528,31 @@ export class AbstractSqlQuerier extends AbstractQuerier {
521
528
  this.#bound = NOTHING_BOUND;
522
529
  }
523
530
  /**
524
- * A `COMMIT` that fails can leave the transaction open (SQLite answers `SQLITE_BUSY` and keeps it), so the
525
- * flag stays for the rollback after it. A `ROLLBACK` always ends it: one the server refuses, a deadlock
526
- * victim's on SQL Server, left nothing open to roll back.
531
+ * A handle is dropped before it ends: one outliving a failed end would carry every later statement into a
532
+ * transaction the server may have ended. A `ROLLBACK` always ends it, a deadlock victim's on SQL Server included;
533
+ * a `COMMIT` that fails can leave it open (SQLite's `SQLITE_BUSY`) for the rollback after it.
527
534
  */
528
535
  async endTransaction(commit) {
529
- if (commit) {
530
- await this.internalCommit();
536
+ const { tx, dialect } = this;
537
+ if (commit && !tx) {
538
+ const { command } = await this.runTransactionCommand(dialect.commitTransactionCommand);
531
539
  this.hasOpenTransaction = false;
540
+ if (command === 'ROLLBACK') {
541
+ throw abortedCommitError();
542
+ }
532
543
  return;
533
544
  }
545
+ this.tx = undefined;
534
546
  try {
535
- await this.internalRollback();
547
+ if (tx) {
548
+ await (commit ? tx.commit() : tx.rollback());
549
+ }
550
+ else {
551
+ await this.runTransactionCommand(dialect.rollbackTransactionCommand);
552
+ }
553
+ }
554
+ catch (err) {
555
+ throw isAbortedTransaction(err) ? abortedCommitError(err) : err;
536
556
  }
537
557
  finally {
538
558
  this.hasOpenTransaction = false;
@@ -548,26 +568,16 @@ export class AbstractSqlQuerier extends AbstractQuerier {
548
568
  this.#bound = unsettled(this.#bound);
549
569
  }
550
570
  }
551
- /**
552
- * How this driver opens, commits and rolls back: the dialect's statements, unless its transactions
553
- * are objects rather than statements - Hrana's session handle, `mssql`'s `Transaction` - in which
554
- * case it overrides all three. The bookkeeping around them stays above, written once.
555
- */
571
+ /** Opens a transaction on the engine: the dialect's statements, or a driver's {@link tx} it sets instead. */
556
572
  async internalBegin(opts) {
557
573
  for (const sql of this.dialect.getBeginTransactionStatements(opts)) {
558
574
  await this.runTransactionCommand(sql);
559
575
  }
560
576
  }
561
- internalCommit() {
562
- return this.runTransactionCommand(this.dialect.commitTransactionCommand);
563
- }
564
- internalRollback() {
565
- return this.runTransactionCommand(this.dialect.rollbackTransactionCommand);
566
- }
567
577
  /** Transaction statements skip `timed()`, so they attach their own query context to a failure. */
568
578
  async runTransactionCommand(sql) {
569
579
  try {
570
- await this.execute(sql);
580
+ return await this.execute(sql);
571
581
  }
572
582
  catch (err) {
573
583
  throw enrichError(err, this.logger, sql);
@@ -8,6 +8,8 @@ export interface QueryError extends Error {
8
8
  query?: string;
9
9
  values?: readonly unknown[];
10
10
  }
11
+ /** Whether `err` is Postgres refusing a commit because a failed statement aborted the transaction (SQLSTATE `25P02`). */
12
+ export declare function isAbortedTransaction(err: unknown): boolean;
11
13
  /**
12
14
  * Names what `err` ran into on any engine, or `undefined` for anything else. Pure: the error is only
13
15
  * read, so it works on any driver error, whether or not a querier saw it first.
@@ -47,6 +47,14 @@ const SQLITE_MESSAGE_KINDS = [
47
47
  ['CHECK constraint failed', 'checkViolation'],
48
48
  ['database is locked', 'retryable'],
49
49
  ];
50
+ /** Whether `err` is Postgres refusing a commit because a failed statement aborted the transaction (SQLSTATE `25P02`). */
51
+ export function isAbortedTransaction(err) {
52
+ if (typeof err !== 'object' || err === null) {
53
+ return false;
54
+ }
55
+ const { code } = err;
56
+ return code === '25P02';
57
+ }
50
58
  /**
51
59
  * Names what `err` ran into on any engine, or `undefined` for anything else. Pure: the error is only
52
60
  * read, so it works on any driver error, whether or not a querier saw it first.
@@ -43,9 +43,8 @@ export type HranaQuerierConnectionOptions = {
43
43
  * @remarks Transactions use the client's own session handle rather than `BEGIN`/`COMMIT` statements,
44
44
  * because over plain HTTP consecutive requests need not share a connection.
45
45
  */
46
- export declare class HranaQuerier extends AbstractSqlQuerier {
46
+ export declare class HranaQuerier extends AbstractSqlQuerier<HranaTransaction> {
47
47
  readonly client: HranaClient;
48
- private tx?;
49
48
  private readonly closeClientOnRelease;
50
49
  constructor(client: HranaClient, dialect: SqliteDialect, extra?: ExtraOptions, connection?: HranaQuerierConnectionOptions);
51
50
  /** Runs on the open transaction's handle when there is one. */
@@ -53,11 +52,5 @@ export declare class HranaQuerier extends AbstractSqlQuerier {
53
52
  /** A list as one request: the client's `batch`, all or none; inside an open transaction, its own, which joins it. */
54
53
  protected executeBatch(statements: readonly BoundStatement[]): Promise<SqlExecution[]>;
55
54
  protected internalBegin(opts?: TransactionOptions): Promise<void>;
56
- /**
57
- * Both drop the handle before the call, not after: one that outlived a failed commit would carry
58
- * every later statement into a transaction the server may already have ended.
59
- */
60
- protected internalCommit(): Promise<void>;
61
- protected internalRollback(): Promise<void>;
62
55
  internalRelease(): Promise<void>;
63
56
  }
@@ -9,7 +9,6 @@ import { sqliteStatements, toBindValues } from './bindValues.js';
9
9
  */
10
10
  export class HranaQuerier extends AbstractSqlQuerier {
11
11
  client;
12
- tx;
13
12
  closeClientOnRelease;
14
13
  constructor(client, dialect, extra, connection) {
15
14
  super(dialect, extra);
@@ -29,20 +28,6 @@ export class HranaQuerier extends AbstractSqlQuerier {
29
28
  async internalBegin(opts) {
30
29
  this.tx = await this.client.transaction(opts?.readOnly ? 'read' : 'write');
31
30
  }
32
- /**
33
- * Both drop the handle before the call, not after: one that outlived a failed commit would carry
34
- * every later statement into a transaction the server may already have ended.
35
- */
36
- async internalCommit() {
37
- const tx = this.tx;
38
- this.tx = undefined;
39
- await tx?.commit();
40
- }
41
- async internalRollback() {
42
- const tx = this.tx;
43
- this.tx = undefined;
44
- await tx?.rollback();
45
- }
46
31
  async internalRelease() {
47
32
  if (this.closeClientOnRelease) {
48
33
  this.client.close();
@@ -46,12 +46,13 @@ export declare function derivedForeignKeyName(table: string, columns: readonly s
46
46
  export declare function escapeSqlId(val: string | undefined, escapeIdChar?: '`' | '"', forbidQualified?: boolean, addDot?: boolean): string;
47
47
  /**
48
48
  * What a statement came back with: the rows it read (a `RETURNING`'s included), how many rows it changed where
49
- * the driver tells it, and the first id a header reports (MySQL's `insertId`).
49
+ * the driver tells it, the first id a header reports (MySQL's `insertId`), and the Postgres wire's command tag.
50
50
  */
51
51
  export type SqlExecution = {
52
52
  readonly rows: RawRow[];
53
53
  readonly changes?: number | null;
54
54
  readonly id?: PrimaryKey;
55
+ readonly command?: string | null;
55
56
  };
56
57
  /** The column a `RETURNING` reports ids under: uql's own statements alias the key to it, and a raw `run()` names it so. */
57
58
  export declare const RETURNED_ID = "id";
package/package.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "homepage": "https://uql-orm.dev",
4
4
  "description": "JSON-native TypeScript ORM for Bun, Browsers, Edge, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, SQL Server, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
5
5
  "license": "MIT",
6
- "version": "0.116.4",
6
+ "version": "0.116.5",
7
7
  "type": "module",
8
8
  "engines": {
9
9
  "node": ">=22.18"
@@ -50,7 +50,7 @@
50
50
  "clean": "rimraf dist .tsconfig.tsbuildinfo"
51
51
  },
52
52
  "peerDependencies": {
53
- "@electric-sql/pglite": ">=0.5.10 <0.6",
53
+ "@electric-sql/pglite": ">=0.5.15 <0.6",
54
54
  "@libsql/client": ">=0.6.0 <0.19",
55
55
  "@neondatabase/serverless": ">=0.9.0 <2",
56
56
  "@nestjs/common": ">=10.0.0 <13",
@@ -37,7 +37,7 @@ export const pool = new PgQuerierPool({ connectionString: process.env.DATABASE_U
37
37
  export default { pool, entities: [User, Post] } satisfies Config;
38
38
  ```
39
39
 
40
- Driver entry points: `uql-orm/postgres`, `mysql`, `mariadb`, `sqlite`, `mongodb`, `libsql`, `turso`, `neon`, `d1`, `pglite`, `bun-sql`, `mssql`, `cockroachdb`. Build the pool once per process and import it.
40
+ Driver entry points: `uql-orm/postgres`, `mysql`, `mariadb`, `sqlite`, `mongodb`, `libsql`, `turso`, `neon`, `d1`, `pglite`, `bun-sql`, `mssql`, `cockroachdb`. Build the pool once per process and import it. `new PgliteQuerierPool(dataDir, opts)` opens PGlite itself; `new PgliteQuerierPool(() => PGliteWorker.create(worker))` runs on a handle you open, as a worker sharing one database across tabs, and its transactions hold PGlite's lock, which every other user of the handle waits on.
41
41
 
42
42
  The pool's first argument is the driver's own config; set an acquire timeout there (`connectionTimeoutMillis` on the `pg` family), which otherwise waits forever. The second holds uql's options: `namingStrategy: new SnakeCaseNamingStrategy()` maps `createdAt` to `created_at` in queries and migrations alike (never name each column by hand), `logger: true` or a level list, `slowQuery: 200` (ms), and a default `schema`. Call `await pool.end()` on shutdown, except in serverless functions: https://uql-orm.dev/pool.md
43
43
 
@@ -276,6 +276,7 @@ await pool.transaction(async (querier) => {
276
276
  ```
277
277
 
278
278
  - The callback commits when it returns and rolls back when it throws. Inside it, `pool` calls run on its querier. A nested `transaction()` is a savepoint; MongoDB refuses it.
279
+ - On the Postgres family a failed statement aborts its whole transaction, so one caught and carried past cannot commit: the commit rejects with `UqlUsageError`. Run a statement that may fail in a nested `transaction()`, whose savepoint keeps the failure to itself.
279
280
  - `querier.onCommit(fn)` runs `fn` after the outermost commit, never on rollback.
280
281
  - A transaction opened in one place and ended in another uses `beginTransaction`, `commitTransaction` and `rollbackTransaction`. A querier from `pool.getQuerier()` is yours to release: bind it with `await using`.
281
282
  - A `findManyStream` holds its querier until the loop ends, refusing other statements meanwhile: run them after the loop, or on another connection.