TS Pressure Observer

Overview

TS Pressure Observer provides complete TypeScript type definitions for the browser’s Compute Pressure API. The Compute Pressure API lets web apps monitor CPU and thermal pressure in real time — crucial for adaptive audio processing, game engines, and any performance-sensitive application that needs to gracefully degrade under load.

Since the API is still experimental and not yet included in TypeScript’s built-in DOM types, this package fills the gap with fully documented ambient declarations for PressureObserver, PressureRecord, and all related interfaces.

Why This Matters

For real-time audio and media applications, CPU headroom is everything. A web-based synthesizer or audio effect running on a user’s device needs to know when CPU pressure is rising before it causes audible glitches. This package makes it possible to observe pressure states — nominal, fair, serious, critical — with full type safety, so you can build adaptive systems that respond intelligently:

import "ts-pressure-observer"

const observer = new PressureObserver((changes) => {
  const current = changes.at(-1)!
  if (current.state === "serious") {
    // Reduce polyphony, disable expensive effects, etc.
    console.log(`🟡 CPU Serious @ ${current.time.toFixed(0)}ms`)
  }
})

observer.observe("cpu", { sampleInterval: 1000 })

Features

• Ambient type declarations — Drop-in types for PressureObserver, PressureRecord, PressureRecordState, PressureRecordSource, and PressureObserveOptions that augment the global scope
• Rich JSDoc documentation — Every type and method is annotated with descriptions, emoji indicators for pressure levels, and usage notes directly from the spec
• Secure context detection — The included example gracefully handles missing API support and non-HTTPS contexts
• Configurable sample interval — Control polling rate via sampleInterval (defaults to fastest system rate when set to 0)
• Live demo — Ships with an index.html + Bun dev server that displays CPU pressure state changes in the browser
• GitHub Pages deployment — CI workflow builds and deploys the demo automatically on push to main

Type Definitions

The index.d.ts file declares all the types as ambient globals, so importing the package is enough to get full IntelliSense:

declare type PressureRecordState = "nominal" | "fair" | "serious" | "critical"
declare type PressureRecordSource = "thermals" | "cpu"

declare interface PressureRecord {
  readonly source: PressureRecordSource
  readonly state: PressureRecordState
  readonly time: number
  toJSON: () => Pick<PressureRecord, 'source' | 'state' | 'time'>
}

declare class PressureObserver {
  constructor(callback: PressureObserverCallback)
  static knownSources: readonly PressureRecordSource[]
  observe: (source: PressureRecordSource, options?: PressureObserveOptions) => Promise<void | never>
  unobserve: () => void
  disconnect: () => void
  takeRecords: () => PressureRecord[]
}

Tech Stack

Language	TypeScript
Platform	Browser (Compute Pressure API)
Build & Runtime	Bun
Hosting	GitHub Pages
CI/CD	GitHub Actions

Source Code

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