Proposal: `ReadableStream.withSafeResolvers()`

[juner]

What problem are you trying to solve?

There is no ergonomic, standardized way to externally control a ReadableStream (i.e., enqueue, close, or error) with a safe interface.

Today:

• The only way is to keep a reference to ReadableStreamDefaultController.
• Calling controller.enqueue(), controller.close(), or controller.error() after the stream is closed/errored/canceled may throw.
• Developers sometimes implement ad-hoc helpers ("withResolvers"-style wrappers) to build "pushable streams", but this pattern is not standardized.

This makes event-based or imperative stream production awkward and error-prone.

What solutions exist today?

1. Manually handling ReadableStreamDefaultController

   • Requires writing boilerplate.
   • Unsafe: calling methods after close/error/cancel throws.
   • Requires custom guarding logic.

2. Ad-hoc helper utilities

   • Non-standard.
   • Inconsistent behavior (especially around cancellation and error propagation).

3. Async generator wrappers

   • Cannot expose a truly push-based API.
   • Cannot support backpressure-compatible push-style enqueuing.

How would you solve it?

Introduce a resolver-style API, similar to Promise.withResolvers():

interface ReadableStream {
  static withSafeResolvers<T = unknown>(): {
    stream: ReadableStream<T>;
    enqueue(chunk: T): void;
    close(): void;
    error(reason: unknown): void;
  };
}

Key behavior

• enqueue(chunk) — enqueues a chunk; ignored if closed/errored/canceled.
• close() — closes the stream safely; ignored after finalization.
• error(reason) — errors the stream; ignored after finalization.
• All operations after the stream is finalized (closed, errored, or canceled) are silently ignored.

This provides an ergonomic, safe way to create externally controlled pushable streams.

Anything else?

A reference implementation exists:

• NPM: https://www.npmjs.com/package/readable-stream-with-safe-resolvers
• TypeScript implementation
• Fully safe for multiple calls to enqueue/close/error even after finalization
• Already used in real-world patterns such as event streams and imperatively controlled data sources

This proposal maintains compatibility with all existing stream semantics (including backpressure). The API surface is minimal and follows existing web-standard precedents such as Promise.withResolvers().

[saschanaz]

The referenced npm package seems to enqueue values regardless of backpressure, what's the motivation for that? I think the current way is more fail-safe where controller is given by pull callback which better handles backpressure (i.e. will be called only if more values are needed).

[ricea]

The referenced npm package seems to enqueue values regardless of backpressure, what's the motivation for that? I think the current way is more fail-safe where controller is given by pull callback which better handles backpressure (i.e. will be called only if more values are needed).

Good point. Sometimes ignoring backpressure is what you want, but providing an API which makes it easy to ignore backpressure would lead to people doing it by accident, which would be a backwards step.

I agree that's it's annoying that enqueue(), close() and error() throw exceptions on closed streams, but I wouldn't call them "unsafe". Signalling that they have not worked can be useful to prevent code from malfunctioning. If enqueue() didn't throw it would be easy to accidentally write code that kept trying to enqueue to a closed stream forever.

[juner]

@ricea
That's certainly true...

I agree that's it's annoying that enqueue(), close() and error() throw exceptions on closed streams, but I wouldn't call them "unsafe". Signalling that they have not worked can be useful to prevent code from malfunctioning. If enqueue() didn't throw it would be easy to accidentally write code that kept trying to enqueue to a closed stream forever.

One possible refinement I’ve been considering is to drop the “safe” framing entirely and instead make the stream’s completion state observable.

Concretely, something along these lines:

const resolvers = ReadableStream.withResolvers();
const { stream, enqueue, close, error } = resolvers;

resolvers.completed;
// → true if close() or error() has already been called, otherwise false

Here, completed would be exposed as a getter rather than a plain boolean value. If it were a data property, destructuring would snapshot the value and wouldn’t reflect subsequent state changes, which seems error-prone. A getter allows producers to deliberately check the current completion state without changing any existing semantics.

This approach wouldn’t suppress exceptions from enqueue(), close(), or error(), nor would it alter backpressure behavior. Those operations would still fail fast as they do today. The goal is simply to provide an explicit, opt-in way for producers to observe completion and avoid late enqueues intentionally, rather than relying on try/catch.

Exposing dynamic internal state via getters is also consistent with existing Streams APIs such as stream.locked or controller.desiredSize, which makes this feel like a natural extension rather than a special case.

[MattiasBuelens]

One possible refinement I’ve been considering is to drop the “safe” framing entirely and instead make the stream’s completion state observable.

Concretely, something along these lines:

const resolvers = ReadableStream.withResolvers();
const { stream, enqueue, close, error } = resolvers;

