@botejs/core 0.2.0 → 0.4.0

package/README.md

@@ -8,94 +8,121 @@ npm install @botejs/core
 
 ```ts
 import { open, fromFile } from '@botejs/core'
+import { publish } from './message-bus'
 
-import * as z from 'zod' // or bring your own Standard Schema validator
+// e.g. { items: [...] }
+await using cursor = await open(fromFile('./some-large.json'))
 
-const User = z.object({
-  id: z.string(),
-  name: z.string(),
-  email: z.string(),
-  details: z.object({
-    lastLoggedIn: z.number(),
-  }),
-})
+// 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 |
 
-type User = z.infer<typeof User>
+## array access
 
-await using cursor = await open(fromFile('./your-big.json'))
+`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):
 
-// users[1000].name
-const desc0: unknown = await cursor.get('users', 1000, 'name')
-// for .get and .iter, you can supply a validator as the last argument
-const desc1: string = await cursor.get('users', 1000, 'name', User.shape.name)
+```ts
+// e.g. [{ id: 'user-1' }, { id: 'user-2' }, ...]
+await using cursor = await open(fromFile('./users.json'))
 
-// iterate an array in batches
-for await (const batch of cursor.iter('users', User)) {
-  // batch: User[]
-  for (const user of batch) {
+// root is an array
+for await (const users of cursor.iter()) {
+  for (const user of users) {
     console.log(user)
   }
 }
+```
 
