@platformatic/sqlite-js-stream 0.0.0-stage → 0.1.1

package/dist/ltx/stream.js

@@ -0,0 +1,248 @@
+/**
+ * Streaming LTX reader.
+ *
+ * The in-memory {@link Decoder} is convenient but requires the whole LTX file in
+ * a single buffer. For large databases we read files from a streaming source (a
+ * `Readable`) and decode page-by-page, so peak memory stays bounded by one page
+ * buffer plus the small page index, never by the full database size.
+ *
+ * {@link StreamLtxReader} mirrors the synchronous `Decoder` in shape: read the
+ * header, then read each page into a reusable buffer, then `verify()` the page
+ * index + trailer (including the rolling checksum) once the end-of-pages marker
+ * is reached. It is used by streaming restore and compact.
+ */
+import { ChecksumFlag, HeaderSize, PageHeaderFlagSize, PageHeaderSize, TrailerChecksumOffset, TrailerSize, lockPgno, } from "./constants.js";
+import { Crc64 } from "./crc64.js";
+import { u32BE } from "./bytes.js";
+import { ByteReader } from "./byte-reader.js";
+import { parsePageIndex } from "./page-index.js";
+import { unmarshalHeader, validateHeader } from "./header.js";
+import { unmarshalPageHeader } from "./page.js";
+import { unmarshalTrailer } from "./trailer.js";
+import { decompressBlockInto } from "./lz4.js";
+import { checksumPage } from "./checksum.js";
+import { isSnapshot } from "./types.js";
+import { LTXFormatError } from "../errors.js";
+const stateHeader = 'header';
+const statePage = 'page';
+const stateClose = 'close';
+const stateClosed = 'closed';
+function noChecksum(h) {
+    return (h.flags & 0x00000002) !== 0;
+}
+/**
+ * Pulls bytes from an async iterable of chunks into an exact-bytes reader.
+ * Handles chunk boundaries that split logical records (page headers, LZ4
+ * blocks, varints) without buffering more than one chunk at a time.
+ */
+export class AsyncByteReader {
+    it;
+    buf = new Uint8Array(0);
+    bufPos = 0;
+    pos = 0;
+    constructor(source) {
+        this.it = source[Symbol.asyncIterator]();
+    }
+    /** Fills the internal buffer from the source. Returns false on EOF. */
+    async fill() {
+        if (this.bufPos < this.buf.length)
+            return true;
+        const next = await this.it.next();
+        if (next.done)
+            return false;
+        const v = next.value;
+        this.buf = v instanceof Uint8Array ? v : new Uint8Array(v);
+        this.bufPos = 0;
+        return true;
+    }
+    /** Reads exactly `n` bytes, advancing the position. Throws on short input. */
+    async readFull(n) {
+        const out = new Uint8Array(n);
+        let o = 0;
+        while (o < n) {
+            if (this.bufPos >= this.buf.length) {
+                if (!(await this.fill()))
+                    throw new LTXFormatError('unexpected end of input');
+            }
+            const take = Math.min(n - o, this.buf.length - this.bufPos);
+            out.set(this.buf.subarray(this.bufPos, this.bufPos + take), o);
+            this.bufPos += take;
+            o += take;
+        }
+        this.pos += n;
+        return out;
+    }
+    /** Reads and returns every remaining byte in the source. */
+    async readAllRemaining() {
+        const parts = [];
+        let total = 0;
+        if (this.bufPos < this.buf.length) {
+            const rest = this.buf.subarray(this.bufPos);
+            parts.push(rest);
+            total += rest.length;
+        }
+        for (;;) {
+            const next = await this.it.next();
+            if (next.done)
+                break;
+            const v = next.value;
+            const c = v instanceof Uint8Array ? v : new Uint8Array(v);
+            parts.push(c);
+            total += c.length;
+        }
+        this.pos += total;
+        const out = new Uint8Array(total);
+        let o = 0;
+        for (const p of parts) {
+            out.set(p, o);
+            o += p.length;
+        }
+        return out;
+    }
+}
+/**
+ * Streams an LTX file from an async iterable of byte chunks, decoding the
+ * header and each page without holding the whole file in memory.
+ */
+export class StreamLtxReader {
+    r;
+    header;
+    trailer = { postApplyChecksum: 0n, fileChecksum: 0n };
+    state = stateHeader;
+    hash = new Crc64();
+    pageSeq = new Crc64();
+    chksum = 0n;
+    pageN = 0;
+    constructor(source) {
+        this.r = new AsyncByteReader(source);
+    }
+    /** Header returns the decoded header (after `readHeader`). */
+    Header() {
+        return this.header;
+    }
+    /** Trailer returns the trailer (valid after `verify`). */
+    Trailer() {
+        return this.trailer;
+    }
+    /** PageN returns the number of pages decoded. */
+    PageN() {
+        return this.pageN;
+    }
+    /** Reads and validates the LTX header frame. */
+    async readHeader() {
+        if (this.state === stateClosed)
+            throw new LTXFormatError('ltx reader closed');
+        if (this.state !== stateHeader) {
+            throw new LTXFormatError(`cannot read header, expected ${this.state}`);
+        }
+        const b = await this.r.readFull(HeaderSize);
+        this.header = unmarshalHeader(b);
+        this.hash.update(b);
+        this.state = statePage;
+        validateHeader(this.header);
+        if (!noChecksum(this.header))
+            this.chksum = ChecksumFlag;
+    }
+    /**
+     * Reads the next page frame into `data`. Returns the page header, or null
+     * when the end-of-pages marker is reached.
+     */
+    async readPage(data) {
+        if (this.state === stateClosed)
+            throw new LTXFormatError('ltx reader closed');
+        if (this.state === stateClose)
+            return null;
+        if (this.state !== statePage) {
+            throw new LTXFormatError(`cannot read page header, expected ${this.state}`);
+        }
+        if (data.length !== this.header.pageSize) {
+            throw new LTXFormatError(`invalid page buffer size: ${data.length}, expecting ${this.header.pageSize}`);
+        }
+        const b = await this.r.readFull(PageHeaderSize);
+        const hdr = unmarshalPageHeader(b);
+        this.hash.update(b);
+        // An empty page header marks the end of the page block.
+        if (hdr.pgno === 0 && hdr.flags === 0) {
+            this.state = stateClose;
+            return null;
+        }
+        if (hdr.pgno > this.header.commit) {
+            throw new LTXFormatError(`page number ${hdr.pgno} out-of-bounds for commit size ${this.header.commit}`);
+        }
+        if (hdr.flags & PageHeaderFlagSize) {
+            const sizeBuf = await this.r.readFull(4);
+            this.hash.update(sizeBuf);
+            const dataSize = (sizeBuf[0] << 24 | sizeBuf[1] << 16 | sizeBuf[2] << 8 | sizeBuf[3]) >>> 0;
+            const compressed = await this.r.readFull(dataSize);
+            const n = decompressBlockInto(compressed, data);
+            if (n !== this.header.pageSize) {
+                throw new LTXFormatError(`lz4 block decompressed to ${n} bytes, expected ${this.header.pageSize}`);
+            }
+        }
+        else {
+            throw new LTXFormatError('legacy LZ4 frame format not supported');
+        }
+        this.hash.update(data);
+        this.hashPgo(this.pageSeq, hdr.pgno);
+        this.pageN++;
+        // Track the rolling DB checksum for checksum-tracking snapshots.
+        if (isSnapshot(this.header) && !noChecksum(this.header)) {
+            if (hdr.pgno !== lockPgno(this.header.pageSize)) {
+                this.chksum = ChecksumFlag | (this.chksum ^ checksumPage(hdr.pgno, data));
+            }
+        }
+        return hdr;
+    }
+    /** Reads the page index + trailer and verifies the file checksum. */
+    async verify() {
+        if (this.state === stateClosed)
+            return;
+        if (this.state !== stateClose) {
+            throw new LTXFormatError(`cannot verify, expected ${this.state}`);
+        }
+        const remaining = await this.r.readAllRemaining();
+        const br = new ByteReader(remaining);
+        let n = 0;
+        let nextOffset = HeaderSize;
+        const seq = new Crc64();
+        parsePageIndex(br, (buf) => this.hash.update(buf), (pgno, offset, size) => {
+            if (pgno > this.header.commit) {
+                throw new LTXFormatError(`page index pgno ${pgno} exceeds commit ${this.header.commit}`);
+            }
+            if (offset < nextOffset) {
+                throw new LTXFormatError(`page index pgno ${pgno} offset ${offset} overlaps previous frame ending at ${nextOffset}`);
+            }
+            if (size <= PageHeaderSize) {
+                throw new LTXFormatError(`page index pgno ${pgno} has invalid frame size ${size}`);
+            }
+            nextOffset = offset + size;
+            n++;
+            this.hashPgo(seq, pgno);
+        });
+        if (n !== this.pageN) {
+            throw new LTXFormatError(`page index has ${n} entries but ${this.pageN} pages were decoded`);
+        }
+        if (seq.sum64() !== this.pageSeq.sum64()) {
+            throw new LTXFormatError('page index does not match the decoded page numbers');
+        }
+        const t = br.readFull(TrailerSize);
+        this.hash.update(t.subarray(0, TrailerChecksumOffset));
+        this.trailer = unmarshalTrailer(t);
+        if (br.remaining > 0) {
+            throw new LTXFormatError('unexpected data after trailer');
+        }
+        const computed = ChecksumFlag | this.hash.sum64();
+        if (computed !== this.trailer.fileChecksum) {
+            throw new LTXFormatError('file checksum mismatch');
+        }
+        if (isSnapshot(this.header) && !noChecksum(this.header)) {
+            if (this.trailer.postApplyChecksum !== this.chksum) {
+                throw new LTXFormatError(`post-apply checksum in trailer (${this.trailer.postApplyChecksum.toString(16)}) does not match calculated checksum (${this.chksum.toString(16)})`);
+            }
+        }
+        this.state = stateClosed;
+    }
+    hashPgo(h, pgno) {
+        h.update(u32BE(pgno));
+    }
+}

