0
# Processing Pipeline
1

2
Core content processing functionality providing a three-phase pipeline for parsing text to syntax trees, running transformations, and compiling back to text format. Supports both synchronous and asynchronous operation modes.
3

4
## Capabilities
5

6
### Parse
7

8
Parses text input into a syntax tree using the configured parser.
9

10
```typescript { .api }
11
/**
12
 * Parse text to a syntax tree
13
 * @param file - File to parse (string, VFile, or compatible)
14
 * @returns Syntax tree representing the input
15
 * @throws Error if no parser is configured
16
 */
17
parse<ParseTree extends Node = Node>(file?: Compatible): ParseTree;
18
```
19

20
**Usage Examples:**
21

22
```javascript
23
import { unified } from "unified";
24

25
const processor = unified().use(someParser);
26

27
// Parse string content
28
const tree = processor.parse("# Hello World");
29

30
// Parse with VFile
31
import { VFile } from "vfile";
32
const file = new VFile({value: "# Hello", path: "readme.md"});
33
const tree = processor.parse(file);
34
```
35

36
**Errors:**
37
- Throws `"Cannot \`parse\` without \`parser\`"` if no parser is configured
38

39
### Stringify
40

41
Compiles a syntax tree back to text using the configured compiler.
42

43
```typescript { .api }
44
/**
45
 * Compile a syntax tree to text
46
 * @param tree - Syntax tree to compile
47
 * @param file - File context (optional)
48
 * @returns Compiled text or custom result
49
 * @throws Error if no compiler is configured
50
 */
51
stringify<CompileTree extends Node = Node, CompileResult = CompileResults>(
52
  tree: CompileTree,
53
  file?: Compatible
54
): CompileResult;
55
```
56

57
**Usage Examples:**
58

59
```javascript
60
import { unified } from "unified";
61

62
const processor = unified()
63
  .use(someParser)
64
  .use(someCompiler);
65

66
const tree = processor.parse("# Hello World");
67
const output = processor.stringify(tree);
68
console.log(String(output)); // Compiled text
69
```
70

71
**Result Types:**
72
- `string` or `Uint8Array`: Standard text output
73
- Custom types: When using specialized compilers (e.g., React components)
74

75
### Run (Async)
76

77
Runs all configured transformers on a syntax tree asynchronously.
78

79
```typescript { .api }
80
/**
81
 * Run transformers on a syntax tree (async)
82
 * @param tree - Tree to transform
83
 * @param file - File context (optional)
84
 * @param done - Completion callback (optional)
85
 * @returns Promise resolving to transformed tree if no callback
86
 */
87
run(
88
  tree: HeadTree extends undefined ? Node : HeadTree,
89
  file?: Compatible,
90
  done?: RunCallback<TailTree extends undefined ? Node : TailTree>
91
): Promise<TailTree extends undefined ? Node : TailTree> | undefined;
92

93
// Overloaded signatures
94
run(
95
  tree: HeadTree extends undefined ? Node : HeadTree,
96
  done: RunCallback<TailTree extends undefined ? Node : TailTree>
97
): undefined;
98
```
99

100
**Usage Examples:**
101

102
```javascript
103
import { unified } from "unified";
104

105
const processor = unified()
106
  .use(someParser)
107
  .use(someTransformer)
108
  .use(anotherTransformer);
109

110
// Promise-based usage
111
const tree = processor.parse("content");
112
const transformedTree = await processor.run(tree);
113

114
// Callback-based usage
115
processor.run(tree, (error, resultTree, file) => {
116
  if (error) throw error;
117
  console.log("Transformed:", resultTree);
118
});
119

120
// With file context
121
import { VFile } from "vfile";
122
const file = new VFile("content");
123
const tree = processor.parse(file);
124
const result = await processor.run(tree, file);
125
```
126

127
### Run Sync
128

129
Runs all configured transformers on a syntax tree synchronously.
130

131
```typescript { .api }
132
/**
133
 * Run transformers on a syntax tree (sync)
134
 * @param tree - Tree to transform
135
 * @param file - File context (optional)
136
 * @returns Transformed tree
137
 * @throws Error if async transformers are configured
138
 */
139
runSync<HeadTree extends Node = Node, TailTree extends Node = Node>(
140
  tree: HeadTree,
141
  file?: Compatible
142
): TailTree;
143
```
144

