Streaming Markdown Parser

Common errors

• ReferenceError: require is not defined

  cause Attempting to use the CommonJS `require()` syntax to import `markdown-parser` in an environment configured for ES modules (e.g., a Node.js project with `"type": "module"` in `package.json` or direct execution of `.mjs` files).
  fix Switch to ES module `import` syntax: `import { MarkdownParser } from 'markdown-parser';`.

• Some expected Markdown blocks are missing from the output when using streaming mode.

  cause When `stream: true` is enabled, the parser only emits blocks that have been fully closed and are stable. If the input ends prematurely or the stream is not explicitly finalized, any incomplete or buffered blocks will not be returned.
  fix After providing all available input chunks, make a final call to `parser.parse('', { stream: false })` to force the parser to finalize and emit any remaining buffered blocks. This signals the end of the stream.

• TypeError: parser.parse is not a function

  cause This error typically occurs when attempting to call the `parse` method directly on the imported module object rather than on an instance of the `MarkdownParser` class.
  fix Ensure you correctly instantiate the parser class before calling its methods: `const parser = new MarkdownParser();` then `parser.parse(...)`.

Warnings

• gotcha When utilizing the streaming mode, it's crucial to understand that link reference definitions (e.g., `[label]: url`) might not resolve immediately if their corresponding definitions arrive in subsequent input chunks. The parser processes content sequentially, and any link references that precede their definitions will remain unresolved until the definitions are fed into the stream and the relevant blocks are finalized.
  Fix: To ensure all link references are correctly resolved, always feed all definition-containing chunks to the parser. Crucially, call `parser.parse('', { stream: false })` as the final step when all input has been provided to explicitly finalize the stream and allow the parser to resolve any remaining references. If displaying partial streams, handle potentially unresolved links gracefully in your rendering logic.
• breaking As this package is in its very early stages (v0.1.x), the API is considered unstable. Breaking changes, including alterations to node structures, parser options, or method signatures, are highly likely to occur in minor or even patch versions as the API matures towards a stable v1.0.0 release. Updates may require code adjustments.
  Fix: It is strongly recommended to regularly consult the package's changelog or GitHub repository for any breaking changes before upgrading. For production environments, pinning to exact patch versions (`~0.1.x` or `0.1.x`) is advisable until a stable major release (v1.0.0) is available.
• gotcha The parser's `parse` method maintains internal state when `stream: true` is used. This means that a single `MarkdownParser` instance should be used for a continuous stream of input. Starting a new, unrelated stream requires a new `MarkdownParser` instance or careful management of the state, though the latter is not directly exposed.
  Fix: For each distinct Markdown document or stream, instantiate a new `MarkdownParser`. Reusing an instance for unrelated content after a streaming parse without full finalization can lead to corrupted ASTs due to lingering internal state.

Install

• npm install markdown-parser npm
• yarn add markdown-parser yarn
• pnpm add markdown-parser pnpm

Imports

• MarkdownParser
  wrong:

  const { MarkdownParser } = require('markdown-parser');

  correct:

  import { MarkdownParser } from 'markdown-parser';

  This package targets Node.js >=18 and is primarily designed for ES module (ESM) usage. While CommonJS might technically work via transpilation or bundlers, native ESM imports are the recommended and intended way to consume this library.
• BlockNode

  import type { BlockNode } from 'markdown-parser';

  The `BlockNode` type represents a parsed block-level Markdown element (e.g., heading, paragraph, list). Importing this type is useful for type-checking and understanding the structure of the AST returned by the parser.
• InlineNode

  import type { InlineNode } from 'markdown-parser';

  The `InlineNode` type defines inline Markdown elements (e.g., text, emphasis, code span) which typically exist as children within `BlockNode` structures. Useful for detailed AST traversal.

Quickstart

This quickstart demonstrates both synchronous parsing of a complete Markdown string and the library's core feature: streaming/incremental parsing, where content is fed in chunks and finalized blocks are emitted progressively.

import { MarkdownParser } from "markdown-parser";
import type { BlockNode } from "markdown-parser";

const parser = new MarkdownParser();

// Example 1: Parse complete markdown in one go
const completeNodes: BlockNode[] = parser.parse("# Hello World\nThis is a paragraph.");
console.log('Complete Parse Output:', JSON.stringify(completeNodes, null, 2));
// Expected: [
//   { type: "heading", level: 1, children: [{ type: "text", text: "Hello World" }] },
//   { type: "paragraph", children: [{ type: "text", text: "This is a paragraph." }] }
// ]

// Example 2: Parse with streaming mode for incremental content
console.log('\n--- Streaming Parse ---');
let streamOutput1: BlockNode[] = parser.parse("# Hello World\nThis", { stream: true });
console.log('Stream Part 1:', JSON.stringify(streamOutput1, null, 2));
// Expected: [
//   { type: "heading", level: 1, children: [{ type: "text", text: "Hello World" }] }
// ] (paragraph is still open)

let streamOutput2: BlockNode[] = parser.parse(" is a paragraph\n\nThis is another paragraph.", { stream: true });
console.log('Stream Part 2:', JSON.stringify(streamOutput2, null, 2));
// Expected: [
//   { type: "paragraph", children: [{ type: "text", text: "This is a paragraph." }] }
// ] (second paragraph still open)

let streamOutput3: BlockNode[] = parser.parse("", { stream: false }); // Finalize the stream
console.log('Stream Finalize:', JSON.stringify(streamOutput3, null, 2));
// Expected: [
//   { type: "paragraph", children: [{ type: "text", text: "This is another paragraph." }] }
// ]

console.log('\n--- End Streaming Parse ---');