turbodata 0.1.0

package/dist/read_planner.d.ts

@@ -0,0 +1,37 @@
+import type { ReadStrategy } from "./read_strategy.js";
+export interface Range {
+    /** int64. Absolute file offset. */
+    offset: bigint;
+    /** int64. Length in bytes. */
+    length: bigint;
+}
+export interface ReadOp {
+    offset: bigint;
+    length: bigint;
+}
+export interface RangeLocation {
+    /** Index into the produced ReadOp[]. */
+    opIndex: number;
+    /** Byte offset within that op's buffer (must fit in number; ops are bounded). */
+    inOpOff: number;
+    /** Length of this original range, in bytes. */
+    length: number;
+}
+/**
+ * Plan groups Ranges into ReadOps.
+ *
+ * Precondition: ranges must be in non-decreasing offset order. All call sites
+ * in this package satisfy this by construction (writer lays out groups and
+ * chunks at monotonically increasing file offsets).
+ *
+ * Algorithm:
+ *  1. Coalesce: merge adjacent ranges whose gap is < coalesceGap.
+ *  2. Split: a coalesced op whose length exceeds splitThreshold is sliced at
+ *     internal range boundaries via greedy packing. A single range larger
+ *     than splitThreshold stays as one oversize op (atomic units never break).
+ */
+export declare function plan(ranges: Range[], s: ReadStrategy): {
+    ops: ReadOp[];
+    locations: RangeLocation[];
+};
+//# sourceMappingURL=read_planner.d.ts.map

package/dist/read_planner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read_planner.d.ts","sourceRoot":"","sources":["../src/read_planner.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,MAAM,WAAW,KAAK;IACpB,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,MAAM;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;CAChB;AAQD;;;;;;;;;;;;GAYG;AACH,wBAAgB,IAAI,CAClB,MAAM,EAAE,KAAK,EAAE,EACf,CAAC,EAAE,YAAY,GACd;IAAE,GAAG,EAAE,MAAM,EAAE,CAAC;IAAC,SAAS,EAAE,aAAa,EAAE,CAAA;CAAE,CA0F/C"}

package/dist/read_planner.js

@@ -0,0 +1,110 @@
+// Copyright 2026 Wanjia He
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+/**
+ * Plan groups Ranges into ReadOps.
+ *
+ * Precondition: ranges must be in non-decreasing offset order. All call sites
+ * in this package satisfy this by construction (writer lays out groups and
+ * chunks at monotonically increasing file offsets).
+ *
+ * Algorithm:
+ *  1. Coalesce: merge adjacent ranges whose gap is < coalesceGap.
+ *  2. Split: a coalesced op whose length exceeds splitThreshold is sliced at
+ *     internal range boundaries via greedy packing. A single range larger
+ *     than splitThreshold stays as one oversize op (atomic units never break).
+ */
+export function plan(ranges, s) {
+    const locations = new Array(ranges.length);
+    if (ranges.length === 0) {
+        return { ops: [], locations };
+    }
+    const groups = [];
+    for (let idx = 0; idx < ranges.length; idx++) {
+        const r = ranges[idx];
+        if (groups.length === 0) {
+            groups.push({
+                offset: r.offset,
+                end: r.offset + r.length,
+                members: [idx],
+            });
+            continue;
+        }
+        const cur = groups[groups.length - 1];
+        const gap = r.offset - cur.end;
+        if (gap >= 0n && gap < s.coalesceGap) {
+            const newEnd = r.offset + r.length;
+            if (newEnd > cur.end) {
+                cur.end = newEnd;
+            }
+            cur.members.push(idx);
+            continue;
+        }
+        groups.push({
+            offset: r.offset,
+            end: r.offset + r.length,
+            members: [idx],
+        });
+    }
+    const ops = [];
+    const threshold = s.splitThreshold;
+    const splitDisabled = threshold <= 0n;
+    for (const g of groups) {
+        if (splitDisabled || g.end - g.offset <= threshold) {
+            const opIndex = ops.length;
+            ops.push({ offset: g.offset, length: g.end - g.offset });
+            for (const mi of g.members) {
+                const r = ranges[mi];
+                locations[mi] = {
+                    opIndex,
+                    inOpOff: Number(r.offset - g.offset),
+                    length: Number(r.length),
+                };
+            }
+            continue;
+        }
+        // Greedy split at range boundaries.
+        let opStartIdx = 0;
+        let opStartOffset = ranges[g.members[0]].offset;
+        let opEndOffset = ranges[g.members[0]].offset + ranges[g.members[0]].length;
+        const flushOp = (lastMember) => {
+            const opIndex = ops.length;
+            ops.push({ offset: opStartOffset, length: opEndOffset - opStartOffset });
+            for (let k = opStartIdx; k <= lastMember; k++) {
+                const mi = g.members[k];
+                const r = ranges[mi];
+                locations[mi] = {
+                    opIndex,
+                    inOpOff: Number(r.offset - opStartOffset),
+                    length: Number(r.length),
+                };
+            }
+        };
+        for (let k = 1; k < g.members.length; k++) {
+            const mi = g.members[k];
+            const r = ranges[mi];
+            const nextEnd = r.offset + r.length;
+            if (nextEnd - opStartOffset > threshold) {
+                flushOp(k - 1);
+                opStartIdx = k;
+                opStartOffset = r.offset;
+                opEndOffset = nextEnd;
+                continue;
+            }
+            opEndOffset = nextEnd;
+        }
+        flushOp(g.members.length - 1);
+    }
+    return { ops, locations };
+}
+//# sourceMappingURL=read_planner.js.map

