postgrejs 3.0.1 → 3.0.2

package/CHANGELOG.md

@@ -1,6 +1,25 @@
 ## Changelog
 
-### [v3.0.1](https://github.com/panates/postgrejs/compare/v3.0.0...v3.0.1) - 
+### [v3.0.2](https://github.com/panates/postgrejs/compare/v3.0.1...v3.0.2) - 
+
+#### 🚀 New Features
+
+- feat: add Docker setup for PostgreSQL with SSL support @Eray Hanoğlu 
+- feat: support nested startTransaction()/commit() and savepoint()/releaseSavepoint() @Eray Hanoğlu 
+- feat: make execute()/query() timing an opt-in, default-off option @Eray Hanoğlu 
+
+#### 🪲 Fixes
+
+- fix: raise warmup for Simple Query benchmark, regenerate BENCHMARKS.md @Eray Hanoğlu 
+- fix: enlarge benchmark charts so GitHub's Mermaid overlay doesn't swallow them @Eray Hanoğlu 
+- fix: replace deprecated substr() with substring() @Eray Hanoğlu 
+
+#### ⚡️ Performance Improvments
+
+- perf: remove needless async wrapping and coercion from execute()/query() hot path @Eray Hanoğlu 
+- perf: hoist loop-invariant reads in Frontend/numeric encoders @Eray Hanoğlu 
+
+### [v3.0.1](https://github.com/panates/postgrejs/compare/v3.0.0...v3.0.1) -  7 September 2026 
 
 - Dev
 - Dev

package/README.md

@@ -126,7 +126,7 @@ in · 🟡 partial or needs a separate package · ❌ not supported.
 | Per-query type mapping            |           ✅           |    ❌ <sup>6</sup>    | ❌ <sup>6</sup>  |
 | Query cancellation                |     ✅ AbortSignal     |          ✅           |        ✅        |
 | Per-query timeout                 |     ✅ AbortSignal     |          ✅           | ❌ <sup>7</sup>  |
-| Reference counters                | Connection · Statement |          ❌           |        ❌        |
+| Reference counters                | Connection / Statement |          ❌           |        ❌        |
 | Caller kept in async error stacks |           ✅           |    🟡 <sup>8</sup>    | 🟡 <sup>9</sup>  |
 | Error located in the SQL text     |    ✅ line and mark    |       🟡 offset       |    🟡 offset     |
 | TC39 Explicit Resource Management |           ✅           |          ❌           |        ❌        |

package/connection/connection.d.ts

@@ -157,9 +157,11 @@ export declare class Connection extends SafeEventEmitter implements AsyncDisposa
      */
     startTransaction(): Promise<void>;
     /**
-     * Commits current transaction
+     * Commits current transaction.
+     * @param immediate - Commits right away, ignoring how many nested
+     *   startTransaction() calls are still unmatched by a commit().
      */
-    commit(): Promise<void>;
+    commit(immediate?: boolean): Promise<void>;
     /**
      * Rolls back current transaction
      */
@@ -206,8 +208,11 @@ export declare class Connection extends SafeEventEmitter implements AsyncDisposa
     /**
      * Releases savepoint
      * @param name {string} - Name of the savepoint
+     * @param immediate - Releases right away, ignoring how many nested
+     *   savepoint() calls under this name are still unmatched by a
+     *   releaseSavepoint().
      */
-    releaseSavepoint(name: string): Promise<void>;
+    releaseSavepoint(name: string, immediate?: boolean): Promise<void>;
     listen(channel: string, callback: NotificationCallback): Promise<void>;
     unListen(channel: string): Promise<void>;
     unListenAll(): Promise<void>;
@@ -242,6 +247,15 @@ export declare class Connection extends SafeEventEmitter implements AsyncDisposa
      * `asyncErrorHandling` is the per-call override (execute()/query()'s own
      * option of the same name); when omitted, the connection's own
      * `DatabaseConnectionParams.asyncErrorHandling` decides.
+     *
+     * Not `async` itself, deliberately: every branch below already returns a
+     * promise directly (`promise` itself, or `promise.catch(...)`'s own
+     * derived one) with no `await` in between, so there is nothing here that
+     * needs the function to be a coroutine. Marking it `async` anyway would
+     * still be correct, but the spec requires wrapping whatever an async
+     * function returns through a promise-resolve step, a genuine extra
+     * microtask tick on top of the one `promise`/`.catch()` already goes
+     * through - paid on every single query this wraps, disabled or not.
      */
     protected _captureErrorStack<T>(promise: Promise<T>, entry?: (...args: any[]) => any, asyncErrorHandling?: boolean): Promise<T>;
     [Symbol.asyncDispose](): Promise<void>;

