node-firebird 2.11.0 → 2.13.0

package/src/wire/xsqlvar.ts

@@ -1,5 +1,9 @@
 import Const from './const';
+import { BlrReader } from './serialize';
+import { getCodec } from './codepages';
+import type { TextCodec } from './codepages';
 import type { XdrReader, XdrWriter, BlrWriter } from './serialize';
+import type { RecordCounts } from '../types';
 
 /***************************************
  *
@@ -14,6 +18,8 @@ const
     TimeCoeff = 86400000,
     MsPerMinute = 60000;
 
+const EMPTY_BUFFER = Buffer.alloc(0);
+
 /**
  * Maps Firebird character-set names (upper-case) to the Node.js Buffer
  * encoding string used by Buffer.toString() / Buffer.from().
@@ -39,11 +45,19 @@ const FirebirdToNodeEncoding: Readonly<Record<string, string>> = Object.freeze({
 const FirebirdCharsetWidths: Record<string, number> = {
     'UTF8': 4,
     'UNICODE_FSS': 3,
-    'SJIS': 2,
-    'EUCJ': 2
+    // real Firebird names — the bare 'SJIS'/'EUCJ' keys never matched a
+    // valid encoding option and silently resolved to width 1
+    'SJIS_0208': 2,
+    'EUCJ_0208': 2,
+    'KSC_5601': 2,
+    'BIG_5': 2,
+    'GB_2312': 2,
+    'GBK': 2,
+    'CP943C': 2,
+    'GB18030': 4,
 };
 
-function getFirebirdCharsetWidth(charset?: string): number {
+export function getFirebirdCharsetWidth(charset?: string): number {
     if (!charset) return 4;
     const upper = charset.toUpperCase();
     return FirebirdCharsetWidths[upper] || 1;
@@ -56,13 +70,85 @@ function getFirebirdCharsetWidth(charset?: string): number {
  * @param {object|null} options  Connection options object (may be falsy).
  * @returns {string}             A Node.js-compatible encoding string.
  */
