node-firebird 2.8.1 → 2.10.0

package/src/index.ts

@@ -1,8 +1,9 @@
 import Const from './wire/const';
-import { doError, doCallback, fromCallback } from './callback';
+import { doError, doCallback, fromCallback, type Callback } 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,
@@ -47,6 +48,36 @@ export const ISOLATION_READ_COMMITTED_READ_ONLY: number[] = Const.ISOLATION_READ
 
 export const escape = escapeValue;
 
+/**
+ * Firebird SQL type codes, as seen in `column.type` inside a `typeCast`
+ * hook (each code also has a friendly `column.typeName`).
+ */
+export const SQL_TYPES: Readonly<Record<string, number>> = Object.freeze({
+    SQL_TEXT: Const.SQL_TEXT,
+    SQL_VARYING: Const.SQL_VARYING,
+    SQL_SHORT: Const.SQL_SHORT,
+    SQL_LONG: Const.SQL_LONG,
+    SQL_FLOAT: Const.SQL_FLOAT,
+    SQL_DOUBLE: Const.SQL_DOUBLE,
+    SQL_D_FLOAT: Const.SQL_D_FLOAT,
+    SQL_TIMESTAMP: Const.SQL_TIMESTAMP,
+    SQL_BLOB: Const.SQL_BLOB,
+    SQL_ARRAY: Const.SQL_ARRAY,
+    SQL_QUAD: Const.SQL_QUAD,
+    SQL_TYPE_TIME: Const.SQL_TYPE_TIME,
+    SQL_TYPE_DATE: Const.SQL_TYPE_DATE,
+    SQL_INT64: Const.SQL_INT64,
+    SQL_INT128: Const.SQL_INT128,
+    SQL_TIMESTAMP_TZ: Const.SQL_TIMESTAMP_TZ,
+    SQL_TIMESTAMP_TZ_EX: Const.SQL_TIMESTAMP_TZ_EX,
+    SQL_TIME_TZ: Const.SQL_TIME_TZ,
+    SQL_TIME_TZ_EX: Const.SQL_TIME_TZ_EX,
+    SQL_DEC16: Const.SQL_DEC16,
+    SQL_DEC34: Const.SQL_DEC34,
+    SQL_BOOLEAN: Const.SQL_BOOLEAN,
+    SQL_NULL: Const.SQL_NULL,
+});
+
 /**
  * The most recent Connection created by attach()/create()/attachOrCreate().
  * Kept for backwards compatibility with the previous CommonJS module where
@@ -54,9 +85,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 +113,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 +124,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) {
@@ -111,12 +144,13 @@ export function create(options: Options, callback: DatabaseCallback): void {
                 return;
             }
 
-            cnx.createDatabase(options, callback);
+            cnx.createDatabase(options, callback as any);
         });
     }, 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;
@@ -142,11 +176,13 @@ export function attachOrCreate(options: Options, callback: DatabaseCallback): vo
                 if (!err) {
                     if (self.db)
                         self.db.emit('connect', ret);
-                    doCallback(ret, callback);
+                    // DatabaseCallback stays permissive (db non-optional) for
+                    // API users; internally the error path passes no db
+                    doCallback(ret, callback as Callback<Database>);
                     return;
                 }
 
-                cnx.createDatabase(options, callback);
+                cnx.createDatabase(options, callback as any);
             });
         });
 
@@ -154,10 +190,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 +205,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/messages.ts

@@ -138,7 +138,7 @@ export const lookupMessages = function(status: FbStatusItem[], messageFile: stri
             buffer = Buffer.alloc(bucket_size);
 
             var i = 0;
-            var text;
+            var text: string | undefined;
 
             function loop() {
                 lookup(status[i], function(line) {

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;
+}

package/src/pool.ts

@@ -161,7 +161,7 @@ class Pool extends Events.EventEmitter {
         if ((self.dbinuse + self._creating) >= self.max)
             return self;
 
-        var cb = self.pending.shift();
+        const cb = self.pending.shift();
         if (!cb)
             return self;
         if (self.pooldb.length) {

package/src/srp.ts

@@ -67,7 +67,7 @@ export function clientSeed(a: bigint = toBigInt(crypto.randomBytes(SRP_KEY_SIZE)
  * @param b BigInt Server private key.
  * @returns {{private: BigInt, public: BigInt}}
  */
