@jarenjs/josl 0.56.0 → 0.66.1

package/FORMAT.md

@@ -136,9 +136,31 @@ visits leaves bottom-up, only after the full text has arrived, and never
 tells you where you are.
 
 The write side mirrors this: `createStreamWriter` emits text chunks
-event by event (`pair`, `table`, `tableArray`, `rootItem`), and
-`stringifyJoslChunks` streams an existing value one `[[]]` record at a
-time — byte-identical to `stringifyJosl` output.
+event by event (`pair`, `table`, `tableArray`, `rootItem`; `buffer:
+false` retains none of them), `stringifyJoslChunks` streams an existing
+value one `[[]]` record at a time, and `stringifyJoslStream` pulls
+records from an async source one per chunk — all byte-identical to
+`stringifyJosl` output. `iterateJoslStream` is the reading twin: a
+`[[]]` root array as a pull source of records, each detached from the
+root as the next header completes it; a table root is refused, being one
+retained value rather than a record stream.
+
+**Limits.** A reader refuses a document by size only when asked. Every
+limit defaults to `Infinity`, counts UTF-8 bytes, and is judged while
+the text is still in cutter, token or container state; a crossing is a
+`JoslLimitError` with a stable code — never a repair.
+
+| reader | option | code |
+| --- | --- | --- |
+| JOSL / TOML | `maxTotalBytes` | `JOSL2001` |
+| JOSL / TOML | `maxRecordBytes` — one logical line | `JOSL2002` |
+| JOSL / TOML | `maxTokenBytes` — a string or key as written, quotes included | `JOSL2003` |
+| JOSL / TOML | `maxDepth` — inline nesting and header path depth | `JOSL2004` |
+| JOSL / TOML | `maxRetainedValues` — values the root holds, starting over per detached `[[]]` item | `JOSL2005` |
+| JSONX / JSON (stream reader) | `maxTotalBytes` | `JSONX2001` |
+| JSONX / JSON (stream reader) | `maxTokenBytes` — a string, key, number or regexp as written | `JSONX2002` |
+| JSONX / JSON (stream reader) | `maxDepth` | `JSONX2003` |
+| JSONX / JSON (stream reader) | `maxRetainedValues` — linked values only; a detached subtree never counts | `JSONX2004` |
 
 ## JSONX
 
@@ -206,13 +228,28 @@ information that cannot be recovered downstream:
   did not carry it, `''` would claim it carried nothing.
 - `typed: true` promotes an integer beyond 2^53 to bigint rather than
   rounding, reads unambiguous ISO-8601 as the value classes above, and
-  leaves anything with a leading zero a string.
+  leaves numbers with a leading zero a string. Offset date-times use
+  the same instant conversion as JOSL, preserving four-digit years and
+  truncating precision beyond milliseconds; invalid offsets stay text.
 - A BOM is stripped without comment; it is an encoding mark, not data.
 
 **Writing** quotes a field only when it contains the delimiter, the quote
 character, a newline, or edge whitespace a lenient reader might trim. The
 default terminator is CRLF, per RFC 4180 §2.1 and what spreadsheet
-software expects.
+software expects. `stringifyCsv`, `stringifyCsvChunks`, the stream writer
+and the pull form `stringifyCsvStream` share one row formatter and are
+byte-identical for the same records; the pull form requests a record only
+when its consumer asks for the next line.
+
+**Limits.** Optional, `Infinity` by default, in UTF-8 bytes, judged before
+the text is kept; a crossing is a `JoslLimitError`, never a repair:
+
+| option | code |
+| --- | --- |
+| `maxTotalBytes` | `CSV2001` |
+| `maxRecordBytes` — one record, its terminator included | `CSV2002` |
+| `maxFieldBytes` — one field as written, quotes included | `CSV2003` |
+| `maxColumns` | `CSV2004` |
 
 ## Compliance notes
 

package/README.md

@@ -129,6 +129,49 @@ records went past. The pattern matches an exact path, not a prefix, so a
 feature's own rings are not separately detached: they belong to their
 feature and are freed with it.
 
