unist utility to build trees
npm install @flex-development/unist-util-builder








[unist][unist] utility to build trees
- 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
This is a tiny but useful utility for building [trees][tree].
Use this package when you need to create nodes.
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`
`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 }
}
]
}
This package exports the identifier u. There is no default export.
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 typebuilder
- (Builder, optional) - node children, properties, or value
##### Returns
T new node.
#### u(type, children)
Create a [parent][parent].
##### Type Parameters
- T ([Type][type]) - node typeChildren
- (BuilderChildren) - node children
##### Parameters
- type (T) - node typechildren
- (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 typeProperties
- (BuilderProps) - node properties
##### Parameters
- type (T) - node typeproperties
- (Properties) - node properties
##### Returns
Properties & { type: T } new node.
#### u(type, value)
Create a [literal][literal].
- bigintboolean
- number
- string
- null
-
> 👉 Undefined literals must be created using a properties object, rather than a value. Passing undefined will createtype
> a void node (a node with only a field).
##### Type Parameters
- T ([Type][type]) - node typeValue
- (BuilderValue) - node value
##### Parameters
- type (T) - node typevalue
- (Value) - node value
##### Returns
{ type: T; value: Value } new literal node.
Union of types that can be used to build any node (TypeScript type).
`ts`
type AnyBuilder = BuilderChildren | BuilderProps | BuilderValue
Union of node children, properties, and value (TypeScript type).
See also: [MatchChildren][matchchildren], [MatchProperties][matchproperties]
`ts`
type Builder
| Extract
| MatchChildren
| MatchProperties
List of [child][child] nodes used to build a [parent] (TypeScript type).
`ts`
type BuilderChildren
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 }
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 createtype
> a void node (a node with only a field).
`ts`
type BuilderValue = bigint | boolean | number | string | null
This package is fully typed with [TypeScript][typescript].
- [esast-util-builder][esast-util-builder] — build [esast][esast] nodes
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