package/connection/connection.js

@@ -1,4 +1,3 @@
-import { coerceToBoolean } from 'putil-varhelpers';
 import { ConnectionState, DataTypeOIDs } from '../constants.js';
 import { GlobalTypeMap } from '../data-type-map.js';
 import { SafeEventEmitter } from '../safe-event-emitter.js';
@@ -141,7 +140,8 @@ export class Connection extends SafeEventEmitter {
     async execute(sql, options) {
         if (typeof sql === 'object' && sql instanceof QueryRequest)
             sql = sql.stringify({ ...options, typeMap: options?.typeMap });
-        this.emit('execute', sql, options);
+        if (this.listenerCount('execute'))
+            this.emit('execute', sql, options);
         return withAbortSignal(options?.signal, () => this._intlCon.cancel(), () => this._captureErrorStack(this._intlCon.execute(sql, options), this.execute, options?.asyncErrorHandling).catch((e) => {
             throw this._handleError(e, sql);
         }));
@@ -164,7 +164,8 @@ export class Connection extends SafeEventEmitter {
             });
         }
         /* c8 ignore stop */
-        this.emit('query', sql, options);
+        if (this.listenerCount('query'))
+            this.emit('query', sql, options);
         return withAbortSignal(options?.signal, () => this._intlCon.cancel(), () => this._query(sql, options));
     }
     /**
@@ -198,7 +199,8 @@ export class Connection extends SafeEventEmitter {
             });
         }
         /* c8 ignore stop */
-        this.emit('execute', sql);
+        if (this.listenerCount('execute'))
+            this.emit('execute', sql);
         return await this._captureErrorStack(this._intlCon.copyTo(sql)).catch((e) => {
             throw this._handleError(e, sql);
         });
@@ -231,7 +233,8 @@ export class Connection extends SafeEventEmitter {
             });
         }
         /* c8 ignore stop */
-        this.emit('execute', sql);
+        if (this.listenerCount('execute'))
+            this.emit('execute', sql);
         return await this._captureErrorStack(this._intlCon.copyFrom(sql)).catch((e) => {
             throw this._handleError(e, sql);
         });
@@ -313,10 +316,12 @@ export class Connection extends SafeEventEmitter {
         return this._captureErrorStack(this._intlCon.startTransaction());
     }
     /**
-     * Commits current transaction
+     * Commits current transaction.
+     * @param immediate - Commits right away, ignoring how many nested
+     *   startTransaction() calls are still unmatched by a commit().
      */