package/dist/read_planner.js.map

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

package/dist/read_source.d.ts

@@ -0,0 +1,19 @@
+/**
+ * ReadSource is the storage abstraction the Reader uses. It is intentionally
+ * minimal: every Go ReadAt/Read+Seek call site can be expressed as `read(off,
+ * len)`.
+ *
+ * Concurrency contract: implementations MUST be safe for concurrent `read`
+ * calls. The cost-aware reader path issues many in-flight reads bounded only
+ * by `maxConcurrency`.
+ */
+export interface ReadSource {
+    /** Total length of the underlying file/blob/resource, in bytes. */
+    size(): Promise<bigint>;
+    /**
+     * Read exactly `length` bytes starting at `offset`. Implementations should
+     * throw if fewer bytes are available; the Reader assumes a full read.
+     */
+    read(offset: bigint, length: bigint): Promise<Uint8Array>;
+}
+//# sourceMappingURL=read_source.d.ts.map

package/dist/read_source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read_source.d.ts","sourceRoot":"","sources":["../src/read_source.ts"],"names":[],"mappings":"AAcA;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACzB,mEAAmE;IACnE,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAExB;;;OAGG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CAC3D"}

package/dist/read_source.js

@@ -0,0 +1,15 @@
+// Copyright 2026 Wanjia He
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+export {};
+//# sourceMappingURL=read_source.js.map

package/dist/read_source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read_source.js","sourceRoot":"","sources":["../src/read_source.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAC3B,EAAE;AACF,kEAAkE;AAClE,mEAAmE;AACnE,0CAA0C;AAC1C,EAAE;AACF,iDAAiD;AACjD,EAAE;AACF,sEAAsE;AACtE,oEAAoE;AACpE,2EAA2E;AAC3E,sEAAsE;AACtE,iCAAiC"}

package/dist/read_strategy.d.ts

