node-firebird 2.4.2 → 2.5.0

package/README.md

@@ -10,6 +10,7 @@
 
 - [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
@@ -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
 
@@ -1230,6 +1280,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

@@ -82,6 +82,18 @@ 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>;
 }
 export interface Transaction {
     newStatement(query: string, callback: (err: Error | null, statement: Statement) => void): void;
@@ -92,6 +104,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 +122,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 +216,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.js

@@ -1823,16 +1823,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 +1921,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/database.d.ts

@@ -53,5 +53,20 @@ 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>;
+    /**
+     * 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

@@ -377,5 +377,71 @@ 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); });
+    }
+    /**
+     * 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;

package/lib/wire/statement.js

@@ -4,6 +4,7 @@
  *   Statement
  *
  ***************************************/
+const callback_1 = require("../callback");
 class Statement {
     constructor(connection) {
         this.connection = connection;
@@ -48,5 +49,34 @@ class Statement {
     fetchAll(transaction, callback) {
         this.connection.fetchAll(this, transaction, callback);
     }
+    /* Promise / async-await API — wrappers over the callback methods above. */
+    executeAsync(transaction, params, options) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.execute(transaction, params, cb, options); });
+    }
+    fetchAsync(transaction, count) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.fetch(transaction, count, cb); });
+    }
+    fetchScrollAsync(transaction, direction, offset, count) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.fetchScroll(transaction, direction, offset, count, cb); });
+    }
+    fetchAllAsync(transaction) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.fetchAll(transaction, cb); });
+    }
+    closeAsync() {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.close(cb); });
+    }
+    dropAsync() {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.drop(cb); });
+    }
+    releaseAsync() {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.release(cb); });
+    }
 }
 module.exports = Statement;

package/lib/wire/transaction.d.ts

@@ -17,5 +17,13 @@ declare class Transaction {
     rollback(callback?: (err?: any) => void): void;
     commitRetaining(callback?: (err?: any) => void): void;
     rollbackRetaining(callback?: (err?: any) => void): void;
+    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>;
+    newStatementAsync(query: string): Promise<any>;
+    commitAsync(): Promise<void>;
+    rollbackAsync(): Promise<void>;
+    commitRetainingAsync(): Promise<void>;
+    rollbackRetainingAsync(): Promise<void>;
 }
 export = Transaction;

package/lib/wire/transaction.js

@@ -174,5 +174,43 @@ class Transaction {
     rollbackRetaining(callback) {
         this.connection.rollbackRetaining(this, callback);
     }
+    /* Promise / async-await API — wrappers over the callback methods above. */
+    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); });
+    }
+    newStatementAsync(query) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.newStatement(query, cb); });
+    }
+    commitAsync() {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.commit(cb); });
+    }
+    rollbackAsync() {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.rollback(cb); });
+    }
+    commitRetainingAsync() {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.commitRetaining(cb); });
+    }
+    rollbackRetainingAsync() {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.rollbackRetaining(cb); });
+    }
 }
 module.exports = Transaction;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "node-firebird",
-    "version": "2.4.2",
+    "version": "2.5.0",
     "description": "Pure JavaScript and Asynchronous Firebird client for Node.js.",
     "keywords": [
         "firebird",

package/src/callback.ts

@@ -20,6 +20,42 @@ 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 function toError(err: any): Error {
+    if (err instanceof Error)
+        return err;
+
+    var error: FbError = 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))
+ */
+export function fromCallback<T = any>(executor: (cb: Callback<T>) => void): Promise<T> {
+    return new Promise<T>(function(resolve, reject) {
+        executor(function(err?: any, result?: T) {
+            if (err)
+                reject(toError(err));
+            else
+                resolve(result as T);
+        });
+    });
+}
+
 export function doError(obj: any, callback?: (...args: any[]) => void): void {
     if (callback)
         callback(obj)

package/src/index.ts

@@ -1,5 +1,5 @@
 import Const from './wire/const';
-import { doError, doCallback } from './callback';
+import { doError, doCallback, fromCallback } from './callback';
 import Connection from './wire/connection';
 import Pool from './pool';
 import { escape as escapeValue } from './utils';
@@ -10,6 +10,8 @@ import type {
     ServiceManagerCallback,
     SimpleCallback,
     ConnectionPool,
+    Database,
+    ServiceManager,
 } from './types';
 
 export * from './types';
@@ -155,3 +157,28 @@ export function attachOrCreate(options: Options, callback: DatabaseCallback): vo
 export function pool(max: number, options: Options): ConnectionPool {
 	return new Pool(attach, max, Object.assign({}, options, { isPool: true }));
 }
+
+/*
+ * Promise / async-await API.
+ * Wrappers over the callback functions above; the callback API stays
+ * untouched. Rejections are always Error instances carrying the usual
+ * Firebird properties (gdscode, gdsparams, ...).
+ */
+
+export function attachAsync(options: SvcMgrOptions): Promise<ServiceManager>;
+export function attachAsync(options: Options): Promise<Database>;
+export function attachAsync(options: any): Promise<any> {
+    return fromCallback(function(cb) { attach(options, cb); });
+}
+
+export function createAsync(options: Options): Promise<Database> {
+    return fromCallback(function(cb) { create(options, cb); });
+}
+
+export function attachOrCreateAsync(options: Options): Promise<Database> {
+    return fromCallback(function(cb) { attachOrCreate(options, cb); });
+}
+
+export function dropAsync(options: Options): Promise<void> {
+    return fromCallback(function(cb) { drop(options, cb); });
+}

package/src/pool.ts

@@ -4,6 +4,7 @@
  *
  ***************************************/
 
+import { fromCallback } from './callback';
 import type { Callback } from './callback';
 
 type AttachFn = (options: any, callback: Callback) => void;
@@ -204,6 +205,33 @@ class Pool {
             }
         });
     }
