node-firebird 2.9.0 → 2.10.0

package/lib/wire/connection.d.ts

@@ -1,5 +1,14 @@
-import { XdrWriter, BlrWriter } from './serialize';
+import { XdrWriter, BlrWriter, XdrReader } from './serialize';
+import { type Callback, type SimpleCallback } from '../callback';
 import * as srp from '../srp';
+import * as Xsql from './xsqlvar';
+import ServiceManager from './service';
+import Database from './database';
+import Statement from './statement';
+import Transaction from './transaction';
+import Socket from './socket';
+import type { QueueCallback, QueueEntry, WireResponse, InternalOptions, InternalQueryOptions, BatchCb, Quad, AcceptPacket } from './wire-types';
+import type { BatchOptions, QueryParams } from '../types';
 declare function parseValueIfJson(value: any, options: any): any;
 /***************************************
  *
@@ -12,10 +21,12 @@ declare class Connection {
     static fetch_blob_async: typeof fetch_blob_async;
     static parseValueIfJson: typeof parseValueIfJson;
     static describe: typeof describe;
-    db: any;
-    svc: any;
-    options: any;
-    accept: any;
+    db: Database;
+    svc: ServiceManager | undefined;
+    options: InternalOptions;
+    /** protocol negotiation result (op_accept / op_cond_accept / op_accept_data);
+     *  populated during the connect/attach handshake */
+    accept: AcceptPacket;
     error: any;
     dbhandle: number | undefined;
     svchandle: number | undefined;
@@ -27,10 +38,12 @@ declare class Connection {
     } | undefined;
     _msg: XdrWriter;
     _blr: BlrWriter;
-    _queue: any[];
+    /** response queue: one entry per expected server response (see wire-types) */
+    _queue: QueueEntry[];
     _pending: string[];
-    _socket: any;
-    _xdr: any;
+    _socket: Socket;
+    /** partially received packet buffered between 'data' events */
+    _xdr: XdrReader | undefined;
     _isOpened: boolean;
     _isClosed: boolean;
     _isDetach: boolean;
