@beignet/core/dist/server/server-sent-events.d.ts

Core framework primitives for Beignet

/**
 * One JSON-encoded Server-Sent Event.
 */
export interface ServerSentEventMessage<TData = unknown> {
    /** JSON-serializable event payload. */
    data: TData;
    /** Optional event type consumed by `EventSource.addEventListener(...)`. */
    event?: string;
    /** Optional event identifier used by browsers for `Last-Event-ID`. */
    id?: string;
    /** Optional browser reconnection delay in milliseconds. */
    retry?: number;
}
/**
 * Controls exposed while an SSE response is active.
 */
export interface ServerSentEventStream {
    /**
     * Aborts whenever this stream closes, including response cancellation.
     * Async setup should pass it to cancellable subscription APIs.
     */
    readonly signal: AbortSignal;
    /**
     * Send a JSON-encoded event.
     *
     * Returns `false` after the stream closes, when encoding fails, or when the
     * unread byte limit would be exceeded.
     */
    send<TData>(message: ServerSentEventMessage<TData>): boolean;
    /**
     * Send an SSE comment. Comments are useful as connection heartbeats.
     *
     * Returns `false` when the stream is no longer writable or its unread byte
     * limit would be exceeded.
     */
    comment(value?: string): boolean;
    /** Close the stream and run its cleanup exactly once. */
    close(): void;
}
/** Closeable subscription returned by an SSE stream's `start` callback. */
export interface ServerSentEventSubscription {
    /** Close the associated subscription. */
    close(): Promise<void> | void;
}
/** Cleanup returned by an SSE stream's `start` callback. */
export type ServerSentEventCleanup = (() => Promise<void> | void) | ServerSentEventSubscription;
/** Options for `createServerSentEventResponse(...)`. */
export interface ServerSentEventResponseOptions {
    /**
     * Begin producing events. Return a cleanup callback or closeable
     * subscription for resources associated with this connection. Pending
     * asynchronous setup does not block response cancellation; honor the stream
     * signal and return cleanup when setup settles.
     */
    start(stream: ServerSentEventStream): Promise<ServerSentEventCleanup | undefined> | ServerSentEventCleanup | undefined;
    /**
     * Abort the stream with the surrounding request or application lifecycle.
     */
    signal?: AbortSignal;
    /**
     * Interval for SSE heartbeat comments. Defaults to 25 seconds. Set to
     * `false` to disable heartbeats.
     */
    heartbeatMs?: number | false;
    /**
     * Close the connection after this duration so clients can reconnect and
     * reconcile. Disabled by default.
     */
    maxLifetimeMs?: number | false;
    /**
     * Maximum bytes of unread event data held by the response stream. Defaults
     * to 1 MiB. The connection closes when one frame or the accumulated queue
     * would exceed this limit.
     */
    maxBufferedBytes?: number;
    /** Additional response headers such as CORS or `Vary`. */
    headers?: HeadersInit;
    /**
     * Observe producer, serialization, buffer, stream, or cleanup failures.
     * Expected `AbortError` rejections caused by stream closure are ignored.
     */
    onError?(error: unknown): Promise<void> | void;
}
/**
 * Create a portable Fetch `Response` that safely manages a Server-Sent Events
 * stream.
 *
 * The helper owns SSE framing, JSON encoding, heartbeats, abort handling,
 * bounded unread buffering, maximum lifetime, and cleanup. Authentication,
 * replay, authorization, connection limits, and application reconciliation
 * remain the caller's responsibility.
 */
export declare function createServerSentEventResponse(options: ServerSentEventResponseOptions): Response;
//# sourceMappingURL=server-sent-events.d.ts.map