@oh-my-pi/pi-utils 11.1.0 → 11.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-utils",
-	"version": "11.1.0",
+	"version": "11.2.0",
 	"description": "Shared utilities for pi packages",
 	"type": "module",
 	"main": "./src/index.ts",
@@ -31,7 +31,7 @@
 		"winston-daily-rotate-file": "^5.0.0"
 	},
 	"devDependencies": {
-		"@types/node": "^25.2.0"
+		"@types/bun": "^1.3.8"
 	},
 	"engines": {
 		"bun": ">=1.3.7"

package/src/ptree.ts

@@ -1,125 +1,24 @@
 /**
  * Process tree management utilities for Bun subprocesses.
  *
- * Exposes the same public interface as the original implementation, but with
- * much less code:
  * - Track managed child processes for cleanup on shutdown (postmortem).
  * - Drain stdout/stderr to avoid subprocess pipe deadlocks.
  * - Cross-platform tree kill for process groups (Windows taskkill, Unix -pid).
  * - Convenience helpers: captureText / execText, AbortSignal, timeouts.
  */
-
 import type { Spawn, Subprocess } from "bun";
 import { terminate } from "./procmgr";
 
+type InMask = "pipe" | "ignore" | Buffer | Uint8Array | null;
+
 /** A Bun subprocess with stdout/stderr always piped (stdin may vary). */
 type PipedSubprocess<In extends InMask = InMask> = Subprocess<In, "pipe", "pipe">;
 
-/** Minimal push-based ReadableStream that buffers unboundedly (like the old queue). */
-function pushStream<T>() {
-	let controller!: ReadableStreamDefaultController<T>;
-	let closed = false;
-
-	const stream = new ReadableStream<T>({
-		start(c) {
-			controller = c;
-		},
-		cancel() {
-			closed = true; // consumer no longer cares; keep draining but drop
-		},
-	});
-
-	return {
-		stream,
-		push(value: T) {
-			if (closed) return;
-			try {
-				controller.enqueue(value);
-			} catch {
-				closed = true;
-			}
-		},
-		close() {
-			if (closed) return;
-			closed = true;
-			try {
-				controller.close();
-			} catch {}
-		},
-	};
-}
-
-const DONE = { done: true, value: undefined } as const;
-
-function abortRead(signal: AbortSignal) {
-	if (signal.aborted) return Promise.resolve(DONE);
-	const { promise, resolve } = Promise.withResolvers<typeof DONE>();
-	signal.addEventListener("abort", () => resolve(DONE), { once: true });
-	return promise;
-}
-
-/** Drain a ReadableStream into a pushStream, optionally tapping each chunk. */
-async function pump(
-	src: ReadableStream<Uint8Array>,
-	dst: ReturnType<typeof pushStream<Uint8Array>>,
-	opts?: { signal?: AbortSignal; onChunk?: (chunk: Uint8Array) => void; onFinally?: () => void },
-) {
-	const reader = src.getReader();
-	const stop = opts?.signal ? abortRead(opts.signal) : null;
-
-	try {
-		while (true) {
-			const r = stop ? await Promise.race([reader.read(), stop]) : await reader.read();
-			if (r.done) break;
-			if (!r.value) continue;
-			opts?.onChunk?.(r.value);
-			dst.push(r.value);
-		}
-	} catch {
-		// ignore; this module is "best effort" for streaming/cleanup
-	} finally {
-		try {
-			await reader.cancel();
-		} catch {}
-		try {
-			reader.releaseLock();
-		} catch {}
-		dst.close();
-		opts?.onFinally?.();
-	}
-}
-
-/**
- * Kill a child process and its descendents.
- * - Windows: taskkill /T, add /F on SIGKILL
- * - Unix: negative PID signals the process group
- */
-async function killChild(child: ChildProcess) {
-	await terminate({ target: child.proc });
-}
-
-/**
- * Options for waiting for process exit and capturing output.
- */
-export interface WaitOptions {
-	allowNonZero?: boolean;
-	allowAbort?: boolean;
-	stderr?: "full" | "buffer";
-}
-
-/**
- * Result from wait and captureText.
- */
-export interface ExecResult {
-	stdout: string;
-	stderr: string;
-	exitCode: number | null;
-	ok: boolean;
-	exitError?: Exception;
-}
+// ── Exceptions ───────────────────────────────────────────────────────────────
 
 /**
- * Base for all exceptions representing child process nonzero exit, killed, or cancellation.
+ * Base for all exceptions representing child process nonzero exit, killed, or
+ * cancellation.
  */
 export abstract class Exception extends Error {
 	constructor(
@@ -133,119 +32,117 @@ export abstract class Exception extends Error {
 	abstract get aborted(): boolean;
 }
 
-/**
- * Exception for nonzero exit codes (not cancellation).
- */
+/** Exception for nonzero exit codes (not cancellation). */
 export class NonZeroExitError extends Exception {
 	static readonly MAX_TRACE = 32 * 1024;
 
-	constructor(
-		public readonly exitCode: number,
-		public readonly stderr: string,
-	) {
+	constructor(exitCode: number, stderr: string) {
 		super(`Process exited with code ${exitCode}:\n${stderr}`, exitCode, stderr);
 	}
-	get aborted(): boolean {
+	get aborted() {
 		return false;
 	}
 }
 
-/**
- * Exception for explicit process abortion (via signal).
- */
+/** Exception for explicit process abortion (via signal). */
 export class AbortError extends Exception {
 	constructor(
 		public readonly reason: unknown,
 		stderr: string,
 	) {
-		const reasonString = reason instanceof Error ? reason.message : String(reason ?? "aborted");
-		super(`Operation cancelled: ${reasonString}`, -1, stderr);
+		const msg = reason instanceof Error ? reason.message : String(reason ?? "aborted");
+		super(`Operation cancelled: ${msg}`, -1, stderr);
 	}
-	get aborted(): boolean {
+	get aborted() {
 		return true;
 	}
 }
 
-/**
- * Exception for process timeout.
- */
+/** Exception for process timeout. */
 export class TimeoutError extends AbortError {
 	constructor(timeout: number, stderr: string) {
 		super(new Error(`Timed out after ${Math.round(timeout / 1000)}s`), stderr);
 	}
 }
 
-type InMask = "pipe" | "ignore" | Buffer | Uint8Array | null;
+// ── Wait / Exec types ────────────────────────────────────────────────────────
+
+/** Options for waiting for process exit and capturing output. */
+export interface WaitOptions {
+	allowNonZero?: boolean;
+	allowAbort?: boolean;
+	stderr?: "full" | "buffer";
+}
+
+/** Result from wait and exec. */
+export interface ExecResult {
+	stdout: string;
+	stderr: string;
+	exitCode: number | null;
+	ok: boolean;
+	exitError?: Exception;
+}
+
+// ── ChildProcess ─────────────────────────────────────────────────────────────
 
 /**
  * ChildProcess wraps a managed subprocess, capturing stderr tail, providing
  * cross-platform kill/detach logic plus AbortSignal integration.
+ *
+ * Stdout is exposed directly from the underlying Bun subprocess; consumers
+ * must read it (via text(), wait(), etc.) to prevent pipe deadlock.
+ * Stderr is eagerly drained into an internal buffer.
  */
 export class ChildProcess<In extends InMask = InMask> {
 	#nothrow = false;
-
-	#stderrBuffer = "";
+	#stderrTail = "";
+	#stderrChunks: Uint8Array[] = [];
 	#exitReason?: Exception;
 	#exitReasonPending?: Exception;
-
-	#stop = new AbortController();
-
-	#stdoutOut = pushStream<Uint8Array>();
-	#stderrOut = pushStream<Uint8Array>();
-
 	#stderrDone: Promise<void>;
 	#exited: Promise<number>;
+	#stderrStream?: ReadableStream<Uint8Array>;
 
-	constructor(public readonly proc: PipedSubprocess<In>) {
-		const { promise: stderrDone, resolve: resolveStderrDone } = Promise.withResolvers<void>();
-		this.#stderrDone = stderrDone;
-
-		// Drain stdout always -> expose our buffered stream to the user.
-		void pump(proc.stdout, this.#stdoutOut, { signal: this.#stop.signal }).catch(() => this.#stdoutOut.close());
-
-		// Drain stderr always -> expose stream + keep a bounded tail buffer.
-		const decoder = new TextDecoder();
+	constructor(
+		public readonly proc: PipedSubprocess<In>,
+		readonly exposeStderr: boolean,
+	) {
+		// Eagerly drain stderr into a truncated tail string + raw chunks.
+		const dec = new TextDecoder();
 		const trim = () => {
-			if (this.#stderrBuffer.length > NonZeroExitError.MAX_TRACE) {
-				this.#stderrBuffer = this.#stderrBuffer.slice(-NonZeroExitError.MAX_TRACE);
-			}
+			if (this.#stderrTail.length > NonZeroExitError.MAX_TRACE)
+				this.#stderrTail = this.#stderrTail.slice(-NonZeroExitError.MAX_TRACE);
 		};
-		void pump(proc.stderr, this.#stderrOut, {
-			signal: this.#stop.signal,
-			onChunk: chunk => {
-				this.#stderrBuffer += decoder.decode(chunk, { stream: true });
-				trim();
-			},
-			onFinally: () => {
-				this.#stderrBuffer += decoder.decode();
-				trim();
-				resolveStderrDone();
-			},
-		}).catch(() => {
+		let stderrStream = proc.stderr;
+		if (exposeStderr) {
+			const [teeStream, drainStream] = stderrStream.tee();
+			this.#stderrStream = teeStream;
+			stderrStream = drainStream;
+		}
+		this.#stderrDone = (async () => {
 			try {
-				this.#stderrBuffer += decoder.decode();
-				trim();
+				for await (const chunk of stderrStream) {
+					this.#stderrChunks.push(chunk);
+					this.#stderrTail += dec.decode(chunk, { stream: true });
+					trim();
+				}
 			} catch {}
-			this.#stderrOut.close();
-			resolveStderrDone();
-		});
+			this.#stderrTail += dec.decode();
+			trim();
+		})();
 
+		// Normalize Bun's exited promise into our exitReason / exitedCleanly model.
 		const { promise, resolve, reject } = Promise.withResolvers<number>();
 		this.#exited = promise;
 
-		// Normalize Bun's exited promise into our "exitReason / exitedCleanly" model.
 		proc.exited
 			.catch(() => null)
 			.then(async exitCode => {
-				// Stop pumping streams - process has exited, no more data coming
-				this.#stop.abort();
-
 				if (this.#exitReasonPending) {
 					this.#exitReason = this.#exitReasonPending;
 					reject(this.#exitReasonPending);
 					return;
 				}
-
 				if (exitCode === 0) {
 					resolve(0);
 					return;
@@ -254,54 +151,61 @@ export class ChildProcess<In extends InMask = InMask> {
 				await this.#stderrDone;
 
 				if (exitCode !== null) {
-					this.#exitReason = new NonZeroExitError(exitCode, this.#stderrBuffer);
+					this.#exitReason = new NonZeroExitError(exitCode, this.#stderrTail);
 					resolve(exitCode);
 					return;
 				}
 
 				const ex = this.proc.killed
-					? new AbortError(new Error("process killed"), this.#stderrBuffer)
-					: new NonZeroExitError(-1, this.#stderrBuffer);
-
+					? new AbortError(new Error("process killed"), this.#stderrTail)
+					: new NonZeroExitError(-1, this.#stderrTail);
 				this.#exitReason = ex;
 				reject(ex);
 			});
 	}
 
-	get pid(): number | undefined {
+	// ── Properties ───────────────────────────────────────────────────────
+
+	get pid() {
 		return this.proc.pid;
 	}
-	get exited(): Promise<number> {
+	get exited() {
 		return this.#exited;
 	}
-	get exitedCleanly(): Promise<number> {
-		if (this.#nothrow) return this.exited;
-		return this.exited.then(code => {
-			if (code !== 0) throw new NonZeroExitError(code, this.#stderrBuffer);
-			return code;
-		});
-	}
-	get exitCode(): number | null {
+	get exitCode() {
 		return this.proc.exitCode;
 	}
-	get exitReason(): Exception | undefined {
+	get exitReason() {
 		return this.#exitReason;
 	}
-	get killed(): boolean {
+	get killed() {
 		return this.proc.killed;
 	}
 	get stdin(): Bun.SpawnOptions.WritableToIO<In> {
 		return this.proc.stdin;
 	}
-	get stdout(): ReadableStream<Uint8Array> {
-		return this.#stdoutOut.stream;
+
+	/** Raw stdout stream. Must be consumed to prevent pipe deadlock. */
+	get stdout() {
+		return this.proc.stdout;
+	}
+
+	/** Optional stderr stream (only when requested in spawn options). */
+	get stderr() {
+		return this.#stderrStream;
 	}
-	get stderr(): ReadableStream<Uint8Array> {
-		return this.#stderrOut.stream;
+
+	get exitedCleanly(): Promise<number> {
+		if (this.#nothrow) return this.#exited;
+		return this.#exited.then(code => {
+			if (code !== 0) throw new NonZeroExitError(code, this.#stderrTail);
+			return code;
+		});
 	}
 
-	peekStderr(): string {
-		return this.#stderrBuffer;
+	/** Returns the truncated stderr tail (last 32KB). */
+	peekStderr() {
+		return this.#stderrTail;
 	}
 
 	nothrow(): this {
@@ -311,120 +215,116 @@ export class ChildProcess<In extends InMask = InMask> {
 
 	kill(reason?: Exception) {
 		if (reason && !this.#exitReasonPending) this.#exitReasonPending = reason;
-		this.#stop.abort();
-		if (this.proc.killed) return;
-		void killChild(this);
+		if (!this.proc.killed) void terminate({ target: this.proc });
+	}
+
+	// ── Output helpers ───────────────────────────────────────────────────
+
+	async text(): Promise<string> {
+		const p = new Response(this.stdout).text();
+		if (this.#nothrow) return p;
+		const [text] = await Promise.all([p, this.exitedCleanly]);
+		return text;
 	}
 
-	// Output helpers
 	async blob(): Promise<Blob> {
-		const blobPromise = new Response(this.stdout).blob();
-		if (this.#nothrow) return await blobPromise;
-		const [blob] = await Promise.all([blobPromise, this.exitedCleanly]);
+		const p = new Response(this.stdout).blob();
+		if (this.#nothrow) return p;
+		const [blob] = await Promise.all([p, this.exitedCleanly]);
 		return blob;
 	}
-	async text(): Promise<string> {
-		return (await this.blob()).text();
-	}
+
 	async json(): Promise<unknown> {
-		return await new Response(await this.blob()).json();
+		return new Response(this.stdout).json();
 	}
+
 	async arrayBuffer(): Promise<ArrayBuffer> {
-		return (await this.blob()).arrayBuffer();
+		return new Response(this.stdout).arrayBuffer();
 	}
+
 	async bytes(): Promise<Uint8Array> {
-		return new Uint8Array(await this.arrayBuffer());
+		return new Response(this.stdout).bytes();
 	}
 
-	async wait(options?: WaitOptions): Promise<ExecResult> {
-		const { allowNonZero = false, allowAbort = false, stderr: stderrMode = "buffer" } = options ?? {};
+	// ── Wait ─────────────────────────────────────────────────────────────
 
-		const stdoutPromise = new Response(this.stdout).text();
-		const stderrPromise =
+	async wait(opts?: WaitOptions): Promise<ExecResult> {
+		const { allowNonZero = false, allowAbort = false, stderr: stderrMode = "buffer" } = opts ?? {};
+
+		const stdoutP = new Response(this.stdout).text();
+		const stderrP =
 			stderrMode === "full"
-				? new Response(this.stderr).text()
-				: (async () => {
-						await Promise.allSettled([stdoutPromise, this.exited, this.#stderrDone]);
-						return this.peekStderr();
-					})();
+				? this.#stderrDone.then(() => new TextDecoder().decode(Buffer.concat(this.#stderrChunks)))
+				: this.#stderrDone.then(() => this.#stderrTail);
 
-		const [stdout, stderr] = await Promise.all([stdoutPromise, stderrPromise]);
+		const [stdout, stderr] = await Promise.all([stdoutP, stderrP]);
 
 		let exitError: Exception | undefined;
 		try {
-			await this.exited;
+			await this.#exited;
 		} catch (err) {
 			if (err instanceof Exception) exitError = err;
 			else throw err;
 		}
 
+		if (!exitError) exitError = this.exitReason;
+		if (!exitError && this.exitCode !== null && this.exitCode !== 0) {
+			exitError = new NonZeroExitError(this.exitCode, this.#stderrTail);
+		}
+
 		const exitCode = this.exitCode ?? (exitError && !exitError.aborted ? exitError.exitCode : null);
 		const ok = exitCode === 0;
 
 		if (exitError) {
-			if ((exitError.aborted && !allowAbort) || (!exitError.aborted && !allowNonZero)) {
-				throw exitError;
-			}
+			if ((exitError.aborted && !allowAbort) || (!exitError.aborted && !allowNonZero)) throw exitError;
 		}
 
 		return { stdout, stderr, exitCode, ok, exitError };
 	}
 
+	// ── Signal / timeout ─────────────────────────────────────────────────
+
 	attachSignal(signal: AbortSignal): void {
 		const onAbort = () => this.kill(new AbortError(signal.reason, "<cancelled>"));
 		if (signal.aborted) return void onAbort();
-
 		signal.addEventListener("abort", onAbort, { once: true });
-		this.#exited
-			.catch(() => {})
-			.finally(() => {
-				signal.removeEventListener("abort", onAbort);
-			});
-	}
-
-	attachTimeout(timeout: number): void {
-		if (timeout <= 0 || this.proc.killed) return;
-		void (async () => {
-			const timedOut = await Promise.race([
-				Bun.sleep(timeout).then(() => true),
-				this.proc.exited.then(
-					() => false,
-					() => false,
-				),
-			]);
-			if (timedOut) this.kill(new TimeoutError(timeout, this.#stderrBuffer));
-		})();
+		this.#exited.catch(() => {}).finally(() => signal.removeEventListener("abort", onAbort));
+	}
+
+	attachTimeout(ms: number): void {
+		if (ms <= 0 || this.proc.killed) return;
+		Promise.race([
+			Bun.sleep(ms).then(() => true),
+			this.proc.exited.then(
+				() => false,
+				() => false,
+			),
+		]).then(timedOut => {
+			if (timedOut) this.kill(new TimeoutError(ms, this.#stderrTail));
+		});
 	}
 
 	[Symbol.dispose](): void {
-		// Don't kill if process already exited - avoids race where dispose runs
-		// before the proc.exited.then() callback, causing spurious AbortError
 		if (this.proc.exitCode !== null) return;
-		this.kill(new AbortError("process disposed", this.#stderrBuffer));
+		this.kill(new AbortError("process disposed", this.#stderrTail));
 	}
 }
 
-/**
- * Options for cspawn (child spawn). Always pipes stdout/stderr, allows signal.
- */
+// ── Spawn / exec ─────────────────────────────────────────────────────────────
+
+/** Options for child spawn. Always pipes stdout/stderr. */
 type ChildSpawnOptions<In extends InMask = InMask> = Omit<
 	Spawn.SpawnOptions<In, "pipe", "pipe">,
 	"stdout" | "stderr" | "detached"
 > & {
-	/** AbortSignal to cancel the process */
 	signal?: AbortSignal;
-	/** Whether to detach the process */
 	detached?: boolean;
+	stderr?: "full" | null;
 };
 
-/**
- * Spawn a child process.
- * @param cmd - The command to spawn.
- * @param options - The options for the spawn.
- * @returns A ChildProcess instance.
- */
-export function spawn<In extends InMask = InMask>(cmd: string[], options?: ChildSpawnOptions<In>): ChildProcess<In> {
-	const { timeout = -1, signal, ...rest } = options ?? {};
+/** Spawn a child process with piped stdout/stderr. */
+export function spawn<In extends InMask = InMask>(cmd: string[], opts?: ChildSpawnOptions<In>): ChildProcess<In> {
+	const { timeout = -1, signal, stderr, ...rest } = opts ?? {};
 	const child = Bun.spawn(cmd, {
 		stdin: "ignore",
 		stdout: "pipe",
@@ -432,55 +332,55 @@ export function spawn<In extends InMask = InMask>(cmd: string[], options?: Child
 		windowsHide: true,
 		...rest,
 	});
-	const cproc = new ChildProcess(child);
-	if (signal) cproc.attachSignal(signal);
-	if (timeout > 0) cproc.attachTimeout(timeout);
-	return cproc;
+	const cp = new ChildProcess(child, stderr === "full");
+	if (signal) cp.attachSignal(signal);
+	if (timeout > 0) cp.attachTimeout(timeout);
+	return cp;
 }
 
-/**
- * Options for execText.
- */
-export interface ExecOptions extends Omit<ChildSpawnOptions, "stdin">, WaitOptions {
+/** Options for exec. */
+export interface ExecOptions extends Omit<ChildSpawnOptions, "stderr" | "stdin">, WaitOptions {
 	input?: string | Buffer | Uint8Array;
 }
 
-export async function exec(cmd: string[], options?: ExecOptions): Promise<ExecResult> {
-	const { input, stderr, allowAbort, allowNonZero, ...spawnOptions } = options ?? {};
+/** Spawn, wait, and return captured output. */
+export async function exec(cmd: string[], opts?: ExecOptions): Promise<ExecResult> {
+	const { input, stderr, allowAbort, allowNonZero, ...spawnOpts } = opts ?? {};
 	const stdin = typeof input === "string" ? Buffer.from(input) : input;
-	const resolvedOptions: ChildSpawnOptions = stdin === undefined ? spawnOptions : { ...spawnOptions, stdin };
-	using child = spawn(cmd, resolvedOptions);
-	return await child.wait({ stderr, allowAbort, allowNonZero });
+	const resolved: ChildSpawnOptions = stdin === undefined ? spawnOpts : { ...spawnOpts, stdin };
+	using child = spawn(cmd, resolved);
+	return child.wait({ stderr, allowAbort, allowNonZero });
 }
 
+// ── Signal combinators ───────────────────────────────────────────────────────
+
 type SignalValue = AbortSignal | number | null | undefined;
 
+/** Combine AbortSignals and timeout values into a single signal. */
 export function combineSignals(...signals: SignalValue[]): AbortSignal | undefined {
 	let timeout: number | undefined;
+
 	let n = 0;
 	for (let i = 0; i < signals.length; i++) {
 		const s = signals[i];
 		if (s instanceof AbortSignal) {
 			if (s.aborted) return s;
-			signals[n++] = s;
+			if (i !== n) signals[n] = s;
+			n++;
 		} else if (typeof s === "number" && s > 0) {
-			timeout = Math.min(timeout ?? s, s);
+			timeout = timeout === undefined ? s : Math.min(timeout, s);
 		}
 	}
-
-	// Create timeout signal.
 	if (timeout !== undefined) {
-		signals[n++] = AbortSignal.timeout(timeout);
+		signals[n] = AbortSignal.timeout(timeout);
+		n++;
 	}
-
-	// Single signal, ezpz.
-	const rawSignals = signals.slice(0, n) as AbortSignal[];
-	switch (rawSignals.length) {
+	switch (n) {
 		case 0:
 			return undefined;
 		case 1:
-			return rawSignals[0];
+			return signals[0] as AbortSignal;
 		default:
-			return AbortSignal.any(rawSignals);
+			return AbortSignal.any(signals.slice(0, n) as AbortSignal[]);
 	}
 }

package/src/stream.ts

@@ -1,3 +1,5 @@
+import { ArrayBufferSink } from "bun";
+
 /**
  * Sanitize binary output for display/storage.
  * Removes characters that crash string-width or cause display issues:
@@ -43,27 +45,57 @@ export function sanitizeText(text: string): string {
 /**
  * Create a transform stream that splits lines.
  */
-export function createSplitterStream(delimiter: string): TransformStream<string, string> {
-	let buf = "";
-	return new TransformStream<string, string>({
-		transform(chunk, controller) {
-			buf = buf ? `${buf}${chunk}` : chunk;
-
-			while (true) {
-				const nl = buf.indexOf(delimiter);
-				if (nl === -1) break;
-				controller.enqueue(buf.slice(0, nl));
-				buf = buf.slice(nl + delimiter.length);
+export function createSplitterStream<T>(options: {
+	newLine?: boolean;
+	mapFn: (chunk: Uint8Array) => T;
+}): TransformStream<Uint8Array, T> {
+	const { newLine = false, mapFn } = options;
+	const LF = 0x0a;
+	const sink = new Bun.ArrayBufferSink();
+	sink.start({ asUint8Array: true, stream: true, highWaterMark: 4096 });
+	let pending = false; // whether the sink has unflushed data
+
+	return new TransformStream<Uint8Array, T>({
+		transform(chunk, ctrl) {
+			let pos = 0;
+
+			while (pos < chunk.length) {
+				const nl = chunk.indexOf(LF, pos);
+				if (nl === -1) {
+					sink.write(chunk.subarray(pos));
+					pending = true;
+					break;
+				}
+
+				const slice = chunk.subarray(pos, newLine ? nl + 1 : nl);
+
+				if (pending) {
+					if (slice.length > 0) sink.write(slice);
+					ctrl.enqueue(mapFn(sink.flush() as Uint8Array));
+					pending = false;
+				} else {
+					ctrl.enqueue(mapFn(slice));
+				}
+				pos = nl + 1;
 			}
 		},
-		flush(controller) {
-			if (buf) {
-				controller.enqueue(buf);
+		flush(ctrl) {
+			if (pending) {
+				const tail = sink.end() as Uint8Array;
+				if (tail.length > 0) ctrl.enqueue(mapFn(tail));
 			}
 		},
 	});
 }
 
+export function createTextLineSplitter(sanitize = false): TransformStream<Uint8Array, string> {
+	const dec = new TextDecoder("utf-8", { ignoreBOM: true, fatal: true });
+	if (sanitize) {
+		return createSplitterStream({ mapFn: chunk => sanitizeText(dec.decode(chunk)) });
+	}
+	return createSplitterStream({ mapFn: dec.decode.bind(dec) });
+}
+
 /**
  * Create a transform stream that sanitizes text.
  */
@@ -82,152 +114,132 @@ export function createTextDecoderStream(): TransformStream<Uint8Array, string> {
 	return new TextDecoderStream() as TransformStream<Uint8Array, string>;
 }
 
-/**
- * Read stream line-by-line
- *
- * @param delimiter Line delimiter (default: "\n")
- */
-export function readLines(stream: ReadableStream<Uint8Array>, delimiter = "\n"): AsyncIterable<string> {
-	return stream.pipeThrough(createTextDecoderStream()).pipeThrough(createSplitterStream(delimiter));
-}
-
 // =============================================================================
 // SSE (Server-Sent Events)
 // =============================================================================
 
-/**
- * Parsed SSE event.
- */
-export interface SseEvent {
-	/** Event type (from `event:` field, default: "message") */
-	event: string;
-	/** Event data (from `data:` field(s), joined with newlines) */
-	data: string;
-	/** Event ID (from `id:` field) */
-	id?: string;
-	/** Retry interval in ms (from `retry:` field) */
-	retry?: number;
-}
+const LF = 0x0a;
+const CR = 0x0d;
+const SPACE = 0x20;
 
-/**
- * Parse a single SSE event block (lines between blank lines).
- * Returns null if the block contains no data.
- */
-export function parseSseEvent(block: string): SseEvent | null {
-	const lines = block.split("\n");
-	let event = "message";
-	const dataLines: string[] = [];
-	let id: string | undefined;
-	let retry: number | undefined;
-
-	for (const line of lines) {
-		// Comments start with ':'
-		if (line.startsWith(":")) continue;
-
-		const colonIdx = line.indexOf(":");
-		if (colonIdx === -1) continue;
-
-		const field = line.slice(0, colonIdx);
-		// Value starts after colon, with optional leading space trimmed
-		let value = line.slice(colonIdx + 1);
-		if (value.startsWith(" ")) value = value.slice(1);
-
-		switch (field) {
-			case "event":
-				event = value;
-				break;
-			case "data":
-				dataLines.push(value);
-				break;
-			case "id":
-				id = value;
-				break;
-			case "retry": {
-				const n = parseInt(value, 10);
-				if (!Number.isNaN(n)) retry = n;
-				break;
-			}
-		}
-	}
+// "data:" = [0x64, 0x61, 0x74, 0x61, 0x3a]
+const DATA_0 = 0x64; // d
+const DATA_1 = 0x61; // a
+const DATA_2 = 0x74; // t
+const DATA_3 = 0x61; // a
+const DATA_4 = 0x3a; // :
 
-	if (dataLines.length === 0) return null;
+// "[DONE]" = [0x5b, 0x44, 0x4f, 0x4e, 0x45, 0x5d]
+const DONE = Uint8Array.from([0x5b, 0x44, 0x4f, 0x4e, 0x45, 0x5d]);
 
-	return {
-		event,
-		data: dataLines.join("\n"),
-		id,
-		retry,
-	};
+function isDone(buf: Uint8Array, start: number, end: number): boolean {
+	if (end - start !== 6) return false;
+	for (let i = 0; i < 6; i++) {
+		if (buf[start + i] !== DONE[i]) return false;
+	}
+	return true;
 }
 
 /**
- * Read SSE events from a stream.
- *
- * Handles the SSE wire format:
- * - Events separated by blank lines
- * - Fields: event, data, id, retry
- * - Comments (lines starting with :) are ignored
- * - Multiple data: lines are joined with newlines
+ * Stream parsed JSON objects from SSE `data:` lines.
  *
  * @example
  * ```ts
- * for await (const event of readSseEvents(response.body)) {
- *   if (event.data === "[DONE]") break;
- *   const payload = JSON.parse(event.data);
- *   console.log(event.event, payload);
+ * for await (const obj of readSseJson(response.body!)) {
+ *   console.log(obj);
  * }
  * ```
  */
-export async function* readSseEvents(stream: ReadableStream<Uint8Array>): AsyncGenerator<SseEvent, void, undefined> {
-	const blockLines: string[] = [];
-
-	for await (const rawLine of readLines(stream)) {
-		const line = rawLine.replace(/\r$/, "");
-		if (line === "") {
-			if (blockLines.length > 0) {
-				const event = parseSseEvent(blockLines.join("\n"));
-				if (event) yield event;
-				blockLines.length = 0;
+export async function* readSseJson<T>(
+	stream: ReadableStream<Uint8Array>,
+	abortSignal?: AbortSignal,
+): AsyncGenerator<T> {
+	const sink = new ArrayBufferSink();
+	sink.start({ asUint8Array: true, stream: true, highWaterMark: 4096 });
+	let pending = false;
+
+	// pipeThrough with { signal } makes the stream abort-aware: the pipe
+	// cancels the source and errors the output when the signal fires,
+	// so for-await-of exits cleanly without manual reader/listener management.
+	const source = abortSignal ? stream.pipeThrough(new TransformStream(), { signal: abortSignal }) : stream;
+
+	try {
+		for await (const chunk of source) {
+			let pos = 0;
+			while (pos < chunk.length) {
+				const nl = chunk.indexOf(LF, pos);
+				if (nl === -1) {
+					sink.write(chunk.subarray(pos));
+					pending = true;
+					break;
+				}
+
+				let line: Uint8Array;
+				if (pending) {
+					if (nl > pos) sink.write(chunk.subarray(pos, nl));
+					line = sink.flush() as Uint8Array;
+					pending = false;
+				} else {
+					line = chunk.subarray(pos, nl);
+				}
+				pos = nl + 1;
+
+				// Strip trailing CR, skip blank/short lines.
+				const len = line.length > 0 && line[line.length - 1] === CR ? line.length - 1 : line.length;
+				if (len < 6) continue; // "data:" + at least 1 byte
+
+				// Check "data:" prefix.
+				if (
+					line[0] !== DATA_0 ||
+					line[1] !== DATA_1 ||
+					line[2] !== DATA_2 ||
+					line[3] !== DATA_3 ||
+					line[4] !== DATA_4
+				)
+					continue;
+
+				// Payload start — skip optional space after colon.
+				const pStart = line[5] === SPACE ? 6 : 5;
+				if (pStart >= len) continue;
+				if (isDone(line, pStart, len)) return;
+
+				// Build payload + \n for JSONL.parse.
+				const pLen = len - pStart;
+				const buf = new Uint8Array(pLen + 1);
+				buf.set(line.subarray(pStart, len));
+				buf[pLen] = LF;
+
+				const [parsed] = Bun.JSONL.parse(buf);
+				if (parsed !== undefined) yield parsed as T;
 			}
-			continue;
 		}
-
-		blockLines.push(line);
+	} catch (err) {
+		// Abort errors are expected — just stop the generator.
+		if (abortSignal?.aborted) return;
+		throw err;
 	}
 
-	if (blockLines.length > 0) {
-		const event = parseSseEvent(blockLines.join("\n"));
-		if (event) yield event;
-	}
-}
-
-/**
- * Read SSE data payloads from a stream, parsing JSON automatically.
- *
- * Convenience wrapper over readSseEvents that:
- * - Skips [DONE] markers
- * - Parses JSON data
- * - Optionally filters by event type
- *
- * @example
- * ```ts
- * for await (const data of readSseData<ChatChunk>(response.body)) {
- *   console.log(data.choices[0].delta);
- * }
- * ```
- */
-export async function* readSseData<T = unknown>(
-	stream: ReadableStream<Uint8Array>,
-	eventType?: string,
-): AsyncGenerator<T, void, undefined> {
-	for await (const event of readSseEvents(stream)) {
-		if (eventType && event.event !== eventType) continue;
-		if (event.data === "[DONE]") continue;
-
-		try {
-			yield JSON.parse(event.data) as T;
-		} catch {
-			// Skip malformed JSON
+	// Trailing line without final newline.
+	if (pending) {
+		const tail = sink.end() as Uint8Array;
+		const len = tail.length > 0 && tail[tail.length - 1] === CR ? tail.length - 1 : tail.length;
+		if (
+			len >= 6 &&
+			tail[0] === DATA_0 &&
+			tail[1] === DATA_1 &&
+			tail[2] === DATA_2 &&
+			tail[3] === DATA_3 &&
+			tail[4] === DATA_4
+		) {
+			const pStart = tail[5] === SPACE ? 6 : 5;
+			if (pStart < len && !isDone(tail, pStart, len)) {
+				const pLen = len - pStart;
+				const buf = new Uint8Array(pLen + 1);
+				buf.set(tail.subarray(pStart, len));
+				buf[pLen] = LF;
+				const [parsed] = Bun.JSONL.parse(buf);
+				if (parsed !== undefined) yield parsed as T;
+			}
 		}
 	}
 }