-    commit() {
-        return this._captureErrorStack(this._intlCon.commit());
+    commit(immediate) {
+        return this._captureErrorStack(this._intlCon.commit(immediate));
     }
     /**
      * Rolls back current transaction
@@ -378,9 +383,12 @@ export class Connection extends SafeEventEmitter {
     /**
      * Releases savepoint
      * @param name {string} - Name of the savepoint
+     * @param immediate - Releases right away, ignoring how many nested
+     *   savepoint() calls under this name are still unmatched by a
+     *   releaseSavepoint().
      */
-    releaseSavepoint(name) {
-        return this._captureErrorStack(this._intlCon.releaseSavepoint(name));
+    releaseSavepoint(name, immediate) {
+        return this._captureErrorStack(this._intlCon.releaseSavepoint(name, immediate));
     }
     async listen(channel, callback) {
         if (!/^[A-Z]\w+$/i.test(channel))
@@ -420,8 +428,8 @@ export class Connection extends SafeEventEmitter {
             ? options.autoCommit
             : this._intlCon.config.autoCommit;
         if (!options?.cursor &&
-            !this._intlCon.inTransaction &&
-            effectiveAutoCommit !== false) {
+            effectiveAutoCommit !== false &&
+            !this._intlCon.inTransaction) {
             const params = options?.params?.map(prm => prm instanceof BindParam ? prm.value : prm);
             return await this._captureErrorStack(this._intlCon.queryOnce(sql, paramTypes, params, options || {}), this.query, options?.asyncErrorHandling).catch((e) => {
                 throw this._handleError(e, sql);
@@ -509,11 +517,18 @@ export class Connection extends SafeEventEmitter {
      * `asyncErrorHandling` is the per-call override (execute()/query()'s own
      * option of the same name); when omitted, the connection's own
      * `DatabaseConnectionParams.asyncErrorHandling` decides.
+     *
+     * Not `async` itself, deliberately: every branch below already returns a
+     * promise directly (`promise` itself, or `promise.catch(...)`'s own
+     * derived one) with no `await` in between, so there is nothing here that
+     * needs the function to be a coroutine. Marking it `async` anyway would
+     * still be correct, but the spec requires wrapping whatever an async
+     * function returns through a promise-resolve step, a genuine extra
+     * microtask tick on top of the one `promise`/`.catch()` already goes
+     * through - paid on every single query this wraps, disabled or not.
      */
-    async _captureErrorStack(promise, entry, asyncErrorHandling) {
-        const enabled = asyncErrorHandling != null
-            ? asyncErrorHandling
-            : coerceToBoolean(this._intlCon.config.asyncErrorHandling, true);
+    _captureErrorStack(promise, entry, asyncErrorHandling) {
+        const enabled = asyncErrorHandling ?? this._intlCon.config.asyncErrorHandling ?? true;
         if (!enabled)
             return promise;
         const stackHolder = {};

package/connection/intl-connection.d.ts

@@ -13,6 +13,8 @@ import { CopyFromStream, CopyToStream } from './copy-stream.js';
 export declare class IntlConnection extends SafeEventEmitter {
     private _executeReusedParserCache;
     protected _refCount: number;
+    protected _transactionDepth: number;
+    protected _savepointDepths: Map<string, number>;
     protected _config: ConnectionConfiguration;
     protected _onErrorSavePoint: string;
     transactionStatus: string;
@@ -30,9 +32,45 @@ export declare class IntlConnection extends SafeEventEmitter {
     connect(): Promise<void>;
     close(): Promise<void>;
     execute(sql: string, options?: ScriptExecuteOptions, cb?: (event: string, ...args: any[]) => void): Promise<ScriptResult>;
+    /**
+     * Starts a transaction, or - if one is already running - marks a nested
+     * level of it. Each call increments `_transactionDepth`; only the
+     * outermost one actually sends BEGIN (`inTransaction` is already false at
+     * that point). A matching number of commit() calls is then needed to
+     * actually commit - see commit().
+     */
     startTransaction(): Promise<void>;
+    /**
+     * Starts a savepoint, or - if one under the same `name` is already open -
+     * marks a nested level of it. Mirrors startTransaction(): only the
+     * outermost call for a given name actually sends SAVEPOINT: a savepoint
+     * already exists under that name, re-declaring it would just stack a
+     * second, independent one with the same name on the server rather than
+     * nesting the existing one.
+     */
     savepoint(name: string): Promise<void>;
-    commit(): Promise<void>;
+    /**
+     * Commits the transaction started by startTransaction() - or, when nested,
+     * just unwinds one level of `_transactionDepth`. The actual COMMIT is only
+     * sent once the depth reaches zero, i.e. once every startTransaction()
+     * call has a matching commit().
+     * @param immediate - Ignores `_transactionDepth` and commits right away,
+     *   regardless of how many nested levels are still open.
+     */
+    commit(immediate?: boolean): Promise<void>;
+    /**
+     * Releases the savepoint created by savepoint() - or, when nested, just
+     * unwinds one level of that name's depth. The actual RELEASE SAVEPOINT is
+     * only sent once that depth reaches zero.
+     * @param name - Name of the savepoint.
+     * @param immediate - Ignores the tracked depth and releases right away.
+     */
+    releaseSavepoint(name: string, immediate?: boolean): Promise<void>;
+    /**
+     * Rolls back the whole transaction, regardless of `_transactionDepth` -
+     * a rollback ends the transaction outright, so there is nothing left for
+     * any pending, still-nested commit() call to unwind.
+     */
     rollback(): Promise<void>;
     /**
      * Ends the current transaction as a prepared one: it stops being tied to
@@ -53,8 +91,13 @@ export declare class IntlConnection extends SafeEventEmitter {
     commitPrepared(name: string): Promise<void>;
     /** Discards a transaction left waiting by prepareTransaction(). */
     rollbackPrepared(name: string): Promise<void>;
+    /**
+     * Rolls back to the given savepoint, regardless of its tracked depth - a
+     * rollback discards it (and everything after it) outright, so there is
+     * nothing left for any pending, still-nested releaseSavepoint() call to
+     * unwind.
+     */
     rollbackToSavepoint(name: string): Promise<void>;
-    releaseSavepoint(name: string): Promise<void>;
     /** Asks the server to cancel whatever this session is running. */
     cancel(): Promise<void>;
     ref(): void;

package/connection/intl-connection.js

@@ -1,5 +1,4 @@
 import { performance } from 'node:perf_hooks';
-import { coerceToBoolean } from 'putil-varhelpers';
 import { ConnectionState, DEFAULT_COLUMN_FORMAT } from '../constants.js';
 import { GlobalTypeMap } from '../data-type-map.js';
 import { PgSocket } from '../protocol/pg-socket.js';
@@ -29,6 +28,8 @@ function columnFormatsEqual(a, b) {
 export class IntlConnection extends SafeEventEmitter {
     _executeReusedParserCache = new WeakMap();
     _refCount = 0;
+    _transactionDepth = 0;
+    _savepointDepths = new Map();
     _config;
     _onErrorSavePoint;
     transactionStatus = 'I';
@@ -109,58 +110,122 @@ export class IntlConnection extends SafeEventEmitter {
             });
         });
     }
-    async execute(sql, options, cb) {
+    async execute(sql, options = {}, cb) {
         this.assertConnected();
         const transactionCommand = sql.match(/^(\bBEGIN\b|\bCOMMIT\b|\bSTART\b|\bROLLBACK|SAVEPOINT|RELEASE\b)/i);
         let beginFirst = false;
         let commitLast = false;
+        const { autoCommit } = options;
         if (!transactionCommand) {
-            if (!this.inTransaction &&
-                (options?.autoCommit != null
-                    ? options?.autoCommit
-                    : this.config.autoCommit) === false) {
+            if ((autoCommit != null ? autoCommit : this.config.autoCommit) === false &&
+                !this.inTransaction) {
                 beginFirst = true;
             }
-            if (this.inTransaction && options?.autoCommit)
+            if (autoCommit && this.inTransaction)
                 commitLast = true;
         }
         if (beginFirst)
             await this._execute('BEGIN');
+        // this.inTransaction goes first here, before the config fallback: the
+        // result is only ever consulted below when it's true, so checking it
+        // first short-circuits that read on every call made outside of a
+        // transaction, the common case. Below, `rollbackOnError &&
+        // this.inTransaction` deliberately puts it last instead - re-checking
+        // live state a plain local boolean can't capture (the awaited call in
+        // between may have committed, rolled back, or errored the transaction
+        // out from under it) - but ordered so the cheap local read still
+        // short-circuits the getter whenever rollbackOnError is already
+        // false, which it is outside a transaction.
         const rollbackOnError = !transactionCommand &&
-            (options?.rollbackOnError != null
-                ? options.rollbackOnError
-                : coerceToBoolean(this.config.rollbackOnError, true));
-        if (this.inTransaction && rollbackOnError)
+            this.inTransaction &&
+            (options.rollbackOnError ?? this.config.rollbackOnError ?? true);
+        if (rollbackOnError && this.inTransaction)
             await this._execute('SAVEPOINT ' + this._onErrorSavePoint);
         try {
             const result = await this._execute(sql, options, cb);
             if (commitLast)
                 await this._execute('COMMIT');
-            else if (this.inTransaction && rollbackOnError) {
+            else if (rollbackOnError && this.inTransaction) {
                 await this._execute('RELEASE ' + this._onErrorSavePoint + ';');
             }
             return result;
         }
         catch (e) {
-            if (this.inTransaction && rollbackOnError)
+            if (rollbackOnError && this.inTransaction)
                 await this._execute('ROLLBACK TO ' + this._onErrorSavePoint + ';');
             throw e;
         }
     }
+    /**
+     * Starts a transaction, or - if one is already running - marks a nested
+     * level of it. Each call increments `_transactionDepth`; only the
+     * outermost one actually sends BEGIN (`inTransaction` is already false at
+     * that point). A matching number of commit() calls is then needed to
+     * actually commit - see commit().
+     */
     async startTransaction() {
+        this._transactionDepth++;
         if (!this.inTransaction)
             await this.execute('BEGIN');
     }
+    /**
+     * Starts a savepoint, or - if one under the same `name` is already open -
+     * marks a nested level of it. Mirrors startTransaction(): only the
+     * outermost call for a given name actually sends SAVEPOINT: a savepoint
+     * already exists under that name, re-declaring it would just stack a
+     * second, independent one with the same name on the server rather than
+     * nesting the existing one.
+     */
     async savepoint(name) {
         if (!(name && name.match(/^[a-zA-Z]\w+$/)))
             throw new Error(`Invalid savepoint "${name}"`);
-        await this.execute('BEGIN; SAVEPOINT ' + name);
+        const depth = (this._savepointDepths.get(name) || 0) + 1;
+        this._savepointDepths.set(name, depth);
+        if (depth === 1)
+            await this.execute('BEGIN; SAVEPOINT ' + name);
     }
-    async commit() {
+    /**
+     * Commits the transaction started by startTransaction() - or, when nested,
+     * just unwinds one level of `_transactionDepth`. The actual COMMIT is only
+     * sent once the depth reaches zero, i.e. once every startTransaction()
+     * call has a matching commit().
+     * @param immediate - Ignores `_transactionDepth` and commits right away,
+     *   regardless of how many nested levels are still open.
+     */
+    async commit(immediate) {
+        if (!immediate && this._transactionDepth > 1) {
+            this._transactionDepth--;
+            return;
+        }
+        this._transactionDepth = 0;
         if (this.inTransaction)
             await this.execute('COMMIT');
     }
+    /**
+     * Releases the savepoint created by savepoint() - or, when nested, just
+     * unwinds one level of that name's depth. The actual RELEASE SAVEPOINT is
+     * only sent once that depth reaches zero.
+     * @param name - Name of the savepoint.
+     * @param immediate - Ignores the tracked depth and releases right away.
+     */
+    async releaseSavepoint(name, immediate) {
+        if (!(name && name.match(/^[a-zA-Z]\w+$/)))
+            throw new Error(`Invalid savepoint "${name}"`);
+        const depth = this._savepointDepths.get(name) || 0;
+        if (!immediate && depth > 1) {
+            this._savepointDepths.set(name, depth - 1);
+            return;
+        }
+        this._savepointDepths.delete(name);
+        await this.execute('RELEASE SAVEPOINT ' + name, { autoCommit: false });
+    }
+    /**
+     * Rolls back the whole transaction, regardless of `_transactionDepth` -
+     * a rollback ends the transaction outright, so there is nothing left for
+     * any pending, still-nested commit() call to unwind.
+     */
     async rollback() {
+        this._transactionDepth = 0;
         if (this.inTransaction)
             await this.execute('ROLLBACK');
     }
@@ -189,16 +254,18 @@ export class IntlConnection extends SafeEventEmitter {
     async rollbackPrepared(name) {
         await this._execute('ROLLBACK PREPARED ' + escapeLiteral(name));
     }
+    /**
+     * Rolls back to the given savepoint, regardless of its tracked depth - a
+     * rollback discards it (and everything after it) outright, so there is
+     * nothing left for any pending, still-nested releaseSavepoint() call to
+     * unwind.
+     */
     async rollbackToSavepoint(name) {
         if (!(name && name.match(/^[a-zA-Z]\w+$/)))
             throw new Error(`Invalid savepoint "${name}"`);
+        this._savepointDepths.delete(name);
         await this.execute('ROLLBACK TO SAVEPOINT ' + name, { autoCommit: false });
     }
-    async releaseSavepoint(name) {
-        if (!(name && name.match(/^[a-zA-Z]\w+$/)))
-            throw new Error(`Invalid savepoint "${name}"`);
-        await this.execute('RELEASE SAVEPOINT ' + name, { autoCommit: false });
-    }
     /** Asks the server to cancel whatever this session is running. */
     cancel() {
         return this.socket.cancel();
@@ -257,22 +324,21 @@ export class IntlConnection extends SafeEventEmitter {
         await stream.waitStarted();
         return stream;
     }
-    async _execute(sql, options, cb) {
+    async _execute(sql, options = {}, cb) {
         this.ref();
         try {
-            const startTime = performance.now();
+            const timingEnabled = options.timing ?? this.config.timing ?? false;
+            const startTime = timingEnabled ? performance.now() : 0;
             const result = {
                 totalCommands: 0,
-                totalTime: 0,
                 results: [],
             };
-            const opts = options || {};
             let currentStart = startTime;
             let parsers;
             let current = { command: undefined };
             let fields;
             let error;
-            const typeMap = opts.typeMap || GlobalTypeMap;
+            const typeMap = options.typeMap || GlobalTypeMap;
             this.runningQueryCount++;
             return await this.socket.sendQueryMessage(sql, (code, msg, done) => {
                 switch (code) {
@@ -301,9 +367,9 @@ export class IntlConnection extends SafeEventEmitter {
                         break;
                     case Protocol.BackendMessageCode.DataRow:
                         {
-                            const row = opts.objectRows && current.fields
-                                ? parseObjectRow(parsers, msg.data, msg.columnCount, opts, current.fields)
-                                : parseRow(parsers, msg.data, msg.columnCount, opts);
+                            const row = options.objectRows && current.fields
+                                ? parseObjectRow(parsers, msg.data, msg.columnCount, options, current.fields)
+                                : parseRow(parsers, msg.data, msg.columnCount, options);
                             if (cb)
                                 cb('row', row);
                             current.rows = current.rows || [];
@@ -318,15 +384,17 @@ export class IntlConnection extends SafeEventEmitter {
                             current.command === 'UPDATE') {
                             current.rowsAffected = msg.rowCount;
                         }
-                        current.executeTime = performance.now() - currentStart;
+                        if (timingEnabled)
+                            current.executeTime = performance.now() - currentStart;
                         if (current.rows)
                             current.rowType =
-                                opts.objectRows && current.fields ? 'object' : 'array';
+                                options.objectRows && current.fields ? 'object' : 'array';
                         result.results.push(current);
                         if (cb)
                             cb('command-complete', current);
                         current = { command: undefined };
-                        currentStart = performance.now();
+                        if (timingEnabled)
+                            currentStart = performance.now();
                         break;
                     case Protocol.BackendMessageCode.ReadyForQuery:
                         this.transactionStatus = msg.status;
@@ -334,7 +402,8 @@ export class IntlConnection extends SafeEventEmitter {
                             done(error);
                             break;
                         }
-                        result.totalTime = performance.now() - startTime;
+                        if (timingEnabled)
+                            result.totalTime = performance.now() - startTime;
                         // Ignore COMMIT command that we added to sql
                         result.totalCommands = result.results.length;
                         done(undefined, result);
@@ -361,7 +430,8 @@ export class IntlConnection extends SafeEventEmitter {
         this.ref();
         try {
             const typeMap = options.typeMap || GlobalTypeMap;
-            const startTime = performance.now();
+            const timingEnabled = options.timing ?? this.config.timing ?? false;
+            const startTime = timingEnabled ? performance.now() : 0;
             const result = { command: undefined };
             const rows = [];
             let parsers;
@@ -428,7 +498,8 @@ export class IntlConnection extends SafeEventEmitter {
                 result.command === 'UPDATE') {
                 result.rowsAffected = commandTag?.rowCount;
             }
-            result.executeTime = performance.now() - startTime;
+            if (timingEnabled)
+                result.executeTime = performance.now() - startTime;
             return result;
         }
         finally {
@@ -498,7 +569,8 @@ export class IntlConnection extends SafeEventEmitter {
         this.ref();
         try {
             const typeMap = options.typeMap || GlobalTypeMap;
-            const startTime = performance.now();
+            const timingEnabled = options.timing ?? this.config.timing ?? false;
+            const startTime = timingEnabled ? performance.now() : 0;
             const result = { command: undefined };
             const rows = [];
             let parsers;
@@ -591,7 +663,8 @@ export class IntlConnection extends SafeEventEmitter {
                 result.command === 'UPDATE') {
                 result.rowsAffected = commandTag?.rowCount;
             }
-            result.executeTime = performance.now() - startTime;
+            if (timingEnabled)
+                result.executeTime = performance.now() - startTime;
             return result;
         }
         finally {

package/connection/prepared-statement.js

@@ -1,4 +1,3 @@
-import { coerceToBoolean } from 'putil-varhelpers';
 import { DEFAULT_COLUMN_FORMAT } from '../constants.js';
 import { GlobalTypeMap } from '../data-type-map.js';
 import { Protocol } from '../protocol/protocol.js';
@@ -60,35 +59,36 @@ export class PreparedStatement extends SafeEventEmitter {
         const transactionCommand = this.sql.match(/^(\bBEGIN\b|\bCOMMIT\b|\bSTART\b|\bROLLBACK|SAVEPOINT|RELEASE\b)/i);
         let beginFirst = false;
         let commitLast = false;
+        const autoCommit = options?.autoCommit;
         if (!transactionCommand) {
-            if (!intlCon.inTransaction &&
-                (options?.autoCommit != null
-                    ? options?.autoCommit
-                    : intlCon.config.autoCommit) === false) {
+            if ((autoCommit != null ? autoCommit : intlCon.config.autoCommit) ===
+                false &&
+                !intlCon.inTransaction) {
                 beginFirst = true;
             }
-            if (intlCon.inTransaction && options?.autoCommit)
+            if (autoCommit && intlCon.inTransaction)
                 commitLast = true;
         }
         if (beginFirst)
             await intlCon.execute('BEGIN');
+        // See IntlConnection.execute()'s own rollbackOnError for why
+        // intlCon.inTransaction goes first here but last in the checks below.
         const rollbackOnError = !transactionCommand &&
-            (options?.rollbackOnError != null
-                ? options.rollbackOnError
-                : coerceToBoolean(intlCon.config.rollbackOnError, true));
-        if (intlCon.inTransaction && rollbackOnError)
+            intlCon.inTransaction &&
+            (options?.rollbackOnError ?? intlCon.config.rollbackOnError ?? true);
+        if (rollbackOnError && intlCon.inTransaction)
             await intlCon.execute('SAVEPOINT ' + this._onErrorSavePoint);
         try {
             const result = await this._execute(options);
             if (commitLast)
                 await intlCon.execute('COMMIT');
-            else if (intlCon.inTransaction && rollbackOnError) {
+            else if (rollbackOnError && intlCon.inTransaction) {
                 await intlCon.execute('RELEASE ' + this._onErrorSavePoint + ';');
             }
             return result;
         }
         catch (e) {
-            if (intlCon.inTransaction && rollbackOnError) {
+            if (rollbackOnError && intlCon.inTransaction) {
                 await intlCon.execute('ROLLBACK TO ' + this._onErrorSavePoint + ';');
             }
             throw e;

package/data-types/numeric-type.js

@@ -59,9 +59,12 @@ export const NumericType = {
         const fracPad = (DEC_DIGITS - (fracPart.length % DEC_DIGITS)) % DEC_DIGITS;
         fracPart = fracPart + '0'.repeat(fracPad);
         const digits = [];
-        for (let i = 0; i < intPart.length; i += DEC_DIGITS)
+        let i;
+        let l = intPart.length;
+        for (i = 0; i < l; i += DEC_DIGITS)
             digits.push(+intPart.substring(i, i + DEC_DIGITS));
-        for (let i = 0; i < fracPart.length; i += DEC_DIGITS)
+        l = fracPart.length;
+        for (i = 0; i < l; i += DEC_DIGITS)
             digits.push(+fracPart.substring(i, i + DEC_DIGITS));
         // weight counts groups before the point, less one; leading zero groups
         // are dropped and lower it, trailing ones are simply dropped.
@@ -75,8 +78,10 @@ export const NumericType = {
         if (!digits.length)
             weight = 0;
         writeHeader(digits.length, weight, sign, dscale);
-        for (const d of digits)
-            buf.writeInt16BE(d);
+        l = digits.length;
+        for (i = 0; i < l; i++) {
+            buf.writeInt16BE(digits[i]);
+        }
     },
     decodeBinary(v, offset = 0) {
         const len = v.readInt16BE(offset);
@@ -190,7 +195,7 @@ export function numberBytesToString(digits, scale, weight, sign) {
         }
     }
     const extra = (i - scale) % DEC_DIGITS;
-    return out.substr(0, out.length - extra);
+    return out.substring(0, out.length - extra);
 }
 /* https://github.com/pgjdbc/pgjdbc/blob/3eca3a76aa4a04cb28cb960ed674cb67db30b5e3/pgjdbc/src/main/java/org/postgresql/util/ByteConverter.java */
 /**

package/interfaces/command-result.d.ts

@@ -18,7 +18,8 @@ export interface CommandResult {
      */
     rowType?: 'array' | 'object';
     /**
-     * Time elapsed to execute command
+     * Time elapsed to execute command - only measured when `timing` is
+     * enabled (off by default; see `DatabaseConnectionParams.timing`).
      */
     executeTime?: number;
     /**

package/interfaces/database-connection-params.d.ts

@@ -91,6 +91,19 @@ export interface DatabaseConnectionParams {
      * @default true
      */
     asyncErrorHandling?: boolean;
+    /**
+     * Whether `query()`/`execute()` (etc.) measure how long the call took -
+     * `CommandResult.executeTime` and `ScriptResult.totalTime`.
+     *
+     * Off by default: each measurement is a `performance.now()` call, and
+     * unlike `asyncErrorHandling` there is no way to compute it lazily only
+     * once something actually reads it - a real, if small, cost paid on
+     * every call whether or not the result is ever inspected, and one a
+     * client that does not offer this at all does not pay. Set to `true` to
+     * turn it on, connection-wide or for one call.
+     * @default false
+     */
+    timing?: boolean;
     debugLogger?: DebugLogger;
 }
 export type TargetSessionAttrs = 'read-write' | 'read-only' | 'primary' | 'standby' | 'prefer-standby';

package/interfaces/query-options.d.ts

@@ -60,4 +60,10 @@ export interface QueryOptions extends DataMappingOptions {
      * @default the connection's own setting
      */
     asyncErrorHandling?: boolean;
+    /**
+     * Overrides the connection's own `timing` for this call only - see
+     * `DatabaseConnectionParams.timing`.
+     * @default the connection's own setting
+     */
+    timing?: boolean;
 }

package/interfaces/script-execute-options.d.ts

@@ -40,4 +40,10 @@ export interface ScriptExecuteOptions extends DataMappingOptions {
      * @default the connection's own setting
      */
     asyncErrorHandling?: boolean;
+    /**
+     * Overrides the connection's own `timing` for this call only - see
+     * `DatabaseConnectionParams.timing`.
+     * @default the connection's own setting
+     */
+    timing?: boolean;
 }

package/interfaces/script-result.d.ts

@@ -9,7 +9,8 @@ export interface ScriptResult {
      */
     totalCommands: number;
     /**
-     * Total execution time
+     * Total execution time - only measured when `timing` is enabled (off by
+     * default; see `DatabaseConnectionParams.timing`).
      */
-    totalTime: number;
+    totalTime?: number;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "postgrejs",
   "description": "Professional PostgreSQL client NodeJS",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "author": "Panates",
   "license": "BSD-3-Clause",
   "dependencies": {

package/protocol/frontend.js

@@ -52,7 +52,12 @@ export class Frontend {
             .writeInt32BE(0) // Preserve length
             .writeInt16BE(Protocol.VERSION_MAJOR)
             .writeInt16BE(Protocol.VERSION_MINOR);
-        for (const [k, v] of Object.entries(args)) {
+        const entries = Object.entries(args);
+        const l = entries.length;
+        let k;
+        let v;
+        for (let i = 0; i < l; i++) {
+            [k, v] = entries[i];
             if (k !== 'client_encoding')
                 io.writeCString(k, 'utf8').writeCString(v, 'utf8');
         }
@@ -105,16 +110,19 @@ export class Frontend {
     getParseMessage(args) {
         if (args.statement && args.statement.length > 63)
             throw new Error('Query name length must be lower than 63');
+        const { paramTypes } = args;
         const io = this._io
             .start()
             .writeInt8(Protocol.FrontendMessageCode.Parse)
             .writeInt32BE(0) // Preserve header
             .writeCString(args.statement || '', 'utf8')
             .writeCString(args.sql, 'utf8')
-            .writeUInt16BE(args.paramTypes ? args.paramTypes.length : 0);
-        if (args.paramTypes) {
-            for (const t of args.paramTypes) {
-                io.writeUInt32BE(t || 0);
+            .writeUInt16BE(paramTypes?.length || 0);
+        if (paramTypes) {
+            let i;
+            const l = paramTypes.length;
+            for (i = 0; i < l; i++) {
+                io.writeUInt32BE(paramTypes[i] || 0);
             }
         }
         return setLengthAndFlush(io, 1);

package/protocol/sasl.js

@@ -96,7 +96,7 @@ export var SASL;
         const arr = data.split(',');
         for (const s of arr) {
             if (s[0] === 'v')
-                serverSignature = s.substr(2);
+                serverSignature = s.substring(2);
         }
         if (serverSignature !== session.serverSignature)
             throw new Error('SASL: Server signature does not match');

package/util/abort-signal.d.ts

@@ -20,5 +20,15 @@ export declare function abortError(signal: AbortSignal, cause?: unknown): Error;
  *
  * The listener is always removed again: one long-lived signal shared by many
  * queries would otherwise accumulate a listener per query.
+ *
+ * Not `async` itself: the overwhelmingly common case (no signal passed) just
+ * returns `run()`'s own promise straight through. Marking this function
+ * `async` would still be correct, but every `async function` return goes
+ * through the spec's promise-resolve machinery - a real extra microtask
+ * tick, even for a value that is already the right kind of promise - and
+ * this sits on every query's hot path, signal or not. The slow path (a
+ * signal actually given) is factored into its own async helper below, where
+ * the cost is negligible next to the abort-listener bookkeeping it already
+ * does.
  */
 export declare function withAbortSignal<T>(signal: AbortSignal | undefined, cancel: () => Promise<void>, run: () => Promise<T>): Promise<T>;

package/util/abort-signal.js

@@ -36,13 +36,26 @@ export function abortError(signal, cause) {
  *
  * The listener is always removed again: one long-lived signal shared by many
  * queries would otherwise accumulate a listener per query.
+ *
+ * Not `async` itself: the overwhelmingly common case (no signal passed) just
+ * returns `run()`'s own promise straight through. Marking this function
+ * `async` would still be correct, but every `async function` return goes
+ * through the spec's promise-resolve machinery - a real extra microtask
+ * tick, even for a value that is already the right kind of promise - and
+ * this sits on every query's hot path, signal or not. The slow path (a
+ * signal actually given) is factored into its own async helper below, where
+ * the cost is negligible next to the abort-listener bookkeeping it already
+ * does.
  */
-export async function withAbortSignal(signal, cancel, run) {
+export function withAbortSignal(signal, cancel, run) {
     if (!signal)
         return run();
     // Already aborted: nothing has been sent, so nothing needs cancelling.
     if (signal.aborted)
-        throw abortError(signal);
+        return Promise.reject(abortError(signal));
+    return runWithAbortSignal(signal, cancel, run);
+}
+async function runWithAbortSignal(signal, cancel, run) {
     const onAbort = () => {
         // A failed cancel (the session already gone, say) must not replace the
         // error the query itself is about to report.