@@ -0,0 +1,52 @@
+export interface ReadStrategy {
+    /**
+     * int64. Byte gap below which two adjacent needed ranges are merged into
+     * a single read. 0n disables coalescing.
+     */
+    coalesceGap: bigint;
+    /**
+     * int64. Size above which a merged read is sliced into parallel sub-reads
+     * at internal range boundaries. A single range larger than splitThreshold
+     * stays as one oversized op (atomic units are never split). 0n or
+     * int64-max disables splitting.
+     */
+    splitThreshold: bigint;
+    /** Max number of in-flight reads. <= 0 is clamped to 1 (serial). */
+    maxConcurrency: number;
+}
+/**
+ * Strategy that minimizes wall-clock by amortizing per-request RTT and
+ * splitting reads at the bandwidth-latency product so each parallel sub-read
+ * keeps a stream saturated for ~one RTT.
+ */
+export declare function StrategyForLatency(opts: {
+    rttSeconds: number;
+    perStreamBytesPerSec: number;
+    concurrency: number;
+}): ReadStrategy;
+/**
+ * Strategy that minimizes total spend by aggressively coalescing (to save
+ * requests) and never splitting (extra splits = extra paid requests).
+ *
+ * Set bytePrice to 0 for free in-region egress; then coalescing happens
+ * regardless of gap.
+ */
+export declare function StrategyForMoney(opts: {
+    reqPrice: number;
+    bytePrice: number;
+    concurrency: number;
+}): ReadStrategy;
+/**
+ * Strategy that minimizes spend (via the same money-driven coalesceGap as
+ * StrategyForMoney) but caps how long any single read may take by splitting
+ * reads larger than maxReadTimeSeconds * perStreamBytesPerSec into parallel
+ * sub-reads.
+ */
+export declare function StrategyForBlended(opts: {
+    reqPrice: number;
+    bytePrice: number;
+    maxReadTimeSeconds: number;
+    perStreamBytesPerSec: number;
+    concurrency: number;
+}): ReadStrategy;
+//# sourceMappingURL=read_strategy.d.ts.map

package/dist/read_strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read_strategy.d.ts","sourceRoot":"","sources":["../src/read_strategy.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;;;OAKG;IACH,cAAc,EAAE,MAAM,CAAC;IAEvB,oEAAoE;IACpE,cAAc,EAAE,MAAM,CAAC;CACxB;AAID;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,YAAY,CAUf;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,YAAY,CAUf;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,YAAY,CAgBf"}

package/dist/read_strategy.js

@@ -0,0 +1,70 @@
+// Copyright 2026 Wanjia He
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+const MAX_INT64 = 0x7fffffffffffffffn;
+/**
+ * Strategy that minimizes wall-clock by amortizing per-request RTT and
+ * splitting reads at the bandwidth-latency product so each parallel sub-read
+ * keeps a stream saturated for ~one RTT.
+ */
+export function StrategyForLatency(opts) {
+    let bdp = BigInt(Math.trunc(opts.rttSeconds * opts.perStreamBytesPerSec));
+    if (bdp <= 0n) {
+        bdp = 1n;
+    }
+    return {
+        coalesceGap: bdp,
+        splitThreshold: bdp,
+        maxConcurrency: opts.concurrency,
+    };
+}
+/**
+ * Strategy that minimizes total spend by aggressively coalescing (to save
+ * requests) and never splitting (extra splits = extra paid requests).
+ *
+ * Set bytePrice to 0 for free in-region egress; then coalescing happens
+ * regardless of gap.
+ */
+export function StrategyForMoney(opts) {
+    let gap = MAX_INT64;
+    if (opts.bytePrice > 0) {
+        gap = BigInt(Math.trunc(opts.reqPrice / opts.bytePrice));
+    }
+    return {
+        coalesceGap: gap,
+        splitThreshold: MAX_INT64,
+        maxConcurrency: opts.concurrency,
+    };
+}
+/**
+ * Strategy that minimizes spend (via the same money-driven coalesceGap as
+ * StrategyForMoney) but caps how long any single read may take by splitting
+ * reads larger than maxReadTimeSeconds * perStreamBytesPerSec into parallel
+ * sub-reads.
+ */
+export function StrategyForBlended(opts) {
+    let gap = MAX_INT64;
+    if (opts.bytePrice > 0) {
+        gap = BigInt(Math.trunc(opts.reqPrice / opts.bytePrice));
+    }
+    let split = BigInt(Math.trunc(opts.maxReadTimeSeconds * opts.perStreamBytesPerSec));
+    if (split <= 0n) {
+        split = MAX_INT64;
+    }
+    return {
+        coalesceGap: gap,
+        splitThreshold: split,
+        maxConcurrency: opts.concurrency,
+    };
+}
+//# sourceMappingURL=read_strategy.js.map

