TS Self Profiling

Overview

TS Self Profiling provides complete TypeScript type definitions for the browser’s JS Self-Profiling API — an emerging W3C standard that lets web applications collect CPU profiles from real users in production. By importing this package, you get full type coverage for the Profiler class, its configuration options, and the resulting trace data, enabling type-safe performance profiling without relying on DevTools.

This is especially useful for audio and real-time web applications where performance bottlenecks need to be identified in the field, not just the lab.

The Problem

Browser DevTools profiling is great during development, but useless for diagnosing performance issues your users experience in production. The JS Self-Profiling API solves this by letting your code programmatically sample the call stack at configurable intervals — but the API has no built-in TypeScript support. This package fills that gap.

Features

• Complete type definitions — Fully typed interfaces for Profiler, ProfilerTrace, ProfilerSample, ProfilerStack, ProfilerFrame, and ProfilerInitOptions, all mapped to the W3C spec
• Configurable sampling — Set sampleInterval in microseconds and maxBufferSize in samples to control profiling granularity and memory usage
• Rich trace data — Typed access to stack frames with function names, source file references, line/column numbers, and hierarchical stack relationships
• Document-Policy header support — The included dev server demonstrates the required Document-Policy: js-profiling HTTP header that browsers need to enable the API
• Zero runtime footprint — Pure .d.ts type declarations with no runtime code shipped
• Working example — Includes a full browser demo (example.ts + index.html) with annotated trace output

How It Works

Import the package and the Profiler class becomes available globally with full type inference:

import "ts-self-profiling"

const profiler = new Profiler({
  sampleInterval: 100, // microseconds between samples
  maxBufferSize: 100_000, // max samples to collect
});

// ... run your workload ...

const trace = await profiler.stop();

The returned ProfilerTrace gives you structured access to everything the profiler captured:

// Stack frames with source locations
trace.frames   // { name: string, resourceId?: number, line?: number, column?: number }[]

// Resource URLs (scripts that were executing)
trace.resources // string[]

// Timestamped samples pointing into the stack tree
trace.samples  // { timestamp: DOMHighResTimeStamp, stackId?: number }[]

// Stack tree with parent references
trace.stacks   // { frameId: number, parentId?: number }[]

Server Requirement

The API requires the server to send a Document-Policy: js-profiling header. The included serve.ts demonstrates this:

const headers = new Headers()
headers.set("Document-Policy", "js-profiling")
const response = new Response(file, { headers })

Tech Stack

Language	TypeScript
Platform	Browser (JS Self-Profiling API / W3C WICG)
Build Tool	Bun
CI/CD	GitHub Actions → GitHub Pages
Package Format	npm (.d.ts type declarations)

Source Code

The source code is available on the project’s GitHub repository.