node-firebird 2.8.1 → 2.9.0

package/src/types.ts

@@ -100,9 +100,22 @@ export type BatchOptions = {
     chunkSize?: number;
 };
 
+/**
+ * Positional query parameters (array), or — when named placeholders are
+ * enabled via the `namedPlaceholders` connection/query option — values by
+ * placeholder name.
+ */
+export type QueryParams = any[] | Record<string, any>;
+
 export type QueryOptions = {
     timeout?: number;
     scrollable?: boolean;
+    /**
+     * Per-query override of the `namedPlaceholders` connection option
+     * (e.g. disable it for one EXECUTE BLOCK statement whose body uses
+     * `:variable` PSQL references).
+     */
+    namedPlaceholders?: boolean;
     /**
      * Abort the query when the signal fires (Firebird 2.5+ / protocol 12+).
      * If the signal is already aborted the query is not sent at all and the
@@ -118,11 +131,11 @@ export interface Database {
     detach(callback?: SimpleCallback): Database;
     transaction(options: TransactionOptions|Isolation|TransactionCallback, callback?: TransactionCallback): Database;
     newStatement(query: string, callback: (err: Error | null, statement: Statement) => void): Database;
-    query(query: string, params: any[], callback: QueryCallback, options?: QueryOptions): Database;
-    execute(query: string, params: any[], callback: QueryCallback, options?: QueryOptions): Database;
+    query(query: string, params: QueryParams, callback: QueryCallback, options?: QueryOptions): Database;
+    execute(query: string, params: QueryParams, callback: QueryCallback, options?: QueryOptions): Database;
     /** Bulk-execute in its own transaction, all-or-nothing (Firebird 4.0+). */
-    executeBatch(query: string, rows: any[][], callback?: (err: any, result: BatchResult) => void, options?: BatchOptions): Database;
-    sequentially(query: string, params: any[], rowCallback: SequentialCallback, callback: SimpleCallback, options?: QueryOptions | boolean): Database;
+    executeBatch(query: string, rows: QueryParams[], callback?: (err: any, result: BatchResult) => void, options?: BatchOptions): Database;
+    sequentially(query: string, params: QueryParams, rowCallback: SequentialCallback, callback: SimpleCallback, options?: QueryOptions | boolean): Database;
     drop(callback: SimpleCallback): void;
     escape(value: any): string;
     attachEvent(callback: any): this;
@@ -133,10 +146,10 @@ export interface Database {
 
     // Promise / async-await API (see README § Promises / async–await).
     // Result metadata is only available through the callback API.
-    queryAsync<T = any>(query: string, params?: any[], options?: QueryOptions): Promise<T[]>;
-    executeAsync<T = any>(query: string, params?: any[], options?: QueryOptions): Promise<T[]>;
-    executeBatchAsync(query: string, rows: any[][], options?: BatchOptions): Promise<BatchResult>;
-    sequentiallyAsync(query: string, params: any[] | undefined, rowCallback: SequentialCallback, options?: QueryOptions | boolean): Promise<void>;
+    queryAsync<T = any>(query: string, params?: QueryParams, options?: QueryOptions): Promise<T[]>;
+    executeAsync<T = any>(query: string, params?: QueryParams, options?: QueryOptions): Promise<T[]>;
+    executeBatchAsync(query: string, rows: QueryParams[], options?: BatchOptions): Promise<BatchResult>;
+    sequentiallyAsync(query: string, params: QueryParams | undefined, rowCallback: SequentialCallback, options?: QueryOptions | boolean): Promise<void>;
     sequentiallyAsync(query: string, rowCallback: SequentialCallback, options?: QueryOptions | boolean): Promise<void>;
     transactionAsync(options?: TransactionOptions | Isolation): Promise<Transaction>;
     startTransactionAsync(options?: TransactionOptions | Isolation): Promise<Transaction>;
@@ -158,21 +171,21 @@ export interface Database {
 
 export interface Transaction {
     newStatement(query: string, callback: (err: Error | null, statement: Statement) => void): void;
-    query(query: string, params: any[], callback: QueryCallback, options?: QueryOptions): void;
-    execute(query: string, params: any[], callback: QueryCallback, options?: QueryOptions): void;
+    query(query: string, params: QueryParams, callback: QueryCallback, options?: QueryOptions): void;
+    execute(query: string, params: QueryParams, callback: QueryCallback, options?: QueryOptions): void;
     /** Bulk-execute within this transaction; per-record failures do not roll back (Firebird 4.0+). */
-    executeBatch(query: string, rows: any[][], callback?: (err: any, result: BatchResult) => void, options?: BatchOptions): void;
-    sequentially(query: string, params: any[], rowCallback: SequentialCallback, callback: SimpleCallback, options?: QueryOptions | boolean): Database;
+    executeBatch(query: string, rows: QueryParams[], callback?: (err: any, result: BatchResult) => void, options?: BatchOptions): void;
+    sequentially(query: string, params: QueryParams, rowCallback: SequentialCallback, callback: SimpleCallback, options?: QueryOptions | boolean): Database;
     commit(callback?: SimpleCallback): void;
     commitRetaining(callback?: SimpleCallback): void;
     rollback(callback?: SimpleCallback): void;
     rollbackRetaining(callback?: SimpleCallback): void;
 
     // Promise / async-await API
-    queryAsync<T = any>(query: string, params?: any[], options?: QueryOptions): Promise<T[]>;
-    executeAsync<T = any>(query: string, params?: any[], options?: QueryOptions): Promise<T[]>;
-    executeBatchAsync(query: string, rows: any[][], options?: BatchOptions): Promise<BatchResult>;
-    sequentiallyAsync(query: string, params: any[] | undefined, rowCallback: SequentialCallback, options?: QueryOptions | boolean): Promise<void>;
+    queryAsync<T = any>(query: string, params?: QueryParams, options?: QueryOptions): Promise<T[]>;
+    executeAsync<T = any>(query: string, params?: QueryParams, options?: QueryOptions): Promise<T[]>;
+    executeBatchAsync(query: string, rows: QueryParams[], options?: BatchOptions): Promise<BatchResult>;
+    sequentiallyAsync(query: string, params: QueryParams | undefined, rowCallback: SequentialCallback, options?: QueryOptions | boolean): Promise<void>;
     sequentiallyAsync(query: string, rowCallback: SequentialCallback, options?: QueryOptions | boolean): Promise<void>;
     newStatementAsync(query: string): Promise<Statement>;
     commitAsync(): Promise<void>;
@@ -185,17 +198,17 @@ export interface Statement {
     close(callback?: SimpleCallback): void;
     drop(callback?: SimpleCallback): void;
     release(callback?: SimpleCallback): void;
-    execute(transaction: Transaction, params: any[], callback: QueryCallback, options?: QueryOptions): void;
+    execute(transaction: Transaction, params: QueryParams, callback: QueryCallback, options?: QueryOptions): void;
     fetch(transaction: Transaction, count: number, callback: QueryCallback): void;
     fetchScroll(transaction: Transaction, direction: 'NEXT' | 'PRIOR' | 'FIRST' | 'LAST' | 'ABSOLUTE' | 'RELATIVE' | number, offset: number, count: number, callback: QueryCallback): void;
     fetchAll(transaction: Transaction, callback: QueryCallback): void;
 
     /** Execute this prepared statement once per row (Firebird 4.0+ batch API). */
-    executeBatch(transaction: Transaction, rows: any[][], callback?: (err: any, result: BatchResult) => void, options?: BatchOptions): void;
+    executeBatch(transaction: Transaction, rows: QueryParams[], callback?: (err: any, result: BatchResult) => void, options?: BatchOptions): void;
 
     // Promise / async-await API
-    executeAsync(transaction: Transaction, params?: any[], options?: QueryOptions): Promise<any>;
-    executeBatchAsync(transaction: Transaction, rows: any[][], options?: BatchOptions): Promise<BatchResult>;
+    executeAsync(transaction: Transaction, params?: QueryParams, options?: QueryOptions): Promise<any>;
+    executeBatchAsync(transaction: Transaction, rows: QueryParams[], options?: BatchOptions): Promise<BatchResult>;
     fetchAsync(transaction: Transaction, count: number | 'all'): Promise<any>;
     fetchScrollAsync(transaction: Transaction, direction: 'NEXT' | 'PRIOR' | 'FIRST' | 'LAST' | 'ABSOLUTE' | 'RELATIVE' | number, offset?: number, count?: number): Promise<any>;
     fetchAllAsync(transaction: Transaction): Promise<any>;
@@ -266,6 +279,16 @@ export interface Options {
     blobReadChunkSize?: number;
     wireCrypt?: number; // WIRE_CRYPT_DISABLE or WIRE_CRYPT_ENABLE
     wireCompression?: boolean;
+    /**
+     * Enable named placeholders: SQL may use `:name` markers and params may
+     * be a values-by-name object (`db.query('... WHERE id = :id', { id: 1 })`).
+     * Placeholders are rewritten client-side to positional `?` before
+     * preparing; positional arrays keep working unchanged. Off by default
+     * because `EXECUTE BLOCK` bodies use `:variable` for PSQL references —
+     * with this option on, run such statements with positional params or a
+     * per-query `namedPlaceholders: false` override.
+     */
+    namedPlaceholders?: boolean;
     pluginName?: string;
     parallelWorkers?: number;
     maxInlineBlobSize?: number;

package/src/uri.ts

@@ -0,0 +1,204 @@
+/***************************************
+ *
+ *   Connection URI strings
+ *
+ ***************************************/
+
+import type { Options } from './types';
+
+/**
+ * Option keys coerced to boolean when they arrive as URI query parameters.
+ * "1"/"true"/"yes"/"on" (case-insensitive) → true, everything else → false.
+ */
+const BOOLEAN_KEYS = new Set([
+    'lowercase_keys', 'blobAsText', 'wireCompression', 'manager',
+    'namedPlaceholders',
+]);
+
+/** Option keys coerced to number when they arrive as URI query parameters. */
+const NUMBER_KEYS = new Set([
+    'port', 'pageSize', 'timeout', 'retryConnectionInterval',
+    'blobChunkSize', 'blobReadChunkSize', 'wireCrypt', 'parallelWorkers',
+    'maxInlineBlobSize', 'maxNegotiatedProtocols', 'connectTimeout',
+    'min', 'idleTimeoutMillis',
+]);
+
+function coerce(key: string, value: string): any {
+    if (BOOLEAN_KEYS.has(key)) {
+        return /^(1|true|yes|on)$/i.test(value);
+    }
+    if (NUMBER_KEYS.has(key)) {
+        var n = Number(value);
+        if (Number.isNaN(n)) {
+            throw new Error('Invalid numeric value for connection URI option "' + key + '": ' + value);
+        }
+        return n;
+    }
+    return value;
+}
+
+/**
+ * Parse a firebird:// connection URI into an options object.
+ *
+ *   firebird://user:password@host:port/database?option=value&...
+ *
+ * The database part:
+ *   firebird://host/employee              → alias "employee"
+ *   firebird://host//var/db/prod.fdb      → absolute path "/var/db/prod.fdb"
+ *   firebird://host/var/db/prod.fdb       → "/var/db/prod.fdb" (a database
+ *                                           part with slashes is a path —
+ *                                           aliases cannot contain "/")
+ *   firebird://host/C:/db/prod.fdb        → Windows path "C:/db/prod.fdb"
+ *
+ * Credentials and the database path are URL-decoded, so reserved characters
+ * can be percent-encoded (e.g. p%40ss for "p@ss"). Query parameters map
+ * 1:1 to option keys and are coerced to the option's type (booleans accept
+ * 1/true/yes/on). `user` and `password` may be given as query parameters
+ * instead of in the authority.
+ */
+export function parseConnectionUri(uri: string): Options {
+    var url: URL;
+    try {
+        url = new URL(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 options: any = {};
+
+    if (url.hostname) {
+        // URL keeps IPv6 hostnames bracketed ([::1]); net.connect wants them bare
+        options.host = url.hostname.replace(/^\[(.*)\]$/, '$1');
+    }
+    if (url.port) {
+        options.port = Number(url.port);
+    }
+    if (url.username) {
+        options.user = decodeURIComponent(url.username);
+    }
+    if (url.password) {
+        options.password = decodeURIComponent(url.password);
+    }
+
+    var database = decodeURIComponent(url.pathname || '');
+    if (database.startsWith('/')) {
+        database = database.slice(1);
+    }
+    // A database part with path separators is a filesystem path, not an
+    // alias (aliases cannot contain "/") — restore the leading slash unless
+    // it is a Windows drive path or already absolute (double-slash form).
+    if (database.includes('/') && !database.startsWith('/') && !/^[A-Za-z]:\//.test(database)) {
+        database = '/' + database;
+    }
+    if (database) {
+        options.database = database;
+    }
+
+    url.searchParams.forEach(function(value, key) {
+        options[key] = coerce(key, value);
+    });
+
+    return options as Options;
+}
+
+/**
+ * Parse a traditional ("old style") Firebird connection string:
+ *
+ *   [host[/port]:]{path | alias}
+ *
+ *   employee                              → alias "employee" (default host)
+ *   /var/fb/prod.fdb                      → local path (default host)
+ *   C:\fbdata\prod.fdb                    → Windows path — a single character
+ *                                           before ":" is a drive letter, not
+ *                                           a host (same rule as Firebird)
+ *   db.example.com:employee               → host + alias
+ *   db.example.com/3051:/var/fb/prod.fdb  → host + port + path
+ *   myserver:C:\fbdata\prod.fdb           → host + Windows path
+ *   [::1]/3050:employee                   → IPv6 host + port + alias
+ *
+ * Unlike firebird:// URIs, traditional strings carry no credentials or
+ * options — the driver defaults apply (SYSDBA/masterkey, port 3050).
+ * The port must be numeric; /etc/services names are not resolved.
+ */
+export function parseOldStyleConnectionString(str: string): Options {
+    var options: any = {};
+    var host: string | null = null;
+    var port: string | null = null;
+    var database = str;
+
+    var ipv6 = /^\[([^\]]+)\](?:\/([^:]*))?:(.*)$/.exec(str);
+    if (ipv6) {
+        host = ipv6[1];
+        port = ipv6[2] !== undefined ? ipv6[2] : null;
+        database = ipv6[3];
+    } else {
+        var colon = str.indexOf(':');
+        if (colon === 0) {
+            throw new Error('Invalid connection string (empty host): ' + str);
+        }
+        // colon === 1 → single character before ":" is a drive letter;
+        // colon === -1 → no host part. Both leave the whole string as database.
+        if (colon > 1) {
+            var hostPart = str.slice(0, colon);
+            database = str.slice(colon + 1);
+            var slash = hostPart.indexOf('/');
+            if (slash !== -1) {
+                host = hostPart.slice(0, slash);
+                port = hostPart.slice(slash + 1);
+                if (!host) {
+                    throw new Error('Invalid connection string (empty host): ' + str);
+                }
+            } else {
+                host = hostPart;
+            }
+        }
+    }
+
+    if (!database) {
+        throw new Error('Invalid connection string (empty database): ' + str);
+    }
+
+    if (host) {
+        options.host = host;
+    }
+    if (port !== null) {
+        var n = Number(port);
+        if (!/^\d+$/.test(port) || n < 1 || n > 65535) {
+            throw new Error('Invalid port in connection string "' + str +
+                '" (service names are not supported — use a numeric port)');
+        }
+        options.port = n;
+    }
+    options.database = database;
+
+    return options as 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.
+ */
+export function parseConnectionString(str: string): Options {
+    return URI_SCHEME.test(str)
+        ? parseConnectionUri(str)
+        : parseOldStyleConnectionString(str);
+}
+
+/**
+ * Accept either an options object or a connection string (firebird:// 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 {
+    if (typeof options === 'string') {
+        return parseConnectionString(options) as T;
+    }
+    return options;
+}

package/src/wire/connection.ts

@@ -90,6 +90,12 @@ class Connection {
         this._isDetach = false;
         this._isUsed = false;
         this._pooled = options.isPool||false;
+        // Credentials may be absent (e.g. a traditional host:database
+        // connection string) — apply the driver defaults once here, so every
+        // auth path (op_connect CNCT block, SRP proof, legacy cont_auth) sees
+        // the same values.
+        if (options && !options.user) options.user = Const.DEFAULT_USER;
+        if (options && !options.password) options.password = Const.DEFAULT_PASSWORD;
         if (options && options.blobChunkSize > 65535) options.blobChunkSize = 65535;
         if (options && options.blobReadChunkSize > 65535) options.blobReadChunkSize = 65535;
         this.options = options;
@@ -426,8 +432,17 @@ class Connection {
         const canDefer = defer && this.accept.protocolVersion >= Const.PROTOCOL_VERSION11;
     
         self._socket.write(self._msg.getData(), canDefer);
-        if (canDefer && callback) {
-            callback();
+        if (canDefer) {
+            // A deferred packet sits in the socket buffer until the next
+            // non-deferred write flushes it, but the server still answers it
+            // with its own op_response (delivered along with that next
+            // exchange). Queue a placeholder to consume that response —
+            // otherwise the queue pairs it with the NEXT request and every
+            // later response is off by one. The op itself is fire-and-forget,
+            // so complete the caller right away.
+            self._queue.push(undefined);
+            if (callback)
+                callback();
         } else {
             self._queue.push(callback);
         }

package/src/wire/statement.ts

@@ -4,7 +4,8 @@
  *
  ***************************************/
 
-import { fromCallback } from '../callback';
+import { doError, fromCallback } from '../callback';
+import { bindNamedParams, isNamedParamsObject } from '../named-params';
 
 class Statement {
     connection: any;
@@ -15,6 +16,12 @@ class Statement {
     options: any;
     handle: number;
     plan: string;
+    /**
+     * Placeholder names in positional order when this statement was
+     * prepared from SQL with named placeholders (namedPlaceholders on),
+     * null/undefined otherwise. Set by Transaction.newStatement.
+     */
+    namedParams?: string[] | null;
     [key: string]: any;
 
     constructor(connection: any) {
@@ -44,6 +51,15 @@ class Statement {
             params = undefined;
         }
 
+        if (this.namedParams && isNamedParamsObject(params)) {
+            try {
+                params = bindNamedParams(this.namedParams, params);
+            } catch (err) {
+                doError(err, callback);
+                return;
+            }
+        }
+
         this.options = options;
         this.connection.executeStatement(transaction, this, params, callback, options);
     }
@@ -71,9 +87,22 @@ class Statement {
 
     /**
      * Execute this statement once per row via the Firebird 4 batch API
-     * (protocol 16+). `rows` is an array of parameter arrays.
+     * (protocol 16+). `rows` is an array of parameter arrays — or, when the
+     * statement was prepared with named placeholders, of values-by-name
+     * objects (the two forms can be mixed).
      */
     executeBatch(transaction: any, rows: any[][], callback?: any, options?: any): void {
+        var names = this.namedParams;
+        if (names && Array.isArray(rows)) {
+            try {
+                rows = rows.map(function(row: any) {
+                    return isNamedParamsObject(row) ? bindNamedParams(names as string[], row) : row;
+                });
+            } catch (err) {
+                doError(err, callback);
+                return;
+            }
+        }
         this.connection.executeBatch(transaction, this, rows, callback, options);
     }
 

package/src/wire/transaction.ts

@@ -1,4 +1,5 @@
 import { doCallback, doError, fromCallback } from '../callback';
+import { parseNamedPlaceholders } from '../named-params';
 import { noop } from '../utils';
 import Const from './const';
 
@@ -51,15 +52,41 @@ class Transaction {
         this.db = connection.db;
     }
 
-    newStatement(query: string, callback: (err: any, statement?: any) => void): void {
+    /** Per-call options.namedPlaceholders overrides the connection option. */
+    private namedPlaceholdersEnabled(options?: any): boolean {
+        if (options && options.namedPlaceholders !== undefined)
+            return !!options.namedPlaceholders;
+        return !!(this.connection.options && this.connection.options.namedPlaceholders);
+    }
+
+    newStatement(query: string, callback: (err: any, statement?: any) => void, options?: any): void {
         var cnx = this.connection;
         var self = this;
+
+        // With namedPlaceholders on, prepare the positional rewrite and
+        // remember the name order on the statement so statement.execute can
+        // accept a values-by-name object. The rewritten SQL is the cache key.
+        var names: string[] | null = null;
+        if (this.namedPlaceholdersEnabled(options)) {
+            var parsed = parseNamedPlaceholders(query);
+            if (parsed.names) {
+                query = parsed.sql;
+                names = parsed.names;
+            }
+        }
+
+        var deliver = function(err: any, statement?: any) {
+            if (statement)
+                statement.namedParams = names;
+            callback(err, statement);
+        };
+
         var query_cache = cnx.getCachedQuery(query);
 
         if (query_cache) {
-            callback(null, query_cache);
+            deliver(null, query_cache);
         } else {
-            cnx.prepare(self, query, false, callback);
+            cnx.prepare(self, query, false, deliver);
         }
     }
 
@@ -148,7 +175,7 @@ class Transaction {
                 }
 
             }, options);
-        });
+        }, options);
     }
 
     sequentially(query: string, params?: any, on?: any, callback?: any, options: any = {}): this {
@@ -255,7 +282,7 @@ class Transaction {
                 if (callback)
                     callback(err, result);
             }, options);
-        });
+        }, options);
     }
 
     executeBatchAsync(query: string, rows: any[][], options?: any): Promise<any> {