0
# Unist Builder
1

2
Unist Builder is a utility library that provides a hyperscript interface for creating unist (Universal Syntax Tree) nodes with ease. It offers a simple function `u` that allows developers to build syntax trees programmatically using a concise, functional API similar to React's createElement or Vue's h function.
3

4
## Package Information
5

6
- **Package Name**: unist-builder
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript support)
9
- **Installation**: `npm install unist-builder`
10

11
## Core Imports
12

13
```javascript
14
import { u } from "unist-builder";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { u } = require("unist-builder");
21
```
22

23
## Basic Usage
24

25
```javascript
26
import { u } from "unist-builder";
27

28
// Create a simple tree structure
29
const tree = u('root', [
30
  u('subtree', { id: 1 }),
31
  u('subtree', { id: 2 }, [
32
    u('node', [
33
      u('leaf', 'leaf 1'), 
34
      u('leaf', 'leaf 2')
35
    ]),
36
    u('leaf', { id: 3 }, 'leaf 3'),
37
    u('void', { id: 4 })
38
  ])
39
]);
40

41
console.dir(tree, { depth: undefined });
42
```
43

44
## Capabilities
45

46
### Node Builder Function
47

48
The core `u` function builds unist nodes using a hyperscript-like interface, automatically determining node structure based on parameters.
49

50
```javascript { .api }
51
/**
52
 * Build a unist node with hyperscript-like syntax
53
 * @param {string} type - Node type
54
 * @param {Props | ChildrenOrValue} [props] - Properties or children/value
55
 * @param {ChildrenOrValue} [value] - Children array or string value
56
 * @returns {Node} Built unist node
57
 */
58
function u(type, props, value);
59

60
// Function overloads:
61
// u(type) → {type: T} (void node)
62
// u(type, props) → {type: T} & P (node with properties)
63
// u(type, value) → {type: T, value: string} (literal node)
64
// u(type, props, value) → {type: T, value: string} & P (literal with props)
65
// u(type, children) → {type: T, children: C} (parent node)
66
// u(type, props, children) → {type: T, children: C} & P (parent with props)
67
```
68

69
**Usage Examples:**
70

71
```javascript
72
import { u } from "unist-builder";
73

74
// Void node (only type)
75
const voidNode = u('paragraph');
76
// Result: { type: 'paragraph' }
77

78
// Literal node (with value)
79
const textNode = u('text', 'Hello world');
80
// Result: { type: 'text', value: 'Hello world' }
81

82
// Parent node (with children)
83
const parentNode = u('paragraph', [
84
  u('text', 'Hello '),
85
  u('emphasis', [u('text', 'world')])
86
]);
87
// Result: { type: 'paragraph', children: [...] }
88

89
// Node with properties
90
const nodeWithProps = u('link', { url: 'https://example.com' }, [
91
  u('text', 'Click here')
92
]);
93
// Result: { type: 'link', url: 'https://example.com', children: [...] }
94

95
// Literal with properties
96
const literalWithProps = u('code', { lang: 'javascript' }, 'console.log("hi")');
97
// Result: { type: 'code', lang: 'javascript', value: 'console.log("hi")' }
98
```
99

100
### Parameter Resolution Logic
101

102
The `u` function automatically determines the intended node structure:
103

104
- **Second parameter is string or array**: Treated as `value` (string) or `children` (array)
105
- **Second parameter is object**: Treated as `props` (properties)
106
- **Third parameter (when present)**: Treated as `value` (string) or `children` (array)
107

108
### Node Types
109

110
The function creates different unist node types based on the parameters provided:
111

112
- **Void nodes**: Nodes with only a `type` property
113
- **Literal nodes**: Nodes with `type` and `value` properties
114
- **Parent nodes**: Nodes with `type` and `children` properties
115
- **Hybrid nodes**: Nodes with additional custom properties
116

117
## Types
118

119
```javascript { .api }
120
/**
121
 * Union type for node children or value
122
 * @typedef {Array<Node> | string} ChildrenOrValue
123
 */
124

125
/**
126
 * Additional properties to assign to nodes
127
 * @typedef {Record<string, unknown>} Props
128
 */
129

130
/**
131
 * Base unist node type (from @types/unist)
132
 * @typedef {Object} Node
133
 * @property {string} type - Node type
134
 * @property {string} [value] - Node value (for literal nodes)
135
 * @property {Array<Node>} [children] - Child nodes (for parent nodes)
136
 */
137
```
138

139
## TypeScript Support
140

141
The package includes full TypeScript support with generic type inference:
142

143
```typescript
144
import { u } from "unist-builder";
145
import type { ChildrenOrValue, Props } from "unist-builder";
146

147
// Type-safe node creation with inference
148
const typedNode = u('paragraph', [
149
  u('text', 'Hello'),
150
  u('emphasis', [u('text', 'world')])
151
]);
152

153
// Custom properties with type safety
154
interface LinkProps extends Props {
155
  url: string;
156
  title?: string;
157
}
158

159
const linkNode = u('link', { url: 'https://example.com' } as LinkProps, [
160
  u('text', 'Example Link')
161
]);
162
```