0
# Data Types and Structures
1

2
Core type definitions for module trees, bundle data, and visualization information used throughout the plugin.
3

4
```typescript
5
import { 
6
  isModuleTree,
7
  VisualizerData,
8
  ModuleTree,
9
  ModuleTreeLeaf,
10
  ModuleLengths,
11
  ModulePart,
12
  ModuleImport,
13
  ModuleMeta,
14
  ModuleUID,
15
  BundleId,
16
  SizeKey,
17
  TemplateType
18
} from "rollup-plugin-visualizer";
19

20
// Internal compression utilities (advanced usage)
21
import { SizeGetter, createGzipSizeGetter, createBrotliSizeGetter } from "rollup-plugin-visualizer/dist/plugin/compress";
22
import * as zlib from "zlib";
23
```
24

25
## Capabilities
26

27
### Visualizer Data Structure
28

29
Complete dataset structure containing all information needed for visualization.
30

31
```typescript { .api }
32
/**
33
 * Complete visualization dataset containing module hierarchy and metadata
34
 */
35
interface VisualizerData {
36
  /** Data format version number */
37
  version: number;
38
  /** Module hierarchy tree structure */
39
  tree: ModuleTree;
40
  /** Module parts lookup by UID */
41
  nodeParts: Record<ModuleUID, ModulePart>;
42
  /** Module metadata lookup by UID */
43
  nodeMetas: Record<ModuleUID, ModuleMeta>;
44
  /** Environment information (rollup version, etc.) */
45
  env: { [key: string]: unknown };
46
  /** Generation options used */
47
  options: {
48
    gzip: boolean;
49
    brotli: boolean;
50
    sourcemap: boolean;
51
  };
52
}
53
```
54

55
This is the root data structure that contains all information needed to generate visualizations. It's used internally by the plugin and output by the `raw-data` template.
56

57
### Module Tree Structures
58

59
Hierarchical tree structures representing the module organization.
60

61
```typescript { .api }
62
/**
63
 * Tree node containing child modules
64
 */
65
interface ModuleTree {
66
  /** Node name (directory or bundle name) */
67
  name: string;
68
  /** Child nodes (can be trees or leaves) */
69
  children: Array<ModuleTree | ModuleTreeLeaf>;
70
}
71

72
/**
73
 * Leaf node representing an individual module
74
 */
75
interface ModuleTreeLeaf {
76
  /** Module name (file name) */
77
  name: string;
78
  /** Unique identifier for this module */
79
  uid: ModuleUID;
80
}
81

82
/**
83
 * Type guard to distinguish between tree nodes and leaf nodes
84
 * @param mod - Module node to test
85
 * @returns true if the node is a ModuleTree (has children), false if it's a leaf
86
 */
87
function isModuleTree(mod: ModuleTree | ModuleTreeLeaf): mod is ModuleTree;
88
```
89

90
The tree structure represents the hierarchical organization of modules, where `ModuleTree` nodes represent directories or logical groupings, and `ModuleTreeLeaf` nodes represent individual files.
91

92
**Usage Example:**
93

94
```typescript
95
import { isModuleTree } from "rollup-plugin-visualizer";
96

97
function processNode(node: ModuleTree | ModuleTreeLeaf) {
98
  if (isModuleTree(node)) {
99
    // Process directory/tree node
100
    console.log(`Directory: ${node.name} with ${node.children.length} children`);
101
    node.children.forEach(processNode);
102
  } else {
103
    // Process file/leaf node
104
    console.log(`File: ${node.name} (${node.uid})`);
105
  }
106
}
107
```
108

109
### Module Metadata Types
110

111
Detailed metadata about individual modules including sizes and relationships.
112

