xml-to-html-converter 0.3.1 → 0.4.1

package/README.md

@@ -6,72 +6,49 @@
 ![XML](https://img.shields.io/badge/input-XML-orange)
 ![HTML](https://img.shields.io/badge/output-HTML-red)
 
-A zero-dependency Node.js package for converting XML to HTML. Currently in pre-1.0.0 development, building the foundation one functional part at a time. Full XML-to-HTML conversion is the goal of `v1.0.0`.
+A zero-dependency Node.js package for converting XML to HTML.
 
----
+- **`minify(xml)`** strips inter-tag whitespace from prettified XML before parsing. Text content is left untouched
+- **`scaffold(xml)`** reads any XML string and returns a nested node tree
+- **`walk(nodes, visitor)`** traverses the full node tree depth-first, visiting every node
+- **`render(nodes)`** converts a node tree to an HTML string. Every XML element becomes a `<div>` with `data-tag` and `data-attrs-*` attributes
 
-## XML Node Extraction & Scaffolding
+---
 
-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.
+## Install
 
-```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[];
-  malformed?: true;
-}
-
-type XmlNodeRole =
-  | "closeTag"
-  | "comment"
-  | "doctype"
-  | "openTag"
-  | "processingInstruction"
-  | "selfTag"
-  | "textLeaf";
+```bash
+npm install xml-to-html-converter
 ```
 
-This scaffold is the foundation everything else will be built on. No transformation, no HTML output, no opinions about content, just an accurate, traversable representation of what the XML says.
-
 ---
 
-> **Where I am right now**
->
-> `v0.x` is building the scaffold and the first render pass.
->
-> - **`minify(xml)`** strips inter-tag whitespace from prettified XML before parsing — text content is left untouched
-> - **`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
-> - **`render(nodes)`** takes the scaffold output and converts it to an HTML string — every XML element becomes a `<div>` with `data-tag` and `data-attrs-*` attributes
->
-> `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.
+## Usage
 
----
+### minify
 
-## Install
+When your XML comes from a file or an API it is usually indented and line-broken. `minify` strips the whitespace between tags before parsing. Text content is left completely untouched.
 
-```bash
-npm install xml-to-html-converter
+```js
+import { minify } from "xml-to-html-converter";
+
+const clean = minify(`
+  <bookstore>
+    <book category="cooking">
+      <title lang="en">Everyday Italian</title>
+    </book>
+  </bookstore>
+`);
+// <bookstore><book category="cooking"><title lang="en">Everyday Italian</title></book></bookstore>
 ```
 
+`minify` is opt-in. Skip it if whitespace inside your content is meaningful.
+
 ---
 
-## Usage
+### scaffold
 
-### Parsing XML into a node tree
+`scaffold` parses an XML string into a structured tree of `XmlNode` objects. Each node carries its role, its raw source text, and its position in the document both globally across the full document and locally within its parent.
 
 ```js
 import { scaffold } from "xml-to-html-converter";
@@ -135,7 +112,43 @@ const tree = scaffold(`
 ]
 ```
 
-### Converting the tree to HTML
+`scaffold` never throws. Malformed structures are flagged with `malformed: true` in place and the tree is built regardless. See [Malformed XML](#malformed-xml) for details.
+
+---
+
+### walk
+
+`walk` traverses the full node tree depth-first, calling a visitor function on every node including all descendants. The visitor decides what to collect or do. `walk` has no opinions.
+
+```js
+import { scaffold, walk } from "xml-to-html-converter";
+
+const tree = scaffold(xml);
+
+// collect all text content
+const text = [];
+walk(tree, (node) => {
+  if (node.role === "textLeaf") text.push(node.raw);
+});
+
+// find all nodes with a specific tag
+const titles = [];
+walk(tree, (node) => {
+  if (node.xmlTag === "title") titles.push(node);
+});
+
+// check for malformed nodes anywhere in the tree
+const broken = [];
+walk(tree, (node) => {
+  if (node.malformed) broken.push(node);
+});
+```
+
+---
+
+### render
+
+`render` walks the node tree and converts every XML element to a `<div>`. The original tag name is preserved in `data-tag` and each attribute becomes its own `data-attrs-*` attribute.
 
 ```js
 import { scaffold, render } from "xml-to-html-converter";
@@ -151,8 +164,6 @@ const html = render(
 );
 ```
 
-`render` walks the node tree and converts every XML element to a `<div>`. The original tag name is preserved in `data-tag` and each attribute becomes its own `data-attrs-*` attribute:
-
 ```html
 <div data-tag="bookstore">
   <div data-tag="book" data-attrs-category="cooking">
@@ -161,21 +172,23 @@ const html = render(
 </div>
 ```
 
-Processing instructions and doctypes are dropped. Comments are passed through unchanged.
+Processing instructions and doctypes are dropped. Comments are passed through unchanged. The output is a raw HTML string — if you are inserting it into a web page, treat it accordingly.
 
 ---
 
-### Minifying prettified XML
-
-When your XML comes from a file or an API it is usually indented and line-broken. `minify` strips the whitespace between tags before parsing, leaving text content completely untouched.
+### Full pipeline
 
 ```js
-import { minify, scaffold, render } from "xml-to-html-converter";
+import { minify, scaffold, walk, render } from "xml-to-html-converter";
 
-const html = render(scaffold(minify(xml)));
-```
+const tree = scaffold(minify(xml));
 
-`minify` is opt-in. Skip it if whitespace inside your content is meaningful.
+walk(tree, (node) => {
+  if (node.malformed) console.warn("malformed node", node.raw);
+});
+
+const html = render(tree);
+```
 
 ---
 
@@ -187,7 +200,7 @@ Every node in the tree has the following fields:
 | --------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------- |
 | `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`                         |
+| `xmlTag`        | `string`         | Tag name only, e.g. `"book"` or `"env:Envelope"`. Present on `openTag`, `selfTag`, and `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)                                                                        |
@@ -215,11 +228,15 @@ 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.
 
-Four cases are handled:
+Eight 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
+- **Unquoted attributes** - `<tag attr=unquoted>` flags the node `malformed: true`, any valid attributes parsed before the error are preserved
+- **Unclosed processing instructions** - `<?xml ...` with no `?>` captures the remainder as a malformed token
+- **Unclosed comments** - `<!-- ...` with no `-->` captures the remainder as a malformed token
+- **Unclosed CDATA** - `<![CDATA[ ...` with no `]]>` 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
@@ -268,7 +285,13 @@ const tree = scaffold("<root><unclosed><valid>text</valid></root>");
 ## Exports
 
 ```ts
-import { scaffold, render, minify, isMalformed } from "xml-to-html-converter";
+import {
+  minify,
+  scaffold,
+  walk,
+  render,
+  isMalformed,
+} from "xml-to-html-converter";
 import type {
   XmlNode,
   XmlNodeRole,
@@ -277,16 +300,17 @@ import type {
 } from "xml-to-html-converter";
 ```
 
-| Export             | Kind     | Description                                         |
-| ------------------ | -------- | --------------------------------------------------- |
-| `minify`           | function | Strips inter-tag whitespace from an XML string      |
-| `scaffold`         | function | Parses an XML string and returns a node tree        |
-| `render`           | function | Converts a node tree to an HTML string              |
-| `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 }`         |
+| Export             | Kind     | Description                                             |
+| ------------------ | -------- | ------------------------------------------------------- |
+| `minify`           | function | Strips inter-tag whitespace from an XML string          |
+| `scaffold`         | function | Parses an XML string and returns a node tree            |
+| `walk`             | function | Traverses a node tree depth-first with a visitor        |
+| `render`           | function | Converts a node tree to an HTML string                  |
+| `isMalformed`      | function | Type guard that 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 nodes where `malformed` is `true` |
 
 ---
 

package/dist/index.cjs

@@ -23,13 +23,14 @@ __export(src_exports, {
   isMalformed: () => isMalformed,
   minify: () => minify,
   render: () => render,
-  scaffold: () => scaffold
+  scaffold: () => scaffold,
+  walk: () => walk
 });
 module.exports = __toCommonJS(src_exports);
 
 // src/modules/minify/minify.ts
 function minify(xml) {
-  return xml.replace(/>(\s+)</g, (_, gap) => gap.trim() === "" ? "><" : `>${gap}<`).trim();
+  return xml.replace(/>(\s+)</g, "><").trim();
 }
 
 // src/modules/render/render.ts
@@ -73,7 +74,12 @@ function parseXmlAttributes(xmlInner) {
     i++;
     while (i < s.length && /\s/.test(s[i])) i++;
     const quote = s[i];
-    if (quote !== '"' && quote !== "'") break;
+    if (quote !== '"' && quote !== "'") {
+      return {
+        attributes: attributes.length > 0 ? attributes : void 0,
+        malformed: true
+      };
+    }
     i++;
     const valueStart = i;
     while (i < s.length && s[i] !== quote) i++;
@@ -81,7 +87,10 @@ function parseXmlAttributes(xmlInner) {
     i++;
     attributes.push({ name, value });
   }
-  return attributes.length > 0 ? attributes : void 0;
+  return {
+    attributes: attributes.length > 0 ? attributes : void 0,
+    malformed: false
+  };
 }
 var MAX_DEPTH = 500;
 function scaffold(xml) {
@@ -184,7 +193,8 @@ function extractXmlNodes(xml, position) {
       raw: xml.slice(position),
       role: "processingInstruction",
       tag: "",
-      end: xml.length
+      end: xml.length,
+      malformed: true
     } : {
       raw: xml.slice(position, end2 + 2),
       role: "processingInstruction",
@@ -194,7 +204,7 @@ function extractXmlNodes(xml, position) {
   }
   if (xml[position + 1] === "!" && xml[position + 2] === "[") {
     const end2 = xml.indexOf("]]>", position + 3);
-    return end2 === -1 ? { raw: xml.slice(position), role: "textLeaf", tag: "", end: xml.length } : {
+    return end2 === -1 ? { raw: xml.slice(position), role: "textLeaf", tag: "", end: xml.length, malformed: true } : {
       raw: xml.slice(position, end2 + 3),
       role: "textLeaf",
       tag: "",
@@ -203,7 +213,7 @@ function extractXmlNodes(xml, position) {
   }
   if (xml[position + 1] === "!" && xml[position + 2] === "-" && xml[position + 3] === "-") {
     const end2 = xml.indexOf("-->", position + 4);
-    return end2 === -1 ? { raw: xml.slice(position), role: "comment", tag: "", end: xml.length } : {
+    return end2 === -1 ? { raw: xml.slice(position), role: "comment", tag: "", end: xml.length, malformed: true } : {
       raw: xml.slice(position, end2 + 3),
       role: "comment",
       tag: "",
@@ -243,23 +253,32 @@ function extractXmlNodes(xml, position) {
     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 parsed2 = xmlInner2 ? parseXmlAttributes(xmlInner2) : void 0;
+    return { raw, role: "selfTag", tag: tag2, xmlInner: xmlInner2, xmlAttributes: parsed2?.attributes, end, malformed: parsed2?.malformed ? true : void 0 };
   }
   const tag = inner.split(/\s/)[0] ?? "";
   const xmlInner = inner.slice(tag.length).trim() || void 0;
-  const xmlAttributes = xmlInner ? parseXmlAttributes(xmlInner) : void 0;
-  return { raw, role: "openTag", tag, xmlInner, xmlAttributes, end };
+  const parsed = xmlInner ? parseXmlAttributes(xmlInner) : void 0;
+  return { raw, role: "openTag", tag, xmlInner, xmlAttributes: parsed?.attributes, end, malformed: parsed?.malformed ? true : void 0 };
 }
 
 // src/modules/scaffold/types.ts
 function isMalformed(node) {
   return node.malformed === true;
 }
+
+// src/modules/walk/walk.ts
+function walk(nodes, visitor) {
+  for (const node of nodes) {
+    visitor(node);
+    if (node.children) walk(node.children, visitor);
+  }
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   isMalformed,
   minify,
   render,
-  scaffold
+  scaffold,
+  walk
 });

package/dist/index.d.cts

@@ -25,4 +25,6 @@ declare function render(nodes: XmlNode[]): string;
 
 declare function scaffold(xml: string): XmlNode[];
 
-export { type MalformedXmlNode, type XmlAttribute, type XmlNode, type XmlNodeRole, isMalformed, minify, render, scaffold };
+declare function walk(nodes: XmlNode[], visitor: (node: XmlNode) => void): void;
+
+export { type MalformedXmlNode, type XmlAttribute, type XmlNode, type XmlNodeRole, isMalformed, minify, render, scaffold, walk };

package/dist/index.d.ts

@@ -25,4 +25,6 @@ declare function render(nodes: XmlNode[]): string;
 
 declare function scaffold(xml: string): XmlNode[];
 
-export { type MalformedXmlNode, type XmlAttribute, type XmlNode, type XmlNodeRole, isMalformed, minify, render, scaffold };
+declare function walk(nodes: XmlNode[], visitor: (node: XmlNode) => void): void;
+
+export { type MalformedXmlNode, type XmlAttribute, type XmlNode, type XmlNodeRole, isMalformed, minify, render, scaffold, walk };

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/modules/minify/minify.ts
 function minify(xml) {
-  return xml.replace(/>(\s+)</g, (_, gap) => gap.trim() === "" ? "><" : `>${gap}<`).trim();
+  return xml.replace(/>(\s+)</g, "><").trim();
 }
 
 // src/modules/render/render.ts
@@ -44,7 +44,12 @@ function parseXmlAttributes(xmlInner) {
     i++;
     while (i < s.length && /\s/.test(s[i])) i++;
     const quote = s[i];
-    if (quote !== '"' && quote !== "'") break;
+    if (quote !== '"' && quote !== "'") {
+      return {
+        attributes: attributes.length > 0 ? attributes : void 0,
+        malformed: true
+      };
+    }
     i++;
     const valueStart = i;
     while (i < s.length && s[i] !== quote) i++;
@@ -52,7 +57,10 @@ function parseXmlAttributes(xmlInner) {
     i++;
     attributes.push({ name, value });
   }
-  return attributes.length > 0 ? attributes : void 0;
+  return {
+    attributes: attributes.length > 0 ? attributes : void 0,
+    malformed: false
+  };
 }
 var MAX_DEPTH = 500;
 function scaffold(xml) {
@@ -155,7 +163,8 @@ function extractXmlNodes(xml, position) {
       raw: xml.slice(position),
       role: "processingInstruction",
       tag: "",
-      end: xml.length
+      end: xml.length,
+      malformed: true
     } : {
       raw: xml.slice(position, end2 + 2),
       role: "processingInstruction",
@@ -165,7 +174,7 @@ function extractXmlNodes(xml, position) {
   }
   if (xml[position + 1] === "!" && xml[position + 2] === "[") {
     const end2 = xml.indexOf("]]>", position + 3);
-    return end2 === -1 ? { raw: xml.slice(position), role: "textLeaf", tag: "", end: xml.length } : {
+    return end2 === -1 ? { raw: xml.slice(position), role: "textLeaf", tag: "", end: xml.length, malformed: true } : {
       raw: xml.slice(position, end2 + 3),
       role: "textLeaf",
       tag: "",
@@ -174,7 +183,7 @@ function extractXmlNodes(xml, position) {
   }
   if (xml[position + 1] === "!" && xml[position + 2] === "-" && xml[position + 3] === "-") {
     const end2 = xml.indexOf("-->", position + 4);
-    return end2 === -1 ? { raw: xml.slice(position), role: "comment", tag: "", end: xml.length } : {
+    return end2 === -1 ? { raw: xml.slice(position), role: "comment", tag: "", end: xml.length, malformed: true } : {
       raw: xml.slice(position, end2 + 3),
       role: "comment",
       tag: "",
@@ -214,22 +223,31 @@ function extractXmlNodes(xml, position) {
     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 parsed2 = xmlInner2 ? parseXmlAttributes(xmlInner2) : void 0;
+    return { raw, role: "selfTag", tag: tag2, xmlInner: xmlInner2, xmlAttributes: parsed2?.attributes, end, malformed: parsed2?.malformed ? true : void 0 };
   }
   const tag = inner.split(/\s/)[0] ?? "";
   const xmlInner = inner.slice(tag.length).trim() || void 0;
-  const xmlAttributes = xmlInner ? parseXmlAttributes(xmlInner) : void 0;
-  return { raw, role: "openTag", tag, xmlInner, xmlAttributes, end };
+  const parsed = xmlInner ? parseXmlAttributes(xmlInner) : void 0;
+  return { raw, role: "openTag", tag, xmlInner, xmlAttributes: parsed?.attributes, end, malformed: parsed?.malformed ? true : void 0 };
 }
 
 // src/modules/scaffold/types.ts
 function isMalformed(node) {
   return node.malformed === true;
 }
+
+// src/modules/walk/walk.ts
+function walk(nodes, visitor) {
+  for (const node of nodes) {
+    visitor(node);
+    if (node.children) walk(node.children, visitor);
+  }
+}
 export {
   isMalformed,
   minify,
   render,
-  scaffold
+  scaffold,
+  walk
 };

package/package.json

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