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

package/dist/leaser.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Distributed leasing.
+ *
+ * When multiple replicas point at the same storage path, only one may be the
+ * active writer at a time. A `Leaser` acquires a lease on the replica's storage
+ * (a `lock.json` file / object); only the lease holder is the *primary* and may
+ * write. Other replicas become idle *followers* that poll until the lease is
+ * available.
+ *
+ * This mirrors litestream's `leaser.go`/`Lease` (a storage-agnostic interface)
+ * and `s3/leaser.go` (a conditional-write S3 implementation). Acquire uses
+ * `If-None-Match: *` when no lease exists and `If-Match: <etag>` (renew) or
+ * `If-Match: <etag>` (release) otherwise, so a stale writer can never clobber a
+ * live one.
+ */
+import { SqliteJsStreamError } from './errors.js';
+/** A held lease. `etag` is the conditional-write token for renew/release. */
+export declare class Lease {
+    generation: number;
+    expiresAt: number;
+    owner: string;
+    etag: string | null;
+    constructor(generation: number, expiresAt: number, owner: string, etag?: string | null);
+    /** IsExpired reports whether the lease has passed its expiration. */
+    isExpired(now?: number): boolean;
+    /** TTL returns the remaining time before expiration, in ms. */
+    ttl(now?: number): number;
+}
+/** The lease is already held by another owner. */
+export declare class LeaseExistsError extends SqliteJsStreamError {
+    owner: string;
+    expiresAt: number;
+    constructor(owner: string, expiresAt: number);
+}
+/** The caller no longer holds the lease (lost it or never acquired it). */
+export declare class ErrLeaseNotHeld extends SqliteJsStreamError {
+    constructor();
+}
+/**
+ * Leaser acquires, renews, and releases a lease on a storage path. The
+ * implementation must use conditional writes so concurrent acquirers cannot
+ * both win.
+ */
+export interface Leaser {
+    /** Acquires the lease, throwing {@link LeaseExistsError} if held elsewhere. */
+    acquireLease(): Promise<Lease>;
+    /** Renews the lease, throwing {@link ErrLeaseNotHeld} if we lost it. */
+    renewLease(lease: Lease): Promise<Lease>;
+    /** Releases the lease, throwing {@link ErrLeaseNotHeld} if we lost it. */
+    releaseLease(lease: Lease): Promise<void>;
+}
+export declare const DefaultLeaseTTL = 30000;
+export declare const DefaultLeasePath = "lock.json";
+export declare const DefaultLeaseRenewalBuffer = 5000;
+//# sourceMappingURL=leaser.d.ts.map

package/dist/leaser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"leaser.d.ts","sourceRoot":"","sources":["../src/leaser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAElD,6EAA6E;AAC7E,qBAAa,KAAK;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,GAAG,IAAI,CAAQ;gBAEf,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,GAAG,IAAW;IAO5F,qEAAqE;IACrE,SAAS,CAAC,GAAG,SAAa,GAAG,OAAO;IAIpC,+DAA+D;IAC/D,GAAG,CAAC,GAAG,SAAa,GAAG,MAAM;CAG9B;AAED,kDAAkD;AAClD,qBAAa,gBAAiB,SAAQ,mBAAmB;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;gBAEN,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAW7C;AAED,2EAA2E;AAC3E,qBAAa,eAAgB,SAAQ,mBAAmB;;CAKvD;AAED;;;;GAIG;AACH,MAAM,WAAW,MAAM;IACrB,+EAA+E;IAC/E,YAAY,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC;IAC/B,wEAAwE;IACxE,UAAU,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IACzC,0EAA0E;IAC1E,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C;AAED,eAAO,MAAM,eAAe,QAAS,CAAC;AACtC,eAAO,MAAM,gBAAgB,cAAc,CAAC;AAC5C,eAAO,MAAM,yBAAyB,OAAQ,CAAC"}

package/dist/leaser.js

