hast (Hypertext Abstract Syntax Tree)

Property values in HAST reflect the data type determined by the property name.

• Booleans: Attributes like hidden are reflected as hidden: true.
• Numbers: Attributes like minlength="5" are reflected as minLength: 5.
• Lists: Comma or space-separated attribute values are represented as ordered arrays. For example, <div class="alpha bravo"> becomes properties: { className: ['alpha', 'bravo'] }.
• Lenience: Unlike the DOM, HAST is lenient with non-standard values. For example, <div hidden="no"> is reflected as hidden: 'no' rather than being coerced to true.
• Null/Undefined: In JSON or JavaScript, null or undefined values should be treated as if the property was not included.

HAST provides a 'virtual' DOM designed to be lean, easy to transform, and capable of representing the entirety of HTML syntax (including comments and doctypes) while providing positional information.

Abstract Node Types

• Literal: A node containing a value: string.
• Parent: A node containing children (which can be Comment, Doctype, Element, or Text).

Concrete Node Types

• Root: Represents a document. It can be the root of a tree or the content of a <template> element, but it cannot be a child of another node.
• Element: Represents an HTML element. It includes a tagName (local name), properties (attributes), and children. If the tagName is 'template', it may also have a content field of type Root.
• Text: Represents text content.
• Comment: Represents an HTML comment.
• Doctype: Represents a <!doctype> declaration.

HAST transforms HTML attribute names into camelcased property names to align with how attributes are reflected in the DOM.

Transformation Rules:

1. Multi-word names: Names referencing combinations of words (e.g., stroke-miterlimit) become camelcased (strokeMiterLimit).
2. Hyphenated names: Hyphenated attributes (e.g., read-only) become camelcased (readOnly).
3. Acronyms: Acronyms are treated as normal words (e.g., itemid becomes itemId).

Notable Exceptions:

• class becomes className.
• for becomes htmlFor.
• allowfullscreen becomes allowFullScreen.
• autoplay becomes autoPlay.
• autocomplete becomes autoComplete.

Note: For a complete list of transformations, use hastscript or the property-information package.

If you are using TypeScript, you can install the official type definitions for hast using npm.

npm install @types/hast

Because hast represents HTML, improper use can lead to Cross-Site Scripting (XSS) attacks. When dealing with user-provided input, you must ensure the tree is safe before processing or rendering it.

Use the hast-util-sanitize utility to sanitize nodes and mitigate security risks.

Text and comments are represented as nodes with a value property.

Text Example: <span>Foxtrot</span> yields:

{
  type: 'element',
  tagName: 'span',
  properties: {},
  children: [{type: 'text', value: 'Foxtrot'}]
}

Comment Example: <!--Charlie--> yields:

{type: 'comment', value: 'Charlie'}

When converting HTML to HAST, elements are mapped to objects containing their tag name, properties, and children.

Example: <a href="https://alpha.com" class="bravo" download></a> becomes:

{
  type: 'element',
  tagName: 'a',
  properties: {
    href: 'https://alpha.com',
    className: ['bravo'],
    download: true
  },
  children: []
}

Beyond the core hast-util-* packages, there is a collection of specialized HTML-related utilities for working with specific standards and attributes:

• Tag Names: html-tag-names, mathml-tag-names, svg-tag-names, html-void-elements.
• Attributes & Properties: aria-attributes, html-element-attributes, svg-element-attributes, property-information.
• Parsing Tokens: comma-separated-tokens, space-separated-tokens.
• Namespaces & Encodings: web-namespaces, html-encodings, html-dangerous-encodings.
• Link & Meta: a-rel, link-rel, meta-name.
• Event Handlers: html-event-attributes, svg-event-attributes.