turbodata 0.1.0

package/src/io.ts

@@ -0,0 +1,214 @@
+// 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,
+  type Footer,
+  type IndexChunk,
+  type IndexChunkInfo,
+  type MessageIndex,
+  type Summary,
+  type TopicIndex,
+  type TopicMetadata,
+  type TopicsInfo,
+} 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 {
+  private readonly view: DataView;
+  private readonly bytes: Uint8Array;
+  private off: number;
+
+  constructor(bytes: Uint8Array) {
+    this.bytes = bytes;
+    this.view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    this.off = 0;
+  }
+
+  get offset(): number {
+    return this.off;
+  }
+
+  get remaining(): number {
+    return this.bytes.byteLength - this.off;
+  }
+
+  private require(n: number): void {
+    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(): number {
+    this.require(1);
+    const v = this.view.getUint8(this.off);
+    this.off += 1;
+    return v;
+  }
+
+  readUint16(): number {
+    this.require(2);
+    const v = this.view.getUint16(this.off, false);
+    this.off += 2;
+    return v;
+  }
+
+  readUint32(): number {
+    this.require(4);
+    const v = this.view.getUint32(this.off, false);
+    this.off += 4;
+    return v;
+  }
+
+  readInt64(): bigint {
+    this.require(8);
+    const v = this.view.getBigInt64(this.off, false);
+    this.off += 8;
+    return v;
+  }
+
+  readBytes(n: number): Uint8Array {
+    this.require(n);
+    const out = this.bytes.subarray(this.off, this.off + n);
+    this.off += n;
+    return out;
+  }
+}
+
+function readString(r: BinaryReader): string {
+  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: BinaryReader): Map<string, unknown> {
+  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: BinaryReader): Footer {
+  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: BinaryReader): TopicMetadata {
+  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: BinaryReader): IndexChunkInfo {
+  const startTimestamp = r.readInt64();
+  const endTimestamp = r.readInt64();
+  const offset = r.readInt64();
+  return { startTimestamp, endTimestamp, offset };
+}
+
+export function readTopicsInfo(r: BinaryReader): TopicsInfo {
+  const topicMetadataLen = r.readUint32();
+  const topicMetadatas: TopicMetadata[] = new Array(topicMetadataLen);
+  for (let i = 0; i < topicMetadataLen; i++) {
+    topicMetadatas[i] = readTopicMetadata(r);
+  }
+  const indexChunkInfoLen = r.readUint32();
+  const indexChunkInfoList: IndexChunkInfo[] = 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: BinaryReader): Summary {
+  const topicsInfoLen = r.readUint32();
+  const topicsInfos: TopicsInfo[] = new Array(topicsInfoLen);
+  for (let i = 0; i < topicsInfoLen; i++) {
+    topicsInfos[i] = readTopicsInfo(r);
+  }
+  return { topicsInfos };
+}
+
+export function readMessageIndex(r: BinaryReader): MessageIndex {
+  const timestamp = r.readInt64();
+  const offsetInChunk = r.readInt64();
+  return { timestamp, offsetInChunk };
+}
+
+export function readTopicIndex(r: BinaryReader): TopicIndex {
+  const id = r.readUint16();
+  const messageIndexLen = r.readUint32();
+  const messageIndexes: MessageIndex[] = 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: BinaryReader): IndexChunk {
+  const topicIndexesLen = r.readUint32();
+  const topicIndexes: TopicIndex[] = 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 };

package/src/iterators/message_heap.ts

@@ -0,0 +1,104 @@
+// 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.
+
+// Tiny binary heap with bigint priorities, used to merge per-group iterators
+// into a single time-ordered stream. Mirrors go/message_heap.go semantics
+// (separate forward/reverse heaps replaced by a `reverse` flag).
+
+interface HeapItem<T> {
+  priority: bigint;
+  value: T;
+}
+
+export class MessageHeap<T> {
+  private readonly items: HeapItem<T>[] = [];
+  private readonly cmpSign: bigint;
+
+  /** reverse=false: min-heap (time order). reverse=true: max-heap (reverse time). */
+  constructor(reverse: boolean) {
+    this.cmpSign = reverse ? -1n : 1n;
+  }
+
+  get size(): number {
+    return this.items.length;
+  }
+
+  push(priority: bigint, value: T): void {
+    this.items.push({ priority, value });
+    this.siftUp(this.items.length - 1);
+  }
+
+  pop(): { priority: bigint; value: T } | undefined {
+    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. */
+  private compare(a: bigint, b: bigint): bigint {
+    return (a - b) * this.cmpSign;
+  }
+
+  private siftUp(idx: number): void {
+    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;
+      }
+    }
+  }
+
+  private siftDown(idx: number): void {
+    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;
+    }
+  }
+}

