0
# Runtime Utilities
1

2
Low-level utilities for working with content trees, compression, and AST manipulation for advanced content processing scenarios. These utilities provide direct access to the internal tree structures used by Nuxt Content.
3

4
## Capabilities
5

6
### Compress Tree
7

8
Converts a full MDC (Markdown Components) AST tree into a compressed Minimark tree format for efficient storage and transmission.
9

10
```typescript { .api }
11
/**
12
 * Converts an MDC root tree into compressed Minimark format
13
 * @param input - The MDC root tree to compress
14
 * @returns Compressed Minimark tree representation
15
 */
16
function compressTree(input: MDCRoot): MinimarkTree;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import { compressTree } from '@nuxt/content/runtime';
23

24
// Compress a content tree for storage
25
const mdcTree = {
26
  type: 'root',
27
  children: [
28
    { type: 'element', tagName: 'h1', children: [{ type: 'text', value: 'Hello' }] },
29
    { type: 'element', tagName: 'p', children: [{ type: 'text', value: 'World' }] }
30
  ]
31
};
32

33
const compressed = compressTree(mdcTree);
34
// Result: { type: 'minimark', value: '...' } (compressed representation)
35
```
36

37
### Decompress Tree
38

39
Converts a compressed Minimark tree back into a full MDC AST tree for rendering and manipulation.
40

41
```typescript { .api }
42
/**
43
 * Converts a compressed tree back into full MDC format
44
 * @param input - The compressed tree (Tree format) to decompress
45
 * @returns Full MDC root tree for rendering
46
 */
47
function decompressTree(input: Tree): MDCRoot;
48
```
49

50
**Usage Examples:**
51

52
```typescript
53
import { decompressTree } from '@nuxt/content/runtime';
54

55
// Decompress a stored tree for rendering
56
const compressedTree = { type: 'minimark', value: '...' };
57
const mdcTree = decompressTree(compressedTree);
58

59
// Result: Full MDC tree ready for rendering
60
// {
61
//   type: 'root',
62
//   children: [
63
//     { type: 'element', tagName: 'h1', children: [...] },
64
//     { type: 'element', tagName: 'p', children: [...] }
65
//   ]
66
// }
67
```
68

69
### Visit Tree
70

71
Traverses a content tree and allows modification of nodes matching specific criteria using a visitor pattern.
72

73
```typescript { .api }
74
/**
75
 * Traverses tree nodes and applies visitor function to matching nodes
76
 * @param tree - The tree to traverse (Tree format)
77
 * @param checker - Function to test if a node should be visited
78
 * @param visitor - Function to transform matching nodes
79
 */
80
function visit(
81
  tree: Tree, 
82
  checker: (node: Node) => boolean, 
83
  visitor: (node: Node) => Node | undefined
84
): void;
85
```
86

87
**Usage Examples:**
88

89
```typescript
90
import { visit } from '@nuxt/content/runtime';
91

92
// Transform all heading nodes in a tree
93
visit(
94
  contentTree,
95
  (node) => node.type === 'element' && ['h1', 'h2', 'h3'].includes(node.tagName),
96
  (node) => {
97
    // Add an ID attribute to all headings
98
    return {
99
      ...node,
100
      properties: {
101
        ...node.properties,
102
        id: node.children?.[0]?.value?.toLowerCase().replace(/\s+/g, '-')
103
      }
104
    };
105
  }
106
);
107

108
// Remove all images from a tree
109
visit(
110
  contentTree,
111
  (node) => node.type === 'element' && node.tagName === 'img',
112
  () => undefined // Remove the node by returning undefined
113
);
114

115
// Convert code blocks to a specific format
116
visit(
117
  contentTree,
118
  (node) => node.type === 'element' && node.tagName === 'code',
119
  (node) => ({
120
    ...node,
121
    properties: {
122
      ...node.properties,
123
      className: ['highlight', ...(node.properties?.className || [])]
124
    }
125
  })
126
);
127
```
128

129
## Types
130

131
```typescript { .api }
132
interface MDCRoot {
133
  type: 'root';
134
  children: Node[];
135
}
136

137
interface MinimarkTree {
138
  type: 'minimark';
139
  value: unknown;
140
}
141

142
interface Tree {
143
  type: string;
144
  value?: unknown;
145
}
146

147
interface Node {
148
  type: string;
149
  [key: string]: unknown;
150
}
151
```
152

153
## Use Cases
154

155
**Tree Compression**: Use `compressTree` when you need to store or transmit content trees efficiently, such as caching processed content or sending content over a network.
156

157
**Tree Decompression**: Use `decompressTree` when you need to restore a compressed tree for rendering or further processing.
158

159
**Tree Traversal**: Use `visit` for:
160
- Adding metadata to specific node types
161
- Transforming content structure
162
- Removing or filtering nodes
163
- Implementing custom content processors
164
- Building content analysis tools