https://github.com/flex-development/unist-util-builder
unist utility to build trees
https://github.com/flex-development/unist-util-builder
ast builder docast esast mdast syntax syntax-tree tree unist unist-util util
Last synced: 8 months ago
JSON representation
unist utility to build trees
- Host: GitHub
- URL: https://github.com/flex-development/unist-util-builder
- Owner: flex-development
- License: bsd-3-clause
- Created: 2024-05-29T03:34:17.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-10-24T07:05:35.000Z (about 1 year ago)
- Last Synced: 2024-10-25T01:16:46.979Z (about 1 year ago)
- Topics: ast, builder, docast, esast, mdast, syntax, syntax-tree, tree, unist, unist-util, util
- Language: JavaScript
- Homepage: https://github.com/flex-development/unist-util-builder
- Size: 1.67 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/funding.yml
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# unist-util-builder
[](https://github.com/flex-development/unist-util-builder/releases/latest)
[](https://npmjs.com/package/@flex-development/unist-util-builder)
[](https://codecov.io/gh/flex-development/unist-util-builder)
[](https://github.com/voxpelli/badges-cjs-esm)
[](LICENSE.md)
[](https://conventionalcommits.org/)
[](https://typescriptlang.org/)
[](https://vitest.dev/)
[](https://yarnpkg.com/)
[unist][unist] utility to build trees
## Contents
- [What is this?](#what-is-this)
- [When should I use this?](#when-should-i-use-this)
- [Install](#install)
- [Use](#use)
- [API](#api)
- [`u(type[, builder])`](#utype-builder)
- [`u(type, children`](#utype-children)
- [`u(type, properties)`](#utype-properties)
- [`u(type, value`](#utype-value)
- [`AnyBuilder`](#anybuilder)
- [`Builder<[T]>`](#buildert)
- [`BuilderChildren<[T]>`](#builderchildrent)
- [`BuilderProps`](#builderprops)
- [`BuilderValue`](#buildervalue)
- [Types](#types)
- [Related](#related)
- [Contribute](#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
import { u } from 'https://esm.sh/@flex-development/unist-util-builder'
```
## 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`](#utype-builder). There is no default export.
### `u(type[, builder])`
Build a node using a [child node array](#utype-children), [properties object](#utype-properties), or
[value](#utype-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`](#buildert), 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`](#builderchildrent)) - 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`](#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`](#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).
```ts
type AnyBuilder = BuilderChildren | BuilderProps | BuilderValue
```
### `Builder<[T]>`
Union of node children, properties, and value (TypeScript type).
**See also**: [`MatchChildren`][matchchildren], [`MatchProperties`][matchproperties]
```ts
type Builder =
| Extract>, BuilderValue>
| MatchChildren>
| MatchProperties>
```
### `BuilderChildren<[T]>`
List of [*child*][child] nodes used to build a [parent] (TypeScript type).
```ts
type BuilderChildren = 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.
```ts
type BuilderProps = { [x: string]: unknown }
```
### `BuilderValue`
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`](CONTRIBUTING.md).
This project has a [code of conduct](CODE_OF_CONDUCT.md). 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