package/dist/ltx/streaming-compactor.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Streaming LTX Compactor.
+ *
+ * The in-memory {@link Compactor} requires each input LTX file as a single
+ * `Uint8Array`, which defeats bounded-memory compaction of large databases.
+ * This compactor instead merges {@link StreamLtxReader}s (which read pages
+ * incrementally) into a single output stream, so peak memory stays bounded by
+ * one page buffer per input plus the (small) page index.
+ *
+ * Semantics match Go's `ltx.Compactor`: later files override earlier files for
+ * the same page number, and the output is written with `HeaderFlagNoChecksum`.
+ */
+import type { ByteSink } from './sink.js';
+import type { StreamLtxReader } from './stream.js';
+import type { Header, Trailer } from './types.js';
+/** StreamingCompactor merges LTX readers (page-by-page) into one writer. */
+export declare class StreamingCompactor {
+    private enc;
+    private inputs;
+    private _headerFlags;
+    constructor(sink: ByteSink, readers: StreamLtxReader[], headerFlags?: number);
+    /** Header returns the output header (valid after `compact`). */
+    Header(): Header;
+    /** Trailer returns the output trailer (valid after `compact`). */
+    Trailer(): Trailer;
+    /** Compact merges all input readers into a single LTX stream. */
+    compact(): Promise<void>;
+    private writePageBlock;
+    /** Fills buffers as needed and returns the smallest available page number. */
+    private fillPageBuffers;
+    /** Writes the page with matching pgno from the latest input (highest index). */
+    private writePageBuffer;
+}
+//# sourceMappingURL=streaming-compactor.d.ts.map