+The JOSL twin is `iterateJoslStream`: a `[[]]` root array read as a pull
+source of records, each detached from the root the moment the next
+`[[]]` header (or the end) completes it, so the reader holds at most the
+record in progress. A table root is one retained value, not a record
+stream, and is refused by name.
+
+```js
+import { iterateJoslStream } from '@jarenjs/josl/stream';
+
+for await (const record of iterateJoslStream(response.body, { signal }))
+  await save(record);        // the source is closed exactly once on an abort or an early return
+```
+
+### Hostile input
+
+Every reader refuses a document by size only when asked: the limits
+default to `Infinity`, count **UTF-8 bytes** (never code units), and are
+checked while the offending text is still in cutter, token or container
+state — before a concatenation or a link could cross them. A crossing
+throws `JoslLimitError` with a stable code and the limit; it is never a
+repair, because a document that is too large is not damaged.
+
+| reader | option | code |
+| --- | --- | --- |
+| CSV | `maxTotalBytes` | `CSV2001` |
+| CSV | `maxRecordBytes` (one record, its terminator included) | `CSV2002` |
+| CSV | `maxFieldBytes` (one field as written, quotes included) | `CSV2003` |
+| CSV | `maxColumns` | `CSV2004` |
+| JOSL / TOML | `maxTotalBytes` | `JOSL2001` |
+| JOSL / TOML | `maxRecordBytes` (one logical line) | `JOSL2002` |
+| JOSL / TOML | `maxTokenBytes` (a string or key as written, quotes included) | `JOSL2003` |
+| JOSL / TOML | `maxDepth` (inline nesting, header path depth) | `JOSL2004` |
+| JOSL / TOML | `maxRetainedValues` (values the root holds; starts over per detached `[[]]` item) | `JOSL2005` |
+| JSONX / JSON stream | `maxTotalBytes` | `JSONX2001` |
+| JSONX / JSON stream | `maxTokenBytes` (a string, key, number or regexp as written) | `JSONX2002` |
+| JSONX / JSON stream | `maxDepth` | `JSONX2003` |
+| JSONX / JSON stream | `maxRetainedValues` (linked values only — a detached subtree is never counted) | `JSONX2004` |
+
+The CSV and JOSL limits guard the whole-document parsers too, which run
+the same machines; the JSONX limits are the stream reader's, which is
+where a document arrives a chunk at a time. `CSV_LIMIT_CODES`,
+`JOSL_LIMIT_CODES` and `JSONX_LIMIT_CODES` are the tables as data.
+
 Measured on a synthetic OpenStreetMap-shaped extract (`node --expose-gc
 benchmark/jsonx-stream.js`), reading 20 000 features of 40 vertices each:
 
@@ -212,23 +255,33 @@ The write-side mirror of the reader — build a document event by event and
 ship each chunk as it is produced:
 
 ```js
-import { createStreamWriter, stringifyJoslChunks } from '@jarenjs/josl/write';
+import { createStreamWriter, stringifyJoslChunks, stringifyJoslStream } from '@jarenjs/josl/write';
 
-const w = createStreamWriter({ onChunk: (c) => response.write(c) });
+const w = createStreamWriter({ onChunk: (c) => response.write(c), buffer: false });
 w.pair('title', 'run 42')
   .table('server')
   .pair('host', 'localhost');
 // root-array documents: w.rootItem(record) per completed record
-const text = w.end();
+w.end();                                     // '' — buffer: false retains nothing; the sink has it
 
 // or stream an existing value, one chunk per [[]] record:
 for (const chunk of stringifyJoslChunks(records))
   response.write(chunk);
+
+// or pull records from an async source — a database cursor — one per chunk:
+response.body = stringifyJoslStream(store.collection('rows').query(doc), { signal });
 ```
 
 The writer validates what the reader would reject (duplicate keys and
 headers, root table/array mixing, TOML downleveling) and shares its
 serialization with `stringifyJosl`, so both produce identical text.
+`stringifyJoslStream` is the pull form: the next record is requested only
+when the consumer asks for the next chunk, so a cursor behind it never
+runs ahead of the socket in front of it; its chunks are byte-identical to
+`stringifyJoslChunks` for the same records, and an abort (`signal`), a
+consumer that stops early or a throw closes the record source exactly
+once. `buffer: false` (with an `onChunk` sink) keeps the event writer from
+retaining a second copy of the document it streams.
 
 ## Editing a document (CST)
 
