@jarenjs/josl 0.34.0

package/dist/types/csv-stream.d.ts

@@ -0,0 +1,102 @@
+import { stringifyCsvChunks, formatCsvValue } from './csv.js';
+/**
+ * Create an incremental CSV reader.
+ *
+ * Events, in document order:
+ *   {type:'header', fields, line}                  - column names resolved
+ *   {type:'row',    index, values, record, line}   - a record completed
+ *   {type:'repair', code, message, line, column}   - damage healed
+ *
+ * @param {object} [options] - Reader options; see `parseCsv`
+ * @returns {{feed(chunk: string): void, end(): Array, rows(): Array,
+ *  fields(): string[]|null, repairs(): object[]}} The reader: `feed`
+ *  accepts chunks that may split any field, `end` flushes the pending
+ *  record and returns every row, and the rest peek at partial results.
+ * @example
+ * const reader = createCsvStreamReader({ headers: true, onEvent: console.log });
+ * reader.feed('a,b\n1,');
+ * reader.feed('2\n');
+ * reader.end(); // [{ a: '1', b: '2' }]
+ */
+export declare function createCsvStreamReader(options?: object): {
+    feed(chunk: string): void;
+    end(): any[];
+    rows(): any[];
+    fields(): string[] | null;
+    repairs(): object[];
+};
+/**
+ * Read an async iterable of string chunks (a fetch body, a file stream,
+ * an LLM response) into records.
+ * @param {AsyncIterable<string>|Iterable<string>} chunks - Source chunks
+ * @param {object} [options] - Reader options; see `parseCsv`
+ * @returns {Promise<Array>} Every record
+ */
+export declare function parseCsvStream(chunks: AsyncIterable<string> | Iterable<string>, options?: object): Promise<any[]>;
+/**
+ * Yield records as they complete, without ever holding the whole table.
+ *
+ * This is the reason to stream: `parseCsvStream` still accumulates every
+ * row, so a file larger than memory needs a reader that hands each record
+ * over and forgets it. Rows are dropped from the machine as they are
+ * yielded, so memory stays flat in the number of records.
+ * @param {AsyncIterable<string>|Iterable<string>} chunks - Source chunks
+ * @param {object} [options] - Reader options; see `parseCsv`
+ * @yields {Array|object} One record at a time
+ * @example
+ * for await (const row of iterateCsvStream(response.body, { headers: true }))
+ *   await save(row);
+ */
+export declare function iterateCsvStream(chunks: AsyncIterable<string> | Iterable<string>, options?: object): AsyncGenerator<any, void, unknown>;
+/**
+ * An incremental CSV writer: rows in, chunks out.
+ */
+export declare class CsvStreamWriter {
+    #private;
+    options: object;
+    chunks: any[];
+    onChunk: any;
+    fields: any;
+    wroteHeader: boolean;
+    /**
+     * @param {object} [options] - Writer options; see `stringifyCsv`
+     */
+    constructor(options?: object);
+    /**
+     * Write one record.
+     * @param {Array|object} row - An array, or an object keyed by column
+     * @returns {this} The writer, for chaining
+     */
+    write(row: any[] | object): this;
+    /**
+     * Write many records.
+     * @param {Iterable<Array|object>} rows - Records
+     * @returns {this} The writer, for chaining
+     */
+    writeAll(rows: Iterable<any[] | object>): this;
+    /**
+     * Concatenate the buffered chunks; empty when an `onChunk` sink is set.
+     * @returns {string} The document so far
+     */
+    toString(): string;
+    /**
+     * Finish writing.
+     * @returns {string} The complete document, or `''` with an `onChunk` sink
+     */
+    end(): string;
+}
+/**
+ * Create an incremental CSV writer.
+ * @param {object} [options] - Writer options; see `stringifyCsv`
+ * @param {(chunk: string) => void} [options.onChunk] - Chunk sink; without
+ *  one, chunks buffer until `end()`
+ * @returns {CsvStreamWriter} The writer
+ * @example
+ * const w = createCsvStreamWriter();
+ * w.write({ a: 1, b: 2 }).write({ a: 3, b: 4 });
+ * w.end(); // 'a,b\r\n1,2\r\n3,4\r\n'
+ */
+export declare function createCsvStreamWriter(options?: {
+    onChunk?: (chunk: string) => void;
+}): CsvStreamWriter;
+export { stringifyCsvChunks, formatCsvValue };

