markdown-parser 0.0.8 → 0.1.0

package/{MIT-LICENSE.txt → LICENSE}

@@ -1,20 +1,21 @@
-The MIT License (MIT)
-Copyright (c) 2013 Julien Valéry
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Nimesh Nayaju
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,175 +1,95 @@
-# MarkdownParser [![NPM version](https://badge.fury.io/js/markdown-parser.png)](http://badge.fury.io/js/markdown-parser) [![Build Status](https://travis-ci.org/darul75/markdown-parser.png?branch=master)](https://travis-ci.org/darul75/markdown-parser) [![Total views](https://sourcegraph.com/api/repos/github.com/darul75/markdown-parser/counters/views.png)](https://sourcegraph.com/github.com/darul75/markdown-parser)
-
-NodeJS module markdown syntax extractor.
-
-## Why ?
-
-I was looking to extract links from [github markdown](https://guides.github.com/features/mastering-markdown/) readme files.
-
-## Demo
-
-http://darul75.github.io/markdown-parser/
-
-## Features
-
-Extraction of following markdown elements:
-- bold
-- code
-- heading
-- italic
-- reference (link, images)
-- lists
-- listsOrdered
-- sections
-- strikethroughs
-- tasks
-
-## Install
-
-~~~
-npm install markdown-parser
-~~~
-
-## Usage
-
-```javascript
-var Parser = require('markdown-parser');
-
-var parser = new Parser();
-
-// options repository url
-// var parser = new Parser({html_url: "https://github.com/darul75/markdown-parser"});
-
-// fetch by api or what else
-var markdownContent = ".....";
-
-parser.parse(markdownContent, function(err, result) {
-// result example
-/*
-{
-   "bolds": [
-      "No JQUERY dependency needed anymore"
-   ],
-   "codes": [
-      {
-         "type": "html",
-         "code": "<script type=\"text/javascript\" src=\"angular.min.js\"></script>"
-      },
-      {
-         "type": "html",
-         "code": "<link rel=\"stylesheet\" type=\"text/css\" href=\"ng-slider.min.css\">"
-      }
-   ],
-   "headings": [
-      " Options",
-      " Build",
-      " Issue",
-      " Metrics",
-      " License"
-   ],
-   "italics": [],
-   "references": [
-      {
-         "title": "![NPM version",
-         "href": "https://badge.fury.io/js/ng-slider.png",
-         "image": true
-      },
-      {
-         "title": "angular slider demo",
-         "href": "http://darul75.github.io/ng-slider/images/slider1.png \"angular slider demo screenshot\"",
-         "image": true
-      }
-   ],
-   "lists": [
-      [
-         "`from`: start value",
-         "`to`: end value",
-         "`step`: step value",
-         "`dimension`: string, example \" $\"",
-         "`scale`: array for scale",
-         "`round`: how many numbers allowed after comma",
-         "`smooth`: true/false; false snaps the button to value",
-         "`vertical`: true/false; vertical slider, default false",
-         "`css`: hash object"
-      ],
-      [
-         "`callback` : function triggering current value, can be useful"
-      ],
-      [
-         "2.1.3: bug fixes, refactoring, inline options param",
-         "2.1.2: bug fixes, changes in z-index via CSS and not js",
-         "2.1.1: override css, colors...",
-         "2.1.0: bug fixes",
-         "2.0.0: no JQuery"
-      ]
-   ],
-   "listsOrdered": [],
-   "sections": [
-      "Why",
-      "Screenshot",
-      "Demo",
-      "How to use it",
-      "Installation",
-      "RELEASE"
-   ],
-   "strikethroughs": [],
-   "tasks": []
-}
-
-*/
-  
-});
-```
-    
-## Return    
-```json
-{
-  "bolds": [],
-  "codes": [],
-  "headings": [],
-  "italics": [],
-  "references": [],
-  "lists": [],
-  "listsOrdered": [],
-  "sections": [],
-  "strikethroughs": [],
-  "tasks": []
-}
-```
-
-### Options
-
-* `html_url`: repository url, used for link references, ex: "https://github.com/darul75/markdown-parser"
-
-## TODO
-- [ ] Finish tests
-- [ ] Browserify
-- [ ] Missing markdown
-
-## Metrics
-
-[![NPM](https://nodei.co/npm/markdown-parser.png?downloads=true&downloadRank=true&stars=true)](https://nodei.co/npm/markdown-parser/)
-
-## License
-
-The MIT License (MIT)
-
-Copyright (c) 2015 Julien Valéry
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+# `markdown-parser`
+
+A markdown parser with streaming support, suitable for incrementally parsing LLM markdown streams. Parses markdown into a structured fully typed tree of nodes, following the [CommonMark](https://commonmark.org/) specification. It supports streaming/incremental parsing, so you can feed it growing input and emit only the blocks that have become finalized.
+
+## Installation
+
+```bash
+npm install markdown-parser
+```
+
+## Usage
+
+```typescript
+import { MarkdownParser } from "markdown-parser";
+
+const parser = new MarkdownParser();
+
+// Parse complete markdown
+const nodes = parser.parse("# Hello World\nThis is a paragraph.");
+// [
+//   { type: "heading", level: 1, children: [{ type: "text", text: "Hello World" }] },
+//   { type: "paragraph", children: [{ type: "text", text: "This is a paragraph." }] }
+// ]
+
+// Parse with streaming mode (for incremental content)
+const partialNodes = parser.parse("# Hello World\nThis", { stream: true });
+// Emits heading, but not the paragraph (still open)
+// [
+//   { type: "heading", level: 1, children: [{ type: "text", text: "Hello World" }] },
+// ]
+
+// Continue parsing as more content arrives
+const moreNodes = parser.parse(" is a paragraph\n\nThis is another paragraph.", { stream: true });
+// Emits the paragraph
+// [
+//   { type: "paragraph", children: [{ type: "text", text: "This is a paragraph." }] }
+// ]
+
+const finalNodes = parse.parse("", { stream: false })
+// Closes anything still open and emits remaining blocks
+// [
+//   { type: "paragraph", children: [{ type: "text", text: "This is another paragraph." }] }
+// ]
+```
+
+When stream is false (default), the parser finalizes all open blocks at the end of the input and returns the full set of blocks (for that input). When you parse in streaming mode, the parser keeps internal state across calls and returns only blocks that have become closed and stable since the last call.
+
+## API
+
+### `MarkdownParser`
+
+The main parser class that converts markdown text into a structured block AST (headings, paragraphs, lists, etc.).
+
+#### `parse(text: string, options?: { stream: boolean }): BlockNode[]`
+
+Parses markdown text and returns an array of block nodes.
+
+- `text` - The markdown text to parse
+- `options.stream` - When `true`, enables streaming mode which buffers incomplete blocks until they can be fully parsed. Defaults to `false`.
+
+## Supported Nodes
+
+The parser provides 100% support for the CommonMark specification, and includes full support for GitHub Flavored Markdown (GFM) tables.
+
+### Block nodes
+
+- [x] Heading (ATX and setext style)
+- [x] Paragraph
+- [x] Code block (fenced and indented)
+- [x] Thematic break (horizontal rule)
+- [x] HTML block
+- [x] Blockquote
+- [x] List (ordered and unordered)
+- [x] Link reference definitions
+- [x] Table (GFM)
+
+### Inline nodes
+
+- [x] Text
+- [x] Code span
+- [x] Hard break
+- [x] Soft break
+- [x] HTML (inline)
+- [x] Autolink
+- [x] Link
+- [x] Image
+- [x] Emphasis
+- [x] Strong
+
+## Some notes on the implementation
+
+The implementation is inspired by various other markdown parsers, including [commonmark.js](https://github.com/commonmark/commonmark.js), [markdown-it](https://github.com/markdown-it/markdown-it), and [marked.js](https://github.com/markedjs/marked). In fact, the implementation is structurally very similar to how commonmark.js goes about parsing; the only major difference is how we decide which lines to parse when streaming is set to true. I started with a much simpler and a lot more readable implementation for the parser, but it became complex when adding block container (blockquote and lists) support, so I ended up going for a slightly complex solution but a more robust and extensible one.
+
+Commonmark specification allows link reference definitions to appear after the links that use them. Therefore, when streaming is enabled, it is important to consider that a link reference might not resolve, since its definition could arrive in a later chunk of the input.
+

package/dist/index.d.ts

@@ -0,0 +1,112 @@
+interface CodeSpanNode {
+    type: "code-span";
+    text: string;
+}
+interface TextNode {
+    type: "text";
+    text: string;
+}
+interface HardBreakNode {
+    type: "hardbreak";
+}
+interface SoftBreakNode {
+    type: "softbreak";
+}
+interface StrongNode {
+    type: "strong";
+    children: Array<InlineNode>;
+}
+interface EmphasisNode {
+    type: "emphasis";
+    children: Array<InlineNode>;
+}
+interface LinkNode {
+    type: "link";
+    href: string;
+    title?: string;
+    children: Array<InlineNode>;
+}
+interface ImageNode {
+    type: "image";
+    href: string;
+    title?: string;
+    children: Array<InlineNode>;
+}
+interface HtmlTagNode {
+    type: "html";
+    content: string;
+}
+type InlineNode = TextNode | CodeSpanNode | HardBreakNode | SoftBreakNode | StrongNode | EmphasisNode | LinkNode | ImageNode | HtmlTagNode;
+
+declare class MarkdownParser {
+    private splitter;
+    private root;
+    private nextLineIndex;
+    private nextNodeIndex;
+    private referenceDefinitions;
+    parse(input: string, options?: {
+        stream?: boolean;
+    }): BlockNode[];
+    private parseLine;
+    private parseReferenceLinkDefinitions;
+    private convertInternalBlockToPublicBlock;
+}
+interface TableNode {
+    type: "table";
+    head: {
+        cells: Array<{
+            align: "left" | "right" | "center" | undefined;
+            children: Array<InlineNode>;
+        }>;
+    };
+    body: {
+        rows: Array<{
+            cells: Array<{
+                align: "left" | "right" | "center" | undefined;
+                children: Array<InlineNode>;
+            }>;
+        }>;
+    };
+}
+interface ThematicBreakNode {
+    type: "thematic-break";
+}
+interface CodeBlockNode {
+    type: "code-block";
+    info?: string;
+    content: string;
+}
+interface BlockquoteNode {
+    type: "blockquote";
+    children: Array<BlockNode>;
+}
+type ListNode = {
+    type: "list";
+    tight: boolean;
+    items: Array<{
+        children: Array<BlockNode>;
+    }>;
+} & ({
+    kind: "ordered";
+    start: number;
+} | {
+    kind: "unordered";
+    marker: string;
+});
+interface HtmlBlockNode {
+    type: "html-block";
+    content: string;
+}
+interface HeadingNode {
+    type: "heading";
+    level: 1 | 2 | 3 | 4 | 5 | 6;
+    children: Array<InlineNode>;
+}
+interface ParagraphNode {
+    type: "paragraph";
+    children: Array<InlineNode>;
+}
+type BlockNode = TableNode | ThematicBreakNode | CodeBlockNode | HeadingNode | ParagraphNode | BlockquoteNode | ListNode | HtmlBlockNode;
+
+export { MarkdownParser };
+export type { BlockNode, InlineNode };