@solidrt/flux-types 0.0.70 → 0.0.71

package/README.md

@@ -51,9 +51,11 @@ rely on must be named.
   `flux:camera`, `flux:microphone`, `flux:audio`, `flux:gpu`, `flux:spatial`,
   `flux:font`.
 - Web-standard globals: `console`, `fetch` + `Headers`/`Request`/`Response`,
+  `ReadableStream`/`WritableStream`/`TransformStream`,
+  `CompressionStream`/`DecompressionStream`,
   `setTimeout`/`setInterval`/`setImmediate`/`requestIdleCallback`/`queueMicrotask`, `performance`, `WebSocket`,
-  `TextEncoder`/`TextDecoder`, `crypto.subtle.digest`. These are deliberate subsets matching exactly what
-  the runtime implements.
+  `TextEncoder`/`TextDecoder` and `TextEncoderStream`/`TextDecoderStream`, `crypto.subtle.digest`.
+  These are deliberate subsets matching exactly what the runtime implements.
 - GUI globals (gui-enabled runtime only): `requestAnimationFrame` /
   `cancelAnimationFrame` (web-standard names, so kept global).
 

package/gui/rendertree.d.ts

@@ -212,15 +212,25 @@ declare module "flux:rendertree" {
    */
   export function prepareText(text: string, options?: MeasureTextOptions): PreparedText
   /**
-   * Make the glyph cells of printable ASCII for these font styles ahead of
-   * their first use, on the engine's worker thread: the type scale an app
-   * draws its screens in, called at startup under the splash, so a first
-   * paint in any of them never waits for cells. Each entry names a font
-   * (family, size, weight, style) as a `<text>` would; `lineHeight`,
-   * `maxLines`, `carets` and `runs` are ignored. Glyphs outside ASCII are
-   * made at first use.
+   * One font to warm for {@link warmText}: a font (family, size, weight,
+   * style) as a `<text>` names it, and optionally a string the app will
+   * draw in it.
    */
-  export function warmText(styles: MeasureTextOptions[]): void
+  export type WarmTextEntry = MeasureTextOptions & { text?: string }
+  /**
+   * Make glyph cells ahead of their first use, on the engine's worker
+   * thread: the type scale an app draws its screens in, called at startup
+   * under the splash, so a first paint in any of them does not stop to
+   * make them. A cell a text needs that is not in the atlas is made in
+   * that frame, so text never draws with glyphs missing; warming only
+   * moves that work ahead of time. Each entry names a font as a `<text>`
+   * would (`lineHeight`, `maxLines`, `carets` and `runs` are ignored) and
+   * warms its printable ASCII; an entry with a `text` also warms the
+   * glyphs that string shapes to in the font, a ligature, a curly quote or
+   * a letter beyond ASCII included, on whichever face covers it. Anything
+   * else is made at first use.
+   */
+  export function warmText(entries: WarmTextEntry[]): void
   /** How every text is rendered, for {@link setTextRendering}. */
   export interface TextRenderingOptions {
     /**

package/index.d.ts

@@ -16,10 +16,13 @@
 
 // Web-standard globals. The runtime is QuickJS, not a browser or Node, so it
 // ships no lib.dom / @types/bun: these declarations are the sole source for
-// console, fetch, the Fetch types, timers, WebSocket, the encoders, and crypto.
+// console, fetch, the Fetch types, the streams, the compression streams,
+// timers, WebSocket, the encoders, and crypto.
 /// <reference path="./standards/console.d.ts" />
 /// <reference path="./standards/time.d.ts" />
 /// <reference path="./standards/text.d.ts" />
+/// <reference path="./standards/streams.d.ts" />
+/// <reference path="./standards/compression.d.ts" />
 /// <reference path="./standards/base64.d.ts" />
 /// <reference path="./standards/fetch.d.ts" />
 /// <reference path="./standards/websocket.d.ts" />

package/modules/net.d.ts

@@ -68,27 +68,41 @@ declare module "flux:net" {
   }
 
   /**
-   * A connected TCP stream: a byte duplex. It is its own async iterator, so
-   * `for await (let chunk of conn)` reads it until end-of-stream.
+   * A connected TCP stream: a byte duplex as a `readable`/`writable` pair of
+   * web streams, the shape sockets have in every runtime with web streams.
+   * `for await (let chunk of conn.readable)` reads it, `conn.readable
+   * .pipeTo(other.writable)` is one half of a proxy, and a pipe carries the
+   * half-close: when the source ends, the destination's write side closes.
    */
-  export class Conn implements AsyncIterable<Uint8Array> {
+  export class Conn {
     /** The remote peer's address, e.g. "192.168.2.37:445". */
     readonly remoteAddr: string
-    /** Write all of `data`. Resolves once it is handed to the OS. */
-    write(data: string | Uint8Array): Promise<void>
     /**
-     * Half-close: flush and end the write side, so the peer sees end-of-stream
-     * while this side keeps reading until the peer closes. The way to signal
-     * "request done" to protocols that answer after EOF. After it, {@link write}
-     * throws. Idempotent, and a no-op once the connection is closed.
+     * What the peer sends, one chunk per read, pulled only as far as it is
+     * read. Ends when the peer ends its write side or closes, or on
+     * {@link close}; errors with the reason after `writable.abort(reason)`.
+     * `cancel()` stops reading and releases the read half: the write side
+     * stays usable and the connection stays open until {@link close}.
      */
-    closeWrite(): Promise<void>
+    readonly readable: ReadableStream<Uint8Array>
     /**
-     * Close the connection now: a pending read ends, the peer sees end-of-stream
-     * at once. Bytes already handed to the OS still flush.
+     * What to send: strings (as UTF-8) or `Uint8Array`s. A write resolves
+     * once the OS took the bytes, so a producer faster than the peer reads
+     * sees backpressure. `close()` is the half-close: it flushes and ends the
+     * write side, so the peer sees end-of-stream while this side keeps
+     * reading until the peer closes (the way to say "request done" to a
+     * protocol that answers after EOF); a later write rejects. `abort(reason)`
+     * tears the connection down with an error: a pending or later read of
+     * {@link readable} rejects with the reason. TCP has no abortive
+     * half-close, so the peer still sees a plain end-of-stream.
+     */
+    readonly writable: WritableStream<string | Uint8Array>
+    /**
+     * Close the connection now: a pending read ends, a pending write rejects,
+     * the peer sees end-of-stream at once. Bytes already handed to the OS
+     * still flush.
      */
     close(): void
-    [Symbol.asyncIterator](): AsyncIterator<Uint8Array>
   }
 
   /**

package/modules/p2p.d.ts

@@ -47,19 +47,39 @@ declare module "flux:p2p" {
   }
 
   /**
-   * A single bidirectional p2p stream: a byte duplex. It is its own async
-   * iterator, so `for await (let chunk of stream)` reads the recv half.
+   * A single bidirectional p2p stream: a byte duplex as a `readable`/`writable`
+   * pair of web streams, the same shape as a `flux:net` `Conn`, so
+   * `stream.readable.pipeTo(conn.writable)` bridges the two.
    */
-  export class P2pStream implements AsyncIterable<Uint8Array> {
+  export class P2pStream {
     /** The remote peer's endpoint id. */
     readonly remoteId: string
-    /** Queue bytes on the send half. */
-    write(data: string | Uint8Array): void
-    /** Half-close: end the send half (QUIC FIN) after queued writes flush. The recv half stays open. */
-    closeWrite(): void
-    /** Tear the stream down: end the send half and stop reading. */
+    /**
+     * What the peer sends, one chunk per read, pulled only as far as it is
+     * read. Ends when the peer finishes its send half or closes, or on
+     * {@link close}; errors when the peer resets the stream, and with the
+     * reason after `writable.abort(reason)`. `cancel()` stops reading and
+     * releases the recv half, which tells the peer to stop sending (its
+     * writes reject); the send side stays usable until {@link close}.
+     */
+    readonly readable: ReadableStream<Uint8Array>
+    /**
+     * What to send: strings (as UTF-8) or `Uint8Array`s. A write resolves
+     * once the transport took the bytes, paced by QUIC flow control, so a
+     * producer faster than the peer reads sees backpressure; a write to a
+     * peer that went away or stopped reading rejects. `close()` finishes the
+     * send half (QUIC FIN): the peer sees end-of-stream, the recv half stays
+     * open for replies, and a later write rejects. `abort(reason)` resets the
+     * send half and tears the stream down with an error: the peer's read
+     * fails instead of ending, and a pending or later read of
+     * {@link readable} here rejects with the reason.
+     */
+    readonly writable: WritableStream<string | Uint8Array>
+    /**
+     * Tear the stream down: a pending read ends, the recv half is released and
+     * the send half finished.
+     */
     close(): void
-    [Symbol.asyncIterator](): AsyncIterator<Uint8Array>
   }
 
   /** A bound iroh endpoint with a stable keypair. */
@@ -82,11 +102,15 @@ declare module "flux:p2p" {
     /**
      * Dial a peer and open one bidirectional stream over `protocol`. `peer` is
      * either a `ticket` (preferred; connects directly) or a bare endpoint `id`
-     * (needs discovery to resolve the address).
+     * (needs discovery to resolve the address). The peer sees the stream once
+     * this side writes to it (see {@link accept}).
      */
     connect(peer: string, protocol: string): Promise<P2pStream>
     /**
      * An async-iterable of incoming streams whose protocol matches `protocol`.
+     * A dialled stream arrives here with its first bytes (a QUIC stream is
+     * announced by its data), so the dialer writes first and the acceptor
+     * reads first: two sides that both wait for the other never meet.
      * Iterating ends when the endpoint is closed.
      */
     accept(protocol: string): AsyncIterable<P2pStream>

package/modules/subprocess.d.ts

@@ -5,7 +5,11 @@ declare module "flux:subprocess" {
     cwd?: string
     /** Extra env vars, added to / overriding the inherited environment. */
     env?: Record<string, string>
-    /** Bytes written to the child's stdin, after which stdin is closed. */
+    /**
+     * Bytes written to the child's stdin first. With {@link Command.output}
+     * stdin is closed after them; with {@link Command.spawn} it stays open for
+     * the child's `stdin` stream.
+     */
     stdin?: string | Uint8Array
     /** Kill the child if it has not exited within this many milliseconds. */
     timeoutMs?: number
@@ -17,7 +21,8 @@ declare module "flux:subprocess" {
     /**
      * `spawn()` only: the child outlives this engine and this process. It is
      * never killed on drop or reload, has no stdin/stdout/stderr pipes (all
-     * null: `stdout`/`stderr` iterate to nothing, `write` fails) and runs in
+     * null: `stdout`/`stderr` end at once, the first write to `stdin`
+     * rejects) and runs in
      * its own process group, so a Ctrl+C to the parent does not reach it.
      * `pid`, `kill()` and `status()` still work. Cannot combine with `stdin`.
      * What a dev tool uses to launch another runtime instance.
@@ -53,14 +58,19 @@ declare module "flux:subprocess" {
   type Child = {
     /** The OS process id, if available. */
     pid: number | undefined
-    /** Live stdout as an async-iterable of byte chunks. */
-    stdout: AsyncIterable<Uint8Array>
-    /** Live stderr as an async-iterable of byte chunks. */
-    stderr: AsyncIterable<Uint8Array>
-    /** Queue bytes to the child's stdin. Writes serialize and respect backpressure. */
-    write(data: string | Uint8Array): Promise<void>
-    /** Half-close: close the child's stdin (after queued writes drain) so it sees EOF. */
-    closeWrite(): Promise<void>
+    /** Live stdout as a stream of byte chunks, read as far as it is consumed. */
+    stdout: ReadableStream<Uint8Array>
+    /** Live stderr as a stream of byte chunks, read as far as it is consumed. */
+    stderr: ReadableStream<Uint8Array>
+    /**
+     * The child's stdin as a stream: strings (as UTF-8) or `Uint8Array`s,
+     * written after any {@link CommandOptions.stdin}. A write resolves once
+     * the pipe took the bytes, so a producer faster than the child reads
+     * sees backpressure. `close()` (and `abort()`) closes the pipe after the
+     * writes so far, so the child sees EOF; a later write rejects. A body
+     * piped in (`response.body.pipeTo(child.stdin)`) closes it at the end.
+     */
+    stdin: WritableStream<string | Uint8Array>
     /** Request termination (portable; SIGKILL / TerminateProcess). */
     kill(): void
     /** Resolves with the exit status when the child exits. */
@@ -73,7 +83,7 @@ declare module "flux:subprocess" {
     args: string[]
     /** Run the child to completion, buffering stdout/stderr. */
     output(): Promise<CommandOutput>
-    /** Spawn the child and return a handle with live streams, stdin, and control. */
+    /** Spawn the child and return a handle with live stdout/stderr, a stdin stream, and control. */
     spawn(): Child
   }
 

package/modules/test.d.ts

@@ -114,9 +114,11 @@ declare module "flux:test" {
     /**
      * A number within half a unit of the last of `digits` decimal places
      * (default 2): the difference is below `10 ** -digits / 2`. The way to
-     * compare floating point results.
+     * compare floating point results. An array of numbers (a point, a
+     * normal, a motion) compares to one of the same length entry by entry,
+     * and a failure prints both arrays whole.
      */
-    toBeCloseTo(expected: number, digits?: number): void
+    toBeCloseTo(expected: number | readonly number[], digits?: number): void
 
     /**
      * For a function: calling it throws. With a string, the thrown error's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/flux-types",
-  "version": "0.0.70",
+  "version": "0.0.71",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",

package/standards/compression.d.ts

@@ -0,0 +1,32 @@
+// The Compression Streams API: CompressionStream and DecompressionStream,
+// TransformStreams over the deflate formats, with the standard's names and
+// shapes. A chunk written in is an ArrayBuffer or a view of one; what comes
+// out is Uint8Arrays of at most 64 KiB each, produced as the reader pulls,
+// so a small input that inflates to a lot never runs ahead of its reader.
+// The codec runs off the JS thread, a step per piece.
+//
+// Errors are the standard's TypeErrors: an unknown format throws from the
+// constructor; a chunk that is not a buffer, corrupt input, input cut short
+// when the writable side closes, and data after the end of the compressed
+// stream (a second gzip member included) error both sides of the stream.
+
+/**
+ * The formats: `gzip` (RFC 1952), `deflate` (the zlib format, RFC 1950: a
+ * two-byte header and an Adler-32 trailer) and `deflate-raw` (RFC 1951, the
+ * bare stream, what a ZIP entry holds).
+ */
+type CompressionFormat = "gzip" | "deflate" | "deflate-raw"
+
+declare class CompressionStream {
+  /** Any other `format` throws a TypeError. */
+  constructor(format: CompressionFormat)
+  readonly readable: ReadableStream<Uint8Array>
+  readonly writable: WritableStream<ArrayBuffer | ArrayBufferView>
+}
+
+declare class DecompressionStream {
+  /** Any other `format` throws a TypeError. */
+  constructor(format: CompressionFormat)
+  readonly readable: ReadableStream<Uint8Array>
+  readonly writable: WritableStream<ArrayBuffer | ArrayBufferView>
+}

package/standards/fetch.d.ts

@@ -1,6 +1,6 @@
 // The Fetch API cluster (Headers, Request, Response, fetch). A deliberate subset
 // of the WHATWG Fetch standard: flux provides exactly these members and no more
-// (no Blob, FormData, ReadableStream, clone(), ...).
+// (no Blob, FormData, clone(), ...). Bodies are ReadableStreams (streams.d.ts).
 // Grouped in one file because the four share BodyInit/HeadersInit and reference
 // each other.
 
@@ -11,11 +11,12 @@
 type HeadersInit = Record<string, string> | Headers
 
 /**
- * A message body: a string, raw bytes, or an async-iterable of string/byte
- * chunks (e.g. an `async function*`), which is sent as a stream. Any other
- * value throws (the web stringifies it).
+ * A message body: a string, raw bytes, or a stream of string/byte chunks (a
+ * `ReadableStream`, or any async-iterable such as an `async function*`),
+ * which is sent as it is produced. Any other value throws (the web
+ * stringifies it).
  */
-type BodyInit = string | Uint8Array | AsyncIterable<string | Uint8Array>
+type BodyInit = string | Uint8Array | ReadableStream<string | Uint8Array> | AsyncIterable<string | Uint8Array>
 
 /** A subset of the WHATWG Headers API. Names are case-insensitive. */
 interface Headers {
@@ -89,8 +90,12 @@ interface Request {
   readonly headers: Headers
   /** Route params from the matched pattern; an empty object for a JS-constructed Request. */
   readonly params: Record<string, string>
-  /** The body as an async-iterable of byte chunks (read once). */
-  readonly body: AsyncIterable<Uint8Array>
+  /**
+   * The body as a stream of byte chunks, read once: an incoming request's
+   * network stream, read as far as it is consumed; a buffered body as one
+   * chunk. Reading it with `for await` is the common form.
+   */
+  readonly body: ReadableStream<Uint8Array>
   /** Read the whole body as UTF-8 text. */
   text(): Promise<string>
   /** Read the whole body as raw bytes. */
@@ -122,26 +127,38 @@ interface Response {
   readonly ok: boolean
   readonly url: string
   readonly headers: Headers
-  /** The body as an async-iterable of byte chunks (read once). */
-  readonly body: AsyncIterable<Uint8Array>
-  /** Read the whole body as UTF-8 text. */
+  /**
+   * The body as a stream of byte chunks, read once: a fetched response's
+   * network stream, read as far as it is consumed; a buffered body as one
+   * chunk; a stream given to the constructor as it is. Reading it with
+   * `for await` is the common form.
+   */
+  readonly body: ReadableStream<Uint8Array>
+  /** Read the whole body as UTF-8 text. A stream body is drained. */
   text(): Promise<string>
-  /** Read the whole body as raw bytes. */
+  /** Read the whole body as raw bytes. A stream body is drained. */
   bytes(): Promise<Uint8Array>
-  /** Read the whole body as an ArrayBuffer. */
+  /** Read the whole body as an ArrayBuffer. A stream body is drained. */
   arrayBuffer(): Promise<ArrayBuffer>
-  /** Read and parse the whole body as JSON. */
+  /** Read and parse the whole body as JSON. A stream body is drained. */
   json(): Promise<any>
 }
 
 declare let Response: {
+  /**
+   * A stream body (a `ReadableStream`, or any async-iterable of string or
+   * byte chunks, wrapped as one) is sent as it is produced: served over
+   * chunked transfer encoding, or drained by `text()` and the other
+   * readers.
+   */
   new (body?: BodyInit | null, init?: ResponseInit): Response
   /** Build a JSON response (sets Content-Type to application/json when unset). */
   json(data: any, init?: ResponseInit): Response
 }
 
 /**
- * Fetch a resource over HTTP(S). The body may be a string, Uint8Array, or an
- * async-iterable (streamed). Resolves to a {@link Response}.
+ * Fetch a resource over HTTP(S). The body may be a string, Uint8Array, or a
+ * stream (a `ReadableStream` or any async-iterable, sent as it is
+ * produced). Resolves to a {@link Response}.
  */
 declare function fetch(url: string, options?: RequestInit): Promise<Response>

package/standards/streams.d.ts

@@ -0,0 +1,244 @@
+// The WHATWG Streams subset: ReadableStream, WritableStream, TransformStream
+// and the text streams. The names and shapes are the standard's; what is
+// left out is what a single known app has not needed: no BYOB readers or
+// byte streams (`type: "bytes"`), the only queuing strategy a chunk-count
+// `highWaterMark`, no `pipeTo` options (`preventClose`, `preventAbort`,
+// `preventCancel`, `signal`). Chunks are any JS value; a stream used as a
+// body (`new Response(stream)`, a fetch body) must yield strings or
+// Uint8Arrays.
+//
+// A ReadableStream is async-iterable, so `for await (let chunk of stream)`
+// works, and ending the loop early cancels the stream. `Response.body`,
+// `Request.body` and a child process's `stdout`/`stderr` are ReadableStreams
+// over the runtime's own byte sources: one chunk is pulled per read, so a
+// socket advances only as far as it is read, and cancelling the stream
+// releases it.
+
+/** The queuing strategy a stream takes: a chunk count, nothing else. */
+interface QueuingStrategy {
+  /**
+   * How many chunks the stream queues ahead of its consumer (a readable:
+   * before it stops pulling; a writable: before a writer sees
+   * backpressure). Defaults to 1.
+   */
+  highWaterMark?: number
+}
+
+interface ReadableStreamDefaultController<R = any> {
+  /** The chunks the queue has room for; null once the stream is errored. */
+  readonly desiredSize: number | null
+  /** Queue a chunk for the reader. Throws once the stream is closed. */
+  enqueue(chunk: R): void
+  /** End the stream after the queued chunks. */
+  close(): void
+  /** Error the stream: pending and later reads reject with `e`. */
+  error(e?: any): void
+}
+
+/** What `new ReadableStream(source)` takes. Each method is optional. */
+interface UnderlyingSource<R = any> {
+  /** Runs at construction; a returned promise delays the first pull. */
+  start?(controller: ReadableStreamDefaultController<R>): any
+  /**
+   * Called when the queue has room (and again once a returned promise
+   * settles), to produce the next chunk(s).
+   */
+  pull?(controller: ReadableStreamDefaultController<R>): any
+  /** Called when the consumer cancels the stream, with the reason. */
+  cancel?(reason?: any): any
+}
+
+interface ReadableStreamReadResult<R> {
+  value: R | undefined
+  done: boolean
+}
+
+interface ReadableStreamDefaultReader<R = any> {
+  /** Settles when the stream closes; rejects when it errors or the reader is released. */
+  readonly closed: Promise<void>
+  /** The next chunk, or `{ done: true }` at the end. */
+  read(): Promise<ReadableStreamReadResult<R>>
+  /** Cancel the stream, as {@link ReadableStream.cancel}. */
+  cancel(reason?: any): Promise<void>
+  /** Unlock the stream. Pending reads reject. */
+  releaseLock(): void
+}
+
+interface ReadableStreamIteratorOptions {
+  /** Keep the stream open when the loop ends early (`break`, a throw). */
+  preventCancel?: boolean
+}
+
+/** A pair a stream pipes through; a TransformStream is one. */
+interface ReadableWritablePair<R = any, W = any> {
+  readable: ReadableStream<R>
+  writable: WritableStream<W>
+}
+
+declare class ReadableStream<R = any> {
+  /** No `type: "bytes"`; a strategy is a chunk count. */
+  constructor(underlyingSource?: UnderlyingSource<R>, strategy?: QueuingStrategy)
+  /** True while a reader, a pipe or an iteration holds the stream. */
+  readonly locked: boolean
+  /**
+   * Lock the stream to a reader. One reader at a time: a second call
+   * throws until the first is released. No `mode: "byob"`.
+   */
+  getReader(): ReadableStreamDefaultReader<R>
+  /**
+   * Discard the stream: the source's `cancel` runs with `reason`, pending
+   * reads settle as done. Rejects while the stream is locked.
+   */
+  cancel(reason?: any): Promise<void>
+  /**
+   * Read the stream through `transform` and return its readable side. The
+   * pipe runs on its own; an error on either side propagates to the other.
+   * Throws when either stream is locked. No options.
+   */
+  pipeThrough<T>(transform: ReadableWritablePair<T, R>, options?: undefined): ReadableStream<T>
+  /**
+   * Read the stream into `destination` and close it at the end. An errored
+   * source aborts the destination, an errored or closed destination cancels
+   * the source, and the promise rejects with that error. No options.
+   */
+  pipeTo(destination: WritableStream<R>, options?: undefined): Promise<void>
+  /**
+   * Two streams over this one: every chunk goes to both, and the source is
+   * cancelled once both are. A slow branch makes the other wait, since
+   * chunks are not buffered per branch beyond its own queue.
+   */
+  tee(): [ReadableStream<R>, ReadableStream<R>]
+  /** The async iterator `for await` uses; `preventCancel` keeps `break` from cancelling. */
+  values(options?: ReadableStreamIteratorOptions): AsyncIterableIterator<R>
+  [Symbol.asyncIterator](): AsyncIterableIterator<R>
+  /**
+   * A stream over an async (or sync) iterable: one item is pulled per
+   * read, and cancelling the stream returns the iterator.
+   */
+  static from<R>(iterable: AsyncIterable<R> | Iterable<R | PromiseLike<R>>): ReadableStream<R>
+}
+
+interface WritableStreamDefaultController {
+  /** Error the stream: queued and later writes reject with `e`. */
+  error(e?: any): void
+}
+
+/** What `new WritableStream(sink)` takes. Each method is optional. */
+interface UnderlyingSink<W = any> {
+  /** Runs at construction; a returned promise delays the first write. */
+  start?(controller: WritableStreamDefaultController): any
+  /**
+   * Receives one chunk at a time; the next write waits for a returned
+   * promise, which is how a slow sink paces a fast writer.
+   */
+  write?(chunk: W, controller: WritableStreamDefaultController): any
+  /** Runs once after the last write when the stream is closed. */
+  close?(): any
+  /** Runs when the stream is aborted, with the reason. */
+  abort?(reason?: any): any
+}
+
+interface WritableStreamDefaultWriter<W = any> {
+  /** Fulfilled while the queue has room; a new promise each time it fills. */
+  readonly ready: Promise<void>
+  /** Settles when the stream closes; rejects when it errors or the writer is released. */
+  readonly closed: Promise<void>
+  /** The chunks the queue has room for; null once the stream is errored. */
+  readonly desiredSize: number | null
+  /**
+   * Queue a chunk. Resolves once the sink has accepted it, so awaiting each
+   * write is one way to see backpressure; `ready` is the other.
+   */
+  write(chunk: W): Promise<void>
+  /** Close the stream after the queued writes; resolves once the sink closed. */
+  close(): Promise<void>
+  /** Abort the stream, as {@link WritableStream.abort}. */
+  abort(reason?: any): Promise<void>
+  /** Unlock the stream. A pending `ready` or `closed` rejects. */
+  releaseLock(): void
+}
+
+declare class WritableStream<W = any> {
+  /** A strategy is a chunk count. */
+  constructor(underlyingSink?: UnderlyingSink<W>, strategy?: QueuingStrategy)
+  /** True while a writer or a pipe holds the stream. */
+  readonly locked: boolean
+  /**
+   * Lock the stream to a writer. One writer at a time: a second call throws
+   * until the first is released.
+   */
+  getWriter(): WritableStreamDefaultWriter<W>
+  /**
+   * Error the stream with `reason`: queued writes reject, the sink's
+   * `abort` runs once a write in flight has finished. Rejects while the
+   * stream is locked.
+   */
+  abort(reason?: any): Promise<void>
+  /** Close the stream after the queued writes. Rejects while the stream is locked. */
+  close(): Promise<void>
+}
+
+interface TransformStreamDefaultController<O = any> {
+  /** The readable side's room for chunks; null once it is errored. */
+  readonly desiredSize: number | null
+  /** Queue a chunk on the readable side. */
+  enqueue(chunk: O): void
+  /** Error both sides with `e`. */
+  error(e?: any): void
+  /** Close the readable side and error the writable side. */
+  terminate(): void
+}
+
+/** What `new TransformStream(transformer)` takes. Each method is optional. */
+interface Transformer<I = any, O = any> {
+  /** Runs at construction; a returned promise delays the first chunk. */
+  start?(controller: TransformStreamDefaultController<O>): any
+  /**
+   * Receives each written chunk, to enqueue zero or more chunks on the
+   * readable side. Absent, chunks pass through unchanged. A throw errors
+   * both sides.
+   */
+  transform?(chunk: I, controller: TransformStreamDefaultController<O>): any
+  /** Runs when the writable side closes, before the readable side does. */
+  flush?(controller: TransformStreamDefaultController<O>): any
+}
+
+declare class TransformStream<I = any, O = any> {
+  /**
+   * Strategies are chunk counts: the writable side's defaults to 1, the
+   * readable side's to 0, so a chunk is transformed as the reader asks. A
+   * write waits while the readable side's queue is full.
+   */
+  constructor(transformer?: Transformer<I, O>, writableStrategy?: QueuingStrategy, readableStrategy?: QueuingStrategy)
+  readonly readable: ReadableStream<O>
+  readonly writable: WritableStream<I>
+}
+
+/**
+ * A TransformStream from UTF-8 bytes (Uint8Array or ArrayBuffer chunks) to
+ * strings: a {@link TextDecoder} in `stream` mode, so a multibyte sequence
+ * split across chunks decodes whole. Chunks that decode to nothing are not
+ * enqueued.
+ */
+declare class TextDecoderStream {
+  /** As the {@link TextDecoder} constructor: UTF-8 labels only. */
+  constructor(label?: string, options?: TextDecoderOptions)
+  /** Always "utf-8". */
+  readonly encoding: string
+  readonly fatal: boolean
+  readonly ignoreBOM: boolean
+  readonly readable: ReadableStream<string>
+  readonly writable: WritableStream<Uint8Array | ArrayBuffer>
+}
+
+/**
+ * A TransformStream from strings to their UTF-8 bytes. A chunk ending in a
+ * high surrogate holds that half for the next chunk, so a surrogate pair
+ * split across chunks encodes as one character.
+ */
+declare class TextEncoderStream {
+  /** Always "utf-8". */
+  readonly encoding: string
+  readonly readable: ReadableStream<Uint8Array>
+  readonly writable: WritableStream<string>
+}

package/standards/text.d.ts

@@ -1,4 +1,5 @@
 // TextEncoder / TextDecoder. UTF-8 only (the only encoding the runtime needs).
+// Their stream forms, TextEncoderStream / TextDecoderStream, are in streams.d.ts.
 
 interface TextEncoder {
   /** Always "utf-8". */