turbodata 0.1.0

package/dist/sort_and_filter.js

@@ -0,0 +1,126 @@
+// 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.
+// sortAndFilter: pure version that turns a decoded IndexChunk into a flat,
+// timestamp-ordered list of kept (topicId, timestamp, offsetInChunk) plus
+// per-message lengths. Mirrors go/sort_and_filter.go.
+//
+// The "sort" is by per-message OffsetInChunk; the writer interleaves messages
+// in timestamp order, so offset order == timestamp order within a chunk. We
+// preserve that invariant rather than re-sorting by timestamp explicitly.
+import { MessageHeap } from "./iterators/message_heap.js";
+export function sortAndFilter(topicIndexes, totalLen, topicIds, startTimestamp, endTimestamp, videoDecodable = false) {
+    let total = 0;
+    for (const ti of topicIndexes) {
+        total += ti.messageIndexes.length;
+    }
+    if (total === 0) {
+        return { msgs: [], lens: [] };
+    }
+    const sorted = new Array(total);
+    let writeIdx = 0;
+    if (topicIndexes.length === 1) {
+        // Fast path: single topic, messages are already in offset order.
+        const ti = topicIndexes[0];
+        for (const mi of ti.messageIndexes) {
+            sorted[writeIdx++] = { topicId: ti.id, mi };
+        }
+    }
+    else {
+        // K-way merge by offsetInChunk across topics, via a min-heap.
+        // Mirrors go/sort_and_filter.go's MessageIndexHeap-based merge: O(N log K)
+        // regardless of how many topics share a group.
+        const heap = new MessageHeap(false);
+        for (let t = 0; t < topicIndexes.length; t++) {
+            const mis = topicIndexes[t].messageIndexes;
+            if (mis.length === 0) {
+                continue;
+            }
+            heap.push(mis[0].offsetInChunk, { topicSlot: t, cursor: 0 });
+        }
+        while (heap.size > 0) {
+            const top = heap.pop();
+            const { topicSlot, cursor } = top.value;
+            const ti = topicIndexes[topicSlot];
+            sorted[writeIdx++] = { topicId: ti.id, mi: ti.messageIndexes[cursor] };
+            const next = cursor + 1;
+            if (next < ti.messageIndexes.length) {
+                heap.push(ti.messageIndexes[next].offsetInChunk, {
+                    topicSlot,
+                    cursor: next,
+                });
+            }
+        }
+    }
+    // Per-entry lengths from offset deltas.
+    const allLens = new Array(sorted.length);
+    for (let i = 0; i < sorted.length - 1; i++) {
+        allLens[i] = sorted[i + 1].mi.offsetInChunk - sorted[i].mi.offsetInChunk;
+    }
+    allLens[allLens.length - 1] =
+        totalLen - sorted[sorted.length - 1].mi.offsetInChunk;
+    // For video-decodable groups, snap the lower bound back to the anchoring
+    // key frame so the kept sequence is decodable cold.
+    let effectiveStart = startTimestamp;
+    if (videoDecodable) {
+        effectiveStart = keyFrameStart(topicIndexes, startTimestamp);
+    }
+    // Filter by topic + timestamp range.
+    const msgs = [];
+    const lens = [];
+    for (let i = 0; i < sorted.length; i++) {
+        const item = sorted[i];
+        if (!topicIds.has(item.topicId)) {
+            continue;
+        }
+        const ts = item.mi.timestamp;
+        if (ts < effectiveStart || ts > endTimestamp) {
+            continue;
+        }
+        msgs.push({
+            timestamp: ts,
+            topicId: item.topicId,
+            offsetInChunk: item.mi.offsetInChunk,
+        });
+        lens.push(allLens[i]);
+    }
+    return { msgs, lens };
+}
+/**
+ * Timestamp of the latest key frame whose timestamp is <= startTimestamp, or
+ * startTimestamp unchanged if no such key frame exists in this chunk. Mirrors
+ * py key_frame_start / go keyFrameStart.
+ *
+ * Video-decodable groups always hold exactly one topic. keyFrameIndexes are
+ * ascending positions into that topic's timestamp-ordered messageIndexes.
+ */
+export function keyFrameStart(topicIndexes, startTimestamp) {
+    if (topicIndexes.length === 0) {
+        return startTimestamp;
+    }
+    const ti = topicIndexes[0];
+    let anchor = startTimestamp;
+    for (const kfIdx of ti.keyFrameIndexes) {
+        const ts = ti.messageIndexes[kfIdx].timestamp;
+        if (ts > startTimestamp) {
+            break;
+        }
+        anchor = ts;
+    }
+    return anchor;
+}
+/** Convenience: sort+filter directly from a decoded IndexChunk. */
+export function sortAndFilterChunk(chunk, topicIds, startTimestamp, endTimestamp) {
+    return sortAndFilter(chunk.topicIndexes, chunk.uncompressedLen, topicIds, startTimestamp, endTimestamp);
+}
+//# sourceMappingURL=sort_and_filter.js.map

