Event Iterator in oRPC Clients

An Event Iterator in oRPC behaves like an AsyncGenerator. Simply iterate over it and await each event.

Basic Usage

const iterator = await client.streaming()

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

Stopping the Stream Manually

Call .return() on the iterator to gracefully end the stream.

const iterator = await client.streaming()

for await (const event of iterator) {
  if (wantToStop) {
    await iterator.return()
    break
  }

  console.log(event.message)
}

Error Handling

If an error occurs during streaming, oRPC will attempt retries based on your configuration. It can retry multiple times until the specified limit is reached, after which the error will be thrown.

INFO

If you're using RPCLink, you can customize the retry behavior here.

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
  }
}

INFO

Errors thrown by the server can be instances of ORPCError.

Connection Status

Combine with onEventIteratorStatusChange to track the connection status of the event iterator.

import { onEventIteratorStatusChange } from '@orpc/client'

let status: 'connecting' | 'error' | 'reconnecting' | 'connected' | 'closed' = 'connecting'
let unsubscribe: (() => void) | undefined

try {
  const iterator = await client.streaming()

  unsubscribe = onEventIteratorStatusChange(iterator, (newStatus) => {
    status = newStatus
  })

  for await (const event of iterator) {
    console.log(event.message)
  }
}
catch (error) {
  status = 'error'
}
finally {
  unsubscribe?.()
}