@@ -42,48 +55,64 @@ declare class Connection {
     _detachAuto: any;
     _retry_connection_id: any;
     _retry_connection_interval: number;
-    _max_cached_query: number;
-    _cache_query: Record<string, any> | null;
+    _statementCacheSize: number;
+    _statementCache: Map<string, Statement> | null;
     _messageFile: string;
     _authStartTime: number | undefined;
     _pendingAccept: any;
     _inlineBlobs: Map<string, Buffer> | undefined;
-    constructor(host: string, port: number, callback: any, options: any, db?: any, svc?: any);
-    _setcachedquery(query: any, statement: any): void;
-    getCachedQuery(query: any): any;
+    constructor(host: string, port: number, callback: SimpleCallback | undefined, options: InternalOptions, db?: Database, svc?: ServiceManager);
+    /**
+     * Take an idle prepared statement for `query` out of the cache, or null.
+     * The statement leaves the cache while in use, so concurrent callers of
+     * the same query never share a server-side cursor — they simply prepare
+     * a fresh statement and the spare is dropped when released.
+     */
+    takeCachedStatement(query: string): Statement | null;
+    /**
+     * Return a statement after use. With the statement cache enabled the
+     * statement goes back into the cache as most-recently-used (closing its
+     * cursor but keeping the prepared handle), evicting the least-recently
+     * used statement over the limit. Failed statements, DDL and spares for
+     * an already-cached query are dropped instead.
+     */
+    releaseStatement(statement: Statement, callback?: QueueCallback): void;
     _rejectPending(err: any): void;
-    _bind_events(host: any, port: any, callback: any): void;
+    _bind_events(host: string, port: number, callback: SimpleCallback | undefined): void;
     disconnect(): void;
-    sendOpContAuth(authData: any, authDataEnc: any, pluginName: any): void;
-    sendOpCrypt(encryptPlugin: any): void;
-    sendOpCryptKeyCallback(pluginData: any): void;
+    sendOpContAuth(authData: string, authDataEnc: BufferEncoding, pluginName: string): void;
+    sendOpCrypt(encryptPlugin: string): void;
+    sendOpCryptKeyCallback(pluginData: BlrWriter): void;
     /**
      * Send an out-of-band op_cancel packet (protocol 12+ / Firebird 2.5+).
      * The server reads it asynchronously while an operation is executing and
      * makes that operation fail with isc_cancelled (GDSCode.CANCELLED); the
      * op_cancel packet itself has no response, so nothing is queued here.
      */
-    cancelOperation(kind: any, callback: any): this;
+    cancelOperation(kind?: number | SimpleCallback, callback?: SimpleCallback): this | undefined;
     /** Write a prebuilt packet and queue its response callback. */
-    _queueEventBuffer(buffer: any, callback: any): void;
-    _queueEvent(callback: any, defer?: boolean): void;
-    connect(options: any, callback: any): void;
-    attach(options: any, callback?: any, db?: any): void;
-    detach(callback: any): this;
-    createDatabase(options: any, callback: any): void;
-    dropDatabase(callback: any): void;
-    throwClosed(callback: any): this;
-    startTransaction(options: any, callback: any): this;
-    commit(transaction: any, callback: any): this;
-    rollback(transaction: any, callback: any): this;
-    commitRetaining(transaction: any, callback: any): this;
-    rollbackRetaining(transaction: any, callback: any): this;
-    allocateStatement(callback: any): this;
-    dropStatement(statement: any, callback: any): this;
-    closeStatement(statement: any, callback: any): this;
-    allocateAndPrepareStatement(transaction: any, query: any, plan: any, callback: any): void;
-    prepare(transaction: any, query: any, plan: any, callback: any): void;
-    prepareStatement(transaction: any, statement: any, query: any, plan: any, callback: any): this;
+    _queueEventBuffer(buffer: Buffer, callback: QueueCallback | undefined): void;
+    _queueEvent(callback: QueueCallback | undefined, defer?: boolean): void;
+    connect(options: InternalOptions, callback: Callback<AcceptPacket> | undefined): void;
+    attach(options: InternalOptions, callback?: Callback<Database>, db?: Database): void;
+    detach(callback: Callback | undefined): this | undefined;
+    createDatabase(options: InternalOptions, callback: Callback<Database> | undefined): void;
+    dropDatabase(callback: SimpleCallback | undefined): void;
+    throwClosed(callback: ((err: Error, ...args: any[]) => void) | undefined): this;
+    /** `options` is a resolved options object, a bare isolation array, or
+     *  the callback itself when no options are given. */
+    startTransaction(options: any, callback?: any): this | undefined;
+    commit(transaction: Transaction, callback: QueueCallback | undefined): this | undefined;
+    rollback(transaction: Transaction, callback: QueueCallback | undefined): this | undefined;
+    commitRetaining(transaction: Transaction, callback: QueueCallback | undefined): this | undefined;
+    rollbackRetaining(transaction: Transaction, callback: QueueCallback | undefined): this | undefined;
+    allocateStatement(callback: QueueCallback): this | undefined;
+    dropStatement(statement: Statement, callback: QueueCallback | undefined): this | undefined;
+    closeStatement(statement: Statement, callback: QueueCallback | undefined): this | undefined;
+    allocateAndPrepareStatement(transaction: Transaction, query: string, plan: boolean, callback: Callback<Statement>): void;
+    prepare(transaction: Transaction, query: string, plan: boolean, callback: Callback<Statement>): void;
+    /** `plan` may be the callback itself when no plan flag is given. */
+    prepareStatement(transaction: Transaction, statement: Statement, query: string, plan: boolean | Callback<Statement>, callback?: Callback<Statement>): this | undefined;
     /**
      * Execute a statement once per row using the Firebird 4 batch API
      * (protocol 16+): op_batch_create + op_batch_msg(s) + op_batch_exec +
@@ -96,27 +125,31 @@ declare class Connection {
      * { recordCount, updateCounts, errors: [{recordNumber, error}],
      *   errorRecordNumbers, success }.
      */
-    executeBatch(transaction: any, statement: any, rows: any, callback: any, options: any): this;
-    executeStatement(transaction: any, statement: any, params: any, callback: any, custom: any): this;
-    sendExecute(op: number, statement: any, transaction: any, callback: any, parameters?: any[]): void;
-    fetch(statement: any, transaction: any, count: any, callback: any): void;
-    fetchScroll(statement: any, transaction: any, direction: any, offset: any, count: any, callback: any): void;
-    fetchAll(statement: any, transaction: any, callback: any): void;
-    openBlob(blob: any, transaction: any, callback: any): void;
-    closeBlob(blob: any, callback: any, defer?: boolean): void;
-    getSegment(blob: any, callback: any): void;
-    createBlob2(transaction: any, callback: any): void;
-    batchSegments(blob: any, buffer: any, callback: any): void;
-    svcattach(options: any, callback?: any, svc?: any): void;
-    svcstart(spbaction: any, callback: any): void;
-    svcquery(spbquery: any, resultbuffersize: any, timeout: any, callback: any): void;
-    svcdetach(callback: any): void;
-    auxConnection(eventid: any, callback: any): this;
-    queEvents(events: any, eventid: any, callback: any): this;
-    closeEvents(eventid: any, callback: any): this;
+    executeBatch(transaction: Transaction, statement: Statement, rows: QueryParams[], callback: BatchCb | undefined, options?: BatchOptions): this | undefined;
+    /** `params` may be the callback itself when the statement has no parameters. */
+    executeStatement(transaction: Transaction, statement: Statement, params: any, callback?: QueueCallback, custom?: InternalQueryOptions): this | undefined;
+    sendExecute(op: number, statement: Statement, transaction: Transaction, callback: QueueCallback | undefined, parameters?: any[]): void;
+    /** `count` may be the callback itself when no fetch size is given. */
+    fetch(statement: Statement, transaction: Transaction, count: any, callback?: QueueCallback): void;
+    fetchScroll(statement: Statement, transaction: Transaction, direction: string | number, offset: any, count: any, callback?: QueueCallback): void;
+    fetchAll(statement: Statement, transaction: Transaction, callback: Callback<any[]>): void;
+    openBlob(blob: Quad, transaction: Transaction, callback: QueueCallback): void;
+    closeBlob(blob: any, callback?: QueueCallback, defer?: boolean): void;
+    getSegment(blob: any, callback: QueueCallback): void;
+    createBlob2(transaction: Transaction, callback: QueueCallback): void;
+    batchSegments(blob: any, buffer: Buffer, callback: QueueCallback): void;
+    svcattach(options: InternalOptions, callback?: Callback<ServiceManager>, svc?: ServiceManager): void;
+    svcstart(spbaction: BlrWriter, callback: QueueCallback | undefined): void;
+    svcquery(spbquery: number[], resultbuffersize: number, timeout: number | undefined, callback: QueueCallback | undefined): void;
+    svcdetach(callback: Callback | undefined): void;
+    auxConnection(eventid: number | Callback, callback?: Callback): this | undefined;
+    queEvents(events: Record<string, number>, eventid: number, callback: Callback): this | undefined;
+    closeEvents(eventid: number, callback: Callback): this | undefined;
 }
-declare function decodeResponse(data: any, callback: any, cnx: any, lowercase_keys: any, cb: (err?: any, obj?: any) => void): any;
-declare function describe(buff: Buffer, statement: any): void;
-declare function fetch_blob_async_transaction(statement: any, id: any, column: any, row: any): (transactionArg: any) => any;
-declare function fetch_blob_async(statement: any, id: any, name: any, row: any): (transaction: any, callback: any) => void;
+declare function decodeResponse(data: XdrReader, callback: QueueCallback | undefined, cnx: Connection, lowercase_keys: boolean | undefined, cb: (err?: any, obj?: any) => void): void | WireResponse | {
+    error: Error;
+};
+declare function describe(buff: Buffer, statement: Statement): void;
+declare function fetch_blob_async_transaction(statement: Statement, id: Quad, column: string | number, row: number, meta?: Xsql.SQLVarBase): (transactionArg: any) => Promise<unknown>;
+declare function fetch_blob_async(statement: Statement, id: Quad, name: string | number, row: number): (transaction: Transaction, callback: any) => void;
 export = Connection;