package/dist/ltx/streaming-compactor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming-compactor.d.ts","sourceRoot":"","sources":["../../src/ltx/streaming-compactor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,MAAM,EAAc,OAAO,EAAE,MAAM,YAAY,CAAC;AAW9D,4EAA4E;AAC5E,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,GAAG,CAAU;IACrB,OAAO,CAAC,MAAM,CAAU;IACxB,OAAO,CAAC,YAAY,CAAS;gBAEjB,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,eAAe,EAAE,EAAE,WAAW,GAAE,MAA6B;IAWlG,gEAAgE;IAChE,MAAM,IAAI,MAAM;IAIhB,kEAAkE;IAClE,OAAO,IAAI,OAAO;IAIlB,iEAAiE;IAC3D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;YAiEhB,cAAc;IAQ5B,8EAA8E;YAChE,eAAe;IAc7B,gFAAgF;YAClE,eAAe;CAqB9B"}

package/dist/ltx/streaming-compactor.js

@@ -0,0 +1,140 @@
+/**
+ * Streaming LTX Compactor.
+ *
+ * The in-memory {@link Compactor} requires each input LTX file as a single
+ * `Uint8Array`, which defeats bounded-memory compaction of large databases.
+ * This compactor instead merges {@link StreamLtxReader}s (which read pages
+ * incrementally) into a single output stream, so peak memory stays bounded by
+ * one page buffer per input plus the (small) page index.
+ *
+ * Semantics match Go's `ltx.Compactor`: later files override earlier files for
+ * the same page number, and the output is written with `HeaderFlagNoChecksum`.
+ */
+import { HeaderFlagNoChecksum, } from "./constants.js";
+import { Encoder } from "./encoder.js";
+import { InvalidArgumentError, LTXFormatError, PageSizeMismatchError } from "../errors.js";
+import { isContiguous } from "./types.js";
+/** StreamingCompactor merges LTX readers (page-by-page) into one writer. */
+export class StreamingCompactor {
+    enc;
+    inputs;
+    _headerFlags;
+    constructor(sink, readers, headerFlags = HeaderFlagNoChecksum) {
+        this.enc = new Encoder(sink);
+        this._headerFlags = headerFlags;
+        this.inputs = readers.map((reader) => ({
+            reader,
+            data: new Uint8Array(0),
+            hdr: null,
+            ended: false,
+        }));
+    }
+    /** Header returns the output header (valid after `compact`). */
+    Header() {
+        return this.enc.Header();
+    }
+    /** Trailer returns the output trailer (valid after `compact`). */
+    Trailer() {
+        return this.enc.Trailer();
+    }
+    /** Compact merges all input readers into a single LTX stream. */
+    async compact() {
+        if (this.inputs.length === 0) {
+            throw new InvalidArgumentError('at least one input reader required');
+        }
+        // Read headers from all inputs.
+        for (const input of this.inputs) {
+            await input.reader.readHeader();
+        }
+        // Validate page sizes & contiguous TXIDs.
+        for (let i = 1; i < this.inputs.length; i++) {
+            const prevHdr = this.inputs[i - 1].reader.Header();
+            const hdr = this.inputs[i].reader.Header();
+            if (prevHdr.pageSize !== hdr.pageSize) {
+                throw new PageSizeMismatchError(`input files have mismatched page sizes: ${prevHdr.pageSize} != ${hdr.pageSize}`);
+            }
+            if (!isContiguous(prevHdr.maxTXID, hdr.minTXID, hdr.maxTXID)) {
+                throw new LTXFormatError(`non-contiguous transaction ids in input files: (${prevHdr.minTXID},${prevHdr.maxTXID}) -> (${hdr.minTXID},${hdr.maxTXID})`);
+            }
+        }
+        const minHdr = this.inputs[0].reader.Header();
+        const maxHdr = this.inputs[this.inputs.length - 1].reader.Header();
+        const pageSize = minHdr.pageSize;
+        for (const input of this.inputs) {
+            input.data = new Uint8Array(pageSize);
+        }
+        // Propagate the WAL position of the last (newest) input so that a later
+        // sync can resume reading the WAL from where the merged range ended,
+        // even after the level-0 sources have been pruned.
+        this.enc.encodeHeader({
+            version: 3,
+            flags: this._headerFlags,
+            pageSize,
+            commit: maxHdr.commit,
+            minTXID: minHdr.minTXID,
+            maxTXID: maxHdr.maxTXID,
+            timestamp: maxHdr.timestamp,
+            preApplyChecksum: minHdr.preApplyChecksum,
+            walOffset: maxHdr.walOffset,
+            walSize: maxHdr.walSize,
+            walSalt1: maxHdr.walSalt1,
+            walSalt2: maxHdr.walSalt2,
+            nodeID: maxHdr.nodeID,
+        });
+        await this.writePageBlock();
+        // Verify every input's index/trailer (catches a corrupt source) and
+        // propagate the final post-apply checksum.
+        const last = this.inputs[this.inputs.length - 1];
+        for (const input of this.inputs) {
+            await input.reader.verify();
+        }
+        this.enc.setPostApplyChecksum(last.reader.Trailer().postApplyChecksum);
+        this.enc.close();
+    }
+    async writePageBlock() {
+        for (;;) {
+            const pgno = await this.fillPageBuffers();
+            if (pgno === 0)
+                break;
+            await this.writePageBuffer(pgno);
+        }
+    }
+    /** Fills buffers as needed and returns the smallest available page number. */
+    async fillPageBuffers() {
+        let pgno = 0;
+        for (const input of this.inputs) {
+            if (input.hdr === null && !input.ended) {
+                input.hdr = await input.reader.readPage(input.data);
+                if (input.hdr === null)
+                    input.ended = true;
+            }
+            if (input.hdr !== null && (pgno === 0 || input.hdr.pgno < pgno)) {
+                pgno = input.hdr.pgno;
+            }
+        }
+        return pgno;
+    }
+    /** Writes the page with matching pgno from the latest input (highest index). */
+    async writePageBuffer(pgno) {
+        let emitIndex = -1;
+        for (let i = 0; i < this.inputs.length; i++) {
+            const hdr = this.inputs[i].hdr;
+            if (hdr !== null && hdr.pgno === pgno)
+                emitIndex = i;
+        }
+        if (emitIndex < 0) {
+            throw new LTXFormatError(`internal: no input holds page ${pgno}`);
+        }
+        // Emit from the latest matching input, then consume every matching input
+        // so a page at the same pgno is only written once.
+        for (let i = 0; i < this.inputs.length; i++) {
+            const input = this.inputs[i];
+            if (input.hdr === null || input.hdr.pgno !== pgno)
+                continue;
+            if (i === emitIndex) {
+                this.enc.encodePage(input.hdr, input.data);
+            }
+            input.hdr = null;
+        }
+    }
+}