@@ -0,0 +1,60 @@
+/**
+ * Distributed leasing.
+ *
+ * When multiple replicas point at the same storage path, only one may be the
+ * active writer at a time. A `Leaser` acquires a lease on the replica's storage
+ * (a `lock.json` file / object); only the lease holder is the *primary* and may
+ * write. Other replicas become idle *followers* that poll until the lease is
+ * available.
+ *
+ * This mirrors litestream's `leaser.go`/`Lease` (a storage-agnostic interface)
+ * and `s3/leaser.go` (a conditional-write S3 implementation). Acquire uses
+ * `If-None-Match: *` when no lease exists and `If-Match: <etag>` (renew) or
+ * `If-Match: <etag>` (release) otherwise, so a stale writer can never clobber a
+ * live one.
+ */
+import { SqliteJsStreamError } from "./errors.js";
+/** A held lease. `etag` is the conditional-write token for renew/release. */
+export class Lease {
+    generation;
+    expiresAt; // ms since epoch
+    owner;
+    etag = null;
+    constructor(generation, expiresAt, owner, etag = null) {
+        this.generation = generation;
+        this.expiresAt = expiresAt;
+        this.owner = owner;
+        this.etag = etag;
+    }
+    /** IsExpired reports whether the lease has passed its expiration. */
+    isExpired(now = Date.now()) {
+        return now > this.expiresAt;
+    }
+    /** TTL returns the remaining time before expiration, in ms. */
+    ttl(now = Date.now()) {
+        return this.expiresAt - now;
+    }
+}
+/** The lease is already held by another owner. */
+export class LeaseExistsError extends SqliteJsStreamError {
+    owner;
+    expiresAt;
+    constructor(owner, expiresAt) {
+        super('ERR_LEASE_EXISTS', owner !== ''
+            ? `lease already held by ${owner} until ${new Date(expiresAt).toISOString()}`
+            : `lease already held until ${new Date(expiresAt).toISOString()}`);
+        this.name = 'LeaseExistsError';
+        this.owner = owner;
+        this.expiresAt = expiresAt;
+    }
+}
+/** The caller no longer holds the lease (lost it or never acquired it). */
+export class ErrLeaseNotHeld extends SqliteJsStreamError {
+    constructor() {
+        super('ERR_LEASE_NOT_HELD', 'lease not held');
+        this.name = 'ErrLeaseNotHeld';
+    }
+}
+export const DefaultLeaseTTL = 30_000; // 30s
+export const DefaultLeasePath = 'lock.json';
+export const DefaultLeaseRenewalBuffer = 5_000; // renew before it expires

package/dist/ltx/byte-reader.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A sequential byte reader over an in-memory buffer. Used by the LTX decoder
+ * to walk the page block, page index, and trailer while tracking position.
+ */
+export declare class ByteReader {
+    private buf;
+    pos: number;
+    constructor(buf: Uint8Array, start?: number);
+    get length(): number;
+    get remaining(): number;
+    /** Reads one byte, advancing the position. Throws on EOF. */
+    readByte(): number;
+    /** Reads exactly `n` bytes, advancing the position. Throws on short input. */
+    readFull(n: number): Uint8Array;
+    /** Returns a view of the bytes in [start, end) without moving the position. */
+    slice(start: number, end: number): Uint8Array;
+}
+//# sourceMappingURL=byte-reader.d.ts.map

package/dist/ltx/byte-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"byte-reader.d.ts","sourceRoot":"","sources":["../../src/ltx/byte-reader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,qBAAa,UAAU;IACrB,OAAO,CAAC,GAAG,CAAa;IACxB,GAAG,EAAE,MAAM,CAAC;gBAEA,GAAG,EAAE,UAAU,EAAE,KAAK,SAAI;IAKtC,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,6DAA6D;IAC7D,QAAQ,IAAI,MAAM;IAOlB,8EAA8E;IAC9E,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,UAAU;IAO/B,+EAA+E;IAC/E,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU;CAG9C"}

package/dist/ltx/byte-reader.js

