xml-to-html-converter 0.1.7 → 0.1.8

package/README.md

@@ -15,9 +15,17 @@ A zero-dependency Node.js package for converting XML to HTML. Currently in pre-1
 Version `0.1.x` is focused entirely on parsing raw XML into a structured tree of nodes. The `scaffold` function walks an XML string and produces an array of `XmlNode` objects, each carrying its role, its raw source text, and its position in the document, both globally across the full document and locally within its parent.
 
 ```ts
+interface XmlAttribute {
+  name: string;
+  value: string;
+}
+
 interface XmlNode {
   role: XmlNodeRole;
   raw: string;
+  xmlTag?: string;
+  xmlInner?: string;
+  xmlAttributes?: XmlAttribute[];
   globalIndex: number;
   localIndex: number;
   children?: XmlNode[];
@@ -44,6 +52,7 @@ This scaffold is the foundation everything else will be built on. No transformat
 >
 > - **`scaffold(xml)`** reads any XML string and returns a nested node tree
 > - Every node knows its `role`, its `raw` source string, its `globalIndex` in the document, and its `localIndex` within its parent
+> - Tag nodes (`openTag`, `selfTag`) also carry `xmlTag`, `xmlInner`, and `xmlAttributes` — the parsed tag name, raw attribute string, and structured attribute array
 > - Broken XML is never thrown - malformed nodes are flagged with `malformed: true` in place and the tree is built regardless
 >
 > `v1.0.0` is when this package becomes what it says it is: a full XML-to-HTML converter. Everything before that is the work to get there.
@@ -92,12 +101,18 @@ const tree = scaffold(`
       {
         "role": "openTag",
         "raw": "<book category=\"cooking\">",
+        "xmlTag": "book",
+        "xmlInner": "category=\"cooking\"",
+        "xmlAttributes": [{ "name": "category", "value": "cooking" }],
         "globalIndex": 2,
         "localIndex": 0,
         "children": [
           {
             "role": "openTag",
             "raw": "<title lang=\"en\">",
+            "xmlTag": "title",
+            "xmlInner": "lang=\"en\"",
+            "xmlAttributes": [{ "name": "lang", "value": "en" }],
             "globalIndex": 3,
             "localIndex": 0,
             "children": [
@@ -122,14 +137,17 @@ const tree = scaffold(`
 
 Every node in the tree has the following fields:
 
-| Field         | Type          | Description                                         |
-| ------------- | ------------- | --------------------------------------------------- |
-| `role`        | `XmlNodeRole` | What kind of node this is                           |
-| `raw`         | `string`      | The exact source string, untouched                  |
-| `globalIndex` | `number`      | Position in the entire document (never resets)      |
-| `localIndex`  | `number`      | Position within the parent's children array         |
-| `children`    | `XmlNode[]`   | Present only on `openTag` - the nested nodes inside |
-| `malformed`   | `true`        | Present only when the structure is broken           |
+| Field           | Type             | Description                                                                                                           |
+| --------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `role`          | `XmlNodeRole`    | What kind of node this is                                                                                             |
+| `raw`           | `string`         | The exact source string, untouched                                                                                    |
+| `xmlTag`        | `string`         | Tag name only, e.g. `"book"` or `"env:Envelope"`. Present on `openTag`, `selfTag`, `closeTag`                         |
+| `xmlInner`      | `string`         | Everything after the tag name inside the brackets, verbatim. Present on `openTag` and `selfTag` when attributes exist |
+| `xmlAttributes` | `XmlAttribute[]` | Parsed array of `{ name, value }` attribute objects. Present on `openTag` and `selfTag` when attributes exist         |
+| `globalIndex`   | `number`         | Position in the entire document (never resets)                                                                        |
+| `localIndex`    | `number`         | Position within the parent's children array                                                                           |
+| `children`      | `XmlNode[]`      | Present only on `openTag` - the nested nodes inside                                                                   |
+| `malformed`     | `true`           | Present only when the structure is broken                                                                             |
 
 ---
 
@@ -151,11 +169,12 @@ Every node in the tree has the following fields:
 
 `scaffold` never throws. No matter what the input looks like, it always returns a complete tree. Malformed structures are flagged with `malformed: true` in place and the walk continues.
 
-Three cases are handled:
+Four cases are handled:
 
 - **Unclosed tags** - opens but never closes, gets `malformed: true`, children are still collected
 - **Stray closing tags** - a `</tag>` with no matching open surfaces as a `closeTag` token with `malformed: true`
 - **Unclosed brackets** - a `<` with no matching `>` captures the remainder as a malformed token
+- **Excessive nesting** - documents nested beyond 500 levels have the deepest open tag flagged `malformed: true` to prevent a stack overflow
 
 ```js
 const tree = scaffold("<root><unclosed><valid>text</valid></root>");
@@ -207,6 +226,7 @@ import { scaffold, isMalformed } from "xml-to-html-converter";
 import type {
   XmlNode,
   XmlNodeRole,
+  XmlAttribute,
   MalformedXmlNode,
 } from "xml-to-html-converter";
 ```
@@ -217,6 +237,7 @@ import type {
 | `isMalformed`      | function | Type guard, narrows `XmlNode` to `MalformedXmlNode` |
 | `XmlNode`          | type     | The shape of every node in the tree                 |
 | `XmlNodeRole`      | type     | Union of all valid role strings                     |
+| `XmlAttribute`     | type     | Shape of a parsed attribute `{ name, value }`       |
 | `MalformedXmlNode` | type     | `XmlNode` narrowed to `{ malformed: true }`         |
 
 ---

package/dist/index.d.ts

@@ -1,7 +1,14 @@
+interface XmlAttribute {
+    name: string;
+    value: string;
+}
 type XmlNodeRole = "closeTag" | "comment" | "doctype" | "openTag" | "processingInstruction" | "selfTag" | "textLeaf";
 interface XmlNode {
     role: XmlNodeRole;
     raw: string;
+    xmlTag?: string;
+    xmlInner?: string;
+    xmlAttributes?: XmlAttribute[];
     globalIndex: number;
     localIndex: number;
     children?: XmlNode[];
@@ -14,4 +21,4 @@ declare function isMalformed(node: XmlNode): node is MalformedXmlNode;
 
 declare function scaffold(xml: string): XmlNode[];
 
-export { type MalformedXmlNode, type XmlNode, type XmlNodeRole, isMalformed, scaffold };
+export { type MalformedXmlNode, type XmlAttribute, type XmlNode, type XmlNodeRole, isMalformed, scaffold };

package/dist/index.js

@@ -1,10 +1,38 @@
 // src/modules/scaffold/scaffold.ts
+function parseXmlAttributes(xmlInner) {
+  const attributes = [];
+  let i = 0;
+  const s = xmlInner.trim();
+  while (i < s.length) {
+    while (i < s.length && /\s/.test(s[i])) i++;
+    if (i >= s.length) break;
+    const nameStart = i;
+    while (i < s.length && s[i] !== "=" && !/\s/.test(s[i])) i++;
+    const name = s.slice(nameStart, i).trim();
+    if (!name) break;
+    while (i < s.length && /\s/.test(s[i])) i++;
+    if (s[i] !== "=") break;
+    i++;
+    while (i < s.length && /\s/.test(s[i])) i++;
+    const quote = s[i];
+    if (quote !== '"' && quote !== "'") break;
+    i++;
+    const valueStart = i;
+    while (i < s.length && s[i] !== quote) i++;
+    const value = s.slice(valueStart, i);
+    i++;
+    attributes.push({ name, value });
+  }
+  return attributes.length > 0 ? attributes : void 0;
+}
+var MAX_DEPTH = 500;
 function scaffold(xml) {
   const counter = { value: 0 };
-  const { xmlNodes } = collectXmlNodes(xml, 0, null, counter);
+  const { xmlNodes } = collectXmlNodes(xml, 0, null, counter, 0);
   return xmlNodes;
 }
-function collectXmlNodes(xml, position, parentTag, counter) {
+function collectXmlNodes(xml, position, parentTag, counter, depth) {
+  if (depth > MAX_DEPTH) return { xmlNodes: [], position, closed: false };
   const xmlNodes = [];
   while (position < xml.length) {
     const xmlNodeData = extractXmlNodes(xml, position);
@@ -18,6 +46,8 @@ function collectXmlNodes(xml, position, parentTag, counter) {
       xmlNodes.push({
         role: "closeTag",
         raw: xmlNodeData.raw,
+        xmlTag: xmlNodeData.tag || void 0,
+        xmlInner: xmlNodeData.xmlInner,
         globalIndex: counter.value++,
         localIndex: xmlNodes.length,
         malformed: true
@@ -32,11 +62,15 @@ function collectXmlNodes(xml, position, parentTag, counter) {
         xml,
         xmlNodeData.end,
         xmlNodeData.tag,
-        counter
+        counter,
+        depth + 1
       );
       const xmlNode2 = {
         role: "openTag",
         raw: xmlNodeData.raw,
+        xmlTag: xmlNodeData.tag || void 0,
+        xmlInner: xmlNodeData.xmlInner,
+        xmlAttributes: xmlNodeData.xmlAttributes,
         globalIndex,
         localIndex,
         children: nested.xmlNodes
@@ -49,6 +83,9 @@ function collectXmlNodes(xml, position, parentTag, counter) {
     const xmlNode = {
       role: xmlNodeData.role,
       raw: xmlNodeData.raw,
+      xmlTag: xmlNodeData.tag || void 0,
+      xmlInner: xmlNodeData.xmlInner,
+      xmlAttributes: xmlNodeData.xmlAttributes,
       globalIndex: counter.value++,
       localIndex: xmlNodes.length
     };
@@ -141,14 +178,20 @@ function extractXmlNodes(xml, position) {
   const inner = xml.slice(position + 1, closeAt).trim();
   if (inner.startsWith("/")) {
     const tag2 = inner.slice(1).trim().split(/\s/)[0] ?? "";
-    return { raw, role: "closeTag", tag: tag2, end };
+    const xmlInner2 = inner.slice(1).trim().slice(tag2.length).trim() || void 0;
+    return { raw, role: "closeTag", tag: tag2, xmlInner: xmlInner2, end };
   }
   if (inner.endsWith("/")) {
-    const tag2 = inner.slice(0, -1).trim().split(/\s/)[0] ?? "";
-    return { raw, role: "selfTag", tag: tag2, end };
+    const trimmed = inner.slice(0, -1).trim();
+    const tag2 = trimmed.split(/\s/)[0] ?? "";
+    const xmlInner2 = trimmed.slice(tag2.length).trim() || void 0;
+    const xmlAttributes2 = xmlInner2 ? parseXmlAttributes(xmlInner2) : void 0;
+    return { raw, role: "selfTag", tag: tag2, xmlInner: xmlInner2, xmlAttributes: xmlAttributes2, end };
   }
   const tag = inner.split(/\s/)[0] ?? "";
-  return { raw, role: "openTag", tag, end };
+  const xmlInner = inner.slice(tag.length).trim() || void 0;
+  const xmlAttributes = xmlInner ? parseXmlAttributes(xmlInner) : void 0;
+  return { raw, role: "openTag", tag, xmlInner, xmlAttributes, end };
 }
 
 // src/modules/scaffold/types.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xml-to-html-converter",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Zero dependency XML to HTML converter for Node environments",
   "type": "module",
   "main": "./dist/index.js",