unist-builder

What is unist-builder?

The `unist-builder` npm package is a utility for creating trees of nodes, specifically designed for the Unified ecosystem. It simplifies the process of creating Unist (Universal Syntax Tree) nodes, which are used in processing complex structures like markdown, HTML, or other abstract syntax trees. This package is particularly useful for developers working with markdown, abstract syntax trees, or needing a structured way to programmatically generate or manipulate document structures.

What are unist-builder's main functionalities?

Creating simple Unist nodes

This feature allows for the creation of simple Unist nodes, such as paragraphs or text nodes, which can be used to represent parts of a document. The code sample demonstrates how to create a paragraph node containing a single text node.

{"type": "paragraph", "children": [{"type": "text", "value": "Hello, world!"}]}

Building complex tree structures

With `unist-builder`, users can build more complex tree structures by nesting nodes. This is useful for representing entire documents or sections of content. The provided code sample illustrates how to create a root node that contains a paragraph node, which in turn contains a text node.

{"type": "root", "children": [{"type": "paragraph", "children": [{"type": "text", "value": "Hello, world!"}]}]}

Manipulating node properties

This functionality enables the addition or modification of properties on nodes, such as adding URLs to link nodes. It's particularly useful for creating hyperlinks or adding metadata to nodes. The code sample shows how to create a link node with a URL property.

{"type": "link", "url": "https://example.com", "children": [{"type": "text", "value": "Example"}]}

Other packages similar to unist-builder

hastscript

Similar to `unist-builder`, `hastscript` (or `h`) is a utility for creating trees, specifically Hast trees used in HTML or XML documents. While `unist-builder` is more general-purpose for Unist nodes, `hastscript` focuses on the HTML aspect, making it more suitable for web document manipulation.

mdast-builder

This package is similar to `unist-builder` but is specifically tailored for creating Mdast (Markdown Abstract Syntax Tree) nodes. While `unist-builder` provides a general approach to node creation across different syntax trees, `mdast-builder` is optimized for markdown, offering markdown-specific functionalities.

xastscript

Like `unist-builder`, `xastscript` is a builder utility but for Xast (XML Abstract Syntax Tree) nodes. It's designed for creating and manipulating XML document structures. While `unist-builder` serves a broader range of syntax trees, `xastscript` focuses on XML, making it ideal for projects that require XML document generation or manipulation.

README

unist-builder

unist utility to create trees with ease.

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • u(type[, props][, children|value])
  • ChildrenOrValue
  • Props
• Types
• Compatibility
• Related
• Contribute
• License

What is this?

This package is a hyperscript interface (like createElement from React and h from Vue and such) to help with creating unist trees.

When should I use this?

You can use this utility in your project when you generate syntax trees with code. It helps because it replaces most of the repetition otherwise needed in a syntax tree with function calls.

You can instead use hastscript or xastscript when creating hast (HTML) or xast (XML) nodes.

Install

This package is ESM only. In Node.js (version 16+), install with npm:

npm install unist-builder

In Deno with esm.sh:

import {u} from 'https://esm.sh/unist-builder@4'

In browsers with esm.sh:

<script type="module">
  import {u} from 'https://esm.sh/unist-builder@4?bundle'
</script>

Use

import {u} from 'unist-builder'

const tree = u('root', [
  u('subtree', {id: 1}),
  u('subtree', {id: 2}, [
    u('node', [u('leaf', 'leaf 1'), u('leaf', 'leaf 2')]),
    u('leaf', {id: 3}, 'leaf 3'),
    u('void', {id: 4})
  ])
])

console.dir(tree, {depth: undefined})

…yields:

{
  type: 'root',
  children: [
    {type: 'subtree', id: 1},
    {
      type: 'subtree',
      id: 2,
      children: [
        {
          type: 'node',
          children: [
            {type: 'leaf', value: 'leaf 1'},
            {type: 'leaf', value: 'leaf 2'}
          ]
        },
        {type: 'leaf', id: 3, value: 'leaf 3'},
        {type: 'void', id: 4}
      ]
    }
  ]
}

API

This package exports the identifier u. There is no default export.

u(type[, props][, children|value])

Build a node.

Signatures

• u(type[, props], children) — create a parent (Parent)
• u(type[, props], value) — create a literal (Literal)
• u(type[, props]) — create a void node (neither parent not literal)

Parameters

• type (string) — node type
• props (Record<string, unknown>) — fields assigned to node
• children (Array<Node>) — children of node
• value (*) — value of node (cast to string)

Returns

Built node (Node).

ChildrenOrValue

List to use as children or value to use as value (TypeScript type).

Type

type ChildrenOrValue = Array<Node> | string

Props

Other fields to add to the node (TypeScript type).

Type

export type Props = Record<string, unknown>

Types

This package is fully typed with TypeScript. It exports the additional types ChildrenOrValue and Props.

Compatibility

Projects maintained by the unified collective are compatible with maintained versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of Node. This means we try to keep the current release line, unist-builder@^4, compatible with Node.js 16.

Related

• hastscript — create hast trees
• xastscript — create xast trees

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 © Eugene Sharygin