@fast-firebird/core
Classes
| Class | Description |
|---|---|
| Attachment | An open database attachment. Obtain via connect() or createDatabase(). |
| Blob | A lazy handle to a Firebird blob. Nothing is fetched until you call a method. VALID ONLY until its transaction closes — Firebird blob ids are transaction-scoped; reading one after commit throws FirebirdBlobError. |
| EventChannel | Per-attachment async event channel. Firebird gives a connection exactly one async aux port; every subscription flows over it and is demultiplexed by request id (rid). Created lazily on the first subscription and torn down when the last one closes. |
| EventListener | A live subscription to Firebird POST_EVENT notifications. |
| FirebirdAuthError | - |
| FirebirdBatchError | A batch row was rejected by the server (default, non-continueOnError mode). |
| FirebirdBlobError | Misuse of a lazy Blob handle (e.g. read after its transaction closed). |
| FirebirdConnectionError | - |
| FirebirdError | - |
| FirebirdParamError | Bad use of named parameters (unknown syntax mix, missing value). |
| FirebirdProtocolError | - |
| Pool | A pool of Firebird connections. Each pooled connection is a full Attachment with its own statement cache, so warm statements survive across acquire/release cycles for a given physical connection — unless statementCache: 'clear-on-release' opts out (DDL-friendly mode). Acquire is LIFO (most recently released first), so the warmest cache is always the one handed out next. |
| PreparedStatement | An explicitly prepared statement, pinned outside the LRU cache. Re-execution costs a single round trip. Close it when done. |
| ScriptParseError | - |
| Service | A connection to the Firebird Service Manager (service_mgr). Supports server metadata queries and streaming service actions (e.g. database statistics). Uses the same SRP handshake + wire crypt as a normal attachment. Call disconnect() when done. |
| Transaction | - |
| ZonedDate | A TIMESTAMP/TIME WITH TIME ZONE value with its zone preserved. |
Interfaces
| Interface | Description |
|---|---|
| BatchOptions | - |
| BatchResult | - |
| BatchRowError | - |
| BlobColumnModes | Per-column blob configuration: a base mode plus named overrides. Column names match the row key (alias-aware) — bare (DOC) or FROM-alias qualified (A.DOC), case-insensitive. A column listed in both arrays is a configuration error (throws at query time). |
| CharsetPage | A pluggable charset codec, matched by name against Firebird charset names and user-facing encoding options. |
| CharsetStreamDecoder | Stateful decoder for chunked decoding (multi-byte pages carry split characters across chunks). |
| ColumnInfo | One output column of a statement run, in row/position order. |
| DecodeContext | Context passed to transcode adapters when decoding a value read from the server. |
| EncodeContext | Context passed to transcode adapters when encoding a parameter for the server. |
| ExecuteScriptOptions | - |
| FirebirdConnectionOptions | - |
| FirebirdTranscodeAdapter | - |
| LegacyOptionAliases | Legacy node-firebird option names accepted at the boundary. |
| NBackupOptions | - |
| NRestoreOptions | - |
| ParsedStatement | - |
| ParseScriptOptions | - |
| PoolOptions | - |
| PoolStats | - |
| QueryOptions | Per-statement options. |
| QueryResult | - |
| RestartOptions | - |
| RewrittenSql | - |
| ScriptExecutionResult | - |
| ServerInfo | - |
| ServiceConnectOptions | - |
| StatementResult | - |
| TransactionOptions | - |
Type Aliases
| Type Alias | Description |
|---|---|
| BatchRow | One batch row: positional values, or an object for @name SQL. |
| BatchRows | - |
| BlobMode | Blob fetch mode: which blob columns come back as lazy Blob handles vs eagerly materialized values (text → string a.k.a. memo, binary → Buffer). |
| BlobReadAheadOption | Read-ahead for LAZY blobs in queryStream: while the consumer processes row N, the driver prefetches upcoming rows' blob contents in background op-lock slices, so .buffer()/.text()/.stream() resolve without wire round trips. Purely an optimization — skipped rows, out-of-order reads, or budget-exceeding blobs silently fall back to the on-demand path. |
| BlobsOption | The blobs option: a plain mode or the per-column form. |
| ClientCommand | A script statement that is a client-side command — executed by the driver (isql-style), never sent to the server as DSQL. op: 'unsupported' marks a statement whose HEAD is transaction control (so it must not reach the server) but whose details the driver cannot process — executeScript rejects it with reason. |
| ConnectInput | - |
| DecodeErrorMode | How invalid/undefined byte sequences decode: U+FFFD ('replace') or throw ('strict'). |
| IsolationLevel | - |
| NamedParams | Values supplied by name for a @name-parameterized statement. |
| ParamValue | - |
| QueryParams | Either positional (array) or named (object) parameter values. |
| Row | - |
| StatementKind | Statement classification from the leading keyword(s). A HEURISTIC for 'ddl'/'dml'/'other': it cannot see through EXECUTE BLOCK bodies (which can hide DDL via EXECUTE STATEMENT) — those classify as 'other'. Intended for commit-after-DDL policies (Delphi AutoDDL style), not as a security boundary. 'client' is EXACT, not heuristic: the statement is a client-side command (see ClientCommand) that executeScript processes driver-side and never sends to the server. |
| WireCryptOption | - |
Variables
| Variable | Description |
|---|---|
| DEFAULT_LOCK_TIMEOUT_SECONDS | Driver default lock wait, in seconds. Firebird's native default is WAIT with NO timeout — a blocked statement (a lock conflict, or DDL against metadata pinned by any prepared statement anywhere) waits forever, which reads as a hang. The driver defaults to a 10s timeout instead: blocked work fails with a clear "lock time-out on wait transaction" error. Opt back into Firebird's unbounded wait explicitly with wait: true. |
| win1252 | Built-in Windows-1252 page — the codepage of the legacy-Delphi databases this driver exists for. Decodes/encodes without touching iconv-lite; benchmarked ~3–4× faster per cell than the iconv path (Jira MFF-4). |
Functions
| Function | Description |
|---|---|
| aliasPage | A transliteration page that makes one charset name decode/encode as another — the one-line fix for mislabeled legacy columns (Jira MFF-4): |
| classifyClientCommand | Recognize a client-side script command (isql-style). Returns null for anything that should go to the server as DSQL — including SAVEPOINT x, RELEASE SAVEPOINT x and ROLLBACK [WORK] TO [SAVEPOINT] x, which operate safely INSIDE the current transaction. Comment-tolerant, case-insensitive. Recognition keys on the statement head: once the head is transaction control (COMMIT/ROLLBACK/SET TRANSACTION), the statement is claimed as a client command even when its details cannot be processed — it comes back as op: 'unsupported' instead of null, so executeScript rejects it by name rather than letting it slip to the server. |
| classifyStatement | Classify a statement by its leading keyword(s). Exported for reuse. |
| commentRanges | All comment ranges (line and block) in sql as [start, end) index pairs — computed by the SAME scanner parseScript uses, so a preprocessor's "is index N inside a comment?" verdict cannot diverge from the statement splitter on q-literals, -- inside quoted identifiers, or a block-comment opener inside a string. Throws ScriptParseError on the same malformed input parseScript rejects (unterminated block comment / string / q-literal). |
| connect | - |
| connectService | - |
| createDatabase | - |
| createPool | Create (and optionally warm up) a connection pool. |
| defineSingleBytePage | Builds a complete single-byte CharsetPage from a 256-character table: table[b] is the character byte b decodes to; U+FFFD marks a byte the codepage leaves undefined (decodes to U+FFFD in 'replace' mode, throws in 'strict', and never enters the reverse map). |
| parseScript | Parse a Firebird script into individual statements. |
| prefetchBlobs | Functional alias for Blob.prefetch: bulk-materialize lazy handles. |
| rewriteNamedParams | Rewrite @name markers to ?, collecting the names in positional order. A repeated name yields one ? (and one entry in names) per occurrence — Firebird has no parameter reuse, so the value is bound once per slot. |
| stripComments | Blank out every comment, LENGTH-PRESERVING: comment characters become spaces but newlines survive, so indexes, line and column positions in the result match the input exactly. Same scanner (and same errors) as parseScript/commentRanges. |