turbodata 0.1.0

package/dist/io.js

@@ -0,0 +1,174 @@
+// 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.
+// Binary readers for turbodata records. Mirrors go/io.go.
+//
+// All multi-byte fields are big-endian (Go's encoding/binary.BigEndian default).
+import { decodeMetadata } from "./msgpack.js";
+import { FOOTER_LEN, } from "./types.js";
+/** Mirrors go/io.go's maxStringLen / maxMapLen safety caps (64 MiB each). */
+const MAX_STRING_LEN = 64 * 1024 * 1024;
+const MAX_MAP_LEN = 64 * 1024 * 1024;
+const UTF8 = new TextDecoder("utf-8", { fatal: false });
+/**
+ * Forward-only cursor over a Uint8Array. The Go reader uses io.Reader+
+ * binary.Read; here we expose the equivalent calls. All reads are big-endian.
+ *
+ * We deliberately do NOT support seeking; everything in the format is
+ * sequentially decodable from a known start point.
+ */
+export class BinaryReader {
+    view;
+    bytes;
+    off;
+    constructor(bytes) {
+        this.bytes = bytes;
+        this.view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+        this.off = 0;
+    }
+    get offset() {
+        return this.off;
+    }
+    get remaining() {
+        return this.bytes.byteLength - this.off;
+    }
+    require(n) {
+        if (this.off + n > this.bytes.byteLength) {
+            throw new Error(`unexpected EOF: need ${n} bytes at offset ${this.off}, have ${this.bytes.byteLength - this.off}`);
+        }
+    }
+    readUint8() {
+        this.require(1);
+        const v = this.view.getUint8(this.off);
+        this.off += 1;
+        return v;
+    }
+    readUint16() {
+        this.require(2);
+        const v = this.view.getUint16(this.off, false);
+        this.off += 2;
+        return v;
+    }
+    readUint32() {
+        this.require(4);
+        const v = this.view.getUint32(this.off, false);
+        this.off += 4;
+        return v;
+    }
+    readInt64() {
+        this.require(8);
+        const v = this.view.getBigInt64(this.off, false);
+        this.off += 8;
+        return v;
+    }
+    readBytes(n) {
+        this.require(n);
+        const out = this.bytes.subarray(this.off, this.off + n);
+        this.off += n;
+        return out;
+    }
+}
+function readString(r) {
+    const strLen = r.readUint32();
+    if (strLen > MAX_STRING_LEN) {
+        throw new Error(`string length ${strLen} exceeds maximum allowed ${MAX_STRING_LEN}`);
+    }
+    const bytes = r.readBytes(strLen);
+    return UTF8.decode(bytes);
+}
+function readMap(r) {
+    const mapLen = r.readUint32();
+    if (mapLen > MAX_MAP_LEN) {
+        throw new Error(`map length ${mapLen} exceeds maximum allowed ${MAX_MAP_LEN}`);
+    }
+    const buf = r.readBytes(mapLen);
+    return decodeMetadata(buf);
+}
+/**
+ * Parse a fixed-size (13-byte) footer.
+ *
+ * Layout: 8-byte int64 SummaryLen, then 5-byte Magic.
+ */
+export function readFooter(r) {
+    const summaryLen = r.readInt64();
+    const magic = r.readBytes(5);
+    // Defensive copy: r.readBytes returns a subarray view into the source buffer.
+    return { summaryLen, magic: new Uint8Array(magic) };
+}
+export function readTopicMetadata(r) {
+    const id = r.readUint16();
+    const name = readString(r);
+    const metadata = readMap(r);
+    const messageCount = r.readUint32();
+    return { id, name, metadata, messageCount };
+}
+export function readIndexChunkInfo(r) {
+    const startTimestamp = r.readInt64();
+    const endTimestamp = r.readInt64();
+    const offset = r.readInt64();
+    return { startTimestamp, endTimestamp, offset };
+}
+export function readTopicsInfo(r) {
+    const topicMetadataLen = r.readUint32();
+    const topicMetadatas = new Array(topicMetadataLen);
+    for (let i = 0; i < topicMetadataLen; i++) {
+        topicMetadatas[i] = readTopicMetadata(r);
+    }
+    const indexChunkInfoLen = r.readUint32();
+    const indexChunkInfoList = new Array(indexChunkInfoLen);
+    for (let i = 0; i < indexChunkInfoLen; i++) {
+        indexChunkInfoList[i] = readIndexChunkInfo(r);
+    }
+    const totalLen = r.readInt64();
+    return { topicMetadatas, indexChunkInfoList, totalLen };
+}
+export function readSummary(r) {
+    const topicsInfoLen = r.readUint32();
+    const topicsInfos = new Array(topicsInfoLen);
+    for (let i = 0; i < topicsInfoLen; i++) {
+        topicsInfos[i] = readTopicsInfo(r);
+    }
+    return { topicsInfos };
+}
+export function readMessageIndex(r) {
+    const timestamp = r.readInt64();
+    const offsetInChunk = r.readInt64();
+    return { timestamp, offsetInChunk };
+}
+export function readTopicIndex(r) {
+    const id = r.readUint16();
+    const messageIndexLen = r.readUint32();
+    const messageIndexes = new Array(messageIndexLen);
+    for (let i = 0; i < messageIndexLen; i++) {
+        messageIndexes[i] = readMessageIndex(r);
+    }
+    const keyFrameIndexLen = r.readUint32();
+    const keyFrameIndexes = new Uint32Array(keyFrameIndexLen);
+    for (let i = 0; i < keyFrameIndexLen; i++) {
+        keyFrameIndexes[i] = r.readUint32();
+    }
+    return { id, messageIndexes, keyFrameIndexes };
+}
+export function readIndexChunk(r) {
+    const topicIndexesLen = r.readUint32();
+    const topicIndexes = new Array(topicIndexesLen);
+    for (let i = 0; i < topicIndexesLen; i++) {
+        topicIndexes[i] = readTopicIndex(r);
+    }
+    const chunkOffset = r.readInt64();
+    const chunkLen = r.readInt64();
+    const uncompressedLen = r.readInt64();
+    return { topicIndexes, chunkOffset, chunkLen, uncompressedLen };
+}
+export { FOOTER_LEN };
+//# sourceMappingURL=io.js.map

