inngest/components/StreamTools.d.cts

Official SDK for Inngest.com. Inngest is the reliability layer for modern applications. Inngest combines durable execution, events, and queues into a zero-infra platform with built-in observability.

import { SseResponse } from "./execution/streaming.cjs";

//#region src/components/StreamTools.d.ts

/**
 * Accepted source types for `stream.pipe()`.
 *
 * - `ReadableStream` — piped directly
 * - `AsyncIterable<string>` — iterated; each yielded value becomes a chunk
 * - `() => AsyncIterable<string>` — factory invoked lazily, then iterated
 */
type PipeSource = ReadableStream | AsyncIterable<string> | (() => AsyncIterable<string>);
/**
 * The public interface for stream tools available to user code.
 */
interface StreamTools {
  /**
   * Push data to the client as an SSE stream event. Fire-and-forget from the
   * caller's perspective.
   *
   * Outside of an Inngest execution context this is a silent no-op (graceful
   * degradation).
   */
  push(data: unknown): void;
  /**
   * Pipe a source to the client, writing each chunk as an SSE stream event.
   * Resolves with the concatenated content of all chunks when the source is
   * fully consumed.
   *
   * Accepts a `ReadableStream`, an `AsyncIterable<string>`, or a factory
   * function that returns an `AsyncIterable<string>` (e.g. an async
   * generator function).
   *
   * Outside of an Inngest execution context this resolves with an empty string.
   */
  pipe(source: PipeSource): Promise<string>;
}
/**
 * Wraps a `TransformStream<Uint8Array>` to provide push/pipe SSE streaming
 * capabilities within an Inngest execution.
 *
 * @internal
 */
declare class Stream implements StreamTools {
  private transform;
  private writer;
  private encoder;
  private _activated;
  private _errored;
  private writeChain;
  /**
   * Optional callback invoked the first time `push` or `pipe` is called.
   * Used by the execution engine to fire a checkpoint that returns the SSE
   * Response to the client immediately.
   */
  private onActivated?;
  /**
   * Optional callback invoked when a write to the underlying stream fails
   * (e.g. the client disconnected or the transform stream errored). Used by
   * the execution engine to emit diagnostic logs.
   */
  private onWriteError?;
  constructor(opts?: {
    onActivated?: () => void;
    onWriteError?: (err: unknown) => void;
  });
  /**
   * Whether `push` or `pipe` has been called at least once.
   */
  get activated(): boolean;
  /**
   * The readable side of the underlying transform stream. Consumers (i.e. the
   * HTTP response) read SSE events from here.
   */
  get readable(): ReadableStream<Uint8Array>;
  /**
   * Resolve the current hashed step ID for stream events. Returns the
   * executing step's hashed ID (read from ALS), or undefined if outside a step.
   */
  private currentHashedStepId;
  private activate;
  /**
   * Encode and write an SSE event string to the underlying writer.
   */
  private writeEncoded;
  /**
   * Enqueue a pre-built SSE event string onto the write chain.
   */
  private enqueue;
  /**
   * Emit an `inngest.commit` SSE event indicating that uncommitted streamed data
   * should be committed (i.e. will not be rolled back). Internal use only.
   */
  commit(hashedStepId: string | null): void;
  /**
   * Emit an `inngest.rollback` SSE event indicating the uncommitted streamed
   * data should be discarded (e.g. step errored). Internal use only.
   */
  rollback(hashedStepId: string | null): void;
  /**
   * Serialize `data` into an SSE stream event and enqueue it. Returns `false`
   * if serialization fails (e.g. circular reference) so callers can skip.
   */
  private enqueueStreamEvent;
  /**
   * Write a single SSE stream event containing `data`. The current step's
   * hashed ID is automatically included as stepId for rollback tracking.
   */
  push(data: unknown): void;
  /**
   * Pipe a source to the client, writing each chunk as an SSE stream event.
   * Returns the concatenated content of all chunks.
   */
  pipe(source: PipeSource): Promise<string>;
  /**
   * Adapt a ReadableStream into an AsyncIterable<string>. TypeScript's
   * ReadableStream type doesn't declare Symbol.asyncIterator, so we use the
   * reader API for type safety.
   */
  private readableToAsyncIterable;
  /**
   * Core pipe loop: iterate an async iterable, writing each chunk as an SSE
   * stream event and collecting the concatenated result.
   */
  private pipeIterable;
  /**
   * Write a redirect info event. Tells the client where to reconnect if the
   * durable endpoint goes async. Does NOT close the writer — more stream
   * events may follow before the durable endpoint actually switches to async
   * mode. Internal use only.
   */
  sendRedirectInfo(data: {
    runId: string;
    url: string;
  }): void;
  /**
   * Write a succeeded result event and close the writer. Internal use only.
   */
  closeSucceeded(response: SseResponse): void;
  /**
   * Write a failed result event and close the writer. Internal use only.
   */
  closeFailed(error: string): void;
  /**
   * Optionally write a final SSE event, then close the writer.
   */
  private closeWriter;
  /**
   * Close the writer without writing a result event. Used when the durable endpoint goes
   * async and the real result will arrive on the redirected stream.
   */
  end(): void;
}
/**
 * Stream tools that use ALS to resolve the current execution context.
 * Outside an Inngest execution, `push()` is a no-op and `pipe()` resolves immediately.
 */
declare const stream: StreamTools;
//#endregion
export { Stream, stream };
//# sourceMappingURL=StreamTools.d.cts.map