node-firebird 2.12.0 → 2.13.0

package/README.md

@@ -14,7 +14,7 @@
 - [Connection types](#connection-types) — connection options, `firebird://` URIs and traditional connection strings, classic connections, pooling
 - [Database object (db)](#database-object-db) — database, transaction and statement methods/options
 - [Examples](#examples) — parametrized queries, tagged-template queries (sql), named placeholders, nested result tables (nestTables), row-key transforms (transformKeys), result metadata / affected rows (withMeta), custom type parsers (typeCast), BLOBs, streaming big data, transactions, driver events, database events (POST_EVENT), service manager, charsets/encoding, Firebird 3.0–6.0 features
-- [Extensive Examples](#extensive-examples) — DECFLOAT/INT128, query cancellation (AbortSignal), batch execution (bulk inserts), statement timeouts, scrollable cursors, RETURNING multiple rows, SKIP LOCKED, advanced pooling
+- [Extensive Examples](#extensive-examples) — DECFLOAT/INT128, query cancellation (AbortSignal), batch execution (bulk inserts incl. BLOBs), bulk-insert stream (batchStream), statement timeouts, scrollable cursors, RETURNING multiple rows, SKIP LOCKED, advanced pooling
 - [Using node-firebird with Express.js](#using-node-firebird-with-expressjs)
 - [FAQ](#faq)
 - [Contributing](#contributing) · [Contributors](#contributors)
@@ -39,16 +39,31 @@ and 26 against Firebird 3, 4, 5 and 6).
 
 ## Usage
 
+CommonJS and ESM are both first-class (conditional `exports`):
+
 ```js
-var Firebird = require('node-firebird');
+// CommonJS
+const Firebird = require('node-firebird');
+
+// ESM — default and named imports both work
+import Firebird from 'node-firebird';
+import { attach, pool, GDSCode, SQL_TYPES } from 'node-firebird';
 ```
 
+The documented subpaths keep working in both module systems
+(`require('node-firebird/lib/gdscodes')`, …).
+
 TypeScript is fully supported — the driver itself is written in TypeScript and
-ships its own type declarations:
+ships its own type declarations, with generics on the query APIs:
 
 ```ts
 import * as Firebird from 'node-firebird';
 import type { Options, Database } from 'node-firebird';
+
+interface Emp { ID: number; NAME: string }
+const rows = await db.queryAsync<Emp>('SELECT ID, NAME FROM EMP');  // Emp[]
+db.query<Emp>('SELECT ID, NAME FROM EMP', [], (err, rows) => { /* rows: Emp[] */ });
+const r = await db.queryAsync<Emp>('SELECT ...', [], { withMeta: true }); // QueryResult<Emp>
 ```
 
 ### Developing the driver
@@ -1209,7 +1224,11 @@ Firebird.attach(options, function (err, db) {
   });
 
   db.on('error', function (err) {
-    // connection-level errors (socket errors, closed connection, etc.)
+    // connection-level errors (socket errors, closed connection, etc.).
+    // Delivered to listeners only: without one, background failures (e.g.
+    // a failed automatic reconnect) are NOT re-thrown as uncaught
+    // exceptions — the operations they affect still receive the error
+    // through their own callbacks/promises.
   });
 
   db.on('transaction', function (options) {
@@ -1506,7 +1525,27 @@ Commonly used Firebird character sets are automatically mapped to their correspo
 | `ASCII`                | `ascii`                 | 7-bit ASCII. |
 | `NONE`                 | `latin1`                | Raw/unspecified character set. Treated as binary-safe 8-bit characters. |
 
-Accented characters and fixed-length `CHAR(N)` column whitespace/truncation are handled automatically matching the connection character set width definitions.
+Beyond Node's native encodings, the driver ships **codepage codecs** for the
+single-byte charsets (decode *and* encode — columns, parameters, SQL
+literals and `blobAsText` blobs all transcode):
+
+> `WIN1250`–`WIN1258` (Central European, Cyrillic, Greek, Turkish, Hebrew,
+> Arabic, Baltic, Vietnamese), `ISO8859_2`–`ISO8859_9`, `ISO8859_13`,
+> `KOI8R`, `KOI8U`, `DOS866`
+
+```js
+const options = { /* ... */ encoding: 'WIN1251' };
+await db.queryAsync('INSERT INTO T VALUES (?)', ['Привет']); // encoded as cp1251
+```
+
+The codecs are built from Node's ICU tables at first use (present in every
+official Node build). `attachOrCreate`/`create` honour `options.encoding`
+for the new database's default charset too. Accented characters and
+fixed-length `CHAR(N)` whitespace/truncation are handled automatically per
+the charset width — and single-byte columns (including charset `NONE`) are
+readable in full under the default UTF8 connection (the declared fetch
+lengths are widened per the charset-width ratio, fixing the
+`string right truncation` errors of issue [#422](https://github.com/hgourvest/node-firebird/issues/422)).
 
 #### Custom Charset Connection Example
 ```js
@@ -1770,11 +1809,43 @@ Notes:
 - Values are encoded from the statement's own parameter metadata, so
   NUMERIC/DECIMAL scale, `BIGINT`/`INT128` (pass `BigInt`), `BOOLEAN`,
   `TIMESTAMP`/`DATE`/`TIME`, `FLOAT`/`DOUBLE` and `DECFLOAT` all round-trip
-  exactly. BLOB and ARRAY parameters are not supported in batches yet.
+  exactly.
+- `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 the blob ops pipeline on the
+  wire — and the batch messages reference their ids. `ARRAY` parameters
+  are not supported.
 - Oversized `CHAR`/`VARCHAR` values fail the batch client-side before
   anything is sent; server-side record errors (constraint violations,
   truncation…) are reported per record.
 
+### Bulk-insert stream (batchStream, Firebird 4.0+)
+
+`db.batchStream(sql, options)` is the COPY FROM analogue: an object-mode
+`Writable` that flushes parameter-array rows in chunks through one
+prepared statement using the batch API. The Database form runs its own
+transaction — **committed on finish, rolled back on error or destroy**,
+all-or-nothing for the whole stream:
+
+```js
+const { pipeline } = require('stream/promises');
+
+const stream = db.batchStream('INSERT INTO EVENTS VALUES (?, ?, ?)', {
+  flushRows: 1000, // rows buffered per batch flush (default 1000)
+});
+
+await pipeline(mySourceOfRowArrays, stream); // e.g. a CSV parser
+console.log(stream.recordCount, stream.affectedRows); // totals after 'finish'
+```
+
+Backpressure is the `Writable` machinery itself: writes pause while a
+chunk is in flight, so an arbitrarily large source never accumulates in
+memory beyond `flushRows`. BLOB columns accept Buffers/strings per the
+batch rules above. `transaction.batchStream(sql, options)` runs inside an
+existing transaction and leaves commit/rollback to you. The remaining
+options (`chunkSize`, `bufferSize`, …) pass through to
+[executeBatch](#batch-execution-firebird-40).
+
 ### Statement Timeouts (Firebird 4.0+)
 Setting a statement timeout allows the client to automatically abort queries that take too long on the server.
 ```js
@@ -2110,6 +2181,25 @@ app.get('/users/:id/picture', withConnection(pool, function (db, req, res, done)
 
 Answers to recurring questions from the [issue tracker](https://github.com/hgourvest/node-firebird/issues).
 
+#### Text comes back as `������` with a WIN1250/1251/1253/1257 database (issue [#319](https://github.com/hgourvest/node-firebird/issues/319))
+
+Resolved — the driver now ships codepage codecs for the single-byte
+charsets (`WIN1250`–`WIN1258`, `ISO8859_2`–`9`/`13`, `KOI8R`/`KOI8U`,
+`DOS866`): just set the matching connection encoding and both reads and
+writes transcode correctly, including parameters, SQL literals and
+`blobAsText` blobs:
+
+```js
+const options = { /* ... */ encoding: 'WIN1253' };
+```
+
+See [§ Character Set & Encoding Support](#character-set--encoding-support).
+For a charset *outside* that list (e.g. `DOS437`/`DOS850`), the
+[iconv-lite](https://www.npmjs.com/package/iconv-lite) escape hatch still
+works: connect with `encoding: 'NONE'`, read raw bytes via `latin1` in a
+[`typeCast` hook](#custom-type-parsers-typecast) and decode with the real
+codepage; write already-encoded bytes as Buffer parameters.
+
 #### Can I use aggregate functions like `LIST()`? I get "no database to handle" when I call the result.
 
 Yes — `LIST()` is plain SQL and needs no special driver support. The error happens because `LIST()` returns a text blob (subtype 1), and blob columns come back from `db.query`/`transaction.query` as **async reader functions** bound to the transaction the query ran in (see [Reading Blobs](#reading-blobs-asynchronous)). Calling that function without a transaction — or with a different one — is what throws "no database to handle".

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