package/dist/read_strategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read_strategy.js","sourceRoot":"","sources":["../src/read_strategy.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAC3B,EAAE;AACF,kEAAkE;AAClE,mEAAmE;AACnE,0CAA0C;AAC1C,EAAE;AACF,iDAAiD;AACjD,EAAE;AACF,sEAAsE;AACtE,oEAAoE;AACpE,2EAA2E;AAC3E,sEAAsE;AACtE,iCAAiC;AAwBjC,MAAM,SAAS,GAAG,mBAAmB,CAAC;AAEtC;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAIlC;IACC,IAAI,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,oBAAoB,CAAC,CAAC,CAAC;IAC1E,IAAI,GAAG,IAAI,EAAE,EAAE,CAAC;QACd,GAAG,GAAG,EAAE,CAAC;IACX,CAAC;IACD,OAAO;QACL,WAAW,EAAE,GAAG;QAChB,cAAc,EAAE,GAAG;QACnB,cAAc,EAAE,IAAI,CAAC,WAAW;KACjC,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAIhC;IACC,IAAI,GAAG,GAAG,SAAS,CAAC;IACpB,IAAI,IAAI,CAAC,SAAS,GAAG,CAAC,EAAE,CAAC;QACvB,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO;QACL,WAAW,EAAE,GAAG;QAChB,cAAc,EAAE,SAAS;QACzB,cAAc,EAAE,IAAI,CAAC,WAAW;KACjC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAMlC;IACC,IAAI,GAAG,GAAG,SAAS,CAAC;IACpB,IAAI,IAAI,CAAC,SAAS,GAAG,CAAC,EAAE,CAAC;QACvB,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;IAC3D,CAAC;IACD,IAAI,KAAK,GAAG,MAAM,CAChB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC,oBAAoB,CAAC,CAChE,CAAC;IACF,IAAI,KAAK,IAAI,EAAE,EAAE,CAAC;QAChB,KAAK,GAAG,SAAS,CAAC;IACpB,CAAC;IACD,OAAO;QACL,WAAW,EAAE,GAAG;QAChB,cAAc,EAAE,KAAK;QACrB,cAAc,EAAE,IAAI,CAAC,WAAW;KACjC,CAAC;AACJ,CAAC"}

package/dist/reader.d.ts

