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