parse-html-dom 1.0.0

package/lib/node.js

@@ -0,0 +1,259 @@
+/**
+ * @module node
+ */
+
+import { querySelector as findFirstMatch, querySelectorAll as findAllMatches } from './selector-matcher.js';
+
+/**
+ * Base class for every node in the tree. Structure — `parentNode` and, for
+ * container nodes, children — is set once during parsing and never changes
+ * afterward. The constructor is not a supported way to build a tree outside
+ * this package; `parseHTML` owns construction.
+ */
+export class Node {
+    /** @type {Node|null} */
+    #parentNode = null;
+
+    /**
+     * @param {number} nodeType - The DOM node type number.
+     */
+    constructor(nodeType) {
+        this.nodeType = nodeType;
+    }
+
+    /**
+     * @returns {Node|null} The parent node, or `null` at the root.
+     */
+    get parentNode() {
+        return this.#parentNode;
+    }
+
+    /**
+     * @returns {Element|null} The parent when it is an `Element`, otherwise
+     *   `null` — so an element directly under `Document` reports `null`
+     *   rather than a `Document`. Checked by `nodeType` rather than
+     *   `instanceof Element` so this module has no dependency on
+     *   element.js, which itself depends on this one.
+     */
+    get parentElement() {
+        return this.#parentNode && this.#parentNode.nodeType === 1 ? this.#parentNode : null;
+    }
+
+    // Internal: called only by the tree builder while assembling a node's
+    // parent, never exposed as a public mutator.
+    setParentNode(node) {
+        this.#parentNode = node;
+    }
+}
+
+/**
+ * A `Node` that can contain children: `Document` and `Element`. Kept
+ * separate from `Node` so that `Text` and `Comment` do not inherit
+ * `children` or the query methods, which would be meaningless on them.
+ */
+export class ParentNode extends Node {
+    /** @type {Node[]} */
+    #childNodes = [];
+
+    /** @type {Node[]|null} */
+    #frozenChildNodes = null;
+
+    /** @type {Element[]|null} */
+    #frozenChildren = null;
+
+    /**
+     * @returns {Node[]} Every child node — elements, text, and comments — in
+     *   source order. The same frozen Array instance is returned on every
+     *   access.
+     */
+    get childNodes() {
+        if (!this.#frozenChildNodes) {
+            this.#frozenChildNodes = Object.freeze(this.#childNodes.slice());
+        }
+        return this.#frozenChildNodes;
+    }
+
+    /**
+     * @returns {Element[]} Child `Element` nodes only, in source order. The
+     *   same frozen Array instance is returned on every access. Filtered by
+     *   `nodeType` rather than `instanceof Element` — see the note on
+     *   `parentElement`.
+     */
+    get children() {
+        if (!this.#frozenChildren) {
+            this.#frozenChildren = Object.freeze(
+                this.#childNodes.filter((node) => node.nodeType === 1),
+            );
+        }
+        return this.#frozenChildren;
+    }
+
+    /**
+     * @returns {string|null} The concatenated data of every descendant
+     *   `Text` node in document order, ignoring comments. `null` when this
+     *   node is a `Document`, per the DOM.
+     */
+    get textContent() {
+        if (this.nodeType === 9) {
+            return null;
+        }
+
+        let result = '';
+        const stack = this.#childNodes.slice().reverse();
+
+        while (stack.length > 0) {
+            const node = stack.pop();
+            if (node instanceof Text) {
+                result += node.data;
+            } else if (node instanceof ParentNode) {
+                for (let index = node.childNodes.length - 1; index >= 0; index -= 1) {
+                    stack.push(node.childNodes[index]);
+                }
+            }
+        }
+
+        return result;
+    }
+
+    /**
+     * @param {string} name - Element local name to match, or `'*'` for any
+     *   element. Matched case-insensitively against HTML elements and
+     *   case-sensitively against foreign elements.
+     * @returns {Element[]} Descendant elements in document order, excluding
+     *   this node itself.
+     */
+    getElementsByTagName(name) {
+        const isWildcard = name === '*';
+        const lowerName = name.toLowerCase();
+        const results = [];
+
+        const visit = (node) => {
+            for (const child of node.children) {
+                const matches = isWildcard
+                    || (child.isForeign ? child.tagName === name : child.localName === lowerName);
+
+                if (matches) {
+                    results.push(child);
+                }
+                visit(child);
+            }
+        };
+
+        visit(this);
+
+        return Object.freeze(results);
+    }
+
+    /**
+     * @param {string} names - One or more class names separated by ASCII
+     *   whitespace. An element must carry all of them, matched
+     *   case-sensitively.
+     * @returns {Element[]} Descendant elements in document order, excluding
+     *   this node itself.
+     */
+    getElementsByClassName(names) {
+        const required = names.split(/\s+/).filter(Boolean);
+        const results = [];
+
+        const visit = (node) => {
+            for (const child of node.children) {
+                if (required.every((token) => child.classList.contains(token))) {
+                    results.push(child);
+                }
+                visit(child);
+            }
+        };
+
+        visit(this);
+
+        return Object.freeze(results);
+    }
+
+    /**
+     * @param {string} selector - A CSS selector.
+     * @returns {Element|null} The first descendant matching `selector`, in
+     *   document order, or `null`.
+     * @throws {SelectorSyntaxError} When `selector` is invalid.
+     */
+    querySelector(selector) {
+        return findFirstMatch(this, selector);
+    }
+
+    /**
+     * @param {string} selector - A CSS selector.
+     * @returns {Element[]} Every descendant matching `selector`, in
+     *   document order, deduplicated across a comma-separated selector
+     *   list.
+     * @throws {SelectorSyntaxError} When `selector` is invalid.
+     */
+    querySelectorAll(selector) {
+        return findAllMatches(this, selector);
+    }
+
+    // Internal: called only by the tree builder while appending a child.
+    appendChild(node) {
+        this.#childNodes.push(node);
+        node.setParentNode(this);
+    }
+}
+
+/**
+ * A node holding a single string of data: `Text` or `Comment`.
+ */
+export class CharacterData extends Node {
+    /**
+     * @param {number} nodeType - The DOM node type number.
+     * @param {string} data - The node's text data.
+     */
+    constructor(nodeType, data) {
+        super(nodeType);
+        this.data = data;
+    }
+
+    /**
+     * @returns {string} The node's data. Provided so `Text` and `Comment`
+     *   match the DOM's `textContent` contract at the leaf level.
+     */
+    get textContent() {
+        return this.data;
+    }
+}
+
+/**
+ * A text node.
+ */
+export class Text extends CharacterData {
+    /**
+     * @param {string} data - The text content.
+     */
+    constructor(data) {
+        super(3, data);
+    }
+
+    /**
+     * @returns {string} Always `'#text'`.
+     */
+    get nodeName() {
+        return '#text';
+    }
+}
+
+/**
+ * A comment node.
+ */
+export class Comment extends CharacterData {
+    /**
+     * @param {string} data - The comment content, excluding `<!--` and
+     *   `-->`.
+     */
+    constructor(data) {
+        super(8, data);
+    }
+
+    /**
+     * @returns {string} Always `'#comment'`.
+     */
+    get nodeName() {
+        return '#comment';
+    }
+}

