ADR 0010: Vendor Node’s streams (readable-stream) for stream
- Status: accepted (2026-10-21)
- Context:
stream underlies most of Node’s I/O APIs (fs streams, stdio, http, zlib,
child_process) and much of npm. It is Node’s most behavior-sensitive code: buffering,
backpressure, event ordering, and error and destroy semantics. A re-implementation would be
thousands of lines that only approximate Node.
- Decision: Vendor
readable-stream 4.8.0 (MIT). It is published by the Node.js team as
a userland copy of lib/internal/streams from Node 18.19.
scripts/vendor-readable-stream.mjs regenerates
packages/node-compat/src/vendor/readable-stream.ts from the npm tarball, and the file
records the tarball’s integrity hash.
- The sources are evaluated through a private CommonJS registry on first
require('stream').
Its buffer, events, string_decoder and process dependencies are ClientVM’s own
builtins, so streams carry our Buffers and use our nextTick. No npm polyfills are
involved.
- Consequences:
- Behavior is Node 18.19’s stream core. The differences from Node 24 that we know about are
patched at the edges:
fs read streams use Node 24’s 64 KiB highWaterMark.
fs reads deliver on a later tick, as Node’s thread-pool reads do.
test/conformance/stream-differential.test.ts compares behavior with node:stream.
- Upgrading means re-running the script with a newer version and the differential suite.
- The vendored file is excluded from lint and formatting and keeps its MIT SPDX header.
Edit this page on GitHub ↗Markdown