@botejs/core 0.1.2

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export type { JsonPointer } from './pointer.ts';
+export { open, type Cursor, type RootCursor, type SessionOptions } from './open.ts';
+export { fromBuffer, fromFile, fromHttpRange, type FactoryOptions, type Source, type SourceReader, type HttpRangeOptions, } from './sources.ts';
+export { ValidationError, type StandardSchemaV1 } from './validate.ts';

package/dist/index.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValidationError = exports.fromHttpRange = exports.fromFile = exports.fromBuffer = 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 open_ts_1 = require("./open.js");
+Object.defineProperty(exports, "open", { enumerable: true, get: function () { return open_ts_1.open; } });
+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; } });
+var validate_ts_1 = require("./validate.js");
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return validate_ts_1.ValidationError; } });

package/dist/open.d.ts

@@ -0,0 +1,49 @@
+import type { JsonPointer } from './pointer.ts';
+import type { Source } from './sources.ts';
+import { type StandardSchemaV1 } from './validate.ts';
+export interface SessionOptions {
+    /**
+     * Maximum number of source chunks held resident at once. Each slot
+     * accounts for one chunk's bytes plus its bitmaps; the cache also
+     * enforces a derived byte ceiling at roughly `maxResidentChunks x
+     * source.chunkBytes x 2` to bound total native memory.
+     *
+     * Defaults to 512 chunks.
+     */
+    maxResidentChunks?: number;
+}
+type InferOutput<Sch> = Sch extends StandardSchemaV1<unknown, infer O> ? O : never;
+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;
+    has<S extends string>(pointer: JsonPointer<S>): Promise<boolean>;
+    has<S extends string>(pointer: JsonPointer<S>, schema: StandardSchemaV1): Promise<boolean>;
+    get<S extends string>(pointer: JsonPointer<S>): Promise<unknown>;
+    get<S extends string, Sch extends StandardSchemaV1>(pointer: JsonPointer<S>, schema: Sch): Promise<InferOutput<Sch>>;
+    iter<S extends string>(pointer: JsonPointer<S>): AsyncIterable<unknown>;
+    iter<S extends string, Sch extends StandardSchemaV1>(pointer: JsonPointer<S>, schema: Sch): AsyncIterable<InferOutput<Sch>>;
+    walk<S extends string>(pointer: JsonPointer<S>): AsyncIterable<Cursor>;
+}
+/**
+ * The cursor returned by `open()`. Owns the underlying `Source` and exposes
+ * both an explicit `close()` and `Symbol.asyncDispose` so callers can choose
+ * between manual cleanup and `await using` scoping.
+ */
+export interface RootCursor extends Cursor, AsyncDisposable {
+    /** Close the underlying source. Idempotent. */
+    close(): Promise<void>;
+}
+/**
+ * Open a cursor over a seekable source.
+ *
+ * Calls `source.open()` to acquire a reader, then constructs the native cursor
+ * over it. The reader's `read(offset, buf)` is invoked with chunk-aligned
+ * `offset` and a `buf` whose `byteLength` equals the configured chunk size;
+ * the reader fills `buf` and resolves with `bytesRead`. `buf` is a view over
+ * native-owned memory and **MUST** not be retained past the returned promise.
+ *
+ * The returned `RootCursor` owns the reader: `close()` (or `await using`)
+ * drives the reader's own `close()` exactly once.
+ */
+export declare function open(source: Source, options?: SessionOptions): Promise<RootCursor>;
+export {};

package/dist/open.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.open = open;
+const native_1 = require("@botejs/native");
+const validate_ts_1 = require("./validate.js");
+/**
+ * Open a cursor over a seekable source.
+ *
+ * Calls `source.open()` to acquire a reader, then constructs the native cursor
+ * over it. The reader's `read(offset, buf)` is invoked with chunk-aligned
+ * `offset` and a `buf` whose `byteLength` equals the configured chunk size;
+ * the reader fills `buf` and resolves with `bytesRead`. `buf` is a view over
+ * native-owned memory and **MUST** not be retained past the returned promise.
+ *
+ * The returned `RootCursor` owns the reader: `close()` (or `await using`)
+ * drives the reader's own `close()` exactly once.
+ */
+async function open(source, options) {
+    const reader = await source.open();
+    let native;
+    try {
+        native = (0, native_1.open)({
+            size: reader.size,
+            chunkBytes: reader.chunkBytes,
+            read: async ({ offset, buf }) => reader.read(offset, buf),
+        }, {
+            maxResidentChunks: options?.maxResidentChunks,
+        });
+    }
+    catch (err) {
+        await closeReader(reader);
+        throw err;
+    }
+    let closed = false;
+    const close = async () => {
+        if (closed)
+            return;
+        closed = true;
+        await closeReader(reader);
+    };
+    return Object.assign(wrap(native), {
+        close,
+        [Symbol.asyncDispose]: close,
+    });
+}
+async function closeReader(reader) {
+    if (reader.close)
+        await reader.close();
+}
+function wrap(native) {
+    const cursor = {
+        get key() {
+            return native.key;
+        },
+        async has(pointer, schema) {
+            if (!schema)
+                return native.has(pointer);
+            if (!(await native.has(pointer)))
+                return false;
+            const result = await schema['~standard'].validate(await native.get(pointer));
+            return result.issues === undefined;
+        },
+        async get(pointer, schema) {
+            const value = await native.get(pointer);
+            return schema ? (0, validate_ts_1.runStandardSchema)(schema, value, pointer) : value;
+        },
+        iter(pointer, schema) {
+            const inner = native.iter(pointer);
+            if (!schema)
+                return inner;
+            return {
+                async *[Symbol.asyncIterator]() {
+                    let i = 0;
+                    for await (const v of inner) {
+                        yield await (0, validate_ts_1.runStandardSchema)(schema, v, `${pointer}/${i++}`);
+                    }
+                },
+            };
+        },
+        walk(pointer) {
+            return {
+                async *[Symbol.asyncIterator]() {
+                    for await (const child of native.walk(pointer)) {
+                        yield wrap(child);
+                    }
+                },
+            };
+        },
+    };
+    return cursor;
+}

