@statewalker/webrun-streams 0.1.0 → 0.2.0

package/README.md

@@ -2,6 +2,8 @@
 
 Async-iterator and `ReadableStream` primitives: `collect` / `collectBytes` / `collectString`, text and JSONL codecs, line splitting/joining, a backpressure-aware queue-based generator, a chunk protocol for pushing iterators across transports, conversions between async iterators and WHATWG `ReadableStream<Uint8Array>`, and serialisable `Error` objects.
 
+It also defines the **`Duplex` seam** the whole `webrun-streams-*` transport family implements, and `emulateMux` — a stream multiplexer that turns any message-oriented byte channel into many concurrent `Duplex` calls.
+
 ## Why it exists
 
 Every higher-level package in the `webrun-*` family (and its consumers — scanners, indexers, chat pipelines) needs the same small set of building blocks:
@@ -15,6 +17,16 @@ Every higher-level package in the `webrun-*` family (and its consumers — scann
 
 The MessagePack codec that previously rode along here is split out to [`@statewalker/webrun-msgpack`](../webrun-msgpack) so consumers that don't need framing don't pull in `@ygoe/msgpack`.
 
+## Install
+
+```sh
+npm install @statewalker/webrun-streams
+```
+
+Zero runtime dependencies, zero peer dependencies. ESM only
+(`"type": "module"`); runs in browsers, Node, Deno, Bun and Workers. This is the
+foundation package — everything else in the workspace depends on it.
+
 ## How to use
 
 ```sh
@@ -35,6 +47,9 @@ npm install @statewalker/webrun-streams
 | `recieveIterator(installer)` | Inverse of `sendIterator`: wire an installer's chunk callback into a new `AsyncGenerator<T>`. |
 | `toReadableStream(it)` | Wrap an `AsyncIterator<Uint8Array>` in a `ReadableStream<Uint8Array>`. |
 | `fromReadableStream(stream)` | Iterate a `ReadableStream<Uint8Array>` as `AsyncGenerator<Uint8Array>`. |
+| `emulateMux(channel, opts?)` | Multiplex many concurrent `Duplex` calls over one `ByteChannel`; returns `{ call, serve, close }`. |
+| `normalizeToUint8Array(value)` | Coerce a `ByteLike` (string, `ArrayBuffer`, typed array, `Blob`) to `Uint8Array`. Synchronous except for a `Blob`, which returns a `Promise`. |
+| `toChunks(size?)` | Curried: returns a transform that re-chunks an `AsyncIterable<Uint8Array>` into pieces of at most `size` bytes. `size` defaults to 16384. |
 | `serializeError(error)` | Turn an `Error` (or anything) into a plain `{message, stack, …}` object preserving subclass fields. |
 | `deserializeError(obj \| string)` | Reconstruct an `Error` from a serialised form, restoring extra fields. |
 
@@ -75,11 +90,18 @@ async function* chunks() {
   yield new Uint8Array([0x22, 0x3a, 0x31, 0x7d, 0x0a]);
 }
 
-const values = decodeJsonl<{ a: number }>(splitLines(decodeText(chunks())));
+// `decodeJsonl` splits lines itself — do not wrap it in `splitLines`, or a
+// stream carrying more than one value arrives as one concatenated line and
+// `JSON.parse` throws.
+const values = decodeJsonl<{ a: number }>(decodeText(chunks()));
 for await (const v of values) console.log(v); // { a: 1 }
 
-// inverse
-const jsonl = encodeText(joinLines(encodeJsonl([{ a: 1 }, { a: 2 }])));
+// inverse. `encodeJsonl` already terminates each value with "\n", so
+// `joinLines` here would emit a blank line between every record.
+const jsonl = encodeText(encodeJsonl([{ a: 1 }, { a: 2 }]));
+
+// `splitLines` / `joinLines` are for plain string streams, with no JSON involved:
+for await (const line of splitLines(decodeText(byteStream))) console.log(line);
 ```
 
 ### Callback → AsyncGenerator bridge
@@ -107,19 +129,27 @@ for await (const n of tickEverySecond()) console.log(n); // 0 … 4
 ### Iterator chunk protocol
 
 ```ts
-import { sendIterator, recieveIterator } from "@statewalker/webrun-streams";
+import { collect, recieveIterator, sendIterator } from "@statewalker/webrun-streams";
 
 // Drain an iterable across any transport.
 async function transport<T>(chunk: { done: boolean; value?: T; error?: unknown }) {
-  // …send `chunk` over your channel.
+  await myChannel.send(chunk); // …however your channel sends
 }
-await sendIterator(transport, [1, 2, 3]);
 
 // On the other side, rebuild the original iterator.
 const iter = recieveIterator<number>((deliver) => {
   myChannel.onMessage = (chunk) => deliver(chunk);
 });
-for await (const v of iter) console.log(v); // 1, 2, 3
+
+// Start consuming *before* (or concurrently with) draining the source.
+// `deliver` resolves only once the consumer has dequeued the chunk — that is
+// the backpressure — so awaiting `sendIterator` with nobody iterating `iter`
+// deadlocks both sides.
+const [, received] = await Promise.all([
+  sendIterator(transport, [1, 2, 3]),
+  collect(iter),
+]);
+console.log(received); // [1, 2, 3]
 ```
 
 ### WHATWG streams ↔ async iterators
@@ -160,6 +190,158 @@ console.log(restored instanceof Error); // true
 console.log(restored.status);           // 404
 ```
 
+## The `Duplex` seam
+
+Everything in the `webrun-streams-*` family speaks one shape:
+
+```ts
+type Duplex = (input: AsyncIterable<Uint8Array> | Iterable<Uint8Array>) => AsyncGenerator<Uint8Array>;
+```
+
+One `Duplex` invocation carries **one logical call**: the caller emits bytes,
+the peer yields bytes back. Because both sides have the same shape, an
+in-process test can wire `const caller = handler` and run with no transport at
+all.
+
+Iterator semantics carry every signal, which is why no separate close/abort API
+exists:
+
+| Signal | Mechanism |
+| --- | --- |
+| Consumer is done early | `.return()` on the output → producer's `finally` runs |
+| Producer failed | `throw` → consumer's `for await` throws |
+| Either side finished normally | Normal exhaustion → matching end on the other side |
+
+`Connect<P>` and `Serve<P>` are the adapter-side factories that stand up a
+transport and produce or register a `Duplex`.
+
+> **Caller obligation.** Either drain the returned generator or `.return()` it.
+> Dropping the reference without doing either emits no observable signal: the
+> abandoned consumer never acknowledges inbound data, so the peer's outbound
+> pump blocks awaiting that acknowledgement, no end-of-stream is exchanged, and
+> both peers hold the stream open. An unreferenced generator is not observable,
+> so no transport can detect this for you.
+
+## `emulateMux`
+
+Turns one `ByteChannel` — anything with `send` / `recv` / `closed` / `close` —
+into many concurrent `Duplex` calls. Used by the MessagePort, WebSocket,
+LiveKit, PeerJS and signaling adapters; transports with native multiplexing
+(libp2p) don't need it.
+
+```ts
+import { emulateMux } from "@statewalker/webrun-streams";
+
+const { call, serve, close } = emulateMux(channel, { side: "initiator" });
+
+// caller side
+const response = call([new TextEncoder().encode("ping")]);
+for await (const chunk of response) { /* … */ }
+
+// responder side
+const stop = serve(async function* handler(input) {
+  for await (const chunk of input) yield chunk; // echo
+});
+```
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `side` | `"initiator"` | Id allocation: initiator uses even ids, responder odd. Pick one per peer so they cannot collide. |
+| `maxStreams` | `256` | Concurrent streams before new calls are refused. |
+| `mtu` | `65536` | Largest payload per DATA frame; bigger chunks are split. |
+| `maxStreamBuffer` | `8388608` | The credit this side advertises to the peer, in bytes, and the hard cap on inbound bytes one stream may hold undrained. A peer that honours credit never reaches the cap; one that ignores it has that stream torn down. |
+
+### Flow control
+
+Receiver-advertised credit. Each side puts its `maxStreamBuffer` in the frame it
+opens with — `OPEN` for the caller, the `ACK` answering it for the responder —
+and the sender may only send what it has been granted. Both sides start at zero,
+so a caller pays one round trip per stream before its first DATA frame and none
+thereafter. The receiver grants more once its consumer has actually drained,
+batched at half the window and flushed as soon as its queue empties. A sender
+therefore cannot overrun the receiver's buffer, and `maxStreamBuffer` bounds only
+peers that ignore the protocol.
+
+Backpressure is **per-stream**, so a stalled stream does not block the others,
+and it applies symmetrically in both directions.
+
+There is deliberately **no stall timeout**: a peer that never acknowledges
+blocks that producer indefinitely, exactly as a TCP receiver that never reads
+blocks its sender. `maxStreams` and `maxStreamBuffer` bound what that can cost.
+The bound is per stream and there is no mux-wide budget, so the worst case is
+`maxStreams × maxStreamBuffer` — 2 GiB at the defaults, against 16 MiB under the
+one-frame-in-flight rule this replaced. Lower `maxStreamBuffer` if that matters
+more than throughput.
+
+### Behaviour on hostile input
+
+A `ByteChannel` is message-oriented, so frames are discrete and a corrupt one
+cannot desync the next. A frame that cannot be parsed is therefore **dropped**
+rather than failing the connection — otherwise one malformed frame would tear
+down every stream sharing the mux. A stream that exceeds `maxStreamBuffer` is
+torn down on its own, with an error frame sent to the peer.
+
+## Exports
+
+Everything is exported from the package root.
+
+### Seam types
+
+| Export | Kind | Purpose |
+| --- | --- | --- |
+| `Duplex` | type | `(input) => AsyncGenerator<Uint8Array>` — one logical call. |
+| `Connect<P>` | type | `(params) => Promise<{ call: Duplex; close() }>`. |
+| `Serve<P>` | type | `(params, handler) => Promise<() => Promise<void>>`. |
+| `ByteChannel` | type | `{ send, recv, closed, close }` — the minimum a transport must expose. |
+| `ByteLike` | type | Accepted byte inputs before normalisation. |
+| `emulateMux(channel, opts?)` | function | Multi-stream over a single `ByteChannel`. |
+| `EmulateMuxOptions` | type | `maxStreams` (256), `mtu` (64 KiB), `maxStreamBuffer` (8 MiB), `side`. |
+| `TransportClosedError` | class | Thrown when the transport closes with calls in flight. Catch via `instanceof` or `error.name`. |
+
+The port multiplexing layer — `multiplexPort`, `PortMux`, `structuredCodec`,
+`PortEnvelope` and the `MessageTarget` family of types — lives in
+[`@statewalker/webrun-rpc`](../webrun-rpc#port-multiplexing), not here.
+
+### Credit
+
+| Export | Kind | Purpose |
+| --- | --- | --- |
+| `newCreditLedger(initial?)` | function | Sender-side credit: `reserve(upTo)` waits for any credit and returns how much it got (`upTo` must be >= 1; less rejects with a `RangeError`), `grant(units)` releases waiters in order, `fail(err)` unwinds them. Starts at zero unless told otherwise. |
+| `CreditLedger` | type | `{ available, reserve, grant, fail }`. |
+| `newCreditGrantor(window, threshold?)` | function | Receiver-side: `consumed(units, queueEmpty)` returns the credit to hand back, batched at `threshold` (default half the window) and flushed once the queue empties. |
+| `CreditGrantor` | type | `{ consumed(units, queueEmpty): number }`. |
+
+The unit is whatever the caller counts. `emulateMux` counts bytes; a value-
+oriented caller would count values. Nothing in this module interprets it.
+
+### Collectors and codecs
+
+| Export | Purpose |
+| --- | --- |
+| `collect` / `collectBytes` / `collectString` | Drain an async iterable to an array / `Uint8Array` / `string`. |
+| `encodeText` / `decodeText` | UTF-8 `string` ↔ `Uint8Array` streams. |
+| `splitLines` / `joinLines` | Cross-chunk-safe line splitting and rejoining. |
+| `encodeJsonl` / `decodeJsonl` | JSON values ↔ `\n`-delimited string stream. |
+| `map` | Stream-map over an `AsyncIterable<T>`. |
+| `toChunks` / `normalizeToUint8Array` | Coerce assorted byte-ish inputs into `Uint8Array` chunks. |
+
+### Iterator plumbing
+
+| Export | Purpose |
+| --- | --- |
+| `newAsyncGenerator` | Backpressure-aware queue turning `next`/`done` callbacks into an async generator. |
+| `sendIterator` / `recieveIterator` | Ship an async iterator across any transport. |
+| `IteratorChunk` | type — the `{ done, value, error }` chunk envelope they exchange. |
+| `ChunkSender` / `ChunkReceiver` / `ReceiverInstaller` | types — the transport-side callbacks those two are wired to. |
+| `toReadableStream` / `fromReadableStream` | `AsyncIterator<Uint8Array>` ↔ WHATWG `ReadableStream<Uint8Array>`. |
+
+### Errors
+
+| Export | Purpose |
+| --- | --- |
+| `serializeError` / `deserializeError` | Preserve `message`, `stack` and custom fields across JSON / structured-clone boundaries. |
+| `SerializedError` | type — the wire shape those two produce and consume. |
+
 ## Internals
 
 ### `newAsyncGenerator` — backpressure queue
@@ -210,9 +392,11 @@ strict one-way converters: no queuing strategy tricks, no transform.
 - **British/American spelling kept.** `recieveIterator` uses the
   historical misspelling to stay wire-compatible with `webrun-ports`
   consumers.
-- **No tight coupling to any transport.** Nothing here mentions
-  `MessagePort`, `fetch`, `Worker`, etc. Those belong to the consuming
-  packages.
+- **No tight coupling to any transport.** `ByteChannel` is the only
+  transport-facing type, and it is an interface — nothing here mentions
+  `MessagePort`, `WebSocket`, `fetch`, `Worker`, etc. Those belong to the
+  `webrun-streams-*` adapters, each of which supplies a `ByteChannel` and lets
+  `emulateMux` do the rest.
 
 ### Constraints
 
@@ -227,17 +411,17 @@ strict one-way converters: no queuing strategy tricks, no transform.
 
 **Zero runtime dependencies.**
 
-Dev: TypeScript, vitest, tsdown, rimraf, `@types/node`
+Dev: TypeScript, vitest, rolldown, rimraf, `@types/node`
 (catalog versions from the monorepo root).
 
 ## Scripts
 
 ```sh
 pnpm test        # vitest run
-pnpm run build   # tsdown (publishes src + compiled dist)
+pnpm run build   # rolldown + tsc --emitDeclarationOnly (ships src + dist)
 pnpm lint        # biome check
 ```
 
 ## License
 
-MIT © statewalker
+MIT © statewalker — see [LICENSE](../../LICENSE).

package/dist/collect.d.ts

@@ -0,0 +1,7 @@
+/** Collect all items from an async iterable into an array. */
+export declare function collect<T>(input: AsyncIterable<T>): Promise<T[]>;
+/** Concatenate all Uint8Array chunks into a single Uint8Array. */
+export declare function collectBytes(input: AsyncIterable<Uint8Array>): Promise<Uint8Array>;
+/** Concatenate all string chunks into a single string. */
+export declare function collectString(input: AsyncIterable<string>): Promise<string>;
+//# sourceMappingURL=collect.d.ts.map

package/dist/collect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect.d.ts","sourceRoot":"","sources":["../src/collect.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,wBAAsB,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAItE;AAED,kEAAkE;AAClE,wBAAsB,YAAY,CAAC,KAAK,EAAE,aAAa,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,CAexF;AAED,0DAA0D;AAC1D,wBAAsB,aAAa,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAIjF"}

package/dist/duplex.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The transport seam every `webrun-streams-*` adapter and the conformance suite
+ * are written against.
+ *
+ * These types live here rather than beside an implementation on purpose: the
+ * emulated multiplexer that once declared them is scheduled for deletion, and a
+ * seam that disappears with its first implementation is not a seam.
+ */
+/**
+ * Canonical seam for the webrun-streams transport family. A `Duplex` carries
+ * one logical call: caller emits an iterable of bytes as input, peer yields an
+ * async generator of bytes as output. Same shape on both sides — an in-process
+ * test can wire `const caller = handler` and run without any transport.
+ *
+ * Iterator semantics carry every signal:
+ *  - Consumer `.return()` on the output → producer's `finally` runs.
+ *  - Producer `throw` → consumer's `for await` throws.
+ *  - Normal exhaustion on either side → matching end on the other side.
+ */
+export type Duplex = (input: AsyncIterable<Uint8Array> | Iterable<Uint8Array>) => AsyncGenerator<Uint8Array>;
+/**
+ * Adapter-side factory that stands up a transport connection and yields a
+ * caller `Duplex`. One `Connect` invocation owns one transport; each call
+ * to the resolved `call` opens a new sub-stream on it.
+ *
+ * A caller must either drain the returned generator or `.return()` it.
+ * Dropping the reference without doing either emits no observable signal:
+ * the abandoned consumer never acknowledges inbound data, so the peer's
+ * outbound pump blocks awaiting that acknowledgement, no end-of-stream is
+ * ever exchanged, and both peers hold the stream's slot open. There is no
+ * way for the transport to detect this — an unreferenced generator is not
+ * observable — so it is the consumer's obligation.
+ */
+export type Connect<P> = (params: P) => Promise<{
+    call: Duplex;
+    close: () => Promise<void>;
+}>;
+/**
+ * Adapter-side factory that registers a handler `Duplex` against a transport.
+ * Returns an idempotent teardown.
+ */
+export type Serve<P> = (params: P, handler: Duplex) => Promise<() => Promise<void>>;
+/**
+ * Thrown by `emulateMux` and adapters when the underlying transport closes
+ * while one or more `Duplex` calls are in flight. Consumers can catch by
+ * `instanceof TransportClosedError` or by checking `error.name`.
+ */
+export declare class TransportClosedError extends Error {
+    readonly name = "TransportClosedError";
+    constructor(message?: string);
+}
+//# sourceMappingURL=duplex.d.ts.map

package/dist/duplex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duplex.d.ts","sourceRoot":"","sources":["../src/duplex.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,MAAM,GAAG,CACnB,KAAK,EAAE,aAAa,CAAC,UAAU,CAAC,GAAG,QAAQ,CAAC,UAAU,CAAC,KACpD,cAAc,CAAC,UAAU,CAAC,CAAC;AAEhC;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;AAEpF;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,SAAkB,IAAI,0BAA0B;IAChD,YAAY,OAAO,SAAqB,EAEvC;CACF"}

package/dist/emulate-mux.d.ts

@@ -0,0 +1,39 @@
+import { type Duplex } from "./duplex.js";
+/**
+ * The minimum a transport must expose to be wrapped by `emulateMux`. Inbound
+ * bytes are surfaced as an async iterable; outbound is imperative `send`. All
+ * five message-oriented transports (WebSocket, LiveKit data channel, PeerJS
+ * DataConnection, MessagePort, in-process pipe) match this shape after a thin
+ * wrapper.
+ */
+export type ByteChannel = {
+    send(bytes: Uint8Array): void;
+    recv: AsyncIterable<Uint8Array>;
+    closed: Promise<void>;
+    close(): void;
+};
+export interface EmulateMuxOptions {
+    maxStreams?: number;
+    mtu?: number;
+    /**
+     * Cap on inbound bytes one stream may hold for a consumer that has not
+     * drained them. Exceeding it tears down that stream alone.
+     *
+     * It is also the credit this side advertises to the peer, so it must be at
+     * least 1 — a window of 0 authorises nothing and hangs the peer forever —
+     * and it travels in a uint32, so a value above `MAX_UINT32` (4 GiB - 1) is
+     * advertised as `MAX_UINT32`.
+     */
+    maxStreamBuffer?: number;
+    /**
+     * Stream-id allocation side. Initiator uses even ids (2, 4, …); responder
+     * uses odd ids (1, 3, …). Pick one per peer so allocations don't collide.
+     */
+    side?: "initiator" | "responder";
+}
+export declare function emulateMux(channel: ByteChannel, opts?: EmulateMuxOptions): {
+    call: Duplex;
+    serve: (handler: Duplex) => () => Promise<void>;
+    close: () => Promise<void>;
+};
+//# sourceMappingURL=emulate-mux.d.ts.map

package/dist/emulate-mux.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emulate-mux.d.ts","sourceRoot":"","sources":["../src/emulate-mux.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAwB,MAAM,aAAa,CAAC;AAUhE;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9B,IAAI,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAChC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,KAAK,IAAI,IAAI,CAAC;CACf,CAAC;AA4CF,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,IAAI,CAAC,EAAE,WAAW,GAAG,WAAW,CAAC;CAClC;AAED,wBAAgB,UAAU,CACxB,OAAO,EAAE,WAAW,EACpB,IAAI,GAAE,iBAAsB,GAC3B;IACD,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B,CAuVA"}

package/dist/errors.d.ts

@@ -0,0 +1,8 @@
+export interface SerializedError {
+    message: string;
+    stack?: string;
+    [key: string]: unknown;
+}
+export declare function serializeError(error: unknown): SerializedError;
+export declare function deserializeError(error: SerializedError | string): Error;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAY9D;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,GAAG,KAAK,CAGvE"}

package/dist/flow-control.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Credit-based flow control, as a pair of pure state machines with no I/O.
+ *
+ * The sender holds a {@link CreditLedger}: it reserves credit before it puts
+ * anything on the wire, and stalls at zero. The receiver holds a
+ * {@link CreditGrantor}: it counts what its consumer has actually drained and
+ * says when to hand the sender more.
+ *
+ * A sender therefore cannot overrun a receiver's buffer, because it was never
+ * granted permission to. That is the property a sender-side window cannot
+ * offer: the receiver's capacity is not knowable to the sender unless the
+ * receiver states it.
+ *
+ * **The unit is opaque.** This module never interprets the numbers it counts.
+ * `emulateMux` passes byte counts and advertises `maxStreamBuffer`; the RPC
+ * tier passes 1 per value and advertises a maximum in-flight value count.
+ * Nothing here depends on which.
+ */
+export interface CreditLedger {
+    /** Units authorised by the peer and not yet reserved. */
+    readonly available: number;
+    /**
+     * Reserve up to `upTo` units, resolving with how many were actually
+     * granted — at least 1, never more than `upTo`. The caller sends exactly
+     * that much and calls `reserve` again for the rest.
+     *
+     * `upTo` must itself be at least 1; anything less rejects with a
+     * `RangeError` rather than resolving with 0, which would be a silent no-op
+     * that also consumed a waiter slot.
+     *
+     * Returning a partial amount rather than waiting for the full request is
+     * what makes the ledger deadlock-free: a peer that advertises less than
+     * one `upTo` still makes progress, one short piece at a time.
+     *
+     * Rejects if {@link fail} is called.
+     */
+    reserve(upTo: number): Promise<number>;
+    /** The peer authorised `units` more. */
+    grant(units: number): void;
+    /** Reject every pending and future reservation — transport or stream is gone. */
+    fail(err: Error): void;
+}
+export declare function newCreditLedger(initial?: number): CreditLedger;
+export interface CreditGrantor {
+    /**
+     * Record that the consumer drained `units`, and whether the receive queue
+     * is now empty. Returns the credit to hand back to the peer, or `0` to stay
+     * silent and keep accumulating.
+     */
+    consumed(units: number, queueEmpty: boolean): number;
+}
+/**
+ * Grants are batched: replenishing on every chunk while the receiver is
+ * behind would reinvent the per-frame ACK this change exists to remove.
+ * `threshold` is the fraction of the window that must drain before a grant is
+ * emitted.
+ *
+ * The batch is flushed unconditionally once the receive queue is empty, even
+ * below the threshold, so the receiver never sits on credit it owes. Note what
+ * this is and is not: paired with a {@link CreditLedger}, a sender blocks only
+ * at *exactly* zero credit, and at that point the receiver holds the entire
+ * window as `pending` — above any threshold at or below the whole window — so
+ * the threshold alone cannot deadlock that pairing. The flush is what keeps
+ * that from being an argument about a global accounting identity: it is
+ * locally decidable from one boolean, and it returns owed credit now rather
+ * than at the next threshold crossing. It costs an extra frame only when the
+ * consumer is keeping pace, which is exactly when the sender is not blocked
+ * and the frame is cheap.
+ */
+export declare function newCreditGrantor(window: number, threshold?: number): CreditGrantor;
+//# sourceMappingURL=flow-control.d.ts.map

package/dist/flow-control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-control.d.ts","sourceRoot":"","sources":["../src/flow-control.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,YAAY;IAC3B,yDAAyD;IACzD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACvC,wCAAwC;IACxC,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,iFAAiF;IACjF,IAAI,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI,CAAC;CACxB;AAQD,wBAAgB,eAAe,CAAC,OAAO,SAAI,GAAG,YAAY,CAqDzD;AAED,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,GAAG,MAAM,CAAC;CACtD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,SAAM,GAAG,aAAa,CAa/E"}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export * from "./collect.js";
+export * from "./duplex.js";
+export * from "./emulate-mux.js";
+export * from "./errors.js";
+export * from "./flow-control.js";
+export * from "./jsonl.js";
+export * from "./lines.js";
+export * from "./map.js";
+export * from "./new-async-generator.js";
+export * from "./normalize.js";
+export * from "./readable-streams.js";
+export * from "./recieve-iterator.js";
+export * from "./send-iterator.js";
+export * from "./text.js";
+export * from "./to-chunks.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,0BAA0B,CAAC;AACzC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC"}