@@ -275,6 +328,30 @@ stringifyJsonx(v, { mode: 'json' });     // delegates to JSON.stringify
 
 ## Exports
 
+Every subpath a consumer can import, derived from the manifest by
+`npm run docs:derive` (`npm run docs:check` fails when the two drift):
+
+<!--fact:exports.josl-->
+| Import | Kind | Declarations |
+|---|---|---|
+| `@jarenjs/josl` | JavaScript | declared |
+| `@jarenjs/josl/parse` | JavaScript | declared |
+| `@jarenjs/josl/cst` | JavaScript | declared |
+| `@jarenjs/josl/gbnf` | JavaScript | declared |
+| `@jarenjs/josl/stream` | JavaScript | declared |
+| `@jarenjs/josl/stringify` | JavaScript | declared |
+| `@jarenjs/josl/write` | JavaScript | declared |
+| `@jarenjs/josl/jsonx` | JavaScript | declared |
+| `@jarenjs/josl/jsonx-stream` | JavaScript | declared |
+| `@jarenjs/josl/csv` | JavaScript | declared |
+| `@jarenjs/josl/csv-stream` | JavaScript | declared |
+| `@jarenjs/josl/values` | JavaScript | declared |
+| `@jarenjs/josl/schemas/jaren-josl-data.schema.json` | schema | — |
+| `@jarenjs/josl/package.json` | metadata | — |
+<!--/fact-->
+
+What each subpath carries:
+
 | Subpath | What |
 | --- | --- |
 | `@jarenjs/josl/parse` | `parseJosl`, `parseToml` |
@@ -304,10 +381,22 @@ parseCsv('a,b\n1,2');                     // [['a','b'], ['1','2']]
 parseCsv('a,b\n1,2', { headers: true });  // [{ a: '1', b: '2' }]
 
 // rows as they complete, without ever holding the table
-for await (const row of iterateCsvStream(response.body, { headers: true }))
+for await (const row of iterateCsvStream(response.body, { headers: true, signal }))
   await save(row);
