Class: Blob

Defined in: packages/core/src/api/blob.ts:41

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.

head(n) reads just the first bytes (magic-number sniffing) and KEEPS the server handle open at its position — a later buffer()/stream() resumes from there instead of re-transferring (segmented blobs are forward-only).

Properties

Property	Modifier	Type	Description	Defined in
subType	readonly	number	Blob subtype: 0 = binary, 1 = text.	packages/core/src/api/blob.ts:53

Methods

buffer()

buffer(): Promise<Buffer<ArrayBufferLike>>;

Defined in: packages/core/src/api/blob.ts:197

Materialize the full blob as a Buffer (cached; subsequent calls are free).

Returns

Promise<Buffer<ArrayBufferLike>>

---

close()

close(): Promise<void>;

Defined in: packages/core/src/api/blob.ts:182

Release an open head() cursor without finishing the read. Resets the cursor entirely — a later read starts from byte 0 again. No-op when nothing is open.

Returns

Promise<void>

---

head()

head(n): Promise<Buffer<ArrayBufferLike>>;

Defined in: packages/core/src/api/blob.ts:126

Read the first n bytes (e.g. a file's magic number) and keep the server handle open at its position: a later buffer(), stream() or head(m > n) RESUMES the transfer instead of starting over. Returns raw bytes (no charset decode); fewer than n when the blob is shorter. Release an unfinished cursor early with close() (otherwise it's freed with the transaction).

Parameters

Parameter	Type
n	number

Returns

Promise<Buffer<ArrayBufferLike>>

---

size()

size(): Promise<number>;

Defined in: packages/core/src/api/blob.ts:270

Total byte length via op_info_blob (one round trip; opens + closes the blob).

Returns

Promise<number>

---

stream()

stream(opts?): Readable;

Defined in: packages/core/src/api/blob.ts:289

Stream the blob in backpressured chunks (one op_get_segment per pull). One-shot: consume once. Prefer this for large blobs to avoid buffering. Abandoning the stream early (destroy(), break out of for-await, or an error) closes the server-side blob handle — nothing leaks until tx end.

Parameters

Parameter	Type
opts	{ chunkSize?: number; }
opts.chunkSize?	number

Returns

Readable

---

text()

text(encoding?): Promise<string>;

Defined in: packages/core/src/api/blob.ts:237

Materialize as a decoded string. Subtype-1 (text) blobs use the column's charset codec; binary blobs use encoding (default utf8).

Parameters

Parameter	Type
encoding?	BufferEncoding

Returns

Promise<string>

---

toFile()

toFile(path): Promise<number>;

Defined in: packages/core/src/api/blob.ts:254

Stream the blob into a file (created or truncated) without buffering it whole in memory. Returns the number of bytes written.

await row.DOC.toFile(`/exports/${row.FILENAME}`);

Parameters

Parameter	Type
path	string

Returns

Promise<number>

---

prefetch()

static prefetch(blobs): Promise<void>;

Defined in: packages/core/src/api/blob.ts:83

Bulk-materialize many lazy handles through ONE cross-blob pipeline (open/read/close overlapped — the same engine eager mode uses), instead of one serialized round-trip conversation per handle. Afterwards each blob's buffer()/text()/stream() is served from memory.

const rows = await tx.query('select id, doc from files', [], { blobs: 'lazy' });
await Blob.prefetch(rows.map((r) => r.DOC as Blob)); // one pipeline

Convenience rules: null/undefined entries, duplicates, already-cached blobs, blobs with an open head() cursor (they resume on their own) and blobs tracked by a blobReadAhead store are skipped silently. Handles from different queries are grouped per connection + transaction. Throws if any target transaction is closed or any blob fails to read.

Parameters

Parameter	Type
blobs	readonly (Blob | null | undefined)[]

Returns

Promise<void>