node-firebird 2.8.0 → 2.9.0

package/lib/uri.js

@@ -0,0 +1,193 @@
+"use strict";
+/***************************************
+ *
+ *   Connection URI strings
+ *
+ ***************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseConnectionUri = parseConnectionUri;
+exports.parseOldStyleConnectionString = parseOldStyleConnectionString;
+exports.parseConnectionString = parseConnectionString;
+exports.normalizeOptions = normalizeOptions;
+/**
+ * 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, value) {
+    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.
+ */
+function parseConnectionUri(uri) {
+    var 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 = {};
+    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;
+}
+/**
+ * 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.
+ */
+function parseOldStyleConnectionString(str) {
+    var options = {};
+    var host = null;
+    var port = 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;
+}
+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.
+ */
+function parseConnectionString(str) {
+    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.
+ */
+function normalizeOptions(options) {
+    if (typeof options === 'string') {
+        return parseConnectionString(options);
+    }
+    return options;
+}

package/lib/wire/connection.js

@@ -84,6 +84,14 @@ 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_1.default.DEFAULT_USER;
+        if (options && !options.password)
+            options.password = const_1.default.DEFAULT_PASSWORD;
         if (options && options.blobChunkSize > 65535)
             options.blobChunkSize = 65535;
         if (options && options.blobReadChunkSize > 65535)
@@ -339,8 +347,17 @@ class Connection {
         }
         const canDefer = defer && this.accept.protocolVersion >= const_1.default.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/lib/wire/statement.d.ts

@@ -12,6 +12,12 @@ declare 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);
     close(callback?: (err?: any) => void): void;
@@ -23,7 +29,9 @@ declare class Statement {
     fetchAll(transaction: any, callback: (err: any, result?: any) => void): void;
     /**
      * 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;
     executeAsync(transaction: any, params?: any, options?: any): Promise<any>;

package/lib/wire/statement.js

@@ -5,6 +5,7 @@
  *
  ***************************************/
 const callback_1 = require("../callback");
+const named_params_1 = require("../named-params");
 class Statement {
     constructor(connection) {
         this.connection = connection;
@@ -28,6 +29,15 @@ class Statement {
             callback = params;
             params = undefined;
         }
+        if (this.namedParams && (0, named_params_1.isNamedParamsObject)(params)) {
+            try {
+                params = (0, named_params_1.bindNamedParams)(this.namedParams, params);
+            }
+            catch (err) {
+                (0, callback_1.doError)(err, callback);
+                return;
+            }
+        }
         this.options = options;
         this.connection.executeStatement(transaction, this, params, callback, options);
     }
@@ -51,9 +61,23 @@ 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, rows, callback, options) {
+        var names = this.namedParams;
+        if (names && Array.isArray(rows)) {
+            try {
+                rows = rows.map(function (row) {
+                    return (0, named_params_1.isNamedParamsObject)(row) ? (0, named_params_1.bindNamedParams)(names, row) : row;
+                });
+            }
+            catch (err) {
+                (0, callback_1.doError)(err, callback);
+                return;
+            }
+        }
         this.connection.executeBatch(transaction, this, rows, callback, options);
     }
     /* Promise / async-await API — wrappers over the callback methods above. */

package/lib/wire/transaction.d.ts

@@ -4,7 +4,9 @@ declare class Transaction {
     handle: number;
     [key: string]: any;
     constructor(connection: any);
-    newStatement(query: string, callback: (err: any, statement?: any) => void): void;
+    /** Per-call options.namedPlaceholders overrides the connection option. */
+    private namedPlaceholdersEnabled;
+    newStatement(query: string, callback: (err: any, statement?: any) => void, options?: any): void;
     execute(query: string, params?: any, callback?: any, options?: any): void;
     sequentially(query: string, params?: any, on?: any, callback?: any, options?: any): this;
     query(query: string, params?: any, callback?: any, options?: any): void;

package/lib/wire/transaction.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 const callback_1 = require("../callback");
+const named_params_1 = require("../named-params");
 const utils_1 = require("../utils");
 const const_1 = __importDefault(require("./const"));
 /***************************************
@@ -45,15 +46,37 @@ class Transaction {
         this.connection = connection;
         this.db = connection.db;
     }
-    newStatement(query, callback) {
+    /** Per-call options.namedPlaceholders overrides the connection option. */
+    namedPlaceholdersEnabled(options) {
+        if (options && options.namedPlaceholders !== undefined)
+            return !!options.namedPlaceholders;
+        return !!(this.connection.options && this.connection.options.namedPlaceholders);
+    }
+    newStatement(query, callback, options) {
         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 = null;
+        if (this.namedPlaceholdersEnabled(options)) {
+            var parsed = (0, named_params_1.parseNamedPlaceholders)(query);
+            if (parsed.names) {
+                query = parsed.sql;
+                names = parsed.names;
+            }
+        }
+        var deliver = function (err, statement) {
+            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);
         }
     }
     execute(query, params, callback, options) {
@@ -124,7 +147,7 @@ class Transaction {
                         break;
                 }
             }, options);