package/dist/types/csv.d.ts

@@ -0,0 +1,141 @@
+import { CSV_CODES, coerceCsvValue } from './csv-machine.js';
+import { CsvSyntaxError } from './errors.js';
+/**
+ * Parse a complete CSV document.
+ *
+ * Default is **strict**: anything RFC 4180 does not allow throws a
+ * `CsvSyntaxError` carrying a `CSV1xxx` code, a line and a column.
+ * `repair: true` instead takes the reading that loses the least data,
+ * records it, and carries on — see `parseCsvDocument` for the log.
+ *
+ * @param {string} text - CSV source text
+ * @param {object} [options] - Reader options
+ * @param {string} [options.delimiter=','] - Field separator, one character
+ * @param {string|null} [options.quote='"'] - Quote character; `null` disables quoting
+ * @param {string|null} [options.comment] - Lines starting with it are skipped
+ * @param {boolean|string[]} [options.headers=false] - `true` reads the first
+ *  record as column names, an array supplies them; either way records become
+ *  objects. `false` yields arrays, which allocate less.
+ * @param {boolean} [options.repair=false] - Heal damage instead of throwing
+ * @param {boolean} [options.trim=false] - Trim spaces/tabs around unquoted fields
+ * @param {boolean} [options.typed=false] - Coerce numbers, bigints, booleans,
+ *  `null` and ISO dates; quoted cells always stay strings
+ * @param {boolean} [options.emptyAsNull=false] - Empty cells become `null`
+ * @param {boolean} [options.skipEmptyLines] - Drop blank lines (default: on
+ *  in repair mode, off otherwise)
+ * @param {(event: object) => void} [options.onEvent] - Document-order event sink
+ * @param {(repair: object) => void} [options.onRepair] - Repair sink
+ * @returns {Array<string[]|object>} The records
+ * @throws {CsvSyntaxError} On malformed input, unless `repair` is set
+ * @example
+ * parseCsv('a,b\n1,2');            // [['a','b'], ['1','2']]
+ * parseCsv('a,b\n1,2', { headers: true }); // [{ a: '1', b: '2' }]
+ */
+export declare function parseCsv(text: string, options?: {
+    delimiter?: string;
+    quote?: string | null;
+    comment?: string | null;
+    headers?: boolean | string[];
+    repair?: boolean;
+    trim?: boolean;
+    typed?: boolean;
+    emptyAsNull?: boolean;
+    skipEmptyLines?: boolean;
+    onEvent?: (event: object) => void;
+    onRepair?: (repair: object) => void;
+}): Array<string[] | object>;
+/**
+ * Parse a complete CSV document and report everything that was learned
+ * about it: the resolved dialect, the column names, the records, and the
+ * repair log. This is the form to use when the input is untrusted — it is
+ * the only way to see *what* had to be healed.
+ * @param {string} text - CSV source text
+ * @param {object} [options] - Reader options; see `parseCsv`. `delimiter:
+ *  'auto'` sniffs the dialect from the text first.
+ * @returns {{dialect: object, fields: string[]|null, rows: Array, repairs: object[]}}
+ *  The document
+ * @example
+ * const doc = parseCsvDocument('a;b\n1;2', { delimiter: 'auto', headers: true });
+ * doc.dialect.delimiter; // ';'
+ * doc.rows;              // [{ a: '1', b: '2' }]
+ */
+export declare function parseCsvDocument(text: string, options?: object): {
+    dialect: object;
+    fields: string[] | null;
+    rows: any[];
+    repairs: object[];
+};
+/**
+ * Guess a CSV document's dialect from its text.
+ *
+ * The delimiter is chosen by consistency: each candidate is parsed and
+ * scored by how often it produces the same field count, because a
+ * separator that is really a separator divides every record the same way
+ * and one that is not divides them arbitrarily. Ties go to the delimiter
+ * yielding more columns, since a spurious separator can only ever split
+ * fewer.
+ *
+ * Header detection asks whether the first record looks unlike the rest:
+ * if every cell in it is a non-numeric string while some column below is
+ * consistently numeric or date-like, that first record is naming columns
+ * rather than carrying data.
+ *
+ * @param {string} text - CSV source text (a prefix is enough)
+ * @param {object} [options] - Reader options that affect parsing (`quote`, `comment`)
+ * @returns {{delimiter: string, quote: string|null, headers: boolean, width: number, confidence: number}}
+ *  The guess, with `confidence` in 0..1
+ * @example
+ * sniffCsvDialect('a;b;c\n1;2;3'); // { delimiter: ';', headers: true, ... }
+ */
+export declare function sniffCsvDialect(text: string, options?: object): {
+    delimiter: string;
+    quote: string | null;
+    headers: boolean;
+    width: number;
+    confidence: number;
+};
+/**
+ * Render one value as CSV cell text. `null`/`undefined` become empty,
+ * bigints lose the `n` suffix JOSL uses (CSV has no type marks), and the
+ * JOSL date classes and `Date` render as ISO-8601.
+ * @param {*} value - The value
+ * @returns {string} Cell text, unquoted
+ */
+export declare function formatCsvValue(value: any): string;
+/**
+ * Serialize records to a CSV document.
+ *
+ * A field is quoted only when it has to be — when it contains the
+ * delimiter, a quote, a newline, or edge whitespace a lenient reader
+ * might trim. Everything else is written bare, which keeps the output
+ * both smaller and diff-friendly.
+ *
+ * @param {Array<Array|object>} rows - Records: arrays, or objects keyed by column
+ * @param {object} [options] - Writer options
+ * @param {string} [options.delimiter=','] - Field separator
+ * @param {string} [options.quote='"'] - Quote character
+ * @param {string} [options.newline='\r\n'] - Record terminator; RFC 4180 §2.1
+ *  specifies CRLF, which is also what spreadsheet software expects
+ * @param {string[]} [options.fields] - Column order; inferred from the first
+ *  object record when omitted
+ * @param {boolean} [options.header=true] - Emit a header row for object records
+ * @returns {string} The CSV document
+ * @example
+ * stringifyCsv([{ a: 1, b: 'x,y' }]); // 'a,b\r\n1,"x,y"\r\n'
+ */
+export declare function stringifyCsv(rows: Array<any[] | object>, options?: {
+    delimiter?: string;
+    quote?: string;
+    newline?: string;
+    fields?: string[];
+    header?: boolean;
+}): string;
+/**
+ * Serialize records as an iterable of chunks, one record at a time, so a
+ * large table never exists as a single string.
+ * @param {Iterable<Array|object>} rows - Records
+ * @param {object} [options] - Writer options; see `stringifyCsv`
+ * @yields {string} One record (or the header) at a time
+ */
+export declare function stringifyCsvChunks(rows: Iterable<any[] | object>, options?: object): Generator<string, void, unknown>;
+export { CsvSyntaxError, CSV_CODES, coerceCsvValue };