package/dist/ltx/trailer.d.ts

@@ -0,0 +1,12 @@
+/**
+ * LTX trailer frame marshalling.
+ */
+import type { Header, Trailer } from './types.js';
+/** MarshalBinary encodes a Trailer to its 16-byte representation. */
+export declare function marshalTrailer(t: Trailer): Uint8Array;
+/** UnmarshalBinary decodes a Trailer from a byte slice. */
+export declare function unmarshalTrailer(b: Uint8Array): Trailer;
+/** Validate returns an error (thrown) if t is invalid for header h. */
+export declare function validateTrailer(t: Trailer, h: Header): void;
+export declare const TRAILER_CHECKSUM_OFFSET: number;
+//# sourceMappingURL=trailer.d.ts.map

package/dist/ltx/trailer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trailer.d.ts","sourceRoot":"","sources":["../../src/ltx/trailer.ts"],"names":[],"mappings":"AAAA;;GAEG;AAQH,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAGlD,qEAAqE;AACrE,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,GAAG,UAAU,CAKrD;AAED,2DAA2D;AAC3D,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,UAAU,GAAG,OAAO,CAMvD;AAMD,uEAAuE;AACvE,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAoB3D;AAED,eAAO,MAAM,uBAAuB,QAAwB,CAAC"}

