node-firebird 2.8.1 → 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;
@@ -100,9 +102,22 @@ export type BatchOptions = {
     chunkSize?: number;
 };
 
+/**
+ * Positional query parameters (array), or — when named placeholders are
+ * enabled via the `namedPlaceholders` connection/query option — values by
+ * placeholder name.
+ */
+export type QueryParams = any[] | Record<string, any>;
+
 export type QueryOptions = {
     timeout?: number;
     scrollable?: boolean;
+    /**
+     * Per-query override of the `namedPlaceholders` connection option
+     * (e.g. disable it for one EXECUTE BLOCK statement whose body uses
+     * `:variable` PSQL references).
+     */
+    namedPlaceholders?: boolean;
     /**
      * Abort the query when the signal fires (Firebird 2.5+ / protocol 12+).
      * If the signal is already aborted the query is not sent at all and the
@@ -114,15 +129,32 @@ 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;
     newStatement(query: string, callback: (err: Error | null, statement: Statement) => void): Database;
-    query(query: string, params: any[], callback: QueryCallback, options?: QueryOptions): Database;
-    execute(query: string, params: any[], callback: QueryCallback, options?: QueryOptions): Database;
+    query(query: string, params: QueryParams, callback: QueryCallback, options?: QueryOptions): Database;
+    execute(query: string, params: QueryParams, callback: QueryCallback, options?: QueryOptions): Database;
     /** Bulk-execute in its own transaction, all-or-nothing (Firebird 4.0+). */
-    executeBatch(query: string, rows: any[][], callback?: (err: any, result: BatchResult) => void, options?: BatchOptions): Database;
-    sequentially(query: string, params: any[], rowCallback: SequentialCallback, callback: SimpleCallback, options?: QueryOptions | boolean): Database;
+    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;
@@ -133,10 +165,10 @@ export interface Database {
 
     // Promise / async-await API (see README § Promises / async–await).
     // Result metadata is only available through the callback API.
-    queryAsync<T = any>(query: string, params?: any[], options?: QueryOptions): Promise<T[]>;
-    executeAsync<T = any>(query: string, params?: any[], options?: QueryOptions): Promise<T[]>;
-    executeBatchAsync(query: string, rows: any[][], options?: BatchOptions): Promise<BatchResult>;
-    sequentiallyAsync(query: string, params: any[] | undefined, rowCallback: SequentialCallback, options?: QueryOptions | boolean): Promise<void>;
+    queryAsync<T = any>(query: string, params?: QueryParams, options?: QueryOptions): Promise<T[]>;
+    executeAsync<T = any>(query: string, params?: QueryParams, options?: QueryOptions): Promise<T[]>;
+    executeBatchAsync(query: string, rows: QueryParams[], options?: BatchOptions): Promise<BatchResult>;
+    sequentiallyAsync(query: string, params: QueryParams | undefined, rowCallback: SequentialCallback, options?: QueryOptions | boolean): Promise<void>;
     sequentiallyAsync(query: string, rowCallback: SequentialCallback, options?: QueryOptions | boolean): Promise<void>;
     transactionAsync(options?: TransactionOptions | Isolation): Promise<Transaction>;
     startTransactionAsync(options?: TransactionOptions | Isolation): Promise<Transaction>;
@@ -158,21 +190,27 @@ export interface Database {
 
 export interface Transaction {
     newStatement(query: string, callback: (err: Error | null, statement: Statement) => void): void;
-    query(query: string, params: any[], callback: QueryCallback, options?: QueryOptions): void;
-    execute(query: string, params: any[], callback: QueryCallback, options?: QueryOptions): void;
+    query(query: string, params: QueryParams, callback: QueryCallback, options?: QueryOptions): void;
+    execute(query: string, params: QueryParams, callback: QueryCallback, options?: QueryOptions): void;
     /** Bulk-execute within this transaction; per-record failures do not roll back (Firebird 4.0+). */
-    executeBatch(query: string, rows: any[][], callback?: (err: any, result: BatchResult) => void, options?: BatchOptions): void;
-    sequentially(query: string, params: any[], rowCallback: SequentialCallback, callback: SimpleCallback, options?: QueryOptions | boolean): Database;
+    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;
     rollbackRetaining(callback?: SimpleCallback): void;
 
     // Promise / async-await API
-    queryAsync<T = any>(query: string, params?: any[], options?: QueryOptions): Promise<T[]>;
-    executeAsync<T = any>(query: string, params?: any[], options?: QueryOptions): Promise<T[]>;
-    executeBatchAsync(query: string, rows: any[][], options?: BatchOptions): Promise<BatchResult>;
-    sequentiallyAsync(query: string, params: any[] | undefined, rowCallback: SequentialCallback, options?: QueryOptions | boolean): Promise<void>;
+    queryAsync<T = any>(query: string, params?: QueryParams, options?: QueryOptions): Promise<T[]>;
+    executeAsync<T = any>(query: string, params?: QueryParams, options?: QueryOptions): Promise<T[]>;
+    executeBatchAsync(query: string, rows: QueryParams[], options?: BatchOptions): Promise<BatchResult>;
+    sequentiallyAsync(query: string, params: QueryParams | undefined, rowCallback: SequentialCallback, options?: QueryOptions | boolean): Promise<void>;
     sequentiallyAsync(query: string, rowCallback: SequentialCallback, options?: QueryOptions | boolean): Promise<void>;
     newStatementAsync(query: string): Promise<Statement>;
     commitAsync(): Promise<void>;
@@ -185,17 +223,17 @@ export interface Statement {
     close(callback?: SimpleCallback): void;
     drop(callback?: SimpleCallback): void;
     release(callback?: SimpleCallback): void;
-    execute(transaction: Transaction, params: any[], callback: QueryCallback, options?: QueryOptions): void;
+    execute(transaction: Transaction, params: QueryParams, callback: QueryCallback, options?: QueryOptions): void;
     fetch(transaction: Transaction, count: number, callback: QueryCallback): void;
     fetchScroll(transaction: Transaction, direction: 'NEXT' | 'PRIOR' | 'FIRST' | 'LAST' | 'ABSOLUTE' | 'RELATIVE' | number, offset: number, count: number, callback: QueryCallback): void;
     fetchAll(transaction: Transaction, callback: QueryCallback): void;
 
     /** Execute this prepared statement once per row (Firebird 4.0+ batch API). */
-    executeBatch(transaction: Transaction, rows: any[][], callback?: (err: any, result: BatchResult) => void, options?: BatchOptions): void;
+    executeBatch(transaction: Transaction, rows: QueryParams[], callback?: (err: any, result: BatchResult) => void, options?: BatchOptions): void;
 
     // Promise / async-await API
-    executeAsync(transaction: Transaction, params?: any[], options?: QueryOptions): Promise<any>;
-    executeBatchAsync(transaction: Transaction, rows: any[][], options?: BatchOptions): Promise<BatchResult>;
+    executeAsync(transaction: Transaction, params?: QueryParams, options?: QueryOptions): Promise<any>;
+    executeBatchAsync(transaction: Transaction, rows: QueryParams[], options?: BatchOptions): Promise<BatchResult>;
     fetchAsync(transaction: Transaction, count: number | 'all'): Promise<any>;
     fetchScrollAsync(transaction: Transaction, direction: 'NEXT' | 'PRIOR' | 'FIRST' | 'LAST' | 'ABSOLUTE' | 'RELATIVE' | number, offset?: number, count?: number): Promise<any>;
     fetchAllAsync(transaction: Transaction): Promise<any>;
@@ -266,6 +304,26 @@ export interface Options {
     blobReadChunkSize?: number;
     wireCrypt?: number; // WIRE_CRYPT_DISABLE or WIRE_CRYPT_ENABLE
     wireCompression?: boolean;
+    /**
+     * Enable named placeholders: SQL may use `:name` markers and params may
+     * be a values-by-name object (`db.query('... WHERE id = :id', { id: 1 })`).
+     * Placeholders are rewritten client-side to positional `?` before
+     * preparing; positional arrays keep working unchanged. Off by default
+     * because `EXECUTE BLOCK` bodies use `:variable` for PSQL references —
+     * with this option on, run such statements with positional params or a
+     * 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;
@@ -297,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'`
      */
@@ -323,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+)**
      *
@@ -331,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
 }
@@ -542,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

@@ -0,0 +1,204 @@
+/***************************************
+ *
+ *   Connection URI strings
+ *
+ ***************************************/
+
+import type { Options } from './types';
+
+/**
+ * Option keys coerced to boolean when they arrive as URI query parameters.
+ * "1"/"true"/"yes"/"on" (case-insensitive) → true, everything else → false.
+ */
+const BOOLEAN_KEYS = new Set([
+    'lowercase_keys', 'blobAsText', 'wireCompression', 'manager',
+    'namedPlaceholders', 'enableKeepAlive',
+]);
+
+/** Option keys coerced to number when they arrive as URI query parameters. */
+const NUMBER_KEYS = new Set([
+    'port', 'pageSize', 'timeout', 'retryConnectionInterval',
+    'blobChunkSize', 'blobReadChunkSize', 'wireCrypt', 'parallelWorkers',
+    'maxInlineBlobSize', 'maxNegotiatedProtocols', 'connectTimeout',
+    'min', 'idleTimeoutMillis', 'keepAliveInitialDelay',
+]);
+
+function coerce(key: string, value: string): any {
+    if (BOOLEAN_KEYS.has(key)) {
+        return /^(1|true|yes|on)$/i.test(value);
+    }
+    if (NUMBER_KEYS.has(key)) {
+        var n = Number(value);
+        if (Number.isNaN(n)) {
+            throw new Error('Invalid numeric value for connection URI option "' + key + '": ' + value);
+        }
+        return n;
+    }
+    return value;
+}
+
+/**
+ * Parse a firebird:// connection URI into an options object.
+ *
+ *   firebird://user:password@host:port/database?option=value&...
+ *
+ * The database part:
+ *   firebird://host/employee              → alias "employee"
+ *   firebird://host//var/db/prod.fdb      → absolute path "/var/db/prod.fdb"
+ *   firebird://host/var/db/prod.fdb       → "/var/db/prod.fdb" (a database
+ *                                           part with slashes is a path —
+ *                                           aliases cannot contain "/")
+ *   firebird://host/C:/db/prod.fdb        → Windows path "C:/db/prod.fdb"
+ *
+ * Credentials and the database path are URL-decoded, so reserved characters
+ * can be percent-encoded (e.g. p%40ss for "p@ss"). Query parameters map
+ * 1:1 to option keys and are coerced to the option's type (booleans accept
+ * 1/true/yes/on). `user` and `password` may be given as query parameters
+ * instead of in the authority.
+ */
+export function parseConnectionUri(uri: string): Options {
+    var url: URL;
+    try {
+        url = new URL(uri);
+    } catch (e) {
+        throw new Error('Invalid connection URI: ' + uri);
+    }
+
+    if (url.protocol !== 'firebird:') {
+        throw new Error('Unsupported connection URI scheme "' + url.protocol.replace(/:$/, '') +
+            '" (expected firebird://...)');
+    }
+
+    var options: any = {};
+
+    if (url.hostname) {
+        // URL keeps IPv6 hostnames bracketed ([::1]); net.connect wants them bare
+        options.host = url.hostname.replace(/^\[(.*)\]$/, '$1');
+    }
+    if (url.port) {
+        options.port = Number(url.port);
+    }
+    if (url.username) {
+        options.user = decodeURIComponent(url.username);
+    }
+    if (url.password) {
+        options.password = decodeURIComponent(url.password);
+    }
+
+    var database = decodeURIComponent(url.pathname || '');
+    if (database.startsWith('/')) {
+        database = database.slice(1);
+    }
+    // A database part with path separators is a filesystem path, not an
+    // alias (aliases cannot contain "/") — restore the leading slash unless
+    // it is a Windows drive path or already absolute (double-slash form).
+    if (database.includes('/') && !database.startsWith('/') && !/^[A-Za-z]:\//.test(database)) {
+        database = '/' + database;
+    }
+    if (database) {
+        options.database = database;
+    }
+
+    url.searchParams.forEach(function(value, key) {
+        options[key] = coerce(key, value);
+    });
+
+    return options as Options;
+}
+
+/**
+ * Parse a traditional ("old style") Firebird connection string:
+ *
+ *   [host[/port]:]{path | alias}
+ *
+ *   employee                              → alias "employee" (default host)
+ *   /var/fb/prod.fdb                      → local path (default host)
+ *   C:\fbdata\prod.fdb                    → Windows path — a single character
+ *                                           before ":" is a drive letter, not
+ *                                           a host (same rule as Firebird)
+ *   db.example.com:employee               → host + alias
+ *   db.example.com/3051:/var/fb/prod.fdb  → host + port + path
+ *   myserver:C:\fbdata\prod.fdb           → host + Windows path
+ *   [::1]/3050:employee                   → IPv6 host + port + alias
+ *
+ * Unlike firebird:// URIs, traditional strings carry no credentials or
+ * options — the driver defaults apply (SYSDBA/masterkey, port 3050).
+ * The port must be numeric; /etc/services names are not resolved.
+ */
+export function parseOldStyleConnectionString(str: string): Options {
+    var options: any = {};
+    var host: string | null = null;
+    var port: string | null = null;
+    var database = str;
+
+    var ipv6 = /^\[([^\]]+)\](?:\/([^:]*))?:(.*)$/.exec(str);
+    if (ipv6) {
+        host = ipv6[1];
+        port = ipv6[2] !== undefined ? ipv6[2] : null;
+        database = ipv6[3];
+    } else {
+        var colon = str.indexOf(':');
+        if (colon === 0) {
+            throw new Error('Invalid connection string (empty host): ' + str);
+        }
+        // colon === 1 → single character before ":" is a drive letter;
+        // colon === -1 → no host part. Both leave the whole string as database.
+        if (colon > 1) {
+            var hostPart = str.slice(0, colon);
+            database = str.slice(colon + 1);
+            var slash = hostPart.indexOf('/');
+            if (slash !== -1) {
+                host = hostPart.slice(0, slash);
+                port = hostPart.slice(slash + 1);
+                if (!host) {
+                    throw new Error('Invalid connection string (empty host): ' + str);
+                }
+            } else {
+                host = hostPart;
+            }
+        }
+    }
+
+    if (!database) {
+        throw new Error('Invalid connection string (empty database): ' + str);
+    }
+
+    if (host) {
+        options.host = host;
+    }
+    if (port !== null) {
+        var n = Number(port);
+        if (!/^\d+$/.test(port) || n < 1 || n > 65535) {
+            throw new Error('Invalid port in connection string "' + str +
+                '" (service names are not supported — use a numeric port)');
+        }
+        options.port = n;
+    }
+    options.database = database;
+
+    return options as Options;
+}
+
+const URI_SCHEME = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//;
+
+/**
+ * Parse any connection string the driver accepts: a firebird:// URI, or a
+ * traditional [host[/port]:]database string when there is no scheme.
+ */
+export function parseConnectionString(str: string): Options {
+    return URI_SCHEME.test(str)
+        ? parseConnectionUri(str)
+        : parseOldStyleConnectionString(str);
+}
+
+/**
+ * Accept either an options object or a connection string (firebird:// URI
+ * or traditional host[/port]:database) everywhere options are taken.
+ * Strings are parsed; objects pass through unchanged.
+ */
+export function normalizeOptions<T>(options: T | string): T {
+    if (typeof options === 'string') {
+        return parseConnectionString(options) as T;
+    }
+    return options;
+}