-        });
+        }, options);
     }
     sequentially(query, params, on, callback, options = {}) {
         if (params instanceof Function) {
@@ -221,7 +244,7 @@ class Transaction {
                 if (callback)
                     callback(err, result);
             }, options);
-        });
+        }, options);
     }
     executeBatchAsync(query, rows, options) {
         var self = this;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "node-firebird",
-    "version": "2.8.0",
+    "version": "2.9.0",
     "description": "Pure JavaScript and Asynchronous Firebird client for Node.js.",
     "keywords": [
         "firebird",

package/src/index.ts

@@ -3,6 +3,7 @@ import { doError, doCallback, fromCallback } from './callback';
 import Connection from './wire/connection';
 import Pool from './pool';
 import { escape as escapeValue } from './utils';
+import { parseConnectionUri, parseConnectionString, normalizeOptions } from './uri';
 import type {
     Options,
     SvcMgrOptions,
@@ -54,9 +55,10 @@ export const escape = escapeValue;
  */
 export let connection: Connection | undefined;
 
-export function attach(options: Options, callback: DatabaseCallback): void;
+export function attach(options: Options | string, callback: DatabaseCallback): void;
 export function attach(options: SvcMgrOptions, callback: ServiceManagerCallback): void;
 export function attach(options: any, callback: any): void {
+    options = normalizeOptions(options);
     var host = options.host || Const.DEFAULT_HOST;
     var port = options.port || Const.DEFAULT_PORT;
     var manager = options.manager || false;
@@ -81,8 +83,8 @@ export function attach(options: any, callback: any): void {
     }, options);
 }
 
-export function drop(options: Options, callback: SimpleCallback): void {
-	attach(options, function(err: any, db: any) {
+export function drop(options: Options | string, callback: SimpleCallback): void {
+	attach(normalizeOptions(options), function(err: any, db: any) {
 		if (err) {
 			callback({ error: err, message: "Drop error" });
 			return;
@@ -92,7 +94,8 @@ export function drop(options: Options, callback: SimpleCallback): void {
 	});
 }
 
-export function create(options: Options, callback: DatabaseCallback): void {
+export function create(options: Options | string, callback: DatabaseCallback): void {
+    options = normalizeOptions(options);
     var host = options.host || Const.DEFAULT_HOST;
     var port = options.port || Const.DEFAULT_PORT;
     var cnx = connection = new Connection(host, port, function(err: any) {
@@ -116,7 +119,8 @@ export function create(options: Options, callback: DatabaseCallback): void {
     }, options);
 }
 
-export function attachOrCreate(options: Options, callback: DatabaseCallback): void {
+export function attachOrCreate(options: Options | string, callback: DatabaseCallback): void {
+    options = normalizeOptions(options);
 
     var host = options.host || Const.DEFAULT_HOST;
     var port = options.port || Const.DEFAULT_PORT;
@@ -154,10 +158,13 @@ export function attachOrCreate(options: Options, callback: DatabaseCallback): vo
 }
 
 // Pooling
-export function pool(max: number, options: Options): ConnectionPool {
-	return new Pool(attach, max, Object.assign({}, options, { isPool: true }));
+export function pool(max: number, options: Options | string): ConnectionPool {
+	return new Pool(attach, max, Object.assign({}, normalizeOptions(options), { isPool: true }));
 }
 
+export { parseConnectionUri, parseConnectionString };
+export { parseNamedPlaceholders } from './named-params';
+
 /*
  * Promise / async-await API.
  * Wrappers over the callback functions above; the callback API stays
@@ -166,19 +173,19 @@ export function pool(max: number, options: Options): ConnectionPool {
  */
 
 export function attachAsync(options: SvcMgrOptions): Promise<ServiceManager>;
-export function attachAsync(options: Options): Promise<Database>;
+export function attachAsync(options: Options | string): Promise<Database>;
 export function attachAsync(options: any): Promise<any> {
     return fromCallback(function(cb) { attach(options, cb); });
 }
 
-export function createAsync(options: Options): Promise<Database> {
+export function createAsync(options: Options | string): Promise<Database> {
     return fromCallback(function(cb) { create(options, cb); });
 }
 
-export function attachOrCreateAsync(options: Options): Promise<Database> {
+export function attachOrCreateAsync(options: Options | string): Promise<Database> {
     return fromCallback(function(cb) { attachOrCreate(options, cb); });
 }
 
-export function dropAsync(options: Options): Promise<void> {
+export function dropAsync(options: Options | string): Promise<void> {
     return fromCallback(function(cb) { drop(options, cb); });
 }

package/src/named-params.ts

@@ -0,0 +1,145 @@
+/***************************************
+ *
+ *   Named placeholders (:name → ?)
+ *
+ ***************************************/
+
+/**
+ * Result of scanning a SQL string for named placeholders.
+ */
+export interface ParsedNamedPlaceholders {
+    /** SQL with every named placeholder replaced by a positional "?". */
+    sql: string;
+    /**
+     * Placeholder names in positional order (a repeated name appears once
+     * per occurrence), or null when the SQL contains none.
+     */
+    names: string[] | null;
+}
+
+const IDENT_START = /[A-Za-z_]/;
+const IDENT_PART = /[A-Za-z0-9_$]/;
+
+// Parsing is pure string work, so identical SQL (the common case with
+// query builders and hot paths) is scanned only once.
+const CACHE_MAX = 100;
+const cache = new Map<string, ParsedNamedPlaceholders>();
+
+/**
+ * Scan `sql` for named placeholders (`:name`) and rewrite them to positional
+ * `?` markers, returning the rewritten SQL and the names in positional
+ * order. Placeholders inside string literals ('...'), quoted identifiers
+ * ("..."), line comments (--), block comments and Firebird alternative
+ * string literals (q'{...}') are left untouched.
+ *
+ * Note: the scanner has no SQL grammar — inside an EXECUTE BLOCK body every
+ * `:variable` reference looks like a placeholder too. Use positional params
+ * (or per-call `namedPlaceholders: false`) for EXECUTE BLOCK.
+ */
+export function parseNamedPlaceholders(sql: string): ParsedNamedPlaceholders {
+    var cached = cache.get(sql);
+    if (cached)
+        return cached;
+
+    var out = '';
+    var names: string[] = [];
+    var i = 0;
+    var n = sql.length;
+
+    while (i < n) {
+        var c = sql[i];
+
+        if (c === "'" || c === '"') {
+            // string literal or quoted identifier; doubled quotes escape
+            var quote = c;
+            var end = i + 1;
+            while (end < n) {
+                if (sql[end] === quote) {
+                    if (sql[end + 1] === quote) {
+                        end += 2;
+                        continue;
+                    }
+                    end++;
+                    break;
+                }
+                end++;
+            }
+            out += sql.slice(i, end);
+            i = end;
+        } else if (c === '-' && sql[i + 1] === '-') {
+            var eol = sql.indexOf('\n', i);
+            if (eol === -1) eol = n;
+            out += sql.slice(i, eol);
+            i = eol;
+        } else if (c === '/' && sql[i + 1] === '*') {
+            var close = sql.indexOf('*/', i + 2);
+            close = close === -1 ? n : close + 2;
+            out += sql.slice(i, close);
+            i = close;
+        } else if ((c === 'q' || c === 'Q') && sql[i + 1] === "'" && i + 2 < n &&
+                   (i === 0 || !IDENT_PART.test(sql[i - 1]))) {
+            // Firebird 3+ alternative string literal: q'{...}' / q'!...!'
+            var open = sql[i + 2];
+            var closer = open === '(' ? ')'
+                       : open === '[' ? ']'
+                       : open === '{' ? '}'
+                       : open === '<' ? '>'
+                       : open;
+            var stop = sql.indexOf(closer + "'", i + 3);
+            stop = stop === -1 ? n : stop + 2;
+            out += sql.slice(i, stop);
+            i = stop;
+        } else if (c === ':' && i + 1 < n && IDENT_START.test(sql[i + 1])) {
+            var end2 = i + 2;
+            while (end2 < n && IDENT_PART.test(sql[end2]))
+                end2++;
+            names.push(sql.slice(i + 1, end2));
+            out += '?';
+            i = end2;
+        } else {
+            out += c;
+            i++;
+        }
+    }
+
+    var result: ParsedNamedPlaceholders = names.length
+        ? { sql: out, names: names }
+        : { sql: sql, names: null };
+
+    if (cache.size >= CACHE_MAX) {
+        cache.delete(cache.keys().next().value as string);
+    }
+    cache.set(sql, result);
+    return result;
+}
+
+/**
+ * True when `params` is a plain values-by-name object (and not one of the
+ * values the driver accepts as a single positional parameter, like Date or
+ * Buffer).
+ */
+export function isNamedParamsObject(params: any): params is Record<string, any> {
+    return params !== null &&
+        typeof params === 'object' &&
+        !Array.isArray(params) &&
+        !Buffer.isBuffer(params) &&
+        !(params instanceof Date);
+}
+
+/**
+ * Map a values-by-name object onto the positional order collected by
+ * parseNamedPlaceholders. A name may be bound multiple times; every name
+ * must be an own property of `params` (a present key holding null is a
+ * NULL parameter, a missing key is an error).
+ */
+export function bindNamedParams(names: string[], params: Record<string, any>): any[] {
+    var missing: string[] = [];
+    var values = names.map(function(name) {
+        if (!Object.prototype.hasOwnProperty.call(params, name))
+            missing.push(name);
+        return params[name];
+    });
+    if (missing.length)
+        throw new Error('Missing value for named placeholder(s): ' + missing.join(', '));
+    return values;
+}