package/dist/ltx/trailer.js

@@ -0,0 +1,47 @@
+/**
+ * LTX trailer frame marshalling.
+ */
+import { ChecksumFlag, TrailerChecksumOffset, TrailerSize, } from "./constants.js";
+import { assertFull, readU64BE, writeU64BE } from "./bytes.js";
+import { LTXFormatError } from "../errors.js";
+/** MarshalBinary encodes a Trailer to its 16-byte representation. */
+export function marshalTrailer(t) {
+    const b = new Uint8Array(TrailerSize);
+    writeU64BE(b, 0, t.postApplyChecksum);
+    writeU64BE(b, 8, t.fileChecksum);
+    return b;
+}
+/** UnmarshalBinary decodes a Trailer from a byte slice. */
+export function unmarshalTrailer(b) {
+    assertFull(b, 0, TrailerSize);
+    return {
+        postApplyChecksum: readU64BE(b, 0),
+        fileChecksum: readU64BE(b, 8),
+    };
+}
+function noChecksum(h) {
+    return (h.flags & 0x00000002) !== 0;
+}
+/** Validate returns an error (thrown) if t is invalid for header h. */
+export function validateTrailer(t, h) {
+    if (noChecksum(h)) {
+        if (t.postApplyChecksum !== 0n) {
+            throw new LTXFormatError('post-apply checksum not allowed');
+        }
+    }
+    else {
+        if (t.postApplyChecksum === 0n) {
+            throw new LTXFormatError('post-apply checksum required');
+        }
+        if ((t.postApplyChecksum & ChecksumFlag) === 0n) {
+            throw new LTXFormatError('invalid post-apply checksum format');
+        }
+    }
+    if (t.fileChecksum === 0n) {
+        throw new LTXFormatError('file checksum required');
+    }
+    if ((t.fileChecksum & ChecksumFlag) === 0n) {
+        throw new LTXFormatError('invalid file checksum format');
+    }
+}
+export const TRAILER_CHECKSUM_OFFSET = TrailerChecksumOffset;