-export function serverSeed(user: string, password: string, salt: Buffer, b?: bigint | string, hashAlgo: string = 'sha1'): KeyPair {
+export function serverSeed(user: string, password: string, salt: Buffer | string, b?: bigint | string, hashAlgo: string = 'sha1'): KeyPair {
     if (typeof b === 'string') {
         hashAlgo = b;
         b = undefined;
@@ -104,7 +104,7 @@ export function serverSeed(user: string, password: string, salt: Buffer, b?: big
  * @param b BigInt Server private key.
  * @returns {BigInt}
  */
-export function serverSession(user: string, password: string, salt: Buffer, A: bigint, B: bigint, b: bigint, hashAlgo: string = 'sha1'): bigint {
+export function serverSession(user: string, password: string, salt: Buffer | string, A: bigint, B: bigint, b: bigint, hashAlgo: string = 'sha1'): bigint {
     var u = getScramble(A, B, 'sha1');
     var v = getVerifier(user, password, salt, 'sha1');
     var vu = modPow(v, u, PRIME.N);
@@ -121,7 +121,7 @@ export function serverSession(user: string, password: string, salt: Buffer, A: b
 /**
  * M = H(H(N) xor H(g), H(I), s, A, B, K)
  */
-export function clientProof(user: string, password: string, salt: Buffer, A: bigint, B: bigint, a: bigint, hashAlgo: string = 'sha1'): ClientProof {
+export function clientProof(user: string, password: string, salt: Buffer | string, A: bigint, B: bigint, a: bigint, hashAlgo: string = 'sha1'): ClientProof {
     var K = clientSession(user, password, salt, A, B, a, 'sha1');
     var n1, n2;
 
@@ -222,7 +222,7 @@ function getScramble(A: bigint, B: bigint, hashAlgo: string = 'sha1'): bigint {
  * @returns Buffer The raw session-key digest (fixed length, may start
  *                 with a zero byte — significant for the proof).
  */
-function clientSession(user: string, password: string, salt: Buffer, A: bigint, B: bigint, a: bigint, hashAlgo: string = 'sha1'): Buffer {
+function clientSession(user: string, password: string, salt: Buffer | string, A: bigint, B: bigint, a: bigint, hashAlgo: string = 'sha1'): Buffer {
     var u = getScramble(A, B, 'sha1');
     var x = getUserHash(user, salt, password, 'sha1');
     var gx = modPow(PRIME.g, x, PRIME.N);
@@ -264,7 +264,7 @@ function clientSession(user: string, password: string, salt: Buffer, A: bigint,
  * @param password string Connection password.
  * @returns {BigInt}
  */
-function getUserHash(user: string, salt: Buffer, password: string, hashAlgo: string = 'sha1'): bigint {
+function getUserHash(user: string, salt: Buffer | string, password: string, hashAlgo: string = 'sha1'): bigint {
     var hash1 = getHash(hashAlgo, user.toUpperCase(), ':', password);
     var hash2 = getHash(hashAlgo, salt, toBuffer(hash1));
 
@@ -279,7 +279,7 @@ function getUserHash(user: string, salt: Buffer, password: string, hashAlgo: str
  * @param salt  BigInt Connection salt.
  * @returns {BigInt}
  */
-function getVerifier(user: string, password: string, salt: Buffer, hashAlgo: string = 'sha1'): bigint {
+function getVerifier(user: string, password: string, salt: Buffer | string, hashAlgo: string = 'sha1'): bigint {
     return modPow(PRIME.g, getUserHash(user, salt, password, hashAlgo), PRIME.N);
 }