package/src/iterators/preloaded_topics_group_iterator.ts

@@ -0,0 +1,143 @@
+// 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.
+
+// Preloaded topics-group iterator: all bytes pre-fetched into LoadedBytes;
+// per-chunk kept-message lists pre-computed at setup time. Used by the
+// cost-aware read path. Counterpart to TopicsGroupIterator (lazy default
+// path). Mirrors go/preloaded_topics_group_iterator.go.
+
+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 class PreloadedTopicsGroupIterator {
+  private readonly isCompressed: boolean;
+  private readonly reverse: boolean;
+  private readonly indexChunks: IndexChunk[];
+  private readonly chunkMessages: MessageRef[][];
+  private readonly chunkMsgLens: bigint[][];
+  private readonly loadedData: LoadedBytes;
+  private readonly decompress: Decompressor;
+
+  // Decompressed buffer for the *current* compressed data chunk; undefined
+  // when isCompressed=false or no chunk has been materialized yet.
+  private currentDecompressed: Uint8Array | undefined;
+  private loadedChunkIdx = -1;
+
+  private chunkIdx: number;
+  private msgIdx: number;
+
+  constructor(args: {
+    isCompressed: boolean;
+    reverse: boolean;
+    indexChunks: IndexChunk[];
+    chunkMessages: MessageRef[][];
+    chunkMsgLens: bigint[][];
+    loadedData: LoadedBytes;
+    decompress: Decompressor;
+  }) {
+    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():
+    | { timestamp: bigint; topicId: number; data: Uint8Array }
+    | undefined {
+    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: Uint8Array;
+      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 };
+    }
+  }
+
+  private advanceMessage(): void {
+    this.msgIdx += this.reverse ? -1 : 1;
+  }
+
+  private advanceChunk(): void {
+    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;
+      }
+    }
+  }
+}

package/src/iterators/topics_group_iterator.ts

@@ -0,0 +1,180 @@
+// 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-path per-group iterator. Lazily reads one index chunk and one data
+// chunk at a time; mirrors go/topics_group_iterator.go but uses readAt
+// (offset/length) instead of Read+Seek state.
+
+import type { Decompressor } from "../compression.js";
+import { BinaryReader, readIndexChunk } from "../io.js";
+import type { ReadSource } from "../read_source.js";
+import { sortAndFilter, type MessageRef } from "../sort_and_filter.js";
+import { META_KEY_COMPRESSED, type IndexChunkInfo, type TopicsInfo } from "../types.js";
+
+export class TopicsGroupIterator {
+  private readonly rs: ReadSource;
+  private readonly decompress: Decompressor;
+  private readonly topicIds: Set<number>;
+  private readonly startTimestamp: bigint;
+  private readonly endTimestamp: bigint;
+  private readonly reverse: boolean;
+  private readonly isCompressed: boolean;
+  private readonly videoDecodable: boolean;
+
+  // Per-chunk metadata.
+  private readonly indexChunkInfoList: IndexChunkInfo[];
+  private readonly indexChunkInfoLens: bigint[];
+
+  // Iteration cursors.
+  private chunkIdx: number;
+  private msgIdx: number;
+  private currentMessages: MessageRef[] = [];
+  private currentLens: bigint[] = [];
+
+  // Most-recently-loaded data chunk (uncompressed bytes).
+  private dataBuffer: Uint8Array | undefined;
+
+  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;
+  }) {
+    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: IndexChunkInfo[] = [];
+    const filteredLens: bigint[] = [];
+    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: bigint;
+      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(): boolean {
+    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(): Promise<{
+    timestamp: bigint;
+    topicId: number;
+    data: Uint8Array;
+  } | undefined> {
+    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 };
+  }
+
+  private async loadCurrentChunk(): Promise<void> {
+    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;
+  }
+}

package/src/loaded_bytes.ts

@@ -0,0 +1,61 @@
+// 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.
+
+// LoadedBytes: bridge between the planner+fetcher (which think in coalesced /
+// split byte ranges) and the consumers (which think in their original
+// per-range terms). Mirrors go/loaded_bytes.go.
+
+import type { Range, RangeLocation } from "./read_planner.js";
+
+interface BytesLocation {
+  bufferIdx: number;
+  inBufOff: number;
+  length: number;
+}
+
+export class LoadedBytes {
+  private readonly buffers: Uint8Array[];
+  private readonly index: Map<bigint, BytesLocation>;
+
+  constructor(
+    ranges: Range[],
+    locations: RangeLocation[],
+    buffers: Uint8Array[],
+  ) {
+    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: bigint): Uint8Array | undefined {
+    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);
+  }
+}