use-event-source

Reactive Server-Sent Events stream with typed, per-event decoding.


Package	`@vizejs/composable/use-event-source`
Own the source	`vize lib pull composable:use-event-source`
Runtime exports	`useEventSource`
Gzip budget	4608 B

Usage

import { useEventSource } from "@vizejs/composable/use-event-source";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useEventSource`	networking	experimental	deterministic-fallback	caller-managed	caller, reactive-scope	web, server, worker, native, desktop, terminal	`globalThis`, `window`	`calculateRetryDelay`, `tryOnScopeDispose`

API

`useEventSource`

Reactive Server-Sent Events stream with typed, per-event decoding. Every subscribed event is decoded by its parser (raw text by default) and exposed as a discriminated message, plus data/event/lastEventId shortcuts and typed on() handlers. Transient drops use the browser's native reconnection; autoReconnect additionally reopens streams the browser closed for good. The stream and timers are released when the owning reactive scope stops (the caller owns close() outside a scope). Server rendering never connects and reports "closed".

function useEventSource<Events extends EventSourceEventMap = { message: string }>( url: MaybeRefOrGetter<string | URL | null | undefined>, ...[options]: unknown extends EventSourceParseRequirement<Events> ? [options?: UseEventSourceOptions<Events>] : [options: UseEventSourceOptions<Events> & EventSourceParseRequirement<Events>] ): EventSourceControls<Events>

const feed = useEventSource<{ price: number; notice: string }>("/stream", {
  events: ["price", "notice"],
  parse: { price: (raw) => Number(raw) },
});
feed.on("price", (price) => chart.push(price));

Types

`EventSourceLike`

Minimal EventSource instance used by useEventSource.

Member	Type	Description
`readyState`	`number`	`0` connecting, `1` open, `2` closed (native values).
`close`	`() => void`	Close the stream; the source never reconnects afterwards.
`addEventListener`	`(type: string, listener: EventListener) => void`	Subscribe to `open`, `error`, or a named server event.
`removeEventListener`	`(type: string, listener: EventListener) => void`	Remove a listener registered with `addEventListener`.

`EventSourceReconnectOptions`

Options for reconnecting streams the browser gave up on.

Member	Type	Description
`initialDelayMs`?	`number`	Delay before the first retry, in milliseconds.
`multiplier`?	`number`	Exponential multiplier applied for each subsequent retry. Values may be fractional but must be finite and at least one. The calculated delay is rounded up so a retry never starts earlier than the requested backoff.
`maximumDelayMs`?	`number`	Inclusive ceiling for the calculated delay, in milliseconds. The ceiling may be lower than `RetryDelayOptions.initialDelayMs`; in that case it also caps the first retry.
`jitterRatio`?	`number`	Fraction of the capped delay eligible for downward jitter. `0` is deterministic exponential backoff, `0.5` samples from the upper half of the range, and `1` applies full jitter from zero through the capped delay. Jitter never exceeds the unjittered delay.
`random`?	`() => number`	Entropy source returning a number in the half-open interval `[0, 1)`. It is called exactly once when the selected jitter range contains more than one integer millisecond, and is otherwise not read.
`retries`?	`number`	Maximum consecutive reconnection attempts.
`onFailed`?	`() => void`	Called once reconnection gives up.

`UseEventSourceOptions`

Options for useEventSource.

Member	Type	Description
`events`?	`readonly (keyof Events & string)[]`	Named server events to subscribe to.
`parse`?	`EventSourceParsers<Events>`	Per-event decoders (required for events whose data is not text).
`withCredentials`?	`boolean`	Send cookies with cross-origin requests.
`host`?	`MaybeRef<EventSourceConstructorLike \| null \| undefined>`	`EventSource` constructor (a plain value or ref, never a getter). Supplying one also enables automatic connection outside a browser.
`immediate`?	`boolean`	Connect as soon as a URL is available (browser or explicit host only).
`autoReconnect`?	`boolean \| EventSourceReconnectOptions`	Reopen the stream with backoff after the browser closes it for good (native reconnection covers transient drops).
`scheduler`?	`TimeoutScheduler`	Timer host for reconnection.
`onError`?	`(failure: EventSourceFailure) => void`	Observe failures.

`EventSourceControls`

Reactive state and controls returned by useEventSource.

Member	Type	Description
`status`	`Readonly<Ref<EventSourceStatus>>`	Connection status.
`message`	`Readonly<ShallowRef<EventSourceMessage<Events> \| undefined>>`	Latest decoded event, discriminated by name.
`data`	`Readonly<ShallowRef<Events[keyof Events & string] \| undefined>>`	Data of the latest event.
`event`	`Readonly<Ref<(keyof Events & string) \| undefined>>`	Name of the latest event.
`lastEventId`	`Readonly<Ref<string \| undefined>>`	`id:` field of the latest event.
`error`	`Readonly<ShallowRef<EventSourceFailure \| undefined>>`	Latest failure, cleared when the stream opens.
`source`	`Readonly<ShallowRef<EventSourceLike \| undefined>>`	Current underlying source, if any.
`on`	`<Name extends keyof Events & string>( event: Name, handler: (data: NoInfer<Events[Name]>, lastEventId: string) => void, ) => () => void`	Observe one subscribed event with typed data.
`open`	`() => void`	Open (or reopen) the stream.
`close`	`() => void`	Close the stream and disable reconnection.