unist-util-builder


[unist][unist] utility to build trees

Contents

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

What is this?

This is a tiny but useful utility for building [trees][tree].

When should I use this?

Use this package when you need to create nodes.

Install

This package is [ESM only][esm].

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

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



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



In Deno with [esm.sh][esmsh]:

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

In browsers with [esm.sh][esmsh]:

`html

`

Use

`ts
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:

`sh
{
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.

$3

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]) - node to build

##### Parameters

- type ([Type][type]) - node type
- builder (Builder, optional) - node children, properties, or value

##### Returns

T new node.

#### u(type, children)

Create a [parent][parent].

##### Type Parameters

- T ([Type][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][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][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][type]) - node type
- Value (BuilderValue) - node value

##### Parameters

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

##### Returns

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

$3

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

`ts
type AnyBuilder = BuilderChildren | BuilderProps | BuilderValue
`

$3

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

See also: [MatchChildren][matchchildren], [MatchProperties][matchproperties]

`ts
type Builder =
| Extract>, BuilderValue>
| MatchChildren>
| MatchProperties>
`

$3

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

`ts
type BuilderChildren = T[]
`

$3

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.

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

$3

Union of values that can be used to build a [literal][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).

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

Types

This package is fully typed with [TypeScript][typescript].

Related

- [esast-util-builder][esast-util-builder] — build [esast][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.

[child]: https://github.com/syntax-tree/unist#child
[esast-util-builder]: https://github.com/flex-development/esast-util-builder
[esast]: https://github.com/flex-development/esast
[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
[esmsh]: https://esm.sh/
[literal]: https://github.com/syntax-tree/unist#literal
[matchchildren]: https://github.com/flex-development/unist-util-types#matchchildrenn-check
[matchproperties]: https://github.com/flex-development/unist-util-types#matchpropertiesn-check
[node]: https://github.com/syntax-tree/unist#node
[parent]: https://github.com/syntax-tree/unist#parent
[tree]: https://github.com/syntax-tree/unist#tree
[type]: https://github.com/flex-development/unist-util-types#typet
[typescript]: https://www.typescriptlang.org
[unist]: https://github.com/syntax-tree/unist
[yarn]: https://yarnpkg.com