package/dist/io.js.map

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

package/dist/iterators/message_heap.d.ts

@@ -0,0 +1,17 @@
+export declare class MessageHeap<T> {
+    private readonly items;
+    private readonly cmpSign;
+    /** reverse=false: min-heap (time order). reverse=true: max-heap (reverse time). */
+    constructor(reverse: boolean);
+    get size(): number;
+    push(priority: bigint, value: T): void;
+    pop(): {
+        priority: bigint;
+        value: T;
+    } | undefined;
+    /** Return < 0 if a goes before b, > 0 if after, 0 if equal. */
+    private compare;
+    private siftUp;
+    private siftDown;
+}
+//# sourceMappingURL=message_heap.d.ts.map

package/dist/iterators/message_heap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message_heap.d.ts","sourceRoot":"","sources":["../../src/iterators/message_heap.ts"],"names":[],"mappings":"AAuBA,qBAAa,WAAW,CAAC,CAAC;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC,mFAAmF;gBACvE,OAAO,EAAE,OAAO;IAI5B,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAKtC,GAAG,IAAI;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,CAAC,CAAA;KAAE,GAAG,SAAS;IAajD,+DAA+D;IAC/D,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,MAAM;IAiBd,OAAO,CAAC,QAAQ;CA2BjB"}

package/dist/iterators/message_heap.js

