node-firebird 2.12.0 → 2.14.0

package/lib/types.d.ts

@@ -1,4 +1,4 @@
-import type { Readable } from 'stream';
+import type { Readable, Writable } from 'stream';
 import type { SqlTag } from './sql-template';
 export type { SqlTag, SqlQuery, SqlIdentifier, CompiledQuery } from './sql-template';
 export type DatabaseCallback = (err: any, db: Database) => void;
@@ -193,6 +193,20 @@ export interface QueryResult<T = any> {
     recordCounts?: RecordCounts;
     warnings: ServerWarning[];
 }
+/** Options for batchStream: the executeBatch options plus stream tuning. */
+export type BatchStreamOptions = BatchOptions & {
+    /** Rows buffered per executeBatch flush (default 1000). */
+    flushRows?: number;
+    /** Writable highWaterMark in rows (default: flushRows). */
+    highWaterMark?: number;
+};
+/** The Writable returned by batchStream, with totals valid after 'finish'. */
+export interface BatchStream extends Writable {
+    /** Records the server processed so far. */
+    recordCount: number;
+    /** Sum of per-record update counts so far. */
+    affectedRows: number;
+}
 export type QueryStreamOptions = QueryOptions & {
     /**
      * Rows buffered internally before fetching pauses (object-mode
@@ -213,8 +227,8 @@ 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: QueryParams, callback: QueryCallback, options?: QueryOptions): Database;
-    execute(query: string, params: QueryParams, callback: QueryCallback, options?: QueryOptions): Database;
+    query<T = any>(query: string, params: QueryParams, callback: (err: any, result: T[], meta?: any[], isSelect?: boolean) => void, options?: QueryOptions): Database;
+    execute<T = any>(query: string, params: QueryParams, callback: (err: any, result: T[], meta?: any[], isSelect?: boolean) => void, options?: QueryOptions): Database;
     /** Bulk-execute in its own transaction, all-or-nothing (Firebird 4.0+). */
     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;
@@ -225,6 +239,13 @@ export interface Database {
      * fetch and releases the statement.
      */
     queryStream(query: string, params?: QueryParams, options?: QueryStreamOptions): Readable;
+    /**
+     * Bulk-insert Writable (COPY FROM analogue, Firebird 4.0+): write
+     * parameter-array rows; they are flushed in chunks through the batch
+     * API. Runs its own transaction — committed on finish, rolled back on
+     * error/destroy. BLOB columns accept Buffers/strings.
+     */
+    batchStream(query: string, options?: BatchStreamOptions): BatchStream;
     drop(callback: SimpleCallback): void;
     escape(value: any): string;
     attachEvent(callback: any): this;
@@ -270,8 +291,8 @@ export interface Transaction {
      */
     savepoint<T>(work: (transaction: Transaction) => Promise<T> | T): Promise<T>;
     newStatement(query: string, callback: (err: Error | null, statement: Statement) => void): void;
-    query(query: string, params: QueryParams, callback: QueryCallback, options?: QueryOptions): void;
-    execute(query: string, params: QueryParams, callback: QueryCallback, options?: QueryOptions): void;
+    query<T = any>(query: string, params: QueryParams, callback: (err: any, result: T[], meta?: any[], isSelect?: boolean) => void, options?: QueryOptions): void;
+    execute<T = any>(query: string, params: QueryParams, callback: (err: any, result: T[], meta?: any[], isSelect?: boolean) => void, options?: QueryOptions): void;
     /** Bulk-execute within this transaction; per-record failures do not roll back (Firebird 4.0+). */
     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;
@@ -281,6 +302,11 @@ export interface Transaction {
      * transaction is NOT committed when the stream ends.
      */
     queryStream(query: string, params?: QueryParams, options?: QueryStreamOptions): Readable;
+    /**
+     * Bulk-insert Writable inside this transaction (see
+     * Database.batchStream); commit/rollback stays with the caller.
+     */
+    batchStream(query: string, options?: BatchStreamOptions): BatchStream;
     commit(callback?: SimpleCallback): void;
     commitRetaining(callback?: SimpleCallback): void;
     rollback(callback?: SimpleCallback): void;
@@ -358,6 +384,13 @@ export interface Options {
      * per-query `namedPlaceholders: false` override.
      */
     namedPlaceholders?: boolean;
+    /**
+     * Default character set of a NEWLY CREATED database (create /
+     * attachOrCreate only). Falls back to the connection `encoding`, then
+     * UTF8 — pass e.g. `defaultCharset: 'UTF8'` to keep a modern database
+     * default while connecting with a legacy codepage `encoding`.
+     */
+    defaultCharset?: string;
     /**
      * Qualify object-row keys by source table (same option as mysql2), so
      * JOINed columns with the same name stop overwriting each other:

package/lib/utils.d.ts

@@ -6,6 +6,18 @@ export declare const parseDate: (str: string) => Date;
 /**
  * Get Error Message per gdscode
  */
+/**
+ * Turn a failed executeBatch completion into the all-or-nothing error
+ * shape shared by database.executeBatch and batchStream: the first
+ * record's own error (or a synthesized summary), with the full
+ * completion attached as err.batchCompletion.
+ */
+export declare const batchResultToError: (result: {
+    errors: {
+        error: any;
+    }[];
+    errorRecordNumbers: number[];
+}) => any;
 export declare const lookupMessages: (status: FbStatusItem[]) => string;
 /**
  * Escape value

package/lib/utils.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.escape = exports.lookupMessages = exports.parseDate = void 0;
+exports.escape = exports.lookupMessages = exports.batchResultToError = exports.parseDate = void 0;
 exports.noop = noop;
 const firebird_msg_json_1 = __importDefault(require("./firebird.msg.json"));
 const const_1 = __importDefault(require("./wire/const"));
@@ -97,6 +97,21 @@ exports.parseDate = parseDate;
 /**
  * Get Error Message per gdscode
  */
+/**
+ * Turn a failed executeBatch completion into the all-or-nothing error
+ * shape shared by database.executeBatch and batchStream: the first
+ * record's own error (or a synthesized summary), with the full
+ * completion attached as err.batchCompletion.
+ */
+const batchResultToError = (result) => {
+    const first = result.errors.length ? result.errors[0] : null;
+    const err = first
+        ? first.error
+        : new Error('Batch failed for record(s) ' + result.errorRecordNumbers.join(', '));
+    err.batchCompletion = result;
+    return err;
+};
+exports.batchResultToError = batchResultToError;
 const lookupMessages = (status) => {
     const messages = status.map((item) => {
         let text = MessagesError[item.gdscode];
@@ -130,7 +145,10 @@ const escape = function (value, protocolVersion) {
         case 'number':
             return value.toString();
         case 'string':
-            return "'" + value.replace(/'/g, "''").replace(/\\/g, '\\\\') + "'";
+            // Firebird string literals have NO backslash escapes — only the
+            // quote is doubled. Doubling backslashes corrupted the data
+            // (issue #156: '\' arrived as '\\').
+            return "'" + value.replace(/'/g, "''") + "'";
     }
     if (value instanceof Date)
         return "'" + value.getFullYear() + '-' + (value.getMonth() + 1).toString().padStart(2, '0') + '-' + value.getDate().toString().padStart(2, '0') + ' ' + value.getHours().toString().padStart(2, '0') + ':' + value.getMinutes().toString().padStart(2, '0') + ':' + value.getSeconds().toString().padStart(2, '0') + '.' + value.getMilliseconds().toString().padStart(3, '0') + "'";

package/lib/wire/batch-stream.d.ts

@@ -0,0 +1,26 @@
+/***************************************
+ *
+ *   batchStream — object-mode Writable over the Firebird 4 batch API
+ *
+ *   The COPY FROM analogue: write parameter rows, they are flushed in
+ *   chunks through statement.executeBatch (single prepared statement,
+ *   protocol-level batching, BLOB values included). Backpressure is the
+ *   Writable machinery itself: a write callback is held while a chunk
+ *   is in flight.
+ *
+ ***************************************/
+import { Writable } from 'stream';
+/**
+ * Build the Writable for Database.batchStream / Transaction.batchStream.
+ * With `ownsTransaction` (the Database form) the stream runs its own
+ * transaction: committed on finish, rolled back on error/destroy —
+ * all-or-nothing for the whole stream. The Transaction form leaves
+ * commit/rollback to the caller.
+ *
+ * Rows accumulate up to options.flushRows (default 1000) per
+ * executeBatch flush; the remaining executeBatch options (chunkSize,
+ * bufferSize, …) pass through. After 'finish', stream.recordCount and
+ * stream.affectedRows carry the totals.
+ */
+declare function makeBatchStream(target: any, query: string, options: any, ownsTransaction: boolean): Writable;
+export = makeBatchStream;

package/lib/wire/batch-stream.js

@@ -0,0 +1,109 @@
+"use strict";
+/***************************************
+ *
+ *   batchStream — object-mode Writable over the Firebird 4 batch API
+ *
+ *   The COPY FROM analogue: write parameter rows, they are flushed in
+ *   chunks through statement.executeBatch (single prepared statement,
+ *   protocol-level batching, BLOB values included). Backpressure is the
+ *   Writable machinery itself: a write callback is held while a chunk
+ *   is in flight.
+ *
+ ***************************************/
+const stream_1 = require("stream");
+const callback_1 = require("../callback");
+const utils_1 = require("../utils");
+/**
+ * Build the Writable for Database.batchStream / Transaction.batchStream.
+ * With `ownsTransaction` (the Database form) the stream runs its own
+ * transaction: committed on finish, rolled back on error/destroy —
+ * all-or-nothing for the whole stream. The Transaction form leaves
+ * commit/rollback to the caller.
+ *
+ * Rows accumulate up to options.flushRows (default 1000) per
+ * executeBatch flush; the remaining executeBatch options (chunkSize,
+ * bufferSize, …) pass through. After 'finish', stream.recordCount and
+ * stream.affectedRows carry the totals.
+ */
+function makeBatchStream(target, query, options, ownsTransaction) {
+    options = options || {};
+    const flushRows = options.flushRows > 0 ? Math.floor(options.flushRows) : 1000;
+    const batchOptions = { ...options };
+    delete batchOptions.flushRows;
+    delete batchOptions.highWaterMark;
+    let transaction = null;
+    let statement = null;
+    let buffered = [];
+    const init = async () => {
+        if (statement) {
+            return;
+        }
+        transaction = ownsTransaction ? await target.transactionAsync() : target;
+        statement = await (0, callback_1.fromCallback)((cb) => transaction.newStatement(query, cb));
+    };
+    const flush = async () => {
+        if (!buffered.length) {
+            return;
+        }
+        await init();
+        const chunk = buffered;
+        buffered = [];
+        const result = await (0, callback_1.fromCallback)((cb) => statement.executeBatch(transaction, chunk, cb, batchOptions));
+        if (!result.success) {
+            // the same all-or-nothing error shape database.executeBatch uses
+            throw (0, utils_1.batchResultToError)(result);
+        }
+        stream.recordCount += result.recordCount;
+        for (const count of result.updateCounts) {
+            stream.affectedRows += count;
+        }
+    };
+    const cleanup = async (commit) => {
+        if (statement) {
+            const stmt = statement;
+            statement = null;
+            await new Promise((resolve) => stmt.release(() => resolve()));
+        }
+        if (ownsTransaction && transaction) {
+            const tx = transaction;
+            transaction = null;
+            await (commit ? tx.commitAsync() : tx.rollbackAsync());
+        }
+    };
+    const stream = new stream_1.Writable({
+        objectMode: true,
+        highWaterMark: options.highWaterMark > 0 ? options.highWaterMark : flushRows,
+        write(row, _enc, cb) {
+            if (!Array.isArray(row)) {
+                cb(new Error('batchStream expects parameter-array rows'));
+                return;
+            }
+            buffered.push(row);
+            if (buffered.length >= flushRows) {
+                flush().then(() => cb(), cb);
+            }
+            else {
+                cb();
+            }
+        },
+        final(cb) {
+            // an empty stream finishes without touching the server at all
+            // (flush() early-returns and init never runs)
+            flush()
+                .then(() => cleanup(true))
+                .then(() => cb(), (err) => {
+                // the failed stream must not commit half a bulk load
+                cleanup(false).catch(() => { });
+                cb(err);
+            });
+        },
+        destroy(err, cb) {
+            cleanup(false)
+                .then(() => cb(err), () => cb(err));
+        },
+    });
+    stream.recordCount = 0;
+    stream.affectedRows = 0;
+    return stream;
+}
+module.exports = makeBatchStream;

package/lib/wire/codepages.d.ts

@@ -0,0 +1,23 @@
+/***************************************
+ *
+ *   Single-byte codepage codecs (WIN125x, ISO8859_x, KOI8, DOS866)
+ *
+ *   Node's Buffer only decodes utf8/latin1/ascii natively. These
+ *   codepages are decoded through the WHATWG TextDecoder (backed by
+ *   ICU — present in every official Node build) and encoded through
+ *   reverse tables built from the same decoder at first use, so the
+ *   two directions can never disagree. Issues #319/#301/#422.
+ *
+ ***************************************/
+export interface TextCodec {
+    /** Firebird charset name (upper case). */
+    name: string;
+    decode(buffer: Buffer): string;
+    encode(value: string): Buffer;
+}
+export declare function charsetWidthById(id: number | undefined): number;
+/**
+ * Codec for a Firebird charset name, or null when the charset is unknown,
+ * natively handled by Buffer, or the ICU tables are unavailable. Cached.
+ */
+export declare function getCodec(charsetName: string | undefined): TextCodec | null;

package/lib/wire/codepages.js

@@ -0,0 +1,137 @@
+"use strict";
+/***************************************
+ *
+ *   Single-byte codepage codecs (WIN125x, ISO8859_x, KOI8, DOS866)
+ *
+ *   Node's Buffer only decodes utf8/latin1/ascii natively. These
+ *   codepages are decoded through the WHATWG TextDecoder (backed by
+ *   ICU — present in every official Node build) and encoded through
+ *   reverse tables built from the same decoder at first use, so the
+ *   two directions can never disagree. Issues #319/#301/#422.
+ *
+ ***************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.charsetWidthById = charsetWidthById;
+exports.getCodec = getCodec;
+/** Firebird charset name → WHATWG encoding label (single-byte only). */
+const ICU_LABELS = Object.freeze({
+    WIN1250: 'windows-1250',
+    WIN1251: 'windows-1251',
+    WIN1253: 'windows-1253',
+    WIN1254: 'windows-1254',
+    WIN1255: 'windows-1255',
+    WIN1256: 'windows-1256',
+    WIN1257: 'windows-1257',
+    WIN1258: 'windows-1258',
+    ISO8859_2: 'iso-8859-2',
+    ISO8859_3: 'iso-8859-3',
+    ISO8859_4: 'iso-8859-4',
+    ISO8859_5: 'iso-8859-5',
+    ISO8859_6: 'iso-8859-6',
+    ISO8859_7: 'iso-8859-7',
+    ISO8859_8: 'iso-8859-8',
+    ISO8859_9: 'iso-8859-9',
+    ISO8859_13: 'iso-8859-13',
+    KOI8R: 'koi8-r',
+    KOI8U: 'koi8-u',
+    DOS866: 'ibm866',
+});
+/**
+ * Bytes-per-character by Firebird charset id (RDB$CHARACTER_SETS —
+ * verified against a live server). Everything not listed (NONE, ASCII,
+ * ISO8859_x, WIN125x, DOS*, KOI8*, CYRL, TIS620, …) is single-byte.
+ */
+const CHARSET_WIDTH_BY_ID = Object.freeze({
+    3: 3, // UNICODE_FSS
+    4: 4, // UTF8
+    5: 2, // SJIS_0208
+    6: 2, // EUCJ_0208
+    44: 2, // KSC_5601
+    56: 2, // BIG_5
+    57: 2, // GB_2312
+    67: 2, // GBK
+    68: 2, // CP943C
+    69: 4, // GB18030
+});
+function charsetWidthById(id) {
+    if (id === undefined) {
+        return 1;
+    }
+    return CHARSET_WIDTH_BY_ID[id] || 1;
+}
+const cache = new Map();
+function buildCodec(name) {
+    const label = ICU_LABELS[name];
+    if (!label) {
+        return null;
+    }
+    let decoder;
+    try {
+        decoder = new TextDecoder(label);
+    }
+    catch {
+        // Node built with small-icu: legacy encodings unavailable
+        return null;
+    }
+    // Build both directions from the decoder, one byte at a time — every
+    // byte of a single-byte codepage maps to exactly one BMP character
+    // (undefined bytes decode to U+FFFD, which is kept for decoding but
+    // never used for the reverse map).
+    const toCode = new Uint16Array(256);
+    const toByte = new Map();
+    const one = Buffer.alloc(1);
+    for (let i = 0; i < 256; i++) {
+        one[0] = i;
+        const ch = decoder.decode(one);
+        toCode[i] = ch.charCodeAt(0);
+        if (ch !== '�' && !toByte.has(ch)) {
+            toByte.set(ch, i);
+        }
+    }
+    return {
+        name,
+        decode(buffer) {
+            // batch through fromCharCode instead of per-byte string concat —
+            // wide CHAR columns and text blobs decode in O(chunks) allocations
+            const codes = new Array(buffer.length);
+            for (let i = 0; i < buffer.length; i++) {
+                codes[i] = toCode[buffer[i]];
+            }
+            const CHUNK = 4096;
+            if (codes.length <= CHUNK) {
+                return String.fromCharCode(...codes);
+            }
+            let out = '';
+            for (let i = 0; i < codes.length; i += CHUNK) {
+                out += String.fromCharCode(...codes.slice(i, i + CHUNK));
+            }
+            return out;
+        },
+        encode(value) {
+            const out = Buffer.alloc(value.length);
+            for (let i = 0; i < value.length; i++) {
+                const b = toByte.get(value[i]);
+                // unmappable characters become '?' — the convention every
+                // codepage transcoder (incl. iconv) uses by default
+                out[i] = b === undefined ? 0x3f : b;
+            }
+            return out;
+        },
+    };
+}
+/**
+ * Codec for a Firebird charset name, or null when the charset is unknown,
+ * natively handled by Buffer, or the ICU tables are unavailable. Cached.
+ */
+function getCodec(charsetName) {
+    if (!charsetName) {
+        return null;
+    }
+    const name = String(charsetName).toUpperCase();
+    let codec = cache.get(name);
+    if (codec === undefined) {
+        codec = buildCodec(name);
+        cache.set(name, codec);
+    }
+    return codec;
+}

package/lib/wire/connection.d.ts

@@ -78,6 +78,17 @@ declare class Connection {
      */
     releaseStatement(statement: Statement, callback?: QueueCallback): void;
     _rejectPending(err: any): void;
+    /**
+     * Deliver a connection-level error to 'error' listeners — and ONLY to
+     * listeners. Emitting an unlistened 'error' makes Node throw the error
+     * object as an uncaught exception; for errors that originate in
+     * background contexts (the reconnect timer, socket-level failures whose
+     * operations are separately rejected via _rejectPending) that crashes
+     * the process — or, under a test runner, fails whatever unrelated test
+     * happens to be running. The failing operations themselves always
+     * still receive their error through their own callbacks.
+     */
+    _emitError(err: any): void;
     _bind_events(host: string, port: number, callback: SimpleCallback | undefined): void;
     disconnect(): void;
     sendOpContAuth(authData: string, authDataEnc: BufferEncoding, pluginName: string): void;
@@ -120,12 +131,18 @@ declare class Connection {
      * gets an in-order response (op_batch_cs for exec), so the regular
      * response queue keeps everything in sync.
      *
-     * rows: array of parameter arrays, one per record. BLOB/ARRAY columns
-     * are not supported yet. The callback receives a completion object:
-     * { recordCount, updateCounts, errors: [{recordNumber, error}],
-     *   errorRecordNumbers, success }.
+     * rows: array of parameter arrays, one per record. BLOB columns accept
+     * Buffers, strings, JSON-able objects or pre-created blob quad ids —
+     * values are uploaded as transaction blobs first (all initiated
+     * back-to-back so they pipeline) and the batch messages reference their
+     * ids. ARRAY columns are not supported. The callback receives a
+     * completion object: { recordCount, updateCounts, errors:
+     * [{recordNumber, error}], errorRecordNumbers, success }.
      */
     executeBatch(transaction: Transaction, statement: Statement, rows: QueryParams[], callback: BatchCb | undefined, options?: BatchOptions): this | undefined;
+    /** Encode and send the batch packets (rows are fully materialized:
+     *  blob values already replaced by quad ids by executeBatch). */
+    _executeBatchEncoded(transaction: Transaction, statement: Statement, rows: any[][], callback: BatchCb | undefined, options: BatchOptions): void;
     /** `params` may be the callback itself when the statement has no parameters. */
     executeStatement(transaction: Transaction, statement: Statement, params: any, callback?: QueueCallback, custom?: InternalQueryOptions): this | undefined;
     sendExecute(op: number, statement: Statement, transaction: Transaction, callback: QueueCallback | undefined, parameters?: any[]): void;
@@ -138,12 +155,29 @@ declare class Connection {
      * response is a plain op_response whose buffer holds the info clusters.
      */
     statementInfo(statement: Statement, items: number[], callback?: QueueCallback): this | undefined;
+    /**
+     * Resolve the pending blobAsText fetches of a decoded row batch
+     * (ret.arrBlob) and write the text back into ret.data. Reads run
+     * sequentially to respect Firebird's per-connection open-blob-handle
+     * limit (issue #387). Used by fetchAll for cursors and by
+     * transaction.execute for op_execute2 singletons (EXECUTE PROCEDURE /
+     * RETURNING — issue #305, whose blobs never resolved before).
+     */
+    resolveTextBlobs(transaction: Transaction, ret: any, callback: (err?: any) => void): void;
     fetchAll(statement: Statement, transaction: Transaction, callback: Callback<any[]>): void;
     openBlob(blob: Quad, transaction: Transaction, callback: QueueCallback): void;
     closeBlob(blob: any, callback?: QueueCallback, defer?: boolean): void;
     getSegment(blob: any, callback: QueueCallback): void;
     createBlob2(transaction: Transaction, callback: QueueCallback): void;
     batchSegments(blob: any, buffer: Buffer, callback: QueueCallback): void;
+    /**
+     * Create a transaction blob, upload `value` (Buffer, string, or a
+     * JSON-able object) and deliver its quad id. executeBatch's blob
+     * pre-pass uses this: batch messages reference pre-created transaction
+     * blobs (the batch parameter buffer's default BLOB_NONE policy), just
+     * like the classic execute path stores blob params.
+     */
+    uploadBlob(transaction: Transaction, value: any, callback: (err: any, oid?: any) => void): void;
     svcattach(options: InternalOptions, callback?: Callback<ServiceManager>, svc?: ServiceManager): void;
     svcstart(spbaction: BlrWriter, callback: QueueCallback | undefined): void;
     svcquery(spbquery: number[], resultbuffersize: number, timeout: number | undefined, callback: QueueCallback | undefined): void;