@jarenjs/josl 0.34.0

package/dist/types/machine.d.ts

@@ -0,0 +1,97 @@
+export declare class JoslMachine {
+    mode: string;
+    onEvent: ((event: object) => void) | null;
+    onLine: any;
+    lineValueStart: number;
+    lineValueEnd: number;
+    buf: string;
+    scanPos: number;
+    scanState: number;
+    scanDepth: number;
+    scanNl: number;
+    startLine: number;
+    lineOrigin: number;
+    started: boolean;
+    ended: boolean;
+    rootValue: {} | undefined;
+    rootIsArray: boolean;
+    current: any;
+    currentPath: any[];
+    meta: WeakMap<WeakKey, any>;
+    line: string;
+    /**
+     * @param {object} [options] - Reader options
+     * @param {'josl'|'toml'} [options.mode] - 'toml' rejects JOSL extensions
+     * @param {(event: object) => void} [options.onEvent] - Document-order
+     *  event sink: {type:'table'|'table-array'|'root-item'|'pair', path, ...}
+     */
+    constructor(options?: {
+        mode?: 'josl' | 'toml';
+        onEvent?: (event: object) => void;
+    });
+    /**
+     * 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 logical line.
+     * @returns {*} The completed root value
+     */
+    end(): any;
+    /**
+     * Parse a complete document in one pass. Every value parser already stops
+     * at the newlines TOML forbids a construct from crossing, so with the
+     * whole text in hand the parser finds each logical line's end itself and
+     * the cutter's separate pass over the source is not needed. `feed`/`end`
+     * keep the cutter because a chunk can stop mid-token, where only a
+     * side-effect-free pre-pass can decide whether a line is complete.
+     * @param {string} text - The entire document
+     * @returns {*} The completed root value
+     */
+    parseAll(text: string): any;
+    /**
+     * The (possibly still growing) root value: `{}`-rooted for documents,
+     * `[]`-rooted after a `[[]]` header. Undefined content yields `{}`.
+     * @returns {*} Current root value
+     */
+    root(): any;
+    scan(): void;
+    cutLine(buf: any, start: any, nlPos: any, innerNl: any): void;
+    err(pos: any, message: any, hint: any): void;
+    emit(event: any): void;
+    parseLine(line: any, pos?: number): any;
+    skipWs(line: any, pos: any): any;
+    skipWsNlComment(line: any, pos: any): any;
+    expectLineEnd(line: any, pos: any): any;
+    checkComment(line: any, pos: any): any;
+    parseHeader(line: any, pos: any): any;
+    headerBase(): any[];
+    navigate(keys: any, pos: any): any[];
+    openTable(keys: any, pos: any): void;
+    openArrayTable(keys: any, pos: any): void;
+    openRootItem(pos: any): void;
+    parsePair(line: any, pos: any): any;
+    assignPair(keys: any, value: any, pos: any): void;
+    parseKeys(line: any, pos: any): any[];
+    parseValue(line: any, pos: any): any;
+    checkValueEnd(line: any, pos: any): any;
+    parseWord(line: any, pos: any): any[] | undefined;
+    parseSignedWord(line: any, pos: any): any[] | undefined;
+    decodeEscape(line: any, pos: any): any[] | undefined;
+    decodeUnicodeEscape(line: any, pos: any, width: any): any[];
+    checkStringChar(line: any, pos: any, multiline: any): void;
+    parseBasicString(line: any, pos: any): any[] | undefined;
+    parseLiteralString(line: any, pos: any): any[] | undefined;
+    parseMlBasicString(line: any, pos: any): any[] | undefined;
+    parseMlLiteralString(line: any, pos: any): any[] | undefined;
+    parseArray(line: any, pos: any): any;
+    parseInlineTable(line: any, pos: any): any[];
+    assignInline(obj: any, keys: any, value: any, pos: any): void;
+    parseRegExp(line: any, pos: any): any[] | undefined;
+    parseDateTimeOrNumber(line: any, pos: any): any[];
+    bigIntCheck(pos: any, suffix: any): boolean;
+    intValue(pos: any, source: any, big: any, m0: any): number | bigint;
+    parseNumber(line: any, pos: any): any[];
+}

