@tkeron/html-parser 0.1.5 → 1.0.0

package/README.md

@@ -1,7 +1,5 @@
 # HTML Parser - Powered by Bun Native Tokenizer
 
-> ⚠️ **Work in Progress** - This package is currently under active development.
-
 A fast and lightweight HTML parser for Bun that converts HTML strings into DOM Document objects. **Now powered by a native Bun tokenizer** for optimal performance.
 
 ## Features
@@ -11,15 +9,11 @@ A fast and lightweight HTML parser for Bun that converts HTML strings into DOM D
 - 🪶 **Lightweight**: Minimal dependencies, native implementation
 - 🌐 **Standards Compliant**: Returns standard DOM Document objects
 - 🔧 **TypeScript Support**: Full TypeScript definitions included
-- ✅ **Well Tested**: Comprehensive unit test suite (181/181 passing)
+- ✅ **Well Tested**: Comprehensive test suite (5200+ tests passing)
 - 🔄 **100% Compatible**: Drop-in replacement, same API
 
 ## Installation
 
-> **Note**: This package is not yet published to npm. For now, you can clone and build locally.
-
-Once published, it will be available as:
-
 ```bash
 npm install @tkeron/html-parser
 ```

package/bun.lock

@@ -4,8 +4,11 @@
   "workspaces": {
     "": {
       "name": "@tkeron/html-parser",
+      "dependencies": {
+        "all-named-html-entities": "^3.1.3",
+      },
       "devDependencies": {
-        "@types/bun": "^1.3.4",
+        "@types/bun": "^1.3.6",
       },
       "peerDependencies": {
         "typescript": "^5.9.3",
@@ -13,11 +16,13 @@
     },
   },
   "packages": {
-    "@types/bun": ["@types/bun@1.3.4", "", { "dependencies": { "bun-types": "1.3.4" } }, "sha512-EEPTKXHP+zKGPkhRLv+HI0UEX8/o+65hqARxLy8Ov5rIxMBPNTjeZww00CIihrIQGEQBYg+0roO5qOnS/7boGA=="],
+    "@types/bun": ["@types/bun@1.3.6", "", { "dependencies": { "bun-types": "1.3.6" } }, "sha512-uWCv6FO/8LcpREhenN1d1b6fcspAB+cefwD7uti8C8VffIv0Um08TKMn98FynpTiU38+y2dUO55T11NgDt8VAA=="],
 
     "@types/node": ["@types/node@25.0.3", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-W609buLVRVmeW693xKfzHeIV6nJGGz98uCPfeXI1ELMLXVeKYZ9m15fAMSaUPBHYLGFsVRcMmSCksQOrZV9BYA=="],
 
-    "bun-types": ["bun-types@1.3.4", "", { "dependencies": { "@types/node": "*" } }, "sha512-5ua817+BZPZOlNaRgGBpZJOSAQ9RQ17pkwPD0yR7CfJg+r8DgIILByFifDTa+IPDDxzf5VNhtNlcKqFzDgJvlQ=="],
+    "all-named-html-entities": ["all-named-html-entities@3.1.3", "", {}, "sha512-eG7/XkhxyIUWApWvhVPcusxZ3PTebJo1AvkFkQj7MDSkBYmzXZsNadKZWuo1UxEX6QrE7y7JQx7G3Fx0YjVtnA=="],
+
+    "bun-types": ["bun-types@1.3.6", "", { "dependencies": { "@types/node": "*" } }, "sha512-OlFwHcnNV99r//9v5IIOgQ9Uk37gZqrNMCcqEaExdkVq3Avwqok1bJFmvGMCkCE0FqzdY8VMOZpfpR3lwI+CsQ=="],
 
     "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
 

package/index.ts

@@ -7,6 +7,10 @@ import {
 export function parseHTML(html: string = ""): Document {
   const tokens = tokenize(html);
   const ast = parse(tokens);
+  // If parse already returns a DOM document, return it directly
+  if (ast && typeof ast.nodeType === 'number' && ast.nodeType === 9) {
+    return ast;
+  }
   return astToDOM(ast);
 }
 

package/package.json

@@ -1,25 +1,32 @@
 {
   "name": "@tkeron/html-parser",
-  "version": "0.1.5",
+  "version": "1.0.0",
   "description": "A fast and lightweight HTML parser for Bun",
   "main": "index.js",
   "module": "index.ts",
   "type": "module",
   "author": "tkeron",
   "license": "MIT",
+  "scripts": {
+    "test": "bun test --concurrent"
+  },
   "devDependencies": {
-    "@types/bun": "^1.3.4"
+    "@types/bun": "^1.3.6"
   },
   "peerDependencies": {
     "typescript": "^5.9.3"
   },
   "keywords": [
-    "cli",
-    "commands",
-    "command-line",
-    "arguments"
+    "html",
+    "parser",
+    "dom",
+    "bun",
+    "tokenizer"
   ],
   "repository": {
     "url": "git@github.com:tkeron/html-parser.git"
+  },
+  "dependencies": {
+    "all-named-html-entities": "^3.1.3"
   }
 }

package/src/css-selector.ts

@@ -14,33 +14,47 @@ function parseSelector(selector: string): SelectorGroup[] {
 
   return parts.map((part) => {
     const trimmed = part.trim();
-    let tokens: SelectorToken[];
-
-    if (trimmed.startsWith("#")) {
-      tokens = [{ type: "id", value: trimmed.slice(1) }];
-    } else if (trimmed.startsWith(".")) {
-      tokens = [{ type: "class", value: trimmed.slice(1) }];
-    } else if (trimmed.includes("[") && trimmed.includes("]")) {
-      const attributeMatch = trimmed.match(/^([^[\]]*)\[([^=\]]+)(?:=["']?([^"'\]]*?)["']?)?\]$/);
-      if (attributeMatch) {
-        const [, tagName, attrName, attrValue] = attributeMatch;
-        tokens = [];
-        
-        if (tagName && tagName.trim()) {
-          tokens.push({ type: "tag", value: tagName.trim().toLowerCase() });
-        }
-        
-        tokens.push({ 
-          type: "attribute", 
-          value: (attrName || "").trim(),
-          attributeName: (attrName || "").trim(),
-          attributeValue: attrValue ? attrValue.trim() : undefined
-        });
-      } else {
-        tokens = [{ type: "tag", value: trimmed.toLowerCase() }];
-      }
-    } else {
-      tokens = [{ type: "tag", value: trimmed.toLowerCase() }];
+    let tokens: SelectorToken[] = [];
+
+    // Handle universal selector
+    if (trimmed === '*') {
+      // Match any element - we'll handle this specially
+      return { tokens: [] };
+    }
+
+    // Parse complex selectors like p#intro.first or .foo.bar.baz
+    let remaining = trimmed;
+    
+    // Extract tag name first if present
+    const tagMatch = remaining.match(/^([a-zA-Z][a-zA-Z0-9-]*)/);
+    if (tagMatch) {
+      tokens.push({ type: "tag", value: tagMatch[1].toLowerCase() });
+      remaining = remaining.slice(tagMatch[1].length);
+    }
+
+    // Extract all IDs (HTML5 allows IDs starting with digits)
+    const idMatches = remaining.matchAll(/#([a-zA-Z0-9][a-zA-Z0-9_-]*)/g);
+    for (const match of idMatches) {
+      tokens.push({ type: "id", value: match[1] });
+    }
+    remaining = remaining.replace(/#[a-zA-Z0-9][a-zA-Z0-9_-]*/g, '');
+
+    // Extract all classes
+    const classMatches = remaining.matchAll(/\.([a-zA-Z][a-zA-Z0-9_-]*)/g);
+    for (const match of classMatches) {
+      tokens.push({ type: "class", value: match[1] });
+    }
+    remaining = remaining.replace(/\.[a-zA-Z][a-zA-Z0-9_-]*/g, '');
+
+    // Extract attributes
+    const attrMatches = remaining.matchAll(/\[([^=\]]+)(?:=["']?([^"'\]]*?)["']?)?\]/g);
+    for (const match of attrMatches) {
+      tokens.push({
+        type: "attribute",
+        value: match[1].trim(),
+        attributeName: match[1].trim(),
+        attributeValue: match[2] ? match[2].trim() : undefined
+      });
     }
 
     return { tokens };
@@ -74,6 +88,10 @@ function matchesToken(element: any, token: SelectorToken): boolean {
 }
 
 function matchesSelector(element: any, tokens: SelectorToken[]): boolean {
+  // Universal selector - matches any element
+  if (tokens.length === 0) {
+    return true;
+  }
   return tokens.every((token) => matchesToken(element, token));
 }
 

package/src/dom-simulator.ts

@@ -6,6 +6,16 @@ import {
   querySelectorAll as querySelectorAllFunction,
 } from "./css-selector.js";
 
+// Escape special HTML characters in text content
+function escapeTextContent(text: string): string {
+  return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+const VOID_ELEMENTS = new Set([
+  'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+  'link', 'meta', 'param', 'source', 'track', 'wbr'
+]);
+
 export const enum NodeType {
   ELEMENT_NODE = 1,
   TEXT_NODE = 3,
@@ -22,9 +32,13 @@ export function createElement(
 ): any {
   const innerHTML = "";
   const tagNameLower = tagName.toLowerCase();
-  const initialOuterHTML = `<${tagNameLower}${Object.entries(attributes)
+  const isVoid = VOID_ELEMENTS.has(tagNameLower);
+  const attrsStr = Object.entries(attributes)
     .map(([k, v]) => ` ${k}="${v}"`)
-    .join("")}></${tagNameLower}>`;
+    .join("");
+  const initialOuterHTML = isVoid
+    ? `<${tagNameLower}${attrsStr}>`
+    : `<${tagNameLower}${attrsStr}></${tagNameLower}>`;
   const textContent = "";
 
   const element: any = {
@@ -54,6 +68,18 @@ export function createElement(
       return child;
     },
 
+    prepend(...nodes: any[]): void {
+      prepend(element, ...nodes);
+    },
+
+    append(...nodes: any[]): void {
+      append(element, ...nodes);
+    },
+
+    remove(): void {
+      remove(element);
+    },
+
     removeChild(child: any): any {
       return removeChild(element, child);
     },
@@ -96,6 +122,10 @@ export function createElement(
       return querySelectorAllFunction(element, selector);
     },
 
+    matches(selector: string): boolean {
+      return matches(element, selector);
+    },
+
     cloneNode(deep: boolean = false): any {
       return cloneNode(element, deep);
     },
@@ -172,6 +202,10 @@ export function createTextNode(content: string): any {
     lastChild: null,
     nextSibling: null,
     previousSibling: null,
+
+    remove(): void {
+      remove(textNode);
+    },
   };
   return textNode;
 }
@@ -189,10 +223,33 @@ export function createComment(content: string): any {
     lastChild: null,
     nextSibling: null,
     previousSibling: null,
+
+    remove(): void {
+      remove(commentNode);
+    },
   };
   return commentNode;
 }
 
+export function createDoctype(name: string = 'html'): any {
+  const doctypeNode: any = {
+    nodeType: NodeType.DOCUMENT_TYPE_NODE,
+    nodeName: name.toUpperCase(),
+    name: name.toLowerCase(),
+    nodeValue: null,
+    textContent: "",
+    publicId: null,
+    systemId: null,
+    childNodes: [],
+    parentNode: null,
+    firstChild: null,
+    lastChild: null,
+    nextSibling: null,
+    previousSibling: null,
+  };
+  return doctypeNode;
+}
+
 export function createDocument(): any {
   const document: any = {
     nodeType: NodeType.DOCUMENT_NODE,
@@ -222,6 +279,14 @@ export function createDocument(): any {
       return child;
     },
 
+    prepend(...nodes: any[]): void {
+      prepend(document, ...nodes);
+    },
+
+    append(...nodes: any[]): void {
+      append(document, ...nodes);
+    },
+
     removeChild(child: any): any {
       return removeChild(document, child);
     },
@@ -334,7 +399,7 @@ function convertASTNodeToDOM(astNode: ASTNode): any {
   }
 }
 
-function appendChild(parent: any, child: any): void {
+export function appendChild(parent: any, child: any): void {
   if (child.nodeType === NodeType.ELEMENT_NODE || child.nodeType === NodeType.DOCUMENT_NODE) {
     let ancestor = parent;
     while (ancestor) {
@@ -395,6 +460,83 @@ function appendChild(parent: any, child: any): void {
   }
 }
 
+function prepend(parent: any, ...nodes: any[]): void {
+  if (nodes.length === 0) return;
+
+  for (let i = nodes.length - 1; i >= 0; i--) {
+    const node = nodes[i];
+    let childNode: any;
+
+    if (typeof node === 'string') {
+      childNode = createTextNode(node);
+    } else {
+      childNode = node;
+    }
+
+    if (parent.firstChild) {
+      insertBefore(parent, childNode, parent.firstChild);
+    } else {
+      appendChild(parent, childNode);
+    }
+  }
+}
+
+function append(parent: any, ...nodes: any[]): void {
+  if (nodes.length === 0) return;
+
+  for (const node of nodes) {
+    let childNode: any;
+
+    if (typeof node === 'string') {
+      childNode = createTextNode(node);
+    } else {
+      childNode = node;
+    }
+
+    appendChild(parent, childNode);
+  }
+}
+
+function remove(node: any): void {
+  if (node.parentNode) {
+    removeChild(node.parentNode, node);
+  }
+}
+
+function matches(element: any, selector: string): boolean {
+  if (!selector || element.nodeType !== NodeType.ELEMENT_NODE) {
+    return false;
+  }
+
+  try {
+    // Para selectores complejos con descendientes, necesitamos buscar desde un ancestro
+    if (selector.includes(' ') || selector.includes('>')) {
+      // Buscar desde la raíz del documento
+      let root = element;
+      while (root.parentNode) {
+        root = root.parentNode;
+      }
+      const results = querySelectorAllFunction(root, selector);
+      return results.includes(element);
+    }
+    
+    // Para selectores simples, usar el padre o crear uno temporal
+    const parent = element.parentNode || createTempParent(element);
+    const results = querySelectorAllFunction(parent, selector);
+    return results.includes(element);
+  } catch (error) {
+    return false;
+  }
+}
+
+function createTempParent(element: any): any {
+  const temp = createElement('div');
+  temp.childNodes.push(element);
+  temp.children.push(element);
+  element._tempParent = temp;
+  return temp;
+}
+
 function removeChild(parent: any, child: any): any {
   const index = parent.childNodes.indexOf(child);
   if (index === -1) {
@@ -733,9 +875,10 @@ function updateElementContent(element: any): void {
     .map(([k, v]) => ` ${k}="${v}"`)
     .join("");
   const tagNameLower = element.tagName.toLowerCase();
+  const isVoid = VOID_ELEMENTS.has(tagNameLower);
   
   Object.defineProperty(element, "_internalOuterHTML", {
-    value: `<${tagNameLower}${attrs}>${innerHTML}</${tagNameLower}>`,
+    value: isVoid ? `<${tagNameLower}${attrs}>` : `<${tagNameLower}${attrs}>${innerHTML}</${tagNameLower}>`,
     writable: true,
     enumerable: false,
     configurable: true,
@@ -799,13 +942,13 @@ export function setInnerHTML(element: any, html: string): void {
 
   if (html.trim()) {
     const tokens = tokenize(html);
-    const ast = parse(tokens);
-    if (ast.children) {
-      for (const child of ast.children) {
-        const domChild = convertASTNodeToDOM(child);
-        if (domChild) {
-          appendChild(element, domChild);
-        }
+    const doc = parse(tokens);
+    const body = doc.body;
+    if (body && body.childNodes) {
+      const nodesToMove = [...body.childNodes];
+      for (const child of nodesToMove) {
+        child.parentNode = null;
+        appendChild(element, child);
       }
     }
   }
@@ -830,9 +973,10 @@ export function setInnerHTML(element: any, html: string): void {
     .map(([k, v]) => ` ${k}="${v}"`)
     .join("");
   const tagNameLower = element.tagName.toLowerCase();
+  const isVoid = VOID_ELEMENTS.has(tagNameLower);
   
   Object.defineProperty(element, "_internalOuterHTML", {
-    value: `<${tagNameLower}${attrs}>${actualInnerHTML}</${tagNameLower}>`,
+    value: isVoid ? `<${tagNameLower}${attrs}>` : `<${tagNameLower}${attrs}>${actualInnerHTML}</${tagNameLower}>`,
     writable: true,
     enumerable: false,
     configurable: true,
@@ -855,14 +999,12 @@ export function setOuterHTML(element: any, html: string): void {
   
   if (html.trim()) {
     const tokens = tokenize(html);
-    const ast = parse(tokens);
-    
-    if (ast.children) {
-      for (const child of ast.children) {
-        const domChild = convertASTNodeToDOM(child);
-        if (domChild) {
-          newNodes.push(domChild);
-        }
+    const doc = parse(tokens);
+    const body = doc.body;
+    if (body && body.childNodes) {
+      for (const child of body.childNodes) {
+        child.parentNode = null;
+        newNodes.push(child);
       }
     }
   }

package/src/encoding.ts

@@ -0,0 +1,39 @@
+/**
+ * Detects the character encoding of an HTML document.
+ * Based on HTML5 specification for encoding detection.
+ */
+
+const encodingAliases: Record<string, string> = {
+  'iso-8859-1': 'windows-1252',
+  'iso8859-1': 'windows-1252',
+  'iso-8859-2': 'iso-8859-2',
+  'iso8859-2': 'iso-8859-2',
+  'utf-8': 'utf-8',
+  'utf8': 'utf-8',
+  // Add more as needed
+};
+
+function normalizeEncoding(name: string): string | null {
+  const lower = name.toLowerCase().replace(/[^a-z0-9-]/g, '');
+  return encodingAliases[lower] || lower;
+}
+
+export function detectEncoding(html: string): string | null {
+  // Limit to first 1024 characters for performance
+  const prefix = html.substring(0, 1024);
+
+  // Look for <meta charset="...">
+  const charsetMatch = prefix.match(/<meta[^>]*charset\s*=\s*["']?([^"'\s>]+)["']?/i);
+  if (charsetMatch) {
+    return normalizeEncoding(charsetMatch[1]);
+  }
+
+  // Look for <meta http-equiv="Content-Type" content="text/html; charset=...">
+  const contentTypeMatch = prefix.match(/<meta[^>]*http-equiv\s*=\s*["']?\s*content-type\s*["']?[^>]*content\s*=\s*["']?\s*text\/html;\s*charset\s*=\s*([^"'\s>]+)["']?/i);
+  if (contentTypeMatch) {
+    return normalizeEncoding(contentTypeMatch[1]);
+  }
+
+  // Default to Windows-1252 if no encoding found (as per HTML5 spec)
+  return 'windows-1252';
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+import { tokenize } from './tokenizer.js';
+import { parse } from './parser.js';
+
+export function parseHTML(html: string): any {
+  const tokens = tokenize(html);
+  return parse(tokens);
+}
+
+export { parse } from './parser';