@flex-development/unist-util-builder
v2.0.0
Published
unist utility to build trees
Downloads
8
Maintainers
Readme
unist-util-builder
unist utility to build trees
Contents
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
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 typebuilder
(Builder<T>
, optional) - node children, properties, or value
Returns
T
new node.
u(type, children)
Create a parent.
Type Parameters
T
(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 atype
field is on the builder object, it will be ignored.
Type Parameters
T
(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.
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 atype
field).
Type Parameters
T
(Type
) - node typeValue
(BuilderValue
) - node value
Parameters
type
(T
) - node typevalue
(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 atype
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 atype
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.