Consider making `WritableStreamDefaultWriter.write()` contravariant

[cdauth]

⚙ Compilation target

esnext

⚙ Library

dom

Missing / Incorrect Definition

WritableStreamDefaultWriter.write(chunk)

Sample Code

const test: WritableStream<{ a: string }> = new WritableStream<{ a: string; b: string }>();

The above does not raise a type error. test.getWriter().write({ a: "string" }) will not show an error, even though the underlying stream expects b properties on the chunks. A variation of the problem is this:

const writable = new WritableStream<{ a: string; b: string }>();
new ReadableStream<{ a: string }>().pipeTo(writable); // No error

WritableStream<A> and WritableStream<B> differ in the signature of their getWriter().write(chunk) method. Because WritableStreamDefaultWriter.write(chunk) is a method, it is bivariant, leading to the above examples to pass.

Other than for example Array, WritableStream is only ever used for writing, never for reading, so as far as my understanding goes, bivariance does not have any use here. This is why I would suggest to change the typing of WritableStream to make it contravariant, to make the examples above raise errors. One way to achieve that would be to declare WritableStreamDefaultWriter.write() as a function property instead of a method, that would solve the problem at least in strict mode:

    write: (chunk?: W) => Promise<void>;

Although I am not sure whether that would have any other implications.

As a workaround, I use the following code:

declare const write: unique symbol;
declare global {
	interface WritableStreamDefaultWriter<W = any> {
		[write]?: (a: W) => void;
	}
}

Some more details about this can also be found on StackOverflow.

Documentation Link

No response

[steabert]

Is this bivariance the underlying issue that allows piping streams with mismatching types?

The following is not giving an error:

const test = new ReadableStream<{ kind:'a'|'b' }>().pipeTo(new WritableStream<{ kind:'a' }>)

This causes issues with both pipeTo and pipeThrough as they allow mismatching chunk types.

[RyanCavanaugh]

WritableStream remains bivariant in its chunk type under --strict, so both assignments below are accepted in TypeScript 5.5.4, 6.0.3, and current native TypeScript 7.1.0-dev.20260918.1 even though the destination stream requires b.

assignment.ts

const stream: WritableStream<{ a: string }> = new WritableStream<{
  a: string;
  b: string;
}>();

// Expected: assignment and write reject values missing required properties.
// Actual: both compile without error.
stream.getWriter().write({ a: "string" });

pipe.ts

const writable = new WritableStream<{ a: string; b: string }>();

// Expected: pipeTo rejects a destination requiring property "b".
// Actual: it compiles without error.
new ReadableStream<{ a: string }>().pipeTo(writable);