package/dist/ltx/types.d.ts

@@ -0,0 +1,79 @@
+/**
+ * LTX shared types and small value helpers.
+ *
+ * 64-bit unsigned values (TXID, Checksum) are represented as `bigint` to keep
+ * exact semantics. Page numbers and file offsets/sizes fit within JS safe
+ * integers for any realistic database, so they are `number`.
+ */
+export type TXID = bigint;
+export type Checksum = bigint;
+/** Pos is the transactional position of a database. */
+export interface Pos {
+    txID: TXID;
+    postApplyChecksum: Checksum;
+}
+/** Formats a TXID as a fixed-width 16-char lowercase hex string. */
+export declare function formatTXID(txID: bigint): string;
+/** Parses a 16-character hex string into a TXID. */
+export declare function parseTXID(s: string): bigint;
+/** Formats a Checksum as a fixed-width 16-char lowercase hex string. */
+export declare function formatChecksum(chk: bigint): string;
+/** Parses a 16-character hex string into a Checksum. */
+export declare function parseChecksum(s: string): bigint;
+export declare function parsePos(s: string): Pos;
+export declare function formatPos(p: Pos): string;
+export declare function isZeroPos(p: Pos): boolean;
+/** Header flags. */
+export interface Header {
+    version: number;
+    flags: number;
+    pageSize: number;
+    commit: number;
+    minTXID: TXID;
+    maxTXID: TXID;
+    timestamp: bigint;
+    preApplyChecksum: Checksum;
+    walOffset: bigint;
+    walSize: bigint;
+    walSalt1: number;
+    walSalt2: number;
+    nodeID: bigint;
+}
+export declare function isSnapshot(h: Header): boolean;
+export declare function noChecksum(h: Header): boolean;
+/** PageHeader represents the header for a single page in an LTX file. */
+export interface PageHeader {
+    pgno: number;
+    flags: number;
+}
+export declare function isZeroPageHeader(h: PageHeader): boolean;
+/** Trailer represents the ending frame of an LTX file. */
+export interface Trailer {
+    postApplyChecksum: Checksum;
+    fileChecksum: Checksum;
+}
+/** PageIndexElem describes a single page entry in the file's page index. */
+export interface PageIndexElem {
+    level: number;
+    minTXID: TXID;
+    maxTXID: TXID;
+    offset: number;
+    size: number;
+}
+export type PageIndex = Map<number, PageIndexElem>;
+/** FileInfo represents file information about an LTX file. */
+export interface FileInfo {
+    level: number;
+    minTXID: TXID;
+    maxTXID: TXID;
+    preApplyChecksum?: Checksum;
+    postApplyChecksum?: Checksum;
+    size: number;
+    createdAt: number;
+    checksum?: Checksum;
+}
+export declare function preApplyPos(info: FileInfo): Pos;
+export declare function postApplyPos(info: FileInfo): Pos;
+/** IsContiguous reports whether a transaction range is contiguous with prevMaxTXID. */
+export declare function isContiguous(prevMaxTXID: TXID, minTXID: TXID, maxTXID: TXID): boolean;
+//# sourceMappingURL=types.d.ts.map