@@ -0,0 +1,38 @@
+/**
+ * A sequential byte reader over an in-memory buffer. Used by the LTX decoder
+ * to walk the page block, page index, and trailer while tracking position.
+ */
+import { assertFull } from "./bytes.js";
+import { LTXFormatError } from "../errors.js";
+export class ByteReader {
+    buf;
+    pos;
+    constructor(buf, start = 0) {
+        this.buf = buf;
+        this.pos = start;
+    }
+    get length() {
+        return this.buf.length;
+    }
+    get remaining() {
+        return this.buf.length - this.pos;
+    }
+    /** Reads one byte, advancing the position. Throws on EOF. */
+    readByte() {
+        if (this.pos >= this.buf.length) {
+            throw new LTXFormatError('unexpected end of input');
+        }
+        return this.buf[this.pos++];
+    }
+    /** Reads exactly `n` bytes, advancing the position. Throws on short input. */
+    readFull(n) {
+        assertFull(this.buf, this.pos, n);
+        const out = this.buf.subarray(this.pos, this.pos + n);
+        this.pos += n;
+        return out;
+    }
+    /** Returns a view of the bytes in [start, end) without moving the position. */
+    slice(start, end) {
+        return this.buf.subarray(start, end);
+    }
+}

package/dist/ltx/bytes.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Big-endian byte helpers for LTX marshalling.
+ */
+export declare function writeU8(buf: Uint8Array, off: number, v: number): void;
+export declare function writeU16BE(buf: Uint8Array, off: number, v: number): void;
+export declare function writeU32BE(buf: Uint8Array, off: number, v: number): void;
+export declare function writeU64BE(buf: Uint8Array, off: number, v: bigint): void;
+export declare function readU16BE(buf: Uint8Array, off: number): number;
+export declare function readU32BE(buf: Uint8Array, off: number): number;
+export declare function readU32LE(buf: Uint8Array, off: number): number;
+export declare function readU64BE(buf: Uint8Array, off: number): bigint;
+/** Converts a number to a big-endian 4-byte array. */
+export declare function u32BE(v: number): Uint8Array;
+/** Converts a number to a big-endian 8-byte array. */
+export declare function u64BE(v: bigint): Uint8Array;
+/** Converts a number to a big-endian 2-byte array. */
+export declare function u16BE(v: number): Uint8Array;
+/** Throws unless exactly `n` bytes are available to read. */
+export declare function assertFull(buf: Uint8Array, off: number, n: number): void;
+//# sourceMappingURL=bytes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bytes.d.ts","sourceRoot":"","sources":["../../src/ltx/bytes.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,wBAAgB,OAAO,CAAC,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAErE;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAGxE;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAKxE;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAMxE;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAO9D;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAO9D;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAM9D;AAED,sDAAsD;AACtD,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,UAAU,CAI3C;AAED,sDAAsD;AACtD,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,UAAU,CAI3C;AAED,sDAAsD;AACtD,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,UAAU,CAI3C;AAED,6DAA6D;AAC7D,wBAAgB,UAAU,CAAC,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAMxE"}

package/dist/ltx/bytes.js