package/dist/pointer.d.ts

@@ -0,0 +1,5 @@
+type ValidateTokenChars<S extends string> = S extends `${string}~${infer Rest}` ? Rest extends `0${infer After}` | `1${infer After}` ? ValidateTokenChars<After> : false : true;
+type ValidateTokens<S extends string> = S extends `${infer Token}/${infer Rest}` ? ValidateTokenChars<Token> extends true ? ValidateTokens<Rest> : false : ValidateTokenChars<S>;
+type IsJsonPointer<S extends string> = S extends '' ? true : S extends `/${infer Rest}` ? ValidateTokens<Rest> : false;
+export type JsonPointer<S extends string> = IsJsonPointer<S> extends true ? S : `Error: invalid JSON pointer "${S}"`;
+export {};

package/dist/pointer.js

@@ -0,0 +1,3 @@
+"use strict";
+// RFC 6901 JSON Pointer Static Typing Validator
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/sources.d.ts

@@ -0,0 +1,43 @@
+/**
+ * A handle on an opened seekable byte stream. The reader owns whatever
+ * resources back the stream (a file handle, an `AbortController`, etc.) and
+ * surfaces them through `close()`. Constructed by `Source.open()`; never by
+ * library callers directly.
+ */
+export interface SourceReader {
+    /** Total length of the underlying byte stream. */
+    readonly size: number;
+    /** Preferred read granularity in bytes. Must be a non-zero multiple of 64. */
+    readonly chunkBytes?: number;
+    /**
+     * Fill `buf` with up to `buf.byteLength` bytes starting at `offset` and
+     * resolve with the number of bytes written. The implementation must not
+     * retain a reference to `buf` or read from it after the returned promise
+     * resolves: `buf` is a view over native-owned memory whose lifetime ends
+     * once the promise settles.
+     */
+    read(offset: number, buf: Uint8Array): Promise<number>;
+    /** Release resources held by the reader. Driven once by the `open()` lifecycle. */
+    close?(): Promise<void> | void;
+}
+/**
+ * Describes how to obtain a seekable byte stream. Construction is cheap and
+ * synchronous - no I/O happens until `open()` runs, which the top-level
+ * `open()` API drives. Provide your own object implementing this interface to
+ * plug in custom backends.
+ */
+export interface Source {
+    /** Acquire the stream. Resolves to a `SourceReader` that owns any underlying resources. */
+    open(): Promise<SourceReader>;
+}
+export interface FactoryOptions {
+    /** Override the factory's default chunk size. Must be a non-zero multiple of 64. */
+    chunkBytes?: number;
+}
+export interface HttpRangeOptions extends FactoryOptions {
+    /** Merged into every request (headers, credentials, signal, etc.). */
+    init?: RequestInit;
+}
+export declare function fromBuffer(buf: Uint8Array | ArrayBuffer, options?: FactoryOptions): Source;
+export declare function fromFile(path: string, options?: FactoryOptions): Source;
+export declare function fromHttpRange(url: string, options?: HttpRangeOptions): Source;

