turbodata 0.1.0

package/dist/loaded_bytes.d.ts

@@ -0,0 +1,12 @@
+import type { Range, RangeLocation } from "./read_planner.js";
+export declare class LoadedBytes {
+    private readonly buffers;
+    private readonly index;
+    constructor(ranges: Range[], locations: RangeLocation[], buffers: Uint8Array[]);
+    /**
+     * Return the slice for the range registered at offset. The returned
+     * Uint8Array aliases the underlying buffer; callers must not mutate it.
+     */
+    get(offset: bigint): Uint8Array | undefined;
+}
+//# sourceMappingURL=loaded_bytes.d.ts.map

package/dist/loaded_bytes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loaded_bytes.d.ts","sourceRoot":"","sources":["../src/loaded_bytes.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAQ9D,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6B;gBAGjD,MAAM,EAAE,KAAK,EAAE,EACf,SAAS,EAAE,aAAa,EAAE,EAC1B,OAAO,EAAE,UAAU,EAAE;IAevB;;;OAGG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;CAQ5C"}

package/dist/loaded_bytes.js

@@ -0,0 +1,43 @@
+// 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 class LoadedBytes {
+    buffers;
+    index;
+    constructor(ranges, locations, buffers) {
+        this.buffers = buffers;
+        this.index = new Map();
+        for (let i = 0; i < ranges.length; i++) {
+            const r = ranges[i];
+            const loc = locations[i];
+            this.index.set(r.offset, {
+                bufferIdx: loc.opIndex,
+                inBufOff: loc.inOpOff,
+                length: loc.length,
+            });
+        }
+    }
+    /**
+     * Return the slice for the range registered at offset. The returned
+     * Uint8Array aliases the underlying buffer; callers must not mutate it.
+     */
+    get(offset) {
+        const loc = this.index.get(offset);
+        if (loc === undefined) {
+            return undefined;
+        }
+        const buf = this.buffers[loc.bufferIdx];
+        return buf.subarray(loc.inBufOff, loc.inBufOff + loc.length);
+    }
+}
+//# sourceMappingURL=loaded_bytes.js.map

package/dist/loaded_bytes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loaded_bytes.js","sourceRoot":"","sources":["../src/loaded_bytes.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;AAcjC,MAAM,OAAO,WAAW;IACL,OAAO,CAAe;IACtB,KAAK,CAA6B;IAEnD,YACE,MAAe,EACf,SAA0B,EAC1B,OAAqB;QAErB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,KAAK,GAAG,IAAI,GAAG,EAAE,CAAC;QACvB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACvC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAE,CAAC;YACrB,MAAM,GAAG,GAAG,SAAS,CAAC,CAAC,CAAE,CAAC;YAC1B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE;gBACvB,SAAS,EAAE,GAAG,CAAC,OAAO;gBACtB,QAAQ,EAAE,GAAG,CAAC,OAAO;gBACrB,MAAM,EAAE,GAAG,CAAC,MAAM;aACnB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,GAAG,CAAC,MAAc;QAChB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACnC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAE,CAAC;QACzC,OAAO,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,QAAQ,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC;IAC/D,CAAC;CACF"}

package/dist/msgpack.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Decode a msgpack-encoded map into a Map<string, unknown>.
+ *
+ * - `useBigInt64: true` so any int64 values round-trip exactly as bigint.
+ *   Smaller integers (int32 and below) decode as number.
+ * - The Go writer always msgpack-encodes a `map[string]any`. We coerce the
+ *   decoded plain object into a `Map` for an unambiguous string-keyed view.
+ */
+export declare function decodeMetadata(buf: Uint8Array): Map<string, unknown>;
+//# sourceMappingURL=msgpack.d.ts.map

package/dist/msgpack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"msgpack.d.ts","sourceRoot":"","sources":["../src/msgpack.ts"],"names":[],"mappings":"AAmBA;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,UAAU,GAAG,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAkBpE"}

package/dist/msgpack.js

