node-firebird 2.8.1 → 2.10.0

package/lib/wire/statement.d.ts

@@ -3,34 +3,54 @@
  *   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;
-    [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;
+    /**
+     * Placeholder names in positional order when this statement was
+     * prepared from SQL with named placeholders (namedPlaceholders on),
+     * null/undefined otherwise. Set by Transaction.newStatement.
+     */
+    namedParams?: string[] | null;
+    /** 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.
+     * (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

@@ -5,6 +5,7 @@
  *
  ***************************************/
 const callback_1 = require("../callback");
+const named_params_1 = require("../named-params");
 class Statement {
     constructor(connection) {
         this.connection = connection;
@@ -16,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) {
@@ -28,6 +25,15 @@ class Statement {
             callback = params;
             params = undefined;
         }
+        if (this.namedParams && (0, named_params_1.isNamedParamsObject)(params)) {
+            try {
+                params = (0, named_params_1.bindNamedParams)(this.namedParams, params);
+            }
+            catch (err) {
+                (0, callback_1.doError)(err, callback);
+                return;
+            }
+        }
         this.options = options;
         this.connection.executeStatement(transaction, this, params, callback, options);
     }
@@ -51,9 +57,23 @@ class Statement {
     }
     /**
      * Execute this statement once per row via the Firebird 4 batch API
-     * (protocol 16+). `rows` is an array of parameter arrays.
+     * (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, rows, callback, options) {
+        var names = this.namedParams;
+        if (names && Array.isArray(rows)) {
+            try {
+                rows = rows.map(function (row) {
+                    return (0, named_params_1.isNamedParamsObject)(row) ? (0, named_params_1.bindNamedParams)(names, row) : row;
+                });
+            }
+            catch (err) {
+                (0, callback_1.doError)(err, callback);
+                return;
+            }
+        }
         this.connection.executeBatch(transaction, this, rows, callback, options);
     }
     /* Promise / async-await API — wrappers over the callback methods above. */

package/lib/wire/transaction.d.ts

@@ -1,13 +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);
-    newStatement(query: string, callback: (err: any, statement?: any) => void): 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;
+    constructor(connection: Connection);
+    /** Per-call options.namedPlaceholders overrides the connection option. */
+    private namedPlaceholdersEnabled;
+    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
@@ -17,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

@@ -3,8 +3,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 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
@@ -45,15 +47,40 @@ class Transaction {
         this.connection = connection;
         this.db = connection.db;
     }
-    newStatement(query, callback) {
+    /** Per-call options.namedPlaceholders overrides the connection option. */
+    namedPlaceholdersEnabled(options) {
+        if (options && options.namedPlaceholders !== undefined)
+            return !!options.namedPlaceholders;
+        return !!(this.connection.options && this.connection.options.namedPlaceholders);
+    }
+    newStatement(query, callback, options) {
         var cnx = this.connection;
         var self = this;
-        var query_cache = cnx.getCachedQuery(query);
+        // 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.
+        var names = null;
+        if (this.namedPlaceholdersEnabled(options)) {
+            var parsed = (0, named_params_1.parseNamedPlaceholders)(query);
+            if (parsed.names) {
+                query = parsed.sql;
+                names = parsed.names;
+            }
+        }
+        var deliver = function (err, statement) {
+            if (statement)
+                statement.namedParams = names;
+            cb(err, statement);
+        };
+        var query_cache = cnx.takeCachedStatement(query);
         if (query_cache) {
-            callback(null, query_cache);
+            deliver(null, query_cache);
         }
         else {
-            cnx.prepare(self, query, false, callback);
+            cnx.prepare(self, query, false, deliver);
         }
     }
     execute(query, params, callback, options) {
@@ -72,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);
             }
@@ -124,7 +155,7 @@ class Transaction {
                         break;
                 }
             }, options);
-        });
+        }, options);
     }
     sequentially(query, params, on, callback, options = {}) {
         if (params instanceof Function) {
@@ -186,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;
@@ -212,16 +252,18 @@ 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);
             }, options);
-        });
+        }, options);
     }
     executeBatchAsync(query, rows, options) {
         var self = this;

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 });

package/lib/wire/xsqlvar.d.ts

@@ -22,20 +22,20 @@ export declare abstract class SQLVarBase {
     abstract calcBlr(blr: BlrWriter): void;
 }
 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 +45,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/package.json

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