node-firebird 2.9.0 → 2.11.0

package/lib/wire/service.js

@@ -1027,5 +1027,150 @@ class ServiceManager extends events_1.default.EventEmitter {
             self._processquery(data.buffer, callback);
         });
     }
+    /* Promise / async-await API — wrappers over the callback methods above. */
+    detachAsync(force) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.detach(cb, force); });
+    }
+    backupAsync(options) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.backup(options, cb); });
+    }
+    nbackupAsync(options) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.nbackup(options, cb); });
+    }
+    restoreAsync(options) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.restore(options, cb); });
+    }
+    nrestoreAsync(options) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.nrestore(options, cb); });
+    }
+    setDialectAsync(db, dialect) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.setDialect(db, dialect, cb); });
+    }
+    setSweepintervalAsync(db, sweepinterval) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.setSweepinterval(db, sweepinterval, cb); });
+    }
+    setCachebufferAsync(db, nbpages) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.setCachebuffer(db, nbpages, cb); });
+    }
+    BringOnlineAsync(db) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.BringOnline(db, cb); });
+    }
+    ShutdownAsync(db, kind, delay, mode) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.Shutdown(db, kind, delay, mode, cb); });
+    }
+    setShadowAsync(db, val) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.setShadow(db, val, cb); });
+    }
+    setForcewriteAsync(db, val) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.setForcewrite(db, val, cb); });
+    }
+    setReservespaceAsync(db, val) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.setReservespace(db, val, cb); });
+    }
+    setReadonlyModeAsync(db) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.setReadonlyMode(db, cb); });
+    }
+    setReadwriteModeAsync(db) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.setReadwriteMode(db, cb); });
+    }
+    validateAsync(options) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.validate(options, cb); });
+    }
+    commitAsync(db, transactid) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.commit(db, transactid, cb); });
+    }
+    rollbackAsync(db, transactid) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.rollback(db, transactid, cb); });
+    }
+    recoverAsync(db, transactid) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.recover(db, transactid, cb); });
+    }
+    getStatsAsync(options) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.getStats(options, cb); });
+    }
+    getLogAsync(options) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.getLog(options, cb); });
+    }
+    getUsersAsync(username) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.getUsers(username === undefined ? null : username, cb); });
+    }
+    addUserAsync(username, password, options) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.addUser(username, password, options, cb); });
+    }
+    editUserAsync(username, options) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.editUser(username, options, cb); });
+    }
+    removeUserAsync(username, rolename) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.removeUser(username, rolename === undefined ? null : rolename, cb); });
+    }
+    getFbserverInfosAsync(infos, options) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.getFbserverInfos(infos || {}, options || {}, cb); });
+    }
+    startTraceAsync(options) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.startTrace(options, cb); });
+    }
+    suspendTraceAsync(options) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.suspendTrace(options, cb); });
+    }
+    resumeTraceAsync(options) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.resumeTrace(options, cb); });
+    }
+    stopTraceAsync(options) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.stopTrace(options, cb); });
+    }
+    getTraceListAsync(options) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.getTraceList(options || {}, cb); });
+    }
+    readlineAsync(options) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.readline(options || {}, cb); });
+    }
+    readeofAsync(options) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.readeof(options || {}, cb); });
+    }
+    hasRunningActionAsync(options) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.hasRunningAction(options || {}, cb); });
+    }
+    readusersAsync(options) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.readusers(options || {}, cb); });
+    }
+    readlimboAsync(options) {
+        var self = this;
+        return (0, callback_1.fromCallback)(function (cb) { self.readlimbo(options || {}, cb); });
+    }
 }
 module.exports = ServiceManager;

package/lib/wire/socket.d.ts

