@botejs/core 0.5.0 → 0.7.0

package/dist/open.d.ts

@@ -1,40 +1,47 @@
 import { type RootCursor } from './cursor.ts';
-import type { Source } from './sources.ts';
+import type { SeekableSource, ForwardSource } from './source/base.ts';
 export declare const DEFAULT_SOURCE_CHUNK_BYTES: number;
 export interface OpenOptions {
     /**
-     * Slot budget for the structural-index cache: one slot per cached container
-     * plus one per tabled object member. When a scan tips the cache over this
-     * budget, the deepest (least navigationally useful) containers are evicted
-     * first, LRU-tiebroken, keeping the shallow backbone that resumes future
-     * scans. Bounds resident cache memory regardless of document size. `0`
-     * disables the cache entirely. Omit for the native default (1024).
+     * How much of the index that speeds up repeat lookups to keep in memory,
+     * measured in entries. Higher means faster repeat queries but more memory;
+     * lower means less memory but slower repeats. Set to `0` to turn the cache
+     * off. Defaults to 1024.
      */
     indexCacheEntries?: number;
     /**
-     * Max object members tabled per walked container in the structural-index
-     * cache. The table is a dense prefix; past the cap, lookups of later members
-     * resume-scan from the cap boundary. Lower trades cache memory for resume work
-     * on pathologically large objects. `0` disables object member indexing. Omit
-     * for the native default (unbounded).
+     * How many keys per object to index for fast lookup. Higher speeds up access
+     * to keys later in large objects but uses more memory; lower saves memory at
+     * the cost of slower lookups for those keys. Set to `0` to skip indexing
+     * object keys. Defaults to unlimited.
      */
     objectMemberCap?: number;
     /**
-     * Element-index stride between sampled array members in the structural-index
-     * cache. A later index resumes from the nearest array member at or before it, so
-     * a smaller stride means denser array members (more memory, shorter resume
-     * scans). `0` disables array-member indexing. Omit for the native default (16).
-     *
-     * Setting both `objectMemberCap` and `arrayIndexInterval` to `0` disables the
-     * cache entirely (no source bytes are ever cached either way), as does
-     * `indexCacheEntries: 0`.
+     * How often to index array positions, e.g. every 16th element. Lower means
+     * faster access to arbitrary array elements but more memory; higher saves
+     * memory at the cost of slower access. Set to `0` to skip indexing array
+     * positions. Defaults to 16.
      */
     arrayIndexInterval?: number;
 }
 /**
- * Open a cursor over a seekable source.
+ * Options for a forward source: every cache knob is forbidden (the structural-index
+ * cache is forced off). `Omit` would collapse to `{}` and silently permit them, so
+ * the knobs are mapped to `never` to reject them at compile time.
+ */
+export type ForwardOpenOptions = {
+    [K in keyof OpenOptions]?: never;
+};
+/**
+ * Open a cursor over a source.
+ *
+ * A seekable source (`fromFile`/`fromBuffer`/`fromHttpRange`) supports the cache
+ * and repeated, out-of-order queries. A forward source (`fromReadable`/`fromHttpStream`)
+ * is a single forward pass: the cache is forced off, so its cache knobs are
+ * rejected at compile time and at runtime.
  *
- * The returned `RootCursor` owns the reader: `close()` (or `await using`)
- * drives the reader's own `close()` exactly once.
+ * The returned `RootCursor` owns the reader: `close()` (or `await using`) drives
+ * the reader's own `close()` exactly once.
  */
-export declare function open(source: Source, options?: OpenOptions): Promise<RootCursor>;
+export declare function open(source: SeekableSource, options?: OpenOptions): Promise<RootCursor>;
+export declare function open(source: ForwardSource, options?: ForwardOpenOptions): Promise<RootCursor>;

package/dist/open.js

