uql-orm 0.116.0 → 0.116.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -18,7 +18,7 @@ export declare class NeonQuerier extends PgQuerier {
18
18
  /** Connects nothing: a statement goes over HTTP until a session holds the connection. */
19
19
  protected lazyConnect(): Promise<void>;
20
20
  protected execute(sql: string, values?: unknown[]): Promise<SqlExecution>;
21
- /** A list as one HTTP transaction, all or none; inside an open transaction, in turn on its session, which it joins. */
21
+ /** A list as one HTTP transaction, all or none; inside an open transaction, pipelined on its session, which it joins. */
22
22
  protected executeBatch(statements: readonly BoundStatement[]): Promise<SqlExecution[]>;
23
23
  protected openTransaction(opts?: TransactionOptions): Promise<void>;
24
24
  internalStream(query: string, values?: unknown[]): AsyncGenerator<import("../type/utility.js").RawRow, void, any>;
@@ -20,16 +20,9 @@ export class NeonQuerier extends PgQuerier {
20
20
  }
21
21
  return this.http.query(sql, values);
22
22
  }
23
- /** A list as one HTTP transaction, all or none; inside an open transaction, in turn on its session, which it joins. */
24
- async executeBatch(statements) {
25
- if (this.hasOpenTransaction) {
26
- const results = [];
27
- for (const { sql, values } of statements) {
28
- results.push(await super.execute(sql, values));
29
- }
30
- return results;
31
- }
32
- return this.http.transaction(statements);
23
+ /** A list as one HTTP transaction, all or none; inside an open transaction, pipelined on its session, which it joins. */
24
+ executeBatch(statements) {
25
+ return this.hasOpenTransaction ? super.executeBatch(statements) : this.http.transaction(statements);
33
26
  }
34
27
  async openTransaction(opts) {
35
28
  await super.lazyConnect();
@@ -0,0 +1,33 @@
1
+ import type { BoundStatement } from '../type/index.js';
2
+ import type { PgResult } from './pgExecution.js';
3
+ /** What a pipeline writes to besides the statements its `Query` writes: the `Sync` closing the request. */
4
+ type PgConnection = {
5
+ sync(): void;
6
+ };
7
+ /** What decodes a column, as node-postgres reads its wire types off a client: `client.getTypeParser`. */
8
+ export type PgTypes = {
9
+ getTypeParser(oid: number, format?: 'text' | 'binary'): unknown;
10
+ };
11
+ /** node-postgres' `Query`, as a pipeline extends it: the one the client runs, so it reads the client's protocol. */
12
+ interface PgQuery {
13
+ text: string;
14
+ values?: readonly unknown[];
15
+ submit(connection: object): unknown;
16
+ requiresPreparation(): boolean;
17
+ prepare(connection: PgConnection): void;
18
+ handleCommandComplete(msg: unknown, connection: PgConnection): void;
19
+ handleError(error: Error, connection: PgConnection): void;
20
+ }
21
+ /** A client running statements, `pg`'s or a fork's, which names its `Query` on its class. */
22
+ export type PgPipelineClient = PgTypes & {
23
+ query(text: string, values?: unknown[]): Promise<PgResult>;
24
+ query(query: PgQuery): unknown;
25
+ };
26
+ /**
27
+ * Runs `statements` on `client` in one round trip: each one's Parse, Bind and Execute, then a single `Sync`, so the
28
+ * server answers them in order and fails the list at its first error, skipping the rest. A client whose `Query` cannot
29
+ * be pipelined, as pg-native's, runs them in turn. The error names the statement that failed as `statementIndex`,
30
+ * counted from the first after the `leading` ones the caller added.
31
+ */
32
+ export declare function pipelined(client: PgPipelineClient, statements: readonly BoundStatement[], leading?: number): Promise<PgResult[]>;
33
+ export {};
@@ -0,0 +1,82 @@
1
+ import { cachedIn, noop } from '../util/object.util.js';
2
+ const PIPELINES = new WeakMap();
3
+ /**
4
+ * Runs `statements` on `client` in one round trip: each one's Parse, Bind and Execute, then a single `Sync`, so the
5
+ * server answers them in order and fails the list at its first error, skipping the rest. A client whose `Query` cannot
6
+ * be pipelined, as pg-native's, runs them in turn. The error names the statement that failed as `statementIndex`,
7
+ * counted from the first after the `leading` ones the caller added.
8
+ */
9
+ export function pipelined(client, statements, leading = 0) {
10
+ const Query = Reflect.get(client.constructor, 'Query');
11
+ if (!pipelines(Query)) {
12
+ return inTurn(client, statements, leading);
13
+ }
14
+ const Pipeline = cachedIn(PIPELINES, Query, () => pipelineOf(Query));
15
+ return new Promise((resolve, reject) => {
16
+ client.query(new Pipeline(statements, client, leading, (error, results) => error ? reject(error) : resolve([results].flat())));
17
+ });
18
+ }
19
+ /** Whether `value` is a `Query` writing its statement's protocol itself, as `pg`'s does, which a pipeline extends. */
20
+ function pipelines(value) {
21
+ return typeof value === 'function' && typeof value.prototype?.prepare === 'function';
22
+ }
23
+ /** `statements` one round trip each, the error naming its statement as {@link pipelined}'s does. */
24
+ async function inTurn(client, statements, leading) {
25
+ const results = [];
26
+ for (const [at, { sql, values }] of statements.entries()) {
27
+ const result = await client.query(sql, [...values]).catch((error) => {
28
+ throw Object.assign(error, { statementIndex: at - leading });
29
+ });
30
+ results.push(result);
31
+ }
32
+ return results;
33
+ }
34
+ /**
35
+ * The pipeline over `Query`: it writes each statement as `Query` does, holding back each one's `Sync` but the last.
36
+ * Earlier than `pg` 8.5 a failed list crashes the client, hence the peer floor. `pg` 8.23's public `pipeline` option
37
+ * does not fit yet: it is set per client, and refuses the cursors a stream reads.
38
+ */
39
+ function pipelineOf(Query) {
40
+ return class Pipeline extends Query {
41
+ #statements;
42
+ #leading;
43
+ /** The statements the server finished, which is the position of one it fails. */
44
+ #completed = 0;
45
+ /** The statement being written, which is the one failing where its values cannot be. */
46
+ #writing;
47
+ #failed = false;
48
+ /** `types`, the client's own, so every statement's rows decode as one run alone would, on a fork too. */
49
+ constructor(statements, types, leading, callback) {
50
+ super({ text: statements[0].sql, callback, types });
51
+ this.#statements = statements;
52
+ this.#leading = leading;
53
+ }
54
+ requiresPreparation() {
55
+ return true;
56
+ }
57
+ prepare(connection) {
58
+ // `Query` closes each statement it writes with a `Sync`, which would commit it alone: the list sends one, last.
59
+ const held = Object.create(connection, { sync: { value: noop } });
60
+ for (const [at, { sql, values }] of this.#statements.entries()) {
61
+ this.#writing = at;
62
+ this.text = sql;
63
+ this.values = values;
64
+ super.prepare(held);
65
+ if (this.#failed) {
66
+ break;
67
+ }
68
+ }
69
+ this.#writing = undefined;
70
+ connection.sync();
71
+ }
72
+ handleCommandComplete(msg, connection) {
73
+ this.#completed++;
74
+ super.handleCommandComplete(msg, connection);
75
+ }
76
+ handleError(error, connection) {
77
+ this.#failed = true;
78
+ const statementIndex = (this.#writing ?? this.#completed) - this.#leading;
79
+ super.handleError(Object.assign(error, { statementIndex }), connection);
80
+ }
81
+ };
82
+ }
@@ -1,10 +1,12 @@
1
1
  import { AbstractPoolQuerier } from '../querier/abstractPoolQuerier.js';
2
- import type { RawRow } from '../type/index.js';
2
+ import type { BoundStatement, RawRow } from '../type/index.js';
3
3
  import type { SqlExecution } from '../util/sql.util.js';
4
4
  import { type PgResult } from './pgExecution.js';
5
+ import { type PgTypes } from './pgPipeline.js';
5
6
  export interface PgAnyClient {
6
7
  query(text: string, values?: unknown[]): Promise<PgResult>;
7
8
  query(stream: object): AsyncIterable<RawRow>;
9
+ getTypeParser: PgTypes['getTypeParser'];
8
10
  on(event: 'error', listener: (err: Error) => void): unknown;
9
11
  removeListener(event: 'error', listener: (err: Error) => void): unknown;
10
12
  /** Any truthy argument makes `pg-pool` evict the client instead of returning it to the idle list. */
@@ -21,6 +23,12 @@ export declare class PgQuerier extends AbstractPoolQuerier<PgAnyClient> {
21
23
  */
22
24
  protected acquired(conn: PgAnyClient): PgAnyClient;
23
25
  protected execute(sql: string, values?: unknown[]): Promise<SqlExecution>;
26
+ /**
27
+ * `statements` as one request: written ahead of one `Sync`, so they cost one round trip. Outside a transaction they
28
+ * run in one opened and committed in the same request, all or none, which also scopes a setting bound for the
29
+ * database's policies, as CockroachDB scopes one only in a transaction; rolled back where one fails.
30
+ */
31
+ protected executeBatch(statements: readonly BoundStatement[]): Promise<SqlExecution[]>;
24
32
  internalStream(query: string, values?: unknown[]): AsyncGenerator<RawRow, void, any>;
25
33
  protected releaseConn(conn: PgAnyClient, discard: boolean): Promise<void>;
26
34
  }
@@ -1,6 +1,7 @@
1
1
  import { AbstractPoolQuerier } from '../querier/abstractPoolQuerier.js';
2
2
  import { noop } from '../util/object.util.js';
3
3
  import { pgExecution } from './pgExecution.js';
4
+ import { pipelined } from './pgPipeline.js';
4
5
  /**
5
6
  * Querier for every client with node-postgres' API: `pg` itself, for Postgres and CockroachDB, and
6
7
  * Neon's serverless driver; the dialect is whichever the pool built.
@@ -17,6 +18,28 @@ export class PgQuerier extends AbstractPoolQuerier {
17
18
  async execute(sql, values) {
18
19
  return pgExecution(await this.getConn().query(sql, values));
19
20
  }
21
+ /**
22
+ * `statements` as one request: written ahead of one `Sync`, so they cost one round trip. Outside a transaction they
23
+ * run in one opened and committed in the same request, all or none, which also scopes a setting bound for the
24
+ * database's policies, as CockroachDB scopes one only in a transaction; rolled back where one fails.
25
+ */
26
+ async executeBatch(statements) {
27
+ const conn = this.getConn();
28
+ if (this.hasOpenTransaction) {
29
+ return (await pipelined(conn, statements)).map(pgExecution);
30
+ }
31
+ const { dialect } = this;
32
+ const begin = dialect.getBeginTransactionStatements().map((sql) => ({ sql, values: [] }));
33
+ const listed = [...begin, ...statements, { sql: dialect.commitTransactionCommand, values: [] }];
34
+ try {
35
+ return (await pipelined(conn, listed, begin.length)).slice(begin.length, -1).map(pgExecution);
36
+ }
37
+ catch (error) {
38
+ // The failed transaction stays open past the `Sync`; its own failure is the one worth reporting.
39
+ await conn.query(dialect.rollbackTransactionCommand).catch(noop);
40
+ throw error;
41
+ }
42
+ }
20
43
  async *internalStream(query, values) {
21
44
  const { default: QueryStream } = await import('pg-query-stream');
22
45
  yield* this.getConn().query(new QueryStream(query, values));
@@ -27,19 +27,22 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
27
27
  all<T extends object = RawRow>(...statement: SqlStatement): Promise<T[]>;
28
28
  run(...statement: SqlStatement): Promise<QueryUpdateResult>;
29
29
  /**
30
- * Runs `statements` as one request, all or none, joining an open transaction: what a driver taking a list as one
31
- * declares. Called for two or more.
30
+ * Runs `statements` as one request, all or none: in a transaction of its own outside one, which scopes a context
31
+ * bound ahead of them, else joining the open one. What a driver taking a list as one declares. Called for two or more.
32
32
  */
33
33
  protected executeBatch?(statements: readonly BoundStatement[]): Promise<SqlExecution[]>;
34
34
  /**
35
35
  * The one path every statement takes, alone or as a list answering a result each, all or none: one request where
36
36
  * the driver has {@link executeBatch}, a failure tagged with the statement it names; else in turn, in a transaction
37
- * where `atomic` (a split write) asks for one, opened before the queue is taken, which its `BEGIN` waits on.
37
+ * where `atomic` (a split write) asks for one, opened before the queue is taken, which its `BEGIN` waits on. A
38
+ * context the database's policies read is bound ahead of them, in the same request where the driver sends lists;
39
+ * else in a transaction opened for it, which scopes the binding.
38
40
  */
39
41
  protected runStatements(statements: readonly BoundStatement[], atomic?: boolean): Promise<readonly SqlExecution[]>;
40
42
  /**
41
- * The statement binding the ambient context into the open transaction ahead of its next statement: none where it is
42
- * bound already, or there is nothing to bind. `ask` runs the question of the connected role.
43
+ * The statement binding the ambient context ahead of the next statement: none where the open transaction bound it
44
+ * already, or there is nothing to bind. Outside one, every request binds it anew. `ask` runs the question of the
45
+ * connected role.
43
46
  */
44
47
  private pendingBinding;
45
48
  /** Whether a statement here runs under a context the database's policies read, which binds in a transaction. */
@@ -112,31 +112,34 @@ export class AbstractSqlQuerier extends AbstractQuerier {
112
112
  /**
113
113
  * The one path every statement takes, alone or as a list answering a result each, all or none: one request where
114
114
  * the driver has {@link executeBatch}, a failure tagged with the statement it names; else in turn, in a transaction
115
- * where `atomic` (a split write) asks for one, opened before the queue is taken, which its `BEGIN` waits on.
115
+ * where `atomic` (a split write) asks for one, opened before the queue is taken, which its `BEGIN` waits on. A
116
+ * context the database's policies read is bound ahead of them, in the same request where the driver sends lists;
117
+ * else in a transaction opened for it, which scopes the binding.
116
118
  */
117
119
  async runStatements(statements, atomic = false) {
118
- if (!this.dialect.policies.database) {
119
- return this.runBound(statements, atomic);
120
+ if (!this.executeBatch && !this.scopeHere() && this.bindsContext()) {
121
+ return this.atomically(() => this.runStatements(statements, atomic));
120
122
  }
121
- if (!this.scopeHere()) {
122
- return this.bindsContext()
123
- ? this.atomically(() => this.runStatements(statements, atomic))
124
- : this.runBound(statements, atomic);
125
- }
126
- const binding = await this.pendingBinding((sql) => this.onConnection(() => this.execute(sql)));
123
+ const binding = this.dialect.policies.database
124
+ ? await this.pendingBinding((sql) => this.onConnection(() => this.execute(sql)))
125
+ : undefined;
127
126
  const results = await this.runBound(binding ? [binding, ...statements] : statements, atomic);
128
127
  return binding ? results.slice(1) : results;
129
128
  }
130
129
  /**
131
- * The statement binding the ambient context into the open transaction ahead of its next statement: none where it is
132
- * bound already, or there is nothing to bind. `ask` runs the question of the connected role.
130
+ * The statement binding the ambient context ahead of the next statement: none where the open transaction bound it
131
+ * already, or there is nothing to bind. Outside one, every request binds it anew. `ask` runs the question of the
132
+ * connected role.
133
133
  */
134
134
  async pendingBinding(ask) {
135
- const { entries, bound } = nextBinding(this.#bound, getContext());
135
+ const held = this.scopeHere() !== undefined;
136
+ const { entries, bound } = nextBinding(held ? this.#bound : NOTHING_BOUND, getContext());
136
137
  if (entries.length && this.bindsContext()) {
137
138
  await this.assertHeldToPolicies(ask, roleOf(entries, this.dialect.policies.role));
138
139
  }
139
- this.#bound = bound;
140
+ if (held) {
141
+ this.#bound = bound;
142
+ }
140
143
  return this.dialect.contextBinding(entries);
141
144
  }
142
145
  /** Whether a statement here runs under a context the database's policies read, which binds in a transaction. */
@@ -150,14 +153,17 @@ export class AbstractSqlQuerier extends AbstractQuerier {
150
153
  assertHeldToPolicies(ask, role) {
151
154
  const { dialect } = this;
152
155
  const held = cachedIn(heldToPolicies, dialect, () => new Map());
153
- return cachedIn(held, role, () => ask(dialect.rowSecurityBypassQuery(role)).then(({ rows }) => {
156
+ // A failed answer is forgotten, so the next statement asks again.
157
+ return cachedIn(held, role, () => ask(dialect.rowSecurityBypassQuery(role))
158
+ .then(({ rows }) => {
154
159
  if (rows[0]?.['bypasses'] !== false) {
155
160
  throw new UqlUsageError(`a pool with policies: 'native' runs a context's statements as a role ${dialect.engineName} lets past row-level security: connect as, or name, one that does not, or leave policies unset`);
156
161
  }
157
- })).catch((error) => {
162
+ })
163
+ .catch((error) => {
158
164
  held.delete(role);
159
165
  throw error;
160
- });
166
+ }));
161
167
  }
162
168
  /** {@link runStatements} once the context is bound. */
163
169
  runBound(statements, atomic) {
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.0",
6
+ "version": "0.116.1",
7
7
  "type": "module",
8
8
  "engines": {
9
9
  "node": ">=22.18"
@@ -63,7 +63,7 @@
63
63
  "mongodb": ">=6.0.0 <8",
64
64
  "mssql": ">=11.0.0 <13",
65
65
  "mysql2": ">=3.0.0 <4",
66
- "pg": ">=8.0.0 <9",
66
+ "pg": ">=8.5.0 <9",
67
67
  "pg-query-stream": ">=4.0.0 <5",
68
68
  "rxjs": ">=7.0.0 <8"
69
69
  },