node-firebird 2.15.0 → 2.16.0

package/README.md

@@ -11,7 +11,7 @@
 - [Installation](#installation)
 - [Usage](#usage) — including [developing the driver](#developing-the-driver)
 - [Promises and async/await](#promises-and-asyncawait) — the `*Async` API plus `withConnection` / `withTransaction` helpers
-- [Connection types](#connection-types) — connection options, `firebird://` URIs and traditional connection strings, classic connections, pooling
+- [Connection types](#connection-types) — connection options, `firebird://` / `inet://` URIs and traditional connection strings, classic connections, pooling
 - [Database object (db)](#database-object-db) — database, transaction and statement methods/options
 - [Examples](#examples) — parametrized queries, tagged-template queries (sql), named placeholders, nested result tables (nestTables), row-key transforms (transformKeys), result metadata / affected rows (withMeta), custom type parsers (typeCast), BLOBs, streaming big data, transactions, driver events, database events (POST_EVENT), service manager, charsets/encoding, Firebird 3.0–6.0 features
 - [Extensive Examples](#extensive-examples) — DECFLOAT/INT128, query cancellation (AbortSignal), batch execution (bulk inserts incl. BLOBs), bulk-insert stream (batchStream), statement timeouts, scrollable cursors, RETURNING multiple rows, SKIP LOCKED, advanced pooling
@@ -200,6 +200,7 @@ options.dbCryptConfig = undefined; // optional; database encryption key for encr
 options.connectTimeout = 10000; // optional; timeout in ms for a single pool.get() attach operation (default: no timeout)
 options.enableKeepAlive = true; // TCP keepalive probing to detect dead/stale connections (same option names as mysql2); set to false to disable
 options.keepAliveInitialDelay = 60000; // ms a socket must be idle before the first keepalive probe (ignored when enableKeepAlive is false)
+options.ipFamily = 4; // optional; force IPv4 (4) or IPv6 (6) when resolving host — also set by inet4:// / inet6:// URIs
 options.parallelWorkers = undefined; // optional; request multiple thread workers for maintenance/index tasks (FB >= 5)
 options.maxInlineBlobSize = undefined; // optional; threshold size in bytes for inline blob transmission (default 65535, FB >= 5.0.3)
 options.maxNegotiatedProtocols = undefined; // optional; cap how many protocol versions are offered, oldest first (default: all, up to Protocol 20; set to 10 to stop at Protocol 19)
@@ -248,6 +249,20 @@ be passed as query parameters. IPv6 hosts use brackets:
 `firebird://[::1]:3050/employee`. The parser is exported as
 `Firebird.parseConnectionUri(uri)` if you need the resulting options object.
 
+Firebird's own URL-style connection strings (Firebird 3+) are accepted with
+the same rules, so a string that works with isql works here unchanged:
+
+| URI | meaning |
+| :--- | :--- |
+| `inet://host/employee` | same as `firebird://host/employee` |
+| `inet://host:3051//var/fb/prod.fdb` | host, port and an absolute path |
+| `inet4://host/employee` | resolve `host` as IPv4 only (sets `ipFamily: 4`) |
+| `inet6://[::1]/employee` | IPv6 only (sets `ipFamily: 6`) |
+
+`inet://` strings may carry credentials and query options exactly like
+`firebird://` ones. The local-only transports `xnet://` and `wnet://` are
+rejected — this driver speaks TCP only.
+
 ### Traditional connection strings (old style)
 
 The classic Firebird connection string format — the same

package/lib/pool.js

@@ -258,6 +258,12 @@ class Pool extends events_1.default.EventEmitter {
                             self.internaldb.splice(self.internaldb.indexOf(db), 1);
                             self.emit('remove', db);
                         }
+                        else if (self._destroyed) {
+                            // destroy() deliberately does not wait for checked-out
+                            // connections. Close one for good when its caller later
+                            // releases it instead of returning it to a stopped pool.
+                            self._retire(db);
+                        }
                         else if (self._isExpired(db)) {
                             // worn out (maxUses / maxLifetimeMillis): close it
                             // for good instead of returning it to the idle
@@ -318,7 +324,7 @@ class Pool extends events_1.default.EventEmitter {
                 callback();
             }
         }
-        this.internaldb.forEach(function (db) {
+        this.internaldb.slice().forEach(function (db) {
             if (db.connection._pooled === false) {
                 detachCallback();
                 return;
@@ -326,15 +332,20 @@ class Pool extends events_1.default.EventEmitter {
             // check if the db is not free into the pool otherwise user should manual detach it
             var _db_in_pool = self.pooldb.indexOf(db);
             if (_db_in_pool !== -1) {
-                self.pooldb.splice(_db_in_pool, 1);
                 db.connection._pooled = false;
-                db.detach(detachCallback);
-                self.emit('remove', db);
+                // Keep the connection marked idle until physical detach emits
+                // its detach event. The listener above will then ignore that
+                // event instead of counting it as an active release.
+                db.detach(function (err) {
+                    self._forget(db);
+                    detachCallback(err);
+                });
             }
             else {
                 // [Fix 5] Connection is currently in use (dbinuse > 0).
                 // The caller is responsible for releasing it via detach().
-                // Count it down here so the destroy() callback is not blocked forever.
+                // Count it down here so the destroy() callback is not blocked forever;
+                // the detach listener retires it when the caller releases it.
                 detachCallback();
             }
         });

package/lib/types.d.ts

@@ -432,6 +432,12 @@ export interface Options {
      * probe is sent (default 60000). Ignored when enableKeepAlive is false.
      */
     keepAliveInitialDelay?: number;
+    /**
+     * Force the TCP socket to IPv4 (4) or IPv6 (6) when resolving `host`.
+     * Unset lets the resolver choose. Set automatically by `inet4://` /
+     * `inet6://` connection URIs.
+     */
+    ipFamily?: 4 | 6;
     pluginName?: string;
     parallelWorkers?: number;
     maxInlineBlobSize?: number;

package/lib/uri.d.ts

@@ -5,9 +5,11 @@
  ***************************************/
 import type { Options } from './types';
 /**
- * Parse a firebird:// connection URI into an options object.
+ * Parse a firebird:// or inet:// connection URI into an options object.
  *
  *   firebird://user:password@host:port/database?option=value&...
+ *   inet://host:port/database              (Firebird's own URL style;
+ *   inet4://... / inet6://...               also force IPv4 / IPv6)
  *
  * The database part:
  *   firebird://host/employee              → alias "employee"
@@ -45,13 +47,15 @@ export declare function parseConnectionUri(uri: string): Options;
  */
 export declare function parseOldStyleConnectionString(str: string): Options;
 /**
- * Parse any connection string the driver accepts: a firebird:// URI, or a
- * traditional [host[/port]:]database string when there is no scheme.
+ * Parse any connection string the driver accepts: a firebird:// or
+ * inet[4|6]:// URI, or a traditional [host[/port]:]database string when
+ * there is no scheme.
  */
 export declare function parseConnectionString(str: string): Options;
 /**
- * Accept either an options object or a connection string (firebird:// URI
- * or traditional host[/port]:database) everywhere options are taken.
+ * Accept either an options object or a connection string (firebird:// or
+ * inet:// URI, or traditional host[/port]:database) everywhere options are
+ * taken.
  * Strings are parsed; objects pass through unchanged.
  */
 export declare function normalizeOptions<T>(options: T | string): T;

package/lib/uri.js

@@ -22,7 +22,7 @@ const NUMBER_KEYS = new Set([
     'port', 'pageSize', 'timeout', 'retryConnectionInterval',
     'blobChunkSize', 'blobReadChunkSize', 'wireCrypt', 'parallelWorkers',
     'maxInlineBlobSize', 'maxNegotiatedProtocols', 'connectTimeout',
-    'min', 'idleTimeoutMillis', 'keepAliveInitialDelay',
+    'min', 'idleTimeoutMillis', 'keepAliveInitialDelay', 'ipFamily',
 ]);
 function coerce(key, value) {
     if (BOOLEAN_KEYS.has(key)) {
@@ -38,9 +38,29 @@ function coerce(key, value) {
     return value;
 }
 /**
- * Parse a firebird:// connection URI into an options object.
+ * URI schemes accepted by parseConnectionUri. `firebird://` is this driver's
+ * own scheme; `inet://`, `inet4://` and `inet6://` are Firebird's native
+ * URL-style connection strings (Firebird 3+), so a string that works with
+ * isql works here too. inet4/inet6 pin the socket's IP family (the
+ * `ipFamily` option); inet and firebird let the resolver pick.
+ */
+const URI_SCHEMES = {
+    'firebird:': undefined,
+    'inet:': undefined,
+    'inet4:': 4,
+    'inet6:': 6,
+};
+/**
+ * Firebird protocols this driver cannot speak: they are local-machine IPC
+ * transports (shared memory / named pipes), not TCP.
+ */
+const LOCAL_SCHEMES = /^(xnet|wnet):$/;
+/**
+ * Parse a firebird:// or inet:// connection URI into an options object.
  *
  *   firebird://user:password@host:port/database?option=value&...
+ *   inet://host:port/database              (Firebird's own URL style;
+ *   inet4://... / inet6://...               also force IPv4 / IPv6)
  *
  * The database part:
  *   firebird://host/employee              → alias "employee"
@@ -64,11 +84,20 @@ function parseConnectionUri(uri) {
     catch (e) {
         throw new Error('Invalid connection URI: ' + uri);
     }
-    if (url.protocol !== 'firebird:') {
-        throw new Error('Unsupported connection URI scheme "' + url.protocol.replace(/:$/, '') +
-            '" (expected firebird://...)');
+    var scheme = url.protocol.toLowerCase();
+    if (LOCAL_SCHEMES.test(scheme)) {
+        throw new Error('Unsupported connection URI scheme "' + scheme.replace(/:$/, '') +
+            '" (local IPC transports are not available over the wire — use inet:// or firebird://)');
+    }
+    if (!Object.prototype.hasOwnProperty.call(URI_SCHEMES, scheme)) {
+        throw new Error('Unsupported connection URI scheme "' + scheme.replace(/:$/, '') +
+            '" (expected firebird://, inet://, inet4:// or inet6://)');
     }
     var options = {};
+    var ipFamily = URI_SCHEMES[scheme];
+    if (ipFamily !== undefined) {
+        options.ipFamily = ipFamily;
+    }
     if (url.hostname) {
         // URL keeps IPv6 hostnames bracketed ([::1]); net.connect wants them bare
         options.host = url.hostname.replace(/^\[(.*)\]$/, '$1');
@@ -172,8 +201,9 @@ function parseOldStyleConnectionString(str) {
 }
 const URI_SCHEME = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//;
 /**
- * Parse any connection string the driver accepts: a firebird:// URI, or a
- * traditional [host[/port]:]database string when there is no scheme.
+ * Parse any connection string the driver accepts: a firebird:// or
+ * inet[4|6]:// URI, or a traditional [host[/port]:]database string when
+ * there is no scheme.
  */
 function parseConnectionString(str) {
     return URI_SCHEME.test(str)
@@ -181,8 +211,9 @@ function parseConnectionString(str) {
         : parseOldStyleConnectionString(str);
 }
 /**
- * Accept either an options object or a connection string (firebird:// URI
- * or traditional host[/port]:database) everywhere options are taken.
+ * Accept either an options object or a connection string (firebird:// or
+ * inet:// URI, or traditional host[/port]:database) everywhere options are
+ * taken.
  * Strings are parsed; objects pass through unchanged.
  */
 function normalizeOptions(options) {

package/lib/wire/connection.js

@@ -168,7 +168,7 @@ class Connection {
         this._detachTimeout;
         this._detachCallback;
         this._detachAuto;
-        this._socket = new socket_1.default(port, host, options.enableKeepAlive !== false, options.keepAliveInitialDelay);
+        this._socket = new socket_1.default(port, host, options.enableKeepAlive !== false, options.keepAliveInitialDelay, options.ipFamily);
         this._pending = [];
         this._isOpened = false;
         this._isClosed = false;

package/lib/wire/socket.d.ts

@@ -32,7 +32,7 @@ declare class Socket {
     encrypt: boolean;
     encryptCipher: any;
     decryptCipher: any;
-    constructor(port: number, host: string, enableKeepAlive?: boolean, keepAliveInitialDelay?: number);
+    constructor(port: number, host: string, enableKeepAlive?: boolean, keepAliveInitialDelay?: number, ipFamily?: 4 | 6);
     /**
      * Decompress and/or decrypt data when received.
      * Override on data event.

package/lib/wire/socket.js

@@ -82,9 +82,10 @@ class ChaChaCipher {
  */
 class Socket {
     static { this.Arc4 = Arc4; }
-    constructor(port, host, enableKeepAlive = true, keepAliveInitialDelay = 60000) {
+    constructor(port, host, enableKeepAlive = true, keepAliveInitialDelay = 60000, ipFamily) {
         this.compress = false;
-        this._socket = net_1.default.createConnection(port, host);
+        // family: 0 is "either" (Node's default); 4/6 pin the resolver
+        this._socket = net_1.default.createConnection({ port: port, host: host, family: ipFamily || 0 });
         this._socket.setNoDelay(true);
         // TCP keepalive probing detects dead/stale connections; the delay is
         // how long the socket must be idle before the first probe.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "node-firebird",
-    "version": "2.15.0",
+    "version": "2.16.0",
     "description": "Pure JavaScript and Asynchronous Firebird client for Node.js.",
     "keywords": [
         "firebird",
@@ -58,6 +58,6 @@
         "@types/node": "^26.1.1",
         "oxlint": "^0.15.11",
         "typescript": "^7.0.2",
-        "vitest": "^4.0.18"
+        "vitest": "^4.1.11"
     }
 }

package/src/pool.ts

@@ -281,6 +281,11 @@ class Pool extends Events.EventEmitter {
                         if (db.connection._isClosed || db.connection._isDetach || db.connection._pooled === false) {
                             self.internaldb.splice(self.internaldb.indexOf(db), 1);
                             self.emit('remove', db);
+                        } else if (self._destroyed) {
+                            // destroy() deliberately does not wait for checked-out
+                            // connections. Close one for good when its caller later
+                            // releases it instead of returning it to a stopped pool.
+                            self._retire(db);
                         } else if (self._isExpired(db)) {
                             // worn out (maxUses / maxLifetimeMillis): close it
                             // for good instead of returning it to the idle
@@ -348,7 +353,7 @@ class Pool extends Events.EventEmitter {
             }
         }
 
-        this.internaldb.forEach(function(db) {
+        this.internaldb.slice().forEach(function(db) {
             if (db.connection._pooled === false) {
                 detachCallback();
                 return;
@@ -356,14 +361,19 @@ class Pool extends Events.EventEmitter {
             // check if the db is not free into the pool otherwise user should manual detach it
             var _db_in_pool = self.pooldb.indexOf(db);
             if (_db_in_pool !== -1) {
-                self.pooldb.splice(_db_in_pool, 1);
                 db.connection._pooled = false;
-                db.detach(detachCallback);
-                self.emit('remove', db);
+                // Keep the connection marked idle until physical detach emits
+                // its detach event. The listener above will then ignore that
+                // event instead of counting it as an active release.
+                db.detach(function(err?: any) {
+                    self._forget(db);
+                    detachCallback(err);
+                });
             } else {
                 // [Fix 5] Connection is currently in use (dbinuse > 0).
                 // The caller is responsible for releasing it via detach().
-                // Count it down here so the destroy() callback is not blocked forever.
+                // Count it down here so the destroy() callback is not blocked forever;
+                // the detach listener retires it when the caller releases it.
                 detachCallback();
             }
         });

package/src/types.ts

@@ -493,6 +493,12 @@ export interface Options {
      * probe is sent (default 60000). Ignored when enableKeepAlive is false.
      */
     keepAliveInitialDelay?: number;
+    /**
+     * Force the TCP socket to IPv4 (4) or IPv6 (6) when resolving `host`.
+     * Unset lets the resolver choose. Set automatically by `inet4://` /
+     * `inet6://` connection URIs.
+     */
+    ipFamily?: 4 | 6;
     pluginName?: string;
     parallelWorkers?: number;
     maxInlineBlobSize?: number;

package/src/uri.ts

@@ -20,7 +20,7 @@ const NUMBER_KEYS = new Set([
     'port', 'pageSize', 'timeout', 'retryConnectionInterval',
     'blobChunkSize', 'blobReadChunkSize', 'wireCrypt', 'parallelWorkers',
     'maxInlineBlobSize', 'maxNegotiatedProtocols', 'connectTimeout',
-    'min', 'idleTimeoutMillis', 'keepAliveInitialDelay',
+    'min', 'idleTimeoutMillis', 'keepAliveInitialDelay', 'ipFamily',
 ]);
 
 function coerce(key: string, value: string): any {
@@ -38,9 +38,31 @@ function coerce(key: string, value: string): any {
 }
 
 /**
- * Parse a firebird:// connection URI into an options object.
+ * URI schemes accepted by parseConnectionUri. `firebird://` is this driver's
+ * own scheme; `inet://`, `inet4://` and `inet6://` are Firebird's native
+ * URL-style connection strings (Firebird 3+), so a string that works with
+ * isql works here too. inet4/inet6 pin the socket's IP family (the
+ * `ipFamily` option); inet and firebird let the resolver pick.
+ */
+const URI_SCHEMES: Record<string, 4 | 6 | undefined> = {
+    'firebird:': undefined,
+    'inet:': undefined,
+    'inet4:': 4,
+    'inet6:': 6,
+};
+
+/**
+ * Firebird protocols this driver cannot speak: they are local-machine IPC
+ * transports (shared memory / named pipes), not TCP.
+ */
+const LOCAL_SCHEMES = /^(xnet|wnet):$/;
+
+/**
+ * Parse a firebird:// or inet:// connection URI into an options object.
  *
  *   firebird://user:password@host:port/database?option=value&...
+ *   inet://host:port/database              (Firebird's own URL style;
+ *   inet4://... / inet6://...               also force IPv4 / IPv6)
  *
  * The database part:
  *   firebird://host/employee              → alias "employee"
@@ -64,13 +86,23 @@ export function parseConnectionUri(uri: string): Options {
         throw new Error('Invalid connection URI: ' + uri);
     }
 
-    if (url.protocol !== 'firebird:') {
-        throw new Error('Unsupported connection URI scheme "' + url.protocol.replace(/:$/, '') +
-            '" (expected firebird://...)');
+    var scheme = url.protocol.toLowerCase();
+    if (LOCAL_SCHEMES.test(scheme)) {
+        throw new Error('Unsupported connection URI scheme "' + scheme.replace(/:$/, '') +
+            '" (local IPC transports are not available over the wire — use inet:// or firebird://)');
+    }
+    if (!Object.prototype.hasOwnProperty.call(URI_SCHEMES, scheme)) {
+        throw new Error('Unsupported connection URI scheme "' + scheme.replace(/:$/, '') +
+            '" (expected firebird://, inet://, inet4:// or inet6://)');
     }
 
     var options: any = {};
 
+    var ipFamily = URI_SCHEMES[scheme];
+    if (ipFamily !== undefined) {
+        options.ipFamily = ipFamily;
+    }
+
     if (url.hostname) {
         // URL keeps IPv6 hostnames bracketed ([::1]); net.connect wants them bare
         options.host = url.hostname.replace(/^\[(.*)\]$/, '$1');
@@ -182,8 +214,9 @@ export function parseOldStyleConnectionString(str: string): Options {
 const URI_SCHEME = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//;
 
 /**
- * Parse any connection string the driver accepts: a firebird:// URI, or a
- * traditional [host[/port]:]database string when there is no scheme.
+ * Parse any connection string the driver accepts: a firebird:// or
+ * inet[4|6]:// URI, or a traditional [host[/port]:]database string when
+ * there is no scheme.
  */
 export function parseConnectionString(str: string): Options {
     return URI_SCHEME.test(str)
@@ -192,8 +225,9 @@ export function parseConnectionString(str: string): Options {
 }
 
 /**
- * Accept either an options object or a connection string (firebird:// URI
- * or traditional host[/port]:database) everywhere options are taken.
+ * Accept either an options object or a connection string (firebird:// or
+ * inet:// URI, or traditional host[/port]:database) everywhere options are
+ * taken.
  * Strings are parsed; objects pass through unchanged.
  */
 export function normalizeOptions<T>(options: T | string): T {

package/src/wire/connection.ts

@@ -186,7 +186,8 @@ class Connection {
         this._detachAuto;
         this._socket = new Socket(port, host,
             options.enableKeepAlive !== false,
-            options.keepAliveInitialDelay);
+            options.keepAliveInitialDelay,
+            options.ipFamily);
         this._pending = [];
         this._isOpened = false;
         this._isClosed = false;

package/src/wire/socket.ts

@@ -109,8 +109,9 @@ class Socket {
     encryptCipher: any;
     decryptCipher: any;
 
-    constructor(port: number, host: string, enableKeepAlive = true, keepAliveInitialDelay = 60000) {
-        this._socket = net.createConnection(port, host);
+    constructor(port: number, host: string, enableKeepAlive = true, keepAliveInitialDelay = 60000, ipFamily?: 4 | 6) {
+        // family: 0 is "either" (Node's default); 4/6 pin the resolver
+        this._socket = net.createConnection({ port: port, host: host, family: ipFamily || 0 });
         this._socket.setNoDelay(true);
         // TCP keepalive probing detects dead/stale connections; the delay is
         // how long the socket must be idle before the first probe.