@@ -0,0 +1,44 @@
+// 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.
+// msgpack decoder for TopicMetadata.Metadata. Uses @msgpack/msgpack with
+// useBigInt64 so int64 values round-trip exactly.
+import { decode } from "@msgpack/msgpack";
+/**
+ * Decode a msgpack-encoded map into a Map<string, unknown>.
+ *
+ * - `useBigInt64: true` so any int64 values round-trip exactly as bigint.
+ *   Smaller integers (int32 and below) decode as number.
+ * - The Go writer always msgpack-encodes a `map[string]any`. We coerce the
+ *   decoded plain object into a `Map` for an unambiguous string-keyed view.
+ */
+export function decodeMetadata(buf) {
+    const decoded = decode(buf, { useBigInt64: true });
+    const out = new Map();
+    if (decoded === null || typeof decoded !== "object") {
+        return out;
+    }
+    if (decoded instanceof Map) {
+        for (const [k, v] of decoded) {
+            if (typeof k === "string") {
+                out.set(k, v);
+            }
+        }
+        return out;
+    }
+    for (const k of Object.keys(decoded)) {
+        out.set(k, decoded[k]);
+    }
+    return out;
+}
+//# sourceMappingURL=msgpack.js.map

package/dist/msgpack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"msgpack.js","sourceRoot":"","sources":["../src/msgpack.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;AAEjC,yEAAyE;AACzE,kDAAkD;AAElD,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE1C;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,GAAe;IAC5C,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;IACnD,MAAM,GAAG,GAAG,IAAI,GAAG,EAAmB,CAAC;IACvC,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QACpD,OAAO,GAAG,CAAC;IACb,CAAC;IACD,IAAI,OAAO,YAAY,GAAG,EAAE,CAAC;QAC3B,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,OAAgC,EAAE,CAAC;YACtD,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;gBAC1B,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YAChB,CAAC;QACH,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,OAAkC,CAAC,EAAE,CAAC;QAChE,GAAG,CAAC,GAAG,CAAC,CAAC,EAAG,OAAmC,CAAC,CAAC,CAAC,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/multi_reader.d.ts

@@ -0,0 +1,56 @@
+import type { ReadOptions } from "./read_options.js";
+import { Reader, type Message, type SampleOptions, type SampleQuery, type SampleResult } from "./reader.js";
+/**
+ * Thrown by MultiReader.sample/readMessages under videoDecodable when a queried
+ * video topic is provided by more than one reader whose time ranges overlap.
+ * Decodable multi-file video requires each video topic's source files to be
+ * time-disjoint; merging overlapping decodable sources would interleave frames
+ * from different GOP chains into an undecodable stream. Mirrors go
+ * ErrVideoSourcesOverlap / py VideoSourcesOverlapError.
+ */
+export declare class VideoSourcesOverlapError extends Error {
+    readonly topic: string;
+    readonly first: readonly [bigint, bigint];
+    readonly second: readonly [bigint, bigint];
+    constructor(topic: string, first: readonly [bigint, bigint], second: readonly [bigint, bigint]);
+}
+export declare class MultiReader {
+    private readonly readers;
+    /**
+     * Group readers into one merged view. At least one reader is required.
+     * Per-file behavior (remap, etc.) lives on each underlying Reader.
+     */
+    constructor(readers: Reader[]);
+    /**
+     * Read every reader's messages as one merged, time-ordered stream. Options
+     * pass through to each underlying Reader.readMessages unchanged, so order,
+     * time bounds, topic filtering (by exposed name), and strategy apply per file
+     * before the merge.
+     *
+     * When videoDecodable is set, any in-scope video topic supplied by more than
+     * one reader must have time-disjoint source ranges; overlapping sources throw
+     * VideoSourcesOverlapError (merging them would interleave frames from
+     * different GOP chains into an undecodable stream). As with the single
+     * Reader, all I/O (and this check) is deferred to the first iteration step.
+     */
+    readMessages(opts?: ReadOptions): AsyncIterableIterator<Message>;
+    /**
+     * Resolve floor messages across every reader. For each
+     * (queries[i].topic, queries[i].timestamps[j]) pair, out[i][j] is the floor
+     * result with the latest found timestamp among all readers that hold the
+     * topic (by exposed name) - the true floor over the union. Ties resolve
+     * arbitrarily.
+     *
+     * Preconditions, validated before any data I/O (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 at least one reader
+     *
+     * When videoDecodable is set, a video topic supplied by more than one reader
+     * must have time-disjoint source ranges; overlapping sources throw
+     * VideoSourcesOverlapError.
+     */
+    sample(queries: SampleQuery[], opts?: SampleOptions): Promise<SampleResult[][]>;
+}
+//# sourceMappingURL=multi_reader.d.ts.map

package/dist/multi_reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi_reader.d.ts","sourceRoot":"","sources":["../src/multi_reader.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EACL,MAAM,EAEN,KAAK,OAAO,EACZ,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,YAAY,EAElB,MAAM,aAAa,CAAC;AAErB;;;;;;;GAOG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;gBAEzC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC;CAUpC;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAW;IAEnC;;;OAGG;gBACS,OAAO,EAAE,MAAM,EAAE;IAO7B;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,IAAI,GAAE,WAAgB,GAAG,qBAAqB,CAAC,OAAO,CAAC;IAwEpE;;;;;;;;;;;;;;;;OAgBG;IACG,MAAM,CACV,OAAO,EAAE,WAAW,EAAE,EACtB,IAAI,GAAE,aAAkB,GACvB,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC;CAwD7B"}

package/dist/multi_reader.js

@@ -0,0 +1,281 @@
+// 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.
+// MultiReader: present several single-file Readers as one time-ordered stream.
+// Mirrors go/multi_reader.go and py/turbodata/multi_reader.py.
+//
+// readMessages merges every reader's stream in timestamp order; sample resolves
+// floor messages across the union of readers. Both operate entirely in each
+// Reader's exposed-name space. Topic-name collisions across files are the
+// caller's responsibility: configure per-Reader topicRemap so that names meant
+// to union share an exposed name and names meant to stay distinct do not.
+import { MessageHeap } from "./iterators/message_heap.js";
+import { SampleValidationError, } from "./reader.js";
+/**
+ * Thrown by MultiReader.sample/readMessages under videoDecodable when a queried
+ * video topic is provided by more than one reader whose time ranges overlap.
+ * Decodable multi-file video requires each video topic's source files to be
+ * time-disjoint; merging overlapping decodable sources would interleave frames
+ * from different GOP chains into an undecodable stream. Mirrors go
+ * ErrVideoSourcesOverlap / py VideoSourcesOverlapError.
+ */
+export class VideoSourcesOverlapError extends Error {
+    topic;
+    first;
+    second;
+    constructor(topic, first, second) {
+        super(`turbodata: video topic "${topic}" sources [${first[0]},${first[1]}] and [${second[0]},${second[1]}] overlap in time`);
+        this.name = "VideoSourcesOverlapError";
+        this.topic = topic;
+        this.first = first;
+        this.second = second;
+    }
+}
+export class MultiReader {
+    readers;
+    /**
+     * Group readers into one merged view. At least one reader is required.
+     * Per-file behavior (remap, etc.) lives on each underlying Reader.
+     */
+    constructor(readers) {
+        if (readers.length === 0) {
+            throw new Error("turbodata: MultiReader requires at least one reader");
+        }
+        this.readers = readers;
+    }
+    /**
+     * Read every reader's messages as one merged, time-ordered stream. Options
+     * pass through to each underlying Reader.readMessages unchanged, so order,
+     * time bounds, topic filtering (by exposed name), and strategy apply per file
+     * before the merge.
+     *
+     * When videoDecodable is set, any in-scope video topic supplied by more than
+     * one reader must have time-disjoint source ranges; overlapping sources throw
+     * VideoSourcesOverlapError (merging them would interleave frames from
+     * different GOP chains into an undecodable stream). As with the single
+     * Reader, all I/O (and this check) is deferred to the first iteration step.
+     */
+    readMessages(opts = {}) {
+        const readers = this.readers;
+        const reverse = opts.order === "reverse-time";
+        const videoDecodable = opts.videoDecodable === true;
+        const wantedNames = opts.topicNames;
+        let initialized = false;
+        let exhausted = false;
+        const subs = [];
+        const heap = new MessageHeap(reverse);
+        const init = async () => {
+            for (const r of readers) {
+                subs.push(r.readMessages(opts));
+            }
+            if (videoDecodable) {
+                const bounds = await Promise.all(readers.map((r) => r.topicBounds()));
+                enforceVideoDisjoint(readScopeTopics(wantedNames, bounds), bounds);
+            }
+            // Prime the heap with one message from each reader's stream.
+            for (let i = 0; i < subs.length; i++) {
+                const res = await subs[i].next();
+                if (res.done === true) {
+                    continue;
+                }
+                heap.push(res.value.timestamp, { subIdx: i, msg: res.value });
+            }
+        };
+        const iter = {
+            [Symbol.asyncIterator]() {
+                return iter;
+            },
+            async next() {
+                if (exhausted) {
+                    return { value: undefined, done: true };
+                }
+                if (!initialized) {
+                    await init();
+                    initialized = true;
+                }
+                const top = heap.pop();
+                if (top === undefined) {
+                    exhausted = true;
+                    return { value: undefined, done: true };
+                }
+                const out = top.value.msg;
+                const nm = await subs[top.value.subIdx].next();
+                if (nm.done !== true) {
+                    heap.push(nm.value.timestamp, {
+                        subIdx: top.value.subIdx,
+                        msg: nm.value,
+                    });
+                }
+                return { value: out, done: false };
+            },
+            async return() {
+                exhausted = true;
+                for (const s of subs) {
+                    if (s.return !== undefined) {
+                        await s.return();
+                    }
+                }
+                return { value: undefined, done: true };
+            },
+        };
+        return iter;
+    }
+    /**
+     * Resolve floor messages across every reader. For each
+     * (queries[i].topic, queries[i].timestamps[j]) pair, out[i][j] is the floor
+     * result with the latest found timestamp among all readers that hold the
+     * topic (by exposed name) - the true floor over the union. Ties resolve
+     * arbitrarily.
+     *
+     * Preconditions, validated before any data I/O (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 at least one reader
+     *
+     * When videoDecodable is set, a video topic supplied by more than one reader
+     * must have time-disjoint source ranges; overlapping sources throw
+     * VideoSourcesOverlapError.
+     */
+    async sample(queries, opts = {}) {
+        const videoDecodable = opts.videoDecodable === true;
+        const bounds = await Promise.all(this.readers.map((r) => r.topicBounds()));
+        validateMultiSampleQueries(queries, bounds);
+        if (videoDecodable) {
+            enforceVideoDisjoint(queries.map((q) => q.topic), bounds);
+        }
+        const out = queries.map((q) => q.timestamps.map(() => ({
+            found: false,
+            timestamp: 0n,
+            data: new Uint8Array(0),
+            isVideo: false,
+            frames: [],
+            resetDecoder: false,
+        })));
+        // Dispatch to each reader only the queries whose topic it holds (avoids
+        // the engine's unknown-topic error), then merge by latest found floor.
+        for (let ri = 0; ri < this.readers.length; ri++) {
+            const subset = [];
+            const origIdx = [];
+            for (let qi = 0; qi < queries.length; qi++) {
+                if (bounds[ri].has(queries[qi].topic)) {
+                    subset.push(queries[qi]);
+                    origIdx.push(qi);
+                }
+            }
+            if (subset.length === 0) {
+                continue;
+            }
+            const res = await this.readers[ri].sample(subset, opts);
+            for (let sub = 0; sub < origIdx.length; sub++) {
+                const qi = origIdx[sub];
+                const row = res[sub];
+                for (let j = 0; j < row.length; j++) {
+                    const cand = row[j];
+                    if (!cand.found) {
+                        continue;
+                    }
+                    const cur = out[qi][j];
+                    if (!cur.found || cand.timestamp > cur.timestamp) {
+                        out[qi][j] = cand;
+                    }
+                }
+            }
+        }
+        return out;
+    }
+}
+/**
+ * The exposed topic names a readMessages call covers: the requested
+ * topicNames, or every exposed topic across all readers when unset.
+ */
+function readScopeTopics(topicNames, bounds) {
+    if (topicNames !== undefined && topicNames.length > 0) {
+        return topicNames;
+    }
+    const seen = new Set();
+    const out = [];
+    for (const b of bounds) {
+        for (const name of b.keys()) {
+            if (!seen.has(name)) {
+                seen.add(name);
+                out.push(name);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Mirror the single-reader checks but treat a topic as known if any reader
+ * holds it. All violations are aggregated into one SampleValidationError.
+ * Mirrors go validateMultiSampleQueries.
+ */
+function validateMultiSampleQueries(queries, bounds) {
+    const seen = new Map();
+    const violations = [];
+    for (let i = 0; i < queries.length; i++) {
+        const q = queries[i];
+        const known = bounds.some((b) => b.has(q.topic));
+        if (!known) {
+            violations.push(`queries[${i}]: unknown topic "${q.topic}" (not in any reader)`);
+        }
+        const prev = seen.get(q.topic);
+        if (prev !== undefined) {
+            violations.push(`queries[${i}]: duplicate topic "${q.topic}" already used by queries[${prev}]`);
+        }
+        else {
+            seen.set(q.topic, i);
+        }
+        for (let j = 1; j < q.timestamps.length; j++) {
+            if (q.timestamps[j] <= q.timestamps[j - 1]) {
+                violations.push(`queries[${i}].timestamps not strictly increasing at position ${j} (${q.timestamps[j]} <= ${q.timestamps[j - 1]})`);
+            }
+        }
+    }
+    if (violations.length > 0) {
+        throw new SampleValidationError(violations);
+    }
+}
+/**
+ * Throw VideoSourcesOverlapError when any of the given exposed video topics is
+ * provided by readers with overlapping inclusive time ranges. Topics that are
+ * not video, or are held by fewer than two readers, are skipped. Mirrors go
+ * enforceVideoDisjoint.
+ */
+function enforceVideoDisjoint(topics, bounds) {
+    for (const topic of topics) {
+        const ranges = [];
+        let isVideo = false;
+        for (const b of bounds) {
+            const bound = b.get(topic);
+            if (bound === undefined) {
+                continue;
+            }
+            if (bound.isVideo) {
+                isVideo = true;
+            }
+            ranges.push([bound.minTs, bound.maxTs]);
+        }
+        if (!isVideo || ranges.length < 2) {
+            continue;
+        }
+        for (let a = 0; a < ranges.length; a++) {
+            for (let c = a + 1; c < ranges.length; c++) {
+                if (ranges[a][0] <= ranges[c][1] && ranges[c][0] <= ranges[a][1]) {
+                    throw new VideoSourcesOverlapError(topic, ranges[a], ranges[c]);
+                }
+            }
+        }
+    }
+}
+//# sourceMappingURL=multi_reader.js.map

package/dist/multi_reader.js.map

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

package/dist/read_fetcher.d.ts

@@ -0,0 +1,9 @@
+import type { ReadOp } from "./read_planner.js";
+import type { ReadSource } from "./read_source.js";
+/**
+ * Execute ops against rs with at most maxConcurrency in-flight reads. Returns
+ * one Uint8Array per op, in input order. Throws on the first error
+ * encountered; in-flight reads may still settle in the background.
+ */
+export declare function fetchAll(rs: ReadSource, ops: ReadOp[], maxConcurrency: number): Promise<Uint8Array[]>;
+//# sourceMappingURL=read_fetcher.d.ts.map

package/dist/read_fetcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read_fetcher.d.ts","sourceRoot":"","sources":["../src/read_fetcher.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;;;GAIG;AACH,wBAAsB,QAAQ,CAC5B,EAAE,EAAE,UAAU,EACd,GAAG,EAAE,MAAM,EAAE,EACb,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,UAAU,EAAE,CAAC,CA4CvB"}

package/dist/read_fetcher.js

@@ -0,0 +1,59 @@
+// 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.
+/**
+ * Execute ops against rs with at most maxConcurrency in-flight reads. Returns
+ * one Uint8Array per op, in input order. Throws on the first error
+ * encountered; in-flight reads may still settle in the background.
+ */
+export async function fetchAll(rs, ops, maxConcurrency) {
+    if (ops.length === 0) {
+        return [];
+    }
+    const workers = maxConcurrency > 0 ? maxConcurrency : 1;
+    const out = new Array(ops.length);
+    let nextIdx = 0;
+    let firstErr = undefined;
+    const runOne = async () => {
+        while (firstErr === undefined) {
+            const i = nextIdx++;
+            if (i >= ops.length) {
+                return;
+            }
+            const op = ops[i];
+            try {
+                const buf = await rs.read(op.offset, op.length);
+                if (BigInt(buf.byteLength) !== op.length) {
+                    throw new Error(`fetcher: short read for op ${i}: got ${buf.byteLength} want ${op.length}`);
+                }
+                out[i] = buf;
+            }
+            catch (err) {
+                if (firstErr === undefined) {
+                    firstErr = err;
+                }
+                return;
+            }
+        }
+    };
+    const pool = new Array(Math.min(workers, ops.length));
+    for (let w = 0; w < pool.length; w++) {
+        pool[w] = runOne();
+    }
+    await Promise.all(pool);
+    if (firstErr !== undefined) {
+        throw firstErr;
+    }
+    return out;
+}
+//# sourceMappingURL=read_fetcher.js.map

package/dist/read_fetcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read_fetcher.js","sourceRoot":"","sources":["../src/read_fetcher.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;AAQjC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,EAAc,EACd,GAAa,EACb,cAAsB;IAEtB,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,OAAO,GAAG,cAAc,GAAG,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;IACxD,MAAM,GAAG,GAAG,IAAI,KAAK,CAAa,GAAG,CAAC,MAAM,CAAC,CAAC;IAE9C,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,QAAQ,GAAY,SAAS,CAAC;IAElC,MAAM,MAAM,GAAG,KAAK,IAAmB,EAAE;QACvC,OAAO,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC9B,MAAM,CAAC,GAAG,OAAO,EAAE,CAAC;YACpB,IAAI,CAAC,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;gBACpB,OAAO;YACT,CAAC;YACD,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC,CAAE,CAAC;YACnB,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC;gBAChD,IAAI,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,CAAC;oBACzC,MAAM,IAAI,KAAK,CACb,8BAA8B,CAAC,SAAS,GAAG,CAAC,UAAU,SAAS,EAAE,CAAC,MAAM,EAAE,CAC3E,CAAC;gBACJ,CAAC;gBACD,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC;YACf,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;oBAC3B,QAAQ,GAAG,GAAG,CAAC;gBACjB,CAAC;gBACD,OAAO;YACT,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,IAAI,GAAoB,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IACvE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,IAAI,CAAC,CAAC,CAAC,GAAG,MAAM,EAAE,CAAC;IACrB,CAAC;IACD,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAExB,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,MAAM,QAAQ,CAAC;IACjB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/read_options.d.ts

@@ -0,0 +1,40 @@
+import type { ReadStrategy } from "./read_strategy.js";
+export type Order = "time" | "reverse-time";
+export interface ReadOptions {
+    /** When set, only messages from these topic names are emitted. */
+    topicNames?: string[];
+    /** int64. Inclusive lower bound on message timestamp. Default: 0n. */
+    startTimestamp?: bigint;
+    /** int64. Inclusive upper bound on message timestamp. Default: int64-max. */
+    endTimestamp?: bigint;
+    /** Iteration order. Default: "time". */
+    order?: Order;
+    /**
+     * When set, switches Reader.readMessages onto the cost-aware path. Without
+     * a strategy, the reader uses the default lazy path (one chunk at a time).
+     */
+    strategy?: ReadStrategy;
+    /**
+     * int64. Bytes to read speculatively from the file tail when loading the
+     * summary. When the (footer + compressed summary) fits within the prefetch
+     * window, summary loading costs one read instead of two. Default: 0n
+     * (footer-only read).
+     */
+    tailPrefetch?: bigint;
+    /**
+     * If true, the iterator hands out a freshly-allocated Uint8Array per
+     * message (safe to retain). If false (default), `data` aliases an internal
+     * reusable buffer that becomes invalid on the next iteration step.
+     */
+    copy?: boolean;
+    /**
+     * If true, for any video topic in scope the effective per-group
+     * startTimestamp is snapped back to the latest key frame whose timestamp is
+     * <= startTimestamp, so the emitted sequence can be fed to a decoder cold.
+     * Non-video topics are unaffected. Default: false.
+     */
+    videoDecodable?: boolean;
+}
+/** Default value for endTimestamp: matches Go's math.MaxInt64. */
+export declare const MAX_INT64 = 9223372036854775807n;
+//# sourceMappingURL=read_options.d.ts.map

package/dist/read_options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read_options.d.ts","sourceRoot":"","sources":["../src/read_options.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,MAAM,MAAM,KAAK,GAAG,MAAM,GAAG,cAAc,CAAC;AAE5C,MAAM,WAAW,WAAW;IAC1B,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,sEAAsE;IACtE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wCAAwC;IACxC,KAAK,CAAC,EAAE,KAAK,CAAC;IACd;;;OAGG;IACH,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,kEAAkE;AAClE,eAAO,MAAM,SAAS,uBAAsB,CAAC"}

package/dist/read_options.js

@@ -0,0 +1,16 @@
+// 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.
+/** Default value for endTimestamp: matches Go's math.MaxInt64. */
+export const MAX_INT64 = 0x7fffffffffffffffn;
+//# sourceMappingURL=read_options.js.map

package/dist/read_options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read_options.js","sourceRoot":"","sources":["../src/read_options.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;AA4CjC,kEAAkE;AAClE,MAAM,CAAC,MAAM,SAAS,GAAG,mBAAmB,CAAC"}