package/dist/types/errors.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Shared constructor body for the line/column syntax errors. The `name`
+ * is passed as a string literal because the bundle is minified and a
+ * mangled class name must not leak into `error.name`.
+ */
+declare class LineColumnSyntaxError extends SyntaxError {
+    line: number;
+    column: number;
+    hint: string | undefined;
+    /**
+     * @param {string} name - The public class name for `error.name`
+     * @param {string} message - What is wrong
+     * @param {number} line - 1-based physical line number
+     * @param {number} column - 1-based column number
+     * @param {string} [hint] - Repair suggestion for machine-repair loops
+     */
+    constructor(name: string, message: string, line: number, column: number, hint?: string);
+}
+/**
+ * Error thrown when JOSL / TOML source text violates the grammar or the
+ * table redefinition rules.
+ */
+export declare class JoslSyntaxError extends LineColumnSyntaxError {
+    /**
+     * @param {string} message - What is wrong
+     * @param {number} line - 1-based physical line number
+     * @param {number} column - 1-based column number
+     * @param {string} [hint] - Repair suggestion for machine-repair loops
+     */
+    constructor(message: string, line: number, column: number, hint?: string);
+}
+/**
+ * Error thrown when a value cannot be represented in the requested output
+ * mode (e.g. `null` or a RegExp in strict TOML mode, a scalar root).
+ */
+export declare class JoslStringifyError extends Error {
+    path: (string | number)[];
+    /**
+     * @param {string} message - What is wrong
+     * @param {(string|number)[]} [path] - Path of the offending value
+     */
+    constructor(message: string, path?: (string | number)[]);
+}
+/**
+ * Error thrown when CSV source text violates RFC 4180 in strict mode.
+ *
+ * Every condition this reports is also a *repairable* one: `repair: true`
+ * turns each into a logged repair instead of a throw, so the same `code`
+ * appears either as `error.code` here or as an entry in the reader's
+ * repair log. Carrying the code both ways is what lets a caller move
+ * between the two modes without re-learning the diagnosis.
+ */
+export declare class CsvSyntaxError extends SyntaxError {
+    code: string;
+    line: number;
+    column: number;
+    hint: string | undefined;
+    /**
+     * @param {string} code - Stable `CSV1xxx` diagnosis code
+     * @param {string} message - What is wrong
+     * @param {number} line - 1-based physical line number
+     * @param {number} column - 1-based column number
+     * @param {string} [hint] - Repair suggestion for machine-repair loops
+     */
+    constructor(code: string, message: string, line: number, column: number, hint?: string);
+}
+/**
+ * Error thrown when JSONX source text violates the grammar.
+ */
+export declare class JsonxSyntaxError extends LineColumnSyntaxError {
+    /**
+     * @param {string} message - What is wrong
+     * @param {number} line - 1-based physical line number
+     * @param {number} column - 1-based column number
+     * @param {string} [hint] - Repair suggestion for machine-repair loops
+     */
+    constructor(message: string, line: number, column: number, hint?: string);
+}
+export {};

