xml-to-html-converter 0.1.5 → 0.1.6

package/README.md

@@ -10,12 +10,40 @@ A zero-dependency Node.js package for converting XML to HTML. Currently in pre-1
 
 ---
 
+## v0.1.x: XML Node Extraction & Scaffolding
+
+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 XmlNode {
+  role: XmlNodeRole;
+  raw: string;
+  globalIndex: number;
+  localIndex: number;
+  children?: XmlNode[];
+  malformed?: true;
+}
+
+type XmlNodeRole =
+  | "closeTag"
+  | "comment"
+  | "doctype"
+  | "openTag"
+  | "processingInstruction"
+  | "selfTag"
+  | "textLeaf";
+```
+
+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 - a structural tree of every node in your XML document, each carrying its raw source string and its exact position in the document. This scaffold is what the HTML converter will walk when it's built.
+> `v0.x` is building the scaffold: a structural tree of every node in your XML document, each carrying its raw source string and its exact position in the document. This scaffold is what the HTML converter will walk when it's built.
 >
-> - **`scaffold(xml)`** reads any XML string and returns a nested token tree
-> - Every token knows its `role`, its `raw` source string, its `globalIndex` in the document, and its `localIndex` within its parent
+> - **`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
 > - 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.
@@ -45,7 +73,7 @@ const tree = scaffold(`
 `);
 ```
 
-`scaffold` returns a flat array of root-level tokens. Each `openTag` token carries its children nested inside it:
+`scaffold` returns a flat array of root-level nodes. Each `openTag` node carries its children nested inside it:
 
 ```json
 [
@@ -58,25 +86,25 @@ const tree = scaffold(`
   {
     "role": "openTag",
     "raw": "<bookstore>",
-    "globalIndex": 2,
-    "localIndex": 2,
+    "globalIndex": 1,
+    "localIndex": 1,
     "children": [
       {
         "role": "openTag",
         "raw": "<book category=\"cooking\">",
-        "globalIndex": 4,
-        "localIndex": 1,
+        "globalIndex": 2,
+        "localIndex": 0,
         "children": [
           {
             "role": "openTag",
             "raw": "<title lang=\"en\">",
-            "globalIndex": 6,
-            "localIndex": 1,
+            "globalIndex": 3,
+            "localIndex": 0,
             "children": [
               {
                 "role": "textLeaf",
                 "raw": "Everyday Italian",
-                "globalIndex": 7,
+                "globalIndex": 4,
                 "localIndex": 0
               }
             ]
@@ -90,31 +118,32 @@ const tree = scaffold(`
 
 ---
 
-## Token Shape
+## Node Shape
 
-Every token in the tree has the following fields:
+Every node in the tree has the following fields:
 
-| Field         | Type        | Description                                          |
-| ------------- | ----------- | ---------------------------------------------------- |
-| `role`        | `TokenRole` | What kind of token 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`    | `Token[]`   | Present only on `openTag` - the nested tokens 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                  |
+| `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           |
 
 ---
 
-## Token Roles
+## Node Roles
 
-| Role                    | Has children | Description                                  |
-| ----------------------- | ------------ | -------------------------------------------- |
-| `openTag`               | yes          | An opening tag, e.g. `<book category="web">` |
-| `selfTag`               | no           | A self-closing tag, e.g. `<br/>`             |
-| `closeTag`              | no           | Only appears when stray (no matching open)   |
-| `processingInstruction` | no           | e.g. `<?xml version="1.0"?>`                 |
-| `comment`               | no           | e.g. `<!-- a comment -->`                    |
-| `textLeaf`              | no           | Text content between tags                    |
+| Role                    | Has children | Description                                         |
+| ----------------------- | ------------ | --------------------------------------------------- |
+| `openTag`               | yes          | An opening tag, e.g. `<book category="web">`        |
+| `selfTag`               | no           | A self-closing tag, e.g. `<br/>`                    |
+| `closeTag`              | no           | Only appears when stray (no matching open)          |
+| `processingInstruction` | no           | e.g. `<?xml version="1.0"?>`                        |
+| `comment`               | no           | e.g. `<!-- a comment -->`                           |
+| `textLeaf`              | no           | Text content between tags, including CDATA sections |
+| `doctype`               | no           | e.g. `<!DOCTYPE html>` or `<!DOCTYPE root [...]>`   |
 
 ---
 
@@ -171,6 +200,27 @@ const tree = scaffold("<root><unclosed><valid>text</valid></root>");
 
 ---
 
+## Exports
+
+```ts
+import { scaffold, isMalformed } from "xml-to-html-converter";
+import type {
+  XmlNode,
+  XmlNodeRole,
+  MalformedXmlNode,
+} from "xml-to-html-converter";
+```
+
+| Export             | Kind     | Description                                         |
+| ------------------ | -------- | --------------------------------------------------- |
+| `scaffold`         | function | Parses an XML string and returns a node tree        |
+| `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                     |
+| `MalformedXmlNode` | type     | `XmlNode` narrowed to `{ malformed: true }`         |
+
+---
+
 ## Requirements
 
 Node.js `>=20.0.0`

package/dist/index.d.ts

@@ -1,88 +1,13 @@
-interface DocumentNode {
-    type: 'document';
-    children: Node[];
-}
-interface ElementNode {
-    type: 'element';
-    tag: string;
-    attributes: Record<string, string>;
-    children: Node[];
-    malformed?: true;
-}
-interface TextNode {
-    type: 'text';
-    value: string;
-}
-interface CommentNode {
-    type: 'comment';
-    value: string;
-}
-interface CDataNode {
-    type: 'cdata';
-    value: string;
-}
-interface ProcessingInstructionNode {
-    type: 'processing-instruction';
-    target: string;
-    attributes: Record<string, string>;
-}
-interface MalformedNode {
-    type: 'malformed';
-    raw: string;
-    malformed: true;
-}
-type Node = ElementNode | TextNode | CommentNode | CDataNode | ProcessingInstructionNode | MalformedNode;
-
-declare function parse(xml: string): DocumentNode;
-
-declare const TokenType: {
-    readonly PROCESSING_INSTRUCTION: "processing-instruction";
-    readonly ELEMENT_OPEN: "element-open";
-    readonly ELEMENT_CLOSE: "element-close";
-    readonly SELF_CLOSING: "self-closing";
-    readonly TEXT: "text";
-    readonly COMMENT: "comment";
-    readonly CDATA: "cdata";
-    readonly MALFORMED: "malformed";
-};
-interface ProcessingInstructionToken {
-    type: typeof TokenType.PROCESSING_INSTRUCTION;
-    target: string;
-    attributes: Record<string, string>;
-}
-interface ElementOpenToken {
-    type: typeof TokenType.ELEMENT_OPEN;
-    tag: string;
-    attributes: Record<string, string>;
-}
-interface ElementCloseToken {
-    type: typeof TokenType.ELEMENT_CLOSE;
-    tag: string;
-}
-interface SelfClosingToken {
-    type: typeof TokenType.SELF_CLOSING;
-    tag: string;
-    attributes: Record<string, string>;
-}
-interface TextToken {
-    type: typeof TokenType.TEXT;
-    value: string;
-}
-interface CommentToken {
-    type: typeof TokenType.COMMENT;
-    value: string;
-}
-interface CDataToken {
-    type: typeof TokenType.CDATA;
-    value: string;
-}
-interface MalformedToken {
-    type: typeof TokenType.MALFORMED;
+type XmlNodeRole = "openTag" | "closeTag" | "selfTag" | "processingInstruction" | "comment" | "textLeaf";
+interface XmlNode {
+    role: XmlNodeRole;
     raw: string;
+    globalIndex: number;
+    localIndex: number;
+    children?: XmlNode[];
+    malformed?: true;
 }
-type Token = ProcessingInstructionToken | ElementOpenToken | ElementCloseToken | SelfClosingToken | TextToken | CommentToken | CDataToken | MalformedToken;
-type ContentToken = Exclude<Token, ElementOpenToken | ElementCloseToken>;
 
-declare function tokenize(xml: string): Token[];
+declare function scaffold(xml: string): XmlNode[];
 
-export { type CDataNode, type CommentNode, type ContentToken, type DocumentNode, type ElementNode, type MalformedNode, type Node, type ProcessingInstructionNode, type TextNode, type Token, TokenType, parse, tokenize };
+export { type XmlNode, type XmlNodeRole, scaffold };

package/dist/index.js

@@ -1,179 +1,116 @@
-// src/modules/tokenizer/types.ts
-var TokenType = {
-  PROCESSING_INSTRUCTION: "processing-instruction",
-  ELEMENT_OPEN: "element-open",
-  ELEMENT_CLOSE: "element-close",
-  SELF_CLOSING: "self-closing",
-  TEXT: "text",
-  COMMENT: "comment",
-  CDATA: "cdata",
-  MALFORMED: "malformed"
-};
-
-// src/modules/tokenizer/tokenizer.ts
-var WHITESPACE = /\s/;
-function parseAttributes(raw) {
-  const attributes = {};
-  const pattern = /(\S+?)\s*=\s*(["'])([^"']*)\2/g;
-  let match;
-  while ((match = pattern.exec(raw)) !== null) {
-    attributes[match[1]] = match[3];
-  }
-  return attributes;
+// src/modules/scaffold/scaffold.ts
+function scaffold(xml) {
+  const counter = { value: 0 };
+  const { xmlNodes } = collectXmlNodes(xml, 0, null, counter);
+  return xmlNodes;
 }
-function nextToken(xml, position) {
-  if (xml[position] !== "<") {
-    const end2 = xml.indexOf("<", position);
-    const value = xml.slice(position, end2 === -1 ? xml.length : end2);
-    return {
-      token: value.trim() ? { type: TokenType.TEXT, value } : null,
-      end: end2 === -1 ? xml.length : end2
-    };
-  }
-  const next = xml[position + 1];
-  if (next === "?") {
-    const closeIndex = xml.indexOf("?>", position);
-    if (closeIndex === -1)
-      return {
-        token: { type: TokenType.MALFORMED, raw: xml.slice(position) },
-        end: xml.length
-      };
-    const end2 = closeIndex + 2;
-    const inner2 = xml.slice(position + 2, end2 - 2).trim();
-    const space2 = inner2.search(WHITESPACE);
-    return {
-      token: {
-        type: TokenType.PROCESSING_INSTRUCTION,
-        target: space2 === -1 ? inner2 : inner2.slice(0, space2),
-        attributes: parseAttributes(inner2)
-      },
-      end: end2
-    };
-  }
-  if (next === "!" && xml[position + 2] === "-") {
-    const closeIndex = xml.indexOf("-->", position);
-    if (closeIndex === -1)
-      return {
-        token: { type: TokenType.MALFORMED, raw: xml.slice(position) },
-        end: xml.length
-      };
-    const end2 = closeIndex + 3;
-    return {
-      token: {
-        type: TokenType.COMMENT,
-        value: xml.slice(position + 4, end2 - 3)
-      },
-      end: end2
-    };
-  }
-  if (next === "!" && xml[position + 2] === "[") {
-    const closeIndex = xml.indexOf("]]>", position);
-    if (closeIndex === -1)
-      return {
-        token: { type: TokenType.MALFORMED, raw: xml.slice(position) },
-        end: xml.length
-      };
-    const end2 = closeIndex + 3;
-    return {
-      token: { type: TokenType.CDATA, value: xml.slice(position + 9, end2 - 3) },
-      end: end2
-    };
-  }
-  const end = xml.indexOf(">", position) + 1;
-  if (!end)
-    return {
-      token: { type: TokenType.MALFORMED, raw: xml.slice(position) },
-      end: xml.length
-    };
-  const raw = xml.slice(position + 1, end - 1).trim();
-  if (raw[0] === "/")
-    return {
-      token: { type: TokenType.ELEMENT_CLOSE, tag: raw.slice(1).trim() },
-      end
-    };
-  const selfClosing = raw[raw.length - 1] === "/";
-  const inner = selfClosing ? raw.slice(0, -1).trim() : raw;
-  const space = inner.search(WHITESPACE);
-  const tag = space === -1 ? inner : inner.slice(0, space);
-  const type = selfClosing ? TokenType.SELF_CLOSING : TokenType.ELEMENT_OPEN;
-  return { token: { type, tag, attributes: parseAttributes(inner) }, end };
-}
-function tokenize(xml) {
-  const tokens = [];
-  let position = 0;
+function collectXmlNodes(xml, position, parentTag, counter) {
+  const xmlNodes = [];
   while (position < xml.length) {
-    const { token, end } = nextToken(xml, position);
-    if (token) tokens.push(token);
-    position = end;
-  }
-  return tokens;
-}
-
-// src/modules/parser/parser.ts
-function parse(xml) {
-  const tokens = tokenize(xml);
-  const cursor = { position: 0 };
-  const { children } = collectChildren(tokens, cursor, null);
-  return { type: "document", children };
-}
-function collectChildren(tokens, cursor, parentTag) {
-  const children = [];
-  while (cursor.position < tokens.length) {
-    const token = tokens[cursor.position];
-    cursor.position++;
-    if (token.type === TokenType.ELEMENT_CLOSE) {
-      if (token.tag === parentTag) return { children, closed: true };
-      children.push({
-        type: "malformed",
-        raw: `</${token.tag}>`,
+    const xmlNodeData = extractXmlNodes(xml, position);
+    if (xmlNodeData.role === "closeTag") {
+      if (xmlNodeData.tag === parentTag)
+        return { xmlNodes, position: xmlNodeData.end, closed: true };
+      xmlNodes.push({
+        role: "closeTag",
+        raw: xmlNodeData.raw,
+        globalIndex: counter.value++,
+        localIndex: xmlNodes.length,
         malformed: true
       });
+      position = xmlNodeData.end;
       continue;
     }
-    if (token.type === TokenType.ELEMENT_OPEN) {
-      const { children: elementChildren, closed } = collectChildren(
-        tokens,
-        cursor,
-        token.tag
+    if (xmlNodeData.role === "openTag" && !xmlNodeData.malformed) {
+      const globalIndex = counter.value++;
+      const localIndex = xmlNodes.length;
+      const nested = collectXmlNodes(
+        xml,
+        xmlNodeData.end,
+        xmlNodeData.tag,
+        counter
       );
-      const node = {
-        type: "element",
-        tag: token.tag,
-        attributes: token.attributes,
-        children: elementChildren
+      const xmlNode2 = {
+        role: "openTag",
+        raw: xmlNodeData.raw,
+        globalIndex,
+        localIndex,
+        children: nested.xmlNodes
       };
-      if (!closed) node.malformed = true;
-      children.push(node);
+      if (!nested.closed) xmlNode2.malformed = true;
+      xmlNodes.push(xmlNode2);
+      position = nested.position;
       continue;
     }
-    children.push(tokenToNode(token));
+    const xmlNode = {
+      role: xmlNodeData.role,
+      raw: xmlNodeData.raw,
+      globalIndex: counter.value++,
+      localIndex: xmlNodes.length
+    };
+    if (xmlNodeData.malformed) xmlNode.malformed = true;
+    if (xmlNodeData.role === "openTag") xmlNode.children = [];
+    xmlNodes.push(xmlNode);
+    position = xmlNodeData.end;
   }
-  return { children, closed: parentTag === null };
+  return { xmlNodes, position, closed: parentTag === null };
 }
-function tokenToNode(token) {
-  if (token.type === TokenType.TEXT)
-    return { type: "text", value: token.value };
-  if (token.type === TokenType.COMMENT)
-    return { type: "comment", value: token.value };
-  if (token.type === TokenType.CDATA)
-    return { type: "cdata", value: token.value };
-  if (token.type === TokenType.SELF_CLOSING)
+function extractXmlNodes(xml, position) {
+  if (xml[position] !== "<") {
+    const end2 = xml.indexOf("<", position);
     return {
-      type: "element",
-      tag: token.tag,
-      attributes: token.attributes,
-      children: []
+      raw: xml.slice(position, end2 === -1 ? xml.length : end2),
+      role: "textLeaf",
+      tag: "",
+      end: end2 === -1 ? xml.length : end2
+    };
+  }
+  if (xml[position + 1] === "?") {
+    const end2 = xml.indexOf("?>", position + 2);
+    return end2 === -1 ? {
+      raw: xml.slice(position),
+      role: "processingInstruction",
+      tag: "",
+      end: xml.length
+    } : {
+      raw: xml.slice(position, end2 + 2),
+      role: "processingInstruction",
+      tag: "",
+      end: end2 + 2
     };
-  if (token.type === TokenType.PROCESSING_INSTRUCTION)
+  }
+  if (xml[position + 1] === "!" && xml[position + 2] === "-") {
+    const end2 = xml.indexOf("-->", position + 4);
+    return end2 === -1 ? { raw: xml.slice(position), role: "comment", tag: "", end: xml.length } : {
+      raw: xml.slice(position, end2 + 3),
+      role: "comment",
+      tag: "",
+      end: end2 + 3
+    };
+  }
+  const closeAt = xml.indexOf(">", position);
+  if (closeAt === -1)
     return {
-      type: "processing-instruction",
-      target: token.target,
-      attributes: token.attributes
+      raw: xml.slice(position),
+      role: "openTag",
+      tag: "",
+      end: xml.length,
+      malformed: true
     };
-  return { type: "malformed", raw: token.raw, malformed: true };
+  const raw = xml.slice(position, closeAt + 1);
+  const end = closeAt + 1;
+  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 };
+  }
+  if (inner.endsWith("/")) {
+    const tag2 = inner.slice(0, -1).trim().split(/\s/)[0] ?? "";
+    return { raw, role: "selfTag", tag: tag2, end };
+  }
+  const tag = inner.split(/\s/)[0] ?? "";
+  return { raw, role: "openTag", tag, end };
 }
 export {
-  TokenType,
-  parse,
-  tokenize
+  scaffold
 };

package/package.json

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