node-firebird 2.12.0 → 2.13.0

package/lib/wire/serialize.js

@@ -277,6 +277,16 @@ class XdrWriter {
         this.buffer.fill(0, this.pos + len, this.pos + alen);
         this.pos += alen;
     }
+    /** addString for pre-encoded bytes (codepage connection charsets). */
+    addStringBuffer(b) {
+        var alen = align(b.length);
+        this.ensure(alen + 4);
+        this.buffer.writeInt32BE(b.length, this.pos);
+        this.pos += 4;
+        b.copy(this.buffer, this.pos);
+        this.buffer.fill(0, this.pos + b.length, this.pos + alen);
+        this.pos += alen;
+    }
     addText(s, encoding) {
         var len = Buffer.byteLength(s, encoding);
         var alen = align(len);

package/lib/wire/socket.js

@@ -132,8 +132,14 @@ class Socket {
      * Compress and/or encrypt data before sending to socket.
      */
     write(data, defer = false) {
+        // Callers pass views of the connection's shared _msg buffer, and both
+        // net.Socket (when it cannot flush immediately) and zlib keep a
+        // REFERENCE to the chunk — a later sender rebuilding _msg would then
+        // corrupt this queued packet (intermittent, load-dependent). Own the
+        // bytes at the send boundary, once.
+        data = Buffer.from(data);
         if (process.env.FIREBIRD_DEBUG) {
-            console.log('[fb-debug] socket.write: length=%d bytes=%s encrypt=%s defer=%s', data.length, Buffer.from(data).toString('hex'), this.encrypt, defer);
+            console.log('[fb-debug] socket.write: length=%d bytes=%s encrypt=%s defer=%s', data.length, data.toString('hex'), this.encrypt, defer);
         }
         if (defer) {
             // Accumulate deferred packets instead of overwriting.  Multiple
@@ -142,8 +148,8 @@ class Socket {
             // overwriting the buffer silently drops packets and desynchronises
             // the request/response queue, causing the connection to hang.
             this.buffer = this.buffer
-                ? Buffer.concat([this.buffer, Buffer.from(data)])
-                : Buffer.from(data);
+                ? Buffer.concat([this.buffer, data])
+                : data;
             return;
         }
         if (!defer && this.buffer) {

package/lib/wire/transaction.d.ts

@@ -48,6 +48,12 @@ declare class Transaction {
      * stream ends — commit or roll back yourself.
      */
     queryStream(query: string, params?: QueryParams, options?: QueryStreamOptions): import("node:stream").Readable;
+    /**
+     * 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: string, options?: any): import("node:stream").Writable;
     query(query: string, params?: QueryParams | Callback, callback?: any, options?: InternalQueryOptions): void;
     /**
      * Execute `query` once per row in `rows` using the Firebird 4 batch API

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.13.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/types.ts

@@ -5,7 +5,7 @@
 // They now live in the TypeScript source tree and are compiled into the
 // published declaration files.
 
-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';
@@ -211,6 +211,22 @@ export interface QueryResult<T = any> {
     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
@@ -232,8 +248,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;
@@ -244,6 +260,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;
@@ -290,8 +313,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;
@@ -301,6 +324,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;
@@ -416,6 +444,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/src/utils.ts

@@ -108,6 +108,21 @@ export 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 const batchResultToError = (result: { errors: { error: any }[]; errorRecordNumbers: number[] }): any => {
+    const first = result.errors.length ? result.errors[0] : null;
+    const err: any = first
+        ? first.error
+        : new Error('Batch failed for record(s) ' + result.errorRecordNumbers.join(', '));
+    err.batchCompletion = result;
+    return err;
+};
+
 export const lookupMessages = (status: FbStatusItem[]): string => {
     const messages = status.map((item) => {
         let text = MessagesError[item.gdscode];
@@ -143,7 +158,10 @@ export const escape = function(value: any, protocolVersion?: number): string {
         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)