package/dist/sort_and_filter.js.map

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

package/dist/sources/blob.d.ts

@@ -0,0 +1,8 @@
+import type { ReadSource } from "../read_source.js";
+export declare class BlobReadSource implements ReadSource {
+    private readonly blob;
+    constructor(blob: Blob);
+    size(): Promise<bigint>;
+    read(offset: bigint, length: bigint): Promise<Uint8Array>;
+}
+//# sourceMappingURL=blob.d.ts.map

package/dist/sources/blob.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blob.d.ts","sourceRoot":"","sources":["../../src/sources/blob.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,qBAAa,cAAe,YAAW,UAAU;IAC/C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAO;gBAEhB,IAAI,EAAE,IAAI;IAIhB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;IAIvB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;CAmBhE"}

package/dist/sources/blob.js

@@ -0,0 +1,38 @@
+// 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 BlobReadSource {
+    blob;
+    constructor(blob) {
+        this.blob = blob;
+    }
+    async size() {
+        return BigInt(this.blob.size);
+    }
+    async read(offset, length) {
+        // Blob.slice takes number offsets. We accept that browsers can't host a
+        // single Blob > 2^53 bytes anyway; clamp via Number() and validate.
+        const start = Number(offset);
+        const end = Number(offset + length);
+        if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end)) {
+            throw new Error(`BlobReadSource.read: offset/length exceed Number.MAX_SAFE_INTEGER (offset=${offset}, length=${length})`);
+        }
+        const slice = this.blob.slice(start, end);
+        const buf = await slice.arrayBuffer();
+        if (buf.byteLength !== Number(length)) {
+            throw new Error(`BlobReadSource.read: short read at offset ${offset}, expected ${length}, got ${buf.byteLength}`);
+        }
+        return new Uint8Array(buf);
+    }
+}
+//# sourceMappingURL=blob.js.map

package/dist/sources/blob.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blob.js","sourceRoot":"","sources":["../../src/sources/blob.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;AASjC,MAAM,OAAO,cAAc;IACR,IAAI,CAAO;IAE5B,YAAY,IAAU;QACpB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,KAAK,CAAC,IAAI;QACR,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,MAAc,EAAE,MAAc;QACvC,wEAAwE;QACxE,oEAAoE;QACpE,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;QAC7B,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;QACpC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;YAC/D,MAAM,IAAI,KAAK,CACb,6EAA6E,MAAM,YAAY,MAAM,GAAG,CACzG,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAC1C,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,WAAW,EAAE,CAAC;QACtC,IAAI,GAAG,CAAC,UAAU,KAAK,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CACb,6CAA6C,MAAM,cAAc,MAAM,SAAS,GAAG,CAAC,UAAU,EAAE,CACjG,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;CACF"}

package/dist/sources/http.d.ts

@@ -0,0 +1,17 @@
+import type { ReadSource } from "../read_source.js";
+export interface HttpRangeReadSourceOptions {
+    /** Custom fetch implementation (e.g. for tests or auth headers). */
+    fetch?: typeof fetch;
+    /** Extra request init applied to every request (e.g. credentials, headers). */
+    init?: RequestInit;
+}
+export declare class HttpRangeReadSource implements ReadSource {
+    private readonly url;
+    private readonly fetchImpl;
+    private readonly init;
+    private cachedSize;
+    constructor(url: string, opts?: HttpRangeReadSourceOptions);
+    size(): Promise<bigint>;
+    read(offset: bigint, length: bigint): Promise<Uint8Array>;
+}
+//# sourceMappingURL=http.d.ts.map

package/dist/sources/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/sources/http.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,MAAM,WAAW,0BAA0B;IACzC,oEAAoE;IACpE,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,+EAA+E;IAC/E,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAED,qBAAa,mBAAoB,YAAW,UAAU;IACpD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAc;IACnC,OAAO,CAAC,UAAU,CAAqB;gBAE3B,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,0BAA+B;IAMxD,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;IAkDvB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;CAyBhE"}