@@ -0,0 +1,209 @@
+import type { Decompressor } from "./compression.js";
+import type { ReadOptions } from "./read_options.js";
+import type { ReadSource } from "./read_source.js";
+import type { ReadStrategy } from "./read_strategy.js";
+import { type Summary } from "./types.js";
+export interface Message {
+    /** int64 nanosecond (or arbitrary unit) timestamp from the writer. */
+    timestamp: bigint;
+    topicName: string;
+    /**
+     * Message bytes. By default this aliases an internal reusable buffer and
+     * is only valid until the next iteration step. Pass `{ copy: true }` to
+     * receive a fresh Uint8Array per message.
+     */
+    data: Uint8Array;
+}
+export interface ReaderOptions {
+    /** Override the default fzstd decompressor (e.g. for a WASM zstd build). */
+    decompress?: Decompressor;
+    /**
+     * Present in-file topic names under different exposed names. Keyed by in-file
+     * name, valued by the exposed name emitted from readMessages, accepted by
+     * ReadOptions.topicNames and SampleQuery.topic, and reported by summary().
+     * Names absent from the map pass through unchanged; omitting it means
+     * identity (no behavior change).
+     *
+     * Validated lazily against the file's summary on first use: it throws a
+     * TopicRemapError when two topics collapse onto the same exposed name
+     * (whether two in-file names map to the same target, or a renamed name
+     * collides with an untouched in-file name).
+     */
+    topicRemap?: Record<string, string>;
+}
+/**
+ * Thrown when a configured topic remap collapses two in-file topics onto the
+ * same exposed name. Detected lazily against the summary on first use.
+ */
+export declare class TopicRemapError extends Error {
+    readonly exposed: string;
+    readonly first: string;
+    readonly second: string;
+    constructor(exposed: string, first: string, second: string);
+}
+/**
+ * One sampling request: the floor message of `topic` at each timestamp.
+ * Within `timestamps`, values must be strictly increasing, and the same
+ * `topic` must not appear in more than one query in a single sample() call.
+ */
+export interface SampleQuery {
+    topic: string;
+    /** int64 timestamps; strictly increasing. */
+    timestamps: bigint[];
+}
+/**
+ * One coded video frame surfaced as part of a SampleResult's GOP prefix or
+ * incremental tail. `data` is an owned copy and is safe to retain.
+ */
+export interface Frame {
+    timestamp: bigint;
+    isKeyFrame: boolean;
+    data: Uint8Array;
+}
+/**
+ * One returned floor message. out[i][j] corresponds to queries[i].timestamps[j].
+ * `found` is false when there is no message with timestamp <= timestamps[j]
+ * for the topic.
+ *
+ * Without videoDecodable, every topic (including video topics) returns its
+ * floor message in `data` (an owned copy), `isVideo` is false, and `frames` /
+ * `resetDecoder` are unset.
+ *
+ * With videoDecodable, results for video topics instead carry a decoder-ready
+ * GOP sequence and set `isVideo` true. For those results, within a single row
+ * (one topic, strictly increasing query timestamps):
+ *
+ *   - `data` is empty; the frame bytes live in `frames` and the target frame
+ *     is the last element. `timestamp` names that target frame.
+ *   - For the first found result in each GOP encountered in the row:
+ *     `resetDecoder` is true, `frames` = [keyframe ... target] in storage
+ *     (decode) order. The decoder must reset before feeding.
+ *   - For subsequent found results within the same GOP: `resetDecoder` is
+ *     false, `frames` = [previous_target+1 ... target] (only the new frames).
+ *     `frames` is empty when two queries resolve to the same target frame;
+ *     `timestamp` still names that target.
+ */
+export interface SampleResult {
+    found: boolean;
+    timestamp: bigint;
+    data: Uint8Array;
+    isVideo: boolean;
+    frames: Frame[];
+    resetDecoder: boolean;
+}
+/** Options for Reader.sample(). */
+export interface SampleOptions {
+    /**
+     * Cost model for the concurrent reads. Defaults to DEFAULT_SAMPLE_STRATEGY,
+     * which is sized for a cloud-object / in-region profile.
+     */
+    strategy?: ReadStrategy;
+    /**
+     * int64. Bytes to read speculatively from the file tail when loading the
+     * summary. Same semantics as ReadOptions.tailPrefetch.
+     */
+    tailPrefetch?: bigint;
+    /**
+     * When true, results for video topics carry a decoder-ready GOP sequence
+     * (frames + resetDecoder) and set isVideo. See SampleResult. Non-video
+     * topics are unaffected. Default: false.
+     */
+    videoDecodable?: boolean;
+}
+/**
+ * Default strategy for Reader.sample when none is supplied. Mirrors the Go and
+ * Python DEFAULT_SAMPLE_STRATEGY (1 MiB coalesce, 4 MiB split, 16-way fanout).
+ */
+export declare const DEFAULT_SAMPLE_STRATEGY: ReadStrategy;
+/**
+ * Aggregated precondition failures from Reader.sample, raised before any data
+ * I/O. `violations` lists every problem found across all queries.
+ */
+export declare class SampleValidationError extends Error {
+    readonly violations: string[];
+    constructor(violations: string[]);
+}
+/**
+ * N timestamps starting at `start`, each `stride` apart. Useful for "N samples
+ * at a given frequency from T" patterns. Mirrors Go LinSpaceTimestamps.
+ * Returns [] when count <= 0; throws when stride <= 0 (would break the
+ * strictly-increasing contract on SampleQuery.timestamps).
+ */
+export declare function linSpaceTimestamps(start: bigint, stride: bigint, count: number): bigint[];
+/**
+ * Per-exposed-topic span used by MultiReader. `isVideo` flags a video topic
+ * (always a single-topic group); [minTs, maxTs] is the inclusive timestamp
+ * span of the topic's messages. Mirrors go topicBound / py _TopicBound.
+ *
+ * @internal
+ */
+export interface TopicBound {
+    isVideo: boolean;
+    minTs: bigint;
+    maxTs: bigint;
+}
+export declare class Reader {
+    private readonly rs;
+    private readonly decompress;
+    private cachedSize;
+    private cachedSummary;
+    private boundsCache;
+    private readonly topicRemap;
+    private renamePrepared;
+    private renameInverse;
+    private renameErr;
+    constructor(rs: ReadSource, opts?: ReaderOptions);
+    /**
+     * Build the exposed -> in-file inverse map once the summary is known and
+     * validate that no two topics collapse onto the same exposed name. Results
+     * (including any error) are cached. Returns undefined when no remap is set.
+     */
+    private prepareRename;
+    /**
+     * Return a copy of `summary` with TopicMetadata.name rewritten to exposed
+     * names. Index-chunk lists and metadata maps are shared (read-only here).
+     * Returns the original summary when no remap is configured.
+     */
+    private exposedSummary;
+    /**
+     * Returns the parsed summary, loading and caching it on first call. When a
+     * topic remap is configured, TopicMetadata.name reports exposed names.
+     */
+    summary(): Promise<Summary>;
+    private summaryWithHint;
+    /**
+     * Read messages. Returns an async iterable; iterating consumes lazily.
+     *
+     * Concurrency note: because the iterator carries internal mutable state
+     * (cursors and a reusable buffer), only one iteration at a time over the
+     * same returned async iterable is supported.
+     */
+    readMessages(opts?: ReadOptions): AsyncIterableIterator<Message>;
+    /**
+     * Floor-message lookup at concrete timestamps per topic. For each
+     * (queries[i].topic, queries[i].timestamps[j]) pair, out[i][j] is the
+     * message with the greatest timestamp <= timestamps[j], or found=false when
+     * none exists.
+     *
+     * Preconditions, validated before any data I/O (all violations aggregated
+     * into a single SampleValidationError):
+     *   - each queries[i].timestamps must be strictly increasing
+     *   - each queries[i].topic must be unique across all i
+     *   - each queries[i].topic must exist in the file's summary
+     *
+     * All data I/O runs concurrently under the hood, governed by the strategy.
+     */
+    sample(queries: SampleQuery[], opts?: SampleOptions): Promise<SampleResult[][]>;
+    /**
+     * Per-exposed-topic bounds, computed once from the cached summary. Honors any
+     * configured remap so keys are exposed names. Used by MultiReader to merge
+     * streams and enforce video time-disjointness. Mirrors go (*Reader).topicBounds
+     * and py Reader._topic_bounds.
+     *
+     * @internal
+     */
+    topicBounds(): Promise<Map<string, TopicBound>>;
+    private prepareDefault;
+    private prepareCostAware;
+}
+//# sourceMappingURL=reader.d.ts.map

package/dist/reader.d.ts.map

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