+
+    /* Promise / async-await API — wrappers over the callback methods above. */
+
+    getAsync(): Promise<any> {
+        var self = this;
+        return fromCallback(function(cb) { self.get(cb); });
+    }
+
+    destroyAsync(): Promise<void> {
+        var self = this;
+        return 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<T>(work: (db: any) => Promise<T> | T): Promise<T> {
+        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<void>(function(resolve) { db.detach(function() { resolve(); }); });
+        }
+    }
 }
 
 export = Pool;

package/src/types.ts

@@ -94,6 +94,21 @@ 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;
+
+    // Promise / async-await API (see README § Promises / async–await).
+    // Result metadata is only available through the callback API.
+    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>;
 }
 
 export interface Transaction {
@@ -105,6 +120,17 @@ export interface Transaction {
     commitRetaining(callback?: SimpleCallback): void;
     rollback(callback?: SimpleCallback): void;
     rollbackRetaining(callback?: SimpleCallback): void;
+
+    // Promise / async-await API
+    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 {
@@ -115,6 +141,15 @@ 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;
+
+    // Promise / async-await API
+    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 = |
@@ -240,6 +275,12 @@ export interface SvcMgrOptions extends Options {
 export interface ConnectionPool {
     get(callback: DatabaseCallback): void;
     destroy(callback?: SimpleCallback): void;
+
+    // Promise / async-await API
+    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 {

package/src/wire/connection.ts

@@ -2185,12 +2185,13 @@ function decodeResponse(data: any, callback: any, cnx: any, lowercase_keys: any,
                                 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(
@@ -2203,8 +2204,11 @@ function decodeResponse(data: any, callback: any, cnx: any, lowercase_keys: any,
                                 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);
@@ -2309,12 +2313,13 @@ function decodeResponse(data: any, callback: any, cnx: any, lowercase_keys: any,
                         };
                         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(

package/src/wire/database.ts

@@ -1,5 +1,5 @@
 import Events from 'events';
-import { doError } from '../callback';
+import { doError, fromCallback } from '../callback';
 import { escape } from '../utils';
 import Const from './const';
 import EventConnection from './eventConnection';
@@ -439,6 +439,81 @@ class Database extends Events.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: string, params?: any, options?: any): Promise<any[]> {
+        var self = this;
+        return fromCallback(function(cb) { self.query(query, params, cb, options); });
+    }
+
+    executeAsync(query: string, params?: any, options?: any): Promise<any[]> {
+        var self = this;
+        return fromCallback(function(cb) { self.execute(query, params, cb, options); });
+    }
+
+    sequentiallyAsync(query: string, params?: any, on?: any, options?: any): Promise<void> {
+        if (params instanceof Function) {
+            options = on;
+            on = params;
+            params = undefined;
+        }
+        var self = this;
+        return fromCallback(function(cb) { self.sequentially(query, params, on, cb, options); });
+    }
+
+    transactionAsync(options?: any): Promise<any> {
+        var self = this;
+        return fromCallback(function(cb) { self.startTransaction(options, cb); });
+    }
+
+    startTransactionAsync(options?: any): Promise<any> {
+        return this.transactionAsync(options);
+    }
+
+    newStatementAsync(query: string): Promise<any> {
+        var self = this;
+        return fromCallback(function(cb) { self.newStatement(query, cb); });
+    }
+
+    detachAsync(force?: boolean): Promise<void> {
+        var self = this;
+        return fromCallback(function(cb) { self.detach(cb, force); });
+    }
+
+    dropAsync(): Promise<void> {
+        var self = this;
+        return fromCallback(function(cb) { self.drop(cb); });
+    }
+
+    attachEventAsync(): Promise<any> {
+        var self = this;
+        return fromCallback(function(cb) { self.attachEvent(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<T>(work: (transaction: any) => Promise<T> | T, options?: any): Promise<T> {
+        const transaction = await this.transactionAsync(options);
+        try {
+            const result = await work(transaction);
+            await fromCallback(function(cb) { transaction.commit(cb); });
+            return result;
+        } catch (err) {
+            try {
+                await fromCallback(function(cb) { transaction.rollback(cb); });
+            } catch { /* surface the original error, not the rollback failure */ }
+            throw err;
+        }
+    }
 }
 
 export = Database;

package/src/wire/statement.ts

@@ -4,6 +4,8 @@
  *
  ***************************************/
 
+import { fromCallback } from '../callback';
+
 class Statement {
     connection: any;
     query: string;
@@ -66,6 +68,43 @@ class Statement {
     fetchAll(transaction: any, callback: (err: any, result?: any) => void): void {
         this.connection.fetchAll(this, transaction, callback);
     }
+
+    /* Promise / async-await API — wrappers over the callback methods above. */
+
+    executeAsync(transaction: any, params?: any, options?: any): Promise<any> {
+        var self = this;
+        return fromCallback(function(cb) { self.execute(transaction, params, cb, options); });
+    }
+
+    fetchAsync(transaction: any, count: number | string): Promise<any> {
+        var self = this;
+        return fromCallback(function(cb) { self.fetch(transaction, count, cb); });
+    }
+
+    fetchScrollAsync(transaction: any, direction: string | number, offset?: any, count?: any): Promise<any> {
+        var self = this;
+        return fromCallback(function(cb) { self.fetchScroll(transaction, direction, offset, count, cb); });
+    }
+
+    fetchAllAsync(transaction: any): Promise<any> {
+        var self = this;
+        return fromCallback(function(cb) { self.fetchAll(transaction, cb); });
+    }
+
+    closeAsync(): Promise<void> {
+        var self = this;
+        return fromCallback(function(cb) { self.close(cb); });
+    }
+
+    dropAsync(): Promise<void> {
+        var self = this;
+        return fromCallback(function(cb) { self.drop(cb); });
+    }
+
+    releaseAsync(): Promise<void> {
+        var self = this;
+        return fromCallback(function(cb) { self.release(cb); });
+    }
 }
 
 export = Statement;

package/src/wire/transaction.ts

@@ -1,4 +1,4 @@
-import { doCallback, doError } from '../callback';
+import { doCallback, doError, fromCallback } from '../callback';
 import { noop } from '../utils';
 import Const from './const';
 
@@ -207,6 +207,53 @@ class Transaction {
     rollbackRetaining(callback?: (err?: any) => void): void {
         this.connection.rollbackRetaining(this, callback);
     }
+
+    /* Promise / async-await API — wrappers over the callback methods above. */
+
+    queryAsync(query: string, params?: any, options?: any): Promise<any[]> {
+        var self = this;
+        return fromCallback(function(cb) { self.query(query, params, cb, options); });
+    }
+
+    executeAsync(query: string, params?: any, options?: any): Promise<any[]> {
+        var self = this;
+        return fromCallback(function(cb) { self.execute(query, params, cb, options); });
+    }
+
+    sequentiallyAsync(query: string, params?: any, on?: any, options?: any): Promise<void> {
+        if (params instanceof Function) {
+            options = on;
+            on = params;
+            params = undefined;
+        }
+        var self = this;
+        return fromCallback(function(cb) { self.sequentially(query, params, on, cb, options); });
+    }
+
+    newStatementAsync(query: string): Promise<any> {
+        var self = this;
+        return fromCallback(function(cb) { self.newStatement(query, cb); });
+    }
+
+    commitAsync(): Promise<void> {
+        var self = this;
+        return fromCallback(function(cb) { self.commit(cb); });
+    }
+
+    rollbackAsync(): Promise<void> {
+        var self = this;
+        return fromCallback(function(cb) { self.rollback(cb); });
+    }
+
+    commitRetainingAsync(): Promise<void> {
+        var self = this;
+        return fromCallback(function(cb) { self.commitRetaining(cb); });
+    }
+
+    rollbackRetainingAsync(): Promise<void> {
+        var self = this;
+        return fromCallback(function(cb) { self.rollbackRetaining(cb); });
+    }
 }
 
 export = Transaction;