node-firebird 2.9.0 → 2.10.0

package/src/types.ts

@@ -5,6 +5,8 @@
 // They now live in the TypeScript source tree and are compiled into the
 // published declaration files.
 
+import type { Readable } from 'stream';
+
 export type DatabaseCallback = (err: any, db: Database) => void;
 export type TransactionCallback = (err: any, transaction: Transaction) => void;
 export type QueryCallback = (err: any, result: any[]) => void;
@@ -127,6 +129,16 @@ export type QueryOptions = {
     signal?: AbortSignal;
 }
 
+export type QueryStreamOptions = QueryOptions & {
+    /**
+     * Rows buffered internally before fetching pauses (object-mode
+     * Readable highWaterMark, default 16).
+     */
+    highWaterMark?: number;
+    /** Emit array rows instead of objects (like db.execute). */
+    asObject?: boolean;
+}
+
 export interface Database {
     detach(callback?: SimpleCallback): Database;
     transaction(options: TransactionOptions|Isolation|TransactionCallback, callback?: TransactionCallback): Database;
@@ -136,6 +148,13 @@ export interface Database {
     /** Bulk-execute in its own transaction, all-or-nothing (Firebird 4.0+). */
     executeBatch(query: string, rows: QueryParams[], callback?: (err: any, result: BatchResult) => void, options?: BatchOptions): Database;
     sequentially(query: string, params: QueryParams, rowCallback: SequentialCallback, callback: SimpleCallback, options?: QueryOptions | boolean): Database;
+    /**
+     * Run `query` and return an object-mode Readable emitting one row per
+     * chunk, with backpressure (fetching pauses while the buffer is full).
+     * Runs in its own transaction. Destroying the stream early aborts the
+     * fetch and releases the statement.
+     */
+    queryStream(query: string, params?: QueryParams, options?: QueryStreamOptions): Readable;
     drop(callback: SimpleCallback): void;
     escape(value: any): string;
     attachEvent(callback: any): this;
@@ -176,6 +195,12 @@ export interface Transaction {
     /** Bulk-execute within this transaction; per-record failures do not roll back (Firebird 4.0+). */
     executeBatch(query: string, rows: QueryParams[], callback?: (err: any, result: BatchResult) => void, options?: BatchOptions): void;
     sequentially(query: string, params: QueryParams, rowCallback: SequentialCallback, callback: SimpleCallback, options?: QueryOptions | boolean): Database;
+    /**
+     * Run `query` inside this transaction and return an object-mode
+     * Readable emitting one row per chunk, with backpressure. The
+     * transaction is NOT committed when the stream ends.
+     */
+    queryStream(query: string, params?: QueryParams, options?: QueryStreamOptions): Readable;
     commit(callback?: SimpleCallback): void;
     commitRetaining(callback?: SimpleCallback): void;
     rollback(callback?: SimpleCallback): void;
@@ -289,6 +314,16 @@ export interface Options {
      * per-query `namedPlaceholders: false` override.
      */
     namedPlaceholders?: boolean;
+    /**
+     * TCP keepalive probing to detect dead/stale connections (same option
+     * names as mysql2). On by default; set false to disable.
+     */
+    enableKeepAlive?: boolean;
+    /**
+     * Milliseconds a socket must be idle before the first TCP keepalive
+     * probe is sent (default 60000). Ignored when enableKeepAlive is false.
+     */
+    keepAliveInitialDelay?: number;
     pluginName?: string;
     parallelWorkers?: number;
     maxInlineBlobSize?: number;
@@ -320,11 +355,11 @@ export interface Options {
     /**
      * **Firebird 6.0+ only (Protocol 20+)**
      *
-     * Sets the session's current schema at connection time.  Equivalent to
-     * executing `SET SCHEMA <name>` immediately after connecting.
-     *
-     * Unqualified object references (tables, procedures, etc.) that do not
-     * match any schema in the `searchPath` fall back to `PUBLIC`.
+     * Sets the session's current schema at connection time. `CURRENT_SCHEMA`
+     * in Firebird is the first existing schema of the search path, so this
+     * option is implemented by putting the schema at the front of the
+     * `searchPath` sent to the server (with `PUBLIC` kept as a fallback when
+     * no explicit `searchPath` is given).
      *
      * Example: `defaultSchema: 'myapp'`
      */
@@ -346,6 +381,18 @@ export interface Options {
      * (typically `PUBLIC` then `SYSTEM`).
      */
     searchPath?: string | string[];
+    /**
+     * **Firebird 6.0+ only**
+     *
+     * Owner of a newly created database (`isc_dpb_owner`), allowing a
+     * superuser to create a database owned by another user
+     * ([firebird#7718](https://github.com/FirebirdSQL/firebird/issues/7718)).
+     * Only honored by `create`/`attachOrCreate` when the database is
+     * created; ignored on plain attach and by older servers.
+     *
+     * Example: `owner: 'APP_OWNER'`
+     */
+    owner?: string;
     /**
      * **Firebird 6.0+ only (Protocol 20+)**
      *
@@ -354,8 +401,58 @@ export interface Options {
      * text/BLOB columns back into JavaScript objects/arrays.
      */
     jsonAsObject?: boolean;
+    /**
+     * Custom type parser (mysql2-style). Called for every column value of
+     * every result row (including NULLs); whatever it returns becomes the
+     * value in the row. Call `next()` to get the value the driver would
+     * produce by default (after `blobAsText`/`jsonAsObject` are applied).
+     *
+     * ```js
+     * typeCast: (column, next) =>
+     *     column.typeName === 'INT64' ? Number(next()) : next()
+     * ```
+     *
+     * Non-text BLOB columns reach the hook as the usual fetch function;
+     * text BLOBs with `blobAsText` reach it as the resolved string. The
+     * hook must be a pure function: a row can be decoded more than once
+     * when a response spans TCP packets.
+     */
+    typeCast?: TypeCastFunction;
+    /**
+     * Per-connection LRU cache of prepared statements (like mysql2's
+     * statement cache). `db.query`/`tx.query` and friends transparently
+     * reuse the prepared handle for a repeated SQL string, skipping the
+     * prepare round-trip on hot paths. The number is the maximum of idle
+     * cached statements; least-recently-used ones are dropped over the
+     * limit. 0 / unset = disabled. Statements that failed and DDL are
+     * never cached; concurrent runs of the same SQL never share a
+     * statement (extra preparations are simply not cached).
+     */
+    statementCacheSize?: number;
+}
+
+/** Column metadata passed to the {@link Options.typeCast} hook. */
+export interface TypeCastColumn {
+    /** Firebird SQL type code (see the exported `SQL_TYPES` map). */
+    type: number;
+    /** Friendly name of the type code: 'VARYING', 'INT64', 'BLOB', ... */
+    typeName: string;
+    /** Column subtype (e.g. 1 = text for BLOBs; charset id for strings). */
+    subType?: number;
+    /** Negative decimal scale for NUMERIC/DECIMAL columns (e.g. -2). */
+    scale?: number;
+    /** Declared length in bytes. */
+    length?: number;
+    /** Column name in the table. */
+    field?: string;
+    /** Table (relation) name. */
+    relation?: string;
+    /** Alias used in the SELECT list (the row key for object rows). */
+    alias?: string;
 }
 
+export type TypeCastFunction = (column: TypeCastColumn, next: () => any) => any;
+
 export interface SvcMgrOptions extends Options {
     manager: true; // Attach to ServiceManager
 }
@@ -565,4 +662,42 @@ export interface ServiceManager {
     hasRunningAction(options: ReadableOptions, callback: ReadableCallback): void;
     readusers(options: ReadableOptions, callback: ReadableCallback): void;
     readlimbo(options: ReadableOptions, callback: ReadableCallback): void;
+
+    // Promise / async-await API (see README § Promises / async–await).
+    detachAsync(force?: boolean): Promise<void>;
+    backupAsync(options: BackupOptions): Promise<NodeJS.ReadableStream>;
+    nbackupAsync(options: BackupOptions): Promise<NodeJS.ReadableStream>;
+    restoreAsync(options: RestoreOptions): Promise<NodeJS.ReadableStream>;
+    nrestoreAsync(options: NRestoreOptions): Promise<NodeJS.ReadableStream>;
+    setDialectAsync(db: string, dialect: 1 | 3): Promise<NodeJS.ReadableStream>;
+    setSweepintervalAsync(db: string, interval: number): Promise<any>;
+    setCachebufferAsync(db: string, nbpages: any): Promise<NodeJS.ReadableStream>;
+    BringOnlineAsync(db: string): Promise<NodeJS.ReadableStream>;
+    ShutdownAsync(db: string, kind: ShutdownKind, delay: number, mode?: ShutdownMode): Promise<NodeJS.ReadableStream>;
+    setShadowAsync(db: string, val: boolean): Promise<NodeJS.ReadableStream>;
+    setForcewriteAsync(db: string, val: boolean): Promise<NodeJS.ReadableStream>;
+    setReservespaceAsync(db: string, val: boolean): Promise<NodeJS.ReadableStream>;
+    setReadonlyModeAsync(db: string): Promise<NodeJS.ReadableStream>;
+    setReadwriteModeAsync(db: string): Promise<NodeJS.ReadableStream>;
+    validateAsync(options: ValidateOptions): Promise<NodeJS.ReadableStream>;
+    commitAsync(db: string, transactid: number): Promise<NodeJS.ReadableStream>;
+    rollbackAsync(db: string, transactid: number): Promise<NodeJS.ReadableStream>;
+    recoverAsync(db: string, transactid: number): Promise<NodeJS.ReadableStream>;
+    getStatsAsync(options: StatsOptions): Promise<NodeJS.ReadableStream>;
+    getLogAsync(options: ReadableOptions): Promise<NodeJS.ReadableStream>;
+    getUsersAsync(username?: string | null): Promise<ServerInfo>;
+    addUserAsync(username: string, password: string, info?: UserInfo): Promise<NodeJS.ReadableStream>;
+    editUserAsync(username: string, info: UserInfo): Promise<NodeJS.ReadableStream>;
+    removeUserAsync(username: string, rolename?: string | null): Promise<NodeJS.ReadableStream>;
+    getFbserverInfosAsync(infos?: ServerInfoReq, options?: { buffersize?: number, timeout?: number }): Promise<ServerInfo>;
+    startTraceAsync(options: TraceOptions): Promise<NodeJS.ReadableStream>;
+    suspendTraceAsync(options: TraceOptions): Promise<NodeJS.ReadableStream>;
+    resumeTraceAsync(options: TraceOptions): Promise<NodeJS.ReadableStream>;
+    stopTraceAsync(options: TraceOptions): Promise<NodeJS.ReadableStream>;
+    getTraceListAsync(options?: ReadableOptions): Promise<NodeJS.ReadableStream>;
+    readlineAsync(options?: ReadableOptions): Promise<{ result: number, line: string }>;
+    readeofAsync(options?: ReadableOptions): Promise<{ result: number, line: string }>;
+    hasRunningActionAsync(options?: ReadableOptions): Promise<any>;
+    readusersAsync(options?: ReadableOptions): Promise<any>;
+    readlimboAsync(options?: ReadableOptions): Promise<any>;
 }

package/src/unix-crypt.ts

@@ -152,25 +152,25 @@ var SPTRANS=
             0x8200020, 32768, 0x208020 ]
 ];
 
-function hPermOp(a, n, m) {
+function hPermOp(a: number, n: number, m: number) {
     var t = (a << 16 - n ^ a) & m;
     a = a ^ t ^ t >>> 16 - n;
     return a;
 }
 
-function intToFourBytes(iValue, b, offset) {
+function intToFourBytes(iValue: number, b: Buffer, offset: number) {
     b[offset++] = iValue & 0xff;
     b[offset++] = iValue >>> 8 & 0xff;
     b[offset++] = iValue >>> 16 & 0xff;
     b[offset++] = iValue >>> 24 & 0xff;
 }
 
-function byteToUnsigned(b) {
+function byteToUnsigned(b: number) {
     var value = b;
     return value < 0 ? value + 256 : value;
 }
 
-function fourBytesToInt(b, offset) {
+function fourBytesToInt(b: Buffer, offset: number) {
     var value = byteToUnsigned(b[offset++]);
     value |= byteToUnsigned(b[offset++]) << 8;
     value |= byteToUnsigned(b[offset++]) << 16;
@@ -178,7 +178,7 @@ function fourBytesToInt(b, offset) {
     return value;
 }
 
-function permOp(a, b, n, m, results) {
+function permOp(a: number, b: number, n: number, m: number, results: number[]) {
     var t = (a >>> n ^ b) & m;
     a ^= t << n;
     b ^= t;
@@ -186,8 +186,8 @@ function permOp(a, b, n, m, results) {
     results[1] = b;
 }
 
-function desSetKey(key) {
-    var schedule = [];
+function desSetKey(key: Buffer) {
+    var schedule: number[] = [];
     var c = fourBytesToInt(key, 0);
     var d = fourBytesToInt(key, 4);
     var results = [0, 0];
@@ -232,7 +232,7 @@ function desSetKey(key) {
     return schedule;
 }
 
-function dEncrypt(el, r, s, e0, e1, sArr) {
+function dEncrypt(el: number, r: number, s: number, e0: number, e1: number, sArr: number[]) {
     var v = r ^ r >>> 16;
     var u = v & e0;
     v &= e1;
@@ -245,7 +245,7 @@ function dEncrypt(el, r, s, e0, e1, sArr) {
     return el;
 }
 
-function body(schedule, eSwap0, eSwap1) {
+function body(schedule: number[], eSwap0: number, eSwap1: number) {
     var left = 0;
     var right = 0;
     var t = 0;

package/src/uri.ts

@@ -12,7 +12,7 @@ import type { Options } from './types';
  */
 const BOOLEAN_KEYS = new Set([
     'lowercase_keys', 'blobAsText', 'wireCompression', 'manager',
-    'namedPlaceholders',
+    'namedPlaceholders', 'enableKeepAlive',
 ]);
 
 /** Option keys coerced to number when they arrive as URI query parameters. */
@@ -20,7 +20,7 @@ const NUMBER_KEYS = new Set([
     'port', 'pageSize', 'timeout', 'retryConnectionInterval',
     'blobChunkSize', 'blobReadChunkSize', 'wireCrypt', 'parallelWorkers',
     'maxInlineBlobSize', 'maxNegotiatedProtocols', 'connectTimeout',
-    'min', 'idleTimeoutMillis',
+    'min', 'idleTimeoutMillis', 'keepAliveInitialDelay',
 ]);
 
 function coerce(key: string, value: string): any {