hastscript

What is hastscript?

The hastscript npm package, often abbreviated as 'h', is a utility that allows for the easy creation of HAST (Hypertext Abstract Syntax Tree) nodes. HAST is a virtual DOM representation used for parsing, manipulating, and serializing HTML and XML documents. This package is particularly useful for developers working with virtual DOMs or those who need to manipulate HTML/XML documents programmatically.

What are hastscript's main functionalities?

Creating elements

This feature allows for the creation of HAST elements. The example demonstrates creating a 'div' element with a class of 'container' and the text 'Hello, world!' as its child.

const h = require('hastscript');
const element = h('div', {className: 'container'}, 'Hello, world!');

Creating elements with children

This feature enables the creation of HAST elements that contain other elements as children. The code sample shows how to create an unordered list ('ul') with two list items ('li') as its children.

const h = require('hastscript');
const list = h('ul', [
  h('li', 'Item 1'),
  h('li', 'Item 2')
]);

Creating elements with properties

This feature allows for the creation of HAST elements with specific properties. In the example, an anchor ('a') element is created with an 'href' attribute pointing to 'https://example.com' and containing the text 'Visit Example'.

const h = require('hastscript');
const link = h('a', {href: 'https://example.com'}, 'Visit Example');

Other packages similar to hastscript

react-hyperscript

Similar to hastscript, react-hyperscript provides a way to create React elements using a hyperscript-like syntax. While hastscript is focused on creating HAST nodes for HTML/XML documents, react-hyperscript is tailored for React's virtual DOM.

virtual-dom

The virtual-dom package offers a virtual DOM implementation for efficient re-rendering of web interfaces. Unlike hastscript, which is specifically designed for creating HAST nodes, virtual-dom focuses on general virtual DOM functionality, including diffing and patching algorithms.

snabbdom

Snabbdom is a virtual DOM library that is lightweight and extensible. It shares similarities with hastscript in terms of manipulating virtual DOM trees but is more focused on being a core part of user interface rendering and updates, rather than specifically dealing with HAST nodes.

README

hastscript

hast utility to create trees in HTML or SVG.

Similar to hyperscript, virtual-dom/h, React.createElement, and Vue’s createElement, but for hast.

Use unist-builder to create any unist tree.

Install

This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.

npm:

npm install hastscript

Use

import {h, s} from 'hastscript'

// Children as an array:
console.log(
  h('.foo#some-id', [
    h('span', 'some text'),
    h('input', {type: 'text', value: 'foo'}),
    h('a.alpha', {class: 'bravo charlie', download: 'download'}, [
      'delta',
      'echo'
    ])
  ])
)

// Children as arguments:
console.log(
  h(
    'form',
    {method: 'POST'},
    h('input', {type: 'text', name: 'foo'}),
    h('input', {type: 'text', name: 'bar'}),
    h('input', {type: 'submit', value: 'send'})
  )
)

// SVG:
console.log(
  s('svg', {xmlns: 'http://www.w3.org/2000/svg', viewbox: '0 0 500 500'}, [
    s('title', 'SVG `<circle>` element'),
    s('circle', {cx: 120, cy: 120, r: 100})
  ])
)

Yields:

{
  type: 'element',
  tagName: 'div',
  properties: {className: ['foo'], id: 'some-id'},
  children: [
    {
      type: 'element',
      tagName: 'span',
      properties: {},
      children: [{type: 'text', value: 'some text'}]
    },
    {
      type: 'element',
      tagName: 'input',
      properties: {type: 'text', value: 'foo'},
      children: []
    },
    {
      type: 'element',
      tagName: 'a',
      properties: {className: ['alpha', 'bravo', 'charlie'], download: true},
      children: [{type: 'text', value: 'delta'}, {type: 'text', value: 'echo'}]
    }
  ]
}
{
  type: 'element',
  tagName: 'form',
  properties: {method: 'POST'},
  children: [
    {
      type: 'element',
      tagName: 'input',
      properties: {type: 'text', name: 'foo'},
      children: []
    },
    {
      type: 'element',
      tagName: 'input',
      properties: {type: 'text', name: 'bar'},
      children: []
    },
    {
      type: 'element',
      tagName: 'input',
      properties: {type: 'submit', value: 'send'},
      children: []
    }
  ]
}
{
  type: 'element',
  tagName: 'svg',
  properties: {xmlns: 'http://www.w3.org/2000/svg', viewBox: '0 0 500 500'},
  children: [
    {
      type: 'element',
      tagName: 'title',
      properties: {},
      children: [{type: 'text', value: 'SVG `<circle>` element'}]
    },
    {
      type: 'element',
      tagName: 'circle',
      properties: {cx: 120, cy: 120, r: 100},
      children: []
    }
  ]
}