package/lib/parse-html.js

@@ -0,0 +1,96 @@
+/**
+ * @module parse-html
+ */
+
+import { tokenize } from './tokenizer.js';
+import { buildTree } from './tree-builder.js';
+
+const BOM = '';
+
+// Normalizes line endings to LF and strips a leading BOM before tokenizing,
+// so every offset the tokenizer and tree builder record indexes into this
+// normalized string rather than the caller's original one.
+function preprocess(html) {
+    let source = html;
+
+    if (source.startsWith(BOM)) {
+        source = source.slice(1);
+    }
+
+    return source.replace(/\r\n?/g, '\n');
+}
+
+// Builds a sorted index of the offset just after every "\n" in `source`, so
+// that resolveErrorPositions() can turn a byte offset into a 1-based line
+// and column with a binary search instead of rescanning the source once per
+// error.
+function buildLineStartIndex(source) {
+    const lineStarts = [ 0 ];
+
+    for (let index = 0; index < source.length; index += 1) {
+        if (source[index] === '\n') {
+            lineStarts.push(index + 1);
+        }
+    }
+
+    return lineStarts;
+}
+
+function findLineIndex(lineStarts, offset) {
+    let low = 0;
+    let high = lineStarts.length - 1;
+
+    while (low < high) {
+        const mid = Math.ceil((low + high) / 2);
+        if (lineStarts[mid] <= offset) {
+            low = mid;
+        } else {
+            high = mid - 1;
+        }
+    }
+
+    return low;
+}
+
+// Resolving line/column is deferred until we know at least one error
+// happened, so a clean document never pays for the line-start scan.
+function resolveErrorPositions(errors, source) {
+    if (errors.length === 0) {
+        return [];
+    }
+
+    const lineStarts = buildLineStartIndex(source);
+
+    return errors.map((error) => {
+        const lineIndex = findLineIndex(lineStarts, error.offset);
+        return Object.freeze({
+            code: error.code,
+            message: error.message,
+            offset: error.offset,
+            line: lineIndex + 1,
+            column: error.offset - lineStarts[lineIndex] + 1,
+        });
+    });
+}
+
+/**
+ * Parses an HTML string into a read-only `Document`. Never throws for
+ * malformed markup — recoveries are recorded on the returned document's
+ * `parseErrors` — but does throw for a caller error: a non-string argument.
+ * @param {string} html - The HTML source to parse.
+ * @returns {Document} The parsed document. `documentElement`, `head`, and
+ *   `body` are always non-null, even for empty input.
+ * @throws {TypeError} When `html` is not a string.
+ */
+export function parseHTML(html) {
+    if (typeof html !== 'string') {
+        throw new TypeError(`parseHTML() expects a string, received ${ typeof html }.`);
+    }
+
+    const source = preprocess(html);
+    const { document, errors } = buildTree(tokenize(source));
+
+    document.setParseErrors(resolveErrorPositions(errors, source));
+
+    return document;
+}