@@ -0,0 +1,69 @@
+/**
+ * Big-endian byte helpers for LTX marshalling.
+ */
+export function writeU8(buf, off, v) {
+    buf[off] = v & 0xff;
+}
+export function writeU16BE(buf, off, v) {
+    buf[off] = (v >>> 8) & 0xff;
+    buf[off + 1] = v & 0xff;
+}
+export function writeU32BE(buf, off, v) {
+    buf[off] = (v >>> 24) & 0xff;
+    buf[off + 1] = (v >>> 16) & 0xff;
+    buf[off + 2] = (v >>> 8) & 0xff;
+    buf[off + 3] = v & 0xff;
+}
+export function writeU64BE(buf, off, v) {
+    let n = v;
+    for (let i = 0; i < 8; i++) {
+        buf[off + (7 - i)] = Number(n & 0xffn);
+        n >>= 8n;
+    }
+}
+export function readU16BE(buf, off) {
+    return (buf[off] << 8) | buf[off + 1];
+}
+export function readU32BE(buf, off) {
+    return (((buf[off] | 0) << 24) >>> 0 |
+        (buf[off + 1] << 16) |
+        (buf[off + 2] << 8) |
+        buf[off + 3]) >>> 0;
+}
+export function readU32LE(buf, off) {
+    return (buf[off] |
+        (buf[off + 1] << 8) |
+        (buf[off + 2] << 16) |
+        ((buf[off + 3] | 0) << 24)) >>> 0;
+}
+export function readU64BE(buf, off) {
+    let n = 0n;
+    for (let i = 0; i < 8; i++) {
+        n = (n << 8n) | BigInt(buf[off + i]);
+    }
+    return n;
+}
+/** Converts a number to a big-endian 4-byte array. */
+export function u32BE(v) {
+    const b = new Uint8Array(4);
+    writeU32BE(b, 0, v);
+    return b;
+}
+/** Converts a number to a big-endian 8-byte array. */
+export function u64BE(v) {
+    const b = new Uint8Array(8);
+    writeU64BE(b, 0, v);
+    return b;
+}
+/** Converts a number to a big-endian 2-byte array. */
+export function u16BE(v) {
+    const b = new Uint8Array(2);
+    writeU16BE(b, 0, v);
+    return b;
+}
+/** Throws unless exactly `n` bytes are available to read. */
+export function assertFull(buf, off, n) {
+    if (off + n > buf.length) {
+        throw new RangeError(`short buffer: need ${n} bytes at offset ${off}, have ${buf.length - off}`);
+    }
+}

package/dist/ltx/checksum.d.ts

@@ -0,0 +1,20 @@
+/**
+ * LTX checksum helpers: per-page checksums and the rolling DB checksum.
+ */
+import { Crc64 } from './crc64.js';
+/**
+ * ChecksumPage returns a CRC-64 checksum that combines the page number with
+ * the page data: `ChecksumFlag | CRC64-ISO(pgno_be4 ++ data)`.
+ */
+export declare function checksumPage(pgno: number, data: Uint8Array): bigint;
+export declare function checksumPageWithHasher(h: Crc64, pgno: number, data: Uint8Array): bigint;
+/**
+ * ChecksumReader computes the rolling DB checksum over a byte buffer split
+ * into pages of `pageSize`. The "lock page" is skipped entirely (its checksum
+ * contributes nothing), matching Go's `ChecksumReader`.
+ *
+ * For large databases this should later read page-by-page from a file rather
+ * than buffering the whole DB; provided as a buffer for Milestone 1.
+ */
+export declare function checksumReader(data: Uint8Array, pageSize: number): bigint;
+//# sourceMappingURL=checksum.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"checksum.d.ts","sourceRoot":"","sources":["../../src/ltx/checksum.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGnC;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CAKnE;AAED,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CAKvF;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAWzE"}

package/dist/ltx/checksum.js

@@ -0,0 +1,42 @@
+/**
+ * LTX checksum helpers: per-page checksums and the rolling DB checksum.
+ */
+import { ChecksumFlag, lockPgno } from "./constants.js";
+import { Crc64 } from "./crc64.js";
+import { u32BE } from "./bytes.js";
+/**
+ * ChecksumPage returns a CRC-64 checksum that combines the page number with
+ * the page data: `ChecksumFlag | CRC64-ISO(pgno_be4 ++ data)`.
+ */
+export function checksumPage(pgno, data) {
+    const h = new Crc64();
+    h.update(u32BE(pgno));
+    h.update(data);
+    return ChecksumFlag | h.sum64();
+}
+export function checksumPageWithHasher(h, pgno, data) {
+    h.reset();
+    h.update(u32BE(pgno));
+    h.update(data);
+    return ChecksumFlag | h.sum64();
+}
+/**
+ * ChecksumReader computes the rolling DB checksum over a byte buffer split
+ * into pages of `pageSize`. The "lock page" is skipped entirely (its checksum
+ * contributes nothing), matching Go's `ChecksumReader`.
+ *
+ * For large databases this should later read page-by-page from a file rather
+ * than buffering the whole DB; provided as a buffer for Milestone 1.
+ */
+export function checksumReader(data, pageSize) {
+    const lockPg = lockPgno(pageSize);
+    let chksum = 0n;
+    let offset = 0;
+    for (let pgno = 1; offset < data.length; pgno++, offset += pageSize) {
+        const page = data.subarray(offset, offset + pageSize);
+        if (pgno !== lockPg) {
+            chksum = ChecksumFlag | (chksum ^ checksumPage(pgno, page));
+        }
+    }
+    return chksum;
+}