API

This package exports the following identifiers: h and s. There is no default export.

h(selector?[, properties][, …children])

s(selector?[, properties][, …children])

Create virtual hast trees for HTML or SVG.

Signatures

• h(): root
• h(null[, …children]): root
• h(name[, properties][, …children]): element

(and the same for s).

Parameters

selector

Simple CSS selector (string, optional). Can contain a tag name (foo), IDs (#bar), and classes (.baz). If the selector is a string but there is no tag name in it, h defaults to build a div element, and s to a g element. selector is parsed by hast-util-parse-selector. When string, builds an Element. When nullish, builds a Root instead.

properties

Map of properties (Object.<*>, optional). Keys should match either the HTML attribute name, or the DOM property name, but are case-insensitive. Cannot be given when building a Root.

children

(Lists of) children (string, number, Node, Array.<children>, optional). When strings or numbers are encountered, they are mapped to Text nodes. If Root nodes are given, their children are used instead.

Returns

Element or Root.

JSX

hastscript can be used with JSX. Either use the automatic runtime set to hastscript/html, hastscript/svg, or hastscript (shortcut for HTML).

Or import h or s yourself and define it as the pragma (plus set the fragment to null).

The example above can then be written like so, using inline pragmas, so that SVG can be used too:

example-html.jsx:

/** @jsxImportSource hastscript */

console.log(
  <div class="foo" id="some-id">
    <span>some text</span>
    <input type="text" value="foo" />
    <a class="alpha bravo charlie" download>
      deltaecho
    </a>
  </div>
)

console.log(
  <form method="POST">
    <input type="text" name="foo" />
    <input type="text" name="bar" />
    <input type="submit" name="send" />
  </form>
)

example-svg.jsx:

/** @jsxImportSource hastscript/svg */
console.log(
  <svg xmlns="http://www.w3.org/2000/svg" viewbox="0 0 500 500">
    <title>SVG `&lt;circle&gt;` element</title>
    <circle cx={120} cy={120} r={100} />
  </svg>
)

Because JSX does not allow dots (.) or number signs (#) in tag names, you have to pass class names and IDs in as attributes.

You can use estree-util-build-jsx to compile JSX away.

You could also use bublé, but it’s not ideal (jsxFragment is currently only available on the API, not the CLI, and it only allows a single pragma).

For Babel, use @babel/plugin-transform-react-jsx and either pass pragma: 'h' and pragmaFrag: 'null', or pass importSource: 'hastscript'. This is less ideal because it allows a single pragma.

Babel also lets you configure this in a script:

/** @jsx s @jsxFrag null */
import {s} from 'hastscript'

console.log(<rect />)

This is useful because it allows using both html and svg, although in different files.

Security

Use of hastscript can open you up to a cross-site scripting (XSS) attack as values are injected into the syntax tree. The following example shows how a script is injected that runs when loaded in a browser.

const tree = {type: 'root', children: []}

tree.children.push(h('script', 'alert(1)'))

Yields:

<script>alert(1)</script>

The following example shows how an image is injected that fails loading and therefore runs code in a browser.

const tree = {type: 'root', children: []}

// Somehow someone injected these properties instead of an expected `src` and
// `alt`:
const otherProps = {src: 'x', onError: 'alert(2)'}

tree.children.push(h('img', {src: 'default.png', ...otherProps}))

Yields:

<img src="x" onerror="alert(2)">

The following example shows how code can run in a browser because someone stored an object in a database instead of the expected string.

const tree = {type: 'root', children: []}

// Somehow this isn’t the expected `'wooorm'`.
const username = {
  type: 'element',
  tagName: 'script',
  children: [{type: 'text', value: 'alert(3)'}]
}

tree.children.push(h('span.handle', username))

Yields:

<span class="handle"><script>alert(3)</script></span>

Either do not use user input in hastscript or use hast-util-santize.

Related

• unist-builder — Create any unist tree
• xastscript — Create a xast tree
• hast-to-hyperscript — Convert a Node to React, Virtual DOM, Hyperscript, and more
• hast-util-from-dom — Transform a DOM tree to hast
• hast-util-select — querySelector, querySelectorAll, and matches
• hast-util-to-html — Stringify nodes to HTML
• hast-util-to-dom — Transform to a DOM tree

Contribute

See contributing.md in syntax-tree/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MIT © Titus Wormer