package/dist/types/gbnf.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Build a GBNF grammar for raw JOSL or TOML text.
+ *
+ * The result is a complete grammar string with `root` as its entry rule,
+ * ready to hand to a llama.cpp-family sampler. It constrains syntax only —
+ * a document it accepts still has to go through `parseJosl` for the rules
+ * a context-free grammar cannot express (duplicate keys, table conflicts).
+ * @param {object} [options] - Grammar options
+ * @param {'josl'|'toml'} [options.mode] - 'toml' omits the JOSL-only value
+ *  forms (null, bigint, regexp) and the `[[]]` root-array header
+ * @returns {string} The GBNF grammar
+ */
+export declare function toGbnf(options?: {
+    mode?: 'josl' | 'toml';
+}): string;
+/**
+ * Build a GBNF grammar for strict TOML 1.0 text.
+ * @returns {string} The GBNF grammar
+ */
+export declare function tomlToGbnf(): string;

package/dist/types/index.d.ts

@@ -0,0 +1,12 @@
+export { parseJosl, parseToml } from './parse.js';
+export { parseJoslCst, parseTomlCst, JoslCstDocument } from './cst.js';
+export { createStreamReader, parseJoslStream } from './stream.js';
+export { stringifyJosl, stringifyToml, formatKey, formatKeyPath, formatValue, formatSection, } from './stringify.js';
+export { createStreamWriter, stringifyJoslChunks } from './write.js';
+export { toGbnf, tomlToGbnf } from './gbnf.js';
+export { parseJsonx, stringifyJsonx } from './jsonx.js';
+export { createJsonxStreamReader, parseJsonxStream } from './jsonx-stream.js';
+export { parseCsv, parseCsvDocument, stringifyCsv, stringifyCsvChunks, sniffCsvDialect, formatCsvValue, coerceCsvValue, CSV_CODES, } from './csv.js';
+export { createCsvStreamReader, parseCsvStream, iterateCsvStream, createCsvStreamWriter, CsvStreamWriter, } from './csv-stream.js';
+export { JoslSyntaxError, JoslStringifyError, JsonxSyntaxError, CsvSyntaxError } from './errors.js';
+export { LocalDate, LocalTime, LocalDateTime, isValidDateParts, isValidTimeParts, } from './values.js';

package/dist/types/jsonx-scalar.d.ts

