Anvia Docs

Import from @anvia/server.

Types

type EventStreamFormat = "jsonl" | "sse";

type EventStreamErrorEvent = {
  type: "error";
  error: unknown;
};

type CreateEventStreamOptions<TEvent> = {
  format?: EventStreamFormat;
  headers?: HeadersInit;
  status?: number;
  statusText?: string;
  jsonl?: JsonlStreamOptions<TEvent>;
  sse?: SseStreamOptions<TEvent>;
};

type JsonlStreamOptions<TEvent> = {
  serialize?: (event: TEvent | EventStreamErrorEvent) => string;
};

type SseStreamOptions<TEvent> = {
  eventName?: string | ((event: TEvent | EventStreamErrorEvent) => string | undefined);
  serialize?: (event: TEvent | EventStreamErrorEvent) => string;
  retry?: number;
};

createEventStream

function createEventStream<TEvent>(
  events: AsyncIterable<TEvent>,
  options?: {
    format?: "jsonl" | "sse";
    headers?: HeadersInit;
    status?: number;
    statusText?: string;
    jsonl?: JsonlStreamOptions<TEvent>;
    sse?: SseStreamOptions<TEvent>;
  },
): Response;

Purpose: convert an async iterable of events into an HTTP Response.

Default behavior: writes JSONL with content-type: application/x-ndjson; charset=utf-8, cache-control: no-cache, no-transform, connection: keep-alive, and x-accel-buffering: no.

Use format: "sse" to emit text/event-stream.

createJsonlStream

function createJsonlStream<TEvent>(
  events: AsyncIterable<TEvent>,
  options?: {
    serialize?: (event: TEvent | { type: "error"; error: unknown }) => string;
  },
): ReadableStream<Uint8Array>;

Purpose: encode each event as one JSON line.

Error behavior: if the iterable throws, the stream emits { type: "error", error } and closes.

createSseStream

function createSseStream<TEvent>(
  events: AsyncIterable<TEvent>,
  options?: {
    eventName?: string | ((event: TEvent | { type: "error"; error: unknown }) => string | undefined);
    serialize?: (event: TEvent | { type: "error"; error: unknown }) => string;
    retry?: number;
  },
): ReadableStream<Uint8Array>;

Purpose: encode each event as a Server-Sent Event with JSON in data: fields.

For workflow guidance, see Readable Streams.