xml-to-html-converter 0.0.1 → 0.1.0

package/README.md

@@ -0,0 +1,161 @@
+# xml-to-html-converter
+
+![npm version](https://img.shields.io/npm/v/xml-to-html-converter)
+![npm downloads](https://img.shields.io/npm/dw/xml-to-html-converter)
+![license](https://img.shields.io/npm/l/xml-to-html-converter)
+![node version](https://img.shields.io/node/v/xml-to-html-converter)
+![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
+
+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`, but for now, I will be building 0 dependency tools that will eventually be used to convert an xml to html.
+
+---
+
+> **Where I am right now**
+>
+> The goal of this package is to take any XML document and convert it to HTML. Currently, I am building the foundation which is taking an xml doc of any kind, and turning it into a json object otherwise known as a document node.
+>
+> What `v0.x` builds is the foundation that makes `v1.0.0` possible:
+>
+> - **A parser** takes any XML string and returns a plain JS document tree
+> - **A fault-tolerant verifier** flags every broken node with `malformed: true` in-place, giving you a complete map of exactly where and what broke
+> - **An intermediate representation** is a plain JS object tree that the HTML converter will walk when it's built
+>
+> `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.
+
+---
+
+## Install
+
+```bash
+npm install xml-to-html-converter
+```
+
+---
+
+## Usage
+
+```js
+import { parse } from "xml-to-html-converter";
+
+const tree = parse(`
+  <?xml version="1.0" encoding="UTF-8"?>
+  <bookstore>
+    <book category="cooking">
+      <title lang="en">Everyday Italian</title>
+      <author>Giada De Laurentiis</author>
+    </book>
+  </bookstore>
+`);
+```
+
+`parse` returns a document node wrapping the full tree:
+
+```json
+{
+  "type": "document",
+  "children": [
+    {
+      "type": "processing-instruction",
+      "target": "xml",
+      "attributes": { "version": "1.0", "encoding": "UTF-8" }
+    },
+    {
+      "type": "element",
+      "tag": "bookstore",
+      "attributes": {},
+      "children": [
+        {
+          "type": "element",
+          "tag": "book",
+          "attributes": { "category": "cooking" },
+          "children": [
+            {
+              "type": "element",
+              "tag": "title",
+              "attributes": { "lang": "en" },
+              "children": [{ "type": "text", "value": "Everyday Italian" }]
+            },
+            {
+              "type": "element",
+              "tag": "author",
+              "attributes": {},
+              "children": [{ "type": "text", "value": "Giada De Laurentiis" }]
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## Node Types
+
+Every node in the tree has a `type` field.
+
+| Type                     | Properties                      |
+| ------------------------ | ------------------------------- |
+| `document`               | `children`                      |
+| `element`                | `tag`, `attributes`, `children` |
+| `text`                   | `value`                         |
+| `comment`                | `value`                         |
+| `cdata`                  | `value`                         |
+| `processing-instruction` | `target`, `attributes`          |
+| `malformed`              | `raw`, `malformed: true`        |
+
+---
+
+## Malformed XML
+
+The parser never throws. No matter what the input looks like, it always returns a complete document tree. I built this because when working with QTI and xsd validation, it was a pain to get things to work and I could never get past the current industries package standards. Additionally, falling down a Java rabbit hole was not something I enjoyed AT ALL. Therefore, malformed structures are flagged with `malformed: true` in-place and the walk continues. The tree is built no matter what your xml looks like.
+
+Three types of malformed input are caught:
+
+- **Unclosed tags** - a tag that opens but never closes gets `malformed: true`, its children are still collected normally
+- **Stray closing tags** - a `</tag>` with no matching open becomes a `{ type: 'malformed', raw: '...</tag>', malformed: true }` node at that position
+- **Unclosed brackets** - a `<` with no matching `>` before end of string captures the remainder as a malformed node
+
+```js
+const tree = parse("<root><unclosed><valid>text</valid></root>");
+```
+
+```json
+{
+  "type": "document",
+  "children": [
+    {
+      "type": "element",
+      "tag": "root",
+      "attributes": {},
+      "children": [
+        {
+          "type": "element",
+          "tag": "unclosed",
+          "attributes": {},
+          "malformed": true,
+          "children": [
+            {
+              "type": "element",
+              "tag": "valid",
+              "attributes": {},
+              "children": [{ "type": "text", "value": "text" }]
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## Requirements
+
+Node.js `>=18.0.0`
+
+## License
+
+ISC

package/package.json

@@ -1,21 +1,36 @@
 {
   "name": "xml-to-html-converter",
-  "version": "0.0.1",
-  "description": "",
-  "main": "index.js",
+  "version": "0.1.0",
+  "description": "Zero dependency XML to HTML converter for Node environments",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src/"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node --test tests/tokenizer.test.js tests/parser.test.js"
   },
+  "keywords": [
+    "xml",
+    "html",
+    "converter",
+    "parser",
+    "tree"
+  ],
+  "author": "",
+  "license": "ISC",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/jpatterson933/xml-2-html.git"
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "type": "commonjs",
   "bugs": {
     "url": "https://github.com/jpatterson933/xml-2-html/issues"
   },
   "homepage": "https://github.com/jpatterson933/xml-2-html#readme"
-}
+}

package/src/index.js

@@ -0,0 +1,3 @@
+import { parse } from './parser.js';
+
+export { parse };

package/src/parser.js

@@ -0,0 +1,48 @@
+import { tokenize, TokenType } from './tokenizer.js';
+
+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;
+      children.push({ type: 'malformed', raw: `</${token.tag}>`, malformed: true });
+      continue;
+    }
+
+    if (token.type === TokenType.ELEMENT_OPEN) {
+      const node = { type: 'element', tag: token.tag, attributes: token.attributes, children: collectChildren(tokens, cursor, token.tag) };
+      children.push(node);
+      continue;
+    }
+
+    children.push(tokenToNode(token));
+  }
+
+  if (parentTag !== null) {
+    children.forEach(child => { child.malformed = true; });
+  }
+
+  return children;
+}
+
+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) return { type: 'element', tag: token.tag, attributes: token.attributes, children: [] };
+  if (token.type === TokenType.PROCESSING_INSTRUCTION) return { type: 'processing-instruction', target: token.target, attributes: token.attributes };
+  return { type: 'malformed', raw: token.raw, malformed: true };
+}
+
+export { parse };

package/src/tokenizer.js

@@ -0,0 +1,79 @@
+const 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',
+};
+
+const WHITESPACE = /\s/;
+const ATTRIBUTE_PATTERN = /(\S+?)\s*=\s*["']([^"']*)["']/g;
+
+function parseAttributes(raw) {
+  const attributes = {};
+  ATTRIBUTE_PATTERN.lastIndex = 0;
+  let match;
+  while ((match = ATTRIBUTE_PATTERN.exec(raw)) !== null) {
+    attributes[match[1]] = match[2];
+  }
+  return attributes;
+}
+
+function nextToken(xml, position) {
+  if (xml[position] !== '<') {
+    const end = xml.indexOf('<', position);
+    const value = xml.slice(position, end === -1 ? xml.length : end);
+    return { token: value.trim() ? { type: TokenType.TEXT, value } : null, end: end === -1 ? xml.length : end };
+  }
+
+  const next = xml[position + 1];
+
+  if (next === '?') {
+    const end = xml.indexOf('?>', position) + 2;
+    const inner = xml.slice(position + 2, end - 2).trim();
+    const space = inner.search(WHITESPACE);
+    return { token: { type: TokenType.PROCESSING_INSTRUCTION, target: space === -1 ? inner : inner.slice(0, space), attributes: parseAttributes(inner) }, end: end || xml.length };
+  }
+
+  if (next === '!' && xml[position + 2] === '-') {
+    const end = xml.indexOf('-->', position) + 3;
+    return { token: { type: TokenType.COMMENT, value: xml.slice(position + 4, end - 3) }, end: end || xml.length };
+  }
+
+  if (next === '!' && xml[position + 2] === '[') {
+    const end = xml.indexOf(']]>', position) + 3;
+    return { token: { type: TokenType.CDATA, value: xml.slice(position + 9, end - 3) }, end: end || xml.length };
+  }
+
+  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;
+
+  while (position < xml.length) {
+    const { token, end } = nextToken(xml, position);
+    if (token) tokens.push(token);
+    position = end;
+  }
+
+  return tokens;
+}
+
+export { tokenize, TokenType };