@@ -0,0 +1,83 @@
+// 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 MessageHeap {
+    items = [];
+    cmpSign;
+    /** reverse=false: min-heap (time order). reverse=true: max-heap (reverse time). */
+    constructor(reverse) {
+        this.cmpSign = reverse ? -1n : 1n;
+    }
+    get size() {
+        return this.items.length;
+    }
+    push(priority, value) {
+        this.items.push({ priority, value });
+        this.siftUp(this.items.length - 1);
+    }
+    pop() {
+        if (this.items.length === 0) {
+            return undefined;
+        }
+        const top = this.items[0];
+        const last = this.items.pop();
+        if (this.items.length > 0) {
+            this.items[0] = last;
+            this.siftDown(0);
+        }
+        return top;
+    }
+    /** Return < 0 if a goes before b, > 0 if after, 0 if equal. */
+    compare(a, b) {
+        return (a - b) * this.cmpSign;
+    }
+    siftUp(idx) {
+        while (idx > 0) {
+            const parent = (idx - 1) >> 1;
+            if (this.compare(this.items[idx].priority, this.items[parent].priority) <
+                0n) {
+                const tmp = this.items[idx];
+                this.items[idx] = this.items[parent];
+                this.items[parent] = tmp;
+                idx = parent;
+            }
+            else {
+                break;
+            }
+        }
+    }
+    siftDown(idx) {
+        const n = this.items.length;
+        while (true) {
+            const l = idx * 2 + 1;
+            const r = idx * 2 + 2;
+            let best = idx;
+            if (l < n &&
+                this.compare(this.items[l].priority, this.items[best].priority) < 0n) {
+                best = l;
+            }
+            if (r < n &&
+                this.compare(this.items[r].priority, this.items[best].priority) < 0n) {
+                best = r;
+            }
+            if (best === idx) {
+                return;
+            }
+            const tmp = this.items[idx];
+            this.items[idx] = this.items[best];
+            this.items[best] = tmp;
+            idx = best;
+        }
+    }
+}
+//# sourceMappingURL=message_heap.js.map

package/dist/iterators/message_heap.js.map

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

package/dist/iterators/preloaded_topics_group_iterator.d.ts

@@ -0,0 +1,38 @@
+import type { Decompressor } from "../compression.js";
+import type { LoadedBytes } from "../loaded_bytes.js";
+import type { MessageRef } from "../sort_and_filter.js";
+import type { IndexChunk } from "../types.js";
+export declare class PreloadedTopicsGroupIterator {
+    private readonly isCompressed;
+    private readonly reverse;
+    private readonly indexChunks;
+    private readonly chunkMessages;
+    private readonly chunkMsgLens;
+    private readonly loadedData;
+    private readonly decompress;
+    private currentDecompressed;
+    private loadedChunkIdx;
+    private chunkIdx;
+    private msgIdx;
+    constructor(args: {
+        isCompressed: boolean;
+        reverse: boolean;
+        indexChunks: IndexChunk[];
+        chunkMessages: MessageRef[][];
+        chunkMsgLens: bigint[][];
+        loadedData: LoadedBytes;
+        decompress: Decompressor;
+    });
+    /**
+     * Next is synchronous (no I/O remaining). Returns undefined on EOF.
+     * `data` aliases either loadedData or the per-chunk decompressed buffer.
+     */
+    next(): {
+        timestamp: bigint;
+        topicId: number;
+        data: Uint8Array;
+    } | undefined;
+    private advanceMessage;
+    private advanceChunk;
+}
+//# sourceMappingURL=preloaded_topics_group_iterator.d.ts.map

package/dist/iterators/preloaded_topics_group_iterator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preloaded_topics_group_iterator.d.ts","sourceRoot":"","sources":["../../src/iterators/preloaded_topics_group_iterator.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,qBAAa,4BAA4B;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAU;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAe;IAC3C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAiB;IAC/C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAa;IAC1C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAc;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAe;IAI1C,OAAO,CAAC,mBAAmB,CAAyB;IACpD,OAAO,CAAC,cAAc,CAAM;IAE5B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAAS;gBAEX,IAAI,EAAE;QAChB,YAAY,EAAE,OAAO,CAAC;QACtB,OAAO,EAAE,OAAO,CAAC;QACjB,WAAW,EAAE,UAAU,EAAE,CAAC;QAC1B,aAAa,EAAE,UAAU,EAAE,EAAE,CAAC;QAC9B,YAAY,EAAE,MAAM,EAAE,EAAE,CAAC;QACzB,UAAU,EAAE,WAAW,CAAC;QACxB,UAAU,EAAE,YAAY,CAAC;KAC1B;IAqBD;;;OAGG;IACH,IAAI,IACA;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,UAAU,CAAA;KAAE,GACxD,SAAS;IAiDb,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,YAAY;CAarB"}

