0
# Data Structures
1

2
Core data structures for representing performance profiles, call trees, and frame information with weight calculations and hierarchical relationships.
3

4
## Capabilities
5

6
### Profile Classes
7

8
Core classes for representing performance profiling data.
9

10
```typescript { .api }
11
/**
12
 * Main profile class representing a complete performance profile
13
 * Contains timing data, call trees, and metadata
14
 */
15
class Profile {
16
  /** Get the human-readable name of this profile */
17
  getName(): string;
18
  
19
  /** Set the name of this profile */
20
  setName(name: string): void;
21
  
22
  /** Get the unit of measurement for weights (e.g., 'milliseconds', 'bytes') */
23
  getWeightUnit(): string;
24
  
25
  /** Get the total weight/duration of this profile */
26
  getTotalWeight(): number;
27
  
28
  /** Get the formatter for displaying weight values */
29
  getValueFormatter(): ValueFormatter;
30
  
31
  /** Get the number of samples in this profile */
32
  getSampleCount(): number;
33
  
34
  /** Check if this profile has timing information */
35
  getHasTiming(): boolean;
36
  
37
  /** Get the minimum timestamp in the profile */
38
  getMinValue(): number;
39
  
40
  /** Get the maximum timestamp in the profile */
41
  getMaxValue(): number;
42
}
43

44
/**
45
 * Collection of related profiles, typically from the same profiling session
46
 */
47
interface ProfileGroup {
48
  /** Human-readable name for this group of profiles */
49
  name: string;
50
  
51
  /** Index of the profile to display by default */
52
  indexToView: number;
53
  
54
  /** Array of profiles in this group */
55
  profiles: Profile[];
56
}
57
```
58

59
### Frame Representation
60

61
Classes and interfaces for representing individual stack frames.
62

63
```typescript { .api }
64
/**
65
 * Metadata for a stack frame
66
 */
67
interface FrameInfo {
68
  /** Unique identifier for this frame */
69
  key: string | number;
70
  
71
  /** Display name of the frame (e.g., function name) */
72
  name: string;
73
  
74
  /** Source file path (optional) */
75
  file?: string;
76
  
77
  /** Line number in source file (1-based, optional) */
78
  line?: number;
79
  
80
  /** Column number in source file (1-based, optional) */
81
  col?: number;
82
}
83

84
/**
85
 * Stack frame with timing and weight information
86
 * Extends HasWeights to track self and total time/memory usage
87
 */
88
class Frame extends HasWeights {
89
  /** Unique identifier for this frame */
90
  key: string | number;
91
  
92
  /** Display name of the frame */
93
  name: string;
94
  
95
  /** Source file path (optional) */
96
  file?: string;
97
  
98
  /** Line number in source file (optional) */
99
  line?: number;
100
  
101
  /** Column number in source file (optional) */
102
  col?: number;
103
  
104
  /** 
105
   * Create a new frame from frame info
106
   * @param frameInfo - Metadata for the frame
107
   */
108
  constructor(frameInfo: FrameInfo);
109
}
110

111
/**
112
 * Base class providing weight tracking functionality
113
 * Used by Frame and CallTreeNode to track timing/memory data
114
 */
115
class HasWeights {
116
  /** Get the self weight (time spent directly in this frame) */
117
  getSelfWeight(): number;
118
  
119
  /** Get the total weight (time spent in this frame and all children) */
120
  getTotalWeight(): number;
121
  
122
  /** Add to the total weight */
123
  addToTotalWeight(delta: number): void;
124
  
125
  /** Add to the self weight */
126
  addToSelfWeight(delta: number): void;
127
  
128
  /** Copy weights from another HasWeights instance */
129
  overwriteWeightWith(other: HasWeights): void;
130
}
131
```
132

133
### Call Tree Structure
134

135
Classes for representing hierarchical call relationships.
136

137
```typescript { .api }
138
/**
139
 * Node in a call tree representing a function call with timing data
140
 * Each node tracks its frame, parent, children, and weight information
141
 */
142
class CallTreeNode extends HasWeights {
143
  /** The frame this node represents */
144
  frame: Frame;
145
  
146
  /** Parent node in the call tree (null for root) */
147
  parent: CallTreeNode | null;
148
  
149
  /** Child nodes representing functions called from this frame */
150
  children: CallTreeNode[];
151
  
152
  /** 
153
   * Create a new call tree node
154
   * @param frame - The frame this node represents
155
   * @param parent - Parent node (null for root)
156
   */
157
  constructor(frame: Frame, parent: CallTreeNode | null);
158
  
159
  /** Check if this is a root node (has no parent) */
160
  isRoot(): boolean;
161
  
162
  /** Get or create a child node for the given frame */
163
  getOrInsertChildWithFrame(frame: Frame): CallTreeNode;
164
}
165
```
166

167
### Profile Builders
168

169
Builder classes for constructing profiles from raw profiling data.
170

