README.md

unist-util-builder

unist utility to build trees

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • u(type[, builder])
    • u(type, children
    • u(type, properties)
    • u(type, value
  • AnyBuilder
  • Builder<[T]>
  • BuilderChildren<[T]>
  • BuilderProps
  • BuilderValue
• Types
• Related
• Contribute

What is this?

This is a tiny but useful utility for building trees.

When should I use this?

Use this package when you need to create nodes.

Install

This package is ESM only.

In Node.js (version 18+) with yarn:

yarn add @flex-development/unist-util-builder

See Git - Protocols | Yarn  for details regarding installing from Git.

In Deno with esm.sh:

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

In browsers with esm.sh:

<script type="module">
  import { u } from 'https://esm.sh/@flex-development/unist-util-builder'
</script>

Use

import { u } from '@flex-development/unist-util-builder'
import type { Parent } from 'unist'

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

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

...yields:

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

API

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

u(type[, builder])

Build a node using a child node array, properties object, or value.

If builder is omitted, a void node (a node with only a type field) will be created.

Type Parameters

• T (Node) - node to build

Parameters

• type (Type<T>) - node type
• builder (Builder<T>, optional) - node children, properties, or value

Returns

T new node.

u(type, children)

Create a parent.

Type Parameters

• T (Type) - node type
• Children (BuilderChildren) - node children

Parameters

• type (T) - node type
• children (Children) - node children

Returns

{ children: Children; type: T } new parent node.

u(type, properties)

Build a node using a properties object.

👉 Properties of a node are all fields except type. If a type field is on the builder object, it will be ignored.

Type Parameters

• T (Type) - node type
• Properties (BuilderProps) - node properties

Parameters

• type (T) - node type
• properties (Properties) - node properties

Returns

Properties & { type: T } new node.

u(type, value)

Create a literal.

• bigint
• boolean
• number
• string
• null

👉 Undefined literals must be created using a properties object, rather than a value. Passing undefined will create a void node (a node with only a type field).

Type Parameters

• T (Type) - node type
• Value (BuilderValue) - node value

Parameters

• type (T) - node type
• value (Value) - node value

Returns

{ type: T; value: Value } new literal node.

AnyBuilder

Union of types that can be used to build any node (TypeScript type).

type AnyBuilder = BuilderChildren | BuilderProps | BuilderValue

Builder<[T]>

Union of node children, properties, and value (TypeScript type).

See also: MatchChildren, MatchProperties

type Builder<N extends Node = Node> =
  | Extract<MatchValue<N, Type<N>>, BuilderValue>
  | MatchChildren<N, Type<N>>
  | MatchProperties<N, Type<N>>

BuilderChildren<[T]>

List of child nodes used to build a parent (TypeScript type).

type BuilderChildren<T extends Node = Node> = T[]

BuilderProps

Node properties object (TypeScript type).

👉 Properties of a node are all fields except type. If a type field is present on a builder object, it will be ignored.

type BuilderProps = { [x: string]: unknown }

BuilderValue

Union of values that can be used to build a literal (TypeScript type).

👉 Undefined literals must be created using a properties object, rather than a value. Passing undefined will create a void node (a node with only a type field).

type BuilderValue = bigint | boolean | number | string | null

Types

This package is fully typed with TypeScript.

Related

• esast-util-builder — build esast nodes

Contribute

See CONTRIBUTING.md.

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