-function resolveTextEncoding(options?: any): BufferEncoding {
+export function resolveTextEncoding(options?: any): BufferEncoding {
     const encoding = (options && options.encoding)
         ? options.encoding.toUpperCase()
         : Const.DEFAULT_ENCODING;
     return (FirebirdToNodeEncoding[encoding] || Const.DEFAULT_ENCODING.toLowerCase()) as BufferEncoding;
 }
 
+/**
+ * Codec for the CONNECTION charset when it is a codepage Node cannot
+ * handle natively (WIN1251, ISO8859_7, KOI8R, …); null on the native
+ * path (UTF8/latin1/ascii) and for unknown charsets. With a codec
+ * connection charset the server transliterates all text to that
+ * codepage, so every text column, parameter, SQL string and text blob
+ * goes through the codec (issues #319/#301).
+ */
+export function resolveTextCodec(options?: any): TextCodec | null {
+    return resolveTextState(options).codec;
+}
+
+interface TextState {
+    key: string | undefined;
+    codec: TextCodec | null;
+    enc: BufferEncoding;
+    width: number;
+}
+
+/**
+ * Per-connection text handling, resolved once and memoized on the
+ * long-lived options object: the decode loop calls this per CELL, and
+ * recomputing uppercased names + map lookups a million times per large
+ * fetch is pure waste. Invalidated if options.encoding ever changes.
+ */
+export function resolveTextState(options?: any): TextState {
+    const key = options && options.encoding;
+    if (options && options.__textState && options.__textState.key === key) {
+        return options.__textState;
+    }
+    const encoding = (key || Const.DEFAULT_ENCODING).toUpperCase();
+    const state: TextState = {
+        key,
+        codec: FirebirdToNodeEncoding[encoding] ? null : getCodec(encoding),
+        enc: (FirebirdToNodeEncoding[encoding] || Const.DEFAULT_ENCODING.toLowerCase()) as BufferEncoding,
+        width: getFirebirdCharsetWidth(encoding),
+    };
+    if (options) {
+        options.__textState = state;
+    }
+    return state;
+}
+
+/**
+ * Encode text in the CONNECTION charset — the byte form the server
+ * expects for parameters, SQL statement text and text-blob content.
+ */
+export function encodeConnectionText(options: any, value: string): Buffer {
+    const state = resolveTextState(options);
+    if (state.codec) {
+        return state.codec.encode(value);
+    }
+    if (state.enc === 'ascii') {
+        // Node's 'ascii' encoding masks high bits (0xE4 → 'd') — replace
+        // non-ASCII with '?' instead, matching the codec policy
+        value = value.replace(/[^\x00-\x7F]/g, '?');
+    }
+    return Buffer.from(value, state.enc);
+}
+
+/**
+ * Decode connection-charset bytes to text (the read counterpart of
+ * encodeConnectionText — used for text blobs).
+ */
+export function decodeConnectionText(options: any, buffer: Buffer): string {
+    const codec = resolveTextCodec(options);
+    if (codec) {
+        return codec.decode(buffer);
+    }
+    return buffer.toString(resolveTextEncoding(options));
+}
+
 //------------------------------------------------------
 
 /**
@@ -86,6 +172,9 @@ export abstract class SQLVarBase {
     owner?: string;
     charSetId?: number;
     collationId?: number;
+    /** Original declared byte length when scaleOutputLengths widened
+     *  `length` for the fetch capacity check (issue #422). */
+    nativeLength?: number;
 
     abstract decode(data: XdrReader, lowerV13: boolean, options?: any): any;
     abstract calcBlr(blr: BlrWriter): void;
@@ -117,13 +206,17 @@ export interface ColumnKey {
 export function computeColumnKeys(
     output: SQLVarBase[],
     nestTables: boolean | string | undefined,
-    lowercaseKeys: boolean | undefined
+    lowercaseKeys: boolean | undefined,
+    transform?: (key: string) => string
 ): ColumnKey[] {
     return output.map((column) => {
         let key = column.alias || '';
         if (lowercaseKeys) {
             key = key.toLowerCase();
         }
+        if (transform) {
+            key = transform(key);
+        }
         if (nestTables !== true && typeof nestTables !== 'string') {
             return { key };
         }
@@ -131,6 +224,9 @@ export function computeColumnKeys(
         if (lowercaseKeys) {
             table = table.toLowerCase();
         }
+        if (transform) {
+            table = transform(table);
+        }
         if (nestTables === true) {
             return { table, key };
         }
@@ -138,6 +234,67 @@ export function computeColumnKeys(
     });
 }
 
+/** transformKeys option value: the built-in 'camel', or a custom mapper. */
+export type KeyTransform = 'camel' | ((key: string) => string);
+
+/** FIRST_NAME → firstName (the transformKeys: 'camel' built-in). */
+export function camelizeKey(key: string): string {
+    const parts = String(key).toLowerCase().split('_');
+    let out = parts[0] || '';
+    for (let i = 1; i < parts.length; i++) {
+        const part = parts[i];
+        if (part) {
+            out += part.charAt(0).toUpperCase() + part.slice(1);
+        }
+    }
+    return out;
+}
+
+/**
+ * Resolve the effective transformKeys value (per-query wins over the
+ * connection option) into a callable mapper, or undefined when off.
+ * A custom mapper is guarded like the typeCast hook: a throw inside the
+ * row-decode loop would be mistaken for an incomplete packet and desync
+ * the response queue, so failures fall back to the untransformed key.
+ */
+export function resolveKeyTransform(
+    queryOptions: { transformKeys?: KeyTransform } | undefined,
+    connectionOptions: { transformKeys?: KeyTransform } | undefined
+): ((key: string) => string) | undefined {
+    const value = resolveQueryOption<KeyTransform>('transformKeys', queryOptions, connectionOptions);
+    if (value === 'camel') {
+        return camelizeKey;
+    }
+    if (typeof value !== 'function') {
+        return undefined;
+    }
+    return (key: string) => {
+        try {
+            return String(value(key));
+        } catch (err: any) {
+            console.warn('[node-firebird] transformKeys mapper threw for key "%s": %s — using the untransformed key',
+                key, err && err.message);
+            return key;
+        }
+    };
+}
+
+/**
+ * Shared precedence rule for per-query-overridable connection options:
+ * the per-query value wins whenever it is present (even if falsy), the
+ * connection option applies otherwise.
+ */
+function resolveQueryOption<T>(
+    name: string,
+    queryOptions: Record<string, any> | undefined,
+    connectionOptions: Record<string, any> | undefined
+): T | undefined {
+    if (queryOptions && queryOptions[name] !== undefined) {
+        return queryOptions[name];
+    }
+    return connectionOptions ? connectionOptions[name] : undefined;
+}
+
 /**
  * Resolve the effective nestTables value: the per-query option wins over
  * the connection option. The decoder and fetchBlobSyncRow both use this —
@@ -148,10 +305,7 @@ 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;
+    return resolveQueryOption('nestTables', queryOptions, connectionOptions);
 }
 
 /**
@@ -169,25 +323,115 @@ export function nestCell(row: any, table: string | undefined) {
 
 //------------------------------------------------------
 
+/** Human-readable names for the SQL_* wire type codes. */
+export const SQL_TYPE_NAMES: Record<number, string> = {
+    [Const.SQL_TEXT]: 'TEXT',
+    [Const.SQL_VARYING]: 'VARYING',
+    [Const.SQL_SHORT]: 'SHORT',
+    [Const.SQL_LONG]: 'LONG',
+    [Const.SQL_FLOAT]: 'FLOAT',
+    [Const.SQL_DOUBLE]: 'DOUBLE',
+    [Const.SQL_D_FLOAT]: 'D_FLOAT',
+    [Const.SQL_TIMESTAMP]: 'TIMESTAMP',
+    [Const.SQL_BLOB]: 'BLOB',
+    [Const.SQL_ARRAY]: 'ARRAY',
+    [Const.SQL_QUAD]: 'QUAD',
+    [Const.SQL_TYPE_TIME]: 'TIME',
+    [Const.SQL_TYPE_DATE]: 'DATE',
+    [Const.SQL_INT64]: 'INT64',
+    [Const.SQL_INT128]: 'INT128',
+    [Const.SQL_TIMESTAMP_TZ]: 'TIMESTAMP_TZ',
+    [Const.SQL_TIMESTAMP_TZ_EX]: 'TIMESTAMP_TZ_EX',
+    [Const.SQL_TIME_TZ]: 'TIME_TZ',
+    [Const.SQL_TIME_TZ_EX]: 'TIME_TZ_EX',
+    [Const.SQL_DEC16]: 'DEC16',
+    [Const.SQL_DEC34]: 'DEC34',
+    [Const.SQL_BOOLEAN]: 'BOOLEAN',
+    [Const.SQL_NULL]: 'NULL',
+};
+
+/**
+ * Public column-metadata shape for one output descriptor: the vocabulary
+ * both the typeCast hook and withMeta `fields` deliver. Keep the two in
+ * lockstep by building both through here.
+ */
+export function describeField(meta: Partial<SQLVarBase>) {
+    return {
+        type: meta.type!,
+        typeName: SQL_TYPE_NAMES[meta.type!] || 'UNKNOWN',
+        subType: meta.subType,
+        scale: meta.scale,
+        // report the column's true declared length, not the widened fetch
+        // buffer (see scaleOutputLengths)
+        length: meta.nativeLength !== undefined ? meta.nativeLength : meta.length,
+        nullable: meta.nullable,
+        field: meta.field,
+        relation: meta.relation,
+        relationAlias: meta.relationAlias,
+        relationSchema: meta.relationSchema,
+        alias: meta.alias,
+    };
+}
+
+/**
+ * Map a statement's output descriptors to the column-metadata array
+ * delivered in withMeta results ({ rows, fields, ... }).
+ */
+export function describeFields(output: SQLVarBase[]) {
+    return (output || []).map(describeField);
+}
+
+/**
+ * Parse the op_info_sql response buffer of a Const.RECORDS_INFO request
+ * into per-verb row counts. The buffer holds an isc_info_sql_records
+ * cluster (2-byte total length, then nested isc_info_req_*_count items,
+ * each 2-byte length + little-endian integer) terminated by isc_info_end.
+ */
+export function parseRecordCounts(buffer: Buffer | undefined): RecordCounts {
+    const counts = { selectCount: 0, insertCount: 0, updateCount: 0, deleteCount: 0 };
+    if (!buffer || !buffer.length) {
+        return counts;
+    }
+    // this runs inside a response callback — a malformed/truncated buffer
+    // must yield partial counts, never a throw
+    try {
+        const br = new BlrReader(buffer);
+        while (br.pos < br.buffer.length) {
+            const item = br.readByteCode();
+            if (item === Const.isc_info_end || item === Const.isc_info_truncated) {
+                break;
+            }
+            if (item === Const.isc_info_sql_records) {
+                br.pos += 2; // skip the cluster's total length; nested items follow
+                continue;
+            }
+            switch (item) {
+                case Const.isc_info_req_select_count: counts.selectCount = br.readInt() || 0; break;
+                case Const.isc_info_req_insert_count: counts.insertCount = br.readInt() || 0; break;
+                case Const.isc_info_req_update_count: counts.updateCount = br.readInt() || 0; break;
+                case Const.isc_info_req_delete_count: counts.deleteCount = br.readInt() || 0; break;
+                default:
+                    // unknown item: its 2-byte length prefix tells us how far to skip
+                    br.pos += 2 + br.buffer.readUInt16LE(br.pos);
+            }
+        }
+    } catch (e) {
+        // fall through with whatever was parsed so far
+    }
+    return counts;
+}
+
+//------------------------------------------------------
+
 export class SQLVarText extends SQLVarBase {
     decode(data: XdrReader, lowerV13: boolean, options?: any) {
         let ret;
-        const textEncoding = resolveTextEncoding(options);
-        if (this.subType > 1) {
-            // ToDo: with column charset
-            ret = data.readText(this.length, textEncoding);
-            const encoding = options && options.encoding ? options.encoding : 'UTF8';
-            const width = getFirebirdCharsetWidth(encoding);
-            const charLength = Math.floor(this.length / width);
-            if (ret.length > charLength) {
-                ret = ret.substring(0, charLength);
-            }
-        } else if (this.subType === 0) {
-            // without charset definition
-            ret = data.readText(this.length, textEncoding);
-            const encoding = options && options.encoding ? options.encoding : 'UTF8';
-            const width = getFirebirdCharsetWidth(encoding);
-            const charLength = Math.floor(this.length / width);
+        if (this.subType > 1 || this.subType === 0) {
+            const state = resolveTextState(options);
+            ret = state.codec
+                ? state.codec.decode(data.readBuffer(this.length) || EMPTY_BUFFER)
+                : data.readText(this.length, state.enc);
+            const charLength = Math.floor(this.length / state.width);
             if (ret.length > charLength) {
                 ret = ret.substring(0, charLength);
             }
@@ -218,13 +462,11 @@ export class SQLVarNull extends SQLVarText {
 export class SQLVarString extends SQLVarBase {
     decode(data: XdrReader, lowerV13: boolean, options?: any) {
         let ret;
-        const textEncoding = resolveTextEncoding(options);
-        if (this.subType > 1) {
-            // ToDo: with column charset
-            ret = data.readString(textEncoding);
-        } else if (this.subType === 0) {
-            // without charset definition
-            ret = data.readString(textEncoding);
+        if (this.subType > 1 || this.subType === 0) {
+            const state = resolveTextState(options);
+            ret = state.codec
+                ? state.codec.decode(data.readArray() || EMPTY_BUFFER)
+                : data.readString(state.enc);
         } else {
             ret = data.readBuffer();
         }
@@ -872,12 +1114,30 @@ export class SQLParamDate {
 
 export class SQLParamBool {
     value: any;
-
-    constructor(value: any) {
+    /**
+     * Encode as a real BOOLEAN (blr_bool + xdr opaque byte) instead of the
+     * legacy blr_short 0/1. Set when the DESCRIBED parameter type is
+     * SQL_BOOLEAN: Firebird refuses smallint→BOOLEAN conversion
+     * ("conversion error from string", issue #122), and conversely BOOLEAN
+     * does not convert to numbers — so smallint targets keep the legacy
+     * form for compatibility.
+     */
+    asBoolean: boolean;
+
+    constructor(value: any, asBoolean = false) {
         this.value = value;
+        this.asBoolean = asBoolean;
     }
 
     encode(data: XdrWriter): void {
+        if (this.asBoolean) {
+            // xdr_datum sends booleans as 1 opaque value byte + 3 pad bytes
+            // (NOT a big-endian int: the value byte comes FIRST — addInt(1)
+            // would decode server-side as false). Matches the batch encoder.
+            data.addBuffer(Buffer.from([this.value ? 1 : 0]));
+            data.addAlignment(1);
+            return;
+        }
         if (this.value != null) {
             data.addInt(this.value ? 1 : 0);
         } else {
@@ -887,6 +1147,10 @@ export class SQLParamBool {
     }
 
     calcBlr(blr: BlrWriter): void {
+        if (this.asBoolean) {
+            blr.addByte(Const.blr_bool);
+            return;
+        }
         blr.addByte(Const.blr_short);
         blr.addShort(0);
     }