StreamSplit

Find streaming-parser bugs that only appear when bytes arrive in pieces.

Usage · API · Design · Integrations · Safety · Contributing · For agents

A read boundary is not a message boundary. Split a UTF-8 character, CRLF pair, JSON record, or SSE frame in the wrong place and a parser can silently change its output.

StreamSplit tests your existing parser in process, compares its ordered events, and returns a smaller failing partition with an exact replay fixture.

Why StreamSplit

• Real byte boundaries: single-cut, bytewise, empty-read, and seeded random schedules
• Observable behavior: compare every emitted event, final flush, and configured error outcome
• Reproducible failures: repeat unstable outcomes, reduce boundaries, replay exact input bytes
• Small footprint: ESM + TypeScript, synchronous or asynchronous parsers, zero runtime dependencies

Try it

git clone https://github.com/agent-axiom/streamsplit.git
cd streamsplit
npm ci
npm run demo:short

The demo catches a broken UTF-8 decoder in SSE, reproduces a two-chunk failure, then replays it with the fix.

Try three real parser integrations: npm run example:sse, npm run example:ndjson, and npm run example:json. Adapters, edge cases, and tested versions →

One assertion

From the built checkout, using the included NDJSON example:

import { assertChunkInvariant } from './dist/index.js';
import { ndjsonParser } from './examples/parsers.mjs';

await assertChunkInvariant({
  input: new TextEncoder().encode('{"city":"東京"}\n{"emoji":"🌍"}\n'),
  createParser: ndjsonParser,
  seed: 42,
});

Return a fresh parser on every factory call. Emit complete semantic events and flush remaining output in end(). Install the package, adapt your parser, and replay failures →

Know the limits

A pass covers the tested schedules, not every possible partition or protocol correctness. Reduction is bounded and does not claim a global minimum. Repeated runs guard against observed nondeterminism. Timeouts cannot interrupt blocked synchronous JavaScript. Details →

Fixtures contain exact input bytes and may contain secrets. The runtime has no telemetry, network calls, or file access.

Verify and install

npm run check runs regression tests, strict API type checks, and a clean packed-package consumer. CI covers Node 20, 22, and 24.

npm install --save-dev @agent-axiom/streamsplit

Available on npm. You can also build an installable archive with npm pack; see installation and release readiness. Licensed under MIT.