@jarenjs/josl 0.49.2 → 0.66.1

package/src/csv-machine.js

@@ -48,8 +48,10 @@ import {
 } from '@jarenjs/core/scan';
 
 import { CsvSyntaxError } from './errors.js';
-import { columnOf, feedMachine, beginParseAll } from './util.js';
+import { JoslLimitError, limitOption } from './limits.js';
+import { columnOf, feedMachine, beginParseAll, offsetDateTime } from './util.js';
 import { setObjectMember } from '@jarenjs/core/object';
+import { utf8ByteLength } from '@jarenjs/core/string';
 import {
   LocalDate,
   LocalTime,
@@ -182,9 +184,10 @@ export function coerceCsvValue(s) {
     const frac = m[7] === undefined ? '' : '.' + m[7];
     if (m[8] !== undefined || m[9] !== undefined) {
       // an offset date-time is an instant, which `Date` holds faithfully
-      const offset = m[8] !== undefined ? 0 : (m[9] === '-' ? -1 : 1) * (+m[10] * 60 + +m[11]);
-      const ms = frac === '' ? 0 : Math.round(Number('0' + frac) * 1000);
-      return new Date(Date.UTC(year, month - 1, day, hour, min, sec, ms) - offset * 60000);
+      const offset = m[8] ?? `${m[9]}${m[10]}:${m[11]}`;
+      const instant = offsetDateTime(new LocalDate(year, month, day),
+        new LocalTime(hour, min, sec, frac), offset);
+      return Number.isNaN(instant.getTime()) ? s : instant;
     }
     return new LocalDateTime(
       new LocalDate(year, month, day),
@@ -241,6 +244,16 @@ export class CsvMachine {
     this.onEvent = options.onEvent ?? null;
     this.onRepair = options.onRepair ?? null;
 
+    // the hostile-input limits: Infinity unless asked for, checked while
+    // the text is still in cutter or cell state (limits.js)
+    this.maxTotalBytes = limitOption(options, 'maxTotalBytes');
+    this.maxRecordBytes = limitOption(options, 'maxRecordBytes');
+    this.maxFieldBytes = limitOption(options, 'maxFieldBytes');
+    this.maxColumns = limitOption(options, 'maxColumns');
+    this.limited = this.maxTotalBytes !== Infinity || this.maxRecordBytes !== Infinity
+      || this.maxFieldBytes !== Infinity || this.maxColumns !== Infinity;
+    this.totalBytes = 0;
+
     const headers = options.headers;
     this.wantHeader = headers === true;
     this.headerFields = Array.isArray(headers)
@@ -294,9 +307,38 @@ export class CsvMachine {
       this.nextLf = -2;
     if (this.nextCr === -1)
       this.nextCr = -2;
+    if (this.limited)
+      this.count(chunk);
     return feedMachine(this, chunk);
   }
 
+  // The byte limits, checked BEFORE the chunk is buffered: a chunk that
+  // takes the document past maxTotalBytes is refused whole, and a record
+  // still being cut — the unconsumed tail plus this chunk — that would
+  // pass maxRecordBytes is refused before the concatenation that would
+  // hold it. `parseAll` counts its one text the same way.
+  count(text) {
+    if (this.maxTotalBytes !== Infinity) {
+      this.totalBytes += utf8ByteLength(text);
+      if (this.totalBytes > this.maxTotalBytes)
+        throw new JoslLimitError('CSV2001', 'the document exceeds maxTotalBytes', this.maxTotalBytes, this.line);
+    }
+    if (this.maxRecordBytes !== Infinity) {
+      // the pending record is what the cutter has not handed off yet;
+      // a fresh chunk extends it
+      const pending = utf8ByteLength(this.buf) + utf8ByteLength(text);
+      if (pending > this.maxRecordBytes && !this.endsRecordWithin(text))
+        throw new JoslLimitError('CSV2002', 'a record exceeds maxRecordBytes', this.maxRecordBytes, this.recordOrigin);
+    }
+  }
+
+  // Whether a chunk can end the pending record within the bound: cheap
+  // and permissive — a terminator anywhere in the chunk means the cutter
+  // gets its chance; the span check in readSpan is the exact judge.
+  endsRecordWithin(text) {
+    return text.indexOf('\n') >= 0 || text.indexOf('\r') >= 0;
+  }
+
   /**
    * Finish the document, flushing any pending record.
    * @returns {Array} The completed rows
@@ -326,6 +368,8 @@ export class CsvMachine {
    */
   parseAll(text) {
     text = beginParseAll(this, text);
+    if (this.maxTotalBytes !== Infinity && utf8ByteLength(text) > this.maxTotalBytes)
+      throw new JoslLimitError('CSV2001', 'the document exceeds maxTotalBytes', this.maxTotalBytes, 1);
     this.readSpan(text, 0, text.length);
     return this.outRows;
   }
@@ -586,13 +630,29 @@ export class CsvMachine {
       }
       this.recordOrigin = this.line;
       this.dropRecord = false;
+      const start = pos;
       pos = this.parseRecord(text, pos, end, cells);
+      // the record's source bytes, terminator included — judged before
+      // the record is kept (the streaming path also refused it at every
+      // chunk boundary while it was still being cut)
+      if (this.maxRecordBytes !== Infinity && utf8ByteLength(text, start, pos) > this.maxRecordBytes)
+        throw new JoslLimitError('CSV2002', 'a record exceeds maxRecordBytes', this.maxRecordBytes, this.recordOrigin);
       if (!this.dropRecord)
         this.emitRecord(cells);
     }
     return pos;
   }
 
+  // One cell about to be kept: its source bytes (quotes included, as
+  // written) and the column count are judged before the slice or the
+  // push that would hold it.
+  admitCell(cells, text, start, stop) {
+    if (this.maxFieldBytes !== Infinity && utf8ByteLength(text, start, stop) > this.maxFieldBytes)
+      throw new JoslLimitError('CSV2003', 'a field exceeds maxFieldBytes', this.maxFieldBytes, this.line);
+    if (cells.length >= this.maxColumns)
+      throw new JoslLimitError('CSV2004', 'a record has more than maxColumns fields', this.maxColumns, this.recordOrigin);
+  }
+
   // The single grammar path: fill `cells` with one record's fields and
   // return the offset just past the record, including its terminator.
   parseRecord(text, pos, end, cells) {
@@ -668,6 +728,8 @@ export class CsvMachine {
       stop = nlf;
     if (ncr >= 0 && ncr < stop)
       stop = ncr;
+    if (this.limited)
+      this.admitCell(cells, text, pos, stop);
     const raw = text.slice(pos, stop);
     cells.push(this.plainCells ? raw : this.finish(raw));
     return stop;
@@ -677,6 +739,7 @@ export class CsvMachine {
   parseQuoted(text, pos, end, cells) {
     const quote = this.quote;
     const delim = this.delimiter;
+    const opened = pos;
     pos++; // opening quote
     let start = pos;
     let out = null;
@@ -685,6 +748,8 @@ export class CsvMachine {
         // Out of input with the field still open. Closing it here is the
         // only reading that keeps the text.
         this.heal('CSV1001', this.recordOrigin, columnOf(text, pos));
+        if (this.limited)
+          this.admitCell(cells, text, opened, pos);
         cells.push(this.finishQuoted(joinCell(out, text, start, pos)));
         return pos;
       }
@@ -697,12 +762,16 @@ export class CsvMachine {
       }
       const n = pos + 1 < end ? text.charCodeAt(pos + 1) : -1;
       if (n === quote) { // "" — one literal quote
+        if (this.maxFieldBytes !== Infinity && utf8ByteLength(text, opened, pos + 2) > this.maxFieldBytes)
+          throw new JoslLimitError('CSV2003', 'a field exceeds maxFieldBytes', this.maxFieldBytes, this.line);
         out = (out === null ? '' : out) + text.slice(start, pos + 1);
         pos += 2;
         start = pos;
         continue;
       }
       if (n === delim || n === CC_LF || n === CC_CR || n === -1) {
+        if (this.limited)
+          this.admitCell(cells, text, opened, pos + 1);
         cells.push(this.finishQuoted(joinCell(out, text, start, pos)));
         return pos + 1; // past the closing quote
       }
@@ -733,6 +802,8 @@ export class CsvMachine {
           break;
         pos++;
       }
+      if (this.limited)
+        this.admitCell(cells, text, opened, pos);
       cells.push(this.finishQuoted(closed + text.slice(stray, pos)));
       return pos;
     }

package/src/csv-stream.js

@@ -9,7 +9,8 @@
 // test suite asserts exactly that at every chunk size.
 
 import { CsvMachine } from './csv-machine.js';
-import { stringifyCsvChunks, formatCsvValue } from './csv.js';
+import { stringifyCsvChunks, formatCsvValue, createCsvRowFormatter } from './csv.js';
+import { closeIterator, abortedError } from './pull.js';
 
 //#region reading
 
@@ -83,22 +84,82 @@ export async function parseCsvStream(chunks, options = undefined) {
  */
 export async function* iterateCsvStream(chunks, options = undefined) {
   const machine = new CsvMachine(options);
+  const signal = options?.signal ?? null;
   const pending = machine.rows();
-  for await (const chunk of chunks) {
-    machine.feed(chunk);
-    if (pending.length !== 0) {
-      // hand over the completed rows and drop them, so the machine never
-      // accumulates the document it is streaming
-      const batch = pending.splice(0, pending.length);
-      for (const row of batch)
-        yield row;
+  const iterator = chunks[Symbol.asyncIterator]?.() ?? chunks[Symbol.iterator]();
+  let finished = false;
+  try {
+    for (;;) {
+      if (signal !== null && signal.aborted)
+        throw abortedError(signal);
+      const step = await iterator.next();
+      if (step.done) {
+        finished = true;
+        break;
+      }
+      machine.feed(step.value);
+      if (pending.length !== 0) {
+        // hand over the completed rows and drop them, so the machine never
+        // accumulates the document it is streaming
+        const batch = pending.splice(0, pending.length);
+        for (const row of batch)
+          yield row;
+      }
     }
   }
+  finally {
+    // a consumer that stops early, an abort, or a throw: the source is
+    // closed exactly once; a source read to its end needs no close
+    if (!finished)
+      await closeIterator(iterator);
+  }
   machine.end();
   for (const row of pending.splice(0, pending.length))
     yield row;
 }
 
+/**
+ * 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 async function* stringifyCsvStream(rows, options = {}) {
+  const formatter = createCsvRowFormatter(options);
+  const signal = options.signal ?? null;
+  const iterator = rows[Symbol.asyncIterator]?.() ?? rows[Symbol.iterator]();
+  let finished = false;
+  try {
+    for (;;) {
+      if (signal !== null && signal.aborted)
+        throw abortedError(signal);
+      const step = await iterator.next();
+      if (step.done) {
+        finished = true;
+        break;
+      }
+      yield* formatter.lines(step.value);
+    }
+  }
+  finally {
+    if (!finished)
+      await closeIterator(iterator);
+  }
+  const tail = formatter.tail();
+  if (tail.length !== 0)
+    yield tail;
+}
+
 //#endregion
 
 //#region writing
@@ -114,8 +175,7 @@ export class CsvStreamWriter {
     this.options = options;
     this.chunks = [];
     this.onChunk = options.onChunk ?? null;
-    this.fields = options.fields ?? null;
-    this.wroteHeader = options.header === false;
+    this.formatter = createCsvRowFormatter(options);
   }
 
   #emit(text) {
@@ -126,23 +186,19 @@ export class CsvStreamWriter {
     return this;
   }
 
+  /** @returns {string[]|null} The columns as decided, once known. */
+  get fields() {
+    return this.formatter.fields();
+  }
+
   /**
    * Write one record.
    * @param {Array|object} row - An array, or an object keyed by column
    * @returns {this} The writer, for chaining
    */
   write(row) {
-    if (!Array.isArray(row) && this.fields === null)
-      this.fields = Object.keys(row);
-    for (const chunk of stringifyCsvChunks([row], {
-      ...this.options,
-      fields: this.fields,
-      header: !this.wroteHeader && this.options.header !== false,
-    })) {
+    for (const chunk of this.formatter.lines(row))
       this.#emit(chunk);
-    }
-    if (!Array.isArray(row))
-      this.wroteHeader = true;
     return this;
   }
 
@@ -166,10 +222,14 @@ export class CsvStreamWriter {
   }
 
   /**
-   * 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() {
+    const tail = this.formatter.tail();
+    if (tail.length !== 0)
+      this.#emit(tail);
     return this.toString();
   }
 }
@@ -192,5 +252,6 @@ export function createCsvStreamWriter(options = undefined) {
 //#endregion
 
 export { stringifyCsvChunks, formatCsvValue };
+export { JoslLimitError, CSV_LIMIT_CODES } from './limits.js';
 
 //#endregion

package/src/csv.js

@@ -250,8 +250,10 @@ function needsQuoteTester(delimiter, quote) {
 
 /**
  * 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
  */
@@ -267,6 +269,8 @@ export function formatCsvValue(value) {
   }
   if (value instanceof Date)
     return Number.isNaN(value.getTime()) ? '' : value.toISOString();
+  if (Array.isArray(value) || Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)
+    return JSON.stringify(value);
   // LocalDate / LocalTime / LocalDateTime, and anything else that knows
   // how to render itself
   return String(value);
@@ -301,13 +305,19 @@ export function stringifyCsv(rows, options = {}) {
 }
 
 /**
- * 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
+ * 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`
- * @yields {string} One record (or the header) at a time
+ * @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 function* stringifyCsvChunks(rows, options = {}) {
+export function createCsvRowFormatter(options = {}) {
   const delimiter = options.delimiter ?? ',';
   const quote = options.quote ?? '"';
   const newline = options.newline ?? '\r\n';
@@ -321,39 +331,58 @@ export function* stringifyCsvChunks(rows, options = {}) {
       return s;
     return quote + (s.includes(quote) ? s.replaceAll(quote, escaped) : s) + quote;
   };
+  const line = (values) => {
+    let out = '';
+    for (let i = 0; i < values.length; i++)
+      out += (i === 0 ? '' : delimiter) + cell(values[i]);
+    return out + newline;
+  };
 
   let fields = options.fields ?? null;
   let emittedHeader = false;
-  for (const row of rows) {
-    if (Array.isArray(row)) {
-      let line = '';
-      for (let i = 0; i < row.length; i++)
-        line += (i === 0 ? '' : delimiter) + cell(row[i]);
-      yield line + newline;
-      continue;
-    }
-    if (fields === null)
-      fields = Object.keys(row);
-    if (wantHeader && !emittedHeader) {
-      emittedHeader = true;
-      let head = '';
+  return {
+    lines(row) {
+      if (Array.isArray(row))
+        return [line(row)];
+      if (fields === null)
+        fields = Object.keys(row);
+      const values = new Array(fields.length);
       for (let i = 0; i < fields.length; i++)
-        head += (i === 0 ? '' : delimiter) + cell(fields[i]);
-      yield head + newline;
-    }
-    let line = '';
-    for (let i = 0; i < fields.length; i++)
-      line += (i === 0 ? '' : delimiter) + cell(row[fields[i]]);
-    yield line + newline;
-  }
-  // an explicit field list still deserves its header when there were no
-  // records to infer one from
-  if (wantHeader && !emittedHeader && fields !== null && options.fields !== undefined) {
-    let head = '';
-    for (let i = 0; i < fields.length; i++)
-      head += (i === 0 ? '' : delimiter) + cell(fields[i]);
-    yield head + newline;
-  }
+        values[i] = row[fields[i]];
+      if (wantHeader && !emittedHeader) {
+        emittedHeader = true;
+        return [line(fields), line(values)];
+      }
+      return [line(values)];
+    },
+    tail() {
+      // an explicit field list still deserves its header when there
+      // were no records to infer one from
+      if (wantHeader && !emittedHeader && fields !== null && options.fields !== undefined) {
+        emittedHeader = true;
+        return line(fields);
+      }
+      return '';
+    },
+    fields: () => fields,
+  };
+}
+
+/**
+ * Serialize records as an iterable of chunks, one record at a time, so a
+ * 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
+ */
+export function* stringifyCsvChunks(rows, options = {}) {
+  const formatter = createCsvRowFormatter(options);
+  for (const row of rows)
+    yield* formatter.lines(row);
+  const tail = formatter.tail();
+  if (tail.length !== 0)
+    yield tail;
 }
 
 //#endregion

package/src/index.js

@@ -8,7 +8,7 @@
 
 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,
@@ -17,7 +17,7 @@ export {
   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';
@@ -35,10 +35,12 @@ 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,

package/src/jsonx-stream.js

@@ -79,7 +79,9 @@ import {
 } from '@jarenjs/core/scan';
 
 import { JsonxSyntaxError } from './errors.js';
+import { JoslLimitError, limitOption } from './limits.js';
 import { setObjectMember } from '@jarenjs/core/object';
+import { utf8ByteLength } from '@jarenjs/core/string';
 import {
   isValueEndCode,
   decodeString,
@@ -154,6 +156,13 @@ export class JsonxMachine {
     this.onEvent = options.onEvent ?? null;
     this.partialText = options.partialText === true;
     this.detach = options.detach === undefined ? null : detachPattern(options.detach);
+    // the hostile-input limits: Infinity unless asked for (limits.js)
+    this.maxTotalBytes = limitOption(options, 'maxTotalBytes');
+    this.maxTokenBytes = limitOption(options, 'maxTokenBytes');
+    this.maxDepth = limitOption(options, 'maxDepth');
+    this.maxRetainedValues = limitOption(options, 'maxRetainedValues');
+    this.totalBytes = 0;
+    this.retained = 0; // values linked into the tree
     this.partialFrom = -1; // body offset the next text-partial delta starts at
     this.partialHold = ''; // lone high surrogate held back for the next delta
     this.buf = '';
@@ -188,12 +197,38 @@ export class JsonxMachine {
     if (this.ended)
       throw new Error('cannot feed after end()');
     if (chunk.length !== 0) {
+      if (this.maxTotalBytes !== Infinity) {
+        this.totalBytes += utf8ByteLength(chunk);
+        if (this.totalBytes > this.maxTotalBytes)
+          throw new JoslLimitError('JSONX2001', 'the document exceeds maxTotalBytes', this.maxTotalBytes, this.curLine);
+      }
+      if (this.maxTokenBytes !== Infinity && this.scanPos >= 0) {
+        // a token still being scanned grows by this chunk: refused
+        // before the concatenation that would hold it
+        const pending = utf8ByteLength(this.buf, this.pos, this.buf.length) + utf8ByteLength(chunk);
+        if (pending > this.maxTokenBytes)
+          throw new JoslLimitError('JSONX2002', 'a token exceeds maxTokenBytes', this.maxTokenBytes, this.curLine);
+      }
       this.buf += chunk;
       this.pump();
     }
     return this;
   }
 
+  // A token whose extent is known, judged before it is decoded.
+  token(buf, start, end) {
+    if (this.maxTokenBytes !== Infinity && utf8ByteLength(buf, start, end) > this.maxTokenBytes)
+      throw new JoslLimitError('JSONX2002', 'a token exceeds maxTokenBytes', this.maxTokenBytes, this.curLine);
+  }
+
+  // One more value linked into the tree, judged before the link. A
+  // detached value is never linked and never counted: that is what
+  // detaching means.
+  retain() {
+    if (++this.retained > this.maxRetainedValues)
+      throw new JoslLimitError('JSONX2004', 'the root retains more than maxRetainedValues values', this.maxRetainedValues, this.curLine);
+  }
+
   /**
    * Finish the document, flushing any pending token.
    * @returns {*} The completed root value
@@ -301,6 +336,7 @@ export class JsonxMachine {
           const end = this.scanString(buf, pos);
           if (end < 0)
             break pumping;
+          this.token(buf, pos, end);
           this.stack[this.stack.length - 1].key = decodeString(buf, pos, this.errCb)[0];
           this.state = ST_COLON;
           pos = end;
@@ -394,6 +430,7 @@ export class JsonxMachine {
           this.emitPartialText(buf, pos, buf.length, true);
         return -1;
       }
+      this.token(buf, pos, end);
       const value = decodeString(buf, pos, this.errCb)[0];
       if (this.partialText) {
         // the closing delta completes the run, so the deltas for a string
@@ -408,8 +445,10 @@ export class JsonxMachine {
     if (c === CC_SLASH) {
       if (this.mode === 'json')
         this.errAt(pos, 'a regexp literal is a JSONX extension', 'quote the pattern as a string');
-      if (this.scanRegExp(buf, pos) < 0)
+      const scanned = this.scanRegExp(buf, pos);
+      if (scanned < 0)
         return -1;
+      this.token(buf, pos, scanned);
       const [re, end] = matchRegExp(buf, pos, this.errCb);
       this.checkValueEnd(buf, end);
       this.completeScalar(re);
@@ -420,6 +459,7 @@ export class JsonxMachine {
     const end = this.scanScalar(buf, pos);
     if (end < 0)
       return -1;
+    this.token(buf, pos, end);
     return this.decodeScalarToken(buf, pos, c);
   }
 
@@ -525,9 +565,13 @@ export class JsonxMachine {
       const index = frame.count++;
       // A detached scalar is not stored: the `item` event below already
       // carries it, so linking it in would retain exactly what the
-      // caller asked not to retain.
-      if (!this.detaches(index))
+      // caller asked not to retain. A value inside a detached subtree is
+      // linked into that subtree, which the root never holds: not counted.
+      if (!this.detaches(index)) {
+        if (!frame.detached)
+          this.retain();
         frame.value[index] = value;
+      }
       if (this.onEvent !== null)
         this.onEvent({
           type: 'item',
@@ -539,8 +583,11 @@ export class JsonxMachine {
       this.state = ST_ARR_NEXT;
     }
     else {
-      if (!this.detaches(frame.key))
+      if (!this.detaches(frame.key)) {
+        if (!frame.detached)
+          this.retain();
         setObjectMember(frame.value, frame.key, value);
+      }
       if (this.onEvent !== null)
         this.onEvent({
           type: 'pair',
@@ -561,7 +608,12 @@ export class JsonxMachine {
   openContainer(isArray) {
     const container = isArray ? [] : {};
     const stack = this.stack;
+    if (stack.length + 1 > this.maxDepth)
+      throw new JoslLimitError('JSONX2003', 'the document nests deeper than maxDepth', this.maxDepth, this.curLine);
     const parent = stack.length !== 0 ? stack[stack.length - 1] : null;
+    // whether this container lives outside the root: detached itself, or
+    // inside a detached subtree — nothing linked into it counts as retained
+    let detached = parent !== null && parent.detached;
     if (parent === null)
       this.rootValue = container;
     else if (parent.array) {
@@ -571,13 +623,23 @@ export class JsonxMachine {
       // so the memory is not freed later — it is not held in the first
       // place, and a document with a million records never builds a
       // million-slot array either.
-      if (!this.detaches(index))
+      if (this.detaches(index))
+        detached = true;
+      else {
+        if (!detached)
+          this.retain();
         parent.value[index] = container;
+      }
       this.path.push(index);
     }
     else {
-      if (!this.detaches(parent.key))
+      if (this.detaches(parent.key))
+        detached = true;
+      else {
+        if (!detached)
+          this.retain();
         setObjectMember(parent.value, parent.key, container);
+      }
       this.path.push(parent.key);
     }
     stack.push({
@@ -586,6 +648,7 @@ export class JsonxMachine {
       key: undefined,
       count: 0,
       pathed: parent !== null,
+      detached,
     });
     if (this.onEvent !== null)
       this.onEvent({
@@ -802,5 +865,6 @@ export async function parseJsonxStream(chunks, options = undefined) {
 }
 
 export { JsonxSyntaxError } from './errors.js';
+export { JoslLimitError, JSONX_LIMIT_CODES } from './limits.js';
 
 //#endregion