package/dist/sources/http.js

@@ -0,0 +1,90 @@
+// 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 HttpRangeReadSource {
+    url;
+    fetchImpl;
+    init;
+    cachedSize;
+    constructor(url, opts = {}) {
+        this.url = url;
+        this.fetchImpl = opts.fetch ?? fetch.bind(globalThis);
+        this.init = opts.init ?? {};
+    }
+    async size() {
+        if (this.cachedSize !== undefined) {
+            return this.cachedSize;
+        }
+        // Try HEAD first.
+        let resp;
+        try {
+            resp = await this.fetchImpl(this.url, { ...this.init, method: "HEAD" });
+        }
+        catch (err) {
+            throw new Error(`HttpRangeReadSource: HEAD failed for ${this.url}: ${err.message}`);
+        }
+        if (resp.ok) {
+            const cl = resp.headers.get("content-length");
+            if (cl !== null) {
+                const v = BigInt(cl);
+                this.cachedSize = v;
+                return v;
+            }
+        }
+        // Fallback: a 1-byte ranged GET, parse Content-Range total.
+        const probe = await this.fetchImpl(this.url, {
+            ...this.init,
+            method: "GET",
+            headers: { ...(this.init.headers ?? {}), Range: "bytes=0-0" },
+        });
+        if (!probe.ok && probe.status !== 206) {
+            throw new Error(`HttpRangeReadSource: probe GET failed: ${probe.status} ${probe.statusText}`);
+        }
+        const cr = probe.headers.get("content-range");
+        if (cr === null) {
+            throw new Error(`HttpRangeReadSource: server returned no Content-Length or Content-Range`);
+        }
+        // Format: "bytes 0-0/12345"
+        const m = /\/(\d+)$/.exec(cr);
+        if (m === null) {
+            throw new Error(`HttpRangeReadSource: malformed Content-Range: ${cr}`);
+        }
+        const v = BigInt(m[1]);
+        this.cachedSize = v;
+        // Drain the probe body so the connection can be reused.
+        await probe.arrayBuffer();
+        return v;
+    }
+    async read(offset, length) {
+        if (length <= 0n) {
+            return new Uint8Array(0);
+        }
+        const end = offset + length - 1n;
+        const headers = new Headers(this.init.headers);
+        headers.set("Range", `bytes=${offset.toString()}-${end.toString()}`);
+        const resp = await this.fetchImpl(this.url, {
+            ...this.init,
+            method: "GET",
+            headers,
+        });
+        if (!resp.ok && resp.status !== 206) {
+            throw new Error(`HttpRangeReadSource: GET range ${offset}-${end} failed: ${resp.status} ${resp.statusText}`);
+        }
+        const buf = new Uint8Array(await resp.arrayBuffer());
+        if (BigInt(buf.byteLength) !== length) {
+            throw new Error(`HttpRangeReadSource: short read at ${offset}, expected ${length}, got ${buf.byteLength}`);
+        }
+        return buf;
+    }
+}
+//# sourceMappingURL=http.js.map

