Event Iterator in Client

Consume an Event Iterator like an AsyncGenerator. Await the call, then iterate over events as they arrive.

Basic Usage

const iterator = await client.streaming()

for await (const event of iterator) {
  console.log(event.message)
}

Stopping the Stream

Use an AbortSignal or call .return to stop the iterator.

const controller = new AbortController()
const iterator = await client.streaming(undefined, { signal: controller.signal })

// Stop the stream after 1 second
setTimeout(async () => {
  controller.abort()

  // Or call `await iterator.return()` if you already have the iterator instance.
}, 1000)

for await (const event of iterator) {
  console.log(event.message)
}

Error Handling

INFO

Unlike traditional SSE, Event Iterators do not retry automatically after an error. To add retries, use the Retry Plugin.

const iterator = await client.streaming()

try {
  for await (const event of iterator) {
    console.log(event.message)
  }
}
catch (error) {
  if (error instanceof ORPCError) {
    // Handle the error here
  }
}

Event Metadata

Use getEventMeta to read event metadata for each item, such as the event ID and retry interval.

import { getEventMeta } from '@orpc/client'

const iterator = await client.streaming()

for await (const event of iterator) {
  const meta = getEventMeta(event)
  console.log(event.message, meta?.id, meta?.retry)
}

Using consumeEventIterator

Use consumeEventIterator to consume an event iterator with lifecycle callbacks. It accepts either an event iterator or a promise that resolves to one.

import { consumeEventIterator } from '@orpc/client'

const cancel = consumeEventIterator(client.streaming(), {
  onEvent: (event) => {
    console.log(event.message)
  },
  onError: (error) => {
    console.error(error)
  },
  onSuccess: (value) => {
    console.log(value)
  },
  onFinish: (state) => {
    console.log(state)
  },
})

setTimeout(async () => {
  // Stop the stream after 1 second
  await cancel()
}, 1000)