links-notation 0.19.0 → 0.21.0

package/README.md

@@ -147,6 +147,45 @@ const group = new LinksGroup(parsed);
 console.log(group.format());
 ```
 
+### Streaming Parser (for Large Messages)
+
+The `StreamParser` allows you to parse Links Notation incrementally, processing data as it arrives without loading the entire message into memory. This is ideal for:
+
+- Large files that don't fit in memory
+- Network streaming (TCP/HTTP)
+- Real-time processing of incoming data
+
+```javascript
+import { StreamParser } from 'links-notation';
+
+const parser = new StreamParser({ collect: false, maxBufferSize: 1024 * 1024 });
+
+// Listen for parsed links
+parser.on('link', (link) => {
+  console.log('Parsed link:', link.toString());
+});
+
+// Listen for errors with location information
+parser.on('error', (error) => {
+  console.error(
+    `Error at line ${error.line}, col ${error.column}: ${error.message}`
+  );
+});
+
+// Feed data incrementally (e.g., from network chunks)
+parser.write('papa (lovesMama: loves mama)\n');
+parser.write('son lovesMama\n');
+parser.write('daughter lovesMama\n');
+
+// Finish the last record. Links are not retained when collection is disabled.
+parser.end();
+```
+
+`StreamParser.parse(chunks)` and `StreamParser.parseAsync(chunks)` expose native
+sync and async iterables. The parser also provides `position()`, `drain()`,
+`reset()`, and a maximum unresolved-record size. See the
+[streaming parser example](../examples/js_streaming_parser.js).
+
 ### TypeScript Usage Examples
 
 ```typescript
@@ -314,6 +353,19 @@ Container for grouping related links.
 - `constructor(links)` - Create a new group
 - `format()` - Format the group as a string
 
+#### `StreamParser`
+
+EventEmitter-based streaming parser for incremental parsing.
+
+- `constructor(options)` - Create a new streaming parser
+  - `options.maxInputSize` - Maximum input size in bytes (default: 10MB)
+  - `options.maxDepth` - Maximum nesting depth (default: 1000)
+- `write(chunk)` - Feed a chunk of data to the parser
+- `end()` - Finish parsing and return all parsed links
+- `position()` - Get current parsing position (line, column, offset)
+- Event: `'link'` - Emitted when a link is parsed (callback receives Link object)
+- Event: `'error'` - Emitted on parse error (callback receives Error with line/column info)
+
 #### `ParseError`
 
 Thrown by `parse(input)` when the document does not parse. The message says

package/README.ru.md

@@ -105,6 +105,27 @@ const group = new LinksGroup(parsed);
 console.log(group.format());
 ```
 
+### Потоковый парсер
+
+`StreamParser` принимает произвольные порции данных и отправляет события только
+для завершённых связей верхнего уровня. Отключите накопление для обработки с
+ограниченной памятью.
+
+```javascript
+import { StreamParser } from 'links-notation';
+
+const stream = new StreamParser({ collect: false, maxBufferSize: 1024 * 1024 });
+stream.on('link', (link) => console.log(link.toString()));
+stream.on('error', (error) => console.error(error));
+stream.write('профиль:\n  имя Ада\n');
+stream.end('следующая связь');
+```
+
+`StreamParser.parse(chunks)` и `StreamParser.parseAsync(chunks)` предоставляют
+нативные синхронные и асинхронные итераторы. Также доступны `position()`,
+`drain()`, `reset()` и ограничение размера незавершённой записи. См.
+[исполняемый пример](../examples/js_streaming_parser.js).
+
 ## Примеры синтаксиса
 
 ### Дуплеты (2-кортежи)

package/dist/index.js

@@ -275,7 +275,8 @@ var ELLIPSIS = "...";
 
 class ParseError extends Error {
   constructor(input, error) {
-    const start = error?.location?.start ?? { offset: 0, line: 1, column: 1 };
+    const start = positionAt(input, error?.location?.start?.offset ?? 0);
+    const end = positionAt(input, error?.location?.end?.offset ?? start.offset);
     const lineText = lineAt(input, start.offset);
     const summary = `line ${start.line}, column ${start.column}: ${error.message}`;
     const snippet = quote(start.line, lineText, start.column);
@@ -283,7 +284,7 @@ class ParseError extends Error {
 ${snippet}`);
     this.name = "ParseError";
     this.cause = error;
-    this.location = error.location;
+    this.location = { ...error.location, start, end };
     this.offset = start.offset;
     this.line = start.line;
     this.column = start.column;
