Social Media Photo by JJ Ying on Unsplash
LinkeDOM is a triple-linked list based DOM-like namespace, for DOM-less environments, with the following goals:
import {DOMParser, parseHTML} from 'linkedom';
// Standard way: text/html, text/xml, image/svg+xml, etc...
// const document = (new DOMParser).parseFromString(html, 'text/html');
// Simplified way for HTML
const {
// note, these are *not* globals
window, document, customElements,
HTMLElement,
Event, CustomEvent
// other exports ..
} = parseHTML(`
<!doctype html>
<html lang="en">
<head>
<title>Hello SSR</title>
</head>
<body>
<form>
<input name="user">
<button>
Submit
</button>
</form>
</body>
</html>
`);
// builtin extends compatible too 👍
customElements.define('custom-element', class extends HTMLElement {
connectedCallback() {
console.log('it works 🥳');
}
});
document.body.appendChild(
document.createElement('custom-element')
);
document.toString();
// the SSR ready document
document.querySelectorAll('form, input[name], button');
// the NodeList of elements
// CSS Selector via CSSselect
v0.11
a new linkedom/worker
export has been added. This works with deno, Web, and Service Workers, and it's not strictly coupled with NodeJS. Please note, this export does not include canvas
module, and the performance
is retrieved from the globalThis
context.LinkeDOM uses a blazing fast JSDON serializer, and nodes, as well as whole documents, can be retrieved back via parseJSON(value)
.
// any node can be serialized
const array = document.toJSON();
// somewhere else ...
import {parseJSON} from 'linkedom';
const document = parseJSON(array);
Please note that Custom Elements won't be upgraded, unless the resulting nodes are imported via document.importNode(nodeOrFragment, true)
.
Alternatively, JSDON.fromJSON(array, document)
is able to initialize right away Custom Elements associated with the passed document
.
This module is based on DOMParser API, hence it creates a new document
each time new DOMParser().parseFromString(...)
is invoked.
As there's no global pollution whatsoever, to retrieve classes and features associated to the document
returned by parseFromString
, you need to access its defaultView
property, which is a special proxy that lets you get pseudo-global-but-not-global properties and classes.
Alternatively, you can use the parseHTML
utility which returns a pseudo window object with all the public references you need.
// facade to a generic JSDOM bootstrap
import {parseHTML} from 'linkedom';
function JSDOM(html) { return parseHTML(html); }
// now you can do the same as you would with JSDOM
const {document, window} = new JSDOM('<h1>Hello LinkeDOM 👋</h1>');
The triple-linked list data structure is explained below in How does it work?, the Deep Dive, and the presentation on Speakeasy JS.
All nodes are linked on both sides, and all elements consist of 2 nodes, also linked in between.
Attributes are always at the beginning of an element, while zero or more extra nodes can be found before the end.
A fragment is a special element without boundaries, or parent node.
Node: ← node →
Attr<Node>: ← attr → ↑ ownerElement?
Text<Node>: ← text → ↑ parentNode?
Comment<Node>: ← comment → ↑ parentNode?
Element<Node>: ← start ↔ end → ↑ parentNode?
Fragment<Element>: start ↔ end
Element example:
parentNode? (as shortcut for a linked list of previous nodes)
↑
├────────────────────────────────────────────┐
│ ↓
node? ← start → attr* → text* → comment* → element* → end → node?
↑ │
└────────────────────────────────────────────┘
Fragment example:
┌────────────────────────────────────────────┐
│ ↓
start → attr* → text* → comment* → element* → end
↑ │
└────────────────────────────────────────────┘
If this is not clear, feel free to read more in the deep dive page.
Moving N nodes from a container, being it either an Element or a Fragment, requires the following steps:
As result, there are no array operations, and no memory operations, and everything is kept in sync by updating a few properties, so that removing 3714
sparse <div>
elements in a 12M document, as example, takes as little as 3ms, while appending a whole fragment takes close to 0ms.
Try npm run benchmark:html
to see it yourself.
This structure also allows programs to avoid issues such as "Maximum call stack size exceeded" (basicHTML), or "JavaScript heap out of memory" crashes (JSDOM), thanks to its reduced usage of memory and zero stacks involved, hence scaling better from small to very big documents.
As everything is a while(...)
loop away, by default this module does not cache anything, specially because caching requires state invalidation for each container, returned queries, and so on. However, you can import linkedom/cached
instead, as long as you understand its constraints.
This module parses, and works, only with the following nodeType
:
ELEMENT_NODE
ATTRIBUTE_NODE
TEXT_NODE
COMMENT_NODE
DOCUMENT_NODE
DOCUMENT_FRAGMENT_NODE
DOCUMENT_TYPE_NODE
Everything else, at least for the time being, is considered YAGNI, and it won't likely ever land in this project, as there's no goal to replicate deprecated features of this aged Web.
This module exports both linkedom
and linkedom/cached
, which are basically the exact same thing, except the cached version outperforms linkedom
in these scenarios:
On the other hand, the basic, non-cached, module, grants the following:
importNode
or cloneNode
(i.e. template literals based libraries)To run the benchmark locally, please follow these commands:
git clone https://github.com/WebReflection/linkedom.git
cd linkedom/test
npm i
cd ..
npm i
npm run benchmark