node-firebird 2.8.1 → 2.10.0

package/src/wire/transaction.ts

@@ -1,6 +1,13 @@
-import { doCallback, doError, fromCallback } from '../callback';
+import { doCallback, doError, fromCallback, type Callback, type SimpleCallback } from '../callback';
+import { parseNamedPlaceholders } from '../named-params';
 import { noop } from '../utils';
 import Const from './const';
+import makeQueryStream from './query-stream';
+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';
 
 /***************************************
  *
@@ -25,7 +32,7 @@ function abortError(signal: any): Error {
  * GDSCode.CANCELLED). Returns the wrapped callback that detaches the
  * listener once the operation settles.
  */
-function hookAbortSignal(connection: any, signal: any, callback: any): any {
+function hookAbortSignal(connection: Connection, signal: AbortSignal, callback: any): any {
     var settled = false;
     var onAbort = function() {
         if (!settled)
@@ -41,29 +48,58 @@ function hookAbortSignal(connection: any, signal: any, callback: any): any {
 }
 
 class Transaction {
-    connection: any;
-    db: any;
-    handle: number;
-    [key: string]: any;
+    connection: Connection;
+    db: Database;
+    // populated externally from the op_transaction response
+    handle!: number;
 
-    constructor(connection: any) {
+    constructor(connection: Connection) {
         this.connection = connection;
         this.db = connection.db;
     }
 
-    newStatement(query: string, callback: (err: any, statement?: any) => void): void {
+    /** Per-call options.namedPlaceholders overrides the connection option. */
+    private namedPlaceholdersEnabled(options?: InternalQueryOptions): boolean {
+        if (options && options.namedPlaceholders !== undefined)
+            return !!options.namedPlaceholders;
+        return !!(this.connection.options && this.connection.options.namedPlaceholders);
+    }
+
+    newStatement(query: string, callback: StatementCb, options?: InternalQueryOptions): void {
         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 as Callback<Statement>;
+
+        // 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: string[] | null = null;
+        if (this.namedPlaceholdersEnabled(options)) {
+            var parsed = parseNamedPlaceholders(query);
+            if (parsed.names) {
+                query = parsed.sql;
+                names = parsed.names;
+            }
+        }
+
+        var deliver = function(err: any, statement?: 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: string, params?: any, callback?: any, options?: any): void {
+    execute(query: string, params?: QueryParams | Callback, callback?: any, options?: InternalQueryOptions): void {
         if (params instanceof Function) {
             options = callback;
             callback = params;
@@ -80,15 +116,19 @@ class Transaction {
         }
 
         var self = this;
-        this.newStatement(query, function(err: any, statement: any) {
+        this.newStatement(query, function(err: any, statement?: Statement) {
 
-            if (err) {
+            if (err || !statement) {
                 doError(err, callback);
                 return;
             }
 
             function dropError(err: any) {
-                statement.release();
+                // 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();
                 doCallback(err, callback);
             }
 
@@ -148,10 +188,10 @@ class Transaction {
                 }
 
             }, options);
-        });
+        }, options);
     }
 
-    sequentially(query: string, params?: any, on?: any, callback?: any, options: any = {}): this {
+    sequentially(query: string, params?: any, on?: any, callback?: any, options: InternalQueryOptions | boolean = {}): this {
         if (params instanceof Function) {
             options = callback;
             callback = on;
@@ -169,7 +209,7 @@ class Transaction {
         }
 
         var self = this;
-        var _on = function(row: any, i: number, meta: any, next: (err?: any) => void) {
+        var _on = function(row: any, i: number, meta: any[], next: (err?: any) => void) {
             var done = false;
             var finish = function(err?: any) {
                 if (done) {
@@ -215,7 +255,17 @@ class Transaction {
         return self;
     }
 
-    query(query: string, params?: any, callback?: any, options: any = {}): void {
+    /**
+     * 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) {
+        return makeQueryStream(this, query, params, options);
+    }
+
+    query(query: string, params?: QueryParams | Callback, callback?: any, options: InternalQueryOptions = {}): void {
         if (params instanceof Function) {
             callback = params;
             params = undefined;
@@ -242,56 +292,58 @@ 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 {
+    executeBatch(query: string, rows: QueryParams[], callback?: BatchCb, options?: BatchOptions & QueryOptions): void {
         var self = this;
-        this.newStatement(query, function(err: any, statement: any) {
-            if (err) {
+        this.newStatement(query, function(err: any, statement?: Statement) {
+            if (err || !statement) {
                 doError(err, callback);
                 return;
             }
 
-            statement.executeBatch(self, rows, function(err: any, result: any) {
+            statement.executeBatch(self, rows, function(err: any, result: BatchResult) {
+                if (err)
+                    statement._failed = true;
                 statement.release();
                 if (callback)
                     callback(err, result);
             }, options);
-        });
+        }, options);
     }
 
-    executeBatchAsync(query: string, rows: any[][], options?: any): Promise<any> {
+    executeBatchAsync(query: string, rows: QueryParams[], options?: BatchOptions & QueryOptions): Promise<BatchResult> {
         var self = this;
         return fromCallback(function(cb) { self.executeBatch(query, rows, cb, options); });
     }
 
-    commit(callback?: (err?: any) => void): void {
+    commit(callback?: SimpleCallback): void {
         this.connection.commit(this, callback);
     }
 
-    rollback(callback?: (err?: any) => void): void {
+    rollback(callback?: SimpleCallback): void {
         this.connection.rollback(this, callback);
     }
 
-    commitRetaining(callback?: (err?: any) => void): void {
+    commitRetaining(callback?: SimpleCallback): void {
         this.connection.commitRetaining(this, callback);
     }
 
-    rollbackRetaining(callback?: (err?: any) => void): void {
+    rollbackRetaining(callback?: SimpleCallback): 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[]> {
+    queryAsync(query: string, params?: QueryParams, options?: InternalQueryOptions): Promise<any[]> {
         var self = this;
         return fromCallback(function(cb) { self.query(query, params, cb, options); });
     }
 
-    executeAsync(query: string, params?: any, options?: any): Promise<any[]> {
+    executeAsync(query: string, params?: QueryParams, options?: InternalQueryOptions): 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> {
+    sequentiallyAsync(query: string, params?: any, on?: SequentialCallback, options?: InternalQueryOptions | boolean): Promise<void> {
         if (params instanceof Function) {
             options = on;
             on = params;
@@ -301,7 +353,7 @@ class Transaction {
         return fromCallback(function(cb) { self.sequentially(query, params, on, cb, options); });
     }
 
-    newStatementAsync(query: string): Promise<any> {
+    newStatementAsync(query: string): Promise<Statement> {
         var self = this;
         return fromCallback(function(cb) { self.newStatement(query, cb); });
     }

package/src/wire/wire-types.ts

@@ -0,0 +1,127 @@
+/***************************************
+ *
+ *   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/src/wire/xsqlvar.ts

@@ -26,7 +26,7 @@ const
  * Commonly used Firebird charsets not listed here fall back to the
  * connection-level DEFAULT_ENCODING (typically 'utf8').
  */
-const FirebirdToNodeEncoding = Object.freeze({
+const FirebirdToNodeEncoding: Readonly<Record<string, string>> = Object.freeze({
     UTF8:        'utf8',
     UNICODE_FSS: 'utf8',
     WIN1252:     'latin1',
@@ -36,7 +36,7 @@ const FirebirdToNodeEncoding = Object.freeze({
     NONE:        'latin1',   // unspecified charset – treat as binary-safe latin1
 });
 
-const FirebirdCharsetWidths = {
+const FirebirdCharsetWidths: Record<string, number> = {
     'UTF8': 4,
     'UNICODE_FSS': 3,
     'SJIS': 2,
@@ -71,11 +71,13 @@ function resolveTextEncoding(options?: any): BufferEncoding {
  * describe response before decode()/calcBlr() are called.
  */
 export abstract class SQLVarBase {
-    type: number;
-    subType: number;
-    scale: number;
-    length: number;
-    nullable: boolean;
+    // populated externally (see the doc comment above), hence the definite
+    // assignment assertions
+    type!: number;
+    subType!: number;
+    scale!: number;
+    length!: number;
+    nullable!: boolean;
     field?: string;
     relation?: string;
     relationSchema?: string;