{"id":16114,"library":"markdown-parser","title":"Streaming Markdown Parser","description":"The `markdown-parser` library provides a robust and fully typed parser for Markdown content, adhering strictly to the CommonMark specification and including full support for GitHub Flavored Markdown (GFM) tables. Currently at version 0.1.1, its primary differentiation is its advanced streaming and incremental parsing capabilities, which are especially critical for applications consuming continuously arriving content, such as outputs from large language models or real-time communication systems. Unlike conventional Markdown parsers that necessitate complete input before generating an Abstract Syntax Tree (AST), `markdown-parser` can process text in chunks, emitting finalized block nodes as they become stable while internally managing the state of incomplete structures. This design allows for immediate display and dynamic manipulation of Markdown content without waiting for the entire stream to conclude. The library is engineered to produce a structured, typed AST, making it highly amenable to programmatic interaction, rendering, and analysis. While a formal release cadence is not explicitly stated, the early version number suggests active and iterative development.","status":"active","version":"0.1.1","language":"javascript","source_language":"en","source_url":null,"tags":["javascript"],"install":[{"cmd":"npm install markdown-parser","lang":"bash","label":"npm"},{"cmd":"yarn add markdown-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add markdown-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { MarkdownParser } = require('markdown-parser');","symbol":"MarkdownParser","correct":"import { MarkdownParser } from 'markdown-parser';"},{"note":"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.","symbol":"BlockNode","correct":"import type { BlockNode } from 'markdown-parser';"},{"note":"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.","symbol":"InlineNode","correct":"import type { InlineNode } from 'markdown-parser';"}],"quickstart":{"code":"import { MarkdownParser } from \"markdown-parser\";\nimport type { BlockNode } from \"markdown-parser\";\n\nconst parser = new MarkdownParser();\n\n// Example 1: Parse complete markdown in one go\nconst completeNodes: BlockNode[] = parser.parse(\"# Hello World\\nThis is a paragraph.\");\nconsole.log('Complete Parse Output:', JSON.stringify(completeNodes, null, 2));\n// Expected: [\n//   { type: \"heading\", level: 1, children: [{ type: \"text\", text: \"Hello World\" }] },\n//   { type: \"paragraph\", children: [{ type: \"text\", text: \"This is a paragraph.\" }] }\n// ]\n\n// Example 2: Parse with streaming mode for incremental content\nconsole.log('\\n--- Streaming Parse ---');\nlet streamOutput1: BlockNode[] = parser.parse(\"# Hello World\\nThis\", { stream: true });\nconsole.log('Stream Part 1:', JSON.stringify(streamOutput1, null, 2));\n// Expected: [\n//   { type: \"heading\", level: 1, children: [{ type: \"text\", text: \"Hello World\" }] }\n// ] (paragraph is still open)\n\nlet streamOutput2: BlockNode[] = parser.parse(\" is a paragraph\\n\\nThis is another paragraph.\", { stream: true });\nconsole.log('Stream Part 2:', JSON.stringify(streamOutput2, null, 2));\n// Expected: [\n//   { type: \"paragraph\", children: [{ type: \"text\", text: \"This is a paragraph.\" }] }\n// ] (second paragraph still open)\n\nlet streamOutput3: BlockNode[] = parser.parse(\"\", { stream: false }); // Finalize the stream\nconsole.log('Stream Finalize:', JSON.stringify(streamOutput3, null, 2));\n// Expected: [\n//   { type: \"paragraph\", children: [{ type: \"text\", text: \"This is another paragraph.\" }] }\n// ]\n\nconsole.log('\\n--- End Streaming Parse ---');\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.1"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.1.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.1"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Switch to ES module `import` syntax: `import { MarkdownParser } from 'markdown-parser';`.","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).","error":"ReferenceError: require is not defined"},{"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.","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.","error":"Some expected Markdown blocks are missing from the output when using streaming mode."},{"fix":"Ensure you correctly instantiate the parser class before calling its methods: `const parser = new MarkdownParser();` then `parser.parse(...)`.","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.","error":"TypeError: parser.parse is not a function"}],"ecosystem":"npm"}