@@ -0,0 +1,92 @@
+export type JsonxErrCallback = (pos: number, message: string, hint?: string) => never;
+export type JsonxCheckEndCallback = (pos: number) => void;
+/**
+ * @callback JsonxErrCallback
+ * @param {number} pos - Offset of the error in the source text
+ * @param {string} message - What is wrong
+ * @param {string} [hint] - Repair suggestion
+ * @returns {never} Must throw
+ */
+/**
+ * @callback JsonxCheckEndCallback
+ * @param {number} pos - Offset of the first character after the value
+ * @returns {void} Must throw when the character cannot follow a value
+ */
+/**
+ * Whether a char code may legally follow a completed JSON/JSONX value
+ * (whitespace, `,`, `]` or `}`).
+ * @param {number} c - The char code
+ * @returns {boolean}
+ */
+export declare function isValueEndCode(c: number): boolean;
+/**
+ * Decode one escape sequence.
+ * @param {string} text - Source text
+ * @param {number} pos - Offset of the backslash
+ * @param {JsonxErrCallback} err - Error reporter
+ * @returns {[string, number]} The decoded text and the offset after it
+ */
+export declare function decodeEscape(text: string, pos: number, err: JsonxErrCallback): [string, number];
+/**
+ * Decode a double-quoted string.
+ * @param {string} text - Source text
+ * @param {number} pos - Offset of the opening quote
+ * @param {JsonxErrCallback} err - Error reporter
+ * @returns {[string, number]} The value and the offset after the close quote
+ */
+export declare function decodeString(text: string, pos: number, err: JsonxErrCallback): [string, number];
+/**
+ * Decode the body of a string between two offsets, stopping at the closing
+ * quote (which it does not consume) or at `stop`. In `partial` mode it also
+ * stops before an escape that is not complete within the span, so a
+ * still-arriving string can be decoded as far as it is safe to.
+ * @param {string} text - Source text
+ * @param {number} from - Offset of the first body character
+ * @param {number} stop - Exclusive end offset
+ * @param {JsonxErrCallback} err - Error reporter
+ * @param {boolean} partial - Whether the span may end mid-escape
+ * @returns {[string, number]} The decoded text and the offset reached
+ */
+export declare function decodeStringSpan(text: string, from: number, stop: number, err: JsonxErrCallback, partial: boolean): [string, number];
+/**
+ * Try to match an RFC 3339 datetime token (date, time, local or offset
+ * date-time; `T`, `t` or a single space may separate date and time).
+ * @param {string} text - Source text
+ * @param {number} pos - Offset of the first digit
+ * @param {JsonxErrCallback} err - Error reporter
+ * @param {JsonxCheckEndCallback} checkEnd - Value-terminator check
+ * @returns {[*, number]|null} The value and end offset, or null if the
+ *  text at `pos` is not a datetime
+ */
+export declare function matchDateTime(text: string, pos: number, err: JsonxErrCallback, checkEnd: JsonxCheckEndCallback): [any, number] | null;
+/**
+ * Match a number token. Strict JSON follows RFC 8259; JSONX adds a
+ * leading `+`, `_` separators, an `n` bigint suffix, and auto-promotes
+ * unsafe integers to BigInt.
+ * @param {string} text - Source text
+ * @param {number} pos - Offset of the first sign or digit
+ * @param {'jsonx'|'json'} mode - Dialect
+ * @param {JsonxErrCallback} err - Error reporter
+ * @param {JsonxCheckEndCallback} checkEnd - Value-terminator check
+ * @returns {[number|bigint, number]} The value and end offset
+ */
+export declare function matchNumber(text: string, pos: number, mode: 'jsonx' | 'json', err: JsonxErrCallback, checkEnd: JsonxCheckEndCallback): [number | bigint, number];
+/**
+ * Match a word token (`true`, `false`, `null`, and in JSONX the
+ * optionally signed non-finite spellings `inf`/`Infinity`/`nan`/`NaN`).
+ * The caller performs the value-terminator check.
+ * @param {string} text - Source text
+ * @param {number} pos - Offset of the first sign or letter
+ * @param {'jsonx'|'json'} mode - Dialect
+ * @param {JsonxErrCallback} err - Error reporter
+ * @returns {[boolean|null|number, number]} The value and end offset
+ */
+export declare function matchWord(text: string, pos: number, mode: 'jsonx' | 'json', err: JsonxErrCallback): [boolean | null | number, number];
+/**
+ * Match a regexp literal. The caller performs the value-terminator check.
+ * @param {string} text - Source text
+ * @param {number} pos - Offset of the opening slash
+ * @param {JsonxErrCallback} err - Error reporter
+ * @returns {[RegExp, number]} The value and end offset
+ */
+export declare function matchRegExp(text: string, pos: number, err: JsonxErrCallback): [RegExp, number];