@@ -20,6 +20,8 @@ declare class Arc4 {
  */
 declare class Socket {
     static Arc4: typeof Arc4;
+    end: net.Socket['end'];
+    removeAllListeners: net.Socket['removeAllListeners'];
     _socket: net.Socket;
     compress: boolean;
     compressor: zlib.Deflate | null;
@@ -30,7 +32,7 @@ declare class Socket {
     encrypt: boolean;
     encryptCipher: any;
     decryptCipher: any;
-    constructor(port: number, host: string);
+    constructor(port: number, host: string, enableKeepAlive?: boolean, keepAliveInitialDelay?: number);
     /**
      * Decompress and/or decrypt data when received.
      * Override on data event.

package/lib/wire/socket.js

@@ -82,10 +82,13 @@ class ChaChaCipher {
  */
 class Socket {
     static { this.Arc4 = Arc4; }
-    constructor(port, host) {
+    constructor(port, host, enableKeepAlive = true, keepAliveInitialDelay = 60000) {
+        this.compress = false;
         this._socket = net_1.default.createConnection(port, host);
         this._socket.setNoDelay(true);
-        this._socket.setKeepAlive(true, 60000); // 1 minute delay to detect dead/stale connections
+        // TCP keepalive probing detects dead/stale connections; the delay is
+        // how long the socket must be idle before the first probe.
+        this._socket.setKeepAlive(enableKeepAlive, keepAliveInitialDelay);
         this.compressor = null;
         this.compressorBuffer = [];
         this.decompressor = null;

package/lib/wire/statement.d.ts

@@ -3,13 +3,21 @@
  *   Statement
  *
  ***************************************/
+import { type Callback, type SimpleCallback } from '../callback';
+import type Connection from './connection';
+import type Transaction from './transaction';
+import type { SQLVarBase } from './xsqlvar';
+import type { QueryOptions, QueryParams } from '../types';
 declare class Statement {
-    connection: any;
+    connection: Connection;
     query: string;
     type: number;
-    output: any[];
-    input: any[];
-    options: any;
+    output: SQLVarBase[];
+    input: SQLVarBase[];
+    /** per-execute query options (asObject/asStream/timeout/...) */
+    options: (QueryOptions & {
+        [key: string]: any;
+    }) | undefined;
     handle: number;
     plan: string;
     /**
@@ -18,27 +26,31 @@ declare class Statement {
      * null/undefined otherwise. Set by Transaction.newStatement.
      */
     namedParams?: string[] | null;
-    [key: string]: any;
-    constructor(connection: any);
-    close(callback?: (err?: any) => void): void;
-    drop(callback?: (err?: any) => void): void;
-    release(callback?: (err?: any) => void): void;
-    execute(transaction: any, params?: any, callback?: any, options?: any): void;
-    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;
+    /** set when an execute/fetch on this statement errored — the statement
+     *  is dropped on release instead of going back into the cache */
+    _failed?: boolean;
+    /** rows fetched so far by the current cursor (decodeResponse) */
+    nbrowsfetched?: number;
+    constructor(connection: Connection);
+    close(callback?: SimpleCallback): void;
+    drop(callback?: SimpleCallback): void;
+    release(callback?: SimpleCallback): void;
+    execute(transaction: Transaction, params?: any, callback?: any, options?: any): void;
+    fetch(transaction: Transaction, count: number | string, callback: Callback): void;
+    fetchScroll(transaction: Transaction, direction: string | number, offset?: any, count?: any, callback?: any): void;
+    fetchAll(transaction: Transaction, callback: Callback): void;
     /**
      * Execute this statement once per row via the Firebird 4 batch API
      * (protocol 16+). `rows` is an array of parameter arrays — or, when the
      * statement was prepared with named placeholders, of values-by-name
      * objects (the two forms can be mixed).
      */
-    executeBatch(transaction: any, rows: any[][], callback?: any, options?: any): void;
-    executeAsync(transaction: any, params?: any, options?: any): Promise<any>;
-    executeBatchAsync(transaction: any, rows: 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>;
+    executeBatch(transaction: Transaction, rows: QueryParams[], callback?: any, options?: any): void;
+    executeAsync(transaction: Transaction, params?: any, options?: any): Promise<any>;
+    executeBatchAsync(transaction: Transaction, rows: QueryParams[], options?: any): Promise<any>;
+    fetchAsync(transaction: Transaction, count: number | string): Promise<any>;
+    fetchScrollAsync(transaction: Transaction, direction: string | number, offset?: any, count?: any): Promise<any>;
+    fetchAllAsync(transaction: Transaction): Promise<any>;
     closeAsync(): Promise<void>;
     dropAsync(): Promise<void>;
     releaseAsync(): Promise<void>;

package/lib/wire/statement.js

@@ -17,11 +17,7 @@ class Statement {
         this.connection.dropStatement(this, callback);
     }
     release(callback) {
-        var cache_query = this.connection.getCachedQuery(this.query);
-        if (cache_query)
-            this.connection.closeStatement(this, callback);
-        else
-            this.connection.dropStatement(this, callback);
+        this.connection.releaseStatement(this, callback);
     }
     execute(transaction, params, callback, options) {
         if (params instanceof Function) {

package/lib/wire/transaction.d.ts

@@ -1,15 +1,27 @@
+import { type Callback, type SimpleCallback } from '../callback';
+import type Connection from './connection';
+import type Database from './database';
+import type Statement from './statement';
+import type { BatchCb, StatementCb, InternalQueryOptions } from './wire-types';
+import type { BatchOptions, BatchResult, QueryOptions, QueryParams, QueryStreamOptions, SequentialCallback } from '../types';
 declare class Transaction {
-    connection: any;
-    db: any;
+    connection: Connection;
+    db: Database;
     handle: number;
-    [key: string]: any;
-    constructor(connection: any);
+    constructor(connection: Connection);
     /** Per-call options.namedPlaceholders overrides the connection option. */
     private namedPlaceholdersEnabled;
-    newStatement(query: string, callback: (err: any, statement?: any) => void, options?: any): void;
-    execute(query: string, params?: any, callback?: any, options?: any): void;
-    sequentially(query: string, params?: any, on?: any, callback?: any, options?: any): this;
-    query(query: string, params?: any, callback?: any, options?: any): void;
+    newStatement(query: string, callback: StatementCb, options?: InternalQueryOptions): void;
+    execute(query: string, params?: QueryParams | Callback, callback?: any, options?: InternalQueryOptions): void;
+    sequentially(query: string, params?: any, on?: any, callback?: any, options?: InternalQueryOptions | boolean): this;
+    /**
+     * Run `query` inside this transaction and return an object-mode
+     * Readable emitting one row per chunk, with real backpressure (see
+     * Database.queryStream). The transaction is NOT committed when the
+     * stream ends — commit or roll back yourself.
+     */
+    queryStream(query: string, params?: QueryParams, options?: QueryStreamOptions): import("node:stream").Readable;
+    query(query: string, params?: QueryParams | Callback, callback?: any, options?: InternalQueryOptions): void;
     /**
      * Execute `query` once per row in `rows` using the Firebird 4 batch API
      * (protocol 16+, single network flush). The callback receives a
@@ -19,16 +31,16 @@ declare class Transaction {
      * commit or roll back yourself (or use db.executeBatch for
      * all-or-nothing semantics).
      */
-    executeBatch(query: string, rows: any[][], callback?: any, options?: any): void;
-    executeBatchAsync(query: string, rows: any[][], options?: any): Promise<any>;
-    commit(callback?: (err?: any) => void): void;
-    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>;
+    executeBatch(query: string, rows: QueryParams[], callback?: BatchCb, options?: BatchOptions & QueryOptions): void;
+    executeBatchAsync(query: string, rows: QueryParams[], options?: BatchOptions & QueryOptions): Promise<BatchResult>;
+    commit(callback?: SimpleCallback): void;
+    rollback(callback?: SimpleCallback): void;
+    commitRetaining(callback?: SimpleCallback): void;
+    rollbackRetaining(callback?: SimpleCallback): void;
+    queryAsync(query: string, params?: QueryParams, options?: InternalQueryOptions): Promise<any[]>;
+    executeAsync(query: string, params?: QueryParams, options?: InternalQueryOptions): Promise<any[]>;
+    sequentiallyAsync(query: string, params?: any, on?: SequentialCallback, options?: InternalQueryOptions | boolean): Promise<void>;
+    newStatementAsync(query: string): Promise<Statement>;
     commitAsync(): Promise<void>;
     rollbackAsync(): Promise<void>;
     commitRetainingAsync(): Promise<void>;

package/lib/wire/transaction.js

@@ -6,6 +6,7 @@ const callback_1 = require("../callback");
 const named_params_1 = require("../named-params");
 const utils_1 = require("../utils");
 const const_1 = __importDefault(require("./const"));
+const query_stream_1 = __importDefault(require("./query-stream"));
 /***************************************
  *
  *   Transaction
@@ -55,6 +56,9 @@ class Transaction {
     newStatement(query, callback, options) {
         var cnx = this.connection;
         var self = this;
+        // the public strict callback shape and the internal optional-args
+        // shape only differ in optionality; treat it as the internal one
+        var cb = callback;
         // With namedPlaceholders on, prepare the positional rewrite and
         // remember the name order on the statement so statement.execute can
         // accept a values-by-name object. The rewritten SQL is the cache key.
@@ -69,9 +73,9 @@ class Transaction {
         var deliver = function (err, statement) {
             if (statement)
                 statement.namedParams = names;
-            callback(err, statement);
+            cb(err, statement);
         };
-        var query_cache = cnx.getCachedQuery(query);
+        var query_cache = cnx.takeCachedStatement(query);
         if (query_cache) {
             deliver(null, query_cache);
         }
@@ -95,11 +99,15 @@ class Transaction {
         }
         var self = this;
         this.newStatement(query, function (err, statement) {
-            if (err) {
+            if (err || !statement) {
                 (0, callback_1.doError)(err, callback);
                 return;
             }
             function dropError(err) {
+                // do not put a statement that just failed back into the cache
+                // (statement is guaranteed by the guard above; hoisting keeps
+                // the narrowing from reaching this function declaration)
+                statement._failed = true;
                 statement.release();
                 (0, callback_1.doCallback)(err, callback);
             }
@@ -209,6 +217,15 @@ class Transaction {
         self.execute(query, params, callback, options);
         return self;
     }
+    /**
+     * Run `query` inside this transaction and return an object-mode
+     * Readable emitting one row per chunk, with real backpressure (see
+     * Database.queryStream). The transaction is NOT committed when the
+     * stream ends — commit or roll back yourself.
+     */
+    queryStream(query, params, options) {
+        return (0, query_stream_1.default)(this, query, params, options);
+    }
     query(query, params, callback, options = {}) {
         if (params instanceof Function) {
             callback = params;
@@ -235,11 +252,13 @@ class Transaction {
     executeBatch(query, rows, callback, options) {
         var self = this;
         this.newStatement(query, function (err, statement) {
-            if (err) {
+            if (err || !statement) {
                 (0, callback_1.doError)(err, callback);
                 return;
             }
             statement.executeBatch(self, rows, function (err, result) {
+                if (err)
+                    statement._failed = true;
                 statement.release();
                 if (callback)
                     callback(err, result);

package/lib/wire/wire-types.d.ts

@@ -0,0 +1,116 @@
+/***************************************
+ *
+ *   Internal wire-protocol types (type-only module)
+ *
+ * Shared vocabulary for the wire core (connection/statement/transaction/
+ * database). Nothing here exists at runtime.
+ *
+ ***************************************/
+import type { Callback, FbStatusItem } from '../callback';
+import type Statement from './statement';
+import type { BatchResult, Options, QueryOptions, Statement as PublicStatement } from '../types';
+/**
+ * One entry of the connection's response queue (`connection._queue`).
+ * The function itself is the user/driver callback; the extra properties
+ * steer decodeResponse:
+ *
+ * - `response`  — pre-allocated object the op_response decode fills in
+ *                 (a Statement, Transaction, or plain response object).
+ * - `statement` — statement whose `output` describes the rows of an
+ *                 op_fetch_response / op_sql_response.
+ * - `lazy_count`— number of chained lazy op_responses this entry consumes
+ *                 (ptype_lazy_send batches e.g. allocate+prepare).
+ *
+ * Deferred ops (op_free_statement, op_close_blob, ...) push `undefined`
+ * placeholders so every server response still pairs with one entry.
+ */
+export interface QueueCallback {
+    (err?: any, obj?: any): void;
+    response?: any;
+    statement?: Statement;
+    lazy_count?: number;
+}
+/** A queue entry: a callback, or a placeholder for a deferred op. */
+export type QueueEntry = QueueCallback | undefined;
+/** XDR quad — 64-bit value as two 32-bit halves (blob ids, object ids). */
+export interface Quad {
+    high: number;
+    low: number;
+}
+/**
+ * Decoded op_response packet (see parseOpResponse): object handle, object
+ * id, optional info buffer and, on failure, the status vector. Statement /
+ * Transaction responses are these fields merged onto the pre-allocated
+ * object from QueueCallback.response.
+ */
+export interface WireResponse {
+    handle?: number;
+    oid?: Quad;
+    buffer?: Buffer;
+    status?: FbStatusItem[];
+    /** isc_arg_warning entries — attached to a SUCCESSFUL response */
+    warnings?: FbStatusItem[];
+    sqlcode?: number;
+    message?: string;
+}
+/** Result of decoding op_fetch_response / op_sql_response row data. */
+export interface FetchResult {
+    data: any[];
+    /** true when the cursor is exhausted (fetch status 100 / singleton). */
+    fetched: boolean;
+    /** pending blobAsText fetches to resolve before delivering rows. */
+    arrBlob?: any[];
+}
+/**
+ * Protocol negotiation result decoded from op_accept / op_cond_accept /
+ * op_accept_data, plus the auth/crypt state accumulated during the
+ * handshake (op_cont_auth rounds, wire-crypt keys).
+ */
+export interface AcceptPacket {
+    protocolVersion: number;
+    protocolArchitecture: number;
+    protocolMinimumType: number;
+    compress: boolean;
+    pluginName: string;
+    authData: any;
+    sessionKey?: any;
+    [key: string]: any;
+}
+/**
+ * Query options as the wire core sees them: the public QueryOptions plus
+ * the internal row-delivery flags set by the Database/Transaction helpers
+ * (query / sequentially / queryStream).
+ */
+export type InternalQueryOptions = QueryOptions & {
+    /** deliver rows as objects keyed by column alias */
+    asObject?: boolean;
+    /** deliver rows one by one (row events / `on` delegate) instead of accumulating */
+    asStream?: boolean;
+    /** per-row delegate installed by sequentially() */
+    on?: (row: any, index: number, meta: any[], next: (err?: any) => void) => void;
+    [key: string]: any;
+};
+/**
+ * newStatement callback: the internal optional-args shape, or the public
+ * strict shape (non-optional statement) declared in types.ts.
+ */
+export type StatementCb = Callback<Statement> | ((err: Error | null, statement: PublicStatement) => void);
+/**
+ * executeBatch callback: the internal optional-args shape, or the public
+ * strict shape (non-optional result) declared in types.ts.
+ */
+export type BatchCb = Callback<BatchResult> | ((err: any, result: BatchResult) => void);
+/**
+ * Connection options as the wire core sees them: the public Options plus
+ * internal flags set by the driver itself.
+ */
+export type InternalOptions = Options & {
+    /** set by the pool so detach() returns the connection instead */
+    isPool?: boolean;
+    /** override path of the firebird.msg error-message file */
+    messageFile?: string;
+    /** legacy statement-cache flags (mapped onto statementCacheSize) */
+    cacheQuery?: boolean;
+    maxCachedQuery?: number;
+    [key: string]: any;
+};

package/lib/wire/wire-types.js

@@ -0,0 +1,10 @@
+"use strict";
+/***************************************
+ *
+ *   Internal wire-protocol types (type-only module)
+ *
+ * Shared vocabulary for the wire core (connection/statement/transaction/
+ * database). Nothing here exists at runtime.
+ *
+ ***************************************/
+Object.defineProperty(exports, "__esModule", { value: true });