node-firebird 2.4.2 → 2.6.0

package/README.md

@@ -10,10 +10,11 @@
 
 - [Installation](#installation)
 - [Usage](#usage) — including [developing the driver](#developing-the-driver)
+- [Promises and async/await](#promises-and-asyncawait) — the `*Async` API plus `withConnection` / `withTransaction` helpers
 - [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), 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)
@@ -98,6 +99,55 @@ npm test           # build + run the vitest suite (unit + integration)
 - `Firebird.create(options, function(err, db))` create a database
 - `Firebird.attachOrCreate(options, function(err, db))` attach or create database
 - `Firebird.pool(max, options) -> return {Object}` create a connection pooling
+- `Firebird.attachAsync(options) -> Promise<Database>`, `createAsync`, `attachOrCreateAsync`, `dropAsync` — promise counterparts, see [Promises and async/await](#promises-and-asyncawait)
+
+## Promises and async/await
+
+Every callback API has a promise-returning counterpart with an `Async`
+suffix, plus two higher-level helpers: `pool.withConnection()` and
+`db.withTransaction()`. The callback API is unchanged and the two styles can
+be mixed freely, though sticking to one per project keeps code readable.
+
+```js
+const Firebird = require('node-firebird');
+
+const pool = Firebird.pool(5, options);
+
+// acquire → work → always release, even when `work` throws
+const users = await pool.withConnection((db) =>
+    db.queryAsync('SELECT id, name FROM users WHERE plan = ?', ['pro'])
+);
+
+// commit on success, rollback on error
+await pool.withConnection((db) =>
+    db.withTransaction(async (transaction) => {
+        await transaction.executeAsync('INSERT INTO audit (msg) VALUES (?)', ['signup']);
+        await transaction.executeAsync('UPDATE stats SET signups = signups + 1');
+    })
+);
+
+await pool.destroyAsync();
+```
+
+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`
+
+Notes:
+
+- Rejections are always `Error` instances carrying the usual Firebird
+  properties (`err.gdscode`, `err.gdsparams`) — see [Using GDS codes](#using-gds-codes).
+- `queryAsync` / `executeAsync` resolve with the rows only; column metadata
+  is currently available through the callback API only.
+- An un-`await`ed rejected promise becomes an unhandled rejection instead of
+  a callback error — prefer the `withConnection` / `withTransaction` helpers,
+  which guarantee cleanup on every path.
+- TypeScript: the async methods accept a row-shape generic, e.g.
+  `db.queryAsync<User>(sql, params)` returns `Promise<User[]>`.
 
 ## Connection types
 
@@ -1101,6 +1151,47 @@ 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.
+
 ### Statement Timeouts (Firebird 4.0+)
 Setting a statement timeout allows the client to automatically abort queries that take too long on the server.
 ```js
@@ -1230,6 +1321,8 @@ process.on('SIGTERM', function() {
 
 node-firebird works well with Express, but because the driver is connection/pool based rather than an ORM with automatic connection management, a few request-lifecycle patterns keep connections from leaking under load. This section documents the recommended architecture, referenced from the [roadmap](ROADMAP.md#2-expressjs-support-first-class-integration).
 
+> The driver now ships native `pool.withConnection()` and `db.withTransaction()` helpers (see [Promises and async/await](#promises-and-asyncawait)) that supersede the hand-rolled `withConnection` / `transactional` helpers shown in the examples below. The examples remain valid and show what the helpers do under the hood.
+
 ### Recommended architecture: one pool per app, created at startup
 
 Create a single `Firebird.pool(...)` when the app boots and reuse it for the lifetime of the process. Do **not** call `Firebird.pool()` or `Firebird.attach()` inside a request handler — that opens a new socket (or an entire new pool) on every request and will exhaust server and database resources under load.

package/lib/callback.d.ts

@@ -16,5 +16,18 @@ export interface FbError extends Error {
 }
 export type SimpleCallback = (err?: any) => void;
 export type Callback<T = any> = (err?: any, result?: T) => void;
+/**
+ * Normalize the values the driver passes as the callback error argument.
+ * Most code paths already deliver Error instances, but a few older ones
+ * pass plain objects (status vectors, `{error, message}` wrappers).  A
+ * Promise must reject with an Error, so wrap those while preserving all
+ * their properties (gdscode, gdsparams, status, sqlcode, ...).
+ */
+export declare function toError(err: any): Error;
+/**
+ * Run a callback-style operation and return a Promise for its result.
+ * Usage: fromCallback<Database>(cb => attach(options, cb))
+ */
+export declare function fromCallback<T = any>(executor: (cb: Callback<T>) => void): Promise<T>;
 export declare function doError(obj: any, callback?: (...args: any[]) => void): void;
 export declare function doCallback<T>(obj: T, callback?: Callback<T>): void;

package/lib/callback.js

@@ -1,7 +1,38 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.toError = toError;
+exports.fromCallback = fromCallback;
 exports.doError = doError;
 exports.doCallback = doCallback;
+/**
+ * Normalize the values the driver passes as the callback error argument.
+ * Most code paths already deliver Error instances, but a few older ones
+ * pass plain objects (status vectors, `{error, message}` wrappers).  A
+ * Promise must reject with an Error, so wrap those while preserving all
+ * their properties (gdscode, gdsparams, status, sqlcode, ...).
+ */
+function toError(err) {
+    if (err instanceof Error)
+        return err;
+    var error = new Error(err != null && typeof err === 'object' && err.message ? err.message : String(err));
+    if (err != null && typeof err === 'object')
+        Object.assign(error, err);
+    return error;
+}
+/**
+ * Run a callback-style operation and return a Promise for its result.
+ * Usage: fromCallback<Database>(cb => attach(options, cb))
+ */
+function fromCallback(executor) {
+    return new Promise(function (resolve, reject) {
+        executor(function (err, result) {
+            if (err)
+                reject(toError(err));
+            else
+                resolve(result);
+        });
+    });
+}
 function doError(obj, callback) {
     if (callback)
         callback(obj);

package/lib/index.d.ts

@@ -1,6 +1,6 @@
 import Connection from './wire/connection';
 import { escape as escapeValue } from './utils';
-import type { Options, SvcMgrOptions, DatabaseCallback, ServiceManagerCallback, SimpleCallback, ConnectionPool } from './types';
+import type { Options, SvcMgrOptions, DatabaseCallback, ServiceManagerCallback, SimpleCallback, ConnectionPool, Database, ServiceManager } from './types';
 export * from './types';
 export { GDSCode } from './gdscodes';
 export declare const AUTH_PLUGIN_LEGACY: string;
@@ -35,3 +35,8 @@ export declare function drop(options: Options, callback: SimpleCallback): void;
 export declare function create(options: Options, callback: DatabaseCallback): void;
 export declare function attachOrCreate(options: Options, callback: DatabaseCallback): void;
 export declare function pool(max: number, options: Options): ConnectionPool;
+export declare function attachAsync(options: SvcMgrOptions): Promise<ServiceManager>;
+export declare function attachAsync(options: Options): Promise<Database>;
+export declare function createAsync(options: Options): Promise<Database>;
+export declare function attachOrCreateAsync(options: Options): Promise<Database>;
+export declare function dropAsync(options: Options): Promise<void>;

package/lib/index.js

@@ -23,6 +23,10 @@ exports.drop = drop;
 exports.create = create;
 exports.attachOrCreate = attachOrCreate;
 exports.pool = pool;
+exports.attachAsync = attachAsync;
+exports.createAsync = createAsync;
+exports.attachOrCreateAsync = attachOrCreateAsync;
+exports.dropAsync = dropAsync;
 const const_1 = __importDefault(require("./wire/const"));
 const callback_1 = require("./callback");
 const connection_1 = __importDefault(require("./wire/connection"));
@@ -137,3 +141,15 @@ function attachOrCreate(options, callback) {
 function pool(max, options) {
     return new pool_1.default(attach, max, Object.assign({}, options, { isPool: true }));
 }
+function attachAsync(options) {
+    return (0, callback_1.fromCallback)(function (cb) { attach(options, cb); });
+}
+function createAsync(options) {
+    return (0, callback_1.fromCallback)(function (cb) { create(options, cb); });
+}
+function attachOrCreateAsync(options) {
+    return (0, callback_1.fromCallback)(function (cb) { attachOrCreate(options, cb); });
+}
+function dropAsync(options) {
+    return (0, callback_1.fromCallback)(function (cb) { drop(options, cb); });
+}

package/lib/pool.d.ts

@@ -19,5 +19,12 @@ declare class Pool {
     get(callback: Callback): this;
     check(): this;
     destroy(callback?: (err?: any) => void): void;
+    getAsync(): Promise<any>;
+    destroyAsync(): Promise<void>;
+    /**
+     * Run `work` with a connection from the pool, returning it to the pool
+     * (detach) when the returned promise settles — success or failure.
+     */
+    withConnection<T>(work: (db: any) => Promise<T> | T): Promise<T>;
 }
 export = Pool;

package/lib/pool.js

@@ -4,6 +4,7 @@
  *   Simple Pooling
  *
  ***************************************/
+const callback_1 = require("./callback");
 class Pool {
     constructor(attach, max, options) {
         this.attach = attach;
@@ -178,5 +179,29 @@ class Pool {
             }
         });
     }
+    /* Promise / async-await API — wrappers over the callback methods above. */
+    getAsync() {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.get(cb); });
+    }
+    destroyAsync() {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.destroy(cb); });
+    }
+    /**
+     * Run `work` with a connection from the pool, returning it to the pool
+     * (detach) when the returned promise settles — success or failure.
+     */
+    async withConnection(work) {
+        const db = await this.getAsync();
+        try {
+            return await work(db);
+        }
+        finally {
+            // A pooled detach only returns the connection to the pool; do not
+            // let a detach hiccup mask the outcome of `work`.
+            await new Promise(function (resolve) { db.detach(function () { resolve(); }); });
+        }
+    }
 }
 module.exports = Pool;

package/lib/types.d.ts

@@ -67,6 +67,15 @@ export type TransactionOptions = {
 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;
@@ -82,6 +91,26 @@ 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?: any[], options?: QueryOptions): Promise<T[]>;
+    executeAsync<T = any>(query: string, params?: any[], options?: QueryOptions): Promise<T[]>;
+    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>;
+    startTransactionAsync(options?: TransactionOptions | Isolation): Promise<Transaction>;
+    newStatementAsync(query: string): Promise<Statement>;
+    detachAsync(force?: boolean): Promise<void>;
+    dropAsync(): Promise<void>;
+    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;
@@ -92,6 +121,15 @@ export interface Transaction {
     commitRetaining(callback?: SimpleCallback): void;
     rollback(callback?: SimpleCallback): void;
     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[]>;
+    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>;
+    commitAsync(): Promise<void>;
+    commitRetainingAsync(): Promise<void>;
+    rollbackAsync(): Promise<void>;
+    rollbackRetainingAsync(): Promise<void>;
 }
 export interface Statement {
     close(callback?: SimpleCallback): void;
@@ -101,6 +139,13 @@ 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;
+    executeAsync(transaction: Transaction, params?: any[], options?: QueryOptions): Promise<any>;
+    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>;
+    closeAsync(): Promise<void>;
+    dropAsync(): Promise<void>;
+    releaseAsync(): Promise<void>;
 }
 export type SupportedCharacterSet = 'NONE' | 'CP943C' | 'DOS737' | 'DOS775' | 'DOS858' | 'DOS862' | 'DOS864' | 'DOS866' | 'DOS869' | 'GB18030' | 'GBK' | 'ISO8859_1' | 'ISO8859_2' | 'ISO8859_3' | 'ISO8859_4' | 'ISO8859_5' | 'ISO8859_6' | 'ISO8859_7' | 'ISO8859_8' | 'ISO8859_9' | 'ISO8859_13' | 'KOI8R' | 'KOI8U' | 'TIS620' | 'UTF8' | 'WIN1251' | 'WIN1252' | 'WIN1253' | 'WIN1254' | 'WIN1255' | 'WIN1256' | 'WIN1257' | 'WIN1258' | 'WIN_1258';
 export interface Options {
@@ -188,6 +233,10 @@ export interface SvcMgrOptions extends Options {
 export interface ConnectionPool {
     get(callback: DatabaseCallback): void;
     destroy(callback?: SimpleCallback): void;
+    getAsync(): Promise<Database>;
+    destroyAsync(): Promise<void>;
+    /** Acquire a connection, run `work`, always return the connection to the pool. */
+    withConnection<T>(work: (db: Database) => Promise<T> | T): Promise<T>;
 }
 export interface ReadableOptions {
     optread?: 'byline' | 'buffer';

package/lib/wire/connection.d.ts

@@ -57,6 +57,13 @@ 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;
     _queueEvent(callback: any, defer?: boolean): void;
     connect(options: any, callback: any): void;
     attach(options: any, callback?: any, db?: any): void;

package/lib/wire/connection.js

@@ -294,6 +294,32 @@ class Connection {
         msg.addBlr(pluginData); // Send the callback response data as a buffer
         this._socket.write(msg.getData());
     }
+    /**
+     * 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, callback) {
+        if (typeof kind === 'function') {
+            callback = kind;
+            kind = undefined;
+        }
+        kind = kind || const_1.default.fb_cancel_raise;
+        if (this._isClosed)
+            return this.throwClosed(callback);
+        if (!this.accept || this.accept.protocolVersion < const_1.default.PROTOCOL_VERSION12) {
+            (0, callback_1.doError)(new Error('Query cancellation requires protocol 12+ (Firebird 2.5 or newer)'), callback);
+            return;
+        }
+        var msg = this._msg;
+        msg.pos = 0;
+        msg.addInt(const_1.default.op_cancel);
+        msg.addInt(kind);
+        this._socket.write(msg.getData());
+        if (callback)
+            callback();
+    }
     _queueEvent(callback, defer = false) {
         var self = this;
         if (self._isClosed) {
@@ -1823,16 +1849,20 @@ function decodeResponse(data, callback, cnx, lowercase_keys, cb) {
                                 public: BigInt('0x' + d.buffer.slice(keyStart, d.buffer.length).toString('utf8')),
                                 pluginName: accept.pluginName
                             };
-                            console.log('--- DEBUG SRP Handshake ---');
-                            console.log('salt:', cnx.serverKeys.salt);
-                            console.log('server public key:', cnx.serverKeys.public.toString(16));
-                            console.log('client public key:', cnx.clientKeys.public.toString(16));
-                            console.log('client private key:', cnx.clientKeys.private.toString(16));
-                            console.log('hashAlgo:', accept.srpAlgo);
+                            if (process.env.FIREBIRD_DEBUG) {
+                                console.log('--- DEBUG SRP Handshake ---');
+                                console.log('salt:', cnx.serverKeys.salt);
+                                console.log('server public key:', cnx.serverKeys.public.toString(16));
+                                console.log('client public key:', cnx.clientKeys.public.toString(16));
+                                console.log('hashAlgo:', accept.srpAlgo);
+                            }
                             const _t1 = Date.now();
                             var proof = srp.clientProof(cnx.options.user.toUpperCase(), cnx.options.password, cnx.serverKeys.salt, cnx.clientKeys.public, cnx.serverKeys.public, cnx.clientKeys.private, accept.srpAlgo);
-                            console.log('client proof M1:', proof.authData.toString(16));
-                            console.log('client session key K:', proof.clientSessionKey.toString(16));
+                            if (process.env.FIREBIRD_DEBUG) {
+                                // Never log the private key or the session key: the
+                                // session key is the wire-encryption key material.
+                                console.log('client proof M1:', proof.authData.toString(16));
+                            }
                             if (process.env.FIREBIRD_DEBUG) {
                                 console.log('[fb-debug] srp.clientProof(%s): %dms', accept.srpAlgo, Date.now() - _t1);
                             }
@@ -1917,12 +1947,13 @@ function decodeResponse(data, callback, cnx, lowercase_keys, cb) {
                             Srp512: 'sha512'
                         };
                         var srpAlgo = crypto[pluginName];
-                        console.log('--- DEBUG SRP Handshake ---');
-                        console.log('salt:', cnx.serverKeys.salt);
-                        console.log('server public key:', cnx.serverKeys.public.toString(16));
-                        console.log('client public key:', cnx.clientKeys.public.toString(16));
-                        console.log('client private key:', cnx.clientKeys.private.toString(16));
-                        console.log('hashAlgo:', srpAlgo);
+                        if (process.env.FIREBIRD_DEBUG) {
+                            console.log('--- DEBUG SRP Handshake ---');
+                            console.log('salt:', cnx.serverKeys.salt);
+                            console.log('server public key:', cnx.serverKeys.public.toString(16));
+                            console.log('client public key:', cnx.clientKeys.public.toString(16));
+                            console.log('hashAlgo:', srpAlgo);
+                        }
                         const _t1 = Date.now();
                         var proof = srp.clientProof(cnx.options.user.toUpperCase(), cnx.options.password, cnx.serverKeys.salt, cnx.clientKeys.public, cnx.serverKeys.public, cnx.clientKeys.private, srpAlgo);
                         if (process.env.FIREBIRD_DEBUG) {

package/lib/wire/const.d.ts

@@ -104,6 +104,10 @@ declare const Const: Readonly<{
     DSQL_close: number;
     DSQL_drop: number;
     DSQL_unprepare: number;
+    fb_cancel_disable: number;
+    fb_cancel_enable: number;
+    fb_cancel_raise: number;
+    fb_cancel_abort: number;
     fetch_next: number;
     fetch_prior: number;
     fetch_first: number;

package/lib/wire/const.js

@@ -117,6 +117,13 @@ const dsql = {
     DSQL_drop: 2,
     DSQL_unprepare: 4, // >: 2.5
 };
+// fb_cancel_operation kinds sent with op_cancel (protocol 12+ / Firebird 2.5+)
+const cancelKind = {
+    fb_cancel_disable: 1, // disable execution of fb_cancel_raise requests
+    fb_cancel_enable: 2, // re-enable delivery of cancel requests
+    fb_cancel_raise: 3, // cancel the operation currently executing on the attachment
+    fb_cancel_abort: 4, // forcibly abort the attachment's current activity
+};
 const fetchOp = {
     fetch_next: 0,
     fetch_prior: 1,
@@ -794,6 +801,7 @@ const Const = Object.freeze({
     ...blr,
     ...blobType,
     ...buffer,
+    ...cancelKind,
     ...cnct,
     ...common,
     ...connect,

package/lib/wire/database.d.ts

@@ -12,6 +12,14 @@ declare class Database extends Events.EventEmitter {
     sequentially(query: string, params?: any, on?: any, callback?: any, options?: any): this;
     query(query: string, params?: any, callback?: any, options?: any): this;
     drop(callback?: (err?: any) => void): void;
+    /**
+     * Cancel the operation currently executing on this connection by sending
+     * an out-of-band op_cancel (Firebird 2.5+ / protocol 12+). The cancelled
+     * operation fails through its own callback with err.gdscode ===
+     * GDSCode.CANCELLED. `kind` defaults to fb_cancel_raise; cancellation is
+     * per-attachment, not per-statement.
+     */
+    cancel(kind?: number | ((err?: any) => void), callback?: (err?: any) => void): this;
     attachEvent(callback: (err: any, evt?: any) => void): this;
     /**
      * Create a physical tablespace.
@@ -53,5 +61,21 @@ declare class Database extends Events.EventEmitter {
      * @returns {Database}
      */
     createSchema(schemaName: string, tablespaceName?: string | ((err?: any) => void), callback?: any): this;
+    queryAsync(query: string, params?: any, options?: any): Promise<any[]>;
+    executeAsync(query: string, params?: any, options?: any): Promise<any[]>;
+    sequentiallyAsync(query: string, params?: any, on?: any, options?: any): Promise<void>;
+    transactionAsync(options?: any): Promise<any>;
+    startTransactionAsync(options?: any): Promise<any>;
+    newStatementAsync(query: string): Promise<any>;
+    detachAsync(force?: boolean): Promise<void>;
+    dropAsync(): Promise<void>;
+    attachEventAsync(): Promise<any>;
+    cancelAsync(kind?: number): Promise<void>;
+    /**
+     * Run `work` inside a transaction: commits when the returned promise
+     * resolves, rolls back when it rejects (the original error is rethrown,
+     * even if the rollback itself fails).
+     */
+    withTransaction<T>(work: (transaction: any) => Promise<T> | T, options?: any): Promise<T>;
 }
 export = Database;

package/lib/wire/database.js

@@ -273,6 +273,21 @@ class Database extends events_1.default.EventEmitter {
     drop(callback) {
         return this.connection.dropDatabase(callback);
     }
+    /**
+     * Cancel the operation currently executing on this connection by sending
+     * an out-of-band op_cancel (Firebird 2.5+ / protocol 12+). The cancelled
+     * operation fails through its own callback with err.gdscode ===
+     * GDSCode.CANCELLED. `kind` defaults to fb_cancel_raise; cancellation is
+     * per-attachment, not per-statement.
+     */
+    cancel(kind, callback) {
+        if (typeof kind === 'function') {
+            callback = kind;
+            kind = undefined;
+        }
+        this.connection.cancelOperation(kind, callback);
+        return this;
+    }
     attachEvent(callback) {
         var self = this;
         const eventid = self.eventid++;
@@ -377,5 +392,75 @@ class Database extends events_1.default.EventEmitter {
         }
         return this.execute(sql, [], callback);
     }
+    /*
+     * Promise / async-await API.
+     * Each *Async method wraps its callback counterpart; the callback API
+     * stays untouched. Result metadata is only available through the
+     * callback API — the promises resolve with the rows alone.
+     */
+    queryAsync(query, params, options) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.query(query, params, cb, options); });
+    }
+    executeAsync(query, params, options) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.execute(query, params, cb, options); });
+    }
+    sequentiallyAsync(query, params, on, options) {
+        if (params instanceof Function) {
+            options = on;
+            on = params;
+            params = undefined;
+        }
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.sequentially(query, params, on, cb, options); });
+    }
+    transactionAsync(options) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.startTransaction(options, cb); });
+    }
+    startTransactionAsync(options) {
+        return this.transactionAsync(options);
+    }
+    newStatementAsync(query) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.newStatement(query, cb); });
+    }
+    detachAsync(force) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.detach(cb, force); });
+    }
+    dropAsync() {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.drop(cb); });
+    }
+    attachEventAsync() {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.attachEvent(cb); });
+    }
+    cancelAsync(kind) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.cancel(kind, cb); });
+    }
+    /**
+     * Run `work` inside a transaction: commits when the returned promise
+     * resolves, rolls back when it rejects (the original error is rethrown,
+     * even if the rollback itself fails).
+     */
+    async withTransaction(work, options) {
+        const transaction = await this.transactionAsync(options);
+        try {
+            const result = await work(transaction);
+            await (0, callback_1.fromCallback)(function (cb) { transaction.commit(cb); });
+            return result;
+        }
+        catch (err) {
+            try {
+                await (0, callback_1.fromCallback)(function (cb) { transaction.rollback(cb); });
+            }
+            catch { /* surface the original error, not the rollback failure */ }
+            throw err;
+        }
+    }
 }
 module.exports = Database;

package/lib/wire/statement.d.ts

@@ -21,5 +21,12 @@ declare class Statement {
     fetch(transaction: any, count: number | string, callback: (err: any, result?: any) => void): void;
     fetchScroll(transaction: any, direction: string | number, offset?: any, count?: any, callback?: any): void;
     fetchAll(transaction: any, callback: (err: any, result?: any) => void): void;
+    executeAsync(transaction: any, params?: any, options?: any): Promise<any>;
+    fetchAsync(transaction: any, count: number | string): Promise<any>;
+    fetchScrollAsync(transaction: any, direction: string | number, offset?: any, count?: any): Promise<any>;
+    fetchAllAsync(transaction: any): Promise<any>;
+    closeAsync(): Promise<void>;
+    dropAsync(): Promise<void>;
+    releaseAsync(): Promise<void>;
 }
 export = Statement;