@@ -294,12 +295,32 @@ ${snippet}`);
 }
 function lineAt(input, offset) {
   const at = Math.max(0, Math.min(offset, input.length));
-  const start = input.lastIndexOf(`
-`, at - 1) + 1;
-  const end = input.indexOf(`
-`, start);
-  const line = input.slice(start, end === -1 ? input.length : end);
-  return line.endsWith("\r") ? line.slice(0, -1) : line;
+  const before = input.slice(0, at);
+  const start = Math.max(before.lastIndexOf(`
+`), before.lastIndexOf("\r")) + 1;
+  const end = input.slice(start).search(/[\r\n]/);
+  return input.slice(start, end === -1 ? input.length : start + end);
+}
+function positionAt(input, offset) {
+  const at = Math.max(0, Math.min(offset, input.length));
+  let line = 1;
+  let column = 1;
+  for (let index = 0;index < at; index++) {
+    if (input[index] === "\r") {
+      line++;
+      column = 1;
+      if (input[index + 1] === `
+` && index + 1 < at)
+        index++;
+    } else if (input[index] === `
+`) {
+      line++;
+      column = 1;
+    } else {
+      column++;
+    }
+  }
+  return { offset: at, line, column };
 }
 function quote(number, lineText, column) {
   const [quoted, at] = windowAround(lineText, column);
@@ -400,7 +421,7 @@ function isSubstantiveBody(content) {
         return false;
       }
     }
-    if (!/\s/.test(character)) {
+    if (!/[ \t\n\r]/.test(character)) {
       hasVisible = true;
     }
   }
@@ -2220,7 +2241,7 @@ function peg$parse(input, options) {
           return false;
         }
       }
-      if (!/\s/.test(c)) {
+      if (!/[ \t\n\r]/.test(c)) {
         hasVisible = true;
       }
     }
@@ -2419,6 +2440,222 @@ class Parser {
     return new Link(item.id ?? null, []);
   }
 }
+// src/StreamParser.js
+import { EventEmitter } from "events";
+var DEFAULT_MAX_BUFFER_SIZE = 10 * 1024 * 1024;
+
+class StreamParseError extends Error {
+  constructor(error, startOffset, startLine) {
+    const localOffset = error?.offset ?? 0;
+    const localLine = error?.line ?? 1;
+    const column = error?.column ?? 1;
+    const line = startLine + localLine - 1;
+    super(`Stream parse error at line ${line}, column ${column}: ${error.message}`);
+    this.name = "StreamParseError";
+    this.cause = error;
+    this.offset = startOffset + localOffset;
+    this.line = line;
+    this.column = column;
+    this.found = error?.found ?? null;
+    this.lineText = error?.lineText ?? "";
+    this.snippet = error?.snippet ?? "";
+  }
+}
+
+class StreamParser extends EventEmitter {
+  constructor(options = {}) {
+    super();
+    this.parser = options.parser ?? new Parser(options);
+    this.comments = options.comments ?? this.parser.comments ?? true;
+    this.maxBufferSize = options.maxBufferSize ?? options.maxInputSize ?? DEFAULT_MAX_BUFFER_SIZE;
+    this.collect = options.collect ?? true;
+    this.reset();
+  }
+  write(chunk) {
+    if (typeof chunk !== "string") {
+      return this._fail(new TypeError("Input must be a string"));
+    }
+    if (this.ended) {
+      return this._fail(new Error("Cannot write after end()"));
+    }
+    const emitted = [];
+    for (let index = 0;index < chunk.length; index++) {
+      const character = chunk[index];
+      this.currentLine += character;
+      this.offset += 1;
+      if (character === `
+`) {
+        this.buffer += this.currentLine;
+        this.currentLine = "";
+        this.lineClassified = false;
+        this.line += 1;
+        this.column = 1;
+      } else {
+        if (!this.lineClassified && character !== " " && character !== "\t" && character !== "\r") {
+          this.lineClassified = true;
+          const isComment = this.comments && character === "#";
+          if (!isComment) {
+            const indentation = leadingSpaces(this.currentLine);
+            this._startContentLine(indentation, emitted);
+          }
+        }
+        this.column += 1;
+      }
+      if (this.buffer.length + this.currentLine.length > this.maxBufferSize) {
+        return this._fail(new RangeError(`Buffered record exceeds maximum size of ${this.maxBufferSize} characters`));
+      }
+    }
+    return emitted;
+  }
+  end(chunk = "") {
+    const emitted = chunk === "" ? [] : this.write(chunk);
+    if (this.ended) {
+      return this.collect ? [...this.links] : emitted;
+    }
+    const document = this.buffer + this.currentLine;
+    if (document.length > 0) {
+      let links;
+      try {
+        links = this.parser.parse(document);
+      } catch (error) {
+        const streamError = new StreamParseError(error, this.segmentOffset, this.segmentLine);
+        return this._fail(streamError);
+      }
+      this._publish(links, emitted);
+      this._advanceSegment(document);
+    }
+    this.buffer = "";
+    this.currentLine = "";
+    this.baseIndentation = null;
+    this.ended = true;
+    const result = this.collect ? [...this.links] : emitted;
+    this.emit("end", result);
+    return result;
+  }
+  drain() {
+    const links = this.links;
+    this.links = [];
+    return links;
+  }
+  reset() {
+    this.buffer = "";
+    this.currentLine = "";
+    this.baseIndentation = null;
+    this.lineClassified = false;
+    this.links = [];
+    this.offset = 0;
+    this.line = 1;
+    this.column = 1;
+    this.segmentOffset = 0;
+    this.segmentLine = 1;
+    this.ended = false;
+    return this;
+  }
+  position() {
+    return {
+      offset: this.offset,
+      line: this.line,
+      column: this.column,
+      buffered: this.buffer.length + this.currentLine.length
+    };
+  }
+  static *parse(chunks, options = {}) {
+    const parser = new StreamParser({ ...options, collect: false });
+    for (const chunk of chunks) {
+      yield* parser.write(chunk);
+    }
+    yield* parser.end();
+  }
+  static async* parseAsync(chunks, options = {}) {
+    const parser = new StreamParser({ ...options, collect: false });
+    for await (const chunk of chunks) {
+      yield* parser.write(chunk);
+    }
+    yield* parser.end();
+  }
+  _startContentLine(indentation, emitted) {
+    if (this.buffer.length > 0 && this.baseIndentation !== null && indentation <= this.baseIndentation && structurallyComplete(this.buffer, this.comments)) {
+      let links;
+      try {
+        links = this.parser.parse(this.buffer);
+      } catch {
+        links = null;
+      }
+      if (links !== null) {
+        this._publish(links, emitted);
+        this._advanceSegment(this.buffer);
+        this.buffer = "";
+        this.baseIndentation = null;
+      }
+    }
+    if (this.baseIndentation === null) {
+      this.baseIndentation = indentation;
+    }
+  }
+  _publish(links, emitted) {
+    for (const link of links) {
+      emitted.push(link);
+      if (this.collect)
+        this.links.push(link);
+      this.emit("link", link);
+    }
+  }
+  _advanceSegment(document) {
+    this.segmentOffset += document.length;
+    this.segmentLine += countNewlines(document);
+  }
+  _fail(error) {
+    this.emit("error", error);
+    throw error;
+  }
+}
+function leadingSpaces(line) {
+  let indentation = 0;
+  while (line[indentation] === " ")
+    indentation += 1;
+  return indentation;
+}
+function countNewlines(value) {
+  let count = 0;
+  for (const character of value) {
+    if (character === `
+`)
+      count += 1;
+  }
+  return count;
+}
+function structurallyComplete(document, comments) {
+  const quotes = ['"', "'", "`"];
+  const beforeReference = [" ", "\t", `
+`, "\r", "(", ":"];
+  const beforeComment = [" ", "\t", `
+`, "\r"];
+  let depth = 0;
+  for (let position = 0;position < document.length; position++) {
+    const character = document[position];
+    const previous = position === 0 ? null : document[position - 1];
+    if (quotes.includes(character) && (previous === null || beforeReference.includes(previous))) {
+      const end = quotedReferenceEnd(document, position);
+      if (end === null)
+        return false;
+      position = end - 1;
+      continue;
+    }
+    if (comments && character === "#" && (previous === null || beforeComment.includes(previous))) {
+      const newline = document.indexOf(`
+`, position);
+      if (newline === -1)
+        return true;
+      position = newline;
+      continue;
+    }
+    if (character === "(")
+      depth += 1;
+    if (character === ")")
+      depth -= 1;
+  }
+  return depth === 0;
+}
 // src/FormatOptions.js
 class FormatOptions {
   constructor(options = {}) {
@@ -2454,6 +2691,8 @@ export {
   LinksGroup,
   ParseError,
   Parser,
+  StreamParseError,
+  StreamParser,
   formatLinks,
   stripComments
 };

package/index.d.ts

@@ -160,6 +160,82 @@ export class Parser {
   parse(input: string): Link[];
 }
 
+/** Options for incremental parsing. */
+export interface StreamParserOptions extends ParserOptions {
+  /** Canonical parser instance to use for completed records. */
+  parser?: Parser;
+
+  /** Largest unresolved record retained in memory (default: 10MB). */
+  maxBufferSize?: number;
+
+  /** Retain emitted links for end() and drain() (default: true). */
+  collect?: boolean;
+}
+
+/** Position immediately after the last character written. */
+export interface StreamPosition {
+  offset: number;
+  line: number;
+  column: number;
+  buffered: number;
+}
+
+/** Canonical parse error translated to coordinates in the complete stream. */
+export class StreamParseError extends Error {
+  cause: Error;
+  offset: number;
+  line: number;
+  column: number;
+  found: string | null;
+  lineText: string;
+  snippet: string;
+}
+
+/** Incrementally emits complete top-level Links Notation records. */
+export class StreamParser {
+  parser: Parser;
+  comments: boolean;
+  maxBufferSize: number;
+  collect: boolean;
+
+  constructor(options?: StreamParserOptions);
+
+  /** Feed a chunk and return links made complete by it. */
+  write(chunk: string): Link[];
+
+  /** Finish the stream, optionally after consuming one final chunk. */
+  end(chunk?: string): Link[];
+
+  /** Return and forget retained links. */
+  drain(): Link[];
+
+  /** Reuse this parser while preserving its options and listeners. */
+  reset(): this;
+
+  /** Return the absolute stream position and unresolved buffer size. */
+  position(): StreamPosition;
+
+  on(event: 'link', listener: (link: Link) => void): this;
+  on(event: 'end', listener: (links: Link[]) => void): this;
+  on(event: 'error', listener: (error: Error) => void): this;
+  once(event: 'link', listener: (link: Link) => void): this;
+  once(event: 'end', listener: (links: Link[]) => void): this;
+  once(event: 'error', listener: (error: Error) => void): this;
+  off(event: string, listener: (...arguments_: any[]) => void): this;
+
+  /** Lazily parse a synchronous iterable of chunks. */
+  static parse(
+    chunks: Iterable<string>,
+    options?: StreamParserOptions
+  ): IterableIterator<Link>;
+
+  /** Lazily parse an asynchronous iterable of chunks. */
+  static parseAsync(
+    chunks: AsyncIterable<string> | Iterable<string>,
+    options?: StreamParserOptions
+  ): AsyncIterableIterator<Link>;
+}
+
 /**
  * Blank out every comment in a document, keeping its length so that every
  * character stays at the offset it was written at.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "links-notation",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "Links Notation parser for JavaScript",
   "main": "dist/index.js",
   "types": "index.d.ts",

package/src/ParseError.js

@@ -19,7 +19,8 @@ export class ParseError extends Error {
    * @param {Error} error - The error the generated parser threw
    */
   constructor(input, error) {
-    const start = error?.location?.start ?? { offset: 0, line: 1, column: 1 };
+    const start = positionAt(input, error?.location?.start?.offset ?? 0);
+    const end = positionAt(input, error?.location?.end?.offset ?? start.offset);
     const lineText = lineAt(input, start.offset);
     const summary = `line ${start.line}, column ${start.column}: ${error.message}`;
     const snippet = quote(start.line, lineText, start.column);
@@ -29,7 +30,7 @@ export class ParseError extends Error {
     /** @type {Error} The error the generated parser threw */
     this.cause = error;
     /** @type {{start: {offset: number, line: number, column: number}}} */
-    this.location = error.location;
+    this.location = { ...error.location, start, end };
     /** @type {number} Offset of the offending position from the start of the document */
     this.offset = start.offset;
     /** @type {number} Line the offending position is on, counted from 1 */
@@ -53,10 +54,37 @@ export class ParseError extends Error {
  */
 function lineAt(input, offset) {
   const at = Math.max(0, Math.min(offset, input.length));
-  const start = input.lastIndexOf('\n', at - 1) + 1;
-  const end = input.indexOf('\n', start);
-  const line = input.slice(start, end === -1 ? input.length : end);
-  return line.endsWith('\r') ? line.slice(0, -1) : line;
+  const before = input.slice(0, at);
+  const start =
+    Math.max(before.lastIndexOf('\n'), before.lastIndexOf('\r')) + 1;
+  const end = input.slice(start).search(/[\r\n]/);
+  return input.slice(start, end === -1 ? input.length : start + end);
+}
+
+/**
+ * Count CR, LF and CRLF as line breaks, as the grammar does. Peggy's error
+ * location counts a lone CR as an ordinary character.
+ * @param {string} input - The document being parsed
+ * @param {number} offset - Offset of the position
+ * @returns {{offset: number, line: number, column: number}} The position
+ */
+function positionAt(input, offset) {
+  const at = Math.max(0, Math.min(offset, input.length));
+  let line = 1;
+  let column = 1;
+  for (let index = 0; index < at; index++) {
+    if (input[index] === '\r') {
+      line++;
+      column = 1;
+      if (input[index + 1] === '\n' && index + 1 < at) index++;
+    } else if (input[index] === '\n') {
+      line++;
+      column = 1;
+    } else {
+      column++;
+    }
+  }
+  return { offset: at, line, column };
 }
 
 /**

package/src/StreamParser.js

@@ -0,0 +1,284 @@
+import { EventEmitter } from 'events';
+import { Parser } from './Parser.js';
+import { quotedReferenceEnd } from './comments.js';
+
+const DEFAULT_MAX_BUFFER_SIZE = 10 * 1024 * 1024;
+
+/**
+ * An error raised while finishing a streamed document.
+ *
+ * The canonical parser reports positions relative to the currently buffered
+ * record. This wrapper translates them back to the complete stream.
+ */
+export class StreamParseError extends Error {
+  constructor(error, startOffset, startLine) {
+    const localOffset = error?.offset ?? 0;
+    const localLine = error?.line ?? 1;
+    const column = error?.column ?? 1;
+    const line = startLine + localLine - 1;
+    super(
+      `Stream parse error at line ${line}, column ${column}: ${error.message}`
+    );
+    this.name = 'StreamParseError';
+    this.cause = error;
+    this.offset = startOffset + localOffset;
+    this.line = line;
+    this.column = column;
+    this.found = error?.found ?? null;
+    this.lineText = error?.lineText ?? '';
+    this.snippet = error?.snippet ?? '';
+  }
+}
+
+/**
+ * Incrementally parses complete top-level Links Notation records.
+ *
+ * A line can acquire indented children, so its terminating newline alone does
+ * not prove that the record is complete. The parser commits a buffered record
+ * as soon as the first non-indented character of the next record arrives. It
+ * uses the regular Parser as the source of truth, which keeps quoted strings,
+ * nested contexts, comments, and future grammar changes in one place.
+ */
+export class StreamParser extends EventEmitter {
+  constructor(options = {}) {
+    super();
+    this.parser = options.parser ?? new Parser(options);
+    this.comments = options.comments ?? this.parser.comments ?? true;
+    this.maxBufferSize =
+      options.maxBufferSize ?? options.maxInputSize ?? DEFAULT_MAX_BUFFER_SIZE;
+    this.collect = options.collect ?? true;
+    this.reset();
+  }
+
+  /** Feed a string chunk and return the links made complete by that chunk. */
+  write(chunk) {
+    if (typeof chunk !== 'string') {
+      return this._fail(new TypeError('Input must be a string'));
+    }
+    if (this.ended) {
+      return this._fail(new Error('Cannot write after end()'));
+    }
+
+    const emitted = [];
+    for (let index = 0; index < chunk.length; index++) {
+      const character = chunk[index];
+      this.currentLine += character;
+      this.offset += 1;
+
+      if (character === '\n') {
+        this.buffer += this.currentLine;
+        this.currentLine = '';
+        this.lineClassified = false;
+        this.line += 1;
+        this.column = 1;
+      } else {
+        if (
+          !this.lineClassified &&
+          character !== ' ' &&
+          character !== '\t' &&
+          character !== '\r'
+        ) {
+          this.lineClassified = true;
+          const isComment = this.comments && character === '#';
+          if (!isComment) {
+            const indentation = leadingSpaces(this.currentLine);
+            this._startContentLine(indentation, emitted);
+          }
+        }
+        this.column += 1;
+      }
+
+      if (this.buffer.length + this.currentLine.length > this.maxBufferSize) {
+        return this._fail(
+          new RangeError(
+            `Buffered record exceeds maximum size of ${this.maxBufferSize} characters`
+          )
+        );
+      }
+    }
+    return emitted;
+  }
+
+  /**
+   * Finish the stream. With collection enabled (the default), returns every
+   * undrained link; otherwise returns only links completed by this call.
+   */
+  end(chunk = '') {
+    const emitted = chunk === '' ? [] : this.write(chunk);
+    if (this.ended) {
+      return this.collect ? [...this.links] : emitted;
+    }
+
+    const document = this.buffer + this.currentLine;
+    if (document.length > 0) {
+      let links;
+      try {
+        links = this.parser.parse(document);
+      } catch (error) {
+        const streamError = new StreamParseError(
+          error,
+          this.segmentOffset,
+          this.segmentLine
+        );
+        return this._fail(streamError);
+      }
+      this._publish(links, emitted);
+      this._advanceSegment(document);
+    }
+
+    this.buffer = '';
+    this.currentLine = '';
+    this.baseIndentation = null;
+    this.ended = true;
+    const result = this.collect ? [...this.links] : emitted;
+    this.emit('end', result);
+    return result;
+  }
+
+  /** Return and forget links retained since the previous drain. */
+  drain() {
+    const links = this.links;
+    this.links = [];
+    return links;
+  }
+
+  /** Reuse this parser for a new stream while keeping listeners and options. */
+  reset() {
+    this.buffer = '';
+    this.currentLine = '';
+    this.baseIndentation = null;
+    this.lineClassified = false;
+    this.links = [];
+    this.offset = 0;
+    this.line = 1;
+    this.column = 1;
+    this.segmentOffset = 0;
+    this.segmentLine = 1;
+    this.ended = false;
+    return this;
+  }
+
+  /** Position immediately after the last character written. */
+  position() {
+    return {
+      offset: this.offset,
+      line: this.line,
+      column: this.column,
+      buffered: this.buffer.length + this.currentLine.length,
+    };
+  }
+
+  /** Lazily parse a synchronous iterable of chunks. */
+  static *parse(chunks, options = {}) {
+    const parser = new StreamParser({ ...options, collect: false });
+    for (const chunk of chunks) {
+      yield* parser.write(chunk);
+    }
+    yield* parser.end();
+  }
+
+  /** Lazily parse an async iterable of chunks. */
+  static async *parseAsync(chunks, options = {}) {
+    const parser = new StreamParser({ ...options, collect: false });
+    for await (const chunk of chunks) {
+      yield* parser.write(chunk);
+    }
+    yield* parser.end();
+  }
+
+  _startContentLine(indentation, emitted) {
+    if (
+      this.buffer.length > 0 &&
+      this.baseIndentation !== null &&
+      indentation <= this.baseIndentation &&
+      structurallyComplete(this.buffer, this.comments)
+    ) {
+      let links;
+      try {
+        links = this.parser.parse(this.buffer);
+      } catch {
+        links = null;
+      }
+      if (links !== null) {
+        this._publish(links, emitted);
+        this._advanceSegment(this.buffer);
+        this.buffer = '';
+        this.baseIndentation = null;
+      }
+    }
+
+    if (this.baseIndentation === null) {
+      this.baseIndentation = indentation;
+    }
+  }
+
+  _publish(links, emitted) {
+    for (const link of links) {
+      emitted.push(link);
+      if (this.collect) this.links.push(link);
+      this.emit('link', link);
+    }
+  }
+
+  _advanceSegment(document) {
+    this.segmentOffset += document.length;
+    this.segmentLine += countNewlines(document);
+  }
+
+  _fail(error) {
+    this.emit('error', error);
+    throw error;
+  }
+}
+
+function leadingSpaces(line) {
+  let indentation = 0;
+  while (line[indentation] === ' ') indentation += 1;
+  return indentation;
+}
+
+function countNewlines(value) {
+  let count = 0;
+  for (const character of value) {
+    if (character === '\n') count += 1;
+  }
+  return count;
+}
+
+function structurallyComplete(document, comments) {
+  const quotes = ['"', "'", '`'];
+  const beforeReference = [' ', '\t', '\n', '\r', '(', ':'];
+  const beforeComment = [' ', '\t', '\n', '\r'];
+  let depth = 0;
+
+  for (let position = 0; position < document.length; position++) {
+    const character = document[position];
+    const previous = position === 0 ? null : document[position - 1];
+
+    if (
+      quotes.includes(character) &&
+      (previous === null || beforeReference.includes(previous))
+    ) {
+      const end = quotedReferenceEnd(document, position);
+      if (end === null) return false;
+      position = end - 1;
+      continue;
+    }
+
+    if (
+      comments &&
+      character === '#' &&
+      (previous === null || beforeComment.includes(previous))
+    ) {
+      const newline = document.indexOf('\n', position);
+      if (newline === -1) return true;
+      position = newline;
+      continue;
+    }
+
+    if (character === '(') depth += 1;
+    if (character === ')') depth -= 1;
+  }
+
+  return depth === 0;
+}

package/src/comments.js

@@ -155,7 +155,7 @@ function isSubstantiveBody(content) {
         return false;
       }
     }
-    if (!/\s/.test(character)) {
+    if (!/[ \t\n\r]/.test(character)) {
       hasVisible = true;
     }
   }

package/src/grammar.pegjs

@@ -83,7 +83,7 @@
           return false;
         }
       }
-      if (!/\s/.test(c)) {
+      if (!/[ \t\n\r]/.test(c)) {
         hasVisible = true;
       }
     }

package/src/index.js

@@ -1,6 +1,7 @@
 export { Link, formatLinks } from './Link.js';
 export { LinksGroup } from './LinksGroup.js';
 export { Parser } from './Parser.js';
+export { StreamParseError, StreamParser } from './StreamParser.js';
 export { ParseError } from './ParseError.js';
 export { FormatConfig } from './FormatConfig.js';
 export { FormatOptions } from './FormatOptions.js';

package/src/parser-generated.js

@@ -1881,7 +1881,7 @@ function peg$parse(input, options) {
           return false;
         }
       }
-      if (!/\s/.test(c)) {
+      if (!/[ \t\n\r]/.test(c)) {
         hasVisible = true;
       }
     }

package/tests/Issue312Conformance.test.js

@@ -0,0 +1,46 @@
+import { test, expect } from 'bun:test';
+import { Parser } from '../src/Parser.js';
+
+const parser = new Parser();
+
+function render(node) {
+  if (!node.values || node.values.length === 0) {
+    return `<${node.id ?? ''}>`;
+  }
+  const head =
+    node.id === null || node.id === undefined ? '' : `<${node.id}>: `;
+  return `(${head}${node.values.map(render).join(' ')})`;
+}
+
+function parsesAs(source) {
+  return parser.parse(source).map(render).join('\n');
+}
+
+test('CR is a line break', () => {
+  expect(parsesAs('a\rb')).toBe('(<a>)\n(<b>)');
+  expect(parsesAs('a\r\nb')).toBe('(<a>)\n(<b>)');
+});
+
+test('only grammar whitespace makes an empty document', () => {
+  expect(parsesAs(' \t\n\r')).toBe('');
+  for (const character of ['\u0085', '\u00a0', '\u2028', '\u3000', '\ufeff']) {
+    expect(parsesAs(character)).toBe(`(<${character}>)`);
+  }
+});
+
+test('Unicode spaces are substantive even quote bodies', () => {
+  for (const character of ['\u0085', '\u00a0', '\u2028', '\u3000', '\ufeff']) {
+    expect(parsesAs(`''${character}''`)).toBe(`(<${character}>)`);
+  }
+});
+
+test('trailing indentation is document whitespace', () => {
+  expect(parsesAs('a\n  ')).toBe('(<a>)');
+  expect(parsesAs('a\n  \t')).toBe('(<a>)');
+});
+
+test('a single reference is a link value at every depth', () => {
+  expect(parsesAs('1')).toBe('(<1>)');
+  expect(parsesAs('(1)')).toBe('(<1>)');
+  expect(parsesAs('((1))')).toBe('((<1>))');
+});

package/tests/ParseErrorPosition.test.js

@@ -50,6 +50,14 @@ test('reports the line a late defect is on', () => {
   expect(error.lineText).toBe('e: f: g');
 });
 
+test('lone CR counts as one line break in diagnostics', () => {
+  const error = syntaxError('a\rb: c: d');
+
+  expect(error.line).toBe(2);
+  expect(error.column).toBe(5);
+  expect(error.lineText).toBe('b: c: d');
+});
+
 test('reports the end of the document when a group is never closed', () => {
   const error = syntaxError('a (b\n');
 

package/tests/StreamParser.test.js

@@ -0,0 +1,165 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  formatLinks,
+  Parser,
+  StreamParseError,
+  StreamParser,
+} from '../src/index.js';
+
+const document = `first loves data
+# streamed comment
+profile:
+  name Ada
+  note "line one
+line two"
+(nested:
+  child value)
+last sees first`;
+
+const formatted = (links) => formatLinks(links);
+
+describe('StreamParser', () => {
+  test('matches canonical parser one symbol at a time', () => {
+    const stream = new StreamParser();
+    for (const character of document) stream.write(character);
+
+    expect(formatted(stream.end())).toBe(
+      formatted(new Parser().parse(document))
+    );
+  });
+
+  test('supports line chunks final record and position', () => {
+    const stream = new StreamParser();
+    for (const line of document.match(/.*(?:\n|$)/g).filter(Boolean)) {
+      stream.write(line);
+    }
+
+    expect(formatted(stream.end())).toBe(
+      formatted(new Parser().parse(document))
+    );
+    expect(stream.position().offset).toBe(document.length);
+    expect(stream.position().buffered).toBe(0);
+  });
+
+  test('emits a record as soon as the next top-level record starts', () => {
+    const stream = new StreamParser();
+    const seen = [];
+    stream.on('link', (link) => seen.push(link.toString()));
+
+    expect(stream.write('first loves data\n')).toEqual([]);
+    expect(stream.write('s').map(String)).toEqual(['(first loves data)']);
+    expect(seen).toEqual(['(first loves data)']);
+  });
+
+  test('emits only complete records', () => {
+    const stream = new StreamParser();
+    const seen = [];
+    stream.on('link', (link) => seen.push(link));
+
+    for (const character of 'profile:\n  name Ada\n  role engineer\n') {
+      stream.write(character);
+    }
+    expect(seen).toEqual([]);
+
+    stream.write('n');
+    expect(formatted(seen)).toBe('(profile: (name Ada) (role engineer))');
+  });
+
+  test('does not split multiline quotes or parenthesized contexts', () => {
+    const stream = new StreamParser();
+    const seen = [];
+    stream.on('link', (link) => seen.push(link));
+
+    stream.write('"first\nsecond"\n(nested:\n  value one)\n');
+    expect(seen).toHaveLength(1);
+    stream.write('n');
+    expect(seen).toHaveLength(2);
+  });
+
+  test('accepts a final record without a newline', () => {
+    const stream = new StreamParser();
+    stream.write('only one record');
+    expect(formatted(stream.end())).toBe('(only one record)');
+  });
+
+  test('reports positions relative to the whole stream', () => {
+    const stream = new StreamParser();
+    stream.on('error', () => {});
+    stream.write('good link\nnext link\nb');
+
+    let caught;
+    try {
+      stream.end('ad: value: nope');
+    } catch (error) {
+      caught = error;
+    }
+    expect(caught).toBeInstanceOf(StreamParseError);
+    expect(caught.line).toBe(3);
+    expect(caught.offset).toBeGreaterThan('good link\nnext link\n'.length);
+  });
+
+  test('can avoid retaining output for bounded-memory event processing', () => {
+    const stream = new StreamParser({ collect: false });
+    const seen = [];
+    stream.on('link', (link) => seen.push(link.toString()));
+    stream.write('one link\nt');
+    expect(stream.drain()).toEqual([]);
+    expect(stream.end('wo link').map(String)).toEqual(['(two link)']);
+    expect(seen).toEqual(['(one link)', '(two link)']);
+  });
+
+  test('supports drain reset and bounded memory', () => {
+    const stream = new StreamParser();
+    stream.write('one link\nt');
+    expect(stream.drain().map(String)).toEqual(['(one link)']);
+    expect(stream.end('wo link').map(String)).toEqual(['(two link)']);
+
+    stream.reset().write('fresh record');
+    expect(stream.end().map(String)).toEqual(['(fresh record)']);
+
+    const bounded = new StreamParser({ maxBufferSize: 4 });
+    bounded.on('error', () => {});
+    expect(() => bounded.write('12345')).toThrow(RangeError);
+  });
+
+  test('provides lazy adapters', async () => {
+    expect(
+      [...StreamParser.parse(['one link\n', 'two link'])].map(String)
+    ).toEqual(['(one link)', '(two link)']);
+
+    async function* chunks() {
+      yield 'one link\n';
+      yield 'two link';
+    }
+    const links = [];
+    for await (const link of StreamParser.parseAsync(chunks())) {
+      links.push(link.toString());
+    }
+    expect(links).toEqual(['(one link)', '(two link)']);
+  });
+
+  test('limits only the unresolved record, not total stream size', () => {
+    const stream = new StreamParser({ maxBufferSize: 12, collect: false });
+    stream.on('error', () => {});
+    for (let index = 0; index < 100; index++) stream.write(`a${index}\n`);
+    expect(stream.end().map(String)).toEqual(['(a99)']);
+  });
+
+  test('rejects writes after finish', () => {
+    const stream = new StreamParser();
+    stream.end('one');
+    stream.on('error', () => {});
+    expect(() => stream.write('two')).toThrow('after end');
+  });
+
+  test('tracks the absolute stream position', () => {
+    const stream = new StreamParser();
+    stream.write('one\ntw');
+    expect(stream.position()).toEqual({
+      offset: 6,
+      line: 2,
+      column: 3,
+      buffered: 2,
+    });
+  });
+});