package/dist/types/jsonx-stream.d.ts

@@ -0,0 +1,163 @@
+export declare class JsonxMachine {
+    mode: string;
+    onEvent: ((event: JsonxStreamEvent) => void) | null;
+    partialText: boolean;
+    detach: (string | number)[] | null;
+    partialFrom: number;
+    partialHold: string;
+    buf: string;
+    pos: number;
+    state: number;
+    stack: any[];
+    path: any[];
+    rootValue: any;
+    ended: boolean;
+    curLine: number;
+    lineStart: number;
+    scanPos: number;
+    scanInFlags: boolean;
+    scanInClass: boolean;
+    scanDtSpace: boolean;
+    errCb: (pos: any, message: any, hint: any) => void;
+    endCb: (pos: any) => void;
+    /**
+     * @param {object} [options] - Reader options
+     * @param {'jsonx'|'json'} [options.mode] - 'json' rejects every JSONX
+     *  extension (bigint, regexp, datetime, non-finite, separators, +)
+     * @param {(event: JsonxStreamEvent) => void} [options.onEvent] - Event sink
+     * @param {boolean} [options.partialText] - Also emit `text-partial`
+     *  deltas while a string value is still arriving
+     * @param {(string|number)[]} [options.detach] - Path pattern whose
+     *  matching values are NOT retained in the root (see `detachPattern`)
+     */
+    constructor(options?: {
+        mode?: 'jsonx' | 'json';
+        onEvent?: (event: JsonxStreamEvent) => void;
+        partialText?: boolean;
+        detach?: (string | number)[];
+    });
+    /**
+     * Feed the next chunk of source text; chunks may split any token.
+     * @param {string} chunk - Next piece of the document
+     * @returns {this} The machine, for chaining
+     */
+    feed(chunk: string): this;
+    /**
+     * Finish the document, flushing any pending token.
+     * @returns {*} The completed root value
+     * @throws {JsonxSyntaxError} When the document is incomplete or invalid
+     */
+    end(): any;
+    /**
+     * The (possibly still growing) root value. Undefined until the root
+     * value has started; container members appear as they complete.
+     *
+     * Under `detach`, matching values were never linked in — the root is
+     * the document's *frame* (its header members, and an empty array where
+     * the detached records would have been), which is the whole point.
+     * @returns {*} Current root value
+     */
+    root(): any;
+    errAt(pos: any, message: any, hint: any): void;
+    endError(): void;
+    pump(): void;
+    compact(): void;
+    parseValueAt(buf: any, pos: any, c: any): any;
+    decodeScalarToken(buf: any, pos: any, c: any): number;
+    checkValueEnd(buf: any, pos: any): void;
+    emitPartialText(buf: any, pos: any, stop: any, open: any): void;
+    valuePath(): any[];
+    /**
+     * Whether `this.path` plus one more segment matches the detach
+     * pattern. Spelled out rather than built on `valuePath()` so the
+     * common case — a document read with no `detach` at all — costs one
+     * null check, and the matching case costs no array allocation.
+     */
+    detaches(last: any): boolean;
+    completeScalar(value: any): void;
+    openContainer(isArray: any): void;
+    closeContainer(): void;
+    scanString(buf: any, pos: any): any;
+    scanRegExp(buf: any, pos: any): any;
+    scanScalar(buf: any, pos: any): any;
+}
+export type JsonxStreamPath = (string | number)[];
+export type JsonxStreamEvent = ({
+    type: 'object-start' | 'array-start';
+    path: JsonxStreamPath;
+    line: number;
+} | {
+    type: 'object-end' | 'array-end';
+    path: JsonxStreamPath;
+    value: any;
+    line: number;
+} | {
+    type: 'pair';
+    path: JsonxStreamPath;
+    key: string;
+    value: any;
+    line: number;
+} | {
+    type: 'item';
+    path: JsonxStreamPath;
+    index: number;
+    value: any;
+    line: number;
+} | {
+    type: 'text-partial';
+    path: JsonxStreamPath;
+    text: string;
+    line: number;
+});
+/**
+ * Absolute document path: strings for object keys, numbers for array
+ * indices (JSON-Pointer-able).
+ * @typedef {(string|number)[]} JsonxStreamPath
+ */
+/**
+ * Document-order reader event; see the module doc comment for semantics.
+ * @typedef {(
+ *   {type: 'object-start'|'array-start', path: JsonxStreamPath, line: number}
+ * | {type: 'object-end'|'array-end', path: JsonxStreamPath, value: *, line: number}
+ * | {type: 'pair', path: JsonxStreamPath, key: string, value: *, line: number}
+ * | {type: 'item', path: JsonxStreamPath, index: number, value: *, line: number}
+ * | {type: 'text-partial', path: JsonxStreamPath, text: string, line: number}
+ * )} JsonxStreamEvent
+ */
+/**
+ * Create an incremental JSONX / strict-JSON reader.
+ * @param {object} [options] - Reader options
+ * @param {'jsonx'|'json'} [options.mode] - 'json' rejects every JSONX
+ *  extension and matches `JSON.parse` for accepted documents
+ * @param {(event: JsonxStreamEvent) => void} [options.onEvent] - Event sink
+ * @param {boolean} [options.partialText] - Also emit `text-partial` deltas
+ *  while a string value is still arriving, for progressive display
+ * @param {(string|number)[]} [options.detach] - Path pattern (segments,
+ *  or `'*'` for any one segment) whose matching values are never linked
+ *  into the tree. Their completion events still carry them, so the
+ *  consumer sees every record and the reader retains none — this is what
+ *  makes a document larger than memory readable.
+ * @returns {{feed(chunk: string): void, end(): *, root(): *}} The reader:
+ *  `feed` accepts chunks that may split any token, `end` flushes,
+ *  validates completeness and returns the root, `root` peeks at the
+ *  partial result.
+ * @throws {TypeError} On a malformed `detach` pattern
+ */
+export declare function createJsonxStreamReader(options?: {
+    mode?: 'jsonx' | 'json';
+    onEvent?: (event: JsonxStreamEvent) => void;
+    partialText?: boolean;
+    detach?: (string | number)[];
+}): {
+    feed(chunk: string): void;
+    end(): any;
+    root(): any;
+};
+/**
+ * Parse an async iterable of string chunks (e.g. an LLM output stream).
+ * @param {AsyncIterable<string>|Iterable<string>} chunks - Source chunks
+ * @param {object} [options] - Reader options; see `createJsonxStreamReader`
+ * @returns {Promise<*>} The completed root value
+ */
+export declare function parseJsonxStream(chunks: AsyncIterable<string> | Iterable<string>, options?: object): Promise<any>;
+export { JsonxSyntaxError } from './errors.js';

