tessl/npm-speedscope

A fast, interactive web-based viewer for performance profiles with support for multiple profiler formats

—

Pending

Overview

Eval results

Files

File Format

Name: tessl/npm-speedscope
Author: tessl

Export and import functionality for speedscope's native JSON file format with comprehensive metadata, event serialization, and schema validation.

Capabilities

Export Functions

Functions for exporting profile data to speedscope's native JSON format.

/**
 * Export a profile group to speedscope's native JSON format
 * @param profileGroup - ProfileGroup containing profiles to export
 * @returns FileFormat.File object representing the complete export
 */
function exportProfileGroup(profileGroup: ProfileGroup): FileFormat.File;

/**
 * Save profile group to a downloadable file in the browser
 * @param profileGroup - ProfileGroup to save
 * @param fileName - Optional custom filename (defaults to profile name)
 */
function saveToFile(profileGroup: ProfileGroup, fileName?: string): void;

Import Functions

Functions for importing speedscope's native JSON format.

/**
 * Import profiles from speedscope JSON format
 * @param jsonData - Parsed JSON data in speedscope format
 * @returns ProfileGroup or null if import fails
 */
function importSpeedscopeProfiles(jsonData: any): ProfileGroup | null;

File Format Specification

Complete type definitions for speedscope's native JSON file format.

/**
 * Root file format interface for speedscope JSON files
 */
interface FileFormat.File {
  /** Schema URL for validation */
  $schema: 'https://www.speedscope.app/file-format-schema.json';
  
  /** Shared data used across all profiles */
  shared: {
    /** Array of frame definitions referenced by profiles */
    frames: FileFormat.Frame[];
  };
  
  /** Array of profile definitions */
  profiles: FileFormat.Profile[];
  
  /** Optional name for the profile group */
  name?: string;
  
  /** Index of profile to display by default (0-based) */
  activeProfileIndex?: number;
  
  /** Name and version of the tool that exported this file */
  exporter?: string;
}

/**
 * Frame definition in the file format
 */
interface FileFormat.Frame {
  /** Display name of the frame */
  name: string;
  
  /** Source file path (optional) */
  file?: string;
  
  /** Line number in source file (1-based, optional) */
  line?: number;
  
  /** Column number in source file (1-based, optional) */
  col?: number;
}

/**
 * Union type for different profile formats
 */
type FileFormat.Profile = FileFormat.EventedProfile | FileFormat.SampledProfile;

/**
 * Event-based profile format for timeline data
 */
interface FileFormat.EventedProfile {
  /** Profile type discriminator */
  type: FileFormat.ProfileType.EVENTED;
  
  /** Human-readable profile name */
  name: string;
  
  /** Unit for all timing values */
  unit: FileFormat.ValueUnit;
  
  /** Starting timestamp for the profile */
  startValue: number;
  
  /** Ending timestamp for the profile */
  endValue: number;
  
  /** Array of frame open/close events */
  events: (FileFormat.OpenFrameEvent | FileFormat.CloseFrameEvent)[];
}

/**
 * Sample-based profile format for periodic sampling
 */
interface FileFormat.SampledProfile {
  /** Profile type discriminator */
  type: FileFormat.ProfileType.SAMPLED;
  
  /** Human-readable profile name */
  name: string;
  
  /** Unit for all weight values */
  unit: FileFormat.ValueUnit;
  
  /** Starting timestamp for the profile */
  startValue: number;
  
  /** Ending timestamp for the profile */
  endValue: number;
  
  /** Array of call stacks, each element is array of frame indices */
  samples: number[][];
  
  /** Weight/duration for each sample (same length as samples array) */
  weights: number[];
}

Profile Types and Events

Enums and interfaces for profile structure.

/**
 * Enum for different profile types
 */
enum FileFormat.ProfileType {
  EVENTED = 'evented',
  SAMPLED = 'sampled'
}

/**
 * Enum for event types in evented profiles
 */
enum FileFormat.EventType {
  OPEN_FRAME = 'O',
  CLOSE_FRAME = 'C'
}

/**
 * Event indicating a stack frame was entered
 */
