@nextrush/stream 1.0.0-beta.0

package/dist/index.js

@@ -0,0 +1,339 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/errors.ts
+var StreamAbortedError = class _StreamAbortedError extends Error {
+  static {
+    __name(this, "StreamAbortedError");
+  }
+  name = "StreamAbortedError";
+  constructor() {
+    super("Cannot write to stream: client has disconnected.");
+    Object.setPrototypeOf(this, _StreamAbortedError.prototype);
+  }
+};
+
+// src/sse-format.ts
+function formatSSE(event) {
+  let out = "";
+  if (event.event !== void 0) {
+    out += `event: ${sanitizeField(event.event)}
+`;
+  }
+  if (event.id !== void 0) {
+    out += `id: ${sanitizeField(event.id)}
+`;
+  }
+  if (event.retry !== void 0) {
+    out += `retry: ${String(Math.trunc(event.retry))}
+`;
+  }
+  const data = typeof event.data === "string" ? event.data : JSON.stringify(event.data);
+  for (const line of data.split("\n")) {
+    out += `data: ${line.replace(/\r$/, "")}
+`;
+  }
+  out += "\n";
+  return out;
+}
+__name(formatSSE, "formatSSE");
+function sanitizeField(value) {
+  return value.replace(/[\r\n]/g, "");
+}
+__name(sanitizeField, "sanitizeField");
+
+// src/stream-controller.ts
+var TEXT_ENCODER = new TextEncoder();
+var StreamController = class {
+  static {
+    __name(this, "StreamController");
+  }
+  /** Fires when the client disconnects. */
+  signal;
+  _rsController = null;
+  _pullResolve = null;
+  _abortCallbacks = [];
+  _closed = false;
+  constructor(signal) {
+    this.signal = signal;
+    if (!signal.aborted) {
+      signal.addEventListener("abort", this._onAbort, {
+        once: true
+      });
+    }
+  }
+  /** `true` once the client has disconnected. */
+  get aborted() {
+    return this.signal.aborted;
+  }
+  /**
+  * @internal Wire the underlying `ReadableStream` controller. Called once from
+  * the stream's `start()`.
+  */
+  attach(controller) {
+    this._rsController = controller;
+  }
+  /**
+  * @internal Release a pending backpressure wait. Called from the stream's
+  * `pull()` when the consumer is ready for more data.
+  */
+  onPull() {
+    this._resolvePull();
+  }
+  /**
+  * Register a cleanup callback invoked once when the client disconnects.
+  * Invoked immediately if already aborted.
+  */
+  onAbort(fn) {
+    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) {
+    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);
+    if ((controller.desiredSize ?? 1) <= 0) {
+      await this._waitForPull();
+      if (this.signal.aborted) throw new StreamAbortedError();
+    }
+  }
+  /** Encode a UTF-8 string and enqueue it. */
+  enqueueText(text) {
+    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(source) {
+    if (Symbol.asyncIterator in source) {
+      return source[Symbol.asyncIterator]();
+    }
+    const reader = source.getReader();
+    return {
+      async next() {
+        const { done, value } = await reader.read();
+        return done ? {
+          done: true,
+          value: void 0
+        } : {
+          done: false,
+          value
+        };
+      },
+      async return() {
+        await reader.cancel();
+        return {
+          done: true,
+          value: void 0
+        };
+      }
+    };
+  }
+  /** Close the underlying stream cleanly. Idempotent. */
+  close() {
+    if (this._closed) return;
+    this._closed = true;
+    this.signal.removeEventListener("abort", this._onAbort);
+    this._resolvePull();
+    if (this._rsController) {
+      try {
+        this._rsController.close();
+      } catch {
+      }
+    }
+  }
+  /** Error the underlying stream. Idempotent. */
+  error(err) {
+    if (this._closed) return;
+    this._closed = true;
+    this.signal.removeEventListener("abort", this._onAbort);
+    this._resolvePull();
+    if (this._rsController) {
+      try {
+        this._rsController.error(err);
+      } catch {
+      }
+    }
+  }
+  _onAbort = /* @__PURE__ */ __name(() => {
+    this._resolvePull();
+    const callbacks = this._abortCallbacks;
+    this._abortCallbacks = [];
+    for (const cb of callbacks) {
+      try {
+        cb();
+      } catch {
+      }
+    }
+  }, "_onAbort");
+  _resolvePull() {
+    const resolve = this._pullResolve;
+    if (resolve) {
+      this._pullResolve = null;
+      resolve();
+    }
+  }
+  _waitForPull() {
+    return new Promise((resolve) => {
+      this._pullResolve = resolve;
+    });
+  }
+};
+
+// src/writers.ts
+var TEXT_DECODER = new TextDecoder();
+var BaseWriter = class BaseWriter2 {
+  static {
+    __name(this, "BaseWriter");
+  }
+  controller;
+  constructor(controller) {
+    this.controller = controller;
+  }
+  get aborted() {
+    return this.controller.aborted;
+  }
+  get signal() {
+    return this.controller.signal;
+  }
+  onAbort(fn) {
+    this.controller.onAbort(fn);
+  }
+  /**
+  * Consume an existing producer into this response. Single normalization path;
+  * stops and throws `StreamAbortedError` if the client disconnects mid-consume.
+  */
+  async consume(source) {
+    const iterator = this.controller.normalize(source);
+    try {
+      for (; ; ) {
+        const result = await iterator.next();
+        if (result.done) return;
+        await this.write(this.mapChunk(result.value));
+      }
+    } finally {
+      await iterator.return?.(void 0);
+    }
+  }
+};
+var TextWriter = class extends BaseWriter {
+  static {
+    __name(this, "TextWriter");
+  }
+  write(chunk) {
+    return typeof chunk === "string" ? this.controller.enqueueText(chunk) : this.controller.enqueue(chunk);
+  }
+  mapChunk(chunk) {
+    return chunk;
+  }
+};
+var SSEWriter = class extends BaseWriter {
+  static {
+    __name(this, "SSEWriter");
+  }
+  write(event) {
+    return this.controller.enqueueText(formatSSE(event));
+  }
+  mapChunk(chunk) {
+    const data = chunk instanceof Uint8Array ? TEXT_DECODER.decode(chunk) : chunk;
+    return {
+      data
+    };
+  }
+};
+var NDJSONWriter = class extends BaseWriter {
+  static {
+    __name(this, "NDJSONWriter");
+  }
+  write(value) {
+    return this.controller.enqueueText(`${JSON.stringify(value)}
+`);
+  }
+  mapChunk(chunk) {
+    return chunk;
+  }
+};
+
+// src/run.ts
+var CONTENT_TYPE = {
+  text: "text/plain; charset=utf-8",
+  sse: "text/event-stream; charset=utf-8",
+  ndjson: "application/x-ndjson; charset=utf-8"
+};
+function runStream(ctx, contentType, makeWriter, run, extraHeaders) {
+  ctx.set("Content-Type", contentType);
+  if (extraHeaders) {
+    for (const [field, value] of Object.entries(extraHeaders)) {
+      ctx.set(field, value);
+    }
+  }
+  const controller = new StreamController(ctx.signal);
+  const readable = new ReadableStream({
+    start(rsController) {
+      controller.attach(rsController);
+      const writer = makeWriter(controller);
+      void (async () => {
+        try {
+          await run(writer);
+          controller.close();
+        } catch (err) {
+          if (err instanceof StreamAbortedError) {
+            controller.close();
+          } else {
+            controller.error(err);
+          }
+        }
+      })();
+    },
+    pull() {
+      controller.onPull();
+    },
+    cancel() {
+      controller.onPull();
+    }
+  });
+  return ctx.sendStream(readable);
+}
+__name(runStream, "runStream");
+function runTextStream(ctx, run) {
+  return runStream(ctx, CONTENT_TYPE.text, (c) => new TextWriter(c), run);
+}
+__name(runTextStream, "runTextStream");
+function runSSEStream(ctx, run) {
+  return runStream(ctx, CONTENT_TYPE.sse, (c) => new SSEWriter(c), run, {
+    "Cache-Control": "no-cache"
+  });
+}
+__name(runSSEStream, "runSSEStream");
+function runNDJSONStream(ctx, run) {
+  return runStream(ctx, CONTENT_TYPE.ndjson, (c) => new NDJSONWriter(c), run);
+}
+__name(runNDJSONStream, "runNDJSONStream");
+export {
+  NDJSONWriter,
+  SSEWriter,
+  StreamAbortedError,
+  StreamController,
+  TextWriter,
+  formatSSE,
+  runNDJSONStream,
+  runSSEStream,
+  runTextStream
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/sse-format.ts","../src/stream-controller.ts","../src/writers.ts","../src/run.ts"],"sourcesContent":["/**\n * @nextrush/stream - Errors\n *\n * @packageDocumentation\n */\n\n/**\n * Thrown by a writer's `write()`/`consume()` once the client has disconnected.\n *\n * @remarks\n * This is a control-flow signal, not an HTTP error — the client is already gone,\n * so nothing is sent to them. `ctx.stream()`/`ctx.sse()`/`ctx.ndjson()` catch it\n * at the top-level boundary and treat it as a clean, expected shutdown: it is\n * never logged as a failure and never re-thrown to the caller.\n *\n * A handler that wants to distinguish \"I was cancelled\" from \"something broke\"\n * can catch this explicitly; a handler that does nothing special still cannot\n * produce a silently-corrupted response, because the throw happens before any\n * partial write.\n */\nexport class StreamAbortedError extends Error {\n  override readonly name = 'StreamAbortedError';\n\n  constructor() {\n    super('Cannot write to stream: client has disconnected.');\n    // Restore prototype chain for reliable `instanceof` after transpilation.\n    Object.setPrototypeOf(this, StreamAbortedError.prototype);\n  }\n}\n","/**\n * @nextrush/stream - Server-Sent Events wire formatting\n *\n * @packageDocumentation\n */\n\nimport type { SSEEvent } from '@nextrush/types';\n\n/**\n * Format a single {@link SSEEvent} into its `text/event-stream` wire representation.\n *\n * @remarks\n * Handles every framing detail so handlers never touch it:\n * - `data`: objects are `JSON.stringify`'d; strings are sent verbatim.\n * - Multi-line `data` is split into one `data:` line per line, per the SSE spec\n *   (a raw `\\n` inside a single `data:` field would corrupt the stream).\n * - Optional `event:`, `id:`, and `retry:` fields precede the data lines.\n * - The event is terminated by a blank line (`\\n\\n`).\n *\n * Carriage returns and newlines are stripped from `event`/`id` to prevent\n * field injection (a `\\n` in `id` would otherwise start a new field/event).\n *\n * @param event - The event to format.\n * @returns The event as an SSE wire-format string.\n */\nexport function formatSSE(event: SSEEvent): string {\n  let out = '';\n\n  if (event.event !== undefined) {\n    out += `event: ${sanitizeField(event.event)}\\n`;\n  }\n  if (event.id !== undefined) {\n    out += `id: ${sanitizeField(event.id)}\\n`;\n  }\n  if (event.retry !== undefined) {\n    out += `retry: ${String(Math.trunc(event.retry))}\\n`;\n  }\n\n  const data = typeof event.data === 'string' ? event.data : JSON.stringify(event.data);\n  // Per SSE spec, each line of the payload is its own `data:` field.\n  // Split on \\n; also strip any \\r so CRLF sources don't leak a stray \\r.\n  for (const line of data.split('\\n')) {\n    out += `data: ${line.replace(/\\r$/, '')}\\n`;\n  }\n\n  // Blank line terminates the event.\n  out += '\\n';\n  return out;\n}\n\n/** Strip CR/LF so a field value cannot inject additional SSE fields or events. */\nfunction sanitizeField(value: string): string {\n  return value.replace(/[\\r\\n]/g, '');\n}\n","/**\n * @nextrush/stream - StreamController\n *\n * The single internal component that owns streaming lifecycle: abort tracking,\n * enqueue, cooperative backpressure, source normalization, and close/cleanup.\n * The protocol writers ({@link TextWriter}/{@link SSEWriter}/{@link NDJSONWriter})\n * are thin formatting wrappers over this — they never touch lifecycle directly.\n *\n * See docs/RFC/request-data/003-stream.md §5.\n *\n * @packageDocumentation\n */\n\nimport { StreamAbortedError } from './errors';\n\n/** Shared encoder — avoids per-call allocation. */\nconst TEXT_ENCODER = new TextEncoder();\n\n/**\n * Owns the underlying `ReadableStream` controller and all streaming lifecycle.\n *\n * @remarks\n * One instance per streaming response, shared by exactly one writer.\n */\nexport class StreamController {\n  /** Fires when the client disconnects. */\n  readonly signal: AbortSignal;\n\n  private _rsController: ReadableStreamDefaultController<Uint8Array> | null = null;\n  private _pullResolve: (() => void) | null = null;\n  private _abortCallbacks: (() => void)[] = [];\n  private _closed = false;\n\n  constructor(signal: AbortSignal) {\n    this.signal = signal;\n    if (!signal.aborted) {\n      signal.addEventListener('abort', this._onAbort, { once: true });\n    }\n  }\n\n  /** `true` once the client has disconnected. */\n  get aborted(): boolean {\n    return this.signal.aborted;\n  }\n\n  /**\n   * @internal Wire the underlying `ReadableStream` controller. Called once from\n   * the stream's `start()`.\n   */\n  attach(controller: ReadableStreamDefaultController<Uint8Array>): void {\n    this._rsController = controller;\n  }\n\n  /**\n   * @internal Release a pending backpressure wait. Called from the stream's\n   * `pull()` when the consumer is ready for more data.\n   */\n  onPull(): void {\n    this._resolvePull();\n  }\n\n  /**\n   * Register a cleanup callback invoked once when the client disconnects.\n   * Invoked immediately if already aborted.\n   */\n  onAbort(fn: () => void): void {\n    if (this.aborted) {\n      fn();\n      return;\n    }\n    this._abortCallbacks.push(fn);\n  }\n\n  /**\n   * Enqueue raw bytes, applying cooperative backpressure.\n   *\n   * @throws StreamAbortedError if the client has disconnected.\n   */\n  async enqueue(chunk: Uint8Array): Promise<void> {\n    if (this.aborted) throw new StreamAbortedError();\n    const controller = this._rsController;\n    if (!controller) {\n      throw new Error('StreamController is not attached to a stream.');\n    }\n    controller.enqueue(chunk);\n    // Backpressure: if the consumer's buffer is full, wait until the next pull().\n    if ((controller.desiredSize ?? 1) <= 0) {\n      await this._waitForPull();\n      // Re-check via the signal directly: the client may have disconnected\n      // while we were parked on backpressure.\n      if (this.signal.aborted) throw new StreamAbortedError();\n    }\n  }\n\n  /** Encode a UTF-8 string and enqueue it. */\n  enqueueText(text: string): Promise<void> {\n    return this.enqueue(TEXT_ENCODER.encode(text));\n  }\n\n  /**\n   * Normalize any accepted source shape to a single async-iterator.\n   *\n   * @remarks\n   * The one and only place that branches on source type. `AsyncIterable`\n   * (including Node `Readable`, which implements `Symbol.asyncIterator`) is used\n   * directly; a bare Web `ReadableStream` is adapted via its reader.\n   */\n  normalize<T>(source: AsyncIterable<T> | ReadableStream<T>): AsyncIterator<T> {\n    if (Symbol.asyncIterator in source) {\n      return (source as AsyncIterable<T>)[Symbol.asyncIterator]();\n    }\n    const reader = (source as ReadableStream<T>).getReader();\n    return {\n      async next(): Promise<IteratorResult<T>> {\n        const { done, value } = await reader.read();\n        return done\n          ? { done: true, value: undefined as never }\n          : { done: false, value };\n      },\n      async return(): Promise<IteratorResult<T>> {\n        await reader.cancel();\n        return { done: true, value: undefined as never };\n      },\n    };\n  }\n\n  /** Close the underlying stream cleanly. Idempotent. */\n  close(): void {\n    if (this._closed) return;\n    this._closed = true;\n    this.signal.removeEventListener('abort', this._onAbort);\n    this._resolvePull();\n    if (this._rsController) {\n      try {\n        this._rsController.close();\n      } catch {\n        // Already closed or errored by the consumer — nothing to do.\n      }\n    }\n  }\n\n  /** Error the underlying stream. Idempotent. */\n  error(err: unknown): void {\n    if (this._closed) return;\n    this._closed = true;\n    this.signal.removeEventListener('abort', this._onAbort);\n    this._resolvePull();\n    if (this._rsController) {\n      try {\n        this._rsController.error(err);\n      } catch {\n        // Already closed or errored — nothing to do.\n      }\n    }\n  }\n\n  private _onAbort = (): void => {\n    // Unblock any writer waiting on backpressure so it observes the abort.\n    this._resolvePull();\n    const callbacks = this._abortCallbacks;\n    this._abortCallbacks = [];\n    for (const cb of callbacks) {\n      try {\n        cb();\n      } catch {\n        // Cleanup callbacks must not break the abort path.\n      }\n    }\n  };\n\n  private _resolvePull(): void {\n    const resolve = this._pullResolve;\n    if (resolve) {\n      this._pullResolve = null;\n      resolve();\n    }\n  }\n\n  private _waitForPull(): Promise<void> {\n    return new Promise<void>((resolve) => {\n      this._pullResolve = resolve;\n    });\n  }\n}\n","/**\n * @nextrush/stream - Protocol writers\n *\n * Thin formatting wrappers over {@link StreamController}. Each writer differs\n * only in how `write()` encodes its protocol's native unit and how `consume()`\n * maps a raw chunk. All lifecycle (abort, backpressure, close) lives in the\n * controller — not here.\n *\n * See docs/RFC/request-data/003-stream.md §5, §7.\n *\n * @packageDocumentation\n */\n\nimport type {\n  NDJSONStreamWriter,\n  SSEEvent,\n  SSEStreamWriter,\n  StreamSource,\n  TextStreamWriter,\n} from '@nextrush/types';\nimport { formatSSE } from './sse-format';\nimport type { StreamController } from './stream-controller';\n\n/** Decodes byte chunks to text for protocols whose payload is textual (SSE). */\nconst TEXT_DECODER = new TextDecoder();\n\n/**\n * Shared base: exposes the controller's abort surface and drives `consume()`.\n *\n * @typeParam T - The unit type each source chunk is mapped to before `write()`.\n */\nabstract class BaseWriter<T> {\n  constructor(protected readonly controller: StreamController) {}\n\n  get aborted(): boolean {\n    return this.controller.aborted;\n  }\n\n  get signal(): AbortSignal {\n    return this.controller.signal;\n  }\n\n  onAbort(fn: () => void): void {\n    this.controller.onAbort(fn);\n  }\n\n  /** Protocol-specific write of one native unit. */\n  abstract write(value: T): Promise<void>;\n\n  /** Map one raw source chunk to this protocol's native unit. */\n  protected abstract mapChunk(chunk: unknown): T;\n\n  /**\n   * Consume an existing producer into this response. Single normalization path;\n   * stops and throws `StreamAbortedError` if the client disconnects mid-consume.\n   */\n  async consume(source: StreamSource<unknown>): Promise<void> {\n    const iterator = this.controller.normalize(source);\n    try {\n      for (;;) {\n        const result: IteratorResult<unknown> = await iterator.next();\n        if (result.done) return;\n        await this.write(this.mapChunk(result.value));\n      }\n    } finally {\n      await iterator.return?.(undefined);\n    }\n  }\n}\n\n/** Raw text/byte writer for `ctx.stream()`. */\nexport class TextWriter\n  extends BaseWriter<string | Uint8Array>\n  implements TextStreamWriter\n{\n  write(chunk: string | Uint8Array): Promise<void> {\n    return typeof chunk === 'string'\n      ? this.controller.enqueueText(chunk)\n      : this.controller.enqueue(chunk);\n  }\n\n  protected mapChunk(chunk: unknown): string | Uint8Array {\n    return chunk as string | Uint8Array;\n  }\n}\n\n/** Server-Sent Events writer for `ctx.sse()`. */\nexport class SSEWriter extends BaseWriter<SSEEvent> implements SSEStreamWriter {\n  write(event: SSEEvent): Promise<void> {\n    return this.controller.enqueueText(formatSSE(event));\n  }\n\n  protected mapChunk(chunk: unknown): SSEEvent {\n    // A consumed producer yields raw text/bytes; wrap each as an SSE `data` event.\n    const data = chunk instanceof Uint8Array ? TEXT_DECODER.decode(chunk) : (chunk as string);\n    return { data };\n  }\n}\n\n/** Newline-delimited JSON writer for `ctx.ndjson()`. */\nexport class NDJSONWriter extends BaseWriter<unknown> implements NDJSONStreamWriter {\n  write(value: unknown): Promise<void> {\n    return this.controller.enqueueText(`${JSON.stringify(value)}\\n`);\n  }\n\n  protected mapChunk(chunk: unknown): unknown {\n    return chunk;\n  }\n}\n","/**\n * @nextrush/stream - Run orchestration\n *\n * Wires a protocol writer to a Web `ReadableStream` and ships it through the\n * adapter's `ctx.sendStream()` primitive. Runtime-agnostic: identical code path\n * on Node (eager pump) and Bun/Deno/Edge (lazy Response body).\n *\n * See docs/RFC/request-data/003-stream.md §5, §6.\n *\n * @packageDocumentation\n */\n\nimport type {\n  NDJSONStreamWriter,\n  SSEStreamWriter,\n  StreamRun,\n  TextStreamWriter,\n} from '@nextrush/types';\nimport { StreamAbortedError } from './errors';\nimport { StreamController } from './stream-controller';\nimport { NDJSONWriter, SSEWriter, TextWriter } from './writers';\n\n/**\n * Minimal Context surface `@nextrush/stream` needs. The concrete adapter\n * `Context` satisfies this structurally; kept narrow so unit tests can supply a\n * lightweight fake.\n */\nexport interface StreamCapableContext {\n  readonly signal: AbortSignal;\n  set(field: string, value: string | number | string[]): void;\n  sendStream(source: ReadableStream<Uint8Array>): Promise<void>;\n}\n\nconst CONTENT_TYPE = {\n  text: 'text/plain; charset=utf-8',\n  sse: 'text/event-stream; charset=utf-8',\n  ndjson: 'application/x-ndjson; charset=utf-8',\n} as const;\n\n/**\n * Core streaming loop shared by all three protocols.\n *\n * @remarks\n * The callback runs in a **detached** task launched from the stream's `start()`,\n * intentionally not awaited there: awaiting it would block `pull()` from ever\n * being called, deadlocking backpressure on lazy (web) runtimes. Backpressure is\n * instead relieved cooperatively via `pull()` → `controller.onPull()`.\n */\nfunction runStream<W>(\n  ctx: StreamCapableContext,\n  contentType: string,\n  makeWriter: (controller: StreamController) => W,\n  run: (writer: W) => Promise<void>,\n  extraHeaders?: Record<string, string>,\n): Promise<void> {\n  ctx.set('Content-Type', contentType);\n  if (extraHeaders) {\n    for (const [field, value] of Object.entries(extraHeaders)) {\n      ctx.set(field, value);\n    }\n  }\n\n  const controller = new StreamController(ctx.signal);\n\n  const readable = new ReadableStream<Uint8Array>({\n    start(rsController): void {\n      controller.attach(rsController);\n      const writer = makeWriter(controller);\n      // Detached on purpose — see function remarks.\n      void (async (): Promise<void> => {\n        try {\n          await run(writer);\n          controller.close();\n        } catch (err) {\n          if (err instanceof StreamAbortedError) {\n            // Client disconnected — expected, close cleanly and swallow.\n            controller.close();\n          } else {\n            // Real error: surface it to the stream. On Node this rejects the\n            // pump (ctx.sendStream); on web it errors the Response body stream.\n            controller.error(err);\n          }\n        }\n      })();\n    },\n    pull(): void {\n      controller.onPull();\n    },\n    cancel(): void {\n      // Consumer cancelled the read side — release any pending backpressure wait.\n      controller.onPull();\n    },\n  });\n\n  return ctx.sendStream(readable);\n}\n\n/** Implements `ctx.stream()`. */\nexport function runTextStream(\n  ctx: StreamCapableContext,\n  run: StreamRun<TextStreamWriter>,\n): Promise<void> {\n  return runStream(ctx, CONTENT_TYPE.text, (c) => new TextWriter(c), run);\n}\n\n/** Implements `ctx.sse()`. */\nexport function runSSEStream(\n  ctx: StreamCapableContext,\n  run: StreamRun<SSEStreamWriter>,\n): Promise<void> {\n  return runStream(ctx, CONTENT_TYPE.sse, (c) => new SSEWriter(c), run, {\n    'Cache-Control': 'no-cache',\n  });\n}\n\n/** Implements `ctx.ndjson()`. */\nexport function runNDJSONStream(\n  ctx: StreamCapableContext,\n  run: StreamRun<NDJSONStreamWriter>,\n): Promise<void> {\n  return runStream(ctx, CONTENT_TYPE.ndjson, (c) => new NDJSONWriter(c), run);\n}\n"],"mappings":"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","names":["StreamAbortedError","Error","name","Object","setPrototypeOf","prototype","formatSSE","event","out","undefined","sanitizeField","id","retry","String","Math","trunc","data","JSON","stringify","line","split","replace","value","TEXT_ENCODER","TextEncoder","StreamController","signal","_rsController","_pullResolve","_abortCallbacks","_closed","aborted","addEventListener","_onAbort","once","attach","controller","onPull","_resolvePull","onAbort","fn","push","enqueue","chunk","StreamAbortedError","Error","desiredSize","_waitForPull","enqueueText","text","encode","normalize","source","Symbol","asyncIterator","reader","getReader","next","done","value","read","undefined","return","cancel","close","removeEventListener","error","err","callbacks","cb","resolve","Promise","TEXT_DECODER","TextDecoder","BaseWriter","controller","aborted","signal","onAbort","fn","consume","source","iterator","normalize","result","next","done","write","mapChunk","value","return","undefined","TextWriter","chunk","enqueueText","enqueue","SSEWriter","event","formatSSE","data","Uint8Array","decode","NDJSONWriter","JSON","stringify","CONTENT_TYPE","text","sse","ndjson","runStream","ctx","contentType","makeWriter","run","extraHeaders","set","field","value","Object","entries","controller","StreamController","signal","readable","ReadableStream","start","rsController","attach","writer","close","err","StreamAbortedError","error","pull","onPull","cancel","sendStream","runTextStream","c","TextWriter","runSSEStream","SSEWriter","runNDJSONStream","NDJSONWriter"]}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@nextrush/stream",
+  "version": "1.0.0-beta.0",
+  "description": "Runtime-agnostic response streaming (text/SSE/NDJSON) for NextRush — built for AI/agentic apps",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "@nextrush/types": "4.0.0-beta.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3"
+  },
+  "keywords": [
+    "nextrush",
+    "stream",
+    "sse",
+    "server-sent-events",
+    "ndjson",
+    "ai",
+    "streaming",
+    "http"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/0xTanzim/nextRush/tree/main/packages/stream#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/0xTanzim/nextRush.git",
+    "directory": "packages/stream"
+  },
+  "author": {
+    "name": "Tanzim Hossain",
+    "email": "tanzimhossain2@gmail.com",
+    "url": "https://github.com/0xTanzim"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ignore-pattern '**/__tests__/**'",
+    "clean": "rm -rf dist"
+  }
+}

package/src/__tests__/public-surface.test.ts

@@ -0,0 +1,40 @@
+/**
+ * @nextrush/stream - Public API surface test
+ *
+ * Locks the exported symbol set from `src/index.ts`. If this test fails, the
+ * public API has changed. Intentional changes require an explicit update to
+ * the expected list below, plus a changeset for a published package.
+ */
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import * as streamApi from '../index';
+import type { BaseStreamWriter, NDJSONStreamWriter, SSEEvent, SSEStreamWriter, StreamCapableContext, StreamRun, StreamSource, TextStreamWriter } from '../index';
+
+describe('Public API surface (runtime exports)', () => {
+  it('exports exactly the intended runtime symbols', () => {
+    const actualExports = Object.keys(streamApi).sort();
+
+    // SEALED: intentional public runtime API surface.
+    const expectedRuntime = [
+      'StreamAbortedError',
+      'formatSSE',
+      'StreamController',
+      'runNDJSONStream',
+      'runSSEStream',
+      'runTextStream',
+      'NDJSONWriter',
+      'SSEWriter',
+      'TextWriter',
+    ].sort();
+
+    expect(actualExports).toEqual(expectedRuntime);
+  });
+});
+
+describe('Public API surface (type-only exports)', () => {
+  it('the type-only surface stays importable from the barrel', () => {
+    // Compile-time only: removing/renaming any of these in src/index.ts fails
+    // this file to type-check.
+    type Surface = [StreamCapableContext, BaseStreamWriter, NDJSONStreamWriter, SSEEvent, SSEStreamWriter, StreamRun, StreamSource, TextStreamWriter];
+    expectTypeOf<Surface>().not.toBeNever();
+  });
+});