-// pick several fields into a named object to avoid resolving big items
-for await (const batch of cursor.iter('users', {
-  select: {
-    id: 'id',
-    logged: ['details', 'lastLoggedIn'],
-  },
-  schema: z.object({
-    id: User.shape.id,
-    logged: User.shape.details.lastLoggedIn,
-  }),
-})) {
-  // batch: { id: string, logged: number }[]
-  for (const userLog of batch) {
-    console.log(userLog)
-  }
+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.
 
-// or pick a single field
-for await (const batch of cursor.iter('users', {
-  select: 'name',
-  schema: User.shape.name,
-})) {
-  // batch: string[]
-  for (const name of batch) {
-    console.log({ name })
+## 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)
   }
 }
+```
 
-// for open-ended per-child work (e.g. conditional reads, recursive descent, nested
-// iters), `walk` yields a subcursor positioned at each child:
-for await (const metaCursor of cursor.walk('meta')) {
-  if (metaCursor.key === 'details') {
-    const detailsValue = await metaCursor.get()
-    console.log(detailsValue)
-  }
+## 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 using' would normally clean up resources for you
-// when it goes out of lexical scope. if you hate that,
-// you can do it explicitly as well.
 await cursor.close()
 ```
 
-given a **seekable** source (e.g. a file, an HTTP range) and a path, it can retrieve values in a JSON quickly, without loading the whole thing in-memory.
+## memory
 
-here's a run (Apple M1 Pro 2021, ~500MB JSON array file, cold-cache, default settings):
+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.
 
-| 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 |
+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.
 
 ## sources
 
-bote currently only has `fromFile` and `fromHttpRange` as pre-built sources. create your own by implementing the `Source` interface. see [./packages/core/src/sources.ts](./packages/core/src/sources.ts) on how it works.
+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
 

package/dist/args.js

@@ -1,11 +1,5 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.splitArgs = splitArgs;
-exports.isSchema = isSchema;
-exports.normalizeIterTail = normalizeIterTail;
-exports.serializeSelect = serializeSelect;
-const path_ts_1 = require("./path.js");
-function splitArgs(args) {
+import { validatePath } from "./path.js";
+export function splitArgs(args) {
     let pathArgs;
     let tail;
     if (args.length === 0) {
@@ -23,35 +17,41 @@ function splitArgs(args) {
             tail = undefined;
         }
     }
-    (0, path_ts_1.validatePath)(pathArgs);
+    validatePath(pathArgs);
     return { path: pathArgs, tail };
 }
-function isSchema(value) {
+export function isSchema(value) {
     return typeof value === 'object' && value !== null && '~standard' in value;
 }
-function normalizeIterTail(tail) {
+export function normalizeIterTail(tail) {
     if (!tail)
         return {};
     if (isSchema(tail))
         return { schema: tail };
     return tail;
 }
-function serializeSelect(select) {
+export function serializeSelect(select) {
     if (typeof select === 'string' || typeof select === 'number') {
         const one = [select];
-        (0, path_ts_1.validatePath)(one);
+        validatePath(one);
         return JSON.stringify({ one });
     }
     if (Array.isArray(select)) {
-        (0, path_ts_1.validatePath)(select);
+        validatePath(select);
         if (select.length === 0) {
             throw new RangeError('iter: select sub-path must have at least one segment');
         }
         return JSON.stringify({ one: select });
     }
+    if (select === null || typeof select !== 'object') {
+        throw new TypeError(`iter: select must be a segment, path, or field map, got ${describeSelect(select)}`);
+    }
     const entries = Object.entries(select).map(([k, sub]) => {
         const path = typeof sub === 'string' || typeof sub === 'number' ? [sub] : sub;
-        (0, path_ts_1.validatePath)(path);
+        if (!Array.isArray(path)) {
+            throw new TypeError(`iter: select field ${JSON.stringify(k)} must be a segment or path, got ${describeSelect(sub)}`);
+        }
+        validatePath(path);
         if (path.length === 0) {
             throw new RangeError(`iter: select field ${JSON.stringify(k)} sub-path must have at least one segment`);
         }
@@ -62,3 +62,8 @@ function serializeSelect(select) {
     }
     return JSON.stringify({ map: entries });
 }
+function describeSelect(value) {
+    if (value === null)
+        return 'null';
+    return Array.isArray(value) ? 'array' : typeof value;
+}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { type IterOptions } from './args.ts';
-export { ValidationError, formatPath, type Path, type Segment, type StandardSchemaV1 } from './validate.ts';
-export { open, DEFAULT_ITER_BATCH, type Cursor, type RootCursor, type OpenOptions, type IterIndex as IterKey, } from './open.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';

package/dist/index.js

@@ -1,19 +1,3 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.fromHttpRange = exports.fromFile = exports.fromBuffer = exports.DEFAULT_ITER_BATCH = exports.formatPath = exports.ValidationError = void 0;
-// Node 18 and Node 20.3 predate `Symbol.asyncDispose`; mirror what TS emits for
-// `await using` so the well-known symbol is available across our engine range.
-if (!Symbol.asyncDispose) {
-    ;
-    Symbol.asyncDispose = Symbol.for('Symbol.asyncDispose');
-}
-var validate_ts_1 = require("./validate.js");
-Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return validate_ts_1.ValidationError; } });
-Object.defineProperty(exports, "formatPath", { enumerable: true, get: function () { return validate_ts_1.formatPath; } });
-var open_ts_1 = require("./open.js");
-Object.defineProperty(exports, "open", { enumerable: true, get: function () { return open_ts_1.open; } });
-Object.defineProperty(exports, "DEFAULT_ITER_BATCH", { enumerable: true, get: function () { return open_ts_1.DEFAULT_ITER_BATCH; } });
-var sources_ts_1 = require("./sources.js");
-Object.defineProperty(exports, "fromBuffer", { enumerable: true, get: function () { return sources_ts_1.fromBuffer; } });
-Object.defineProperty(exports, "fromFile", { enumerable: true, get: function () { return sources_ts_1.fromFile; } });
-Object.defineProperty(exports, "fromHttpRange", { enumerable: true, get: function () { return sources_ts_1.fromHttpRange; } });
+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";

package/dist/open.d.ts

@@ -7,8 +7,11 @@ type SelectMapShape<S> = {
 };
 /** Zero-based index of an array element. */
 export type IterIndex = number;
+/** One `walk` step: the member's key paired with a cursor anchored at its value. */
+export type WalkEntry = [key: string, cursor: Cursor];
 export declare const DEFAULT_SOURCE_CHUNK_BYTES: number;
 export declare const DEFAULT_ITER_BATCH = 1000;
+export declare const MAX_ITER_BATCH = 1000000;
 export interface OpenOptions {
     /**
      * Slot budget for the structural-index cache: one slot per cached container
@@ -40,8 +43,7 @@ export interface OpenOptions {
     arrayIndexInterval?: number;
 }
 export interface Cursor {
-    /** Object-member key or array-element index that this cursor was yielded under by `walk`. `null` on the root cursor. */
-    readonly key: string | number | null;
+    hop(...path: Segment[]): Promise<Cursor | null>;
     has(...path: Segment[]): Promise<boolean>;
     has(...args: [...Segment[], StandardSchemaV1]): Promise<boolean>;
     get(...path: Segment[]): Promise<unknown>;
@@ -67,6 +69,7 @@ export interface Cursor {
         withIndex: true;
     }]): AsyncIterable<[IterIndex, unknown][]>;
     iter(...args: [...Segment[], IterOptions]): AsyncIterable<unknown[]>;
+    walk(...path: Segment[]): AsyncIterable<WalkEntry>;
     walk(...path: Segment[]): AsyncIterable<Cursor>;
 }
 export interface RootCursor extends Cursor, AsyncDisposable {

package/dist/open.js

@@ -1,35 +1,41 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_ITER_BATCH = exports.DEFAULT_SOURCE_CHUNK_BYTES = void 0;
-exports.open = open;
-const native_1 = require("@botejs/native");
-const path_ts_1 = require("./path.js");
-const validate_ts_1 = require("./validate.js");
-const args_ts_1 = require("./args.js");
-exports.DEFAULT_SOURCE_CHUNK_BYTES = 64 * 1024;
-exports.DEFAULT_ITER_BATCH = 1000;
+import { open as openNative } from '@botejs/native';
+import { validatePath } from "./path.js";
+import { runStandardSchema, validateItem, formatPath, PathError, } from "./validate.js";
+import { splitArgs, isSchema, serializeSelect, normalizeIterTail, } from "./args.js";
+export const DEFAULT_SOURCE_CHUNK_BYTES = 64 * 1024;
+export const DEFAULT_ITER_BATCH = 1000;
+export const MAX_ITER_BATCH = 1_000_000;
 /**
  * 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.
  */
-async function open(source, options) {
+export async function open(source, options) {
     const { indexCacheEntries, objectMemberCap, arrayIndexInterval } = options ?? {};
     for (const [name, value] of [
         ['indexCacheEntries', indexCacheEntries],
         ['objectMemberCap', objectMemberCap],
         ['arrayIndexInterval', arrayIndexInterval],
     ]) {
-        if (value !== undefined && (!Number.isInteger(value) || value < 0)) {
+        if (value !== undefined && (!Number.isSafeInteger(value) || value < 0)) {
             throw new RangeError(`open: ${name} must be a non-negative integer (0 disables), got ${value}`);
         }
     }
     const reader = await source.open();
-    const chunkBytes = reader.chunkBytes ?? exports.DEFAULT_SOURCE_CHUNK_BYTES;
+    const chunkBytes = reader.chunkBytes ?? DEFAULT_SOURCE_CHUNK_BYTES;
     let native;
     try {
-        native = (0, native_1.open)({
+        if (!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) {
+            throw new RangeError(`open: chunkBytes must be a positive integer, got ${chunkBytes}`);
+        }
+        if (chunkBytes % 64 !== 0) {
+            throw new RangeError(`open: chunkBytes must be a multiple of 64, got ${chunkBytes}`);
+        }
+        native = openNative({
             size: reader.size,
             chunkBytes,
             indexCacheEntries,
@@ -39,17 +45,24 @@ async function open(source, options) {
         });
     }
     catch (err) {
-        await closeReader(reader);
+        // Don't let a failing cleanup mask the original open error; attach it as cause.
+        try {
+            await closeReader(reader);
+        }
+        catch (closeErr) {
+            if (err instanceof Error)
+                err.cause ??= closeErr;
+        }
         throw err;
     }
-    let closed = false;
+    const state = { closed: false };
     const close = async () => {
-        if (closed)
+        if (state.closed)
             return;
-        closed = true;
+        state.closed = true;
         await closeReader(reader);
     };
-    return Object.assign(wrap(native), {
+    return Object.assign(wrap(native, state), {
         close,
         [Symbol.asyncDispose]: close,
     });
@@ -58,66 +71,157 @@ async function closeReader(reader) {
     if (reader.close)
         await reader.close();
 }
-function wrap(native) {
+const NATIVE_PATH_ERROR = /^bote:path:([a-z_]+)(?::(\d+))?$/;
+function deserializeError(err, path) {
+    if (err instanceof Error && !(err instanceof PathError)) {
+        const match = NATIVE_PATH_ERROR.exec(err.message);
+        if (match) {
+            const segment = match[2] === undefined ? undefined : Number(match[2]);
+            return new PathError(path, match[1], segment);
+        }
+    }
+    return err;
+}
+/** 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). */
+function ensureOpen(state) {
+    if (state.closed)
+        throw new Error('bote: cursor is closed');
+}
+function wrap(native, state) {
     const cursor = {
-        get key() {
-            return native.key;
+        async hop(...path) {
+            ensureOpen(state);
+            validatePath(path);
+            let child;
+            try {
+                child = await native.hop(path);
+            }
+            catch (err) {
+                throw deserializeError(err, path);
+            }
+            return child ? wrap(child, state) : null;
         },
         async has(...args) {
-            const { path, tail: schema } = (0, args_ts_1.splitArgs)(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 native.has(path);
             if (!(await native.has(path)))
                 return false;
-            const result = await (0, validate_ts_1.validateItem)(schema, await native.get(path), path, 'skip');
+            const text = await 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) {
-            const { path, tail: schema } = (0, args_ts_1.splitArgs)(args);
-            const value = await native.get(path);
-            if (!schema || value === undefined)
+            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');
+            }
+            let value;
+            try {
+                const text = await native.get(path);
+                value = text === undefined ? undefined : parseValue(text, path);
+            }
+            catch (err) {
+                throw deserializeError(err, path);
+            }
+            if (!schema)
                 return value;
-            return (0, validate_ts_1.runStandardSchema)(schema, value, path);
+            return runStandardSchema(schema, value, path);
         },
-        count(...path) {
-            (0, path_ts_1.validatePath)(path);
-            return native.count(path);
+        async count(...path) {
+            ensureOpen(state);
+            validatePath(path);
+            try {
+                return await native.count(path);
+            }
+            catch (err) {
+                throw deserializeError(err, path);
+            }
         },
         iter(...args) {
-            const { path, tail } = (0, args_ts_1.splitArgs)(args);
-            const { schema, select, batch, onInvalid, withIndex } = (0, args_ts_1.normalizeIterTail)(tail);
-            if (batch !== undefined && (!Number.isInteger(batch) || batch <= 0)) {
-                throw new RangeError(`iter: batch must be a positive integer, got ${batch}`);
+            ensureOpen(state);
+            const { path, tail } = splitArgs(args);
+            const { schema, select, batch, onInvalid, withIndex } = 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 (withIndex !== undefined && typeof withIndex !== 'boolean') {
+                throw new TypeError(`iter: withIndex must be a boolean, got ${typeof withIndex}`);
+            }
+            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 inner = native.iter(path, { selectIr, batch: resolvedBatch });
+            if (!schema) {
+                return {
+                    async *[Symbol.asyncIterator]() {
+                        let i = 0;
+                        try {
+                            for await (const b of inner) {
+                                const batch = parseValue(b, path);
+                                if (!withIndex) {
+                                    yield batch;
+                                    continue;
+                                }
+                                const out = new Array(batch.length);
+                                for (let j = 0; j < batch.length; j++) {
+                                    out[j] = [i++, batch[j]];
+                                }
+                                yield out;
+                            }
+                        }
+                        catch (err) {
+                            throw deserializeError(err, path);
+                        }
+                    },
+                };
             }
-            const resolvedBatch = batch ?? exports.DEFAULT_ITER_BATCH;
-            const selectIr = select !== undefined ? (0, args_ts_1.serializeSelect)(select) : undefined;
-            const inner = native.iter(path, { selectIr, batch: resolvedBatch, withKey: withIndex });
-            if (!schema)
-                return inner;
             const policy = onInvalid ?? 'throw';
             return {
                 async *[Symbol.asyncIterator]() {
                     let i = 0;
-                    for await (const b of inner) {
-                        const out = [];
-                        for (const v of b) {
-                            const value = withIndex ? v[1] : v;
-                            const result = await (0, validate_ts_1.validateItem)(schema, value, [...path, i++], policy);
-                            if ('skip' in result)
-                                continue;
-                            out.push(withIndex ? [v[0], result.value] : result.value);
+                    try {
+                        for await (const b of inner) {
+                            const out = [];
+                            for (const v of parseValue(b, path)) {
+                                const index = i++;
+                                const result = await validateItem(schema, v, [...path, index], policy);
+                                if ('skip' in result) {
+                                    continue;
+                                }
+                                out.push(withIndex ? [index, result.value] : result.value);
+                            }
+                            yield out;
                         }
-                        yield out;
+                    }
+                    catch (err) {
+                        throw deserializeError(err, path);
                     }
                 },
             };
         },
         walk(...path) {
-            (0, path_ts_1.validatePath)(path);
+            ensureOpen(state);
+            validatePath(path);
             return {
                 async *[Symbol.asyncIterator]() {
-                    for await (const child of native.walk(path)) {
-                        yield wrap(child);
+                    try {
+                        for await (const [key, child] of native.walk(path)) {
+                            yield [key, wrap(child, state)];
+                        }
+                    }
+                    catch (err) {
+                        throw deserializeError(err, path);
                     }
                 },
             };
@@ -125,3 +229,11 @@ function wrap(native) {
     };
     return cursor;
 }
+function parseValue(text, path) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error(`bote: malformed JSON value at ${formatPath(path)}`);
+    }
+}

package/dist/path.js

@@ -1,18 +1,14 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAX_ARRAY_INDEX = void 0;
-exports.validatePath = validatePath;
 /** Upper bound on numeric segments (napi takes them as `u32`). 2^32 - 1
  *  comfortably covers any in-memory JSON array. */
-exports.MAX_ARRAY_INDEX = 0xffffffff;
-function validatePath(path) {
+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')
             continue;
-        if (typeof s === 'number' && Number.isInteger(s) && s >= 0 && s <= exports.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 (<= ${exports.MAX_ARRAY_INDEX}), got ${describeBadSegment(s)}`);
+        throw new TypeError(`path segment ${i}: expected string or non-negative integer (<= ${MAX_ARRAY_INDEX}), got ${describeBadSegment(s)}`);
     }
 }
 function describeBadSegment(s) {

package/dist/sources.js

@@ -1,16 +1,11 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.fromBuffer = fromBuffer;
-exports.fromFile = fromFile;
-exports.fromHttpRange = fromHttpRange;
-const promises_1 = require("node:fs/promises");
+import { open as fsOpen } from 'node:fs/promises';
 /** Default chunk size, in bytes, for in-memory sources. */
 const DEFAULT_BUFFER_CHUNK_BYTES = 4 * 1024;
 /** Default chunk size, in bytes, for local files: matches typical filesystem readahead. */
 const DEFAULT_FILE_CHUNK_BYTES = 64 * 1024;
 /** Default chunk size, in bytes, for HTTP range reads: amortizes RTT across more data. */
 const DEFAULT_URL_CHUNK_BYTES = 256 * 1024;
-function fromBuffer(buf, options) {
+export function fromBuffer(buf, options) {
     const view = buf instanceof Uint8Array ? buf : new Uint8Array(buf);
     const chunkBytes = options?.chunkBytes ?? DEFAULT_BUFFER_CHUNK_BYTES;
     return {
@@ -21,11 +16,11 @@ function fromBuffer(buf, options) {
         }),
     };
 }
-function fromFile(path, options) {
+export function fromFile(path, options) {
     const chunkBytes = options?.chunkBytes ?? DEFAULT_FILE_CHUNK_BYTES;
     return {
         open: async () => {
-            const handle = await (0, promises_1.open)(path, 'r');
+            const handle = await fsOpen(path, 'r');
             const stat = await handle.stat();
             let closed = false;
             return {
@@ -52,7 +47,7 @@ function fromFile(path, options) {
         },
     };
 }
-function fromHttpRange(url, options) {
+export function fromHttpRange(url, options) {
     const init = options?.init;
     const chunkBytes = options?.chunkBytes ?? DEFAULT_URL_CHUNK_BYTES;
     return {

package/dist/validate.d.ts

@@ -1,5 +1,6 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
-export type { StandardSchemaV1 };
+import type { PathFaultCode } from '@botejs/native';
+export type { StandardSchemaV1, PathFaultCode };
 export type Segment = string | number;
 export type Path = readonly Segment[];
 export declare class ValidationError extends Error {
@@ -7,6 +8,12 @@ export declare class ValidationError extends Error {
     readonly path: Path;
     constructor(issues: readonly StandardSchemaV1.Issue[], path: Path);
 }
+export declare class PathError extends Error {
+    readonly path: Path;
+    /** The fault kind; stable across versions, safe to branch on. */
+    readonly code: PathFaultCode;
+    constructor(path: Path, code: PathFaultCode, segment?: number);
+}
 export declare function runStandardSchema<O>(schema: StandardSchemaV1<unknown, O>, value: unknown, path: Path): Promise<O>;
 export declare function validateItem<O>(schema: StandardSchemaV1<unknown, O>, value: unknown, path: Path, onInvalid: 'throw' | 'skip'): Promise<{
     skip: true;

package/dist/validate.js

@@ -1,10 +1,4 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ValidationError = void 0;
-exports.runStandardSchema = runStandardSchema;
-exports.validateItem = validateItem;
-exports.formatPath = formatPath;
-class ValidationError extends Error {
+export class ValidationError extends Error {
     issues;
     path;
     constructor(issues, path) {
@@ -14,14 +8,35 @@ class ValidationError extends Error {
         this.path = path;
     }
 }
-exports.ValidationError = ValidationError;
-async function runStandardSchema(schema, value, path) {
+/** Human message per fault kind. The native layer ships only the code (and the
+ *  offending `segment` where it matters), so this is the single source of the
+ *  user-facing prose. Keyed by the Rust-generated [`PathFaultCode`]. */
+const PATH_FAULT_MESSAGE = {
+    through_scalar: (segment) => `path traverses a non-container value at segment ${segment}`,
+    wrong_kind: (segment) => `path segment ${segment} does not match the container kind`,
+    scalar_target: () => 'target value is not a container',
+    iter_on_object: () => 'iter target is an object; use walk() to iterate object members',
+    walk_on_array: () => 'walk target is an array; use iter() to iterate array elements',
+};
+export class PathError extends Error {
+    path;
+    /** The fault kind; stable across versions, safe to branch on. */
+    code;
+    constructor(path, code, segment) {
+        const reason = (PATH_FAULT_MESSAGE[code] ?? (() => code))(segment);
+        super(`bote: cannot resolve ${formatPath(path)}: ${reason}`);
+        this.name = 'PathError';
+        this.path = path;
+        this.code = code;
+    }
+}
+export async function runStandardSchema(schema, value, path) {
     const result = await schema['~standard'].validate(value);
     if (result.issues)
         throw new ValidationError(result.issues, path);
     return result.value;
 }
-async function validateItem(schema, value, path, onInvalid) {
+export async function validateItem(schema, value, path, onInvalid) {
     const result = await schema['~standard'].validate(value);
     if (result.issues) {
         if (onInvalid === 'skip')
@@ -30,7 +45,7 @@ async function validateItem(schema, value, path, onInvalid) {
     }
     return { value: result.value };
 }
-function formatPath(path) {
+export function formatPath(path) {
     if (path.length === 0)
         return '(root)';
     let out = '';

package/package.json

@@ -1,12 +1,19 @@
 {
   "name": "@botejs/core",
-  "version": "0.2.0",
+  "version": "0.4.0",
+  "type": "module",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/jankdc/bote.git",
     "directory": "packages/core"
   },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -14,7 +21,7 @@
     "README.md"
   ],
   "engines": {
-    "node": ">= 18.17.0 < 19 || >= 20.3.0 < 21 || >= 21.1.0"
+    "node": ">= 22.18.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -23,12 +30,12 @@
   "scripts": {
     "build": "tsc",
     "build:debug": "tsc --sourceMap",
-    "test": "node --test --experimental-strip-types --no-warnings=ExperimentalWarning __test__/*.spec.ts",
+    "test": "node --test __test__/*.spec.ts",
     "lint": "oxlint src",
     "prepublishOnly": "cp ../../README.md ./README.md && tsc"
   },
   "dependencies": {
-    "@botejs/native": "workspace:*"
+    "@botejs/native": "^0.4.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",