package/dist/ltx/compaction-level.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Multi-level compaction configuration.
+ *
+ * Mirrors litestream's `compaction_level.go`. Litestream stores raw LTX files
+ * at level 0 and progressively merges them into higher levels at increasing
+ * time intervals. Each level is compacted on its own wall-clock bucket; a level
+ * is compacted at most once per bucket so repeated writes are coalesced.
+ *
+ * Defaults (matching litestream):
+ *   - L0: raw LTX (no interval)
+ *   - L1: every 30s
+ *   - L2: every 5m
+ *   - L3: every 1h
+ */
+/** CompactionLevel describes a single compaction tier. */
+export interface CompactionLevel {
+    /** The numeric level. Level 0 is raw, never compacted. */
+    level: number;
+    /** Frequency (ms) that files are compacted from the previous level. 0 for level 0. */
+    intervalMs: number;
+}
+/** CompactionLevels is an ordered set of non-snapshot compaction levels. */
+export declare class CompactionLevels {
+    private levels;
+    constructor(levels: CompactionLevel[]);
+    /** Returns the level configuration at `level`. */
+    level(level: number): CompactionLevel;
+    /** MaxLevel returns the highest non-snapshot compaction level. */
+    maxLevel(): number;
+    /** SnapshotLevel returns a pseudo level for full snapshots. */
+    snapshotLevel(): CompactionLevel;
+    /** PrevLevel returns the level that compacts into `level` (-1 if none). */
+    prevLevel(level: number): number;
+    /** NextLevel returns the level that `level` compacts into (-1 at the top). */
+    nextLevel(level: number): number;
+    /** Validate checks the levels are ordered, bounded, and have sane intervals. */
+    validate(): void;
+    /** IsValidLevel returns true if `level` is a valid compaction level. */
+    isValidLevel(level: number): boolean;
+    /** Returns a copy of the underlying levels. */
+    toArray(): CompactionLevel[];
+}
+/** Canonical default compaction configuration (matches litestream). */
+export declare function defaultCompactionLevels(): CompactionLevels;
+/**
+ * PrevCompactionAt returns the start of the current compaction bucket for
+ * `intervalMs`. Compaction for a level only proceeds once per bucket, so
+ * repeated syncs across a window collapse into one compacted file.
+ */
+export declare function prevCompactionAt(now: number, intervalMs: number): number;
+/** NextCompactionAt returns the start of the next compaction bucket. */
+export declare function nextCompactionAt(now: number, intervalMs: number): number;
+/** Interval (ms) constants matching litestream's defaults. */
+export declare const DefaultSnapshotIntervalMs: number;
+export declare const DefaultSnapshotRetentionMs: number;
+export declare const DefaultL0RetentionMs: number;
+export declare const DefaultL0RetentionCheckIntervalMs: number;
+//# sourceMappingURL=compaction-level.d.ts.map

package/dist/ltx/compaction-level.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction-level.d.ts","sourceRoot":"","sources":["../../src/ltx/compaction-level.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,0DAA0D;AAC1D,MAAM,WAAW,eAAe;IAC9B,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC;IACd,sFAAsF;IACtF,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,4EAA4E;AAC5E,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAoB;gBAEtB,MAAM,EAAE,eAAe,EAAE;IAKrC,kDAAkD;IAClD,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe;IAUrC,kEAAkE;IAClE,QAAQ,IAAI,MAAM;IAIlB,+DAA+D;IAC/D,aAAa,IAAI,eAAe;IAIhC,2EAA2E;IAC3E,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAKhC,8EAA8E;IAC9E,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAMhC,gFAAgF;IAChF,QAAQ,IAAI,IAAI;IAuBhB,wEAAwE;IACxE,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAKpC,+CAA+C;IAC/C,OAAO,IAAI,eAAe,EAAE;CAG7B;AAED,uEAAuE;AACvE,wBAAgB,uBAAuB,IAAI,gBAAgB,CAO1D;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAGxE;AAED,wEAAwE;AACxE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAExE;AAED,8DAA8D;AAC9D,eAAO,MAAM,yBAAyB,QAAsB,CAAC;AAC7D,eAAO,MAAM,0BAA0B,QAAsB,CAAC;AAC9D,eAAO,MAAM,oBAAoB,QAAgB,CAAC;AAClD,eAAO,MAAM,iCAAiC,QAAY,CAAC"}