+
+// and the other way: pull records from a cursor into CSV lines, header once
+response.body = stringifyCsvStream(store.collection('rows').query(doc), { signal });
 ```
 
+`stringifyCsvStream` is byte-identical to `stringifyCsvChunks` and
+`stringifyCsv` for the same records and pulls one record per line, so the
+source is never asked for a row the consumer has not asked for; `signal`
+aborts between pulls, and an abort, an early return or a throw closes the
+source exactly once. The reader's `signal` does the same for
+`iterateCsvStream`. The hostile-input limits (`maxTotalBytes`,
+`maxRecordBytes`, `maxFieldBytes`, `maxColumns`, the `CSV2xxx` codes) are
+listed under Streaming.
+
 **Strict by default.** Anything RFC 4180 forbids throws a
 `CsvSyntaxError` carrying a `CSV1xxx` code, a line and a column — the
 same machine-repairable error shape the JOSL parser uses.

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

@@ -39,6 +39,12 @@ export declare class CsvMachine {
     skipEmptyLines: boolean;
     onEvent: any;
     onRepair: any;
+    maxTotalBytes: number;
+    maxRecordBytes: number;
+    maxFieldBytes: number;
+    maxColumns: number;
+    limited: boolean;
+    totalBytes: number;
     wantHeader: boolean;
     headerFields: any;
     objectRows: boolean;
@@ -69,6 +75,8 @@ export declare class CsvMachine {
      * @returns {this} The machine, for chaining
      */
     feed(chunk: string): this;
+    count(text: any): void;
+    endsRecordWithin(text: any): boolean;
     /**
      * Finish the document, flushing any pending record.
      * @returns {Array} The completed rows
@@ -94,6 +102,7 @@ export declare class CsvMachine {
     scan(): void;
     compact(start: any): void;
     readSpan(text: any, pos: any, end: any): any;
+    admitCell(cells: any, text: any, start: any, stop: any): void;
     parseRecord(text: any, pos: any, end: any, cells: any): any;
     parsePlain(text: any, pos: any, end: any, cells: any): any;
     parseQuoted(text: any, pos: any, end: any, cells: any): any;

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

@@ -48,6 +48,23 @@ export declare function parseCsvStream(chunks: AsyncIterable<string> | Iterable<
  *   await save(row);
  */
 export declare function iterateCsvStream(chunks: AsyncIterable<string> | Iterable<string>, options?: object): AsyncGenerator<any, void, unknown>;
+/**
+ * Serialize an async iterable of records as an async iterable of CSV
+ * text chunks — the pull form of `stringifyCsvChunks`, byte-identical
+ * to it for the same records: the header exactly once before the first
+ * object row, one line per chunk. Pull is the backpressure: the next
+ * record is requested only when the consumer asks for the next chunk,
+ * so a database cursor behind it never runs ahead of the socket in
+ * front of it. `options.signal` aborts between pulls (the rejection is
+ * the signal's reason); an abort, a consumer that stops early or a throw
+ * closes the record source exactly once.
+ * @param {AsyncIterable<Array|object>|Iterable<Array|object>} rows - Records
+ * @param {object} [options] - Writer options; see `stringifyCsv`, plus `signal`
+ * @yields {string} One line at a time
+ * @example
+ * response.body = stringifyCsvStream(store.collection('rows').query(doc), { signal });
+ */
+export declare function stringifyCsvStream(rows: AsyncIterable<any[] | object> | Iterable<any[] | object>, options?: object): AsyncGenerator<string, void, unknown>;
 /**
  * An incremental CSV writer: rows in, chunks out.
  */
@@ -56,12 +73,17 @@ export declare class CsvStreamWriter {
     options: object;
     chunks: any[];
     onChunk: any;
-    fields: any;
-    wroteHeader: boolean;
+    formatter: {
+        lines: (row: any[] | object) => string[];
+        tail: () => string;
+        fields: () => string[] | null;
+    };
     /**
      * @param {object} [options] - Writer options; see `stringifyCsv`
      */
     constructor(options?: object);
+    /** @returns {string[]|null} The columns as decided, once known. */
+    get fields(): string[] | null;
     /**
      * Write one record.
      * @param {Array|object} row - An array, or an object keyed by column
@@ -80,7 +102,8 @@ export declare class CsvStreamWriter {
      */
     toString(): string;
     /**
-     * Finish writing.
+     * Finish writing: the header an explicit field list is still owed
+     * goes out when no record was written.
      * @returns {string} The complete document, or `''` with an `onChunk` sink
      */
     end(): string;
@@ -100,3 +123,4 @@ export declare function createCsvStreamWriter(options?: {
     onChunk?: (chunk: string) => void;
 }): CsvStreamWriter;
 export { stringifyCsvChunks, formatCsvValue };
+export { JoslLimitError, CSV_LIMIT_CODES } from './limits.js';

package/dist/types/csv.d.ts

@@ -96,8 +96,10 @@ export declare function sniffCsvDialect(text: string, options?: object): {
 };
 /**
  * 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.
+ * bigints lose the `n` suffix JOSL uses (CSV has no type marks), the
+ * JOSL date classes and `Date` render as ISO-8601, and a plain object or
+ * an array — a nested document in a flat format — is its JSON text, so
+ * a reader gets the value back instead of `[object Object]`.
  * @param {*} value - The value
  * @returns {string} Cell text, unquoted
  */
@@ -130,9 +132,28 @@ export declare function stringifyCsv(rows: Array<any[] | object>, options?: {
     fields?: string[];
     header?: boolean;
 }): string;
+/**
+ * The one row formatter behind every CSV writer: the same delimiter,
+ * quote and terminator rules and the same header-once rule, whether
+ * rows arrive as an array, an iterable, an async iterable or one at a
+ * time through the stream writer — so all of them produce byte-identical
+ * text for the same records by construction.
+ * @param {object} [options] - Writer options; see `stringifyCsv`
+ * @returns {{ lines: (row: Array|object) => string[], tail: () => string, fields: () => string[] | null }}
+ *   `lines` formats one record as its line — preceded by the header
+ *   line exactly once, before the first object row — `tail` answers the
+ *   header an explicit field list is still owed when no record was
+ *   ever written, `fields` the columns as decided
+ */
+export declare function createCsvRowFormatter(options?: object): {
+    lines: (row: any[] | object) => string[];
+    tail: () => string;
+    fields: () => string[] | null;
+};
 /**
  * Serialize records as an iterable of chunks, one record at a time, so a
- * large table never exists as a single string.
+ * large table never exists as a single string. The header precedes the
+ * first object row; a chunk is one line.
  * @param {Iterable<Array|object>} rows - Records
  * @param {object} [options] - Writer options; see `stringifyCsv`
  * @yields {string} One record (or the header) at a time

package/dist/types/index.d.ts

@@ -1,12 +1,13 @@
 export { parseJosl, parseToml } from './parse.js';
 export { parseJoslCst, parseTomlCst, JoslCstDocument } from './cst.js';
-export { createStreamReader, parseJoslStream } from './stream.js';
+export { createStreamReader, parseJoslStream, iterateJoslStream } from './stream.js';
 export { stringifyJosl, stringifyToml, formatKey, formatKeyPath, formatValue, formatSection, } from './stringify.js';
-export { createStreamWriter, stringifyJoslChunks } from './write.js';
+export { createStreamWriter, stringifyJoslChunks, stringifyJoslStream } 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 { createCsvStreamReader, parseCsvStream, iterateCsvStream, stringifyCsvStream, createCsvStreamWriter, CsvStreamWriter, } from './csv-stream.js';
 export { JoslSyntaxError, JoslStringifyError, JsonxSyntaxError, CsvSyntaxError } from './errors.js';
+export { JoslLimitError, CSV_LIMIT_CODES, JOSL_LIMIT_CODES, JSONX_LIMIT_CODES } from './limits.js';
 export { LocalDate, LocalTime, LocalDateTime, isValidDateParts, isValidTimeParts, } from './values.js';

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

@@ -3,6 +3,12 @@ export declare class JsonxMachine {
     onEvent: ((event: JsonxStreamEvent) => void) | null;
     partialText: boolean;
     detach: (string | number)[] | null;
+    maxTotalBytes: number;
+    maxTokenBytes: number;
+    maxDepth: number;
+    maxRetainedValues: number;
+    totalBytes: number;
+    retained: number;
     partialFrom: number;
     partialHold: string;
     buf: string;
@@ -42,6 +48,8 @@ export declare class JsonxMachine {
      * @returns {this} The machine, for chaining
      */
     feed(chunk: string): this;
+    token(buf: any, start: any, end: any): void;
+    retain(): void;
     /**
      * Finish the document, flushing any pending token.
      * @returns {*} The completed root value
@@ -161,3 +169,4 @@ export declare function createJsonxStreamReader(options?: {
  */
 export declare function parseJsonxStream(chunks: AsyncIterable<string> | Iterable<string>, options?: object): Promise<any>;
 export { JsonxSyntaxError } from './errors.js';
+export { JoslLimitError, JSONX_LIMIT_CODES } from './limits.js';

package/dist/types/limits.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The CSV limits, by option name.
+ * @type {Readonly<Record<'CSV2001' | 'CSV2002' | 'CSV2003' | 'CSV2004', string>>}
+ */
+export declare const CSV_LIMIT_CODES: Readonly<Record<'CSV2001' | 'CSV2002' | 'CSV2003' | 'CSV2004', string>>;
+/**
+ * The JOSL/TOML limits, by option name. A "record" is one logical line —
+ * the unit the reader buffers before it parses anything.
+ * @type {Readonly<Record<'JOSL2001' | 'JOSL2002' | 'JOSL2003' | 'JOSL2004' | 'JOSL2005', string>>}
+ */
+export declare const JOSL_LIMIT_CODES: Readonly<Record<'JOSL2001' | 'JOSL2002' | 'JOSL2003' | 'JOSL2004' | 'JOSL2005', string>>;
+/**
+ * The JSONX/JSON limits, by option name.
+ * @type {Readonly<Record<'JSONX2001' | 'JSONX2002' | 'JSONX2003' | 'JSONX2004', string>>}
+ */
+export declare const JSONX_LIMIT_CODES: Readonly<Record<'JSONX2001' | 'JSONX2002' | 'JSONX2003' | 'JSONX2004', string>>;
+/**
+ * Error thrown when a document crosses a limit a caller set. Never a
+ * repair, never healed: the text is refused where it stands.
+ */
+export declare class JoslLimitError extends Error {
+    code: string;
+    limit: number;
+    line: number | undefined;
+    /**
+     * @param {string} code - The stable `CSV2xxx` / `JOSL2xxx` / `JSONX2xxx` code
+     * @param {string} message - What was crossed
+     * @param {number} limit - The limit the option set
+     * @param {number} [line] - 1-based physical line where the crossing was met, when known
+     */
+    constructor(code: string, message: string, limit: number, line?: number);
+}
+/**
+ * Read one limit option: absent is `Infinity`; anything but a positive
+ * integer or `Infinity` is a `TypeError` — a limit of zero refuses every
+ * document, and a fraction or a string is a caller's mistake.
+ * @param {object} options - The reader/writer options
+ * @param {string} name - The option name
+ * @returns {number} The limit, `Infinity` when unset
+ */
+export declare function limitOption(options: object, name: string): number;

package/dist/types/machine.d.ts

@@ -1,6 +1,16 @@
 export declare class JoslMachine {
     mode: string;
     onEvent: ((event: object) => void) | null;
+    detachRoot: any;
+    rootCount: number;
+    maxTotalBytes: number;
+    maxRecordBytes: number;
+    maxTokenBytes: number;
+    maxDepth: number;
+    maxRetainedValues: number;
+    totalBytes: number;
+    retained: number;
+    depth: number;
     onLine: any;
     lineValueStart: number;
     lineValueEnd: number;
@@ -54,9 +64,15 @@ export declare class JoslMachine {
     /**
      * The (possibly still growing) root value: `{}`-rooted for documents,
      * `[]`-rooted after a `[[]]` header. Undefined content yields `{}`.
+     * Under `detachRoot` a finished document hands its last item over
+     * here, so the root ends empty.
      * @returns {*} Current root value
      */
     root(): any;
+    detachLast(): void;
+    retain(): void;
+    deeper(depth: any): void;
+    token(line: any, start: any, end: any): void;
     scan(): void;
     cutLine(buf: any, start: any, nlPos: any, innerNl: any): void;
     err(pos: any, message: any, hint: any): void;

package/dist/types/pull.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Close an iterator once, swallowing what the close throws: a source
+ * that refuses its cancel is already gone.
+ * @param {Iterator<any> | AsyncIterator<any>} iterator
+ * @returns {Promise<void>}
+ */
+export declare function closeIterator(iterator: Iterator<any> | AsyncIterator<any>): Promise<void>;
+/**
+ * The rejection of an aborted pull: the signal's reason when it has one,
+ * else an `AbortError`-named error, as the platform spells it.
+ * @param {AbortSignal} signal
+ * @returns {unknown}
+ */
+export declare function abortedError(signal: AbortSignal): unknown;

package/dist/types/stream.d.ts

@@ -29,4 +29,24 @@ export declare function createStreamReader(options?: {
  * @returns {Promise<*>} The completed root value
  */
 export declare function parseJoslStream(chunks: AsyncIterable<string> | Iterable<string>, options?: object): Promise<any>;
+/**
+ * Yield the `[[]]` root items of a JOSL document as they complete,
+ * without ever holding the whole document: each item is DETACHED from
+ * the root the moment the next `[[]]` header (or the end) completes it,
+ * so `root()`-style retention never grows past one record — the JOSL
+ * twin of the JSONX reader's `detach`. A document with a table root is
+ * refused by name (`JoslSyntaxError`): a table root is one retained
+ * value, not a stream of records. `options.signal` aborts between
+ * chunks; an abort, a consumer that stops early or a throw closes the
+ * chunk source exactly once.
+ * @param {AsyncIterable<string>|Iterable<string>} chunks - Source chunks
+ * @param {object} [options] - Reader options; see `createStreamReader`,
+ *  plus `signal` and the `JOSL2xxx` limits
+ * @yields {object} One completed root item at a time
+ * @example
+ * for await (const record of iterateJoslStream(response.body))
+ *   await save(record);
+ */
+export declare function iterateJoslStream(chunks: AsyncIterable<string> | Iterable<string>, options?: object): AsyncGenerator<object, void, unknown>;
 export { JoslSyntaxError } from './errors.js';
+export { JoslLimitError, JOSL_LIMIT_CODES } from './limits.js';

package/dist/types/util.d.ts

@@ -2,6 +2,18 @@
 export declare const RE_DATETIME: RegExp;
 /** A bare `HH:MM:SS` with an optional fraction. @type {RegExp} */
 export declare const RE_TIMEONLY: RegExp;
+/**
+ * Convert a local date and time with an offset to their native instant.
+ * ISO parsing preserves years 0000-0099 and truncates sub-millisecond
+ * precision consistently for JOSL and typed CSV. An invalid offset (or
+ * an instant Date cannot represent) returns an invalid Date for the
+ * caller's own refusal or text-preservation policy.
+ * @param {import('./values.js').LocalDate} date - Validated calendar date
+ * @param {import('./values.js').LocalTime} time - Validated local time
+ * @param {string} offset - Z/z or a signed HH:MM offset
+ * @returns {Date}
+ */
+export declare function offsetDateTime(date: import('./values.js').LocalDate, time: import('./values.js').LocalTime, offset: string): Date;
 /**
  * Run a sticky regex at `pos` and return its match (or null).
  * @param {RegExp} re - A sticky (`y`) pattern

package/dist/types/write.d.ts

@@ -5,7 +5,9 @@ declare class JoslStreamWriter {
         onRegExp: any;
     };
     onChunk: any;
+    buffered: boolean;
     chunks: any[];
+    emitted: boolean;
     ended: boolean;
     rootIsArray: boolean;
     rootHasPairs: boolean;
@@ -53,7 +55,8 @@ declare class JoslStreamWriter {
      */
     comment(text: string): this;
     /**
-     * The document text emitted so far.
+     * The document text emitted so far; `''` under `buffer: false`, whose
+     * chunks went to the sink and nowhere else.
      * @returns {string} Concatenated chunks
      */
     text(): string;
@@ -66,12 +69,15 @@ declare class JoslStreamWriter {
 /**
  * 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()`.
