use-next-sse/dist/cjs/client/use-sse.d.ts

A lightweight Server-Sent Events (SSE) library for Next.js, enabling real-time, unidirectional data streaming from server to client

/**
 * Options for the useSSE hook.
 * @property {string} url - The URL to connect to for SSE.
 * @property {string} [eventName='message'] - The name of the event to listen for.
 * @property {boolean | { interval?: number, maxAttempts?: number }} [reconnect] - Whether to automatically reconnect if the connection is lost. If an object, the interval and maxAttempts can be specified. Default `false`.
 * @property {number} [reconnect.interval] - The interval in milliseconds to wait before reconnecting. Default `1000`ms.
 * @property {number} [reconnect.maxAttempts] - The maximum number of reconnection attempts. Default `5`.
 * @example
 * const { data, error, lastEventId, close } = useSSE<{ message: string }>({ url: 'https://example.com/sse' });
 * @example
 * const { data, error, lastEventId, close } = useSSE<{ message: string }>({ url: 'https://example.com/sse', eventName: 'test' });
 * @example
 * const { data, error, lastEventId, close } = useSSE<{ message: string }>({ url: 'https://example.com/sse', reconnect: true });
 * @example
 * const { data, error, lastEventId, close } = useSSE<{ message: string }>({ url: 'https://example.com/sse', reconnect: { interval: 5000, maxAttempts: 10 } });
 * @example
 * const { data, error, lastEventId, close } = useSSE<{ message: string }>({ url: 'https://example.com/sse', eventName: 'test', reconnect: true });
 * @example
 * const { data, error, lastEventId, close } = useSSE<{ message: string }>({ url: 'https://example.com/sse', eventName: 'test', reconnect: { interval: 5000, maxAttempts: 10 } });
 * @example
 * const { data, error, lastEventId, close } = useSSE<{ message: string }>({ url: 'https://example.com/sse', reconnect: { interval: 5000, maxAttempts: 10 } });
 */
export type SSEOptions = {
    url: string;
    eventName?: string;
    /**
     * Whether to automatically reconnect if the connection is lost. If an object, the interval and maxAttempts can be specified. Default `false`.
     * @type {boolean | { interval?: number, maxAttempts?: number }}
     * @default false
     * @example
     * const { data, error, lastEventId, close } = useSSE({ url: 'https://example.com/sse', reconnect: true });
     * @example
     * const { data, error, lastEventId, close } = useSSE({ url: 'https://example.com/sse', reconnect: { interval: 5000, maxAttempts: 10 } });
     * @example
     * const { data, error, lastEventId, close } = useSSE({ url: 'https://example.com/sse', reconnect: { interval: 5000, maxAttempts: 10 } });
     * @example
     * const { data, error, lastEventId, close } = useSSE({ url: 'https://example.com/sse', eventName: 'test', reconnect: true });
     * @example
     * const { data, error, lastEventId, close } = useSSE({ url: 'https://example.com/sse', eventName: 'test', reconnect: { interval: 5000, maxAttempts: 10 } });
     * @example
     * const { data, error, lastEventId, close } = useSSE({ url: 'https://example.com/sse', eventName: 'test', reconnect: true });
     */
    reconnect?: boolean | {
        interval?: number;
        maxAttempts?: number;
    };
    /**
     * Whether to include credentials in the request. Default `false`.
     */
    withCredentials?: boolean;
};
interface SSEResult<T> {
    data: T | null;
    error: Error | null;
    lastEventId: string | null;
    close: () => void;
    /**
     * The connection state of the SSE.
     * @type {'connecting' | 'open' | 'closed'}
     * @default 'connecting'
     * @example
     * const { connectionState } = useSSE({ url: '/api/sse' });
     * if (connectionState === 'open') {
     *  console.log('Connected to SSE');
     * }
     * if (connectionState === 'closed') {
     * console.log('Disconnected from SSE');
     * }
     * if (connectionState === 'connecting') {
     * console.log('Connecting to SSE');
     * }
     */
    connectionState: 'connecting' | 'open' | 'closed';
}
/**
 * Hook to manage Server-Sent Events (SSE) connections.
 *
 * @template T - The type of the data expected from the SSE.
 * @param {SSEOptions} options - The options for the SSE connection. {@link SSEOptions}
 * @param {string} options.url - The URL to connect to for SSE.
 * @param {string} [options.eventName='message'] - The name of the event to listen for.
 * @param {boolean | { interval?: number, maxAttempts?: number }} [options.reconnect] - Whether to automatically reconnect if the connection is lost. If an object, the interval and maxAttempts can be specified. Default `false`.
 * @param {number} [options.reconnect.interval] - The interval in milliseconds to wait before reconnecting. Default `1000`ms.
 * @param {number} [options.reconnect.maxAttempts] - The maximum number of reconnection attempts. Default `5`.
 * @param {boolean} [options.withCredentials=false] - Whether to include credentials in the request. Default `false`.
 * @returns {SSEResult<T>} The result of the SSE connection, including data, error, last event ID, and a close function. {@link SSEResult}
 *
 * @example
 * const { data, error, lastEventId, close } = useSSE<{ message: string }>({ url: 'https://example.com/sse' });
 *
 * useEffect(() => {
 *   if (data) {
 *     console.log(data.message);
 *   }
 * }, [data]);
 */
export declare function useSSE<T = any>({ url, eventName, reconnect, withCredentials, }: SSEOptions): SSEResult<T>;
export {};