package/dist/sources/http.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,75 @@
+export interface Footer {
+    /** uncompressed: int64. Length of the (zstd-compressed) summary block. */
+    summaryLen: bigint;
+    /** Always equals "7URB0" for valid files. */
+    magic: Uint8Array;
+}
+export interface Summary {
+    topicsInfos: TopicsInfo[];
+}
+export interface TopicsInfo {
+    topicMetadatas: TopicMetadata[];
+    indexChunkInfoList: IndexChunkInfo[];
+    /**
+     * int64. Total length of all index chunks for this topic group, in bytes
+     * (compressed). Used by the reader to compute the length of the *last*
+     * index chunk in the group.
+     */
+    totalLen: bigint;
+}
+export interface TopicMetadata {
+    /** uint16 */
+    id: number;
+    name: string;
+    /**
+     * Decoded msgpack map. Int64 values are decoded as bigint (via
+     * `useBigInt64: true`); smaller integers stay as number.
+     */
+    metadata: Map<string, unknown>;
+    /** uint32. Number of messages written into this topic. */
+    messageCount: number;
+}
+export interface IndexChunkInfo {
+    /** int64 */
+    startTimestamp: bigint;
+    /** int64 */
+    endTimestamp: bigint;
+    /** int64. Absolute file offset where the (compressed) index chunk starts. */
+    offset: bigint;
+}
+export interface IndexChunk {
+    topicIndexes: TopicIndex[];
+    /** int64. Absolute file offset of this index chunk's data. */
+    chunkOffset: bigint;
+    /** int64. On-disk (possibly compressed) data length in bytes. */
+    chunkLen: bigint;
+    /** int64. Decompressed data length, used to compute the last message's length. */
+    uncompressedLen: bigint;
+}
+export interface TopicIndex {
+    /** uint16 */
+    id: number;
+    messageIndexes: MessageIndex[];
+    /**
+     * uint32 entries: ascending positions into `messageIndexes` marking key
+     * frames. Consumed by the video-decodable read/sample paths to anchor GOPs.
+     */
+    keyFrameIndexes: Uint32Array;
+}
+export interface MessageIndex {
+    /** int64 */
+    timestamp: bigint;
+    /** int64. Offset relative to the start of the (uncompressed) data chunk. */
+    offsetInChunk: bigint;
+}
+/** The 5 magic bytes that close every turbodata file: "7URB0". */
+export declare const MAGIC: Uint8Array;
+/** Footer is fixed at 13 bytes: 8 (summaryLen) + 5 (magic). */
+export declare const FOOTER_LEN = 13;
+export declare const META_KEY_SCHEMA_NAME = "schema_name";
+export declare const META_KEY_SCHEMA_ENCODING = "schema_encoding";
+export declare const META_KEY_SCHEMA_DATA = "schema_data";
+export declare const META_KEY_COMPRESSED = "__td_is_compressed";
+export declare const META_KEY_VIDEO = "__td_is_video";
+export declare const META_KEY_CHUNK_CONFIG = "__td_chunk_config";
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAoBA,MAAM,WAAW,MAAM;IACrB,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,KAAK,EAAE,UAAU,CAAC;CACnB;AAED,MAAM,WAAW,OAAO;IACtB,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,UAAU;IACzB,cAAc,EAAE,aAAa,EAAE,CAAC;IAChC,kBAAkB,EAAE,cAAc,EAAE,CAAC;IACrC;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,aAAa;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,0DAA0D;IAC1D,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,YAAY;IACZ,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY;IACZ,YAAY,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,UAAU,EAAE,CAAC;IAC3B,8DAA8D;IAC9D,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,UAAU;IACzB,aAAa;IACb,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,EAAE,YAAY,EAAE,CAAC;IAC/B;;;OAGG;IACH,eAAe,EAAE,WAAW,CAAC;CAC9B;AAED,MAAM,WAAW,YAAY;IAC3B,YAAY;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,kEAAkE;AAClE,eAAO,MAAM,KAAK,EAAE,UAA2D,CAAC;AAEhF,+DAA+D;AAC/D,eAAO,MAAM,UAAU,KAAK,CAAC;AAG7B,eAAO,MAAM,oBAAoB,gBAAgB,CAAC;AAClD,eAAO,MAAM,wBAAwB,oBAAoB,CAAC;AAC1D,eAAO,MAAM,oBAAoB,gBAAgB,CAAC;AAMlD,eAAO,MAAM,mBAAmB,uBAAuB,CAAC;AACxD,eAAO,MAAM,cAAc,kBAAkB,CAAC;AAC9C,eAAO,MAAM,qBAAqB,sBAAsB,CAAC"}

package/dist/types.js

