@nextrush/stream 1.0.0-beta.0

package/src/stream-controller.ts

@@ -0,0 +1,184 @@
+/**
+ * @nextrush/stream - StreamController
+ *
+ * The single internal component that owns streaming lifecycle: abort tracking,
+ * enqueue, cooperative backpressure, source normalization, and close/cleanup.
+ * The protocol writers ({@link TextWriter}/{@link SSEWriter}/{@link NDJSONWriter})
+ * are thin formatting wrappers over this — they never touch lifecycle directly.
+ *
+ * See docs/RFC/request-data/003-stream.md §5.
+ *
+ * @packageDocumentation
+ */
+
+import { StreamAbortedError } from './errors';
+
+/** Shared encoder — avoids per-call allocation. */
+const TEXT_ENCODER = new TextEncoder();
+
+/**
+ * Owns the underlying `ReadableStream` controller and all streaming lifecycle.
+ *
+ * @remarks
+ * One instance per streaming response, shared by exactly one writer.
+ */
+export class StreamController {
+  /** Fires when the client disconnects. */
+  readonly signal: AbortSignal;
+
+  private _rsController: ReadableStreamDefaultController<Uint8Array> | null = null;
+  private _pullResolve: (() => void) | null = null;
+  private _abortCallbacks: (() => void)[] = [];
+  private _closed = false;
+
+  constructor(signal: AbortSignal) {
+    this.signal = signal;
+    if (!signal.aborted) {
+      signal.addEventListener('abort', this._onAbort, { once: true });
+    }
+  }
+
+  /** `true` once the client has disconnected. */
+  get aborted(): boolean {
+    return this.signal.aborted;
+  }
+
+  /**
+   * @internal Wire the underlying `ReadableStream` controller. Called once from
+   * the stream's `start()`.
+   */
+  attach(controller: ReadableStreamDefaultController<Uint8Array>): void {
+    this._rsController = controller;
+  }
+
+  /**
+   * @internal Release a pending backpressure wait. Called from the stream's
+   * `pull()` when the consumer is ready for more data.
+   */
+  onPull(): void {
+    this._resolvePull();
+  }
+
+  /**
+   * Register a cleanup callback invoked once when the client disconnects.
+   * Invoked immediately if already aborted.
+   */
+  onAbort(fn: () => void): void {
+    if (this.aborted) {
+      fn();
+      return;
+    }
+    this._abortCallbacks.push(fn);
+  }
+
+  /**
+   * Enqueue raw bytes, applying cooperative backpressure.
+   *
+   * @throws StreamAbortedError if the client has disconnected.
+   */
+  async enqueue(chunk: Uint8Array): Promise<void> {
+    if (this.aborted) throw new StreamAbortedError();
+    const controller = this._rsController;
+    if (!controller) {
+      throw new Error('StreamController is not attached to a stream.');
+    }
+    controller.enqueue(chunk);
+    // Backpressure: if the consumer's buffer is full, wait until the next pull().
+    if ((controller.desiredSize ?? 1) <= 0) {
+      await this._waitForPull();
+      // Re-check via the signal directly: the client may have disconnected
+      // while we were parked on backpressure.
+      if (this.signal.aborted) throw new StreamAbortedError();
+    }
+  }
+
+  /** Encode a UTF-8 string and enqueue it. */
+  enqueueText(text: string): Promise<void> {
+    return this.enqueue(TEXT_ENCODER.encode(text));
+  }
+
+  /**
+   * Normalize any accepted source shape to a single async-iterator.
+   *
+   * @remarks
+   * The one and only place that branches on source type. `AsyncIterable`
+   * (including Node `Readable`, which implements `Symbol.asyncIterator`) is used
+   * directly; a bare Web `ReadableStream` is adapted via its reader.
+   */
+  normalize<T>(source: AsyncIterable<T> | ReadableStream<T>): AsyncIterator<T> {
+    if (Symbol.asyncIterator in source) {
+      return (source as AsyncIterable<T>)[Symbol.asyncIterator]();
+    }
+    const reader = (source as ReadableStream<T>).getReader();
+    return {
+      async next(): Promise<IteratorResult<T>> {
+        const { done, value } = await reader.read();
+        return done
+          ? { done: true, value: undefined as never }
+          : { done: false, value };
+      },
+      async return(): Promise<IteratorResult<T>> {
+        await reader.cancel();
+        return { done: true, value: undefined as never };
+      },
+    };
+  }
+
+  /** Close the underlying stream cleanly. Idempotent. */
+  close(): void {
+    if (this._closed) return;
+    this._closed = true;
+    this.signal.removeEventListener('abort', this._onAbort);
+    this._resolvePull();
+    if (this._rsController) {
+      try {
+        this._rsController.close();
+      } catch {
+        // Already closed or errored by the consumer — nothing to do.
+      }
+    }
+  }
+
+  /** Error the underlying stream. Idempotent. */
+  error(err: unknown): void {
+    if (this._closed) return;
+    this._closed = true;
+    this.signal.removeEventListener('abort', this._onAbort);
+    this._resolvePull();
+    if (this._rsController) {
+      try {
+        this._rsController.error(err);
+      } catch {
+        // Already closed or errored — nothing to do.
+      }
+    }
+  }
+
+  private _onAbort = (): void => {
+    // Unblock any writer waiting on backpressure so it observes the abort.
+    this._resolvePull();
+    const callbacks = this._abortCallbacks;
+    this._abortCallbacks = [];
+    for (const cb of callbacks) {
+      try {
+        cb();
+      } catch {
+        // Cleanup callbacks must not break the abort path.
+      }
+    }
+  };
+
+  private _resolvePull(): void {
+    const resolve = this._pullResolve;
+    if (resolve) {
+      this._pullResolve = null;
+      resolve();
+    }
+  }
+
+  private _waitForPull(): Promise<void> {
+    return new Promise<void>((resolve) => {
+      this._pullResolve = resolve;
+    });
+  }
+}