113
```typescript { .api }
114
/**
115
 * Size measurements for modules in different formats
116
 */
117
interface ModuleLengths {
118
  /** Rendered size in bytes */
119
  renderedLength: number;
120
  /** Gzipped size in bytes */
121
  gzipLength: number;
122
  /** Brotli compressed size in bytes */
123
  brotliLength: number;
124
}
125

126
/**
127
 * Module part with size information and metadata reference
128
 */
129
type ModulePart = {
130
  /** Reference to module metadata */
131
  metaUid: ModuleUID;
132
} & ModuleLengths;
133

134
/**
135
 * Import/export relationship between modules
136
 */
137
type ModuleImport = {
138
  /** Target module unique identifier */
139
  uid: ModuleUID;
140
  /** Whether this is a dynamic import */
141
  dynamic?: boolean;
142
};
143

144
/**
145
 * Complete metadata for a module including relationships
146
 */
147
type ModuleMeta = {
148
  /** Module parts by bundle ID */
149
  moduleParts: Record<BundleId, ModuleUID>;
150
  /** Modules that import this module */
151
  importedBy: ModuleImport[];
152
  /** Modules imported by this module */
153
  imported: ModuleImport[];
154
  /** Whether this is an entry point module */
155
  isEntry?: boolean;
156
  /** Whether this is an external module */
157
  isExternal?: boolean;
158
  /** Module identifier (file path) */
159
  id: string;
160
};
161
```
162

163
These types capture detailed information about each module, including its size in various formats and its relationships with other modules.
164

165
### Identifier Types
166

167
Type aliases for unique identifiers used throughout the system.
168

169
```typescript { .api }
170
/** Unique identifier for modules */
171
type ModuleUID = string;
172

173
/** Bundle identifier */
174
type BundleId = string;
175

176
/** Size measurement keys */
177
type SizeKey = "renderedLength" | "gzipLength" | "brotliLength";
178
```
179

180
### Template Types
181

182
Available visualization template identifiers.
183

184
```typescript { .api }
185
/** Available visualization template types */
186
type TemplateType = "sunburst" | "treemap" | "network" | "raw-data" | "list" | "flamegraph";
187

188
/** Array of all available template types */
189
const templates: ReadonlyArray<TemplateType>;
190
```
191

192
The `templates` array contains all available template type strings and can be used for validation or UI generation.
193

194
**Usage Example:**
195

196
```typescript
197
import templates from "rollup-plugin-visualizer/dist/plugin/template-types";
198

199
// Validate template choice
200
function isValidTemplate(template: string): template is TemplateType {
201
  return templates.includes(template as TemplateType);
202
}
203

204
// Generate UI options
205
const templateOptions = templates.map(template => ({
206
  value: template,
207
  label: template.charAt(0).toUpperCase() + template.slice(1)
208
}));
209
```
210

211
### Compression Utilities (Advanced)
212

213
Internal utilities for calculating compressed sizes of code strings.
214

215
```typescript { .api }
216
/**
217
 * Function type for calculating size of code strings
218
 */
219
type SizeGetter = (code: string) => Promise<number>;
220

221
/**
222
 * Creates a gzip size calculator with custom compression options
223
 * @param options - zlib compression options
224
 * @returns Function that calculates gzipped size of code strings
225
 */
226
function createGzipSizeGetter(options: zlib.ZlibOptions): SizeGetter;
227

228
/**
229
 * Creates a brotli size calculator with custom compression options
230
 * @param options - brotli compression options
231
 * @returns Function that calculates brotli compressed size of code strings
232
 */
233
function createBrotliSizeGetter(options: zlib.BrotliOptions): SizeGetter;
234
```
235

236
These utilities are used internally by the plugin when `gzipSize` or `brotliSize` options are enabled. They're exposed for advanced use cases where custom compression analysis is needed.
237

238
**Usage Example:**
239

240
```typescript
241
import { createGzipSizeGetter, createBrotliSizeGetter } from "rollup-plugin-visualizer/dist/plugin/compress";
242

243
// Create custom size getters with specific compression settings
244
const customGzipSizer = createGzipSizeGetter({ 
245
  level: 6, // Custom compression level
246
  windowBits: 15 
247
});
248

249
const customBrotliSizer = createBrotliSizeGetter({
250
  params: {
251
    [require('zlib').constants.BROTLI_PARAM_QUALITY]: 4
252
  }
253
});
254

255
// Use with code strings
256
const code = "function example() { return 'hello world'; }";
257
const gzipSize = await customGzipSizer(code);
258
const brotliSize = await customBrotliSizer(code);
259

260
console.log(`Original: ${code.length}, Gzip: ${gzipSize}, Brotli: ${brotliSize}`);
261
```