@@ -1,28 +1,32 @@
 import { open as openNative } from '@botejs/native';
 import { wrap } from "./cursor.js";
 export const DEFAULT_SOURCE_CHUNK_BYTES = 64 * 1024;
-/**
- * Open a cursor over a seekable source.
- *
- * The returned `RootCursor` owns the reader: `close()` (or `await using`)
- * drives the reader's own `close()` exactly once.
- */
+const CACHE_KNOBS = ['indexCacheEntries', 'objectMemberCap', 'arrayIndexInterval'];
 export async function open(source, options) {
-    const { indexCacheEntries, objectMemberCap, arrayIndexInterval } = options ?? {};
-    for (const [name, value] of [
-        ['indexCacheEntries', indexCacheEntries],
-        ['objectMemberCap', objectMemberCap],
-        ['arrayIndexInterval', arrayIndexInterval],
-    ]) {
+    if (!source.seekable) {
+        for (const name of CACHE_KNOBS) {
+            if (options?.[name] !== undefined) {
+                throw new RangeError(`open: ${name} is not allowed for a forward source; the structural-index cache is forced off`);
+            }
+        }
+    }
+    for (const name of CACHE_KNOBS) {
+        const value = options?.[name];
         if (value !== undefined && (!Number.isSafeInteger(value) || value < 0)) {
             throw new RangeError(`open: ${name} must be a non-negative integer (0 disables), got ${value}`);
         }
     }
+    // A forward source disables every cache dimension, so the engine never resolves
+    // a cached container offset into a backward read on a stream it cannot rewind.
+    const knobs = source.seekable ? options : { indexCacheEntries: 0, objectMemberCap: 0, arrayIndexInterval: 0 };
     const reader = await source.open();
     const chunkBytes = reader.chunkBytes ?? DEFAULT_SOURCE_CHUNK_BYTES;
     let native;
     try {
-        if (!Number.isInteger(reader.size) || reader.size < 0) {
+        if (reader.seekable && reader.size === undefined) {
+            throw new RangeError('open: a seekable source must report a size');
+        }
+        if (reader.size !== undefined && (!Number.isInteger(reader.size) || reader.size < 0)) {
             throw new RangeError(`open: source size must be a non-negative integer, got ${reader.size}`);
         }
         if (!Number.isSafeInteger(chunkBytes) || chunkBytes <= 0) {
@@ -34,10 +38,10 @@ export async function open(source, options) {
         native = openNative({
             size: reader.size,
             chunkBytes,
-            indexCacheEntries,
-            objectMemberCap,
-            arrayIndexInterval,
-            read: async ({ offset, length }) => reader.read(offset, length),
+            objectMemberCap: knobs?.objectMemberCap,
+            indexCacheEntries: knobs?.indexCacheEntries,
+            arrayIndexInterval: knobs?.arrayIndexInterval,
+            read: ({ offset, length }) => reader.read(offset, length),
         });
     }
     catch (err) {
@@ -46,15 +50,17 @@ export async function open(source, options) {
             await closeReader(reader);
         }
         catch (closeErr) {
-            if (err instanceof Error)
+            if (err instanceof Error) {
                 err.cause ??= closeErr;
+            }
         }
         throw err;
     }
     const state = { closed: false };
     const close = async () => {
-        if (state.closed)
+        if (state.closed) {
             return;
+        }
         state.closed = true;
         await closeReader(reader);
     };
@@ -64,6 +70,7 @@ export async function open(source, options) {
     });
 }
 async function closeReader(reader) {
-    if (reader.close)
+    if (reader.close) {
         await reader.close();
+    }
 }

package/dist/path.d.ts

@@ -1,5 +1,7 @@
-import type { Segment } from './validate.ts';
+export type Segment = string | number;
+export type Path = readonly Segment[];
 /** Upper bound on numeric segments (napi takes them as `u32`). 2^32 - 1
  *  comfortably covers any in-memory JSON array. */
 export declare const MAX_ARRAY_INDEX = 4294967295;
 export declare function validatePath(path: readonly unknown[]): asserts path is readonly Segment[];
+export declare function formatPath(path: Path): string;

package/dist/path.js

@@ -4,17 +4,41 @@ export const MAX_ARRAY_INDEX = 0xffffffff;
 export function validatePath(path) {
     for (let i = 0; i < path.length; i++) {
         const s = path[i];
-        if (typeof s === 'string')
+        if (typeof s === 'string') {
             continue;
-        if (typeof s === 'number' && Number.isInteger(s) && s >= 0 && s <= MAX_ARRAY_INDEX)
+        }
+        if (typeof s === 'number' && Number.isInteger(s) && s >= 0 && s <= MAX_ARRAY_INDEX) {
             continue;
+        }
         throw new TypeError(`path segment ${i}: expected string or non-negative integer (<= ${MAX_ARRAY_INDEX}), got ${describeBadSegment(s)}`);
     }
 }
+export function formatPath(path) {
+    if (path.length === 0) {
+        return '(root)';
+    }
+    let out = '';
+    for (let i = 0; i < path.length; i++) {
+        const seg = path[i];
+        if (typeof seg === 'number') {
+            out += `[${seg}]`;
+            continue;
+        }
+        if (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(seg)) {
+            out += i === 0 ? seg : `.${seg}`;
+        }
+        else {
+            out += `[${JSON.stringify(seg)}]`;
+        }
+    }
+    return out;
+}
 function describeBadSegment(s) {
-    if (typeof s === 'number')
+    if (typeof s === 'number') {
         return `${s}`;
-    if (s === null)
+    }
+    if (s === null) {
         return 'null';
+    }
     return typeof s;
 }

package/dist/source/base.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The bytes a `read` resolves to, plus an end-of-stream flag. `eof` is `true`
+ * iff this read reached the end of the underlying stream. A seekable reader can
+ * compute it from `size`; a forward reader discovers it as the stream drains.
+ */
+export interface ReadResult {
+    readonly data: Uint8Array;
+    readonly eof: boolean;
+}
+/**
+ * A handle on an opened byte stream. The reader owns whatever resources back the
+ * stream (a file handle, a `fetch` body, an `AbortController`, etc.) and surfaces
+ * them through `close()`. Constructed by `Source.open()`; never by callers directly.
+ *
+ * `seekable` declares the access model:
+ *   - `true`: `read(offset, length)` may be called at any offset, in any order.
+ *     `size` is required. This random access is what lets the structural-index
+ *     cache resume scans near a target.
+ *   - `false`: a single forward pass. `read` is called with non-decreasing
+ *     offsets; the cache is forced off. `size` may be omitted (the end is found
+ *     via `eof`). Rewinding to an earlier offset re-acquires the stream (see
+ *     `fromReadable`'s `rewind` option) or throws {@link ForwardReplayError}.
+ */
+export interface Reader {
+    /** Whether reads may target any offset/order (`true`) or a single forward pass (`false`). */
+    readonly seekable: boolean;
+    /** Total length in bytes. Required for seekable readers; optional for forward ones. */
+    readonly size?: number;
+    /** Preferred read granularity in bytes. Must be a non-zero multiple of 64. */
+    readonly chunkBytes?: number;
+    /**
+     * Read up to `length` bytes starting at `offset`. `data.byteLength` is the
+     * actual count read (`<= length`); `eof` is `true` iff the read reached the
+     * end of the stream.
+     */
+    read(offset: number, length: number): Promise<ReadResult>;
+    /** Release resources held by the reader. Driven once by the `open()` lifecycle. */
+    close?(): Promise<void> | void;
+}
+/**
+ * Describes how to obtain a byte stream. `open()` is called once per cursor for
+ * a seekable source; a forward source's reader re-acquires its stream on demand.
+ * Provide your own object to plug in a custom backend.
+ */
+export interface Source {
+    /** Mirrors {@link Reader.seekable}; lets `open()` enforce the right knobs at compile time. */
+    readonly seekable: boolean;
+    /** Acquire the stream. Resolves to a `Reader` that owns any underlying resources. */
+    open(): Promise<Reader>;
+}
+/**
+ * A {@link Source} statically known to be seekable (random access, cache-eligible).
+ * `open()` discriminates on this, so a custom backend must brand its `seekable`
+ * as the literal `true` (annotate the object `SeekableSource`) to be accepted.
+ */
+export type SeekableSource = Source & {
+    readonly seekable: true;
+};
+/**
+ * A {@link Source} statically known to be forward-only (single pass, cache forced
+ * off). Brand a custom backend's object `ForwardSource` so `open()` accepts it and
+ * rejects cache knobs at compile time.
+ */
+export type ForwardSource = Source & {
+    readonly seekable: false;
+};
+export interface FactoryOptions {
+    /** Override the factory's default chunk size. Must be a non-zero multiple of 64. */
+    chunkBytes?: number;
+}

package/dist/source/base.js

@@ -0,0 +1 @@
+export {};

package/dist/source/forward.d.ts

@@ -0,0 +1,49 @@
+import type { FactoryOptions, ForwardSource } from './base.ts';
+/**
+ * A function that produces a fresh readable stream each time it is called. A
+ * forward reader invokes it once up front, and again on every re-acquisition, so
+ * it is also the seam for per-acquisition customization (a freshly minted auth
+ * token, a new `AbortSignal`, etc.).
+ */
+export type ReadableProducer = () => NodeJS.ReadableStream | ReadableStream<Uint8Array> | Promise<NodeJS.ReadableStream | ReadableStream<Uint8Array>>;
+export interface ReadableOptions extends FactoryOptions {
+    /** Known total length, if any. Forwarded to the engine so it can skip rediscovering the end. */
+    size?: number;
+    /** Transform applied to every (re)acquired stream, e.g. `s => s.pipeThrough(new DecompressionStream('gzip'))`. */
+    decode?: (raw: ReadableStream<Uint8Array>) => ReadableStream<Uint8Array>;
+    /**
+     * What a later query that must re-read from an earlier offset does. Defaults
+     * to `'forbid'`. The three settings trade resident memory for re-read ability:
+     *   - `'forbid'`: a single forward pass; a rewind throws {@link ForwardReplayError}.
+     *   - `'replay'`: re-acquire the stream from the start. Only safe when the
+     *     producer is idempotent (yields the same bytes each call). No extra memory.
+     *   - `'buffer'`: snapshot the whole stream into memory on first read, enabling
+     *     random access at O(n) resident memory.
+     */
+    rewind?: 'forbid' | 'replay' | 'buffer';
+}
+export interface HttpRequestOptions extends Omit<ReadableOptions, 'size'> {
+    /** Merged into every `fetch` (headers, credentials, signal, etc.). */
+    init?: RequestInit;
+}
+/**
+ * A forward-only source backed by a re-openable readable stream. `produce` is
+ * called to acquire each pass: once up front, and again on a rewind when
+ * `rewind: 'replay'` is set. A plain `Readable` instance cannot be re-streamed,
+ * so pass a thunk (`() => createReadStream(path)`), not a live stream.
+ *
+ * Because every cursor operation is an independent scan from the start, a single
+ * forward pass serves exactly one query; a second query (or `hop` then `get`)
+ * rewinds. By default that throws {@link ForwardReplayError}; opt into
+ * `rewind: 'replay'` (idempotent producer) or `rewind: 'buffer'` (in-memory
+ * snapshot) for multi-query access.
+ */
+export declare function fromReadable(produce: ReadableProducer, options?: ReadableOptions): ForwardSource;
+/**
+ * A forward-only source over an HTTP request (GET is default), streamed in a single pass. A
+ * convenience wrapper around {@link fromReadable} whose producer re-fetches `url`
+ * (reusing `init`, so auth headers, credentials, and an `AbortSignal` survive
+ * each acquisition). For repeated or random access over HTTP, prefer the seekable
+ * {@link fromHttpRange}.
+ */
+export declare function fromHttpRequest(url: string, options?: HttpRequestOptions): ForwardSource;

package/dist/source/forward.js

@@ -0,0 +1,219 @@
+import { Readable } from 'node:stream';
+import { ForwardReplayError } from "../error.js";
+/** Default chunk size, in bytes, for forward streams: a large pull keeps a streamed scan moving. */
+const DEFAULT_STREAM_CHUNK_BYTES = 256 * 1024;
+const EMPTY = new Uint8Array(0);
+/**
+ * A forward-only source backed by a re-openable readable stream. `produce` is
+ * called to acquire each pass: once up front, and again on a rewind when
+ * `rewind: 'replay'` is set. A plain `Readable` instance cannot be re-streamed,
+ * so pass a thunk (`() => createReadStream(path)`), not a live stream.
+ *
+ * Because every cursor operation is an independent scan from the start, a single
+ * forward pass serves exactly one query; a second query (or `hop` then `get`)
+ * rewinds. By default that throws {@link ForwardReplayError}; opt into
+ * `rewind: 'replay'` (idempotent producer) or `rewind: 'buffer'` (in-memory
+ * snapshot) for multi-query access.
+ */
+export function fromReadable(produce, options) {
+    const chunkBytes = options?.chunkBytes ?? DEFAULT_STREAM_CHUNK_BYTES;
+    const size = options?.size;
+    const decode = options?.decode;
+    const rewind = options?.rewind ?? 'forbid';
+    return {
+        seekable: false,
+        open: () => makeForwardReader(produce, { chunkBytes, size, decode, rewind }),
+    };
+}
+/**
+ * A forward-only source over an HTTP request (GET is default), streamed in a single pass. A
+ * convenience wrapper around {@link fromReadable} whose producer re-fetches `url`
+ * (reusing `init`, so auth headers, credentials, and an `AbortSignal` survive
+ * each acquisition). For repeated or random access over HTTP, prefer the seekable
+ * {@link fromHttpRange}.
+ */
+export function fromHttpRequest(url, options) {
+    const { init, ...readable } = options ?? {};
+    const produce = async () => {
+        const res = await fetch(url, { ...init });
+        if (!res.ok) {
+            throw new Error(`${url} failed: ${res.status} ${res.statusText}`);
+        }
+        if (!res.body) {
+            throw new Error(`${url} returned no body`);
+        }
+        return res.body;
+    };
+    return fromReadable(produce, readable);
+}
+async function makeForwardReader(produce, config) {
+    const { chunkBytes, size, decode, rewind } = config;
+    const replay = rewind === 'replay';
+    const buffer = rewind === 'buffer';
+    let reader = null;
+    let pos = 0; // bytes consumed from the active pass (served + skipped)
+    let leftover = null; // tail of the last pulled chunk, not yet served
+    let done = false;
+    let snapshot = null;
+    let chain = Promise.resolve();
+    const acquire = async () => {
+        let web = toWebStream(await produce());
+        if (decode) {
+            web = decode(web);
+        }
+        reader = web.getReader();
+        pos = 0;
+        leftover = null;
+        done = false;
+    };
+    const release = async () => {
+        const active = reader;
+        reader = null;
+        if (active) {
+            try {
+                await active.cancel();
+            }
+            catch {
+                // cancelling an already-errored/closed stream is not actionable
+            }
+        }
+    };
+    // Next run of bytes available from the active pass, or null once it is drained.
+    const pull = async () => {
+        if (leftover) {
+            const chunk = leftover;
+            leftover = null;
+            return chunk;
+        }
+        if (done || !reader) {
+            return null;
+        }
+        const { value, done: streamDone } = await reader.read();
+        if (streamDone) {
+            done = true;
+            return null;
+        }
+        return value;
+    };
+    const readForward = async (offset, length) => {
+        if (offset < pos) {
+            if (!replay) {
+                throw new ForwardReplayError(offset, pos);
+            }
+            await release();
+            await acquire();
+        }
+        if (!reader && !done) {
+            await acquire();
+        }
+        while (pos < offset) {
+            const chunk = await pull();
+            if (chunk === null) {
+                break; // stream ended before the requested offset; the read returns eof
+            }
+            const skip = offset - pos;
+            if (chunk.byteLength <= skip) {
+                pos += chunk.byteLength;
+            }
+            else {
+                leftover = chunk.subarray(skip);
+                pos += skip;
+            }
+        }
+        const parts = [];
+        let got = 0;
+        while (got < length) {
+            const chunk = await pull();
+            if (chunk === null) {
+                break;
+            }
+            if (chunk.byteLength === 0) {
+                continue;
+            }
+            const take = Math.min(chunk.byteLength, length - got);
+            parts.push(take === chunk.byteLength ? chunk : chunk.subarray(0, take));
+            if (take < chunk.byteLength) {
+                leftover = chunk.subarray(take);
+            }
+            pos += take;
+            got += take;
+        }
+        return { data: concat(parts, got), eof: done && leftover === null };
+    };
+    const readSnapshot = (offset, length) => {
+        const data = snapshot;
+        if (offset >= data.byteLength) {
+            return { data: EMPTY, eof: true };
+        }
+        const end = Math.min(offset + length, data.byteLength);
+        return { data: data.subarray(offset, end), eof: end >= data.byteLength };
+    };
+    // A forward pass has shared position state, so overlapping scans (e.g. two
+    // un-awaited queries) must not interleave their pulls. Serializing reads keeps
+    // bookkeeping intact and turns concurrent misuse into a ForwardReplayError.
+    const read = (offset, length) => {
+        const result = chain.then(async () => {
+            if (buffer) {
+                if (!snapshot) {
+                    snapshot = await drainAll(produce, decode);
+                }
+                return readSnapshot(offset, length);
+            }
+            return readForward(offset, length);
+        });
+        chain = result.catch(() => { });
+        return result;
+    };
+    if (!buffer) {
+        await acquire();
+    }
+    return { seekable: false, size, chunkBytes, read, close: release };
+}
+async function drainAll(produce, decode) {
+    let web = toWebStream(await produce());
+    if (decode) {
+        web = decode(web);
+    }
+    const reader = web.getReader();
+    const parts = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done) {
+                break;
+            }
+            if (value && value.byteLength > 0) {
+                parts.push(value);
+                total += value.byteLength;
+            }
+        }
+    }
+    finally {
+        try {
+            await reader.cancel();
+        }
+        catch {
+            // already drained/errored
+        }
+    }
+    return concat(parts, total);
+}
+function toWebStream(stream) {
+    if (typeof stream.getReader === 'function') {
+        return stream;
+    }
+    return Readable.toWeb(stream);
+}
+function concat(parts, total) {
+    if (parts.length === 1 && parts[0].byteLength === total) {
+        return parts[0];
+    }
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.byteLength;
+    }
+    return out;
+}