package/src/writers.ts

@@ -0,0 +1,109 @@
+/**
+ * @nextrush/stream - Protocol writers
+ *
+ * Thin formatting wrappers over {@link StreamController}. Each writer differs
+ * only in how `write()` encodes its protocol's native unit and how `consume()`
+ * maps a raw chunk. All lifecycle (abort, backpressure, close) lives in the
+ * controller — not here.
+ *
+ * See docs/RFC/request-data/003-stream.md §5, §7.
+ *
+ * @packageDocumentation
+ */
+
+import type {
+  NDJSONStreamWriter,
+  SSEEvent,
+  SSEStreamWriter,
+  StreamSource,
+  TextStreamWriter,
+} from '@nextrush/types';
+import { formatSSE } from './sse-format';
+import type { StreamController } from './stream-controller';
+
+/** Decodes byte chunks to text for protocols whose payload is textual (SSE). */
+const TEXT_DECODER = new TextDecoder();
+
+/**
+ * Shared base: exposes the controller's abort surface and drives `consume()`.
+ *
+ * @typeParam T - The unit type each source chunk is mapped to before `write()`.
+ */
+abstract class BaseWriter<T> {
+  constructor(protected readonly controller: StreamController) {}
+
+  get aborted(): boolean {
+    return this.controller.aborted;
+  }
+
+  get signal(): AbortSignal {
+    return this.controller.signal;
+  }
+
+  onAbort(fn: () => void): void {
+    this.controller.onAbort(fn);
+  }
+
+  /** Protocol-specific write of one native unit. */
+  abstract write(value: T): Promise<void>;
+
+  /** Map one raw source chunk to this protocol's native unit. */
+  protected abstract mapChunk(chunk: unknown): T;
+
+  /**
+   * Consume an existing producer into this response. Single normalization path;
+   * stops and throws `StreamAbortedError` if the client disconnects mid-consume.
+   */
+  async consume(source: StreamSource<unknown>): Promise<void> {
+    const iterator = this.controller.normalize(source);
+    try {
+      for (;;) {
+        const result: IteratorResult<unknown> = await iterator.next();
+        if (result.done) return;
+        await this.write(this.mapChunk(result.value));
+      }
+    } finally {
+      await iterator.return?.(undefined);
+    }
+  }
+}
+
+/** Raw text/byte writer for `ctx.stream()`. */
+export class TextWriter
+  extends BaseWriter<string | Uint8Array>
+  implements TextStreamWriter
+{
+  write(chunk: string | Uint8Array): Promise<void> {
+    return typeof chunk === 'string'
+      ? this.controller.enqueueText(chunk)
+      : this.controller.enqueue(chunk);
+  }
+
+  protected mapChunk(chunk: unknown): string | Uint8Array {
+    return chunk as string | Uint8Array;
+  }
+}
+
+/** Server-Sent Events writer for `ctx.sse()`. */
+export class SSEWriter extends BaseWriter<SSEEvent> implements SSEStreamWriter {
+  write(event: SSEEvent): Promise<void> {
+    return this.controller.enqueueText(formatSSE(event));
+  }
+
+  protected mapChunk(chunk: unknown): SSEEvent {
+    // A consumed producer yields raw text/bytes; wrap each as an SSE `data` event.
+    const data = chunk instanceof Uint8Array ? TEXT_DECODER.decode(chunk) : (chunk as string);
+    return { data };
+  }
+}
+
+/** Newline-delimited JSON writer for `ctx.ndjson()`. */
+export class NDJSONWriter extends BaseWriter<unknown> implements NDJSONStreamWriter {
+  write(value: unknown): Promise<void> {
+    return this.controller.enqueueText(`${JSON.stringify(value)}\n`);
+  }
+
+  protected mapChunk(chunk: unknown): unknown {
+    return chunk;
+  }
+}