node-firebird 2.9.0 → 2.11.0

package/lib/wire/xsqlvar.d.ts

@@ -21,21 +21,60 @@ export declare abstract class SQLVarBase {
     abstract decode(data: XdrReader, lowerV13: boolean, options?: any): any;
     abstract calcBlr(blr: BlrWriter): void;
 }
+/** Effective object-row key(s) of one output column (see computeColumnKeys). */
+export interface ColumnKey {
+    /** Top-level table key when nestTables === true; undefined otherwise. */
+    table?: string;
+    /** Property key: the column alias, or 'table<sep>alias' in separator mode. */
+    key: string;
+}
+/**
+ * Compute the object-row property keys for a statement's output columns,
+ * honouring the nestTables and lowercase_keys options. The table qualifier
+ * is the query's relation alias when one is used (relationAlias, requested
+ * via isc_info_sql_relation_alias), the relation name otherwise, so
+ * self-joins nest under their query aliases. Expression columns (no source
+ * relation) qualify as '' exactly like mysql2: they nest under the '' key,
+ * and in separator mode become '<sep>alias' — always prefixing keeps
+ * qualified keys collision-free (a bare expression alias could otherwise
+ * collide with a real column's 'table<sep>column' key). Used by the fetch
+ * decoder and by fetchBlobSyncRow, which must agree on where each column
+ * landed in the row.
+ */
+export declare function computeColumnKeys(output: SQLVarBase[], nestTables: boolean | string | undefined, lowercaseKeys: boolean | undefined): ColumnKey[];
+/**
+ * Resolve the effective nestTables value: the per-query option wins over
+ * the connection option. The decoder and fetchBlobSyncRow both use this —
+ * they must agree on whether nesting is active or blob cells are looked
+ * up in the wrong place.
+ */
+export declare function resolveNestTables(queryOptions: {
+    nestTables?: boolean | string;
+} | undefined, connectionOptions: {
+    nestTables?: boolean | string;
+} | undefined): boolean | string | undefined;
+/**
+ * The object a column's value lives in: the row itself, or — when the
+ * column carries a nestTables table qualifier — the row's per-table
+ * sub-object, created on first use. Every site that reads or writes a
+ * cell by ColumnKey must resolve it through here.
+ */
+export declare function nestCell(row: any, table: string | undefined): any;
 export declare class SQLVarText extends SQLVarBase {
-    decode(data: XdrReader, lowerV13: boolean, options?: any): any;
+    decode(data: XdrReader, lowerV13: boolean, options?: any): string | Buffer<ArrayBufferLike> | null | undefined;
     calcBlr(blr: BlrWriter): void;
 }
 export declare class SQLVarNull extends SQLVarText {
 }
 export declare class SQLVarString extends SQLVarBase {
-    decode(data: XdrReader, lowerV13: boolean, options?: any): any;
+    decode(data: XdrReader, lowerV13: boolean, options?: any): string | Buffer<ArrayBufferLike> | null | undefined;
     calcBlr(blr: BlrWriter): void;
 }
 export declare class SQLVarQuad extends SQLVarBase {
     decode(data: XdrReader, lowerV13: boolean): {
         low: number;
         high: number;
-    };
+    } | null;
     calcBlr(blr: BlrWriter): void;
 }
 export declare class SQLVarBlob extends SQLVarQuad {
@@ -45,66 +84,66 @@ export declare class SQLVarArray extends SQLVarQuad {
     calcBlr(blr: BlrWriter): void;
 }
 export declare class SQLVarInt extends SQLVarBase {
-    decode(data: XdrReader, lowerV13: boolean): number;
+    decode(data: XdrReader, lowerV13: boolean): number | null;
     calcBlr(blr: BlrWriter): void;
 }
 export declare class SQLVarShort extends SQLVarInt {
     calcBlr(blr: BlrWriter): void;
 }
 export declare class SQLVarInt64 extends SQLVarBase {
-    decode(data: XdrReader, lowerV13: boolean): number;
+    decode(data: XdrReader, lowerV13: boolean): number | null;
     calcBlr(blr: BlrWriter): void;
 }
 export declare class SQLVarInt128 extends SQLVarBase {
-    decode(data: XdrReader, lowerV13: boolean): string | number;
+    decode(data: XdrReader, lowerV13: boolean): string | number | null;
     calcBlr(blr: BlrWriter): void;
 }
 export declare class SQLVarDecFloat16 extends SQLVarBase {
-    decode(data: XdrReader, lowerV13: boolean): string | number;
+    decode(data: XdrReader, lowerV13: boolean): string | number | null;
     calcBlr(blr: BlrWriter): void;
 }
 export declare class SQLVarDecFloat34 extends SQLVarBase {
-    decode(data: XdrReader, lowerV13: boolean): string | number;
+    decode(data: XdrReader, lowerV13: boolean): string | number | null;
     calcBlr(blr: BlrWriter): void;
 }
 export declare class SQLVarFloat extends SQLVarBase {
-    decode(data: XdrReader, lowerV13: boolean): number;
+    decode(data: XdrReader, lowerV13: boolean): number | null;
     calcBlr(blr: BlrWriter): void;
 }
 export declare class SQLVarDouble extends SQLVarBase {
-    decode(data: XdrReader, lowerV13: boolean): number;
+    decode(data: XdrReader, lowerV13: boolean): number | null;
     calcBlr(blr: BlrWriter): void;
 }
 export declare class SQLVarDate extends SQLVarBase {
-    decode(data: XdrReader, lowerV13: boolean): Date;
+    decode(data: XdrReader, lowerV13: boolean): Date | null;
     calcBlr(blr: BlrWriter): void;
 }
 export declare class SQLVarTime extends SQLVarBase {
-    decode(data: XdrReader, lowerV13: boolean): Date;
+    decode(data: XdrReader, lowerV13: boolean): Date | null;
     calcBlr(blr: BlrWriter): void;
 }
 export declare class SQLVarTimeStamp extends SQLVarBase {
-    decode(data: XdrReader, lowerV13: boolean): Date;
+    decode(data: XdrReader, lowerV13: boolean): Date | null;
     calcBlr(blr: BlrWriter): void;
 }
 export declare class SQLVarTimeTz extends SQLVarBase {
-    decode(data: XdrReader, lowerV13: boolean): Date;
+    decode(data: XdrReader, lowerV13: boolean): Date | null;
     calcBlr(blr: BlrWriter): void;
 }
 export declare class SQLVarTimeTzEx extends SQLVarTimeTz {
-    decode(data: XdrReader, lowerV13: boolean): Date;
+    decode(data: XdrReader, lowerV13: boolean): Date | null;
     calcBlr(blr: BlrWriter): void;
 }
 export declare class SQLVarTimeStampTz extends SQLVarBase {
-    decode(data: XdrReader, lowerV13: boolean): Date;
+    decode(data: XdrReader, lowerV13: boolean): Date | null;
     calcBlr(blr: BlrWriter): void;
 }
 export declare class SQLVarTimeStampTzEx extends SQLVarTimeStampTz {
-    decode(data: XdrReader, lowerV13: boolean): Date;
+    decode(data: XdrReader, lowerV13: boolean): Date | null;
     calcBlr(blr: BlrWriter): void;
 }
 export declare class SQLVarBoolean extends SQLVarBase {
-    decode(data: XdrReader, lowerV13: boolean): boolean;
+    decode(data: XdrReader, lowerV13: boolean): boolean | null;
     calcBlr(blr: BlrWriter): void;
 }
 export declare class SQLParamInt {

package/lib/wire/xsqlvar.js

@@ -4,6 +4,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SQLParamBool = exports.SQLParamDate = exports.SQLParamQuad = exports.SQLParamBuffer = exports.SQLParamString = exports.SQLParamDouble = exports.SQLParamDecFloat34 = exports.SQLParamDecFloat16 = exports.SQLParamInt128 = exports.SQLParamInt64 = exports.SQLParamInt = exports.SQLVarBoolean = exports.SQLVarTimeStampTzEx = exports.SQLVarTimeStampTz = exports.SQLVarTimeTzEx = exports.SQLVarTimeTz = exports.SQLVarTimeStamp = exports.SQLVarTime = exports.SQLVarDate = exports.SQLVarDouble = exports.SQLVarFloat = exports.SQLVarDecFloat34 = exports.SQLVarDecFloat16 = exports.SQLVarInt128 = exports.SQLVarInt64 = exports.SQLVarShort = exports.SQLVarInt = exports.SQLVarArray = exports.SQLVarBlob = exports.SQLVarQuad = exports.SQLVarString = exports.SQLVarNull = exports.SQLVarText = exports.SQLVarBase = void 0;
+exports.computeColumnKeys = computeColumnKeys;
+exports.resolveNestTables = resolveNestTables;
+exports.nestCell = nestCell;
 exports.encodeDateTimeParts = encodeDateTimeParts;
 const const_1 = __importDefault(require("./const"));
 /***************************************
@@ -68,6 +71,62 @@ function resolveTextEncoding(options) {
 class SQLVarBase {
 }
 exports.SQLVarBase = SQLVarBase;
+/**
+ * Compute the object-row property keys for a statement's output columns,
+ * honouring the nestTables and lowercase_keys options. The table qualifier
+ * is the query's relation alias when one is used (relationAlias, requested
+ * via isc_info_sql_relation_alias), the relation name otherwise, so
+ * self-joins nest under their query aliases. Expression columns (no source
+ * relation) qualify as '' exactly like mysql2: they nest under the '' key,
+ * and in separator mode become '<sep>alias' — always prefixing keeps
+ * qualified keys collision-free (a bare expression alias could otherwise
+ * collide with a real column's 'table<sep>column' key). Used by the fetch
+ * decoder and by fetchBlobSyncRow, which must agree on where each column
+ * landed in the row.
+ */
+function computeColumnKeys(output, nestTables, lowercaseKeys) {
+    return output.map((column) => {
+        let key = column.alias || '';
+        if (lowercaseKeys) {
+            key = key.toLowerCase();
+        }
+        if (nestTables !== true && typeof nestTables !== 'string') {
+            return { key };
+        }
+        let table = column.relationAlias || column.relation || '';
+        if (lowercaseKeys) {
+            table = table.toLowerCase();
+        }
+        if (nestTables === true) {
+            return { table, key };
+        }
+        return { key: table + nestTables + key };
+    });
+}
+/**
+ * Resolve the effective nestTables value: the per-query option wins over
+ * the connection option. The decoder and fetchBlobSyncRow both use this —
+ * they must agree on whether nesting is active or blob cells are looked
+ * up in the wrong place.
+ */
+function resolveNestTables(queryOptions, connectionOptions) {
+    if (queryOptions && queryOptions.nestTables !== undefined) {
+        return queryOptions.nestTables;
+    }
+    return connectionOptions && connectionOptions.nestTables;
+}
+/**
+ * The object a column's value lives in: the row itself, or — when the
+ * column carries a nestTables table qualifier — the row's per-table
+ * sub-object, created on first use. Every site that reads or writes a
+ * cell by ColumnKey must resolve it through here.
+ */
+function nestCell(row, table) {
+    if (table === undefined) {
+        return row;
+    }
+    return row[table] || (row[table] = {});
+}
 //------------------------------------------------------
 class SQLVarText extends SQLVarBase {
     decode(data, lowerV13, options) {

package/package.json

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

package/src/index.ts

@@ -1,5 +1,5 @@
 import Const from './wire/const';
-import { doError, doCallback, fromCallback } from './callback';
+import { doError, doCallback, fromCallback, type Callback } from './callback';
 import Connection from './wire/connection';
 import Pool from './pool';
 import { escape as escapeValue } from './utils';
@@ -48,6 +48,36 @@ export const ISOLATION_READ_COMMITTED_READ_ONLY: number[] = Const.ISOLATION_READ
 
 export const escape = escapeValue;
 
+/**
+ * Firebird SQL type codes, as seen in `column.type` inside a `typeCast`
+ * hook (each code also has a friendly `column.typeName`).
+ */
+export const SQL_TYPES: Readonly<Record<string, number>> = Object.freeze({
+    SQL_TEXT: Const.SQL_TEXT,
+    SQL_VARYING: Const.SQL_VARYING,
+    SQL_SHORT: Const.SQL_SHORT,
+    SQL_LONG: Const.SQL_LONG,
+    SQL_FLOAT: Const.SQL_FLOAT,
+    SQL_DOUBLE: Const.SQL_DOUBLE,
+    SQL_D_FLOAT: Const.SQL_D_FLOAT,
+    SQL_TIMESTAMP: Const.SQL_TIMESTAMP,
+    SQL_BLOB: Const.SQL_BLOB,
+    SQL_ARRAY: Const.SQL_ARRAY,
+    SQL_QUAD: Const.SQL_QUAD,
+    SQL_TYPE_TIME: Const.SQL_TYPE_TIME,
+    SQL_TYPE_DATE: Const.SQL_TYPE_DATE,
+    SQL_INT64: Const.SQL_INT64,
+    SQL_INT128: Const.SQL_INT128,
+    SQL_TIMESTAMP_TZ: Const.SQL_TIMESTAMP_TZ,
+    SQL_TIMESTAMP_TZ_EX: Const.SQL_TIMESTAMP_TZ_EX,
+    SQL_TIME_TZ: Const.SQL_TIME_TZ,
+    SQL_TIME_TZ_EX: Const.SQL_TIME_TZ_EX,
+    SQL_DEC16: Const.SQL_DEC16,
+    SQL_DEC34: Const.SQL_DEC34,
+    SQL_BOOLEAN: Const.SQL_BOOLEAN,
+    SQL_NULL: Const.SQL_NULL,
+});
+
 /**
  * The most recent Connection created by attach()/create()/attachOrCreate().
  * Kept for backwards compatibility with the previous CommonJS module where
@@ -114,7 +144,7 @@ export function create(options: Options | string, callback: DatabaseCallback): v
                 return;
             }
 
-            cnx.createDatabase(options, callback);
+            cnx.createDatabase(options, callback as any);
         });
     }, options);
 }
@@ -146,11 +176,13 @@ export function attachOrCreate(options: Options | string, callback: DatabaseCall
                 if (!err) {
                     if (self.db)
                         self.db.emit('connect', ret);
-                    doCallback(ret, callback);
+                    // DatabaseCallback stays permissive (db non-optional) for
+                    // API users; internally the error path passes no db
+                    doCallback(ret, callback as Callback<Database>);
                     return;
                 }
 
-                cnx.createDatabase(options, callback);
+                cnx.createDatabase(options, callback as any);
             });
         });
 

package/src/messages.ts

@@ -138,7 +138,7 @@ export const lookupMessages = function(status: FbStatusItem[], messageFile: stri
             buffer = Buffer.alloc(bucket_size);
 
             var i = 0;
-            var text;
+            var text: string | undefined;
 
             function loop() {
                 lookup(status[i], function(line) {

package/src/pool.ts

@@ -161,7 +161,7 @@ class Pool extends Events.EventEmitter {
         if ((self.dbinuse + self._creating) >= self.max)
             return self;
 
-        var cb = self.pending.shift();
+        const cb = self.pending.shift();
         if (!cb)
             return self;
         if (self.pooldb.length) {

package/src/srp.ts

@@ -67,7 +67,7 @@ export function clientSeed(a: bigint = toBigInt(crypto.randomBytes(SRP_KEY_SIZE)
  * @param b BigInt Server private key.
  * @returns {{private: BigInt, public: BigInt}}
  */
-export function serverSeed(user: string, password: string, salt: Buffer, b?: bigint | string, hashAlgo: string = 'sha1'): KeyPair {
+export function serverSeed(user: string, password: string, salt: Buffer | string, b?: bigint | string, hashAlgo: string = 'sha1'): KeyPair {
     if (typeof b === 'string') {
         hashAlgo = b;
         b = undefined;
@@ -104,7 +104,7 @@ export function serverSeed(user: string, password: string, salt: Buffer, b?: big
  * @param b BigInt Server private key.
  * @returns {BigInt}
  */
-export function serverSession(user: string, password: string, salt: Buffer, A: bigint, B: bigint, b: bigint, hashAlgo: string = 'sha1'): bigint {
+export function serverSession(user: string, password: string, salt: Buffer | string, A: bigint, B: bigint, b: bigint, hashAlgo: string = 'sha1'): bigint {
     var u = getScramble(A, B, 'sha1');
     var v = getVerifier(user, password, salt, 'sha1');
     var vu = modPow(v, u, PRIME.N);
@@ -121,7 +121,7 @@ export function serverSession(user: string, password: string, salt: Buffer, A: b
 /**
  * M = H(H(N) xor H(g), H(I), s, A, B, K)
  */
-export function clientProof(user: string, password: string, salt: Buffer, A: bigint, B: bigint, a: bigint, hashAlgo: string = 'sha1'): ClientProof {
+export function clientProof(user: string, password: string, salt: Buffer | string, A: bigint, B: bigint, a: bigint, hashAlgo: string = 'sha1'): ClientProof {
     var K = clientSession(user, password, salt, A, B, a, 'sha1');
     var n1, n2;
 
@@ -222,7 +222,7 @@ function getScramble(A: bigint, B: bigint, hashAlgo: string = 'sha1'): bigint {
  * @returns Buffer The raw session-key digest (fixed length, may start
  *                 with a zero byte — significant for the proof).
  */
-function clientSession(user: string, password: string, salt: Buffer, A: bigint, B: bigint, a: bigint, hashAlgo: string = 'sha1'): Buffer {
+function clientSession(user: string, password: string, salt: Buffer | string, A: bigint, B: bigint, a: bigint, hashAlgo: string = 'sha1'): Buffer {
     var u = getScramble(A, B, 'sha1');
     var x = getUserHash(user, salt, password, 'sha1');
     var gx = modPow(PRIME.g, x, PRIME.N);
@@ -264,7 +264,7 @@ function clientSession(user: string, password: string, salt: Buffer, A: bigint,
  * @param password string Connection password.
  * @returns {BigInt}
  */
-function getUserHash(user: string, salt: Buffer, password: string, hashAlgo: string = 'sha1'): bigint {
+function getUserHash(user: string, salt: Buffer | string, password: string, hashAlgo: string = 'sha1'): bigint {
     var hash1 = getHash(hashAlgo, user.toUpperCase(), ':', password);
     var hash2 = getHash(hashAlgo, salt, toBuffer(hash1));
 
@@ -279,7 +279,7 @@ function getUserHash(user: string, salt: Buffer, password: string, hashAlgo: str
  * @param salt  BigInt Connection salt.
  * @returns {BigInt}
  */
-function getVerifier(user: string, password: string, salt: Buffer, hashAlgo: string = 'sha1'): bigint {
+function getVerifier(user: string, password: string, salt: Buffer | string, hashAlgo: string = 'sha1'): bigint {
     return modPow(PRIME.g, getUserHash(user, salt, password, hashAlgo), PRIME.N);
 }
 

package/src/types.ts

@@ -5,6 +5,8 @@
 // They now live in the TypeScript source tree and are compiled into the
 // published declaration files.
 
+import type { Readable } from 'stream';
+
 export type DatabaseCallback = (err: any, db: Database) => void;
 export type TransactionCallback = (err: any, transaction: Transaction) => void;
 export type QueryCallback = (err: any, result: any[]) => void;
@@ -125,6 +127,28 @@ export type QueryOptions = {
      * it cancels whatever is currently executing on the connection.
      */
     signal?: AbortSignal;
+    /**
+     * Per-query override of the `nestTables` connection option (mysql2
+     * semantics). `true` nests each object row by source table:
+     * `row[table][column]` — the table key is the query's relation alias
+     * when one is used (`FROM emp e` → `row.E`), the table name otherwise,
+     * and `''` for expression columns. A string separator flattens keys
+     * instead: `nestTables: '_'` → `row.EMP_NAME`; expression columns get
+     * the bare separator prefix (`row._ANSWER`, as in mysql2). Keys honour
+     * `lowercase_keys`. Object rows only — `db.execute` array rows are
+     * unaffected.
+     */
+    nestTables?: boolean | string;
+}
+
+export type QueryStreamOptions = QueryOptions & {
+    /**
+     * Rows buffered internally before fetching pauses (object-mode
+     * Readable highWaterMark, default 16).
+     */
+    highWaterMark?: number;
+    /** Emit array rows instead of objects (like db.execute). */
+    asObject?: boolean;
 }
 
 export interface Database {
@@ -136,6 +160,13 @@ export interface Database {
     /** Bulk-execute in its own transaction, all-or-nothing (Firebird 4.0+). */
     executeBatch(query: string, rows: QueryParams[], callback?: (err: any, result: BatchResult) => void, options?: BatchOptions): Database;
     sequentially(query: string, params: QueryParams, rowCallback: SequentialCallback, callback: SimpleCallback, options?: QueryOptions | boolean): Database;
+    /**
+     * Run `query` and return an object-mode Readable emitting one row per
+     * chunk, with backpressure (fetching pauses while the buffer is full).
+     * Runs in its own transaction. Destroying the stream early aborts the
+     * fetch and releases the statement.
+     */
+    queryStream(query: string, params?: QueryParams, options?: QueryStreamOptions): Readable;
     drop(callback: SimpleCallback): void;
     escape(value: any): string;
     attachEvent(callback: any): this;
@@ -176,6 +207,12 @@ export interface Transaction {
     /** Bulk-execute within this transaction; per-record failures do not roll back (Firebird 4.0+). */
     executeBatch(query: string, rows: QueryParams[], callback?: (err: any, result: BatchResult) => void, options?: BatchOptions): void;
     sequentially(query: string, params: QueryParams, rowCallback: SequentialCallback, callback: SimpleCallback, options?: QueryOptions | boolean): Database;
+    /**
+     * Run `query` inside this transaction and return an object-mode
+     * Readable emitting one row per chunk, with backpressure. The
+     * transaction is NOT committed when the stream ends.
+     */
+    queryStream(query: string, params?: QueryParams, options?: QueryStreamOptions): Readable;
     commit(callback?: SimpleCallback): void;
     commitRetaining(callback?: SimpleCallback): void;
     rollback(callback?: SimpleCallback): void;
@@ -289,6 +326,26 @@ export interface Options {
      * per-query `namedPlaceholders: false` override.
      */
     namedPlaceholders?: boolean;
+    /**
+     * Qualify object-row keys by source table (same option as mysql2), so
+     * JOINed columns with the same name stop overwriting each other:
+     * `true` nests each row as `row[table][column]`; a string separator
+     * flattens to `row['table' + sep + 'column']`. See
+     * `QueryOptions.nestTables` for the exact key rules. Applies wherever
+     * object rows are produced (query / sequentially / queryStream);
+     * array rows (execute) are unaffected. Overridable per query.
+     */
+    nestTables?: boolean | string;
+    /**
+     * TCP keepalive probing to detect dead/stale connections (same option
+     * names as mysql2). On by default; set false to disable.
+     */
+    enableKeepAlive?: boolean;
+    /**
+     * Milliseconds a socket must be idle before the first TCP keepalive
+     * probe is sent (default 60000). Ignored when enableKeepAlive is false.
+     */
+    keepAliveInitialDelay?: number;
     pluginName?: string;
     parallelWorkers?: number;
     maxInlineBlobSize?: number;
@@ -320,11 +377,11 @@ export interface Options {
     /**
      * **Firebird 6.0+ only (Protocol 20+)**
      *
-     * Sets the session's current schema at connection time.  Equivalent to
-     * executing `SET SCHEMA <name>` immediately after connecting.
-     *
-     * Unqualified object references (tables, procedures, etc.) that do not
-     * match any schema in the `searchPath` fall back to `PUBLIC`.
+     * Sets the session's current schema at connection time. `CURRENT_SCHEMA`
+     * in Firebird is the first existing schema of the search path, so this
+     * option is implemented by putting the schema at the front of the
+     * `searchPath` sent to the server (with `PUBLIC` kept as a fallback when
+     * no explicit `searchPath` is given).
      *
      * Example: `defaultSchema: 'myapp'`
      */
@@ -346,6 +403,18 @@ export interface Options {
      * (typically `PUBLIC` then `SYSTEM`).
      */
     searchPath?: string | string[];
+    /**
+     * **Firebird 6.0+ only**
+     *
+     * Owner of a newly created database (`isc_dpb_owner`), allowing a
+     * superuser to create a database owned by another user
+     * ([firebird#7718](https://github.com/FirebirdSQL/firebird/issues/7718)).
+     * Only honored by `create`/`attachOrCreate` when the database is
+     * created; ignored on plain attach and by older servers.
+     *
+     * Example: `owner: 'APP_OWNER'`
+     */
+    owner?: string;
     /**
      * **Firebird 6.0+ only (Protocol 20+)**
      *
@@ -354,8 +423,58 @@ export interface Options {
      * text/BLOB columns back into JavaScript objects/arrays.
      */
     jsonAsObject?: boolean;
+    /**
+     * Custom type parser (mysql2-style). Called for every column value of
+     * every result row (including NULLs); whatever it returns becomes the
+     * value in the row. Call `next()` to get the value the driver would
+     * produce by default (after `blobAsText`/`jsonAsObject` are applied).
+     *
+     * ```js
+     * typeCast: (column, next) =>
+     *     column.typeName === 'INT64' ? Number(next()) : next()
+     * ```
+     *
+     * Non-text BLOB columns reach the hook as the usual fetch function;
+     * text BLOBs with `blobAsText` reach it as the resolved string. The
+     * hook must be a pure function: a row can be decoded more than once
+     * when a response spans TCP packets.
+     */
+    typeCast?: TypeCastFunction;
+    /**
+     * Per-connection LRU cache of prepared statements (like mysql2's
+     * statement cache). `db.query`/`tx.query` and friends transparently
+     * reuse the prepared handle for a repeated SQL string, skipping the
+     * prepare round-trip on hot paths. The number is the maximum of idle
+     * cached statements; least-recently-used ones are dropped over the
+     * limit. 0 / unset = disabled. Statements that failed and DDL are
+     * never cached; concurrent runs of the same SQL never share a
+     * statement (extra preparations are simply not cached).
+     */
+    statementCacheSize?: number;
 }
 
+/** Column metadata passed to the {@link Options.typeCast} hook. */
+export interface TypeCastColumn {
+    /** Firebird SQL type code (see the exported `SQL_TYPES` map). */
+    type: number;
+    /** Friendly name of the type code: 'VARYING', 'INT64', 'BLOB', ... */
+    typeName: string;
+    /** Column subtype (e.g. 1 = text for BLOBs; charset id for strings). */
+    subType?: number;
+    /** Negative decimal scale for NUMERIC/DECIMAL columns (e.g. -2). */
+    scale?: number;
+    /** Declared length in bytes. */
+    length?: number;
+    /** Column name in the table. */
+    field?: string;
+    /** Table (relation) name. */
+    relation?: string;
+    /** Alias used in the SELECT list (the row key for object rows). */
+    alias?: string;
+}
+
+export type TypeCastFunction = (column: TypeCastColumn, next: () => any) => any;
+
 export interface SvcMgrOptions extends Options {
     manager: true; // Attach to ServiceManager
 }
@@ -565,4 +684,42 @@ export interface ServiceManager {
     hasRunningAction(options: ReadableOptions, callback: ReadableCallback): void;
     readusers(options: ReadableOptions, callback: ReadableCallback): void;
     readlimbo(options: ReadableOptions, callback: ReadableCallback): void;
+
+    // Promise / async-await API (see README § Promises / async–await).
+    detachAsync(force?: boolean): Promise<void>;
+    backupAsync(options: BackupOptions): Promise<NodeJS.ReadableStream>;
+    nbackupAsync(options: BackupOptions): Promise<NodeJS.ReadableStream>;
+    restoreAsync(options: RestoreOptions): Promise<NodeJS.ReadableStream>;
+    nrestoreAsync(options: NRestoreOptions): Promise<NodeJS.ReadableStream>;
+    setDialectAsync(db: string, dialect: 1 | 3): Promise<NodeJS.ReadableStream>;
+    setSweepintervalAsync(db: string, interval: number): Promise<any>;
+    setCachebufferAsync(db: string, nbpages: any): Promise<NodeJS.ReadableStream>;
+    BringOnlineAsync(db: string): Promise<NodeJS.ReadableStream>;
+    ShutdownAsync(db: string, kind: ShutdownKind, delay: number, mode?: ShutdownMode): Promise<NodeJS.ReadableStream>;
+    setShadowAsync(db: string, val: boolean): Promise<NodeJS.ReadableStream>;
+    setForcewriteAsync(db: string, val: boolean): Promise<NodeJS.ReadableStream>;
+    setReservespaceAsync(db: string, val: boolean): Promise<NodeJS.ReadableStream>;
+    setReadonlyModeAsync(db: string): Promise<NodeJS.ReadableStream>;
+    setReadwriteModeAsync(db: string): Promise<NodeJS.ReadableStream>;
+    validateAsync(options: ValidateOptions): Promise<NodeJS.ReadableStream>;
+    commitAsync(db: string, transactid: number): Promise<NodeJS.ReadableStream>;
+    rollbackAsync(db: string, transactid: number): Promise<NodeJS.ReadableStream>;
+    recoverAsync(db: string, transactid: number): Promise<NodeJS.ReadableStream>;
+    getStatsAsync(options: StatsOptions): Promise<NodeJS.ReadableStream>;
+    getLogAsync(options: ReadableOptions): Promise<NodeJS.ReadableStream>;
+    getUsersAsync(username?: string | null): Promise<ServerInfo>;
+    addUserAsync(username: string, password: string, info?: UserInfo): Promise<NodeJS.ReadableStream>;
+    editUserAsync(username: string, info: UserInfo): Promise<NodeJS.ReadableStream>;
+    removeUserAsync(username: string, rolename?: string | null): Promise<NodeJS.ReadableStream>;
+    getFbserverInfosAsync(infos?: ServerInfoReq, options?: { buffersize?: number, timeout?: number }): Promise<ServerInfo>;
+    startTraceAsync(options: TraceOptions): Promise<NodeJS.ReadableStream>;
+    suspendTraceAsync(options: TraceOptions): Promise<NodeJS.ReadableStream>;
+    resumeTraceAsync(options: TraceOptions): Promise<NodeJS.ReadableStream>;
+    stopTraceAsync(options: TraceOptions): Promise<NodeJS.ReadableStream>;
+    getTraceListAsync(options?: ReadableOptions): Promise<NodeJS.ReadableStream>;
+    readlineAsync(options?: ReadableOptions): Promise<{ result: number, line: string }>;
+    readeofAsync(options?: ReadableOptions): Promise<{ result: number, line: string }>;
+    hasRunningActionAsync(options?: ReadableOptions): Promise<any>;
+    readusersAsync(options?: ReadableOptions): Promise<any>;
+    readlimboAsync(options?: ReadableOptions): Promise<any>;
 }

package/src/unix-crypt.ts

@@ -152,25 +152,25 @@ var SPTRANS=
             0x8200020, 32768, 0x208020 ]
 ];
 
-function hPermOp(a, n, m) {
+function hPermOp(a: number, n: number, m: number) {
     var t = (a << 16 - n ^ a) & m;
     a = a ^ t ^ t >>> 16 - n;
     return a;
 }
 
-function intToFourBytes(iValue, b, offset) {
+function intToFourBytes(iValue: number, b: Buffer, offset: number) {
     b[offset++] = iValue & 0xff;
     b[offset++] = iValue >>> 8 & 0xff;
     b[offset++] = iValue >>> 16 & 0xff;
     b[offset++] = iValue >>> 24 & 0xff;
 }
 
-function byteToUnsigned(b) {
+function byteToUnsigned(b: number) {
     var value = b;
     return value < 0 ? value + 256 : value;
 }
 
-function fourBytesToInt(b, offset) {
+function fourBytesToInt(b: Buffer, offset: number) {
     var value = byteToUnsigned(b[offset++]);
     value |= byteToUnsigned(b[offset++]) << 8;
     value |= byteToUnsigned(b[offset++]) << 16;
@@ -178,7 +178,7 @@ function fourBytesToInt(b, offset) {
     return value;
 }
 
-function permOp(a, b, n, m, results) {
+function permOp(a: number, b: number, n: number, m: number, results: number[]) {
     var t = (a >>> n ^ b) & m;
     a ^= t << n;
     b ^= t;
@@ -186,8 +186,8 @@ function permOp(a, b, n, m, results) {
     results[1] = b;
 }
 
-function desSetKey(key) {
-    var schedule = [];
+function desSetKey(key: Buffer) {
+    var schedule: number[] = [];
     var c = fourBytesToInt(key, 0);
     var d = fourBytesToInt(key, 4);
     var results = [0, 0];
@@ -232,7 +232,7 @@ function desSetKey(key) {
     return schedule;
 }
 
-function dEncrypt(el, r, s, e0, e1, sArr) {
+function dEncrypt(el: number, r: number, s: number, e0: number, e1: number, sArr: number[]) {
     var v = r ^ r >>> 16;
     var u = v & e0;
     v &= e1;
@@ -245,7 +245,7 @@ function dEncrypt(el, r, s, e0, e1, sArr) {
     return el;
 }
 
-function body(schedule, eSwap0, eSwap1) {
+function body(schedule: number[], eSwap0: number, eSwap1: number) {
     var left = 0;
     var right = 0;
     var t = 0;