@botejs/core 0.5.0 → 0.7.0

package/README.md

@@ -1,140 +1,68 @@
 # bote
 
-a minimal, ergonomic and low-memory approach to navigating a big JSON:
+A fast, modern and low-memory approach to processing a big JSON:
 
 ```sh
 npm install @botejs/core
 ```
 
 ```ts
-import { open, fromFile } from '@botejs/core'
-import { publish } from './message-bus'
-
-// e.g. { items: [...] }
-await using cursor = await open(fromFile('./some-large.json'))
-
-// items[0]
-const first = await cursor.get('items', 0)
-console.log(`first item: ${first}`)
-```
-
-given a **seekable** source (e.g. a file, an HTTP range) and a path, it retrieves values out of a JSON quickly, without loading the whole thing in-memory.
-
-here's a run (Apple M1 Pro 2021, ~500MB JSON array file, cold-cache, default settings):
-
-| operation      | approach   |      time | js heap peak Δ | rust heap peak |
-| -------------- | ---------- | --------: | -------------: | -------------: |
-| items[0]       | JSON.parse |    1.81 s |        1.21 GB |            n/a |
-| items[535399]  | JSON.parse |    1.74 s |        1.21 GB |            n/a |
-| items[1070797] | JSON.parse |    1.74 s |        1.21 GB |            n/a |
-| items[0]       | bote       |   1.29 ms |        63.3 KB |       130.8 KB |
-| items[535399]  | bote       | 193.49 ms |       191.5 KB |        36.7 MB |
-| items[1070797] | bote       | 379.98 ms |       189.8 KB |        37.2 MB |
-
-## array access
-
-`iter` streams the children of a container at a path **one item at a time**, so you never hold the whole collection in memory. it works on either kind: array elements or object member values. each `for await` step yields a single item:
-
-```ts
-// e.g. [{ id: 'user-1' }, { id: 'user-2' }, ...]
-await using cursor = await open(fromFile('./users.json'))
-
-// root is an array
-for await (const user of cursor.iter()) {
-  console.log(user)
-}
-```
-
-the item loop is the ergonomic default; it costs a flat ~10% over a full walk. for hot paths, `.raw()` hands back the raw fetch arrays with no per-item tax (the `batch` option sets their size and the memory bound):
-
-```ts
-for await (const users of cursor.iter().raw()) {
-  for (const user of users) {
-    console.log(user)
-  }
-}
-```
-
-## object access
-
-`iter` over an object yields its **member values** in document order. add `withKey: true` to get **`[key, value]`** pairs instead, where `key` is the member name (for an array, `key` is the element's index). streamed either way, so a million-member object never lands on the heap at once:
-
-```ts
-// e.g. { alice: { role: 'admin' }, bob: { role: 'guest' }, ... }
-await using cursor = await open(fromFile('./accounts.json'))
-
-for await (const [name, account] of cursor.iter({ withKey: true })) {
-  // name is the member name ('alice', 'bob', ...); account is its value
-  console.log(`${name}: ${account.role}`)
-}
+import { fileURLToPath } from 'node:url';
+import { open, fromFile } from '@botejs/core';
+
+// 181 MB GeoJSON:
+// { type: "...", features: [{ properties: { STREET: "..." }}] }
+const filePath = fileURLToPath(new URL('../citylots.json', import.meta.url));
+
+await using cursor = await open(fromFile(filePath));
+
+const byStreet = await cursor
+  .iter('features', {
+    select: ['properties', 'STREET'],
+  })
+  .reduce((tally, street) => {
+    if (typeof street === 'string') {
+      tally.set(street, (tally.get(street) ?? 0) + 1);
+    }
+    return tally;
+  }, new Map());
+
+console.log([...byStreet].sort((a, b) => b[1] - a[1]).slice(0, 10));
 ```
 
-see [`recursive.js`](./examples/recursive.js) for advanced use-cases.
-
-## hopping
-
-`hop` resolves a path once and hands back a **cursor** anchored at that value (or `null` if the path isn't there):
-
-```ts
-// e.g. { report: { sections: [{ rows: [...] }, ...] } }
-await using cursor = await open(fromFile('./report.json'))
-
-const section = await cursor.hop('report', 'sections', 0)
-if (section) {
-  console.log(await section.count('rows'))
-  for await (const row of section.iter('rows')) {
-    console.log(row)
-  }
-}
-```
+Given a **seekable** or **forward** source and a path, it retrieves values out of a JSON, without loading the whole thing in-memory.
 
-## validation
+Here's a run (Apple M1 Pro 2021, default settings, RUNS=100):
 
-`get`, and `iter` takes a [Standard Schema](https://standardschema.dev) validator as their last argument (for `iter`, can also be passed in an `options` object). the value is validated and the return type is inferred from the schema, so reads come back typed instead of `unknown`:
+| method             | mean time (seconds) | mean peak footprint (MB) |
+| ------------------ | -----------------   | ------------------------ |
+| bote               | 0.517 ± 0.018 s     | 40.3 ± 2.5               |
+| JSON.parse         | 0.816 ± 0.031 s     | 648.9 ± 2.4              |
+| JSONStream         | 4.452 ± 0.052 s     | 57.9 ± 3.9               |
+| @streamparser/json | 5.103 ± 0.084 s     | 47.9 ± 2.3               |
+| oboe.js            | 8.566 ± 0.295 s     | 100.0 ± 4.6              |
+| stream-json        | 13.346 ± 0.569 s    | 207.6 ± 8.4              |
 
-```ts
-import { open, fromFile } from '@botejs/core'
-import * as z from 'zod' // or any Standard Schema validator
-
-// a downstream API that wants a typed list of recipients
-declare function sendNewsletter(recipients: string[]): Promise<void>
-
-const User = z.object({
-  id: z.string(),
-  name: z.string(),
-  email: z.string(),
-})
-
-const cursor = await open(fromFile('./users.json'))
-
-// name: string
-const name = await cursor.get('users', 1000, 'name', User.shape.name)
-
-let emails: string[] = []
-// .raw() to hand each fetch's worth of recipients to the batched API at once
-for await (const user of cursor.iter('users', User)) {
-  // user: User
-  emails.push(user.email)
-}
-
-await sendNewsletter(emails)
-await cursor.close()
-```
+For comparison notes, go [here](https://github.com/jankdc/bote-comparison).
 
-## memory
+## Features
 
-bote keeps a small **structural-index** cache: as scans walk containers (arrays and object), it remembers where members live, so a later query that lands in an already walked container resumes near the target instead of from the top. it caches structure, never source bytes, so it can't grow unbounded with document size.
+* Modern `AsyncIterator` API with helpers that emulate the [tc39 ones](https://github.com/tc39/proposal-async-iterator-helpers)
+* Validate with [Standard Schema](https://standardschema.dev/), avoiding those pesky `unknown`s
+* Supports multiple sources of data (e.g. file, network, stream) or write a custom one (see [example](./examples/))
+* For forward-only sources, there's support for replaying/buffering, allowing navigation to previous values
 
-the defaults are good, but `open` takes a few knobs: `indexCacheEntries`, `objectMemberCap`, and `arrayIndexInterval`. to bound memory tighter or turn the cache off. see [`memory.js`](./examples/memory.js) for what each does.
+## Documentation
 
-## sources
+Coming soon. Check the [./examples](./examples/) folder for usages. I've also heavily JSDoc'ed the hell out of the API so have fun
+playing around with it for now.
 
-bote ships `fromFile`, `fromHttpRange`, and `fromBuffer` as pre-built sources. create your own by implementing the `Source` interface. see [`sources-custom.ts`](./examples/sources-custom.ts) or [./packages/core/src/sources.ts](./packages/core/src/sources.ts) for how it works.
+## Status
 
-## status
+Pre-1.0. Still in development and APIs may change based on feedback, bugs and holy divinations from the coding gods.
 
-pre-1.0 so still in development and APIs may change based on feedback, bugs and holy divinations from the coding gods.
+I would say 90% satisfactory for MVP, but I'm getting there.
 
-## license
+## License
 
 MIT.

package/dist/args.d.ts

@@ -1,20 +1,26 @@
-import type { Path, Segment, StandardSchemaV1 } from './validate.ts';
+import { type Path, type Segment } from './path.ts';
+import type { StandardSchemaV1 } from './validate.ts';
+/** Trailing options object for `Cursor.iter`, tuning how the iteration yields items. */
 export interface IterOptions {
+    /** Project each member before it is yielded. A single segment or path picks a
+     *  sub-value; a field map (`{ name: 'name', city: ['address', 'city'] }`)
+     *  builds an object from several sub-paths. */
     select?: Segment | Path | Record<string, Segment | Path>;
     /** How many items cross the native boundary per fetch, which also bounds the
-     *  resident materialization window (the memory knob) and sets the array size
-     *  yielded by `IterStream.raw()`. The default item loop drains each fetch
-     *  one item at a time, so this doesn't change what item iteration yields, only
-     *  how much is fetched and held at once. Higher is faster but holds more in
-     *  memory. */
+     *  resident memory to that batch and sets the array size yielded by `IterStream.raw()`.
+     *  The default item loop drains each fetch one item at a time, so this doesn't change
+     *  what item iteration yields, only how much is fetched and held at once.
+     *  Higher is faster but holds more in memory.
+     *
+     * Default is `1000`. */
     batch?: number;
     /** Validate each yielded item against this schema (after `select`). */
     schema?: StandardSchemaV1;
-    /** Policy for items failing `schema`. Default `'throw'`; `'skip'` drops them. */
-    onInvalid?: 'throw' | 'skip';
     /** Yield `[key, value]` tuples instead of bare values. `key` is the member
      *  name for objects and the zero-based index for arrays. */
     withKey?: boolean;
+    /** Policy for items failing `schema`. Default `'throw'`; `'skip'` drops them. */
+    onInvalid?: 'throw' | 'skip';
 }
 export type VariadicPathArgs<TTail> = [...Segment[]] | [...Segment[], TTail];
 export declare function splitArgs<TTail>(args: VariadicPathArgs<TTail>): {

package/dist/args.js

@@ -24,10 +24,12 @@ export function isSchema(value) {
     return typeof value === 'object' && value !== null && '~standard' in value;
 }
 export function normalizeIterTail(tail) {
-    if (!tail)
+    if (!tail) {
         return {};
-    if (isSchema(tail))
+    }
+    if (isSchema(tail)) {
         return { schema: tail };
+    }
     return tail;
 }
 export function serializeSelect(select) {
@@ -63,7 +65,8 @@ export function serializeSelect(select) {
     return JSON.stringify({ map: entries });
 }
 function describeSelect(value) {
-    if (value === null)
+    if (value === null) {
         return 'null';
+    }
     return Array.isArray(value) ? 'array' : typeof value;
 }

package/dist/cursor.d.ts

@@ -1,6 +1,7 @@
 import type { Cursor as NativeCursor } from '@botejs/native';
+import { type Path, type Segment } from './path.ts';
 import { type IterStream } from './stream.ts';
-import { type Path, type Segment, type StandardSchemaV1 } from './validate.ts';
+import { type StandardSchemaV1 } from './validate.ts';
 import { type IterOptions } from './args.ts';
 type InferOutput<Sch> = Sch extends StandardSchemaV1<unknown, infer O> ? O : never;
 type SelectMapShape<S> = {
@@ -10,12 +11,52 @@ export type IterKey = string | number;
 export declare const DEFAULT_ITER_BATCH = 1000;
 export declare const MAX_ITER_BATCH = 1000000;
 export interface Cursor {
+    /**
+     * Resolve `path` to a container and return a new cursor anchored there, or
+     * `null` if it is absent. Child cursors share the root's source and lifetime;
+     * closing the root closes them too.
+     *
+     * @example
+     * const user = await root.hop('users', 0);
+     * const name = await user?.get('name');
+     */
     hop(...path: Segment[]): Promise<Cursor | null>;
+    /**
+     * Report whether a value exists at `path`. With a trailing Standard Schema,
+     * also require the value to validate against it (a parse/validation miss
+     * yields `false` rather than throwing).
+     *
+     * @example
+     * await root.has('users', 0, 'email');
+     * await root.has('users', 0, 'age', z.number());
+     */
     has(...path: Segment[]): Promise<boolean>;
     has(...args: [...Segment[], StandardSchemaV1]): Promise<boolean>;
+    /**
+     * Read and decode the value at `path`, or `undefined` if absent. With a
+     * trailing Standard Schema, validate and return its parsed output, throwing
+     * on failure.
+     *
+     * @example
+     * const name = await root.get('users', 0, 'name');
+     * const age = await root.get('users', 0, 'age', z.number());
+     */
     get(...path: Segment[]): Promise<unknown>;
     get<Sch extends StandardSchemaV1>(...args: [...Segment[], Sch]): Promise<InferOutput<Sch>>;
-    count(...path: Segment[]): Promise<number>;
+    /**
+     * Stream the members of the array or object at `path` as an async iterable.
+     * A trailing Standard Schema validates each item; a trailing {@link IterOptions}
+     * object tunes the iteration (see its fields for the available knobs).
+     *
+     * @example
+     * for await (const user of root.iter('users')) {
+     *   console.log(user);
+     * }
+     *
+     * for await (const [i, name] of root.iter('users', { withKey: true, select: ['name'] })) {
+     *   console.log(i, name);
+     * }
+     */
     iter(...path: Segment[]): IterStream<unknown>;
     iter<Sch extends StandardSchemaV1>(...args: [...Segment[], Sch]): IterStream<InferOutput<Sch>>;
     iter<Sch extends StandardSchemaV1>(...args: [...Segment[], IterOptions & {
@@ -44,9 +85,6 @@ export interface RootCursor extends Cursor, AsyncDisposable {
 export type CursorState = {
     closed: boolean;
 };
-/** Throw a uniform error for any operation on a closed cursor, so use-after-close
- *  is one defined contract regardless of source (some readers' reads keep working
- *  after close, others throw an opaque I/O error). */
-export declare function ensureOpen(state: CursorState): void;
 export declare function wrap(native: NativeCursor, state: CursorState): Cursor;
+export declare function ensureOpen(state: CursorState): void;
 export {};

package/dist/cursor.js

@@ -1,29 +1,16 @@
+import { deserializeNativeError, ClosedCursorError, MalformedJsonError } from "./error.js";
 import { validatePath } from "./path.js";
-import { parseValue, deserializeError } from "./decode.js";
 import { makeStream } from "./stream.js";
 import { runStandardSchema, validateItem } from "./validate.js";
 import { splitArgs, isSchema, serializeSelect, normalizeIterTail, } from "./args.js";
 export const DEFAULT_ITER_BATCH = 1000;
 export const MAX_ITER_BATCH = 1_000_000;
-/** Throw a uniform error for any operation on a closed cursor, so use-after-close
- *  is one defined contract regardless of source (some readers' reads keep working
- *  after close, others throw an opaque I/O error). */
-export function ensureOpen(state) {
-    if (state.closed)
-        throw new Error('bote: cursor is closed');
-}
 export function wrap(native, state) {
     const cursor = {
         async hop(...path) {
             ensureOpen(state);
             validatePath(path);
-            let child;
-            try {
-                child = await native.hop(path);
-            }
-            catch (err) {
-                throw deserializeError(err, path);
-            }
+            const child = await withPath(path, () => native.hop(path));
             return child ? wrap(child, state) : null;
         },
         async has(...args) {
@@ -32,11 +19,13 @@ export function wrap(native, state) {
             if (schema !== undefined && !isSchema(schema)) {
                 throw new TypeError('has: expected a Standard Schema as the trailing argument');
             }
-            if (!schema)
-                return native.has(path);
-            if (!(await native.has(path)))
+            if (!schema) {
+                return withPath(path, () => native.has(path));
+            }
+            if (!(await withPath(path, () => native.has(path)))) {
                 return false;
-            const text = await native.get(path);
+            }
+            const text = await withPath(path, () => native.get(path));
             const value = text === undefined ? undefined : parseValue(text, path);
             const result = await validateItem(schema, value, path, 'skip');
             return !('skip' in result);
@@ -47,27 +36,12 @@ export function wrap(native, state) {
             if (schema !== undefined && !isSchema(schema)) {
                 throw new TypeError('get: expected a Standard Schema as the trailing argument');
             }
-            let value;
-            try {
-                const text = await native.get(path);
-                value = text === undefined ? undefined : parseValue(text, path);
-            }
-            catch (err) {
-                throw deserializeError(err, path);
-            }
-            if (!schema)
+            const text = await withPath(path, () => native.get(path));
+            const value = text === undefined ? undefined : parseValue(text, path);
+            if (!schema) {
                 return value;
-            return runStandardSchema(schema, value, path);
-        },
-        async count(...path) {
-            ensureOpen(state);
-            validatePath(path);
-            try {
-                return await native.count(path);
-            }
-            catch (err) {
-                throw deserializeError(err, path);
             }
+            return runStandardSchema(schema, value, path);
         },
         iter(...args) {
             ensureOpen(state);
@@ -95,8 +69,9 @@ export function wrap(native, state) {
                 const out = [];
                 for (const [key, value] of parseValue(raw, path)) {
                     const result = await validateItem(schema, value, [...path, key], policy);
-                    if ('skip' in result)
+                    if ('skip' in result) {
                         continue;
+                    }
                     out.push(wantKey ? [key, result.value] : result.value);
                 }
                 return out;
@@ -105,15 +80,40 @@ export function wrap(native, state) {
     };
     return cursor;
 }
+export function ensureOpen(state) {
+    if (state.closed) {
+        throw new ClosedCursorError();
+    }
+}
+/** Run a native call, retyping any addon error as the matching {@link BoteError}
+ *  anchored to `path`. The single funnel every cursor operation passes through,
+ *  so native faults surface uniformly. */
+async function withPath(path, op) {
+    try {
+        return await op();
+    }
+    catch (err) {
+        throw deserializeNativeError(err, path);
+    }
+}
 function nativeStream(inner, path, batchSize, mapBatch) {
     async function* batches() {
         try {
-            for await (const raw of inner)
+            for await (const raw of inner) {
                 yield await mapBatch(raw);
+            }
         }
         catch (err) {
-            throw deserializeError(err, path);
+            throw deserializeNativeError(err, path);
         }
     }
     return makeStream(batches, batchSize);
 }
+function parseValue(text, path) {
+    try {
+        return JSON.parse(text);
+    }
+    catch (cause) {
+        throw new MalformedJsonError(path, 'malformed_json', { cause });
+    }
+}

package/dist/error.d.ts

@@ -0,0 +1,47 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { PathFaultCode, JsonFaultCode, SourceFaultCode } from '@botejs/native';
+import { type Path } from './path.ts';
+export type { PathFaultCode, JsonFaultCode, SourceFaultCode };
+export type BoteErrorCode = PathFaultCode | JsonFaultCode | SourceFaultCode | 'validation' | 'closed' | 'forward_replay';
+/** Base class for every error bote raises from its own logic. Catch this to
+ *  catch anything bote throws; branch on {@link BoteError.code} for the precise
+ *  kind. Always carries a `bote:`-prefixed message. */
+export declare abstract class BoteError extends Error {
+    readonly code: BoteErrorCode;
+    constructor(code: BoteErrorCode, message: string, options?: ErrorOptions);
+}
+export declare class PathError extends BoteError {
+    readonly code: PathFaultCode;
+    readonly path: Path;
+    constructor(path: Path, code: PathFaultCode, segment?: number);
+}
+export declare class ValidationError extends BoteError {
+    readonly code: 'validation';
+    readonly issues: readonly StandardSchemaV1.Issue[];
+    readonly path: Path;
+    constructor(issues: readonly StandardSchemaV1.Issue[], path: Path);
+}
+export declare class MalformedJsonError extends BoteError {
+    readonly code: JsonFaultCode;
+    readonly path: Path;
+    constructor(path: Path, code: JsonFaultCode, options?: ErrorOptions);
+}
+export declare class SourceReadError extends BoteError {
+    readonly code: SourceFaultCode;
+    readonly path: Path;
+    constructor(path: Path, detail: string, options?: ErrorOptions);
+}
+export declare class ForwardReplayError extends BoteError {
+    readonly code: 'forward_replay';
+    readonly offset: number;
+    readonly position: number;
+    constructor(offset: number, position: number, options?: ErrorOptions);
+}
+export declare class ClosedCursorError extends BoteError {
+    readonly code: 'closed';
+    constructor();
+}
+/** Rebuild a typed {@link BoteError} from a native addon error, anchoring it to
+ *  the `path` of the call it surfaced through. Pass-through for anything that
+ *  isn't a recognized native error (including errors already typed here). */
+export declare function deserializeNativeError(err: unknown, path: Path): unknown;

package/dist/error.js

@@ -0,0 +1,113 @@
+import { formatPath } from "./path.js";
+/** Base class for every error bote raises from its own logic. Catch this to
+ *  catch anything bote throws; branch on {@link BoteError.code} for the precise
+ *  kind. Always carries a `bote:`-prefixed message. */
+export class BoteError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = 'BoteError';
+    }
+}
+export class PathError extends BoteError {
+    path;
+    constructor(path, code, segment) {
+        const reason = (PATH_FAULT_MESSAGE[code] ?? (() => code))(segment);
+        super(code, `bote: cannot resolve ${formatPath(path)}: ${reason}`);
+        this.name = 'PathError';
+        this.path = path;
+    }
+}
+export class ValidationError extends BoteError {
+    issues;
+    path;
+    constructor(issues, path) {
+        super('validation', `bote: schema validation failed at ${formatPath(path)}: ${issues[0]?.message ?? 'unknown'}`);
+        this.name = 'ValidationError';
+        this.issues = issues;
+        this.path = path;
+    }
+}
+export class MalformedJsonError extends BoteError {
+    path;
+    constructor(path, code, options) {
+        const what = code === 'unexpected_eof' ? 'unexpected end of JSON input' : 'malformed JSON';
+        super(code, `bote: ${what} at ${formatPath(path)}`, options);
+        this.name = 'MalformedJsonError';
+        this.path = path;
+    }
+}
+export class SourceReadError extends BoteError {
+    path;
+    constructor(path, detail, options) {
+        super('source_io', `bote: source read failed at ${formatPath(path)}: ${detail}`, options);
+        this.name = 'SourceReadError';
+        this.path = path;
+    }
+}
+export class ForwardReplayError extends BoteError {
+    offset;
+    position;
+    constructor(offset, position, options) {
+        super('forward_replay', `bote: forward source cannot rewind to offset ${offset} from ${position}: the stream has already advanced. ` +
+            "Pass { rewind: 'replay' } if the producer is idempotent, { rewind: 'buffer' } to snapshot it in memory, " +
+            'or use a seekable source (fromFile/fromBuffer/fromHttpRange) for repeated or out-of-order access.', options);
+        this.name = 'ForwardReplayError';
+        this.offset = offset;
+        this.position = position;
+    }
+}
+export class ClosedCursorError extends BoteError {
+    constructor() {
+        super('closed', 'bote: cursor is closed');
+        this.name = 'ClosedCursorError';
+    }
+}
+/** `bote:<code>[:<detail>]` lines the native addon emits in place of a human
+ *  message, so the typed error and its message live on this side only. `<code>`
+ *  is a Rust-owned native fault code; `<detail>` is a path fault's offending
+ *  segment or a source fault's reason. The code groups below are typed against
+ *  the Rust enums, so renaming a code in Rust breaks compilation here. */
+const NATIVE_ERROR = /^bote:([a-z_]+)(?::([\s\S]*))?$/;
+const PATH_CODES = ['through_scalar', 'scalar_target', 'wrong_kind'];
+const JSON_CODES = ['malformed_json', 'unexpected_eof'];
+const SOURCE_CODE = 'source_io';
+const FORWARD_REWIND = /forward source cannot rewind to offset (\d+) from (\d+)/;
+/** Rebuild a typed {@link BoteError} from a native addon error, anchoring it to
+ *  the `path` of the call it surfaced through. Pass-through for anything that
+ *  isn't a recognized native error (including errors already typed here). */
+export function deserializeNativeError(err, path) {
+    if (!(err instanceof Error) || err instanceof BoteError) {
+        return err;
+    }
+    const match = NATIVE_ERROR.exec(err.message);
+    if (!match) {
+        return err;
+    }
+    const code = match[1];
+    const detail = match[2];
+    if (PATH_CODES.includes(code)) {
+        const segment = detail === undefined ? undefined : Number(detail);
+        return new PathError(path, code, segment);
+    }
+    if (JSON_CODES.includes(code)) {
+        return new MalformedJsonError(path, code, { cause: err });
+    }
+    if (code === SOURCE_CODE) {
+        // A forward reader rejects its read() with a ForwardReplayError; the native
+        // layer can only relay it as a generic source_io fault, so rebuild the typed
+        // error from the message it wrapped (offset/position survive in the detail).
+        const rewind = FORWARD_REWIND.exec(detail ?? '');
+        if (rewind) {
+            return new ForwardReplayError(Number(rewind[1]), Number(rewind[2]), { cause: err });
+        }
+        return new SourceReadError(path, detail ?? '', { cause: err });
+    }
+    return err;
+}
+const PATH_FAULT_MESSAGE = {
+    wrong_kind: (segment) => `path segment ${segment} does not match the container kind`,
+    scalar_target: () => 'target value is not a container',
+    through_scalar: (segment) => `path traverses a non-container value at segment ${segment}`,
+};

package/dist/index.d.ts

@@ -1,6 +1,10 @@
 export { type IterOptions } from './args.ts';
-export { ValidationError, PathError, formatPath, type Path, type PathFaultCode, type Segment, type StandardSchemaV1, } from './validate.ts';
+export { type StandardSchemaV1 } from './validate.ts';
+export { BoteError, PathError, SourceReadError, ValidationError, ClosedCursorError, MalformedJsonError, ForwardReplayError, type BoteErrorCode, type PathFaultCode, type JsonFaultCode, type SourceFaultCode, } from './error.ts';
+export { formatPath, type Path, type Segment } from './path.ts';
 export { DEFAULT_ITER_BATCH, MAX_ITER_BATCH, type Cursor, type RootCursor, type IterKey } from './cursor.ts';
-export { fromBuffer, fromFile, fromHttpRange, type FactoryOptions, type Source, type SourceReader, type HttpRangeOptions, } from './sources.ts';
+export { type Source, type Reader, type ReadResult, type ForwardSource, type FactoryOptions, type SeekableSource, } from './source/base.ts';
+export { fromFile, fromBuffer, fromHttpRange, type HttpRangeOptions } from './source/seekable.ts';
+export { fromReadable, fromHttpRequest, type ReadableOptions, type ReadableProducer, type HttpRequestOptions, } from './source/forward.ts';
 export { type IterStream } from './stream.ts';
-export { open, type OpenOptions } from './open.ts';
+export { open, type OpenOptions, type ForwardOpenOptions } from './open.ts';

package/dist/index.js

@@ -1,4 +1,6 @@
-export { ValidationError, PathError, formatPath, } from "./validate.js";
+export { BoteError, PathError, SourceReadError, ValidationError, ClosedCursorError, MalformedJsonError, ForwardReplayError, } from "./error.js";
+export { formatPath } from "./path.js";
 export { DEFAULT_ITER_BATCH, MAX_ITER_BATCH } from "./cursor.js";
-export { fromBuffer, fromFile, fromHttpRange, } from "./sources.js";
+export { fromFile, fromBuffer, fromHttpRange } from "./source/seekable.js";
+export { fromReadable, fromHttpRequest, } from "./source/forward.js";
 export { open } from "./open.js";