package/dist/iterators/preloaded_topics_group_iterator.js

@@ -0,0 +1,109 @@
+// 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 PreloadedTopicsGroupIterator {
+    isCompressed;
+    reverse;
+    indexChunks;
+    chunkMessages;
+    chunkMsgLens;
+    loadedData;
+    decompress;
+    // Decompressed buffer for the *current* compressed data chunk; undefined
+    // when isCompressed=false or no chunk has been materialized yet.
+    currentDecompressed;
+    loadedChunkIdx = -1;
+    chunkIdx;
+    msgIdx;
+    constructor(args) {
+        this.isCompressed = args.isCompressed;
+        this.reverse = args.reverse;
+        this.indexChunks = args.indexChunks;
+        this.chunkMessages = args.chunkMessages;
+        this.chunkMsgLens = args.chunkMsgLens;
+        this.loadedData = args.loadedData;
+        this.decompress = args.decompress;
+        if (args.reverse) {
+            this.chunkIdx = args.indexChunks.length - 1;
+            this.msgIdx =
+                this.chunkIdx >= 0
+                    ? args.chunkMessages[this.chunkIdx].length - 1
+                    : 0;
+        }
+        else {
+            this.chunkIdx = 0;
+            this.msgIdx = 0;
+        }
+    }
+    /**
+     * Next is synchronous (no I/O remaining). Returns undefined on EOF.
+     * `data` aliases either loadedData or the per-chunk decompressed buffer.
+     */
+    next() {
+        while (true) {
+            if (this.chunkIdx < 0 || this.chunkIdx >= this.indexChunks.length) {
+                return undefined;
+            }
+            const msgs = this.chunkMessages[this.chunkIdx];
+            if (this.msgIdx < 0 || this.msgIdx >= msgs.length) {
+                this.advanceChunk();
+                continue;
+            }
+            // Materialize this chunk's decompressed bytes on first touch.
+            if (this.isCompressed && this.loadedChunkIdx !== this.chunkIdx) {
+                const compressed = this.loadedData.get(this.indexChunks[this.chunkIdx].chunkOffset);
+                if (compressed === undefined) {
+                    throw new Error(`preloaded iterator: missing compressed chunk at offset ${this.indexChunks[this.chunkIdx].chunkOffset}`);
+                }
+                this.currentDecompressed = this.decompress(compressed);
+                this.loadedChunkIdx = this.chunkIdx;
+            }
+            const msg = msgs[this.msgIdx];
+            const length = this.chunkMsgLens[this.chunkIdx][this.msgIdx];
+            const chunkOffset = this.indexChunks[this.chunkIdx].chunkOffset;
+            let data;
+            if (this.isCompressed) {
+                const start = Number(msg.offsetInChunk);
+                const end = start + Number(length);
+                data = this.currentDecompressed.subarray(start, end);
+            }
+            else {
+                const got = this.loadedData.get(chunkOffset + msg.offsetInChunk);
+                if (got === undefined) {
+                    throw new Error(`preloaded iterator: missing message bytes at offset ${chunkOffset + msg.offsetInChunk}`);
+                }
+                data = got;
+            }
+            this.advanceMessage();
+            return { timestamp: msg.timestamp, topicId: msg.topicId, data };
+        }
+    }
+    advanceMessage() {
+        this.msgIdx += this.reverse ? -1 : 1;
+    }
+    advanceChunk() {
+        if (this.reverse) {
+            this.chunkIdx -= 1;
+            if (this.chunkIdx >= 0) {
+                this.msgIdx = this.chunkMessages[this.chunkIdx].length - 1;
+            }
+        }
+        else {
+            this.chunkIdx += 1;
+            if (this.chunkIdx < this.indexChunks.length) {
+                this.msgIdx = 0;
+            }
+        }
+    }
+}
+//# sourceMappingURL=preloaded_topics_group_iterator.js.map