package/dist/ltx/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/ltx/types.ts"],"names":[],"mappings":"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"}

package/dist/ltx/types.js

@@ -0,0 +1,70 @@
+import { LTXFormatError } from "../errors.js";
+/** Formats a TXID as a fixed-width 16-char lowercase hex string. */
+export function formatTXID(txID) {
+    return txID.toString(16).padStart(16, '0');
+}
+/** Parses a 16-character hex string into a TXID. */
+export function parseTXID(s) {
+    if (s.length !== 16) {
+        throw new LTXFormatError(`invalid formatted transaction id length: ${JSON.stringify(s)}`);
+    }
+    if (!/^[0-9a-fA-F]{16}$/.test(s)) {
+        throw new LTXFormatError(`invalid transaction id format: ${JSON.stringify(s)}`);
+    }
+    return BigInt(`0x${s}`);
+}
+/** Formats a Checksum as a fixed-width 16-char lowercase hex string. */
+export function formatChecksum(chk) {
+    return chk.toString(16).padStart(16, '0');
+}
+/** Parses a 16-character hex string into a Checksum. */
+export function parseChecksum(s) {
+    if (s.length !== 16) {
+        throw new LTXFormatError(`invalid formatted checksum length: ${JSON.stringify(s)}`);
+    }
+    if (!/^[0-9a-fA-F]{16}$/.test(s)) {
+        throw new LTXFormatError(`invalid checksum format: ${JSON.stringify(s)}`);
+    }
+    return BigInt(`0x${s}`);
+}
+export function parsePos(s) {
+    if (s.length !== 33) {
+        throw new LTXFormatError(`invalid formatted position length: ${JSON.stringify(s)}`);
+    }
+    return {
+        txID: parseTXID(s.slice(0, 16)),
+        postApplyChecksum: parseChecksum(s.slice(17)),
+    };
+}
+export function formatPos(p) {
+    return `${formatTXID(p.txID)}/${formatChecksum(p.postApplyChecksum)}`;
+}
+export function isZeroPos(p) {
+    return p.txID === 0n && p.postApplyChecksum === 0n;
+}
+export function isSnapshot(h) {
+    return h.minTXID === 1n;
+}
+export function noChecksum(h) {
+    return (h.flags & HeaderFlagNoChecksumBit) !== 0;
+}
+const HeaderFlagNoChecksumBit = 0x00000002;
+export function isZeroPageHeader(h) {
+    return h.pgno === 0 && h.flags === 0;
+}
+export function preApplyPos(info) {
+    return {
+        txID: info.minTXID - 1n,
+        postApplyChecksum: info.preApplyChecksum ?? 0n,
+    };
+}
+export function postApplyPos(info) {
+    return {
+        txID: info.maxTXID,
+        postApplyChecksum: info.postApplyChecksum ?? 0n,
+    };
+}
+/** IsContiguous reports whether a transaction range is contiguous with prevMaxTXID. */
+export function isContiguous(prevMaxTXID, minTXID, maxTXID) {
+    return minTXID <= prevMaxTXID + 1n && maxTXID > prevMaxTXID;
+}