BenchmarksStream

BenchmarksStream is an object-mode stream.Readable. Each lifecycle record is both emitted as a named event and made available on the stream as { type, data }.

The events are emitted in execution order:

• 'bench:plan'
• 'bench:start'
• 'bench:sample'
• 'bench:complete'
• 'bench:diagnostic'
• 'bench:summary'

Named event payloads, readable records, and benchmark completion values are independent snapshots. Mutating a value received through one delivery mechanism does not change values received through the others. As with other EventEmitter events, multiple listeners for the same named event receive the same event payload. Memory referenced through a SharedArrayBuffer remains shared, following structured clone semantics.

Once a consumer starts reading, the runner honors the stream's object-mode high-water mark and waits between records when the consumer is slower than the producer. These waits occur after sample timing has ended, and records are not dropped. Snapshot creation and delivery waits are excluded from benchmark timeout accounting. Before readable consumption starts, records accumulate in the standard readable buffer and are included in readableLength. This keeps an unread stream and a consumer using only named events from deadlocking, but the buffer can grow without bound. A named-event-only consumer that does not need readable records should call stream.resume() to discard them. Destroying the stream stops readable delivery but does not cancel benchmark execution, so benchmark completion promises still settle. Automatically scheduled module-level runs drain their stream internally.

With process isolation, each record sent by a child is acknowledged only after the parent has accepted it. A child sends no additional record until it receives that acknowledgement, bounding the IPC relay when a reporter is slow.

Every benchmark-scoped event contains runId, fileRunId, entryFile, benchId, parentId, and namePath. runId and fileRunId are opaque and change between runs. entryFile identifies the top-level benchmark file whose loading caused the declaration, while file identifies the source location of the declaration itself. parentId is based on the containing suite's source file and hierarchical name path.

After asynchronous suite declarations settle, an in-process runner emits one 'bench:plan' event for every benchmark it collected, in declaration order. All plans from that runner are emitted before its suite hooks or benchmark callbacks run. With process isolation, files run in separate children, so plans for a later file are emitted after an earlier child has completed. With no isolation, all files share one runner and their plans are emitted before any benchmark executes. Plan data contains the benchmark-scoped identity, location, tags, and parameters described in benchmark result, together with:

The plan contains execution settings known to the runner. Runtime version, operating system, processor, and other environment metadata are intentionally left for reporters and higher-level tools to collect.

'bench:complete' data contains a benchmark result. A failed result has an additional error property and may contain samples recorded before the error. A skipped result has an additional skip property and an empty samples array. 'bench:diagnostic' reports loading, suite, and hook errors as well as public context diagnostics. A context diagnostic contains the benchmark-scoped identity fields, phase, index, message, level, source location, and optional detail. 'bench:summary' contains overall runId, fileRunId, entryFile, success, counts, duration_ns, and file properties. fileRunId, entryFile, and file are string | null; they are null when the summary aggregates multiple files.