node-firebird 2.12.0 → 2.14.0

package/lib/wire/transaction.js

@@ -9,6 +9,7 @@ const const_1 = __importDefault(require("./const"));
 const sql_template_1 = require("../sql-template");
 const xsqlvar_1 = require("./xsqlvar");
 const query_stream_1 = __importDefault(require("./query-stream"));
+const batch_stream_1 = __importDefault(require("./batch-stream"));
 /***************************************
  *
  *   Transaction
@@ -254,7 +255,17 @@ class Transaction {
                         break;
                     case const_1.default.isc_info_sql_stmt_exec_procedure:
                         if (ret && ret.data && ret.data.length > 0) {
-                            deliver(ret.data[0], true);
+                            // singleton op_execute2 rows never pass through
+                            // fetchAll, so their blobAsText fetches must be
+                            // resolved here (issue #305: EXECUTE PROCEDURE
+                            // returned text blobs as unresolved functions)
+                            self.connection.resolveTextBlobs(self, ret, function (blobErr) {
+                                if (blobErr) {
+                                    dropError(blobErr);
+                                    return;
+                                }
+                                deliver(ret.data[0], true);
+                            });
                             break;
                         }
                         else if (statement.output.length) {
@@ -263,7 +274,13 @@ class Transaction {
                                     dropError(err);
                                     return;
                                 }
-                                deliver(fret.data[0], false);
+                                self.connection.resolveTextBlobs(self, fret, function (blobErr) {
+                                    if (blobErr) {
+                                        dropError(blobErr);
+                                        return;
+                                    }
+                                    deliver(fret.data[0], false);
+                                });
                             });
                             break;
                         }
@@ -344,6 +361,14 @@ class Transaction {
     queryStream(query, params, options) {
         return (0, query_stream_1.default)(this, query, params, options);
     }
+    /**
+     * Bulk-insert Writable running inside this transaction (see
+     * Database.batchStream). The transaction is NOT committed or rolled
+     * back by the stream — settle it yourself after 'finish'/'error'.
+     */
+    batchStream(query, options) {
+        return (0, batch_stream_1.default)(this, query, options, false);
+    }
     query(query, params, callback, options = {}) {
         if (params instanceof Function) {
             callback = params;

package/lib/wire/xsqlvar.d.ts

@@ -1,5 +1,47 @@
+import type { TextCodec } from './codepages';
 import type { XdrReader, XdrWriter, BlrWriter } from './serialize';
 import type { RecordCounts } from '../types';
+export declare function getFirebirdCharsetWidth(charset?: string): number;
+/**
+ * Resolve the Node.js Buffer encoding to use when decoding text from a
+ * Firebird response buffer.
+ *
+ * @param {object|null} options  Connection options object (may be falsy).
+ * @returns {string}             A Node.js-compatible encoding string.
+ */
+export declare function resolveTextEncoding(options?: any): BufferEncoding;
+/**
+ * Codec for the CONNECTION charset when it is a codepage Node cannot
+ * handle natively (WIN1251, ISO8859_7, KOI8R, …); null on the native
+ * path (UTF8/latin1/ascii) and for unknown charsets. With a codec
+ * connection charset the server transliterates all text to that
+ * codepage, so every text column, parameter, SQL string and text blob
+ * goes through the codec (issues #319/#301).
+ */
+export declare function resolveTextCodec(options?: any): TextCodec | null;
+interface TextState {
+    key: string | undefined;
+    codec: TextCodec | null;
+    enc: BufferEncoding;
+    width: number;
+}
+/**
+ * Per-connection text handling, resolved once and memoized on the
+ * long-lived options object: the decode loop calls this per CELL, and
+ * recomputing uppercased names + map lookups a million times per large
+ * fetch is pure waste. Invalidated if options.encoding ever changes.
+ */
+export declare function resolveTextState(options?: any): TextState;
+/**
+ * Encode text in the CONNECTION charset — the byte form the server
+ * expects for parameters, SQL statement text and text-blob content.
+ */
+export declare function encodeConnectionText(options: any, value: string): Buffer;
+/**
+ * Decode connection-charset bytes to text (the read counterpart of
+ * encodeConnectionText — used for text blobs).
+ */
+export declare function decodeConnectionText(options: any, buffer: Buffer): string;
 /**
  * Common shape of all SQLVar descriptor objects.  The metadata properties
  * are populated externally (in connection.ts) from the op_prepare_statement
@@ -19,6 +61,9 @@ export declare abstract class SQLVarBase {
     owner?: string;
     charSetId?: number;
     collationId?: number;
+    /** Original declared byte length when scaleOutputLengths widened
+     *  `length` for the fetch capacity check (issue #422). */
+    nativeLength?: number;
     abstract decode(data: XdrReader, lowerV13: boolean, options?: any): any;
     abstract calcBlr(blr: BlrWriter): void;
 }
@@ -278,7 +323,17 @@ export declare class SQLParamDate {
 }
 export declare class SQLParamBool {
     value: any;
-    constructor(value: any);
+    /**
+     * Encode as a real BOOLEAN (blr_bool + xdr opaque byte) instead of the
+     * legacy blr_short 0/1. Set when the DESCRIBED parameter type is
+     * SQL_BOOLEAN: Firebird refuses smallint→BOOLEAN conversion
+     * ("conversion error from string", issue #122), and conversely BOOLEAN
+     * does not convert to numbers — so smallint targets keep the legacy
+     * form for compatibility.
+     */
+    asBoolean: boolean;
+    constructor(value: any, asBoolean?: boolean);
     encode(data: XdrWriter): void;
     calcBlr(blr: BlrWriter): void;
 }
+export {};

package/lib/wire/xsqlvar.js

@@ -4,6 +4,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SQLParamBool = exports.SQLParamDate = exports.SQLParamQuad = exports.SQLParamBuffer = exports.SQLParamString = exports.SQLParamDouble = exports.SQLParamDecFloat34 = exports.SQLParamDecFloat16 = exports.SQLParamInt128 = exports.SQLParamInt64 = exports.SQLParamInt = exports.SQLVarBoolean = exports.SQLVarTimeStampTzEx = exports.SQLVarTimeStampTz = exports.SQLVarTimeTzEx = exports.SQLVarTimeTz = exports.SQLVarTimeStamp = exports.SQLVarTime = exports.SQLVarDate = exports.SQLVarDouble = exports.SQLVarFloat = exports.SQLVarDecFloat34 = exports.SQLVarDecFloat16 = exports.SQLVarInt128 = exports.SQLVarInt64 = exports.SQLVarShort = exports.SQLVarInt = exports.SQLVarArray = exports.SQLVarBlob = exports.SQLVarQuad = exports.SQLVarString = exports.SQLVarNull = exports.SQLVarText = exports.SQL_TYPE_NAMES = exports.SQLVarBase = void 0;
+exports.getFirebirdCharsetWidth = getFirebirdCharsetWidth;
+exports.resolveTextEncoding = resolveTextEncoding;
+exports.resolveTextCodec = resolveTextCodec;
+exports.resolveTextState = resolveTextState;
+exports.encodeConnectionText = encodeConnectionText;
+exports.decodeConnectionText = decodeConnectionText;
 exports.computeColumnKeys = computeColumnKeys;
 exports.camelizeKey = camelizeKey;
 exports.resolveKeyTransform = resolveKeyTransform;
@@ -15,6 +21,7 @@ exports.parseRecordCounts = parseRecordCounts;
 exports.encodeDateTimeParts = encodeDateTimeParts;
 const const_1 = __importDefault(require("./const"));
 const serialize_1 = require("./serialize");
+const codepages_1 = require("./codepages");
 /***************************************
  *
  *   SQLVar
@@ -22,6 +29,7 @@ const serialize_1 = require("./serialize");
  ***************************************/
 const ScaleDivisor = [1, 10, 100, 1000, 10000, 100000, 1000000, 10000000, 100000000, 1000000000, 10000000000, 100000000000, 1000000000000, 10000000000000, 100000000000000, 1000000000000000];
 const DateOffset = 40587, TimeCoeff = 86400000, MsPerMinute = 60000;
+const EMPTY_BUFFER = Buffer.alloc(0);
 /**
  * Maps Firebird character-set names (upper-case) to the Node.js Buffer
  * encoding string used by Buffer.toString() / Buffer.from().
@@ -46,8 +54,16 @@ const FirebirdToNodeEncoding = Object.freeze({
 const FirebirdCharsetWidths = {
     'UTF8': 4,
     'UNICODE_FSS': 3,
-    'SJIS': 2,
-    'EUCJ': 2
+    // real Firebird names — the bare 'SJIS'/'EUCJ' keys never matched a
+    // valid encoding option and silently resolved to width 1
+    'SJIS_0208': 2,
+    'EUCJ_0208': 2,
+    'KSC_5601': 2,
+    'BIG_5': 2,
+    'GB_2312': 2,
+    'GBK': 2,
+    'CP943C': 2,
+    'GB18030': 4,
 };
 function getFirebirdCharsetWidth(charset) {
     if (!charset)
@@ -68,6 +84,67 @@ function resolveTextEncoding(options) {
         : const_1.default.DEFAULT_ENCODING;
     return (FirebirdToNodeEncoding[encoding] || const_1.default.DEFAULT_ENCODING.toLowerCase());
 }
+/**
+ * Codec for the CONNECTION charset when it is a codepage Node cannot
+ * handle natively (WIN1251, ISO8859_7, KOI8R, …); null on the native
+ * path (UTF8/latin1/ascii) and for unknown charsets. With a codec
+ * connection charset the server transliterates all text to that
+ * codepage, so every text column, parameter, SQL string and text blob
+ * goes through the codec (issues #319/#301).
+ */
+function resolveTextCodec(options) {
+    return resolveTextState(options).codec;
+}
+/**
+ * Per-connection text handling, resolved once and memoized on the
+ * long-lived options object: the decode loop calls this per CELL, and
+ * recomputing uppercased names + map lookups a million times per large
+ * fetch is pure waste. Invalidated if options.encoding ever changes.
+ */
+function resolveTextState(options) {
+    const key = options && options.encoding;
+    if (options && options.__textState && options.__textState.key === key) {
+        return options.__textState;
+    }
+    const encoding = (key || const_1.default.DEFAULT_ENCODING).toUpperCase();
+    const state = {
+        key,
+        codec: FirebirdToNodeEncoding[encoding] ? null : (0, codepages_1.getCodec)(encoding),
+        enc: (FirebirdToNodeEncoding[encoding] || const_1.default.DEFAULT_ENCODING.toLowerCase()),
+        width: getFirebirdCharsetWidth(encoding),
+    };
+    if (options) {
+        options.__textState = state;
+    }
+    return state;
+}
+/**
+ * Encode text in the CONNECTION charset — the byte form the server
+ * expects for parameters, SQL statement text and text-blob content.
+ */
+function encodeConnectionText(options, value) {
+    const state = resolveTextState(options);
+    if (state.codec) {
+        return state.codec.encode(value);
+    }
+    if (state.enc === 'ascii') {
+        // Node's 'ascii' encoding masks high bits (0xE4 → 'd') — replace
+        // non-ASCII with '?' instead, matching the codec policy
+        value = value.replace(/[^\x00-\x7F]/g, '?');
+    }
+    return Buffer.from(value, state.enc);
+}
+/**
+ * Decode connection-charset bytes to text (the read counterpart of
+ * encodeConnectionText — used for text blobs).
+ */
+function decodeConnectionText(options, buffer) {
+    const codec = resolveTextCodec(options);
+    if (codec) {
+        return codec.decode(buffer);
+    }
+    return buffer.toString(resolveTextEncoding(options));
+}
 //------------------------------------------------------
 /**
  * Common shape of all SQLVar descriptor objects.  The metadata properties
@@ -222,7 +299,9 @@ function describeField(meta) {
         typeName: exports.SQL_TYPE_NAMES[meta.type] || 'UNKNOWN',
         subType: meta.subType,
         scale: meta.scale,
-        length: meta.length,
+        // report the column's true declared length, not the widened fetch
+        // buffer (see scaleOutputLengths)
+        length: meta.nativeLength !== undefined ? meta.nativeLength : meta.length,
         nullable: meta.nullable,
         field: meta.field,
         relation: meta.relation,
@@ -290,23 +369,12 @@ function parseRecordCounts(buffer) {
 class SQLVarText extends SQLVarBase {
     decode(data, lowerV13, options) {
         let ret;
-        const textEncoding = resolveTextEncoding(options);
-        if (this.subType > 1) {
-            // ToDo: with column charset
-            ret = data.readText(this.length, textEncoding);
-            const encoding = options && options.encoding ? options.encoding : 'UTF8';
-            const width = getFirebirdCharsetWidth(encoding);
-            const charLength = Math.floor(this.length / width);
-            if (ret.length > charLength) {
-                ret = ret.substring(0, charLength);
-            }
-        }
-        else if (this.subType === 0) {
-            // without charset definition
-            ret = data.readText(this.length, textEncoding);
-            const encoding = options && options.encoding ? options.encoding : 'UTF8';
-            const width = getFirebirdCharsetWidth(encoding);
-            const charLength = Math.floor(this.length / width);
+        if (this.subType > 1 || this.subType === 0) {
+            const state = resolveTextState(options);
+            ret = state.codec
+                ? state.codec.decode(data.readBuffer(this.length) || EMPTY_BUFFER)
+                : data.readText(this.length, state.enc);
+            const charLength = Math.floor(this.length / state.width);
             if (ret.length > charLength) {
                 ret = ret.substring(0, charLength);
             }
@@ -333,14 +401,11 @@ exports.SQLVarNull = SQLVarNull;
 class SQLVarString extends SQLVarBase {
     decode(data, lowerV13, options) {
         let ret;
-        const textEncoding = resolveTextEncoding(options);
-        if (this.subType > 1) {
-            // ToDo: with column charset
-            ret = data.readString(textEncoding);
-        }
-        else if (this.subType === 0) {
-            // without charset definition
-            ret = data.readString(textEncoding);
+        if (this.subType > 1 || this.subType === 0) {
+            const state = resolveTextState(options);
+            ret = state.codec
+                ? state.codec.decode(data.readArray() || EMPTY_BUFFER)
+                : data.readString(state.enc);
         }
         else {
             ret = data.readBuffer();
@@ -875,10 +940,19 @@ class SQLParamDate {
 exports.SQLParamDate = SQLParamDate;
 //------------------------------------------------------
 class SQLParamBool {
-    constructor(value) {
+    constructor(value, asBoolean = false) {
         this.value = value;
+        this.asBoolean = asBoolean;
     }
     encode(data) {
+        if (this.asBoolean) {
+            // xdr_datum sends booleans as 1 opaque value byte + 3 pad bytes
+            // (NOT a big-endian int: the value byte comes FIRST — addInt(1)
+            // would decode server-side as false). Matches the batch encoder.
+            data.addBuffer(Buffer.from([this.value ? 1 : 0]));
+            data.addAlignment(1);
+            return;
+        }
         if (this.value != null) {
             data.addInt(this.value ? 1 : 0);
         }
@@ -888,6 +962,10 @@ class SQLParamBool {
         }
     }
     calcBlr(blr) {
+        if (this.asBoolean) {
+            blr.addByte(const_1.default.blr_bool);
+            return;
+        }
         blr.addByte(const_1.default.blr_short);
         blr.addShort(0);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "node-firebird",
-    "version": "2.12.0",
+    "version": "2.14.0",
     "description": "Pure JavaScript and Asynchronous Firebird client for Node.js.",
     "keywords": [
         "firebird",
@@ -23,6 +23,24 @@
     ],
     "main": "./lib/index.js",
     "types": "./lib/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./lib/index.d.ts",
+            "import": "./lib/index.js",
+            "require": "./lib/index.js"
+        },
+        "./lib/firebird.msg": "./lib/firebird.msg",
+        "./lib/firebird.msg.json": "./lib/firebird.msg.json",
+        "./lib/*.js": {
+            "types": "./lib/*.d.ts",
+            "default": "./lib/*.js"
+        },
+        "./lib/*": {
+            "types": "./lib/*.d.ts",
+            "default": "./lib/*.js"
+        },
+        "./package.json": "./package.json"
+    },
     "files": [
         "lib",
         "src"

package/src/callback.ts

@@ -45,6 +45,21 @@ export function toError(err: any): Error {
  * Run a callback-style operation and return a Promise for its result.
  * Usage: fromCallback<Database>(cb => attach(options, cb))
  */
+/**
+ * Run `work` with a pooled connection and always return it to its pool
+ * (detach) when the promise settles — a detach hiccup never masks the
+ * outcome of `work`. Shared by Pool.withConnection and
+ * PoolCluster.withConnection so the release semantics cannot drift.
+ */
+export async function withPooledConnection<T>(getAsync: () => Promise<any>, work: (db: any) => Promise<T> | T): Promise<T> {
+    const db = await getAsync();
+    try {
+        return await work(db);
+    } finally {
+        await new Promise<void>(function(resolve) { db.detach(function() { resolve(); }); });
+    }
+}
+
 export function fromCallback<T = any>(executor: (cb: Callback<T>) => void): Promise<T> {
     return new Promise<T>(function(resolve, reject) {
         executor(function(err?: any, result?: T) {

package/src/index.ts

@@ -2,6 +2,8 @@ import Const from './wire/const';
 import { doError, doCallback, fromCallback, type Callback } from './callback';
 import Connection from './wire/connection';
 import Pool from './pool';
+import PoolCluster from './pool-cluster';
+import type { PoolClusterOptions } from './pool-cluster';
 import { escape as escapeValue } from './utils';
 import { parseConnectionUri, parseConnectionString, normalizeOptions } from './uri';
 import type {
@@ -194,6 +196,19 @@ export function pool(max: number, options: Options | string): ConnectionPool {
 	return new Pool(attach, max, Object.assign({}, normalizeOptions(options), { isPool: true }));
 }
 
+/**
+ * Multi-host pooling (primaries/replicas, failover): named nodes, each
+ * backed by a regular pool, selected by glob pattern + 'rr'/'random'/
+ * 'order' selector, with connection-failure failover and error-based
+ * node offlining. See README § Multi-host pooling.
+ */
+export function poolCluster(options?: PoolClusterOptions): PoolCluster {
+	const normalized: PoolClusterOptions = { ...(options || {}) };
+	normalized.defaults = normalizeOptions(normalized.defaults || {});
+	return new PoolCluster(attach, normalized);
+}
+export type { PoolClusterOptions, ClusterSelector } from './pool-cluster';
+
 export { parseConnectionUri, parseConnectionString };
 export { parseNamedPlaceholders } from './named-params';