interface FileFormat.OpenFrameEvent {
  /** Event type discriminator */
  type: FileFormat.EventType.OPEN_FRAME;
  
  /** Timestamp when frame was entered */
  at: number;
  
  /** Index into the shared frames array */
  frame: number;
}

/**
 * Event indicating a stack frame was exited
 */
interface FileFormat.CloseFrameEvent {
  /** Event type discriminator */
  type: FileFormat.EventType.CLOSE_FRAME;
  
  /** Timestamp when frame was exited */
  at: number;
  
  /** Index into the shared frames array */
  frame: number;
}

/**
 * Supported units for profile values
 */
type FileFormat.ValueUnit = 
  | 'none'
  | 'nanoseconds'
  | 'microseconds' 
  | 'milliseconds'
  | 'seconds'
  | 'bytes';

Usage Examples:

import { 
  exportProfileGroup, 
  saveToFile, 
  importSpeedscopeProfiles 
} from 'speedscope';

// Export profile group to JSON format
const profileGroup = {
  name: 'My Application Profile',
  indexToView: 0,
  profiles: [profile1, profile2]
};

const exportedData = exportProfileGroup(profileGroup);

// Save to file in browser
saveToFile(profileGroup, 'my-profile.speedscope.json');

// Import from JSON data
const jsonData = JSON.parse(jsonString);
const importedProfileGroup = importSpeedscopeProfiles(jsonData);

// Example exported file structure
const exampleFile: FileFormat.File = {
  $schema: 'https://www.speedscope.app/file-format-schema.json',
  exporter: 'speedscope@1.23.1',
  name: 'CPU Profile',
  activeProfileIndex: 0,
  shared: {
    frames: [
      { name: 'main', file: 'app.js', line: 1 },
      { name: 'helper', file: 'utils.js', line: 15 }
    ]
  },
  profiles: [{
    type: 'evented',
    name: 'Main Thread',
    unit: 'milliseconds',
    startValue: 0,
    endValue: 1000,
    events: [
      { type: 'O', at: 0, frame: 0 },
      { type: 'O', at: 100, frame: 1 },
      { type: 'C', at: 200, frame: 1 },
      { type: 'C', at: 1000, frame: 0 }
    ]
  }]
};

File Format Schema

The speedscope file format includes a JSON schema for validation:

Schema URL: https://www.speedscope.app/file-format-schema.json
Version Support: Backward compatible across speedscope versions
Validation: Files can be validated against the schema for correctness
Extensions: Schema allows additional properties for future extensions

Export Process

When exporting profiles, speedscope:

Frame Deduplication: Combines identical frames across profiles into shared array
Index Mapping: Maps frame references to indices in shared frames array
Event Serialization: Converts call tree or sample data to event sequences
Metadata Addition: Adds exporter information, timestamps, and version data
Schema Compliance: Ensures output conforms to the JSON schema

Import Process

When importing speedscope files, the system:

Schema Validation: Checks for required fields and proper structure
Frame Reconstruction: Rebuilds Frame objects from shared frames array
Profile Reconstruction: Recreates Profile objects from event data or samples
Metadata Extraction: Extracts names, units, and timing information
ProfileGroup Assembly: Combines profiles into a ProfileGroup structure

File Naming Convention

Speedscope uses the .speedscope.json extension for native format files:

Detection: Automatic format detection based on file extension
Priority: .speedscope.json files are processed with highest priority
Schema: Files with this extension must include the schema URL
Validation: Extension indicates expectation of schema compliance

Types

// Type aliases for common file format operations
type SpeedscopeFile = FileFormat.File;
type SpeedscopeFrame = FileFormat.Frame;
type SpeedscopeProfile = FileFormat.Profile;

// Export function signatures
type ExportFunction = (profileGroup: ProfileGroup) => FileFormat.File;
type SaveFunction = (profileGroup: ProfileGroup, fileName?: string) => void;
type ImportFunction = (jsonData: any) => ProfileGroup | null;

// Event sequence types for evented profiles
type EventSequence = (FileFormat.OpenFrameEvent | FileFormat.CloseFrameEvent)[];
type SampleSequence = { samples: number[][], weights: number[] };

Install with Tessl CLI