package/dist/source/seekable.d.ts

@@ -0,0 +1,8 @@
+import type { FactoryOptions, SeekableSource } from './base.ts';
+export interface HttpRangeOptions extends FactoryOptions {
+    /** Merged into every request (headers, credentials, signal, etc.). */
+    init?: RequestInit;
+}
+export declare function fromBuffer(buf: Uint8Array | ArrayBuffer, options?: FactoryOptions): SeekableSource;
+export declare function fromFile(path: string, options?: FactoryOptions): SeekableSource;
+export declare function fromHttpRange(url: string, options?: HttpRangeOptions): SeekableSource;

package/dist/{sources.js → source/seekable.js}

@@ -9,37 +9,47 @@ export function fromBuffer(buf, options) {
     const view = buf instanceof Uint8Array ? buf : new Uint8Array(buf);
     const chunkBytes = options?.chunkBytes ?? DEFAULT_BUFFER_CHUNK_BYTES;
     return {
+        seekable: true,
         open: () => Promise.resolve({
+            seekable: true,
             size: view.byteLength,
             chunkBytes,
-            read: (offset, length) => Promise.resolve(view.subarray(offset, Math.min(offset + length, view.byteLength))),
+            read: (offset, length) => {
+                const data = view.subarray(offset, Math.min(offset + length, view.byteLength));
+                return Promise.resolve({ data, eof: offset + data.byteLength >= view.byteLength });
+            },
         }),
     };
 }
 export function fromFile(path, options) {
     const chunkBytes = options?.chunkBytes ?? DEFAULT_FILE_CHUNK_BYTES;
     return {
+        seekable: true,
         open: async () => {
             const handle = await fsOpen(path, 'r');
             const stat = await handle.stat();
+            const size = stat.size;
             let closed = false;
             return {
-                size: stat.size,
+                seekable: true,
+                size,
                 chunkBytes,
                 read: async (offset, length) => {
                     const buf = Buffer.allocUnsafe(length);
                     let filled = 0;
                     while (filled < length) {
                         const { bytesRead } = await handle.read(buf, filled, length - filled, offset + filled);
-                        if (bytesRead === 0)
+                        if (bytesRead === 0) {
                             break;
+                        }
                         filled += bytesRead;
                     }
-                    return buf.subarray(0, filled);
+                    return { data: buf.subarray(0, filled), eof: offset + filled >= size };
                 },
                 close: async () => {
-                    if (closed)
+                    if (closed) {
                         return;
+                    }
                     closed = true;
                     await handle.close();
                 },
@@ -51,6 +61,7 @@ export function fromHttpRange(url, options) {
     const init = options?.init;
     const chunkBytes = options?.chunkBytes ?? DEFAULT_URL_CHUNK_BYTES;
     return {
+        seekable: true,
         open: async () => {
             const controller = new AbortController();
             const userSignal = init?.signal;
@@ -79,6 +90,7 @@ export function fromHttpRange(url, options) {
             }
             let closed = false;
             return {
+                seekable: true,
                 size,
                 chunkBytes,
                 read: async (offset, length) => {
@@ -87,21 +99,23 @@ export function fromHttpRange(url, options) {
                     const headers = new Headers(init?.headers);
                     headers.set('Range', `bytes=${offset}-${end}`);
                     headers.set('Accept-Encoding', 'identity');
-                    const res = await fetch(url, { ...init, headers, method: 'GET', signal: controller.signal });
+                    const res = await fetch(url, { ...init, headers, signal: controller.signal });
                     if (res.status === 206) {
-                        return new Uint8Array(await res.arrayBuffer());
+                        const data = new Uint8Array(await res.arrayBuffer());
+                        return { data, eof: offset + data.byteLength >= size };
                     }
                     // A 200 means the server ignored our Range request and returned the full
                     // body. We throw here since the point of using ranges is to not have to
                     // buffer the whole thing in memory.
                     if (res.status === 200) {
-                        throw new Error(`Range GET ${url} (bytes=${offset}-${end}) ignored Range and returned 200.`);
+                        throw new Error(`Range ${url} (bytes=${offset}-${end}) ignored Range and returned 200.`);
                     }
-                    throw new Error(`Range GET ${url} (bytes=${offset}-${end}) failed: ${res.status}`);
+                    throw new Error(`Range ${url} (bytes=${offset}-${end}) failed: ${res.status}`);
                 },
                 close: async () => {
-                    if (closed)
+                    if (closed) {
                         return;
+                    }
                     closed = true;
                     controller.abort();
                 },