package/dist/types/parse.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Parse a complete JOSL document.
+ * @param {string} text - JOSL source text
+ * @param {object} [options] - Reader options
+ * @param {'josl'|'toml'} [options.mode] - 'toml' rejects JOSL extensions
+ *  (null, bigint, regexp literals, root arrays) for strict TOML 1.0 input
+ * @param {(event: object) => void} [options.onEvent] - Document-order
+ *  event sink; see `createStreamReader`
+ * @returns {object|Array} The root table, or root array for [[]] documents
+ * @throws {import('./errors.js').JoslSyntaxError} On invalid input
+ */
+export declare function parseJosl(text: string, options?: {
+    mode?: 'josl' | 'toml';
+    onEvent?: (event: object) => void;
+}): object | any[];
+/**
+ * Parse a complete document in strict TOML 1.0 mode.
+ * @param {string} text - TOML source text
+ * @param {object} [options] - Reader options minus `mode`
+ * @returns {object} The root table
+ */
+export declare function parseToml(text: string, options?: object): object;
+export { JoslSyntaxError } from './errors.js';
+export { LocalDate, LocalTime, LocalDateTime } from './values.js';

package/dist/types/stream.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Create an incremental JOSL/TOML reader.
+ *
+ * Events, in document order:
+ *   {type:'table',       path, line}          - a [header] opened
+ *   {type:'table-array', path, line}          - a [[header]] appended
+ *   {type:'root-item',   path, index, line}   - a [[]] element started
+ *   {type:'pair',        path, key, value, line} - a key-value completed
+ *
+ * @param {object} [options] - Reader options
+ * @param {'josl'|'toml'} [options.mode] - 'toml' rejects JOSL extensions
+ * @param {(event: object) => void} [options.onEvent] - Event sink
+ * @returns {{feed(chunk: string): void, end(): *, root(): *}} The reader:
+ *  `feed` accepts chunks that may split any token, `end` flushes and
+ *  returns the completed root, `root` peeks at the partial result.
+ */
+export declare function createStreamReader(options?: {
+    mode?: 'josl' | 'toml';
+    onEvent?: (event: object) => void;
+}): {
+    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 `createStreamReader`
+ * @returns {Promise<*>} The completed root value
+ */
+export declare function parseJoslStream(chunks: AsyncIterable<string> | Iterable<string>, options?: object): Promise<any>;
+export { JoslSyntaxError } from './errors.js';

package/dist/types/stringify.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Whether a value serializes as a table (a plain object).
+ * @param {*} v - The value
+ * @returns {boolean} True for plain objects
+ */
+export declare function isPlainTable(v: any): boolean;
+/**
+ * Format a single key (bare when possible, quoted otherwise).
+ * @param {string} key - The key
+ * @returns {string} JOSL/TOML key text
+ */
+export declare function formatKey(key: string): string;
+/**
+ * Format a dotted key path.
+ * @param {string[]} path - Key path segments
+ * @returns {string} Dotted key path text
+ */
+export declare function formatKeyPath(path: string[]): string;
+/**
+ * Format a single value (scalars, inline arrays, inline tables).
+ * @param {*} value - The value
+ * @param {object} [options] - Writer options; see `stringifyJosl`
+ * @param {(string|number)[]} [path] - Error-reporting path
+ * @returns {string} JOSL/TOML value text
+ * @throws {JoslStringifyError} When the value cannot be represented
+ */
+export declare function formatValue(value: any, options?: object, path?: (string | number)[]): string;
+/**
+ * Format a table body: its pairs followed by nested `[header]` /
+ * `[[header]]` sections, with headers made relative to `headerPath`.
+ * @param {object} obj - A plain object table
+ * @param {object} [options] - Writer options; see `stringifyJosl`
+ * @param {string[]} [headerPath] - Prefix for nested section headers
+ * @returns {string} Section text (newline terminated, may be empty)
+ * @throws {JoslStringifyError} When a value cannot be represented
+ */
+export declare function formatSection(obj: object, options?: object, headerPath?: string[]): string;
+/**
+ * Serialize a value to JOSL (or strict TOML) text.
+ * @param {object|Array} value - A plain object root, or (JOSL mode only)
+ *  an array of plain objects for a [[]] root-array document
+ * @param {object} [options] - Writer options
+ * @param {'josl'|'toml'} [options.mode] - 'toml' emits strict TOML 1.0
+ * @param {'error'|'omit'} [options.onNull] - TOML mode: what to do with
+ *  null table values (array elements always error)
+ * @param {'error'|'string'} [options.onRegExp] - TOML mode: represent
+ *  regexps as strings, or error
+ * @returns {string} The serialized document, newline terminated
+ * @throws {JoslStringifyError} When the value cannot be represented
+ */
+export declare function stringifyJosl(value: object | any[], options?: {
+    mode?: 'josl' | 'toml';
+    onNull?: 'error' | 'omit';
+    onRegExp?: 'error' | 'string';
+}): string;
+/**
+ * Serialize a value to strict TOML 1.0 text.
+ * @param {object} value - A plain object root
+ * @param {object} [options] - Writer options minus `mode`
+ * @returns {string} The serialized document
+ */
+export declare function stringifyToml(value: object, options?: object): string;
+export { JoslStringifyError } from './errors.js';

package/dist/types/util.d.ts

@@ -0,0 +1,56 @@
+/** `YYYY-MM-DD` with an optional time half. @type {RegExp} */
+export declare const RE_DATETIME: RegExp;
+/** A bare `HH:MM:SS` with an optional fraction. @type {RegExp} */
+export declare const RE_TIMEONLY: RegExp;
+/**
+ * Run a sticky regex at `pos` and return its match (or null).
+ * @param {RegExp} re - A sticky (`y`) pattern
+ * @param {string} text - The text to match against
+ * @param {number} pos - Position the match must start at
+ * @returns {RegExpExecArray | null} The match, anchored at `pos`
+ */
+export declare function stickyExec(re: RegExp, text: string, pos: number): RegExpExecArray | null;
+/**
+ * Shared `feed(chunk)` body for the buffering stream machines (JOSL and
+ * CSV): guard against feeding after `end()`, strip a leading BOM on the
+ * first non-empty chunk, then buffer and scan. The JSONX stream reader
+ * has its own `feed` on purpose - it pumps a token loop and models BOM
+ * handling differently.
+ * @template {{ ended: boolean, started: boolean, buf: string, scan: () => void }} T
+ * @param {T} machine - The stream machine (`this` of its `feed`)
+ * @param {string} chunk - Next piece of the document
+ * @returns {T} The machine, for chaining
+ */
+export declare function feedMachine<T extends {
+    ended: boolean;
+    started: boolean;
+    buf: string;
+    scan: () => void;
+}>(machine: T, chunk: string): T;
+/**
+ * Shared `parseAll(text)` prelude for the buffering stream machines:
+ * reject mixing with `feed()`/`end()`, mark the machine started and
+ * ended, and strip a leading BOM.
+ * @param {{ ended: boolean, started: boolean }} machine - The stream machine
+ * @param {string} text - The entire document
+ * @returns {string} The text with any leading BOM removed
+ */
+export declare function beginParseAll(machine: {
+    ended: boolean;
+    started: boolean;
+}, text: string): string;
+/**
+ * Read an own property, ignoring the prototype chain.
+ * @param {object} obj - Source object
+ * @param {string} key - Member name
+ * @returns {*} The own value or undefined
+ */
+export declare function getOwn(obj: object, key: string): any;
+/**
+ * Compute the 1-based column of `pos` inside `str` (columns restart after
+ * every newline; multi-line logical lines report positions within them).
+ * @param {string} str - Input text
+ * @param {number} pos - Offset into the text
+ * @returns {number} 1-based column number
+ */
+export declare function columnOf(str: string, pos: number): number;

package/dist/types/values.d.ts

@@ -0,0 +1,60 @@
+/**
+ * A TOML/JOSL local date (no time, no offset), e.g. `1979-05-27`.
+ */
+export declare class LocalDate {
+    year: number;
+    month: number;
+    day: number;
+    /**
+     * @param {number} year - Full year
+     * @param {number} month - 1-based month
+     * @param {number} day - 1-based day of month
+     */
+    constructor(year: number, month: number, day: number);
+    toString(): string;
+    toJSON(): string;
+}
+/**
+ * A TOML/JOSL local time (no date, no offset), e.g. `07:32:00.999`.
+ * The sub-second part is kept as the literal fraction string (including
+ * the leading dot, or `''`) so precision round-trips exactly.
+ */
+export declare class LocalTime {
+    hour: number;
+    minute: number;
+    second: number;
+    fraction: string;
+    /**
+     * @param {number} hour - 0-23
+     * @param {number} minute - 0-59
+     * @param {number} second - 0-60 (60 allows leap seconds)
+     * @param {string} [fraction] - Literal fraction incl. leading dot, or ''
+     */
+    constructor(hour: number, minute: number, second: number, fraction?: string);
+    toString(): string;
+    toJSON(): string;
+}
+/**
+ * A TOML/JOSL local date-time (no offset), e.g. `1979-05-27T07:32:00`.
+ */
+export declare class LocalDateTime {
+    date: LocalDate;
+    time: LocalTime;
+    /**
+     * @param {LocalDate} date - The date part
+     * @param {LocalTime} time - The time part
+     */
+    constructor(date: LocalDate, time: LocalTime);
+    toString(): string;
+    toJSON(): string;
+}
+export { isDateOnlyInRange as isValidDateParts } from '@jarenjs/core/dates';
+/**
+ * Whether hour/minute/second form a valid time-of-day (second 60 is
+ * accepted for leap seconds).
+ * @param {number} hour - Hours
+ * @param {number} minute - Minutes
+ * @param {number} second - Seconds
+ * @returns {boolean} True when in range
+ */
+export declare function isValidTimeParts(hour: number, minute: number, second: number): boolean;

package/dist/types/write.d.ts

@@ -0,0 +1,92 @@
+declare class JoslStreamWriter {
+    options: {
+        mode: string;
+        onNull: any;
+        onRegExp: any;
+    };
+    onChunk: any;
+    chunks: any[];
+    ended: boolean;
+    rootIsArray: boolean;
+    rootHasPairs: boolean;
+    sawSection: boolean;
+    sectionKeys: Set<any>;
+    headers: Set<any>;
+    headerScope: number;
+    constructor(options?: {});
+    emit(chunk: any): void;
+    guard(): void;
+    blank(): void;
+    toPath(path: any): any[];
+    openSection(keys: any, wrap: any): void;
+    /**
+     * Emit a key-value pair into the current section.
+     * @param {string|string[]} key - A key, or key segments for dotted keys
+     * @param {*} value - The value
+     * @returns {this} The writer, for chaining
+     */
+    pair(key: string | string[], value: any): this;
+    /**
+     * Open a `[table]` section.
+     * @param {string|string[]} path - Header path
+     * @returns {this} The writer, for chaining
+     */
+    table(path: string | string[]): this;
+    /**
+     * Append a `[[table-array]]` element.
+     * @param {string|string[]} path - Header path
+     * @returns {this} The writer, for chaining
+     */
+    tableArray(path: string | string[]): this;
+    /**
+     * Start a `[[]]` root-array element (JOSL mode only). With a record
+     * argument the whole table body is emitted at once - the natural
+     * unit for streaming one record per completed result.
+     * @param {object} [record] - Optional complete record to emit
+     * @returns {this} The writer, for chaining
+     */
+    rootItem(record?: object): this;
+    /**
+     * Emit a comment line (multi-line text becomes multiple comments).
+     * @param {string} text - Comment text
+     * @returns {this} The writer, for chaining
+     */
+    comment(text: string): this;
+    /**
+     * The document text emitted so far.
+     * @returns {string} Concatenated chunks
+     */
+    text(): string;
+    /**
+     * Finish the document.
+     * @returns {string} The complete document text
+     */
+    end(): string;
+}
+/**
+ * Create a streaming JOSL/TOML writer - the write-side mirror of
+ * `createStreamReader`. Chunks are delivered through `onChunk` as they
+ * are produced and also accumulate for `text()` / `end()`.
+ * @param {object} [options] - Writer options
+ * @param {'josl'|'toml'} [options.mode] - 'toml' emits strict TOML 1.0
+ * @param {'error'|'omit'} [options.onNull] - See `stringifyJosl`
+ * @param {'error'|'string'} [options.onRegExp] - See `stringifyJosl`
+ * @param {(chunk: string) => void} [options.onChunk] - Chunk sink
+ * @returns {JoslStreamWriter} The writer
+ */
+export declare function createStreamWriter(options?: {
+    mode?: 'josl' | 'toml';
+    onNull?: 'error' | 'omit';
+    onRegExp?: 'error' | 'string';
+    onChunk?: (chunk: string) => void;
+}): JoslStreamWriter;
+/**
+ * Serialize a value as an iterable of text chunks: one chunk per record
+ * for a root array, a single chunk for a table root. Useful for piping
+ * record streams onward without building the full string.
+ * @param {object|Array} value - Same roots as `stringifyJosl`
+ * @param {object} [options] - Writer options; see `stringifyJosl`
+ * @yields {string} Document chunks, in order
+ */
+export declare function stringifyJoslChunks(value: object | any[], options?: object): Generator<string, void, unknown>;
+export { JoslStringifyError } from './errors.js';

package/package.json

@@ -0,0 +1,104 @@
+{
+  "name": "@jarenjs/josl",
+  "private": false,
+  "version": "0.34.0",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./dist/types/index.d.ts",
+  "sideEffects": false,
+  "description": "JOSL - JavaScript Obvious Streaming Language. A TOML 1.0 backward-compatible data language with null, bigint, regexp, datetimes and root arrays as first class citizens, plus JSONX, the same extensions over JSON, and a self-healing CSV reader/writer - with incremental streaming readers for JOSL, TOML, JSONX, strict JSON and CSV.",
+  "author": "joham",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jklarenbeek/jarenjs.git",
+    "directory": "packages/josl"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "jaren",
+    "josl",
+    "toml",
+    "jsonx",
+    "json",
+    "csv",
+    "streaming",
+    "incremental",
+    "real-time",
+    "structured-output",
+    "parser",
+    "llm"
+  ],
+  "scripts": {
+    "build": "npm run build:types",
+    "build:types": "tsc -p tsconfig.json",
+    "prepack": "npm run build:types"
+  },
+  "files": [
+    "dist/types/",
+    "src/",
+    "schemas/",
+    "FORMAT.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./parse": {
+      "types": "./dist/types/parse.d.ts",
+      "default": "./src/parse.js"
+    },
+    "./cst": {
+      "types": "./dist/types/cst.d.ts",
+      "default": "./src/cst.js"
+    },
+    "./gbnf": {
+      "types": "./dist/types/gbnf.d.ts",
+      "default": "./src/gbnf.js"
+    },
+    "./stream": {
+      "types": "./dist/types/stream.d.ts",
+      "default": "./src/stream.js"
+    },
+    "./stringify": {
+      "types": "./dist/types/stringify.d.ts",
+      "default": "./src/stringify.js"
+    },
+    "./write": {
+      "types": "./dist/types/write.d.ts",
+      "default": "./src/write.js"
+    },
+    "./jsonx": {
+      "types": "./dist/types/jsonx.d.ts",
+      "default": "./src/jsonx.js"
+    },
+    "./jsonx-stream": {
+      "types": "./dist/types/jsonx-stream.d.ts",
+      "default": "./src/jsonx-stream.js"
+    },
+    "./csv": {
+      "types": "./dist/types/csv.d.ts",
+      "default": "./src/csv.js"
+    },
+    "./csv-stream": {
+      "types": "./dist/types/csv-stream.d.ts",
+      "default": "./src/csv-stream.js"
+    },
+    "./values": {
+      "types": "./dist/types/values.d.ts",
+      "default": "./src/values.js"
+    },
+    "./schemas/*": "./schemas/*",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@jarenjs/core": "^0.34.0"
+  }
+}

package/schemas/jaren-josl-data.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jarenjs.dev/schemas/jaren-josl-data/0.1",
+  "title": "JOSL document data model (JSON-safe subset)",
+  "description": "The JSON-safe data model of a JOSL document, for LLM structured output: a model emits JSON matching this schema and stringifyJosl renders canonical JOSL text (parseJosl round-trips it exactly). The subset is deliberate - JOSL's native date/time scalars parse to platform Date values, which JSON cannot carry; represent them as strings and parse downstream. The root is a table (object), exactly as in TOML.",
+  "type": "object",
+  "additionalProperties": { "$ref": "#/$defs/value" },
+  "$defs": {
+    "value": {
+      "description": "Any JSON-safe JOSL value: scalars, arrays, or nested tables.",
+      "anyOf": [
+        { "type": "string" },
+        { "type": "number" },
+        { "type": "boolean" },
+        { "type": "null" },
+        { "type": "array", "items": { "$ref": "#/$defs/value" } },
+        { "type": "object", "additionalProperties": { "$ref": "#/$defs/value" } }
+      ]
+    }
+  }
+}