package/dist/ltx/compaction-level.js

@@ -0,0 +1,115 @@
+/**
+ * Multi-level compaction configuration.
+ *
+ * Mirrors litestream's `compaction_level.go`. Litestream stores raw LTX files
+ * at level 0 and progressively merges them into higher levels at increasing
+ * time intervals. Each level is compacted on its own wall-clock bucket; a level
+ * is compacted at most once per bucket so repeated writes are coalesced.
+ *
+ * Defaults (matching litestream):
+ *   - L0: raw LTX (no interval)
+ *   - L1: every 30s
+ *   - L2: every 5m
+ *   - L3: every 1h
+ */
+import { SnapshotLevel } from "./constants.js";
+import { InvalidArgumentError } from "../errors.js";
+/** CompactionLevels is an ordered set of non-snapshot compaction levels. */
+export class CompactionLevels {
+    levels;
+    constructor(levels) {
+        this.levels = [...levels].sort((a, b) => a.level - b.level);
+        this.validate();
+    }
+    /** Returns the level configuration at `level`. */
+    level(level) {
+        if (level === SnapshotLevel) {
+            throw new InvalidArgumentError('snapshot level has no compaction interval');
+        }
+        if (level < 0 || level > this.maxLevel()) {
+            throw new InvalidArgumentError(`level out of bounds: ${level}`);
+        }
+        return this.levels[level];
+    }
+    /** MaxLevel returns the highest non-snapshot compaction level. */
+    maxLevel() {
+        return this.levels.length - 1;
+    }
+    /** SnapshotLevel returns a pseudo level for full snapshots. */
+    snapshotLevel() {
+        return { level: SnapshotLevel, intervalMs: 0 };
+    }
+    /** PrevLevel returns the level that compacts into `level` (-1 if none). */
+    prevLevel(level) {
+        if (level === SnapshotLevel)
+            return this.maxLevel();
+        return level - 1;
+    }
+    /** NextLevel returns the level that `level` compacts into (-1 at the top). */
+    nextLevel(level) {
+        if (level === SnapshotLevel)
+            return -1;
+        if (level === this.maxLevel())
+            return SnapshotLevel;
+        return level + 1;
+    }
+    /** Validate checks the levels are ordered, bounded, and have sane intervals. */
+    validate() {
+        if (this.levels.length === 0) {
+            throw new InvalidArgumentError('at least one compaction level is required');
+        }
+        for (let i = 0; i < this.levels.length; i++) {
+            const lvl = this.levels[i];
+            if (lvl.level !== i) {
+                throw new InvalidArgumentError(`compaction level number out of order: ${lvl.level}, expected ${i}`);
+            }
+            if (lvl.level > SnapshotLevel - 1) {
+                throw new InvalidArgumentError(`compaction level cannot exceed ${SnapshotLevel - 1}`);
+            }
+            if (lvl.level === 0 && lvl.intervalMs !== 0) {
+                throw new InvalidArgumentError('cannot set interval on compaction level zero');
+            }
+            if (lvl.level !== 0 && lvl.intervalMs <= 0) {
+                throw new InvalidArgumentError(`interval required for level ${lvl.level}`);
+            }
+        }
+    }
+    /** IsValidLevel returns true if `level` is a valid compaction level. */
+    isValidLevel(level) {
+        if (level === SnapshotLevel)
+            return true;
+        return level >= 0 && level < this.levels.length;
+    }
+    /** Returns a copy of the underlying levels. */
+    toArray() {
+        return this.levels.map((l) => ({ ...l }));
+    }
+}
+/** Canonical default compaction configuration (matches litestream). */
+export function defaultCompactionLevels() {
+    return new CompactionLevels([
+        { level: 0, intervalMs: 0 },
+        { level: 1, intervalMs: 30_000 },
+        { level: 2, intervalMs: 300_000 },
+        { level: 3, intervalMs: 3_600_000 },
+    ]);
+}
+/**
+ * PrevCompactionAt returns the start of the current compaction bucket for
+ * `intervalMs`. Compaction for a level only proceeds once per bucket, so
+ * repeated syncs across a window collapse into one compacted file.
+ */
+export function prevCompactionAt(now, intervalMs) {
+    if (intervalMs <= 0)
+        return now;
+    return Math.floor(now / intervalMs) * intervalMs;
+}
+/** NextCompactionAt returns the start of the next compaction bucket. */
+export function nextCompactionAt(now, intervalMs) {
+    return prevCompactionAt(now, intervalMs) + intervalMs;
+}
+/** Interval (ms) constants matching litestream's defaults. */
+export const DefaultSnapshotIntervalMs = 24 * 60 * 60 * 1000; // 24h
+export const DefaultSnapshotRetentionMs = 24 * 60 * 60 * 1000; // 24h
+export const DefaultL0RetentionMs = 5 * 60 * 1000; // 5m
+export const DefaultL0RetentionCheckIntervalMs = 15 * 1000; // 15s

