@botejs/core 0.3.0 → 0.4.0

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,27 +17,27 @@ 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');
         }
@@ -57,7 +51,7 @@ function serializeSelect(select) {
         if (!Array.isArray(path)) {
             throw new TypeError(`iter: select field ${JSON.stringify(k)} must be a segment or path, got ${describeSelect(sub)}`);
         }
-        (0, path_ts_1.validatePath)(path);
+        validatePath(path);
         if (path.length === 0) {
             throw new RangeError(`iter: select field ${JSON.stringify(k)} sub-path must have at least one segment`);
         }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { type IterOptions } from './args.ts';
-export { ValidationError, PathError, formatPath, type Path, type Segment, type StandardSchemaV1, } from './validate.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,21 +1,3 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.fromHttpRange = exports.fromFile = exports.fromBuffer = exports.MAX_ITER_BATCH = exports.DEFAULT_ITER_BATCH = exports.formatPath = exports.PathError = 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, "PathError", { enumerable: true, get: function () { return validate_ts_1.PathError; } });
-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; } });
-Object.defineProperty(exports, "MAX_ITER_BATCH", { enumerable: true, get: function () { return open_ts_1.MAX_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.js

@@ -1,21 +1,17 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAX_ITER_BATCH = 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;
-exports.MAX_ITER_BATCH = 1_000_000;
+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],
@@ -27,7 +23,7 @@ async function open(source, options) {
         }
     }
     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 {
         if (!Number.isInteger(reader.size) || reader.size < 0) {
@@ -39,7 +35,7 @@ async function open(source, options) {
         if (chunkBytes % 64 !== 0) {
             throw new RangeError(`open: chunkBytes must be a multiple of 64, got ${chunkBytes}`);
         }
-        native = (0, native_1.open)({
+        native = openNative({
             size: reader.size,
             chunkBytes,
             indexCacheEntries,
@@ -75,14 +71,14 @@ async function closeReader(reader) {
     if (reader.close)
         await reader.close();
 }
-/** Sentinel the native layer prefixes onto shape-contradiction errors (see
- *  `session.rs` `SessionError::Path`). */
-const NATIVE_PATH_ERROR_PREFIX = 'bote.PathError: ';
-/** Rethrow a native shape-contradiction error as a `PathError` carrying the
- *  caller's path; pass anything else through unchanged. */
-function asPathError(err, path) {
-    if (err instanceof Error && !(err instanceof validate_ts_1.PathError) && err.message.startsWith(NATIVE_PATH_ERROR_PREFIX)) {
-        return new validate_ts_1.PathError(err.message.slice(NATIVE_PATH_ERROR_PREFIX.length), path);
+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;
 }
@@ -97,62 +93,65 @@ function wrap(native, state) {
     const cursor = {
         async hop(...path) {
             ensureOpen(state);
-            (0, path_ts_1.validatePath)(path);
+            validatePath(path);
             let child;
             try {
                 child = await native.hop(path);
             }
             catch (err) {
-                throw asPathError(err, path);
+                throw deserializeError(err, path);
             }
             return child ? wrap(child, state) : null;
         },
         async has(...args) {
             ensureOpen(state);
-            const { path, tail: schema } = (0, args_ts_1.splitArgs)(args);
-            if (schema !== undefined && !(0, args_ts_1.isSchema)(schema)) {
+            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) {
             ensureOpen(state);
-            const { path, tail: schema } = (0, args_ts_1.splitArgs)(args);
-            if (schema !== undefined && !(0, args_ts_1.isSchema)(schema)) {
+            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 {
-                value = await native.get(path);
+                const text = await native.get(path);
+                value = text === undefined ? undefined : parseValue(text, path);
             }
             catch (err) {
-                throw asPathError(err, path);
+                throw deserializeError(err, path);
             }
             if (!schema)
                 return value;
-            return (0, validate_ts_1.runStandardSchema)(schema, value, path);
+            return runStandardSchema(schema, value, path);
         },
         async count(...path) {
             ensureOpen(state);
-            (0, path_ts_1.validatePath)(path);
+            validatePath(path);
             try {
                 return await native.count(path);
             }
             catch (err) {
-                throw asPathError(err, path);
+                throw deserializeError(err, path);
             }
         },
         iter(...args) {
             ensureOpen(state);
-            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 || batch > exports.MAX_ITER_BATCH)) {
-                throw new RangeError(`iter: batch must be an integer in 1..=${exports.MAX_ITER_BATCH}, got ${batch}`);
+            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}`);
@@ -160,18 +159,29 @@ function wrap(native, state) {
             if (onInvalid !== undefined && onInvalid !== 'throw' && onInvalid !== 'skip') {
                 throw new RangeError(`iter: onInvalid must be "throw" or "skip", got ${JSON.stringify(onInvalid)}`);
             }
-            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 });
+            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)
-                                yield b;
+                            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 asPathError(err, path);
+                            throw deserializeError(err, path);
                         }
                     },
                 };
@@ -183,25 +193,26 @@ function wrap(native, state) {
                     try {
                         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)
+                            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 ? [v[0], result.value] : result.value);
+                                }
+                                out.push(withIndex ? [index, result.value] : result.value);
                             }
                             yield out;
                         }
                     }
                     catch (err) {
-                        throw asPathError(err, path);
+                        throw deserializeError(err, path);
                     }
                 },
             };
         },
         walk(...path) {
             ensureOpen(state);
-            (0, path_ts_1.validatePath)(path);
+            validatePath(path);
             return {
                 async *[Symbol.asyncIterator]() {
                     try {
@@ -210,7 +221,7 @@ function wrap(native, state) {
                         }
                     }
                     catch (err) {
-                        throw asPathError(err, path);
+                        throw deserializeError(err, path);
                     }
                 },
             };
@@ -218,3 +229,11 @@ function wrap(native, state) {
     };
     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 {
@@ -9,7 +10,9 @@ export declare class ValidationError extends Error {
 }
 export declare class PathError extends Error {
     readonly path: Path;
-    constructor(reason: string, 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<{

package/dist/validate.js

@@ -1,10 +1,4 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.PathError = 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,23 +8,35 @@ class ValidationError extends Error {
         this.path = path;
     }
 }
-exports.ValidationError = ValidationError;
-class PathError extends Error {
+/** 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;
-    constructor(reason, 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;
     }
 }
-exports.PathError = PathError;
-async function runStandardSchema(schema, value, path) {
+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')
@@ -39,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.3.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",