node-firebird 2.5.0 → 2.7.0

package/README.md

@@ -14,7 +14,7 @@
 - [Connection types](#connection-types) — connection options, classic connections, pooling
 - [Database object (db)](#database-object-db) — database, transaction and statement methods/options
 - [Examples](#examples) — parametrized queries, 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, statement timeouts, scrollable cursors, RETURNING multiple rows, SKIP LOCKED, advanced pooling
+- [Extensive Examples](#extensive-examples) — DECFLOAT/INT128, query cancellation (AbortSignal), batch execution (bulk inserts), 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)
@@ -133,9 +133,9 @@ Available wrappers:
 
 - **module** — `Firebird.attachAsync(options)`, `createAsync`, `attachOrCreateAsync`, `dropAsync`; resolve with a `Database` (or a `ServiceManager` when `options.manager` is `true`)
 - **pool** — `pool.getAsync()`, `pool.destroyAsync()`, `pool.withConnection(work)`
-- **database** — `db.queryAsync(sql, params?, options?)`, `executeAsync`, `sequentiallyAsync(sql, params?, onRow, options?)`, `transactionAsync(options?)`, `newStatementAsync(sql)`, `attachEventAsync()`, `detachAsync()`, `dropAsync()`, `db.withTransaction(work, options?)`
-- **transaction** — `queryAsync`, `executeAsync`, `sequentiallyAsync`, `newStatementAsync`, `commitAsync`, `rollbackAsync`, `commitRetainingAsync`, `rollbackRetainingAsync`
-- **statement** — `executeAsync(transaction, params?, options?)`, `fetchAsync`, `fetchScrollAsync`, `fetchAllAsync`, `closeAsync`, `dropAsync`, `releaseAsync`
+- **database** — `db.queryAsync(sql, params?, options?)`, `executeAsync`, `executeBatchAsync(sql, rows, options?)`, `sequentiallyAsync(sql, params?, onRow, options?)`, `transactionAsync(options?)`, `newStatementAsync(sql)`, `attachEventAsync()`, `detachAsync()`, `dropAsync()`, `db.withTransaction(work, options?)`
+- **transaction** — `queryAsync`, `executeAsync`, `executeBatchAsync`, `sequentiallyAsync`, `newStatementAsync`, `commitAsync`, `rollbackAsync`, `commitRetainingAsync`, `rollbackRetainingAsync`
+- **statement** — `executeAsync(transaction, params?, options?)`, `executeBatchAsync(transaction, rows, options?)`, `fetchAsync`, `fetchScrollAsync`, `fetchAllAsync`, `closeAsync`, `dropAsync`, `releaseAsync`
 
 Notes:
 
@@ -277,6 +277,7 @@ sequenceDiagram
 
 - `db.query(query, [params], function(err, result), options)` - classic query, returns Array of Object
 - `db.execute(query, [params], function(err, result), options)` - classic query, returns Array of Array
+- `db.executeBatch(query, rows, function(err, result), options)` - bulk execution in one round-trip, all-or-nothing (FB >= 4.0, see [Batch Execution](#batch-execution-firebird-40))
 - `db.sequentially(query, [params], function(row, index), function(err), options)` - sequentially query
 - `db.detach(function(err))` detach a database
 - `db.transaction(options, function(err, transaction))` create transaction
@@ -303,6 +304,7 @@ const options = {
 
 - `transaction.query(query, [params], function(err, result), options)` - classic query, returns Array of Object
 - `transaction.execute(query, [params], function(err, result), options)` - classic query, returns Array of Array
+- `transaction.executeBatch(query, rows, function(err, result), options)` - bulk execution with per-record errors (FB >= 4.0, see [Batch Execution](#batch-execution-firebird-40))
 - `transaction.sequentially(query, [params], function(row, index), function(err), options)` - sequentially query
 - `transaction.commit(function(err))` commit current transaction
 - `transaction.rollback(function(err))` rollback current transaction
@@ -1151,6 +1153,101 @@ Firebird.attach({
 });
 ```
 
+### Query Cancellation with AbortSignal (Firebird 2.5+)
+
+Any query can be cancelled while it is executing on the server. Pass an
+`AbortSignal` in the query options — when it fires, the driver sends an
+out-of-band `op_cancel` packet and the running statement fails with
+`err.gdscode === GDSCode.CANCELLED`. The connection itself stays healthy and
+can run further queries immediately.
+
+```js
+const { GDSCode } = require('node-firebird/lib/gdscodes');
+
+const controller = new AbortController();
+setTimeout(() => controller.abort(), 5000); // or req.on('close', ...) in Express
+
+try {
+    const rows = await db.queryAsync('SELECT /* expensive */ ...', [], { signal: controller.signal });
+} catch (err) {
+    if (err.gdscode === GDSCode.CANCELLED) {
+        // cancelled server-side; the connection remains usable
+    } else if (err.name === 'AbortError') {
+        // the signal was already aborted — the query was never sent
+    } else {
+        throw err;
+    }
+}
+```
+
+The option works with the callback API as well (`db.query(sql, params, cb,
+{ signal })`) and on transaction-level queries. A running operation can also
+be cancelled manually from anywhere with `db.cancel()` / `await
+db.cancelAsync()`.
+
+Notes:
+
+- Cancellation is **per attachment** (that is how the Firebird protocol
+  defines it): it cancels whatever is currently executing on that
+  connection. With a pool this is naturally scoped to the request holding
+  the connection.
+- A signal that is already aborted rejects immediately with an `AbortError`
+  without contacting the server; cancelling an idle connection is harmless.
+
+### Batch Execution (Firebird 4.0+)
+
+`executeBatch` sends many parameter rows for one statement in a single
+round-trip using the Firebird 4 wire batch API (`op_batch_create` /
+`op_batch_msg` / `op_batch_exec`) — typically 5–10× faster than executing
+row by row. Available on the database, transaction and statement objects, in
+callback and promise flavours.
+
+```js
+const rows = [
+    [1, 'Alice', 10.50, new Date(), true,  100n],
+    [2, 'Bob',   null,  new Date(), false, null],   // NULLs per column
+    [3, 'Carol', 7.25,  new Date(), true,  300n],
+];
+
+// database level: own transaction, all-or-nothing (rollback if any record fails)
+const res = await db.executeBatchAsync(
+    'INSERT INTO t (id, name, amount, created, active, big) VALUES (?, ?, ?, ?, ?, ?)',
+    rows);
+console.log(res.recordCount, res.updateCounts, res.success);
+
+// transaction level: partial success — failed records are reported,
+// the rest can still be committed
+const tr = await db.transactionAsync();
+const r = await tr.executeBatchAsync('INSERT INTO t (...) VALUES (?, ?, ?, ?, ?, ?)', rows);
+if (!r.success) {
+    console.log('failed record indexes:', r.errorRecordNumbers);   // 0-based
+    console.log('first error:', r.errors[0].error.message);
+}
+await tr.commitAsync();
+```
+
+The result object contains `recordCount`, `updateCounts` (one entry per
+record), `errors` (`{ recordNumber, error }` with full gdscode details),
+`errorRecordNumbers` and `success`. At the database level a failed batch
+rejects with the first record error, carrying the full completion state as
+`err.batchCompletion`.
+
+Options (last argument): `chunkSize` (rows per `op_batch_msg` packet,
+default 500), `multiError` (default `true` — collect all record errors
+instead of stopping at the first), `bufferSize` (server-side batch buffer
+in bytes).
+
+Notes:
+
+- Requires wire protocol 16+ (Firebird 4.0 or newer server).
+- 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.
+- Oversized `CHAR`/`VARCHAR` values fail the batch client-side before
+  anything is sent; server-side record errors (constraint violations,
+  truncation…) are reported per record.
+
 ### Statement Timeouts (Firebird 4.0+)
 Setting a statement timeout allows the client to automatically abort queries that take too long on the server.
 ```js

package/lib/types.d.ts

@@ -64,9 +64,44 @@ export type TransactionOptions = {
     wait?: boolean;
     waitTimeout?: number;
 };
+/** Result of an executeBatch call (Firebird 4 batch API, protocol 16+). */
+export interface BatchResult {
+    /** Total number of records processed by the server. */
+    recordCount: number;
+    /** Per-record update counts (in record order). */
+    updateCounts: number[];
+    /** Per-record failures with full status vectors (capped by `detailedErrors`). */
+    errors: Array<{
+        recordNumber: number;
+        error: Error;
+    }>;
+    /** Record numbers of ALL failed records (detailed + status-less). */
+    errorRecordNumbers: number[];
+    /** True when every record executed without error. */
+    success: boolean;
+}
+export type BatchOptions = {
+    /** Continue past per-record errors and report them all (default true). */
+    multiError?: boolean;
+    /** Server-side batch buffer limit in bytes (BATCH_TAG_BUFFER_BYTES_SIZE). */
+    bufferSize?: number;
+    /** Max number of detailed per-record status vectors returned (server default 64). */
+    detailedErrors?: number;
+    /** Rows per op_batch_msg packet (default 500). */
+    chunkSize?: number;
+};
 export type QueryOptions = {
     timeout?: number;
     scrollable?: boolean;
+    /**
+     * Abort the query when the signal fires (Firebird 2.5+ / protocol 12+).
+     * If the signal is already aborted the query is not sent at all and the
+     * callback/promise fails with an `AbortError`. If it fires mid-flight an
+     * out-of-band op_cancel is sent and the query fails with
+     * `err.gdscode === GDSCode.CANCELLED`. Cancellation is per-attachment:
+     * it cancels whatever is currently executing on the connection.
+     */
+    signal?: AbortSignal;
 };
 export interface Database {
     detach(callback?: SimpleCallback): Database;
@@ -74,6 +109,8 @@ export interface Database {
     newStatement(query: string, callback: (err: Error | null, statement: Statement) => void): Database;
     query(query: string, params: any[], callback: QueryCallback, options?: QueryOptions): Database;
     execute(query: string, params: any[], callback: QueryCallback, options?: QueryOptions): Database;
+    /** Bulk-execute in its own transaction, all-or-nothing (Firebird 4.0+). */
+    executeBatch(query: string, rows: any[][], callback?: (err: any, result: BatchResult) => void, options?: BatchOptions): Database;
     sequentially(query: string, params: any[], rowCallback: SequentialCallback, callback: SimpleCallback, options?: QueryOptions | boolean): Database;
     drop(callback: SimpleCallback): void;
     escape(value: any): string;
@@ -84,6 +121,7 @@ export interface Database {
     createSchema(schemaName: string, tablespaceName?: string | QueryCallback, callback?: QueryCallback): Database;
     queryAsync<T = any>(query: string, params?: any[], options?: QueryOptions): Promise<T[]>;
     executeAsync<T = any>(query: string, params?: any[], options?: QueryOptions): Promise<T[]>;
+    executeBatchAsync(query: string, rows: any[][], options?: BatchOptions): Promise<BatchResult>;
     sequentiallyAsync(query: string, params: any[] | undefined, rowCallback: SequentialCallback, options?: QueryOptions | boolean): Promise<void>;
     sequentiallyAsync(query: string, rowCallback: SequentialCallback, options?: QueryOptions | boolean): Promise<void>;
     transactionAsync(options?: TransactionOptions | Isolation): Promise<Transaction>;
@@ -94,11 +132,21 @@ export interface Database {
     attachEventAsync(): Promise<any>;
     /** Starts a transaction, commits when `work` resolves, rolls back when it rejects. */
     withTransaction<T>(work: (transaction: Transaction) => Promise<T> | T, options?: TransactionOptions | Isolation): Promise<T>;
+    /**
+     * Cancel the operation currently executing on this connection
+     * (Firebird 2.5+ / protocol 12+). The cancelled operation fails through
+     * its own callback/promise with `err.gdscode === GDSCode.CANCELLED`.
+     */
+    cancel(callback?: SimpleCallback): Database;
+    cancel(kind: number, callback?: SimpleCallback): Database;
+    cancelAsync(kind?: number): Promise<void>;
 }
 export interface Transaction {
     newStatement(query: string, callback: (err: Error | null, statement: Statement) => void): void;
     query(query: string, params: any[], callback: QueryCallback, options?: QueryOptions): void;
     execute(query: string, params: any[], callback: QueryCallback, options?: QueryOptions): void;
+    /** Bulk-execute within this transaction; per-record failures do not roll back (Firebird 4.0+). */
+    executeBatch(query: string, rows: any[][], callback?: (err: any, result: BatchResult) => void, options?: BatchOptions): void;
     sequentially(query: string, params: any[], rowCallback: SequentialCallback, callback: SimpleCallback, options?: QueryOptions | boolean): Database;
     commit(callback?: SimpleCallback): void;
     commitRetaining(callback?: SimpleCallback): void;
@@ -106,6 +154,7 @@ export interface Transaction {
     rollbackRetaining(callback?: SimpleCallback): void;
     queryAsync<T = any>(query: string, params?: any[], options?: QueryOptions): Promise<T[]>;
     executeAsync<T = any>(query: string, params?: any[], options?: QueryOptions): Promise<T[]>;
+    executeBatchAsync(query: string, rows: any[][], options?: BatchOptions): Promise<BatchResult>;
     sequentiallyAsync(query: string, params: any[] | undefined, rowCallback: SequentialCallback, options?: QueryOptions | boolean): Promise<void>;
     sequentiallyAsync(query: string, rowCallback: SequentialCallback, options?: QueryOptions | boolean): Promise<void>;
     newStatementAsync(query: string): Promise<Statement>;
@@ -122,7 +171,10 @@ export interface Statement {
     fetch(transaction: Transaction, count: number, callback: QueryCallback): void;
     fetchScroll(transaction: Transaction, direction: 'NEXT' | 'PRIOR' | 'FIRST' | 'LAST' | 'ABSOLUTE' | 'RELATIVE' | number, offset: number, count: number, callback: QueryCallback): void;
     fetchAll(transaction: Transaction, callback: QueryCallback): void;
+    /** Execute this prepared statement once per row (Firebird 4.0+ batch API). */
+    executeBatch(transaction: Transaction, rows: any[][], callback?: (err: any, result: BatchResult) => void, options?: BatchOptions): void;
     executeAsync(transaction: Transaction, params?: any[], options?: QueryOptions): Promise<any>;
+    executeBatchAsync(transaction: Transaction, rows: any[][], options?: BatchOptions): Promise<BatchResult>;
     fetchAsync(transaction: Transaction, count: number | 'all'): Promise<any>;
     fetchScrollAsync(transaction: Transaction, direction: 'NEXT' | 'PRIOR' | 'FIRST' | 'LAST' | 'ABSOLUTE' | 'RELATIVE' | number, offset?: number, count?: number): Promise<any>;
     fetchAllAsync(transaction: Transaction): Promise<any>;

package/lib/wire/connection.d.ts

@@ -57,6 +57,15 @@ declare class Connection {
     sendOpContAuth(authData: any, authDataEnc: any, pluginName: any): void;
     sendOpCrypt(encryptPlugin: any): void;
     sendOpCryptKeyCallback(pluginData: any): void;
+    /**
+     * Send an out-of-band op_cancel packet (protocol 12+ / Firebird 2.5+).
+     * The server reads it asynchronously while an operation is executing and
+     * makes that operation fail with isc_cancelled (GDSCode.CANCELLED); the
+     * op_cancel packet itself has no response, so nothing is queued here.
+     */
+    cancelOperation(kind: any, callback: any): this;
+    /** Write a prebuilt packet and queue its response callback. */
+    _queueEventBuffer(buffer: any, callback: any): void;
     _queueEvent(callback: any, defer?: boolean): void;
     connect(options: any, callback: any): void;
     attach(options: any, callback?: any, db?: any): void;
@@ -75,6 +84,19 @@ declare class Connection {
     allocateAndPrepareStatement(transaction: any, query: any, plan: any, callback: any): void;
     prepare(transaction: any, query: any, plan: any, callback: any): void;
     prepareStatement(transaction: any, statement: any, query: any, plan: any, callback: any): this;
+    /**
+     * Execute a statement once per row using the Firebird 4 batch API
+     * (protocol 16+): op_batch_create + op_batch_msg(s) + op_batch_exec +
+     * op_batch_rls, all pipelined in a single network flush. Every packet
+     * 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 }.
+     */
+    executeBatch(transaction: any, statement: any, rows: any, callback: any, options: any): this;
     executeStatement(transaction: any, statement: any, params: any, callback: any, custom: any): this;
     sendExecute(op: number, statement: any, transaction: any, callback: any, parameters?: any[]): void;
     fetch(statement: any, transaction: any, count: any, callback: any): void;