@@ -0,0 +1,29 @@
+// 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.
+/** The 5 magic bytes that close every turbodata file: "7URB0". */
+export const MAGIC = new Uint8Array([0x37, 0x55, 0x52, 0x42, 0x30]);
+/** Footer is fixed at 13 bytes: 8 (summaryLen) + 5 (magic). */
+export const FOOTER_LEN = 13;
+// Common per-topic schema metadata keys. SCHEMA_DATA holds raw schema bytes.
+export const META_KEY_SCHEMA_NAME = "schema_name";
+export const META_KEY_SCHEMA_ENCODING = "schema_encoding";
+export const META_KEY_SCHEMA_DATA = "schema_data";
+// Internal per-topic metadata keys used to carry write-format control flags
+// alongside caller-supplied metadata. The __td_ prefix namespaces them away
+// from user keys. The reader reads these back to drive decompression and
+// video-aware sampling.
+export const META_KEY_COMPRESSED = "__td_is_compressed";
+export const META_KEY_VIDEO = "__td_is_video";
+export const META_KEY_CHUNK_CONFIG = "__td_chunk_config";
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.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;AAgFjC,kEAAkE;AAClE,MAAM,CAAC,MAAM,KAAK,GAAe,IAAI,UAAU,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;AAEhF,+DAA+D;AAC/D,MAAM,CAAC,MAAM,UAAU,GAAG,EAAE,CAAC;AAE7B,6EAA6E;AAC7E,MAAM,CAAC,MAAM,oBAAoB,GAAG,aAAa,CAAC;AAClD,MAAM,CAAC,MAAM,wBAAwB,GAAG,iBAAiB,CAAC;AAC1D,MAAM,CAAC,MAAM,oBAAoB,GAAG,aAAa,CAAC;AAElD,4EAA4E;AAC5E,4EAA4E;AAC5E,yEAAyE;AACzE,wBAAwB;AACxB,MAAM,CAAC,MAAM,mBAAmB,GAAG,oBAAoB,CAAC;AACxD,MAAM,CAAC,MAAM,cAAc,GAAG,eAAe,CAAC;AAC9C,MAAM,CAAC,MAAM,qBAAqB,GAAG,mBAAmB,CAAC"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "turbodata",
+  "version": "0.1.0",
+  "description": "Browser TypeScript reader for the turbodata format.",
+  "license": "Apache-2.0",
+  "author": "Wanjia He",
+  "homepage": "https://github.com/opheadacheh/turbodata#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/opheadacheh/turbodata.git",
+    "directory": "ts"
+  },
+  "bugs": {
+    "url": "https://github.com/opheadacheh/turbodata/issues"
+  },
+  "keywords": [
+    "turbodata",
+    "container-format",
+    "timeseries",
+    "robotics",
+    "mcap",
+    "msgpack",
+    "zstd"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "example:read": "tsx examples/read.ts",
+    "example:sample": "tsx examples/sample.ts",
+    "example:multiread": "tsx examples/multiread.ts"
+  },
+  "dependencies": {
+    "@msgpack/msgpack": "^3.0.0",
+    "fzstd": "^0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0",
+    "vitest": "^4.1.8"
+  }
+}

package/src/compression.ts

@@ -0,0 +1,28 @@
+// 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.
+
+// Pluggable zstd decompression. Default backend is fzstd (pure JS, sync).
+
+import { decompress as fzstdDecompress } from "fzstd";
+
+/**
+ * Decompress a zstd-compressed buffer. Must accept the exact bytes produced
+ * by github.com/klauspost/compress/zstd's EncodeAll (i.e. the standard zstd
+ * frame format).
+ */
+export type Decompressor = (compressed: Uint8Array) => Uint8Array;
+
+export const defaultDecompressor: Decompressor = (compressed) => {
+  return fzstdDecompress(compressed);
+};

package/src/index.ts

@@ -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.
+
+// Public API surface.
+
+export {
+  Reader,
+  SampleValidationError,
+  TopicRemapError,
+  DEFAULT_SAMPLE_STRATEGY,
+  linSpaceTimestamps,
+} from "./reader.js";
+export type {
+  Frame,
+  Message,
+  ReaderOptions,
+  SampleQuery,
+  SampleResult,
+  SampleOptions,
+} from "./reader.js";
+
+export { MultiReader, VideoSourcesOverlapError } from "./multi_reader.js";
+
+export type { ReadOptions, Order } from "./read_options.js";
+export { MAX_INT64 } from "./read_options.js";
+
+export type { ReadStrategy } from "./read_strategy.js";
+export {
+  StrategyForLatency,
+  StrategyForMoney,
+  StrategyForBlended,
+} from "./read_strategy.js";
+
+export type { ReadSource } from "./read_source.js";
+export { BlobReadSource } from "./sources/blob.js";
+export { HttpRangeReadSource } from "./sources/http.js";
+export type { HttpRangeReadSourceOptions } from "./sources/http.js";
+
+export type { Decompressor } from "./compression.js";
+export { defaultDecompressor } from "./compression.js";
+
+export type {
+  Footer,
+  Summary,
+  TopicsInfo,
+  TopicMetadata,
+  IndexChunkInfo,
+  IndexChunk,
+  TopicIndex,
+  MessageIndex,
+} from "./types.js";
+export {
+  META_KEY_COMPRESSED,
+  META_KEY_SCHEMA_NAME,
+  META_KEY_SCHEMA_ENCODING,
+  META_KEY_SCHEMA_DATA,
+  META_KEY_VIDEO,
+  META_KEY_CHUNK_CONFIG,
+} from "./types.js";