@botejs/core 0.4.0 → 0.6.0

package/README.md

@@ -1,133 +1,62 @@
 # 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 | 616.02 ms |        1.03 GB |            n/a |
-| items[535399]  | JSON.parse | 604.63 ms |        1.03 GB |            n/a |
-| items[1070797] | JSON.parse | 600.68 ms |        1.03 GB |            n/a |
-| items[0]       | bote       | 527.80 µs |       291.6 KB |       130.4 KB |
-| items[535399]  | bote       | 187.24 ms |       742.3 KB |        36.7 MB |
-| items[1070797] | bote       | 371.61 ms |       828.7 KB |        37.1 MB |
-
-## array access
-
-`iter` streams the elements of an array at a path, **a batch at a time**, so you never hold the whole collection in memory and not wait for the heat death of the universe if this yielded individually. each `for await` step yields an array of items (use `walk` to step over the members of an object):
-
-```ts
-// e.g. [{ id: 'user-1' }, { id: 'user-2' }, ...]
-await using cursor = await open(fromFile('./users.json'))
-
-// root is an array
-for await (const users of cursor.iter()) {
-  for (const user of users) {
-    console.log(user)
-  }
-}
-```
-
-pass an options object as the last argument to tune what comes back: `batch`, `select`, `schema`, `onInvalid`, and `withIndex`. if you want to know more of the options, see [`arrays.js`](./examples/arrays.js).
-
-## object access
-
-`walk` steps over the members of an object at a path, yielding a **`[key, cursor]`** pair per member. the key is the member name, the cursor is anchored at its value. each child cursor is first-class: it outlives the loop and can be `walk`ed again, which is what lets you descend a tree of unknown depth.
-
-```ts
-// e.g. { alice: { role: 'admin' }, bob: { role: 'guest' }, ... }
-await using cursor = await open(fromFile('./accounts.json'))
-
-for await (const [name, account] of cursor.walk()) {
-  // name is the member name ('alice', 'bob', ...)
-  const role = await account.get('role')
-  console.log(`${name}: ${role}`)
-}
-```
-
-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 rows of section.iter('rows')) {
-    console.log(rows)
-  }
-}
+// node examples/citylots.js
+import { join } from 'node:path';
+import { open, fromFile } from '@botejs/core';
+
+// 181 MB GeoJSON:
+// { type: "...", features: [{ properties: { STREET: "..." }}] }
+const filePath = join(import.meta.dirname, 'citylots.json');
+
+await using cursor = await open(fromFile(filePath));
+
+console.log(`type: ${await cursor.get('type')}`);
+// type: 'FeatureCollection'
+
+console.log(`features: ${await cursor.count('features')}`);
+// features: 206_560
+
+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));
+// [[ 'UNKNOWN', 2843 ], [ 'MASON', 2651 ], [ 'PINE', 1799 ], ... ]
 ```
 
-## validation
-
-`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`:
-
-```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)
-
-for await (const users of cursor.iter('users', User)) {
-  // user: User[]
-  const emails = users.map((user) => user.email)
-  await sendNewsletter(emails)
-}
-
-await cursor.close()
-```
-
-## memory
-
-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.
+Given a **seekable** source (e.g. a file, an HTTP range) or "forward-only" source (e.g. HTTP GET request) and a path, it retrieves values out of a JSON, without loading the whole thing in-memory.
 
-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.
+Here's a comparison of running above (using Apple M1 Pro 2021's `/usr/bin/time -l`):
 
-## sources
+| method             | mean time | mean peak footprint (MB) |
+| ------------------ | --------- | ------------------------ |
+| JSON.parse         | 0.81 s    | 647.0                    |
+| bote               | 1.062 s   | 89.0                     |
+| @streamparser/json | 4.363 s   | 98.7                     |
+| JSONStream         | 4.417 s   | 60.7                     |
+| oboe.js            | 9.649 s   | 102.6                    |
+| stream-json        | 18.693 s  | 184.3                    |
 
-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,15 +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 are yielded per batch. Higher is faster, but takes more memory to materialise those items. */
+    /** How many items cross the native boundary per fetch, which also bounds the
+     *  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;
+    /** 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';
-    /** Yield `[index, value]` tuples instead of bare values, where `index` is
-     *  the zero-based position of the element in the source array. */
-    withIndex?: boolean;
 }
 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

@@ -0,0 +1,97 @@
+import type { Cursor as NativeCursor } from '@botejs/native';
+import { type Path, type Segment } from './path.ts';
+import { type IterStream } from './stream.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> = {
+    -readonly [K in keyof S]: unknown;
+};
+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 the members of the array or object at `path`.
+     *
+     * @example
+     * const total = await root.count('users');
+     */
+    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 & {
+        withKey: true;
+        schema: Sch;
+    }]): IterStream<[IterKey, InferOutput<Sch>]>;
+    iter<Sch extends StandardSchemaV1>(...args: [...Segment[], IterOptions & {
+        schema: Sch;
+    }]): IterStream<InferOutput<Sch>>;
+    iter<S extends Record<string, Segment | Path>>(...args: [...Segment[], IterOptions & {
+        withKey: true;
+        select: S;
+    }]): IterStream<[IterKey, SelectMapShape<S>]>;
+    iter<S extends Record<string, Segment | Path>>(...args: [...Segment[], IterOptions & {
+        select: S;
+    }]): IterStream<SelectMapShape<S>>;
+    iter(...args: [...Segment[], IterOptions & {
+        withKey: true;
+    }]): IterStream<[IterKey, unknown]>;
+    iter(...args: [...Segment[], IterOptions]): IterStream<unknown>;
+}
+export interface RootCursor extends Cursor, AsyncDisposable {
+    /** Close the underlying source. Idempotent. */
+    close(): Promise<void>;
+}
+export type CursorState = {
+    closed: boolean;
+};
+export declare function wrap(native: NativeCursor, state: CursorState): Cursor;
+export declare function ensureOpen(state: CursorState): void;
+export {};

package/dist/cursor.js

@@ -0,0 +1,124 @@
+import { deserializeNativeError, ClosedCursorError, MalformedJsonError } from "./error.js";
+import { validatePath } from "./path.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;
+export function wrap(native, state) {
+    const cursor = {
+        async hop(...path) {
+            ensureOpen(state);
+            validatePath(path);
+            const child = await withPath(path, () => native.hop(path));
+            return child ? wrap(child, state) : null;
+        },
+        async has(...args) {
+            ensureOpen(state);
+            const { path, tail: schema } = splitArgs(args);
+            if (schema !== undefined && !isSchema(schema)) {
+                throw new TypeError('has: expected a Standard Schema as the trailing argument');
+            }
+            if (!schema) {
+                return withPath(path, () => native.has(path));
+            }
+            if (!(await withPath(path, () => native.has(path)))) {
+                return false;
+            }
+            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);
+        },
+        async get(...args) {
+            ensureOpen(state);
+            const { path, tail: schema } = splitArgs(args);
+            if (schema !== undefined && !isSchema(schema)) {
+                throw new TypeError('get: expected a Standard Schema as the trailing argument');
+            }
+            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);
+            return withPath(path, () => native.count(path));
+        },
+        iter(...args) {
+            ensureOpen(state);
+            const { path, tail } = splitArgs(args);
+            const { schema, select, batch, onInvalid, withKey } = normalizeIterTail(tail);
+            if (batch !== undefined && (!Number.isInteger(batch) || batch <= 0 || batch > MAX_ITER_BATCH)) {
+                throw new RangeError(`iter: batch must be an integer in 1..=${MAX_ITER_BATCH}, got ${batch}`);
+            }
+            if (withKey !== undefined && typeof withKey !== 'boolean') {
+                throw new TypeError(`iter: withKey must be a boolean, got ${typeof withKey}`);
+            }
+            if (onInvalid !== undefined && onInvalid !== 'throw' && onInvalid !== 'skip') {
+                throw new RangeError(`iter: onInvalid must be "throw" or "skip", got ${JSON.stringify(onInvalid)}`);
+            }
+            const resolvedBatch = batch ?? DEFAULT_ITER_BATCH;
+            const selectIr = select !== undefined ? serializeSelect(select) : undefined;
+            const wantKey = withKey ?? false;
+            const nativeWithKey = wantKey || schema !== undefined;
+            const inner = native.iter(path, { selectIr, batch: resolvedBatch, withKey: nativeWithKey });
+            if (!schema) {
+                return nativeStream(inner, path, resolvedBatch, (raw) => parseValue(raw, path));
+            }
+            const policy = onInvalid ?? 'throw';
+            return nativeStream(inner, path, resolvedBatch, async (raw) => {
+                const out = [];
+                for (const [key, value] of parseValue(raw, path)) {
+                    const result = await validateItem(schema, value, [...path, key], policy);
+                    if ('skip' in result) {
+                        continue;
+                    }
+                    out.push(wantKey ? [key, result.value] : result.value);
+                }
+                return out;
+            });
+        },
+    };
+    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) {
+                yield await mapBatch(raw);
+            }
+        }
+        catch (err) {
+            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,4 +1,10 @@
 export { type IterOptions } from './args.ts';
-export { ValidationError, PathError, formatPath, type Path, type PathFaultCode, type Segment, type StandardSchemaV1, } from './validate.ts';
-export { open, DEFAULT_ITER_BATCH, MAX_ITER_BATCH, type Cursor, type RootCursor, type OpenOptions, type WalkEntry, type IterIndex as IterKey, } from './open.ts';
-export { fromBuffer, fromFile, fromHttpRange, type FactoryOptions, type Source, type SourceReader, type HttpRangeOptions, } from './sources.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 { 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, type ForwardOpenOptions } from './open.ts';

package/dist/index.js

@@ -1,3 +1,6 @@
-export { ValidationError, PathError, formatPath, } from "./validate.js";
-export { open, DEFAULT_ITER_BATCH, MAX_ITER_BATCH, } from "./open.js";
-export { fromBuffer, fromFile, fromHttpRange, } from "./sources.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 { fromFile, fromBuffer, fromHttpRange } from "./source/seekable.js";
+export { fromReadable, fromHttpRequest, } from "./source/forward.js";
+export { open } from "./open.js";