171
```typescript { .api }
172
/**
173
 * Builder for call tree based profiles (hierarchical timing data)
174
 * Used for profiles that track function call relationships over time
175
 */
176
class CallTreeProfileBuilder {
177
  /** 
178
   * Create a new call tree profile builder
179
   * @param valueFormatter - Formatter for displaying timing values
180
   */
181
  constructor(valueFormatter?: ValueFormatter);
182
  
183
  /** Get the root node of the call tree */
184
  getRoot(): CallTreeNode;
185
  
186
  /** 
187
   * Enter a frame (start timing)
188
   * @param frame - Frame being entered
189
   * @param at - Timestamp when frame was entered
190
   */
191
  enterFrame(frame: Frame, at: number): void;
192
  
193
  /** 
194
   * Leave a frame (end timing)
195
   * @param frame - Frame being left  
196
   * @param at - Timestamp when frame was left
197
   */
198
  leaveFrame(frame: Frame, at: number): void;
199
  
200
  /** Build the final profile from collected data */
201
  build(): Profile;
202
}
203

204
/**
205
 * Builder for sampled profiles (periodic sampling data)
206
 * Used for profiles that capture stack samples at regular intervals
207
 */
208
class StackListProfileBuilder {
209
  /** 
210
   * Create a new stack list profile builder
211
   * @param valueFormatter - Formatter for displaying sample values
212
   */
213
  constructor(valueFormatter?: ValueFormatter);
214
  
215
  /** 
216
   * Append a stack sample
217
   * @param stack - Array of frames representing the call stack
218
   * @param weight - Weight/duration of this sample
219
   */
220
  appendSample(stack: Frame[], weight: number): void;
221
  
222
  /** Build the final profile from collected samples */
223
  build(): Profile;
224
}
225
```
226

227
### Symbol Remapping
228

229
Type definitions for remapping symbols to source locations.
230

231
```typescript { .api }
232
/**
233
 * Function type for remapping frame symbols
234
 * Used to map minified/compiled symbols back to source names and locations
235
 */
236
type SymbolRemapper = (
237
  frame: Frame
238
) => {
239
  name?: string;
240
  file?: string; 
241
  line?: number;
242
  col?: number;
243
} | null;
244
```
245

246
### Value Formatters
247

248
Classes for formatting profile values for display.
249

250
```typescript { .api }
251
/**
252
 * Base interface for formatting profile values
253
 */
254
interface ValueFormatter {
255
  /** Format a numeric value for display */
256
  format(v: number): string;
257
  
258
  /** Get the unit string (e.g., 'ms', 'bytes') */
259
  unit: string;
260
}
261

262
/**
263
 * Formatter for time values with appropriate unit scaling
264
 */
265
class TimeFormatter implements ValueFormatter {
266
  unit: string;
267
  format(v: number): string;
268
}
269

270
/**
271
 * Formatter for byte/memory values with appropriate unit scaling  
272
 */
273
class ByteFormatter implements ValueFormatter {
274
  unit: string;
275
  format(v: number): string;
276
}
277

278
/**
279
 * Pass-through formatter that displays raw numeric values
280
 */
281
class RawValueFormatter implements ValueFormatter {
282
  unit: string;
283
  format(v: number): string;
284
}
285
```
286

287
**Usage Examples:**
288

289
```typescript
290
import { 
291
  Profile, 
292
  Frame, 
293
  CallTreeProfileBuilder, 
294
  StackListProfileBuilder,
295
  TimeFormatter 
296
} from 'speedscope';
297

298
// Create frames for profiling data
299
const mainFrame = new Frame({
300
  key: 'main',
301
  name: 'main',
302
  file: 'app.js',
303
  line: 1
304
});
305

306
const helperFrame = new Frame({
307
  key: 'helper', 
308
  name: 'helper',
309
  file: 'utils.js',
310
  line: 15
311
});
312

313
// Build a call tree profile
314
const builder = new CallTreeProfileBuilder(new TimeFormatter());
315
builder.enterFrame(mainFrame, 0);
316
builder.enterFrame(helperFrame, 10);
317
builder.leaveFrame(helperFrame, 50);
318
builder.leaveFrame(mainFrame, 100);
319

320
const profile = builder.build();
321
profile.setName('My Profile');
322

323
// Create a profile group
324
const profileGroup = {
325
  name: 'Application Profile',
326
  indexToView: 0,
327
  profiles: [profile]
328
};
329

330
// Build a sampled profile  
331
const sampledBuilder = new StackListProfileBuilder(new TimeFormatter());
332
sampledBuilder.appendSample([mainFrame, helperFrame], 40);
333
sampledBuilder.appendSample([mainFrame], 20);
334

335
const sampledProfile = sampledBuilder.build();
336
```
337

338
## Profile Data Flow
339

340
1. **Raw Data**: Profiler outputs timing/sampling data in various formats
341
2. **Import**: Format-specific importers parse data into Frame and timing information
342
3. **Building**: ProfileBuilder classes construct Profile objects with call trees or sample lists
343
4. **ProfileGroup**: Related profiles are grouped together with metadata
344
5. **Visualization**: Profile data drives the flamechart and timeline visualizations
345

346
## Types
347

348
```typescript { .api }
349
// Core profile data structures
350
type ProfileData = CallTreeProfile | SampledProfile;
351

352
interface CallTreeProfile {
353
  type: 'call-tree';
354
  root: CallTreeNode;
355
}
356

357
interface SampledProfile {
358
  type: 'sampled'; 
359
  samples: StackSample[];
360
}
361

362
interface StackSample {
363
  stack: Frame[];
364
  weight: number;
365
  timestamp?: number;
366
}
367
```