Or you could group those methods in a single object and perhaps... call it a controller? 😄

const { stream, controller } = ReadableStream.withController();
controller.enqueue("a");
controller.close();

resolvers.completed;
// → true if close() or error() has already been called, otherwise false

Here, completed would be exposed as a getter rather than a plain boolean value. If it were a data property, destructuring would snapshot the value and wouldn’t reflect subsequent state changes, which seems error-prone. A getter allows producers to deliberately check the current completion state without changing any existing semantics.

This approach wouldn’t suppress exceptions from enqueue(), close(), or error(), nor would it alter backpressure behavior. Those operations would still fail fast as they do today. The goal is simply to provide an explicit, opt-in way for producers to observe completion and avoid late enqueues intentionally, rather than relying on try/catch.

Exposing dynamic internal state via getters is also consistent with existing Streams APIs such as stream.locked or controller.desiredSize, which makes this feel like a natural extension rather than a special case.

This could be interesting, but we can then add it to the existing ReadableStreamDefaultController API instead. Something like:

• controller.state
• controller.closed
• ...

[juner]

@MattiasBuelens

😄 Fair point — grouping them back into a controller is certainly the obvious shape, and I agree that if this functionality exists, ReadableStreamDefaultController is a natural place for it.

I think there may be two slightly different questions here, though:

1. How do you obtain a controller?
   (withController(), withResolvers(), or the existing constructor + underlying source hooks)

2. What observable state does a controller expose once you have it?
   (e.g. closed, state, etc.)

My original motivation was mostly about (2): giving producers an explicit, synchronous way to observe completion, so they can deliberately avoid late enqueues without relying on try/catch, while still preserving the existing fail-fast semantics and backpressure behavior.

Exposing something like controller.closed or a small controller.state enum would address that concern just as well, and arguably more cleanly, than hanging it off a separate “resolvers” object. That also avoids introducing a new conceptual surface if the information naturally belongs to the controller anyway.

So yes — if the direction is to add observable completion state, putting it on ReadableStreamDefaultController itself seems like a very reasonable place to explore.

[saschanaz]

But how do we prevent it from being a footgun? withResolvers/withController would sound like a new fancy way to create a stream when it lacks an important feature.

[juner]

@saschanaz

That’s a fair concern, and I agree that anything called withResolvers() / withController() risks being perceived as a “new fancy way to create a stream”, especially if it appears to bypass important guarantees.

I think the key to avoiding that footgun is to make sure this API does not replace or weaken any of the existing invariants:

• Backpressure semantics remain unchanged.
• enqueue(), close(), and error() continue to throw and fail fast.
• The API does not provide any new way to produce data that isn’t already possible today.

In that sense, this wouldn’t be a more powerful way to create streams, just a more explicit one. It mainly exposes information (e.g. observable completion state) or wiring that already exists implicitly in the constructor + underlying source model.

I also think positioning matters a lot here. If this is framed as a low-level, opt-in convenience for advanced producer patterns (where producer and consumer lifetimes are intentionally decoupled), rather than as a recommended default, that helps reduce accidental misuse. Putting observable state on ReadableStreamDefaultController itself might also help, since it avoids introducing a “new way” to create streams and instead makes existing behavior more explicit.

So I agree the bar should be high — but I think the way to clear it is by ensuring the API only makes intent and state observable, without changing the fundamental safety properties that Streams already enforce.

[jasnell]

While I symphathize with the goals, as an implementer I'm not really convinced this is well motivated enough. The existing pattern of extracting the controller via the start is well established and libraries/apps that are using it are unlikely to change:

let controller;
let rs = new ReadableStream({
  start(c) { controller = c; }
});

[juner]

@jasnell

That’s a fair point, and I agree that the existing start(c) { controller = c; } pattern is well established and works fine today. I don’t think this proposal should be seen as something that existing libraries or applications are expected to migrate to.

My motivation here isn’t that the current pattern is insufficient, but that it’s somewhat implicit and non-obvious, especially outside of library code. The controller relationship already exists in the model, but the only way to access it today is by knowing and re-implementing this idiom.

From that perspective, withController() would be more about making an existing relationship explicit than about introducing a new capability or replacing a best practice. Similar to Promise.withResolvers(), it wouldn’t unlock anything new, but it can reduce boilerplate and make intent clearer in cases where producer and consumer lifetimes are intentionally decoupled.

That said, I fully agree the bar for standardizing this should be high, and if the conclusion is that the existing pattern is sufficient and clearer to keep as-is, that’s a reasonable outcome too. I mainly wanted to sanity-check whether this kind of explicitness is something the platform would ever want to offer.