API reference

The assertion API

Everything exported by @motionvector/webcodecs-census. Two halves: the instrumentation that runs inside a context, and the verdict layer that turns a census into pass or fail.

import {
  installCensus, localCensus, timeline, resetCensus, VERSION,
  checkLeaks, expectNoLeaks, expectNoLeakedFrames, summarize, totalLive,
  TRACKED,
} from '@motionvector/webcodecs-census';

Verdicts

checkLeaks(censuses, options?)

Builds a LeakReport without throwing. checkLeaks(...).ok is the boolean form of every assertion below.

const report = checkLeaks(await session.census(), { types: 'all', allow: { VideoFrame: 2 } });
if (!report.ok) console.error(report.message);

LeakOptions

LeakReport

How ok is decided

ok is true when all of these hold:

• no enforced type has more live objects than its allow entry (default 0),
• no tracked type has any collectedUnclosed at all, and
• if failOnOverClose is on, no close() threw.

No leaks in VideoFrame, AudioData, ImageBitmap — but VideoDecoder=47 still
live and not enforced. Pass types: 'all' to check those too.

What the platform does behind your back (v0.3.0)

Two things happen to a codec that no close() call in your source explains. Getting either one wrong makes the report lie in a different direction.

A failing codec is closed by the platform

The spec's Close algorithm sets [[state]] to "closed" before it invokes your error callback, so no close() call ever reaches the instrumentation. Left alone, that codec stays counted live and, once collected, is filed as collectedUnclosed — "definitively leaked" for a resource the platform had already reclaimed.

The census reconciles live codecs against their own state, records the departure as the closedByPlatform fate, and does not call it a leak. Reconciliation runs on every sample tick and at the top of localCensus(), so a census taken straight after a decode error is already correct. A detector that invents leaks in an error-heavy pipeline is worse than one that stays quiet.

Closing an already-closed codec throws

Measured on Chrome 151: the four codec types throw InvalidStateError; the three frame types are idempotent and throw nothing. From a library closing out of a floating .finally(), that surfaces as an unhandled rejection no application code can catch — the platform reports it to nobody who can act on it.

Those calls are counted, grouped by type, message and calling line, in ContextCensus.overCloses and LeakReport.overCloses. The throw is observed, never swallowed: the caller still sees what the platform threw, or instrumenting the app would change how it behaves.

3 close() call(s) threw — a codec was closed twice:
  3x VideoDecoder: Cannot call 'close' on a closed codec (in worker)
      at decodePump (pipeline.js:812:20)

An over-close is a lifecycle defect, not a leak, so it never fails a check on its own. Pass failOnOverClose: true for code you own.

expectNoLeaks(censuses, options?)

Runs checkLeaks and throws new Error(report.message) unless ok. The message carries the counts and up to five allocation sites with three stack frames each — enough to act on from a CI log.

expectNoLeaks(await session.census(), { types: 'all' });

expectNoLeakedFrames(censuses, options?)

The common case, named for what it means: expectNoLeaks with types: ['VideoFrame']. Note that options is spread after the default, so passing your own types overrides it.

expectNoLeakedFrames(await session.census());
expectNoLeakedFrames(await session.census(), { allow: { VideoFrame: 3 } });

Because only VideoFrame is enforced, a live AudioData shows up in unenforcedLive and in the message rather than failing the test.

summarize(censuses)

A compact digest, sized for an agent or a CI log to read in one go. One line per context plus the default verdict. Deliberately small: a full census is mostly stack strings.

2 context(s): main, worker
  main (3s): nothing live
  worker (3s): VideoDecoder=1 VideoFrame=5 | media 4 (1 stalled)

5 VideoFrame still live (allowed 0).

Held by:
  5x VideoFrame (decoded, oldest 100ms) in worker
      at VideoSample.toVideoFrame (pipeline.js:17261:14)
      (frame emitted by this VideoDecoder)

summarize uses the default types. If you are enforcing the codecs, call checkLeaks yourself and print its message.

totalLive(censuses, type)

Sums one type's live count across contexts. Returns a number.

const frames = totalLive(await session.census(), 'VideoFrame');

TRACKED

The seven types whose resources GC cannot reclaim, in order. TrackedType is the union of its members.

['VideoDecoder', 'VideoEncoder', 'AudioDecoder', 'AudioEncoder',
 'VideoFrame', 'AudioData', 'ImageBitmap']

Instrumentation

installCensus(options?)

Patches this context's globals. Safe to call more than once — a second call only updates context and returns, so re-running it after HMR or a second bundle chunk does not reset the counters or double-patch a constructor.

Each patch step is wrapped separately. A global that is missing in this context costs you that one patch and is recorded in problems[] — it never aborts the install, and it is never swallowed.

installCensus also exposes globalThis.__webcodecsCensus: a function returning the local census, with .local(), .timeline(), .reset() and .version attached. That is how the CDP driver and the extension read a context they injected into.

localCensus()

A ContextCensus for this context only. Collecting a worker's census means running this inside that worker.

timeline()

The rolling samples on their own. Each Sample:

This is what separates a busy pipeline from a wedged one. Decoder idle, queue empty and the live count frozen means wedged; a snapshot alone reads it as normal.

resetCensus()

Clears the counters without unpatching. Tests need this; nothing else should. Objects that were live before the reset are forgotten, so a reset mid-run hides a real leak.

VERSION

The core's version string, stamped into every census payload and readable in-page as __webcodecsCensus.version. The release script rewrites it, and fails loudly if it ever stops matching its pattern.

Subpath exports

The injected build reads its options from globalThis.__webcodecsCensusOptions before installing, because an IIFE has no callable export. The CDP driver does this for you.