package/dist/ltx/compactor.d.ts

@@ -0,0 +1,33 @@
+/**
+ * LTX Compactor merges multiple LTX files (readers) into a single stream,
+ * where later files override earlier ones for the same page number.
+ *
+ * Mirrors Go's `ltx.Compactor`. Used by restore (snapshot + incremental L0
+ * files) and by multi-level compaction.
+ */
+import type { Header, Trailer } from './types.js';
+import type { ByteSink } from './sink.js';
+/** Compactor merges LTX readers into a single writer. */
+export declare class Compactor {
+    private enc;
+    private inputs;
+    private _headerFlags;
+    private allowNonContiguousTXIDs;
+    constructor(sink: ByteSink, readers: Uint8Array[]);
+    get headerFlags(): number;
+    set headerFlags(flags: number);
+    /** AllowNonContiguousTXIDs disables contiguous-TXID validation between inputs. */
+    setAllowNonContiguousTXIDs(v: boolean): void;
+    /** Header returns the output header (after Compact). */
+    Header(): Header;
+    /** Trailer returns the output trailer (after Compact). */
+    Trailer(): Trailer;
+    /** Compact merges all input readers into a single LTX stream. */
+    compact(): void;
+    private writePageBlock;
+    /** Fills input buffers and returns the smallest available page number. */
+    private fillPageBuffers;
+    /** Writes the buffer with a matching pgno from the latest input. */
+    private writePageBuffer;
+}
+//# sourceMappingURL=compactor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compactor.d.ts","sourceRoot":"","sources":["../../src/ltx/compactor.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAc,OAAO,EAAE,MAAM,YAAY,CAAC;AAE9D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAW1C,yDAAyD;AACzD,qBAAa,SAAS;IACpB,OAAO,CAAC,GAAG,CAAU;IACrB,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,uBAAuB,CAAS;gBAE5B,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE;IASjD,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,IAAI,WAAW,CAAC,KAAK,EAAE,MAAM,EAE5B;IAED,kFAAkF;IAClF,0BAA0B,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI;IAI5C,wDAAwD;IACxD,MAAM,IAAI,MAAM;IAIhB,0DAA0D;IAC1D,OAAO,IAAI,OAAO;IAIlB,iEAAiE;IACjE,OAAO,IAAI,IAAI;IA2Df,OAAO,CAAC,cAAc;IAYtB,0EAA0E;IAC1E,OAAO,CAAC,eAAe;IAevB,oEAAoE;IACpE,OAAO,CAAC,eAAe;CAiBxB"}