@statewalker/webrun-streams 0.1.0

package/dist/index.mjs

@@ -0,0 +1,722 @@
+//#region src/collect.ts
+/** Collect all items from an async iterable into an array. */
+async function collect(input) {
+	const items = [];
+	for await (const item of input) items.push(item);
+	return items;
+}
+/** Concatenate all Uint8Array chunks into a single Uint8Array. */
+async function collectBytes(input) {
+	const chunks = [];
+	let total = 0;
+	for await (const chunk of input) {
+		chunks.push(chunk);
+		total += chunk.length;
+	}
+	if (chunks.length === 1) return chunks[0] ?? new Uint8Array(0);
+	const result = new Uint8Array(total);
+	let offset = 0;
+	for (const chunk of chunks) {
+		result.set(chunk, offset);
+		offset += chunk.length;
+	}
+	return result;
+}
+/** Concatenate all string chunks into a single string. */
+async function collectString(input) {
+	let result = "";
+	for await (const chunk of input) result += chunk;
+	return result;
+}
+//#endregion
+//#region src/errors.ts
+function serializeError(error) {
+	if (error instanceof Error) {
+		const out = {
+			message: error.message,
+			stack: error.stack
+		};
+		const bag = error;
+		for (const key of Object.keys(bag)) out[key] = bag[key];
+		return out;
+	}
+	if (typeof error === "object" && error !== null) {
+		const bag = error;
+		return {
+			message: String(bag.message ?? error),
+			...bag
+		};
+	}
+	return { message: String(error) };
+}
+function deserializeError(error) {
+	const payload = typeof error === "string" ? { message: error } : error;
+	return Object.assign(new Error(payload.message), payload);
+}
+//#endregion
+//#region src/emulate-mux.ts
+/**
+* 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`.
+*/
+var TransportClosedError = class extends Error {
+	name = "TransportClosedError";
+	constructor(message = "transport closed") {
+		super(message);
+	}
+};
+const TYPE_OPEN = 1;
+const TYPE_DATA = 2;
+const TYPE_ACK = 3;
+const TYPE_END = 4;
+const TYPE_ERROR = 5;
+const TYPE_CLOSE = 6;
+const DEFAULT_MAX_STREAMS = 256;
+const DEFAULT_MTU = 64 * 1024;
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+function emulateMux(channel, opts = {}) {
+	const maxStreams = opts.maxStreams ?? DEFAULT_MAX_STREAMS;
+	const mtu = opts.mtu ?? DEFAULT_MTU;
+	const side = opts.side ?? "initiator";
+	const streams = /* @__PURE__ */ new Map();
+	let nextLocalId = side === "initiator" ? 2 : 1;
+	let handler = null;
+	let muxClosed = false;
+	const sendFrame = (id, type, payload) => {
+		if (muxClosed) return;
+		const idEnc = encodeVarint(id);
+		const total = idEnc.length + 1 + (payload?.byteLength ?? 0);
+		const frame = new Uint8Array(total);
+		frame.set(idEnc, 0);
+		frame[idEnc.length] = type;
+		if (payload && payload.byteLength > 0) frame.set(payload, idEnc.length + 1);
+		try {
+			channel.send(frame);
+		} catch {}
+	};
+	const teardownStream = (s, err) => {
+		if (s.closed) return;
+		s.closed = true;
+		const resolve = s.resolveAck;
+		const reject = s.rejectAck;
+		s.resolveAck = null;
+		s.rejectAck = null;
+		if (reject && err) reject(err);
+		else resolve?.();
+		s.doneIn(err);
+		streams.delete(s.id);
+	};
+	const failAll = (err) => {
+		if (muxClosed) return;
+		muxClosed = true;
+		for (const s of [...streams.values()]) teardownStream(s, err);
+		streams.clear();
+	};
+	const createStream = (id) => {
+		const queue = makeInboundQueue();
+		const state = {
+			id,
+			inbound: queue.generator(() => {
+				if (!state.closed && !muxClosed) sendFrame(state.id, TYPE_CLOSE);
+				teardownStream(state);
+			}),
+			pushIn: queue.push,
+			doneIn: queue.done,
+			resolveAck: null,
+			rejectAck: null,
+			closed: false
+		};
+		return state;
+	};
+	const pumpOutbound = async (s, input) => {
+		try {
+			for await (const chunk of input) {
+				if (s.closed || muxClosed) return;
+				if (chunk.byteLength === 0) continue;
+				let off = 0;
+				while (off < chunk.byteLength) {
+					if (s.closed || muxClosed) return;
+					const end = Math.min(off + mtu, chunk.byteLength);
+					const piece = chunk.subarray(off, end);
+					sendFrame(s.id, TYPE_DATA, piece);
+					await new Promise((resolve, reject) => {
+						s.resolveAck = resolve;
+						s.rejectAck = reject;
+					});
+					off = end;
+				}
+			}
+			if (!s.closed && !muxClosed) sendFrame(s.id, TYPE_END);
+		} catch (err) {
+			if (!s.closed && !muxClosed) {
+				const e = err instanceof Error ? err : new Error(String(err));
+				sendFrame(s.id, TYPE_ERROR, encodeError(e));
+				teardownStream(s, e);
+			}
+		}
+	};
+	const runHandler = async (s, h) => {
+		let outbound;
+		try {
+			outbound = h(s.inbound);
+		} catch (err) {
+			const e = err instanceof Error ? err : new Error(String(err));
+			sendFrame(s.id, TYPE_ERROR, encodeError(e));
+			teardownStream(s, e);
+			return;
+		}
+		await pumpOutbound(s, outbound);
+	};
+	const handleFrame = (frame) => {
+		if (muxClosed) return;
+		if (frame.byteLength < 2) return;
+		const { value: id, offset } = decodeVarint(frame, 0);
+		const type = frame[offset];
+		const payload = frame.subarray(offset + 1);
+		if (type === TYPE_OPEN) {
+			if (streams.has(id)) return;
+			if (streams.size >= maxStreams) {
+				sendFrame(id, TYPE_ERROR, encodeError(/* @__PURE__ */ new RangeError(`emulateMux: maxStreams=${maxStreams} exceeded`)));
+				return;
+			}
+			if (!handler) {
+				sendFrame(id, TYPE_ERROR, encodeError(/* @__PURE__ */ new Error("emulateMux: no handler registered")));
+				return;
+			}
+			const s = createStream(id);
+			streams.set(id, s);
+			runHandler(s, handler);
+			return;
+		}
+		const s = streams.get(id);
+		if (!s) return;
+		switch (type) {
+			case TYPE_DATA: {
+				const copy = payload.byteLength === 0 ? payload : new Uint8Array(payload);
+				s.pushIn(copy).then((handled) => {
+					if (handled && !s.closed && !muxClosed) sendFrame(id, TYPE_ACK);
+				});
+				return;
+			}
+			case TYPE_ACK: {
+				const r = s.resolveAck;
+				s.resolveAck = null;
+				s.rejectAck = null;
+				r?.();
+				return;
+			}
+			case TYPE_END:
+				s.doneIn();
+				return;
+			case TYPE_ERROR:
+				teardownStream(s, decodeError(payload));
+				return;
+			case TYPE_CLOSE:
+				teardownStream(s);
+				return;
+			default: return;
+		}
+	};
+	(async () => {
+		try {
+			for await (const frame of channel.recv) {
+				if (muxClosed) break;
+				handleFrame(frame);
+			}
+		} catch (err) {
+			failAll(err instanceof Error ? err : new Error(String(err)));
+			return;
+		}
+		failAll(new TransportClosedError());
+	})();
+	channel.closed.then(() => failAll(new TransportClosedError())).catch(() => {});
+	const call = (input) => {
+		if (muxClosed) return failedGenerator(new TransportClosedError());
+		if (streams.size >= maxStreams) return failedGenerator(/* @__PURE__ */ new RangeError(`emulateMux: maxStreams=${maxStreams} exceeded`));
+		const id = nextLocalId;
+		nextLocalId += 2;
+		const s = createStream(id);
+		streams.set(id, s);
+		sendFrame(id, TYPE_OPEN);
+		pumpOutbound(s, input);
+		return s.inbound;
+	};
+	const serve = (h) => {
+		handler = h;
+		let torn = false;
+		return async () => {
+			if (torn) return;
+			torn = true;
+			if (handler === h) handler = null;
+		};
+	};
+	const close = async () => {
+		if (muxClosed) return;
+		failAll(new TransportClosedError());
+		try {
+			channel.close();
+		} catch {}
+	};
+	return {
+		call,
+		serve,
+		close
+	};
+}
+function failedGenerator(err) {
+	return (async function* () {
+		throw err;
+	})();
+}
+/**
+* Push/pull queue with eager push/done handles. Unlike `newAsyncGenerator`, the
+* push and done functions are usable *before* the consumer begins iterating —
+* `emulateMux` needs to enqueue frames from inbound traffic regardless of when
+* (or whether) the consumer pulls them.
+*
+* `onCancel` fires only when the consumer terminates the generator before
+* `done()` was called — i.e., a unilateral cancellation. If `done()` is
+* called first (peer END/ERROR/CLOSE), the generator ends naturally and
+* `onCancel` does not fire.
+*/
+function makeInboundQueue() {
+	const slots = [];
+	let wake = null;
+	let queueClosed = false;
+	let doneCalled = false;
+	const push = (chunk) => {
+		if (queueClosed) return Promise.resolve(false);
+		return new Promise((resolve) => {
+			slots.push({
+				type: "value",
+				value: chunk,
+				resolve
+			});
+			wake?.();
+		});
+	};
+	const done = (err) => {
+		if (queueClosed || doneCalled) return Promise.resolve(false);
+		doneCalled = true;
+		return new Promise((resolve) => {
+			slots.push({
+				type: "done",
+				err,
+				resolve
+			});
+			wake?.();
+		});
+	};
+	async function* generator(onCancel) {
+		try {
+			while (true) {
+				if (slots.length === 0) {
+					await new Promise((r) => {
+						wake = r;
+					});
+					wake = null;
+					continue;
+				}
+				const slot = slots.shift();
+				if (slot.type === "done") {
+					slot.resolve(true);
+					if (slot.err) throw slot.err;
+					return;
+				}
+				yield slot.value;
+				slot.resolve(true);
+			}
+		} finally {
+			queueClosed = true;
+			for (const s of slots) s.resolve(false);
+			slots.length = 0;
+			if (!doneCalled) onCancel();
+		}
+	}
+	return {
+		generator,
+		push,
+		done
+	};
+}
+function encodeVarint(value) {
+	if (!Number.isInteger(value) || value < 0) throw new RangeError(`encodeVarint: ${value} is not a non-negative integer`);
+	const out = [];
+	let v = value;
+	while (v >= 128) {
+		out.push(v & 127 | 128);
+		v >>>= 7;
+	}
+	out.push(v & 127);
+	return new Uint8Array(out);
+}
+function decodeVarint(buf, start) {
+	let value = 0;
+	let shift = 0;
+	let i = start;
+	while (i < buf.length) {
+		const b = buf[i++];
+		value |= (b & 127) << shift;
+		if ((b & 128) === 0) return {
+			value: value >>> 0,
+			offset: i
+		};
+		shift += 7;
+		if (shift > 28) throw new Error("decodeVarint: too long");
+	}
+	throw new Error("decodeVarint: truncated");
+}
+function encodeError(err) {
+	return textEncoder.encode(JSON.stringify(serializeError(err)));
+}
+function decodeError(buf) {
+	if (buf.byteLength === 0) return /* @__PURE__ */ new Error("unknown stream error");
+	try {
+		return deserializeError(JSON.parse(textDecoder.decode(buf)));
+	} catch {
+		return new Error(textDecoder.decode(buf));
+	}
+}
+//#endregion
+//#region src/lines.ts
+/** Split a stream of string chunks into individual lines (delimited by \n). */
+async function* splitLines(input) {
+	let buffer = "";
+	for await (const chunk of input) {
+		buffer += chunk;
+		let idx = buffer.indexOf("\n");
+		while (idx !== -1) {
+			yield buffer.slice(0, idx);
+			buffer = buffer.slice(idx + 1);
+			idx = buffer.indexOf("\n");
+		}
+	}
+	if (buffer) yield buffer;
+}
+/** Append \n to each string in the stream. */
+async function* joinLines(input) {
+	for await (const line of input) yield `${line}\n`;
+}
+//#endregion
+//#region src/map.ts
+/** Apply a sync or async function to each item in a stream. */
+async function* map(input, fn) {
+	for await (const item of input) yield await fn(item);
+}
+//#endregion
+//#region src/jsonl.ts
+/** Encode each value as a JSON line (terminated by \n). */
+async function* encodeJsonl(input) {
+	yield* map(input, (item) => `${JSON.stringify(item)}\n`);
+}
+/** Decode each line as a JSON value. Skips empty lines. */
+async function* decodeJsonl(input) {
+	for await (const line of splitLines(input)) {
+		const trimmed = line.trim();
+		if (trimmed) yield JSON.parse(trimmed);
+	}
+}
+//#endregion
+//#region src/new-async-generator.ts
+/**
+* The newAsyncGenerator function creates async generators from callback-based initialization
+* functions, providing a bridge between imperative event handling and declarative async
+* iteration patterns.
+*
+* The initialization function receives two callback functions that control the generator's
+* behavior. The `next` function yields values to consumers, while the `done` function
+* signals completion or error conditions. The initialization function can return a cleanup
+* function that will be called when the generator is closed or an error occurs.
+*
+* The generator manages an internal queue of values and completion signals, ensuring that
+* producers can yield values without overwhelming consumers. Proper backpressure is implemented
+* by having the `next` and `done` functions return promises that resolve only after the
+* consumer has processed the values. This prevents memory leaks and ensures that producers
+* are aware of whether their values were successfully handled.
+* The generator also handles cleanup by draining any remaining items in the queue and notifying
+* producers that their values were not processed if the generator is closed early. This ensures
+* that resources are properly managed and that no memory leaks occur.
+*
+* Example usage:
+* ```typescript
+* const asyncGen = newAsyncGenerator<number>((next, done) => {
+*   let count = 0;
+*   const interval = setInterval(() => {
+*     if (count < 5) {
+*       next(count++);
+*     } else {
+*       done();
+*       clearInterval(interval);
+*     }
+*   }, 1000);
+*   return () => clearInterval(interval); // Cleanup function
+* });
+* (async () => {
+*   for await (const num of asyncGen) {
+*     console.log(num); // Logs numbers 0 to 4 at 1 second intervals
+*   }
+*   console.log("Completed");
+* })();
+* ```
+* @template T The type of values yielded by the generator
+* @template E The type of errors that can be thrown; defaults to Error
+* @param init Initialization function that sets up the generator behavior with next/done callbacks;
+*  The first parameter - `next` function - is used to yield values to consumers;
+*  It returns a Promise<boolean> indicating whether the value was successfully handled;
+*  The second parameter - `done` function - is used to signal completion or error;
+*  It returns a Promise<boolean> indicating whether the completion was successfully handled;
+*  The initialization function can optionally return a cleanup function that will be called
+*  when the generator is closed or an error occurs;
+* @param skipValues If true, only the most recent value is kept in the queue,
+* skipping intermediate values (not consumed values are considered skipped);
+* This is useful for scenarios where only the latest value matters, such as UI updates.
+* Defaults to false, meaning all values are queued and processed in order.
+* @returns AsyncGenerator that properly manages backpressure and resource cleanup
+*/
+async function* newAsyncGenerator(init, skipValues = false) {
+	let head;
+	let tail;
+	/** Flag to prevent new values from being queued after generator closes */
+	let closed = false;
+	/** Wake-up function to notify the generator loop of new items */
+	let wakeUp;
+	/**
+	* Drains the internal queue, notifying all pending producers that their values
+	* were not processed due to generator closure. This prevents memory leaks and
+	* ensures proper backpressure signaling.
+	*/
+	const drainQueue = () => {
+		for (; head; head = head.next) {
+			closed = closed || head.done;
+			head.resolve(false);
+		}
+		tail = void 0;
+	};
+	/**
+	* Enqueues a value or completion signal with a promise that resolves when the item
+	* is processed. This enables backpressure by allowing producers to know when their
+	* values have been consumed.
+	*/
+	const enqueue = (params) => {
+		if (skipValues) drainQueue();
+		return !closed ? new Promise((resolve) => {
+			const next = {
+				...params,
+				next: void 0,
+				resolve
+			};
+			if (tail) tail.next = next;
+			tail = next;
+			if (!head) head = tail;
+			wakeUp?.();
+		}) : Promise.resolve(false);
+	};
+	/**
+	* Producer function to yield a value to consumers. Returns a promise that resolves
+	* to true if the value was successfully processed, false if the generator is closed
+	* or the value was skipped due to backpressure.
+	*/
+	const next = (value) => enqueue({
+		done: false,
+		value
+	});
+	/**
+	* Producer function to signal completion or error. Optional error parameter will
+	* cause the generator to throw that error to consumers.
+	*/
+	const done = (error) => enqueue({
+		done: true,
+		error
+	});
+	const unsubscribe = init(next, done);
+	try {
+		while (!closed) {
+			if (!head) {
+				await new Promise((resolve) => {
+					wakeUp = resolve;
+				}).then(() => {
+					wakeUp = void 0;
+				});
+				continue;
+			}
+			const slot = head;
+			head = head.next;
+			if (tail === slot) tail = head;
+			try {
+				if (slot.done) {
+					closed = true;
+					if (slot.error !== void 0) throw slot.error;
+					break;
+				}
+				yield slot.value;
+			} finally {
+				slot.resolve(true);
+			}
+		}
+	} finally {
+		/**
+		* Cleanup phase - ensures proper resource management and notification of any
+		* remaining producers. This runs whether the generator completes normally,
+		* encounters an error, or is closed early by the consumer.
+		*/
+		closed = true;
+		wakeUp?.();
+		if (typeof unsubscribe === "function") await unsubscribe();
+		/**
+		* Drain any remaining items in the queue and notify their producers that
+		* the values were not processed. This prevents memory leaks and ensures
+		* proper backpressure signaling.
+		*/
+		drainQueue();
+	}
+}
+//#endregion
+//#region src/normalize.ts
+const utf8 = new TextEncoder();
+/**
+* Coerce common byte-like inputs into a `Uint8Array`. Strings encode as UTF-8.
+* Blobs return a `Promise<Uint8Array>`; every other input returns synchronously.
+* Throws `TypeError` for anything else.
+*/
+function normalizeToUint8Array(data) {
+	if (data instanceof Uint8Array) return data;
+	if (data instanceof ArrayBuffer) return new Uint8Array(data);
+	if (ArrayBuffer.isView(data)) return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+	if (typeof Blob !== "undefined" && data instanceof Blob) return data.arrayBuffer().then((buf) => new Uint8Array(buf));
+	if (typeof data === "string") return utf8.encode(data);
+	throw new TypeError(`normalizeToUint8Array: unsupported input ${describe(data)}; expected Uint8Array, ArrayBuffer, ArrayBufferView, Blob, or string`);
+}
+function describe(value) {
+	if (value === null) return "null";
+	const t = typeof value;
+	if (t !== "object") return t;
+	return value.constructor?.name ?? "object";
+}
+//#endregion
+//#region src/readable-streams.ts
+function toReadableStream(it) {
+	return new ReadableStream({ async pull(controller) {
+		let handled = false;
+		try {
+			while (true) {
+				const slot = await it.next();
+				if (!slot || slot.done) break;
+				const value = await slot.value;
+				controller.enqueue(value);
+			}
+		} catch (error) {
+			handled = true;
+			controller.error(error);
+		} finally {
+			if (!handled) controller.close();
+		}
+	} });
+}
+async function* fromReadableStream(stream) {
+	const reader = stream.getReader();
+	while (true) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		if (value !== void 0) yield value;
+	}
+}
+//#endregion
+//#region src/recieve-iterator.ts
+/**
+* Inverse of {@link sendIterator}: turns a sequence of `{done, value, error}`
+* chunks (delivered to the supplied callback by `installer`) into an async
+* generator.
+*
+* The `installer` is given a `deliver` function. It should call `deliver`
+* once for each incoming chunk and may return a cleanup callback that
+* runs when the consumer stops iterating.
+*/
+function recieveIterator(installer) {
+	return newAsyncGenerator((next, done) => {
+		const cleanup = installer(async (chunk = { done: true }) => {
+			const { done: isDone = true, value, error } = chunk;
+			if (error) return await done(error);
+			if (isDone) return await done();
+			return await next(value);
+		});
+		if (cleanup) return async () => {
+			await cleanup();
+		};
+	});
+}
+//#endregion
+//#region src/send-iterator.ts
+/**
+* Drain an async iterator into a sink that consumes one chunk at a time.
+*
+* Each yielded value becomes `{ done: false, value }`. Completion emits
+* `{ done: true }`. If the iterator throws, the error is caught and the
+* final `done` chunk carries it so the peer can rethrow on its side.
+*/
+async function sendIterator(send, it) {
+	let error;
+	try {
+		for await (const value of it) await send({
+			done: false,
+			value
+		});
+	} catch (err) {
+		error = err;
+	} finally {
+		await send({
+			done: true,
+			error
+		});
+	}
+}
+//#endregion
+//#region src/text.ts
+/** Decode Uint8Array chunks to string chunks via TextDecoder, handling split multi-byte characters. */
+async function* decodeText(input) {
+	const decoder = new TextDecoder("utf-8", { fatal: false });
+	for await (const chunk of input) {
+		const text = decoder.decode(chunk, { stream: true });
+		if (text) yield text;
+	}
+	const tail = decoder.decode();
+	if (tail) yield tail;
+}
+/** Encode string chunks to Uint8Array chunks via TextEncoder. */
+async function* encodeText(input) {
+	const encoder = new TextEncoder();
+	for await (const str of input) yield encoder.encode(str);
+}
+//#endregion
+//#region src/to-chunks.ts
+const DEFAULT_CHUNK_SIZE = 16 * 1024;
+/**
+* Curried `Duplex`-shaped transformer that splits incoming `Uint8Array`s into
+* chunks no larger than `size` bytes. Empty input chunks are skipped; small
+* input chunks pass through unchanged (zero-copy `subarray` views are used
+* when splitting, so no allocation per chunk).
+*
+* Use to respect transport MTUs before reaching `channel.send`. Reassembly on
+* the receive side is not needed — consumers iterate a continuous byte stream.
+*/
+function toChunks(size = DEFAULT_CHUNK_SIZE) {
+	if (!(Number.isInteger(size) && size > 0)) throw new RangeError(`toChunks: size must be a positive integer, got ${size}`);
+	return async function* (input) {
+		for await (const block of input) {
+			if (block.byteLength === 0) continue;
+			if (block.byteLength <= size) {
+				yield block;
+				continue;
+			}
+			let offset = 0;
+			while (offset < block.byteLength) {
+				const end = Math.min(offset + size, block.byteLength);
+				yield block.subarray(offset, end);
+				offset = end;
+			}
+		}
+	};
+}
+//#endregion
+export { TransportClosedError, collect, collectBytes, collectString, decodeJsonl, decodeText, deserializeError, emulateMux, encodeJsonl, encodeText, fromReadableStream, joinLines, map, newAsyncGenerator, normalizeToUint8Array, recieveIterator, sendIterator, serializeError, splitLines, toChunks, toReadableStream };