🌱 zeed-dom

Lightweight virtual / offline DOM (Document Object Model)
Great to use in node or exporting to plain strings
Written in Typescript
Generates HTML and XML
Parses HTML
Supports some CSS selectors and queries
JSX compatible
Easy content manipulation (e.g. through element.handle helper)
Pretty print HTML (tidyDOM)

Does not aim for completeness!

Get started

npm i zeed-dom

Related projects

zeed - Foundation library
zerva - Event driven server
hostic - Static site generator

Used by TipTap in its html-package.

Utils

Manipulation

Drop in HTML and query and change it. Returns HTML again. Nice for post processing.

const newHTML = handleHTML(html, (document) => {
  const img = document.querySelector('.img-wrapper img')
  if (img)
    img.setAttribute('title', img.getAttribute('src'))
})

Serialization

Take any HTML node or document an serialize it so some other format:

serializePlaintext(node): Readable and searchable plain text
serializeMarkdown(node): Simple Markdown
serializeSafeHTML(node) or safeHTML(htmlString): Just allow some basic tags and attributes

Example

A simple example without JSX:

import { h, xml } from 'zeed-dom'

const dom = h(
  'ol',
  {
    class: 'projects',
  },
  [
    h('li', null, 'zeed ', h('img', { src: 'logo.png' })),
    h('li', null, 'zeed-dom'),
  ]
)

console.log(dom.render())
// Output: <ol class="projects"><li>zeed <img src="logo.png"></li><li>zeed-dom</li></ol>

console.log(dom.render(xml))
// Output: <ol class="projects"><li>zeed <img src="logo.png" /></li><li>zeed-dom</li></ol>

And this one with JSX:

import { h } from "zeed-dom"

let dom = (
  <ol className="projects">
    <li>zeed</li>
    <li>zeed-dom</li>
  </ol>
)

let projects = dom
  .querySelectorAll("li")
  .map((e) => e.textContent)
  .join(", ")

console.log(projects)
// Output: zeed, zeed-dom

dom.handle("li", (e) => {
  if (!e.textContent.endsWith("-dom")) {
    e.remove()
  } else {
    e.innerHTML = "<b>zeed-dom</b> - great DOM helper for static content"
  }
})

console.log(dom.render())
// Output: <ol class="projects"><li><b>zeed-dom</b> - great DOM helper for static content</li></ol>

In the second example you can see the special manipulation helper .handle(selector, fn) in action. You can also see HTML parsing works seamlessly. You can also parse directly:

import { tidyDOM, vdom } from 'zeed-dom'

const dom = vdom('<div>Hello World</div>')
tidyDOM(dom)
console.log(dom.render())
// Output is pretty printed like: <div>
//   Hello World
// </div>

These examples are available at /example.

JSX

Usually JSX is optimized for React i.e. it expects React.creatElement to exist and be the factory for generating the nodes. You can of course get the same effect here if you set up a helper like this:

import { html } from 'zeed-dom'

const React = {
  createElement: html,
}

But more common is the use of h as the factory function. Here is how you can set up this behavior for various environments:

In case of error messages on JSX in your Typescript project, try to add npm install -D @types/react.

TypeScript

In tsconfig.json:

{
  "compilerOptions": {
    "jsx": "react",
    "jsxFactory": "h"
  }
}

To avoid type checking issues you should add this to you shims.d.ts:

// https://www.typescriptlang.org/docs/handbook/jsx.html#intrinsic-elements
declare namespace JSX {
  interface IntrinsicElements {
    [elemName: string]: any
  }
}

ESBuild

In options:

{
  jsxFactory: 'h'
}

Or alternatively as command line option: --jsx-factory=h

Browser DOM

The JSX factory can also be used to directly create HTML DOM nodes in the browser. Just create the h function and let it use the browser's document object:

const { hFactory } = require('zeed-dom')

export const h = hFactory({ document })

Performance

The parser isn't doing too bad, according to the benchmarks of htmlparser-benchmark ;)

tl                 : 1.02699 ms/file ± 0.679139
htmlparser2        : 1.98505 ms/file ± 2.94434
node-html-parser   : 2.24176 ms/file ± 1.52112
neutron-html5parser: 2.36648 ms/file ± 1.38879
html5parser        : 2.39891 ms/file ± 2.83056
htmlparser2-dom    : 2.57523 ms/file ± 3.35587
html-dom-parser    : 2.84910 ms/file ± 3.61615
libxmljs           : 3.81665 ms/file ± 2.79295
zeed-dom           : 5.05130 ms/file ± 3.57184
htmljs-parser      : 5.58557 ms/file ± 6.47597
parse5             : 9.07862 ms/file ± 6.50856
htmlparser         : 21.2274 ms/file ± 150.951
html-parser        : 30.9104 ms/file ± 24.3930
saxes              : 49.5906 ms/file ± 141.194
html5              : 114.771 ms/file ± 148.345

Misc

To set namespace colons in JSX use double underscore i.e. <xhtml__link /> becomes <xhtml:link />
To allow CDATA use the helper function e.g. <div>{ CDATA(yourRawData) }</div>
style attributes can handle objects e.g. <span style={{backgroundColor: 'red'}} /> becomes <span style="background-color: red" />

holtwick / zeed-dom