package/dist/types/jsonx.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Parse JSONX (or, with `mode: 'json'`, strict JSON) text.
+ * @param {string} text - Source text
+ * @param {object} [options] - Parser options
+ * @param {'jsonx'|'json'} [options.mode] - 'json' matches JSON.parse
+ * @param {(event: object) => void} [options.onEvent] - Document-order
+ *  event sink: {type:'open', path, kind}, {type:'value', path, value},
+ *  {type:'close', path, value} — paths are absolute (JSON-Pointer-able)
+ * @returns {*} The parsed value
+ * @throws {JsonxSyntaxError} On invalid input
+ */
+export declare function parseJsonx(text: string, options?: {
+    mode?: 'jsonx' | 'json';
+    onEvent?: (event: object) => void;
+}): any;
+/**
+ * Serialize a value to JSONX text. With `mode: 'json'` this delegates to
+ * `JSON.stringify` for exact backward compatibility (bigints throw, dates
+ * become quoted strings, non-finite numbers become null, ...).
+ * @param {*} value - The value to serialize
+ * @param {object} [options] - Writer options
+ * @param {'jsonx'|'json'} [options.mode] - Output dialect
+ * @param {number|string} [options.indent] - Pretty-print indentation
+ * @returns {string|undefined} The text, or undefined for undefined input
+ */
+export declare function stringifyJsonx(value: any, options?: {
+    mode?: 'jsonx' | 'json';
+    indent?: number | string;
+}): string | undefined;
+export { JsonxSyntaxError } from './errors.js';
+export { LocalDate, LocalTime, LocalDateTime } from './values.js';