package/dist/iterators/preloaded_topics_group_iterator.js.map

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

package/dist/iterators/topics_group_iterator.d.ts

@@ -0,0 +1,45 @@
+import type { Decompressor } from "../compression.js";
+import type { ReadSource } from "../read_source.js";
+import { type TopicsInfo } from "../types.js";
+export declare class TopicsGroupIterator {
+    private readonly rs;
+    private readonly decompress;
+    private readonly topicIds;
+    private readonly startTimestamp;
+    private readonly endTimestamp;
+    private readonly reverse;
+    private readonly isCompressed;
+    private readonly videoDecodable;
+    private readonly indexChunkInfoList;
+    private readonly indexChunkInfoLens;
+    private chunkIdx;
+    private msgIdx;
+    private currentMessages;
+    private currentLens;
+    private dataBuffer;
+    constructor(args: {
+        rs: ReadSource;
+        decompress: Decompressor;
+        topicIds: Set<number>;
+        startTimestamp: bigint;
+        endTimestamp: bigint;
+        reverse: boolean;
+        topicsInfo: TopicsInfo;
+        /** When true, snap the per-chunk lower bound back to the GOP key frame. */
+        videoDecodable?: boolean;
+    });
+    /** True if we have any in-scope index chunks. */
+    hasAny(): boolean;
+    /**
+     * Next emits one (timestamp, topicId, data) record or returns undefined on
+     * EOF. The returned Uint8Array aliases an internal buffer; the caller must
+     * copy if persistence is needed.
+     */
+    next(): Promise<{
+        timestamp: bigint;
+        topicId: number;
+        data: Uint8Array;
+    } | undefined>;
+    private loadCurrentChunk;
+}
+//# sourceMappingURL=topics_group_iterator.d.ts.map

package/dist/iterators/topics_group_iterator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topics_group_iterator.d.ts","sourceRoot":"","sources":["../../src/iterators/topics_group_iterator.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EAA4C,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAExF,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAa;IAChC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAe;IAC1C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAc;IACvC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAU;IACvC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAU;IAGzC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAmB;IACtD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAW;IAG9C,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,eAAe,CAAoB;IAC3C,OAAO,CAAC,WAAW,CAAgB;IAGnC,OAAO,CAAC,UAAU,CAAyB;gBAE/B,IAAI,EAAE;QAChB,EAAE,EAAE,UAAU,CAAC;QACf,UAAU,EAAE,YAAY,CAAC;QACzB,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QACtB,cAAc,EAAE,MAAM,CAAC;QACvB,YAAY,EAAE,MAAM,CAAC;QACrB,OAAO,EAAE,OAAO,CAAC;QACjB,UAAU,EAAE,UAAU,CAAC;QACvB,2EAA2E;QAC3E,cAAc,CAAC,EAAE,OAAO,CAAC;KAC1B;IA8CD,iDAAiD;IACjD,MAAM,IAAI,OAAO;IAIjB;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,UAAU,CAAC;KAClB,GAAG,SAAS,CAAC;YA8BA,gBAAgB;CAgC/B"}

package/dist/iterators/topics_group_iterator.js