+ * are produced and also accumulate for `text()` / `end()` — unless
+ * `buffer: false`, which keeps no copy: the sink is the only holder.
  * @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
+ * @param {boolean} [options.buffer] - `false` retains no emitted text
+ *  (needs `onChunk`); `text()` and `end()` then answer `''`
  * @returns {JoslStreamWriter} The writer
  */
 export declare function createStreamWriter(options?: {
@@ -79,6 +85,7 @@ export declare function createStreamWriter(options?: {
     onNull?: 'error' | 'omit';
     onRegExp?: 'error' | 'string';
     onChunk?: (chunk: string) => void;
+    buffer?: boolean;
 }): JoslStreamWriter;
 /**
  * Serialize a value as an iterable of text chunks: one chunk per record
@@ -89,4 +96,19 @@ export declare function createStreamWriter(options?: {
  * @yields {string} Document chunks, in order
  */
 export declare function stringifyJoslChunks(value: object | any[], options?: object): Generator<string, void, unknown>;
+/**
+ * Serialize an async iterable of table records as an async iterable of
+ * `[[]]` chunks — the pull form of `stringifyJoslChunks` over a root
+ * array, byte-identical to it for the same records. Pull is the
+ * backpressure: the next record is requested only when the consumer
+ * asks for the next chunk. `options.signal` aborts between pulls (the
+ * rejection is the signal's reason); an abort, a consumer that stops
+ * early or a throw closes the record source exactly once.
+ * @param {AsyncIterable<object>|Iterable<object>} records - Table records
+ * @param {object} [options] - Writer options; see `stringifyJosl`, plus `signal`
+ * @yields {string} One `[[]]` record per chunk
+ * @example
+ * response.body = stringifyJoslStream(store.collection('rows').query(doc), { signal });
+ */
+export declare function stringifyJoslStream(records: AsyncIterable<object> | Iterable<object>, options?: object): AsyncGenerator<string, void, unknown>;
 export { JoslStringifyError } from './errors.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/josl",
   "private": false,
-  "version": "0.56.0",
+  "version": "0.66.1",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -99,6 +99,6 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.56.0"
+    "@jarenjs/core": "^0.66.1"
   }
 }