linkedom

LinkeDOM uses a triple-linked list structure where all nodes are linked on both sides. This allows for extremely fast DOM manipulations (like moving thousands of nodes) because operations only require updating a few pointers rather than performing array or memory reallocations.

Key characteristics:

• Performance: Moving nodes is an $O(1)$ operation regarding memory/array shifts, making it scale linearly from small to very large documents.
• Stability: The structure helps avoid "Maximum call stack size exceeded" errors and reduces memory pressure compared to JSDOM.
• No Caching by default: To avoid the complexity of state invalidation, childNodes and children are computed on demand. If you need cached performance, you must explicitly import linkedom/cached.

Linkedom provides two entry points that are functionally identical but optimized for different performance profiles:

Use linkedom/cached when:

• The document or its elements are rarely changed (low mutation rate).
• You frequently use the same CSS selectors repeatedly.
• You can tolerate whole-document cache invalidation upon any change/removal.
• RAM usage is not a primary concern (cached results are held in NodeList arrays).

Use linkedom (non-cached) when:

• You need minimal RAM usage (nothing is retained in memory).
• You are frequently creating new structures (e.g., via importNode or cloneNode).
• You need fast DOM manipulation without the overhead of cache invalidation side effects.

LinkeDOM achieves high performance and low memory usage by avoiding array manipulation and retention. Instead of a traditional tree structure, it represents the DOM as a linear, double-linked list of nodes.

This approach treats the DOM similarly to how a C-style string works: a sequence of characters (nodes) where elements are defined by boundaries rather than nested object hierarchies. This allows for linear crawling of the document and makes most operations simple property updates.

When reconstructing a document from JSON, Custom Elements will not be automatically upgraded. To ensure they are initialized correctly, you have two options:

1. Use document.importNode(nodeOrFragment, true) to import the nodes.
2. Use JSDON.fromJSON(array, document) to initialize Custom Elements associated with the provided document immediately.

To run the test suite, you must first build the project because ESM source code is transpiled into CJS for testing and coverage analysis.

Workflow:

1. Run npm run build.
2. The test suite executes twice: once for the linkedom module and once for the linkedom/cached export.
3. The project requires 100% code coverage. If a change decreases coverage, it will not be accepted.

Handling Coverage for Accessors: For certain areas like HTMLClasses accessors that may not be fully augmented, you can bypass coverage requirements by wrapping your code in /* c8 ignore start */ and /* c8 ignore stop */ directives.

LinkeDOM's internal logic relies on setting boundaries between nodes. If you are working with the underlying primitives, you can use setAdjacent to link two nodes or setBoundaries to insert a node between two existing ones while correctly handling element boundaries.

const setAdjacent = (before, after) => {
  if (before !== null)
    before.next = after;
  if (after !== null)
    after.prev = before;
};

const setBoundaries = (before, current, after) => {
  setAdjacent(before, current);
  // skip to the node end if needed
  if (current.type === Node.ELEMENT)
    current = current.end;
  setAdjacent(current, after);
};

To run the performance benchmarks, clone the repository, install dependencies in both the test and root directories, and execute the benchmark command.

git clone https://github.com/WebReflection/linkedom.git

cd linkedom/test
npm i

cd ..
npm i

npm run benchmark

Because attributes are part of the linked list but are not considered child nodes, you must skip them when iterating through an element's children. You can traverse the list using next and end pointers, checking the type of each node.

const childNodes = element => {
  const nodeList = [];
  let {next, end} = element;
  while (next !== end) {
    if (next.type !== Node.ATTRIBUTE) {
      nodeList.push(next);
      if (next.type === Node.ELEMENT)
        next = next.end;
    }
    next = next.next;
  }
  return nodeList;
};

If you need a facade that behaves like JSDOM (returning a document and window object), you can wrap parseHTML in a function. This avoids global pollution while providing the same developer experience as JSDOM.

import {parseHTML} from 'linkedom';

function JSDOM(html) { return parseHTML(html); }

const {document, window} = new JSDOM('<h1>Hello LinkeDOM 👋</h1>');