package/lib/selector-matcher.js

@@ -0,0 +1,315 @@
+/**
+ * @module selector-matcher
+ */
+
+import { parseSelector } from './selector-parser.js';
+
+function typeKey(element) {
+    return element.isForeign ? element.rawName : element.localName;
+}
+
+function previousElementSibling(element) {
+    const parent = element.parentNode;
+    if (!parent) {
+        return null;
+    }
+
+    const siblings = parent.childNodes;
+    const index = siblings.indexOf(element);
+
+    for (let i = index - 1; i >= 0; i -= 1) {
+        if (siblings[i].nodeType === 1) {
+            return siblings[i];
+        }
+    }
+
+    return null;
+}
+
+// Element-only siblings (including `element` itself) in document order,
+// optionally narrowed to those sharing `element`'s type — the distinction
+// between the plain "-child" and "-of-type" pseudo-classes.
+function siblingsFor(element, sameTypeOnly) {
+    const parent = element.parentNode;
+    const all = parent ? parent.children : [ element ];
+
+    if (!sameTypeOnly) {
+        return all;
+    }
+
+    const key = typeKey(element);
+    return all.filter((candidate) => typeKey(candidate) === key);
+}
+
+function positionAmongSiblings(element, sameTypeOnly) {
+    const siblings = siblingsFor(element, sameTypeOnly);
+    return siblings.indexOf(element) + 1;
+}
+
+function positionFromEndAmongSiblings(element, sameTypeOnly) {
+    const siblings = siblingsFor(element, sameTypeOnly);
+    return siblings.length - siblings.indexOf(element);
+}
+
+// An, per the CSS An+B microsyntax: true when there exists an integer n >= 0
+// such that a*n + b === position.
+function matchesNth(position, { a, b }) {
+    if (a === 0) {
+        return position === b;
+    }
+    const n = (position - b) / a;
+    return Number.isInteger(n) && n >= 0;
+}
+
+function isEmptyElement(element) {
+    return element.childNodes.every((node) => {
+        if (node.nodeType === 1) {
+            return false;
+        }
+        if (node.nodeType === 3) {
+            return node.data.length === 0;
+        }
+        return true;
+    });
+}
+
+function matchesAttribute(element, attribute) {
+    const value = element.getAttribute(attribute.name);
+
+    if (value === null) {
+        return false;
+    }
+    if (attribute.operator === null) {
+        return true;
+    }
+
+    let actual = value;
+    let expected = attribute.value;
+
+    if (attribute.caseInsensitive) {
+        actual = actual.toLowerCase();
+        expected = expected.toLowerCase();
+    }
+
+    switch (attribute.operator) {
+        case '=':
+            return actual === expected;
+        case '~=':
+            return actual.split(/\s+/u).filter(Boolean).includes(expected);
+        case '|=':
+            return actual === expected || actual.startsWith(`${ expected }-`);
+        case '^=':
+            return expected !== '' && actual.startsWith(expected);
+        case '$=':
+            return expected !== '' && actual.endsWith(expected);
+        case '*=':
+            return expected !== '' && actual.includes(expected);
+        default:
+            return false;
+    }
+}
+
+function matchesPseudo(element, pseudo) {
+    switch (pseudo.name) {
+        case 'root':
+            return Boolean(element.parentNode) && element.parentNode.nodeType === 9;
+        case 'empty':
+            return isEmptyElement(element);
+        case 'first-child':
+            return positionAmongSiblings(element, false) === 1;
+        case 'last-child':
+            return positionFromEndAmongSiblings(element, false) === 1;
+        case 'only-child':
+            return positionAmongSiblings(element, false) === 1 && positionFromEndAmongSiblings(element, false) === 1;
+        case 'first-of-type':
+            return positionAmongSiblings(element, true) === 1;
+        case 'last-of-type':
+            return positionFromEndAmongSiblings(element, true) === 1;
+        case 'only-of-type':
+            return positionAmongSiblings(element, true) === 1 && positionFromEndAmongSiblings(element, true) === 1;
+        case 'nth-child':
+            return matchesNth(positionAmongSiblings(element, false), pseudo.argument);
+        case 'nth-last-child':
+            return matchesNth(positionFromEndAmongSiblings(element, false), pseudo.argument);
+        case 'nth-of-type':
+            return matchesNth(positionAmongSiblings(element, true), pseudo.argument);
+        case 'nth-last-of-type':
+            return matchesNth(positionFromEndAmongSiblings(element, true), pseudo.argument);
+        case 'not':
+            return !matchesAnySelector(element, pseudo.argument);
+        case 'is':
+        case 'where':
+            return matchesAnySelector(element, pseudo.argument);
+        default:
+            return false;
+    }
+}
+
+function matchesCompound(element, compound) {
+    if (compound.tag !== null) {
+        const matchesTag = element.isForeign
+            ? element.rawName === compound.rawTag
+            : element.localName === compound.tag;
+
+        if (!matchesTag) {
+            return false;
+        }
+    }
+
+    if (compound.id !== null && element.id !== compound.id) {
+        return false;
+    }
+
+    if (!compound.classes.every((token) => element.classList.contains(token))) {
+        return false;
+    }
+
+    if (!compound.attributes.every((attribute) => matchesAttribute(element, attribute))) {
+        return false;
+    }
+
+    return compound.pseudos.every((pseudo) => matchesPseudo(element, pseudo));
+}
+
+// Matches right to left: the rightmost compound is tested against `element`
+// first, and only on success does matching walk left through the
+// combinator chain — so a candidate that fails on its own compound never
+// pays for a tree walk.
+function matchesComplex(element, chain) {
+    if (!matchesCompound(element, chain.compound)) {
+        return false;
+    }
+    if (chain.combinator === null) {
+        return true;
+    }
+    return matchesCombinatorLeft(element, chain.combinator, chain.left);
+}
+
+function matchesCombinatorLeft(element, combinator, leftChain) {
+    if (combinator === '>') {
+        const parent = element.parentElement;
+        return Boolean(parent) && matchesComplex(parent, leftChain);
+    }
+
+    if (combinator === ' ') {
+        let ancestor = element.parentElement;
+        while (ancestor) {
+            if (matchesComplex(ancestor, leftChain)) {
+                return true;
+            }
+            ancestor = ancestor.parentElement;
+        }
+        return false;
+    }
+
+    if (combinator === '+') {
+        const sibling = previousElementSibling(element);
+        return Boolean(sibling) && matchesComplex(sibling, leftChain);
+    }
+
+    // '~'
+    let sibling = previousElementSibling(element);
+    while (sibling) {
+        if (matchesComplex(sibling, leftChain)) {
+            return true;
+        }
+        sibling = previousElementSibling(sibling);
+    }
+    return false;
+}
+
+function matchesAnySelector(element, selectorList) {
+    return selectorList.some((chain) => matchesComplex(element, chain));
+}
+
+// Yields every descendant Element of `root` in document order, using an
+// explicit stack rather than recursion so a pathologically deep tree cannot
+// overflow the call stack.
+function* iterateDescendants(root) {
+    const stack = [];
+    const children = root.children;
+    for (let i = children.length - 1; i >= 0; i -= 1) {
+        stack.push(children[i]);
+    }
+
+    while (stack.length > 0) {
+        const node = stack.pop();
+        yield node;
+
+        const kids = node.children;
+        for (let i = kids.length - 1; i >= 0; i -= 1) {
+            stack.push(kids[i]);
+        }
+    }
+}
+
+/**
+ * @param {Element} element - The element to test.
+ * @param {string} selectorText - A CSS selector.
+ * @returns {boolean} Whether `element` matches `selectorText`.
+ * @throws {SelectorSyntaxError} When `selectorText` is invalid.
+ */
+export function matches(element, selectorText) {
+    return matchesAnySelector(element, parseSelector(selectorText));
+}
+
+/**
+ * @param {ParentNode} scope - The element or document to search within.
+ * @param {string} selectorText - A CSS selector.
+ * @returns {Element|null} The first descendant of `scope` matching
+ *   `selectorText`, in document order, or `null`.
+ * @throws {SelectorSyntaxError} When `selectorText` is invalid.
+ */
+export function querySelector(scope, selectorText) {
+    const ast = parseSelector(selectorText);
+
+    for (const element of iterateDescendants(scope)) {
+        if (matchesAnySelector(element, ast)) {
+            return element;
+        }
+    }
+
+    return null;
+}
+
+/**
+ * @param {ParentNode} scope - The element or document to search within.
+ * @param {string} selectorText - A CSS selector.
+ * @returns {Element[]} Every descendant of `scope` matching `selectorText`,
+ *   in document order, deduplicated across a comma-separated selector list.
+ * @throws {SelectorSyntaxError} When `selectorText` is invalid.
+ */
+export function querySelectorAll(scope, selectorText) {
+    const ast = parseSelector(selectorText);
+    const results = [];
+
+    for (const element of iterateDescendants(scope)) {
+        if (matchesAnySelector(element, ast)) {
+            results.push(element);
+        }
+    }
+
+    return Object.freeze(results);
+}
+
+/**
+ * @param {Element} element - The element to start from.
+ * @param {string} selectorText - A CSS selector.
+ * @returns {Element|null} `element` itself if it matches, otherwise the
+ *   nearest matching ancestor, stopping at `documentElement`. `null` when
+ *   nothing matches.
+ * @throws {SelectorSyntaxError} When `selectorText` is invalid.
+ */
+export function closest(element, selectorText) {
+    const ast = parseSelector(selectorText);
+
+    let current = element;
+    while (current) {
+        if (matchesAnySelector(current, ast)) {
+            return current;
+        }
+        current = current.parentElement;
+    }
+
+    return null;
+}