145
**Usage Examples:**
146

147
```javascript
148
const processor = unified()
149
  .use(someParser)
150
  .use(someSyncTransformer);
151

152
const tree = processor.parse("content");
153
const transformedTree = processor.runSync(tree);
154
```
155

156
**Errors:**
157
- Throws `"\`runSync\` finished async. Use \`run\` instead"` if async transformers are used
158

159
### Process (Async)
160

161
Complete processing pipeline: parse → run → stringify, executed asynchronously.
162

163
```typescript { .api }
164
/**
165
 * Process content through complete pipeline (async)
166
 * @param file - Input content to process
167
 * @param done - Completion callback (optional)
168
 * @returns Promise resolving to processed VFile if no callback
169
 */
170
process(
171
  file?: Compatible,
172
  done?: ProcessCallback<VFileWithOutput<CompileResult>>
173
): Promise<VFileWithOutput<CompileResult>> | undefined;
174
```
175

176
**Usage Examples:**
177

178
```javascript
179
import { unified } from "unified";
180

181
const processor = unified()
182
  .use(someParser)
183
  .use(someTransformer)
184
  .use(someCompiler);
185

186
// Promise-based usage
187
const result = await processor.process("# Hello World");
188
console.log(String(result)); // Final output
189
console.log(result.path);    // File metadata
190

191
// Callback-based usage
192
processor.process("content", (error, file) => {
193
  if (error) throw error;
194
  console.log("Result:", String(file));
195
});
196

197
// With VFile input
198
import { VFile } from "vfile";
199
const input = new VFile({value: "content", path: "input.md"});
200
const result = await processor.process(input);
201
```
202

203
**Result Structure:**
204
- `file.value`: Contains the final compiled output (string/Uint8Array)
205
- `file.result`: Contains custom compiler results (non-serialized output)
206
- `file.messages`: Processing messages and warnings
207
- File metadata preserved throughout pipeline
208

209
### Process Sync
210

211
Complete processing pipeline executed synchronously.
212

213
```typescript { .api }
214
/**
215
 * Process content through complete pipeline (sync)
216
 * @param file - Input content to process
217
 * @returns Processed VFile with result
218
 * @throws Error if async operations are detected
219
 */
220
processSync<CompileResult = CompileResults>(
221
  file?: Compatible
222
): VFileWithOutput<CompileResult>;
223
```
224

225
**Usage Examples:**
226

227
```javascript
228
const processor = unified()
229
  .use(someParser)
230
  .use(someSyncTransformer)
231
  .use(someCompiler);
232

233
const result = processor.processSync("# Hello World");
234
console.log(String(result));
235
```
236

237
**Errors:**
238
- Throws `"Cannot \`process\` without \`parser\`"` if no parser configured
239
- Throws `"Cannot \`process\` without \`compiler\`"` if no compiler configured  
240
- Throws `"\`processSync\` finished async. Use \`process\` instead"` for async operations
241

242
## Processing Phases
243

244
### Phase 1: Parse
245
- Converts input text/file to syntax tree (AST)
246
- Uses configured `parser` function
247
- Input: string, VFile, or compatible object
248
- Output: Node (syntax tree)
249

250
### Phase 2: Run
251
- Applies all configured transformers to the syntax tree
252
- Transformers can modify, replace, or validate the tree
253
- Supports sync/async/Promise-based transformers
254
- Input: Node (from parse phase)
255
- Output: Node (transformed tree)
256

257
### Phase 3: Stringify
258
- Converts syntax tree back to text/binary output
259
- Uses configured `compiler` function
260
- Input: Node (from run phase)
261
- Output: string, Uint8Array, or custom result type
262

263
## Error Handling
264

265
### Configuration Errors
266
- Missing parser/compiler throw descriptive errors
267
- Operations on frozen processors are prevented
268

269
### Runtime Errors
270
- Transformer errors propagate through callbacks/promises
271
- Sync methods throw immediately on async operations
272
- File processing errors include context information
273

274
### Async vs Sync Behavior
275
- Async methods support callbacks and promises
276
- Sync methods throw if async operations are detected
277
- Error messages clearly indicate required alternative method