@@ -0,0 +1,132 @@
+// 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.
+import { BinaryReader, readIndexChunk } from "../io.js";
+import { sortAndFilter } from "../sort_and_filter.js";
+import { META_KEY_COMPRESSED } from "../types.js";
+export class TopicsGroupIterator {
+    rs;
+    decompress;
+    topicIds;
+    startTimestamp;
+    endTimestamp;
+    reverse;
+    isCompressed;
+    videoDecodable;
+    // Per-chunk metadata.
+    indexChunkInfoList;
+    indexChunkInfoLens;
+    // Iteration cursors.
+    chunkIdx;
+    msgIdx;
+    currentMessages = [];
+    currentLens = [];
+    // Most-recently-loaded data chunk (uncompressed bytes).
+    dataBuffer;
+    constructor(args) {
+        this.rs = args.rs;
+        this.decompress = args.decompress;
+        this.topicIds = args.topicIds;
+        this.startTimestamp = args.startTimestamp;
+        this.endTimestamp = args.endTimestamp;
+        this.reverse = args.reverse;
+        this.videoDecodable = args.videoDecodable === true;
+        const firstMeta = args.topicsInfo.topicMetadatas[0];
+        const flag = firstMeta?.metadata.get(META_KEY_COMPRESSED);
+        this.isCompressed = flag === true;
+        // Time-range filter at the chunk level + compute compressed lengths.
+        const filteredInfos = [];
+        const filteredLens = [];
+        const all = args.topicsInfo.indexChunkInfoList;
+        for (let i = 0; i < all.length; i++) {
+            const info = all[i];
+            if (info.endTimestamp < args.startTimestamp) {
+                continue;
+            }
+            if (info.startTimestamp > args.endTimestamp) {
+                break;
+            }
+            filteredInfos.push(info);
+            let ln;
+            if (i < all.length - 1) {
+                ln = all[i + 1].offset - info.offset;
+            }
+            else {
+                // Last index chunk: its length is (group total) - (its offset) + (first chunk's offset).
+                ln = args.topicsInfo.totalLen - info.offset + all[0].offset;
+            }
+            filteredLens.push(ln);
+        }
+        this.indexChunkInfoList = filteredInfos;
+        this.indexChunkInfoLens = filteredLens;
+        if (args.reverse) {
+            this.chunkIdx = filteredInfos.length - 1;
+        }
+        else {
+            this.chunkIdx = 0;
+        }
+        this.msgIdx = 0;
+    }
+    /** True if we have any in-scope index chunks. */
+    hasAny() {
+        return this.indexChunkInfoList.length > 0;
+    }
+    /**
+     * Next emits one (timestamp, topicId, data) record or returns undefined on
+     * EOF. The returned Uint8Array aliases an internal buffer; the caller must
+     * copy if persistence is needed.
+     */
+    async next() {
+        while (this.msgIdx >= this.currentMessages.length ||
+            this.msgIdx < 0) {
+            if (this.chunkIdx >= this.indexChunkInfoList.length ||
+                this.chunkIdx < 0) {
+                return undefined;
+            }
+            await this.loadCurrentChunk();
+            this.chunkIdx += this.reverse ? -1 : 1;
+            if (this.reverse) {
+                this.msgIdx = this.currentMessages.length - 1;
+            }
+            else {
+                this.msgIdx = 0;
+            }
+        }
+        const ref = this.currentMessages[this.msgIdx];
+        const len = this.currentLens[this.msgIdx];
+        this.msgIdx += this.reverse ? -1 : 1;
+        const start = Number(ref.offsetInChunk);
+        const end = start + Number(len);
+        const data = this.dataBuffer.subarray(start, end);
+        return { timestamp: ref.timestamp, topicId: ref.topicId, data };
+    }
+    async loadCurrentChunk() {
+        const info = this.indexChunkInfoList[this.chunkIdx];
+        const ln = this.indexChunkInfoLens[this.chunkIdx];
+        // Read + decompress the index chunk.
+        const compressedIndex = await this.rs.read(info.offset, ln);
+        const indexBytes = this.decompress(compressedIndex);
+        const indexChunk = readIndexChunk(new BinaryReader(indexBytes));
+        const filtered = sortAndFilter(indexChunk.topicIndexes, indexChunk.uncompressedLen, this.topicIds, this.startTimestamp, this.endTimestamp, this.videoDecodable);
+        this.currentMessages = filtered.msgs;
+        this.currentLens = filtered.lens;
+        if (filtered.msgs.length === 0) {
+            this.dataBuffer = undefined;
+            return;
+        }
+        // Read (and possibly decompress) the data chunk.
+        const dataBytes = await this.rs.read(indexChunk.chunkOffset, indexChunk.chunkLen);
+        this.dataBuffer = this.isCompressed ? this.decompress(dataBytes) : dataBytes;
+    }
+}
+//# sourceMappingURL=topics_group_iterator.js.map

package/dist/iterators/topics_group_iterator.js.map

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