0
# Unified
1
2
Unified is a comprehensive content processing framework that enables developers to parse, inspect, transform, and serialize content through syntax trees using a unified architecture. It serves as the foundation for multiple content processing ecosystems including remark (Markdown), rehype (HTML), and retext (natural language), offering a plugin-based architecture that allows for complex content transformations through a unified interface.
3
4
## Package Information
5
6
- **Package Name**: unified
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript definitions)
9
- **Installation**: `npm install unified`
10
11
## Core Imports
12
13
```javascript
14
import { unified } from "unified";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const { unified } = require("unified");
21
```
22
23
For TypeScript with types:
24
25
```typescript
26
import { unified } from "unified";
27
import type {
28
Processor,
29
Plugin,
30
Transformer,
31
Compiler,
32
Parser,
33
Data,
34
Settings
35
} from "unified";
36
```
37
38
## Basic Usage
39
40
```javascript
41
import { unified } from "unified";
42
43
// Create a processor
44
const processor = unified()
45
.use(someParser) // Configure parser
46
.use(someTransformer) // Add transformers
47
.use(someCompiler); // Configure compiler
48
49
// Process content (async)
50
const result = await processor.process("input content");
51
console.log(String(result)); // Processed output
52
53
// Or synchronously
54
const syncResult = processor.processSync("input content");
55
console.log(String(syncResult));
56
```
57
58
## Architecture
59
60
Unified is built around several key components:
61
62
- **Processor**: Core processing engine that manages the transformation pipeline
63
- **Plugin System**: Extensible architecture for parsers, transformers, and compilers
64
- **VFile Integration**: Rich file handling with metadata throughout the pipeline
65
- **Processing Phases**: Three-phase pipeline (parse → run → stringify) with precise control
66
- **Configuration Management**: Data and settings management across all plugins
67
- **Type Safety**: Full TypeScript support with extensible interfaces
68
69
## Capabilities
70
71
### Core Processing Pipeline
72
73
Complete content processing through parse, transform, and stringify phases with both synchronous and asynchronous support.
74
75
```typescript { .api }
76
// Main processor creation
77
function unified(): Processor;
78
79
// Core processing methods
80
parse<Tree extends Node = Node>(file?: Compatible): Tree;
81
stringify<Tree extends Node = Node, Result = CompileResults>(
82
tree: Tree,
83
file?: Compatible
84
): Result;
85
run<HeadTree extends Node = Node, TailTree extends Node = Node>(
86
tree: HeadTree,
87
file?: Compatible,
88
done?: RunCallback<TailTree>
89
): Promise<TailTree>;
90
runSync<HeadTree extends Node = Node, TailTree extends Node = Node>(
91
tree: HeadTree,
92
file?: Compatible
93
): TailTree;
94
process<Result = CompileResults>(
95
file?: Compatible,
96
done?: ProcessCallback<VFileWithOutput<Result>>
97
): Promise<VFileWithOutput<Result>>;
98
processSync<Result = CompileResults>(
99
file?: Compatible
100
): VFileWithOutput<Result>;
101
```
102
103
[Processing Pipeline](./processing-pipeline.md)
104
105
### Plugin System
106
107
Flexible plugin architecture supporting parsers, transformers, compilers, and presets with configuration management.
108
109
```typescript { .api }
110
use(plugin: Plugin, ...parameters: unknown[]): Processor;
111
use(preset: Preset): Processor;
112
use(list: PluggableList): Processor;
113
114
interface Plugin<Parameters extends Array<unknown> = []> {
115
(this: Processor, ...parameters: Parameters): Transformer | void;
116
}
117
118
interface Preset {
119
plugins?: PluggableList;
120
settings?: Settings;
121
}
122
```
123
124
[Plugin System](./plugin-system.md)
125
126
### Configuration & Data Management
127
128
Processor configuration, data storage, and state management with freezing capabilities.
129
130
```typescript { .api }
131
data(): Data;
132
data<Key extends keyof Data>(key: Key): Data[Key];
133
data<Key extends keyof Data>(key: Key, value: Data[Key]): Processor;
134
data(dataset: Data): Processor;
135
136
freeze(): Processor;
137
138
// Legacy processor creation (deprecated)
139
copy(): Processor;
140
```
141
142
[Configuration Management](./configuration-management.md)
143
144
## Types
145
146
### Core Types
147
148
```typescript { .api }
149
interface Processor<
150
ParseTree = Node,
151
HeadTree = Node,
152
TailTree = Node,
153
CompileTree = Node,
154
CompileResult = Value
155
> {
156
// Processor methods defined above
157
}
158
159
interface Data {
160
settings?: Settings;
161
[key: string]: unknown;
162
}
163
164
interface Settings {
165
[key: string]: unknown;
166
}
167
168
type Compatible = string | Buffer | VFile | {toString(): string};
169
type Value = string | Uint8Array;
170
```
171
172
### Callback Types
173
174
```typescript { .api }
175
type ProcessCallback<File extends VFile = VFile> = (
176
error?: Error,
177
file?: File
178
) => void;
179
180
type RunCallback<Tree extends Node = Node> = (
181
error?: Error,
182
tree?: Tree,
183
file?: VFile
184
) => void;
185
186
type TransformCallback<Output extends Node = Node> = (
187
error?: Error,
188
tree?: Output,
189
file?: VFile
190
) => void;
191
```
192
193
### Plugin Architecture Types
194
195
```typescript { .api }
196
type Parser<Tree extends Node = Node> = (
197
document: string,
198
file: VFile
199
) => Tree;
200
201
type Compiler<Tree extends Node = Node, Result = Value> = (
202
tree: Tree,
203
file: VFile
204
) => Result;
205
206
type Transformer<Input extends Node = Node, Output extends Node = Input> = (
207
tree: Input,
208
file: VFile,
209
next?: TransformCallback<Output>
210
) => Output | Error | Promise<Output> | void;
211
```
212
213
### Extended Types
214
215
```typescript { .api }
216
type Pluggable = Plugin | PluginTuple | Preset;
217
type PluggableList = Array<Pluggable>;
218
type PluginTuple<Parameters extends Array<unknown> = []> = [
219
Plugin<Parameters>,
220
...Parameters
221
];
222
223
interface CompileResultMap {
224
Uint8Array: Uint8Array;
225
string: string;
226
}
227
228
type CompileResults = CompileResultMap[keyof CompileResultMap];
229
230
// VFile with result handling
231
type VFileWithOutput<Result = CompileResults> = VFile & {
232
value: Result extends string | Uint8Array ? Result : never;
233
result?: Result extends string | Uint8Array ? never : Result;
234
};
235
```
236
237
### Type Augmentation
238
239
Extend unified interfaces for custom compiler results and shared data:
240
241
```typescript { .api }
242
// Augment CompileResultMap for custom results
243
declare module "unified" {
244
interface CompileResultMap {
245
ReactNode: ReactNode; // For rehype-react
246
CustomResult: CustomType; // Custom compiler result
247
}
248
}
249
250
// Augment Data interface for shared plugin data
251
declare module "unified" {
252
interface Data {
253
htmlVoidElements?: Array<string>;
254
customConfig?: CustomConfigType;
255
}
256
}
257
258
// Augment Settings for parser/compiler options
259
declare module "unified" {
260
interface Settings {
261
bullet?: "*" | "+" | "-";
262
emphasis?: "*" | "_";
263
customSetting?: string;
264
}
265
}
266
```
267