We deserve a better streams API for JavaScript (opens in new tab)
Web Streams established a cross-runtime standard for handling streaming data, but their design reflects constraints from 2014–2016 rather than modern JavaScript practices. James M. Snell argues that the API’s reader, lock, and controller machinery creates unnecessary complexity and performance costs. He presents an alternative based on JavaScript language primitives that reportedly runs 2× to 120× faster across browsers and major runtimes. ## Historical Design Constraints - The WHATWG Streams Standard aimed to provide portable APIs for creating, composing, and consuming streams. - It was adopted by browsers, Cloudflare Workers, Node.js, Deno, Bun, and APIs such as `fetch()`. - The design predates JavaScript async iteration, which was standardized in ES2018. - Because `for await...of` did not yet exist, Web Streams introduced a separate reader/writer acquisition model. ## Excessive Ceremony for Basic Reads - Reading a stream to completion traditionally requires: - Calling `stream.getReader()`. - Repeatedly awaiting `reader.read()`. - Checking `{ value, done }` on every iteration. - Releasing the reader lock in a `finally` block. - These steps are API choices rather than inherent requirements of streaming. - Modern async iteration reduces the same operation to: ```js for await (const chunk of stream) { chunks.push(chunk); } ``` - However, async iteration was added after the original design, so it does not eliminate the underlying reader, lock, and controller complexity. - Advanced features such as BYOB reads still require developers to use the lower-level APIs. ## Problems with Manual Locking - Calling `getReader()` places an exclusive lock on the stream. - While locked, other code cannot read, pipe, or cancel the stream directly. - Forgetting `reader.releaseLock()` can permanently prevent later consumers from using the stream. - The `locked` property indicates that a lock exists, but not who owns it, why it exists, or whether the reader remains usable. - Internal operations such as piping also acquire locks, which can make stream behavior surprising. - Lock-release behavior with pending reads was historically unclear and varied between implementations before being clarified by the specification. - Async iterables improve the user experience by handling reader and lock management automatically, but the underlying model remains complex. ## Proposed Direction - The post argues that Web Streams’ limitations are fundamental design consequences, not isolated bugs easily fixed through incremental changes. - A better API should be built around modern JavaScript primitives, especially async iteration. - The author’s alternative reportedly achieves between 2× and 120× the performance of Web Streams across Cloudflare Workers, Node.js, Deno, Bun, and major browsers. - The claimed gains come from different architectural choices rather than narrowly optimized implementations. A more modern streams API should make common operations natural, avoid exposing fragile manual lock management, and use JavaScript’s native asynchronous iteration model from the start.