node-firebird 2.11.0 → 2.13.0

package/lib/sql-template.js

@@ -0,0 +1,162 @@
+"use strict";
+/***************************************
+ *
+ *   Tagged-template query API (Postgres.js-style)
+ *
+ *   db.sql`SELECT * FROM EMP WHERE ID = ${id}`   →  lazy thenable query
+ *   db.sql('COLUMN NAME')                        →  quoted identifier
+ *
+ *   Interpolated values become positional `?` parameters — never string
+ *   concatenation — so the API is injection-safe by construction. A query
+ *   embedded inside another tag is treated as a fragment: its text and
+ *   parameters are spliced in place. Arrays expand to `?, ?, ?` lists for
+ *   IN clauses. Execution is lazy (on await/then) and happens exactly once.
+ *
+ ***************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SqlQuery = exports.SqlIdentifier = void 0;
+exports.quoteIdentifier = quoteIdentifier;
+exports.makeSqlTag = makeSqlTag;
+/** A dynamically quoted identifier produced by sql('name'). */
+class SqlIdentifier {
+    constructor(name) {
+        this.name = name;
+    }
+}
+exports.SqlIdentifier = SqlIdentifier;
+/**
+ * Quote a (possibly dot-qualified) identifier for dialect 3: each part is
+ * wrapped in double quotes with embedded quotes doubled, so user input can
+ * never break out of the identifier position.
+ */
+function quoteIdentifier(name) {
+    return String(name)
+        .split('.')
+        .map((part) => '"' + part.replace(/"/g, '""') + '"')
+        .join('.');
+}
+function compile(strings, values, active) {
+    let text = '';
+    const params = [];
+    for (let i = 0; i < strings.length; i++) {
+        text += strings[i];
+        if (i >= values.length) {
+            continue;
+        }
+        const value = values[i];
+        if (value instanceof SqlIdentifier) {
+            text += quoteIdentifier(value.name);
+        }
+        else if (value instanceof SqlQuery) {
+            // embedded fragment: splice its text and params in place. The
+            // same fragment may appear several times (a DAG), but a fragment
+            // containing itself would recurse forever — track the expansion
+            // stack and reject cycles with a diagnosable error.
+            active = active || new Set();
+            if (active.has(value)) {
+                throw new Error('circular sql fragment: a query is embedded (transitively) inside itself');
+            }
+            active.add(value);
+            const inner = compile(value.strings, value.values, active);
+            active.delete(value);
+            text += inner.text;
+            params.push(...inner.params);
+        }
+        else if (Array.isArray(value)) {
+            // IN (${[1, 2, 3]}) → IN (?, ?, ?)
+            if (!value.length) {
+                // '' would compile to `IN ()` — invalid SQL raising a server
+                // syntax error the caller never wrote; fail early instead
+                throw new Error('cannot interpolate an empty array (would compile to invalid SQL like "IN ()")');
+            }
+            text += value.map(() => '?').join(', ');
+            params.push(...value);
+        }
+        else {
+            text += '?';
+            params.push(value);
+        }
+    }
+    return { text, params };
+}
+/**
+ * A lazily executed tagged query. Awaiting it (or calling then/catch/
+ * finally) runs it through the owning Database/Transaction exactly once;
+ * embedding it in another tag uses it as a fragment instead and never
+ * executes it.
+ */
+class SqlQuery {
+    constructor(executor, strings, values) {
+        this.executor = executor;
+        this.strings = strings;
+        this.values = values;
+    }
+    /** The compiled SQL text (`?` placeholders) and parameter array. */
+    toQuery() {
+        return compile(this.strings, this.values);
+    }
+    /**
+     * Attach per-query options (timeout, signal, nestTables, …). Must be
+     * called before the query executes — options attached afterwards would
+     * be silently ignored, so that throws instead.
+     */
+    options(queryOptions) {
+        if (this.executed) {
+            throw new Error('sql query already executed — call .options() before awaiting it');
+        }
+        this.queryOptions = { ...this.queryOptions, ...queryOptions };
+        return this;
+    }
+    /** Execute resolving the full { rows, fields, affectedRows, … } result. */
+    withMeta() {
+        return this.run(true);
+    }
+    /**
+     * A query executes exactly once, in the shape of its first consumer
+     * (plain rows via then/await, or the full result via withMeta).
+     * Consuming it again in the OTHER shape cannot be honoured from the
+     * cached promise, so it throws rather than silently returning the
+     * wrong shape.
+     */
+    run(withMeta) {
+        if (this.executed) {
+            if (withMeta !== this.executedMeta) {
+                throw new Error(this.executedMeta
+                    ? 'sql query already executed via .withMeta() — await that result instead of the query'
+                    : 'sql query already executed as plain rows — call .withMeta() first, or build a new query');
+            }
+            return this.executed;
+        }
+        this.executedMeta = withMeta;
+        const { text, params } = compile(this.strings, this.values);
+        const options = withMeta ? { ...this.queryOptions, withMeta: true } : this.queryOptions;
+        this.executed = this.executor(text, params, options);
+        return this.executed;
+    }
+    then(onfulfilled, onrejected) {
+        return this.run(false).then(onfulfilled, onrejected);
+    }
+    catch(onrejected) {
+        return this.then(undefined, onrejected);
+    }
+    finally(onfinally) {
+        return this.run(false).finally(onfinally);
+    }
+}
+exports.SqlQuery = SqlQuery;
+/**
+ * Build the `sql` tag for a Database/Transaction. `executor` receives the
+ * compiled text, params and per-query options and must return a promise
+ * (Database/Transaction pass their queryAsync).
+ */
+function makeSqlTag(executor) {
+    return function sql(first, ...values) {
+        if (Array.isArray(first) && Object.prototype.hasOwnProperty.call(first, 'raw')) {
+            return new SqlQuery(executor, first, values);
+        }
+        if (typeof first === 'string') {
+            return new SqlIdentifier(first);
+        }
+        throw new Error('sql must be used as a template tag (sql`...`) or called with an identifier string (sql(\'NAME\'))');
+    };
+}

package/lib/types.d.ts

@@ -1,4 +1,6 @@
-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;
 export type TransactionCallback = (err: any, transaction: Transaction) => void;
 export type QueryCallback = (err: any, result: any[]) => void;
@@ -127,7 +129,84 @@ export type QueryOptions = {
      * unaffected.
      */
     nestTables?: boolean | string;
+    /**
+     * Per-query override of the `transformKeys` connection option: rewrite
+     * object-row keys — `'camel'` turns `FIRST_NAME` into `firstName`, or
+     * pass a custom `(key) => key` mapper. Applied after `lowercase_keys`
+     * and to both parts of `nestTables` keys. Column metadata (`fields`,
+     * typeCast) keeps the raw server aliases.
+     */
+    transformKeys?: 'camel' | ((key: string) => string);
+    /**
+     * Deliver a full result object `{ rows, fields, affectedRows,
+     * recordCounts, warnings }` instead of the bare rows (callback and
+     * promise APIs). For DML, `affectedRows` is what the server actually
+     * changed (`isc_info_sql_records`, one extra lightweight info request
+     * per statement — hence opt-in) and `recordCounts` breaks it down per
+     * verb; for SELECT it is the number of rows returned (pg's `rowCount`
+     * convention) with no extra round-trip. `warnings` carries any
+     * `isc_arg_warning` entries from the execute response. Honoured by
+     * query/execute and their *Async wrappers only — ignored by the
+     * streaming APIs (sequentially/queryStream, where rows bypass the
+     * result) and executeBatch (which has its own completion shape).
+     */
+    withMeta?: boolean;
+};
+/** Column metadata delivered in withMeta results (`fields`) — the same
+ *  vocabulary the typeCast hook receives, plus nullable and the relation
+ *  alias/schema. */
+export interface FieldMetadata {
+    type: number;
+    typeName: string;
+    subType?: number;
+    scale?: number;
+    length?: number;
+    nullable?: boolean;
+    field?: string;
+    relation?: string;
+    relationAlias?: string;
+    relationSchema?: string;
+    alias?: string;
+}
+/** Per-verb server row counts of an executed DML statement. */
+export interface RecordCounts {
+    selectCount: number;
+    insertCount: number;
+    updateCount: number;
+    deleteCount: number;
+}
+/** An isc_arg_warning entry from a server response ('warning' driver event
+ *  and withMeta `warnings`). */
+export interface ServerWarning {
+    gdscode: number;
+    params?: (string | number)[];
+    message: string;
+}
+/** Full result shape delivered when `withMeta: true` is set. */
+export interface QueryResult<T = any> {
+    /** Rows array (SELECT), single row object (RETURNING / procedures), or undefined (plain DML). */
+    rows: T[] | T | undefined;
+    fields: FieldMetadata[];
+    /** DML: rows the server changed; SELECT: rows returned. */
+    affectedRows: number;
+    /** Set for DML statements only. */
+    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
@@ -138,11 +217,18 @@ export type QueryStreamOptions = QueryOptions & {
     asObject?: boolean;
 };
 export interface Database {
+    /**
+     * Tagged-template query API (Postgres.js-style): interpolated values
+     * become positional parameters, `sql('NAME')` quotes an identifier,
+     * embedded `sql` fragments compose, arrays expand to `?, ?, ?` lists.
+     * The returned query is a lazy thenable — it executes once, on await.
+     */
+    sql: SqlTag;
     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;
@@ -153,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;
@@ -160,7 +253,13 @@ export interface Database {
     alterTablespace(name: string, filePath: string, callback?: QueryCallback): Database;
     dropTablespace(name: string, callback?: QueryCallback): Database;
     createSchema(schemaName: string, tablespaceName?: string | QueryCallback, callback?: QueryCallback): Database;
+    queryAsync<T = any>(query: string, params: QueryParams | undefined, options: QueryOptions & {
+        withMeta: true;
+    }): Promise<QueryResult<T>>;
     queryAsync<T = any>(query: string, params?: QueryParams, options?: QueryOptions): Promise<T[]>;
+    executeAsync<T = any>(query: string, params: QueryParams | undefined, options: QueryOptions & {
+        withMeta: true;
+    }): Promise<QueryResult<T>>;
     executeAsync<T = any>(query: string, params?: QueryParams, options?: QueryOptions): Promise<T[]>;
     executeBatchAsync(query: string, rows: QueryParams[], options?: BatchOptions): Promise<BatchResult>;
     sequentiallyAsync(query: string, params: QueryParams | undefined, rowCallback: SequentialCallback, options?: QueryOptions | boolean): Promise<void>;
@@ -183,9 +282,17 @@ export interface Database {
     cancelAsync(kind?: number): Promise<void>;
 }
 export interface Transaction {
+    /** Tagged-template query API running inside this transaction (see Database.sql). */
+    sql: SqlTag;
+    /**
+     * Run `work` inside a savepoint: released on resolve, rolled back TO
+     * (undoing only work's changes) on reject — the transaction stays
+     * usable either way. Nestable.
+     */
+    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;
@@ -195,11 +302,22 @@ 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;
     rollbackRetaining(callback?: SimpleCallback): void;
+    queryAsync<T = any>(query: string, params: QueryParams | undefined, options: QueryOptions & {
+        withMeta: true;
+    }): Promise<QueryResult<T>>;
     queryAsync<T = any>(query: string, params?: QueryParams, options?: QueryOptions): Promise<T[]>;
+    executeAsync<T = any>(query: string, params: QueryParams | undefined, options: QueryOptions & {
+        withMeta: true;
+    }): Promise<QueryResult<T>>;
     executeAsync<T = any>(query: string, params?: QueryParams, options?: QueryOptions): Promise<T[]>;
     executeBatchAsync(query: string, rows: QueryParams[], options?: BatchOptions): Promise<BatchResult>;
     sequentiallyAsync(query: string, params: QueryParams | undefined, rowCallback: SequentialCallback, options?: QueryOptions | boolean): Promise<void>;
@@ -266,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:
@@ -276,6 +401,14 @@ export interface Options {
      * array rows (execute) are unaffected. Overridable per query.
      */
     nestTables?: boolean | string;
+    /**
+     * Rewrite object-row keys (Postgres.js `transform` counterpart):
+     * `'camel'` turns `FIRST_NAME` into `firstName`, or pass a custom
+     * `(key) => key` mapper. Applied after `lowercase_keys` and to both
+     * parts of `nestTables` keys; column metadata keeps raw aliases.
+     * Overridable per query.
+     */
+    transformKeys?: 'camel' | ((key: string) => string);
     /**
      * TCP keepalive probing to detect dead/stale connections (same option
      * names as mysql2). On by default; set false to disable.
@@ -314,6 +447,20 @@ export interface Options {
      * Default 0 (idle connections are kept forever).
      */
     idleTimeoutMillis?: number;
+    /**
+     * Pool only: retire a physical connection after this many checkouts
+     * (pg's `maxUses`) — it is closed for good when returned to the pool
+     * and replaced on demand. Bounds server-side resource drift on
+     * long-lived connections. Default 0 (unlimited uses).
+     */
+    maxUses?: number;
+    /**
+     * Pool only: retire a physical connection this many milliseconds after
+     * it was created (Postgres.js's `max_lifetime`), on return to the pool
+     * or by the idle sweep — even below `min`; replacements are created on
+     * demand. Default 0 (unlimited lifetime).
+     */
+    maxLifetimeMillis?: number;
     /**
      * **Firebird 6.0+ only (Protocol 20+)**
      *

package/lib/uri.js

@@ -187,7 +187,58 @@ function parseConnectionString(str) {
  */
 function normalizeOptions(options) {
     if (typeof options === 'string') {
-        return parseConnectionString(options);
+        options = parseConnectionString(options);
     }
-    return options;
+    return applyEnvDefaults(options);
+}
+/**
+ * Fall back to environment variables for connection settings the caller
+ * did not provide — the pg-style convention using Firebird's own names:
+ * ISC_USER / ISC_PASSWORD (honoured by isql and every official tool) plus
+ * FIREBIRD_HOST / FIREBIRD_PORT / FIREBIRD_DATABASE / FIREBIRD_ROLE.
+ * Explicit options always win; the driver's built-in defaults (SYSDBA /
+ * masterkey / 127.0.0.1) still apply when neither is set. A fresh object
+ * is returned so caller-owned options objects are never mutated.
+ */
+const ENV_FALLBACKS = [
+    ['user', 'ISC_USER'],
+    ['password', 'ISC_PASSWORD'],
+    ['host', 'FIREBIRD_HOST'],
+    ['port', 'FIREBIRD_PORT'],
+    ['database', 'FIREBIRD_DATABASE'],
+    ['role', 'FIREBIRD_ROLE'],
+];
+function applyEnvDefaults(options) {
+    let out = options;
+    for (const [key, envName] of ENV_FALLBACKS) {
+        const value = process.env[envName];
+        // empty-string env vars (common in CI: `export ISC_PASSWORD=`)
+        // count as unset
+        if (value === undefined || value === '') {
+            continue;
+        }
+        // a service-manager connection's `database` selects the TARGET of
+        // backup/restore — never let a leftover env var pick that silently
+        if (key === 'database' && options.manager) {
+            continue;
+        }
+        if (out[key] === undefined || out[key] === null || out[key] === '') {
+            if (out === options) {
+                out = { ...options };
+            }
+            if (key === 'port') {
+                const port = Number(value);
+                if (!Number.isFinite(port) || port <= 0) {
+                    // NaN is falsy: it would silently fall back to 3050
+                    // downstream instead of surfacing the typo
+                    throw new Error('Invalid FIREBIRD_PORT environment variable: ' + value);
+                }
+                out[key] = port;
+            }
+            else {
+                out[key] = value;
+            }
+        }
+    }
+    return out;
 }

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;