js-self-profiling-utils

APIs to parse and summarize JS Self-Profiling traces.

Installation

npm / yarn / pnpm

npm install js-self-profiling-utils

CDN (Browser)

<script src="https://unpkg.com/js-self-profiling-utils"></script>
<!-- or -->
<script src="https://cdn.jsdelivr.net/npm/js-self-profiling-utils"></script>

Usage

ES Modules (TypeScript / Modern JS)

import { summarizeTrace, printCallTree } from 'js-self-profiling-utils';
import type { ProfilerTrace } from 'js-self-profiling-utils';

// After collecting a trace with the JS Self-Profiling API
const trace: ProfilerTrace = await profiler.stop();

const summary = summarizeTrace(trace);

console.log('Total samples:', summary.totalSamples);
console.log('Top functions:', summary.topFunctions);

// Print call tree to console
printCallTree(summary.callTree);

// Export folded stacks for flamegraph tools
const folded = summary.toFoldedStacks();

CommonJS (Node.js)

const { summarizeTrace, printCallTree } = require('js-self-profiling-utils');

const summary = summarizeTrace(trace);

Browser (Script Tag)

<script src="https://unpkg.com/js-self-profiling-utils"></script>
<script>
  const { summarizeTrace, printCallTree } = JSSelfProfilingUtils;
  
  // Use the APIs
  const summary = summarizeTrace(trace);
</script>

API

summarizeTrace(trace, options?)

Analyzes a ProfilerTrace and returns aggregated data.

Options: | Option | Type | Default | Description | |--------|------|---------|-------------| | topN | number | 30 | Number of top functions to return | | minPercent | number | 0 | Minimum inclusive percentage threshold | | formatFrame | function | (built-in) | Custom frame formatting function |

Returns: | Property | Type | Description | |----------|------|-------------| | totalSamples | number | Total number of samples in the trace | | topFunctions | TraceRow[] | Array of top functions with inclusive/exclusive counts | | callTree | CallTreeNode | Hierarchical call tree structure | | toFoldedStacks() | () => string | Method to export folded stacks format (for flamegraphs) |

printCallTree(node, options?)

Prints a call tree to console with indentation.

Options: | Option | Type | Default | Description | |--------|------|---------|-------------| | maxDepth | number | 8 | Maximum depth to print | | minCount | number | 1 | Minimum sample count to display |

Development

Prerequisites

• Node.js 18+
• Chrome or Chromium (for E2E tests)

⚠️ Important: The JS Self-Profiling API is only available in Chromium-based browsers (Chrome, Edge). Make sure to open the dev server URL in Chrome.

Setup

# Install dependencies
npm install

# Install Playwright browsers (for E2E tests)
npx playwright install chromium

Running the Dev Server

npm run dev

This starts a Vite dev server at http://localhost:3000 with the required Document-Policy: js-profiling header. Open in Chrome to test the profiler interactively.

Running Tests

# Unit tests
npm test

# Unit tests in watch mode
npm run test:watch

# Unit tests with coverage
npm run test:coverage

# E2E tests (requires Chromium)
npm run test:e2e

# E2E tests with UI
npm run test:e2e:ui

# All tests
npm run test:all

Building

npm run build

Outputs to dist/:

• index.js — ES Module
• index.cjs — CommonJS
• index.umd.js — UMD (for browsers)
• index.d.ts — TypeScript declarations

License

ISC