node-firebird 2.9.0 → 2.11.0

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;
@@ -91,6 +93,82 @@ export abstract class SQLVarBase {
 
 //------------------------------------------------------
 
+/** 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 function computeColumnKeys(
+    output: SQLVarBase[],
+    nestTables: boolean | string | undefined,
+    lowercaseKeys: boolean | undefined
+): ColumnKey[] {
+    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.
+ */
+export function resolveNestTables(
+    queryOptions: { nestTables?: boolean | string } | undefined,
+    connectionOptions: { nestTables?: boolean | string } | undefined
+): boolean | string | undefined {
+    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.
+ */
+export function nestCell(row: any, table: string | undefined) {
+    if (table === undefined) {
+        return row;
+    }
+    return row[table] || (row[table] = {});
+}
+
+//------------------------------------------------------
+
 export class SQLVarText extends SQLVarBase {
     decode(data: XdrReader, lowerV13: boolean, options?: any) {
         let ret;