package/dist/sources.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fromBuffer = fromBuffer;
+exports.fromFile = fromFile;
+exports.fromHttpRange = fromHttpRange;
+const promises_1 = require("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) {
+    const view = buf instanceof Uint8Array ? buf : new Uint8Array(buf);
+    const chunkBytes = options?.chunkBytes ?? DEFAULT_BUFFER_CHUNK_BYTES;
+    return {
+        open: () => Promise.resolve({
+            size: view.byteLength,
+            chunkBytes,
+            read: async (offset, dst) => {
+                const end = Math.min(offset + dst.byteLength, view.byteLength);
+                const n = Math.max(0, end - offset);
+                if (n > 0)
+                    dst.set(view.subarray(offset, end));
+                return n;
+            },
+        }),
+    };
+}
+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 stat = await handle.stat();
+            let closed = false;
+            return {
+                size: stat.size,
+                chunkBytes,
+                read: async (offset, dst) => {
+                    const { bytesRead } = await handle.read(dst, 0, dst.byteLength, offset);
+                    return bytesRead;
+                },
+                close: async () => {
+                    if (closed)
+                        return;
+                    closed = true;
+                    await handle.close();
+                },
+            };
+        },
+    };
+}
+function fromHttpRange(url, options) {
+    const init = options?.init;
+    const chunkBytes = options?.chunkBytes ?? DEFAULT_URL_CHUNK_BYTES;
+    return {
+        open: async () => {
+            const controller = new AbortController();
+            const userSignal = init?.signal;
+            if (userSignal) {
+                if (userSignal.aborted) {
+                    controller.abort(userSignal.reason);
+                }
+                else {
+                    userSignal.addEventListener('abort', () => controller.abort(userSignal.reason), { once: true });
+                }
+            }
+            const head = await fetch(url, { ...init, method: 'HEAD', signal: controller.signal });
+            if (!head.ok) {
+                throw new Error(`HEAD ${url} failed: ${head.status} ${head.statusText}`);
+            }
+            const sizeHeader = head.headers.get('content-length');
+            const size = sizeHeader === null ? NaN : Number.parseInt(sizeHeader, 10);
+            if (!Number.isFinite(size) || size < 0) {
+                throw new Error(`HEAD ${url} returned no valid Content-Length`);
+            }
+            const acceptsRanges = (head.headers.get('accept-ranges') ?? '').toLowerCase().includes('bytes');
+            if (!acceptsRanges) {
+                throw new Error(`HEAD ${url} does not advertise Accept-Ranges: bytes`);
+            }
+            let closed = false;
+            return {
+                size,
+                chunkBytes,
+                read: async (offset, dst) => {
+                    // HTTP ranges are inclusive on both ends.
+                    const end = Math.min(offset + dst.byteLength, size) - 1;
+                    const headers = new Headers(init?.headers);
+                    headers.set('Range', `bytes=${offset}-${end}`);
+                    const res = await fetch(url, { ...init, headers, method: 'GET', signal: controller.signal });
+                    if (res.status === 206) {
+                        const body = new Uint8Array(await res.arrayBuffer());
+                        dst.set(body);
+                        return body.byteLength;
+                    }
+                    // A 200 means the server ignored our Range request and returned the full
+                    // body. We throw here since the point of using ranges is to not have to
+                    // buffer the whole thing in memory.
+                    if (res.status === 200) {
+                        throw new Error(`Range GET ${url} (bytes=${offset}-${end}) ignored Range and returned 200.`);
+                    }
+                    throw new Error(`Range GET ${url} (bytes=${offset}-${end}) failed: ${res.status}`);
+                },
+                close: async () => {
+                    if (closed)
+                        return;
+                    closed = true;
+                    controller.abort();
+                },
+            };
+        },
+    };
+}

package/dist/validate.d.ts

@@ -0,0 +1,8 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+export type { StandardSchemaV1 };
+export declare class ValidationError extends Error {
+    readonly issues: readonly StandardSchemaV1.Issue[];
+    readonly pointer: string;
+    constructor(issues: readonly StandardSchemaV1.Issue[], pointer: string);
+}
+export declare function runStandardSchema<O>(schema: StandardSchemaV1<unknown, O>, value: unknown, pointer: string): Promise<O>;

package/dist/validate.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValidationError = void 0;
+exports.runStandardSchema = runStandardSchema;
+class ValidationError extends Error {
+    issues;
+    pointer;
+    constructor(issues, pointer) {
+        super(`bote: schema validation failed at ${pointer || '/'}: ${issues[0]?.message ?? 'unknown'}`);
+        this.name = 'ValidationError';
+        this.issues = issues;
+        this.pointer = pointer;
+    }
+}
+exports.ValidationError = ValidationError;
+async function runStandardSchema(schema, value, pointer) {
+    const result = await schema['~standard'].validate(value);
+    if (result.issues)
+        throw new ValidationError(result.issues, pointer);
+    return result.value;
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@botejs/core",
+  "version": "0.1.2",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jankdc/bote.git",
+    "directory": "packages/bote"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">= 18.17.0 < 19 || >= 20.3.0 < 21 || >= 21.1.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "build:debug": "tsc --sourceMap",
+    "test": "node --test --experimental-strip-types --no-warnings=ExperimentalWarning __test__/*.spec.ts",
+    "lint": "oxlint src",
+    "prepublishOnly": "tsc"
+  },
+  "dependencies": {
+    "@botejs/native": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "oxlint": "^1.14.0",
+    "typescript": "^6.0.0"
+  },
+  "optionalDependencies": {
+    "@standard-schema/spec": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@standard-schema/spec": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@standard-schema/spec": {
+      "optional": true
+    }
+  }
+}