feat(client)!: update onEventIteratorStatusChange (#212)

Author: dinwwwh

apps/content/docs/client/event-iterator.md

@@ -70,3 +70,34 @@ catch (error) {
 ::: info
 Errors thrown by the server can be instances of `ORPCError`.
 :::
+
+## Event Iterator Connection Status
+
+Combine with `onEventIteratorStatusChange` to track the connection status of the event iterator.
+
+```ts twoslash
+declare const client: { streaming: () => Promise<AsyncGenerator<{ message: string }, void, void>> }
+// ---cut---
+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?.()
+}
+```

packages/client/src/event-iterator-state.test.ts

@@ -23,29 +23,29 @@ describe('eventIterator Status Management', () => {
 
   it('invokes the callback immediately if notifyImmediately is true', () => {
     const callback = vi.fn()
-    onEventIteratorStatusChange(dummyIterator, callback, true)
+    onEventIteratorStatusChange(dummyIterator, callback, { notifyImmediately: true })
     // The callback should be called right away with the current status.
     expect(callback).toHaveBeenCalledWith('connected')
   })
 
   it('does not invoke the callback immediately if notifyImmediately is false', () => {
     const callback = vi.fn()
-    onEventIteratorStatusChange(dummyIterator, callback, false)
+    onEventIteratorStatusChange(dummyIterator, callback, { notifyImmediately: false })
     // Since immediate notification is disabled, the callback should not have been called.
     expect(callback).not.toHaveBeenCalled()
   })
 
   it('calls the callback when the status is updated', () => {
     const callback = vi.fn()
-    onEventIteratorStatusChange(dummyIterator, callback, false)
+    onEventIteratorStatusChange(dummyIterator, callback, { notifyImmediately: false })
     updateEventIteratorStatus(initialState, 'reconnecting')
     // The callback should be called with the new status.
     expect(callback).toHaveBeenCalledWith('reconnecting')
   })
 
   it('does not call the callback if the status is updated to the same value', () => {
     const callback = vi.fn()
-    onEventIteratorStatusChange(dummyIterator, callback, false)
+    onEventIteratorStatusChange(dummyIterator, callback, { notifyImmediately: false })
     // Update with the same status as the initial one.
     updateEventIteratorStatus(initialState, 'connected')
     // The callback should not be triggered.
@@ -54,7 +54,7 @@ describe('eventIterator Status Management', () => {
 
   it('removes the listener when unsubscribed', () => {
     const callback = vi.fn()
-    const unsubscribe = onEventIteratorStatusChange(dummyIterator, callback, false)
+    const unsubscribe = onEventIteratorStatusChange(dummyIterator, callback, { notifyImmediately: false })
     // Update status to trigger the callback.
     updateEventIteratorStatus(initialState, 'reconnecting')
     expect(callback).toHaveBeenCalledTimes(1)

packages/client/src/event-iterator-state.ts

@@ -27,8 +27,10 @@ export function updateEventIteratorStatus(
 export function onEventIteratorStatusChange(
   iterator: AsyncIteratorObject<unknown, unknown, void>,
   callback: (status: ConnectionStatus) => void,
-  notifyImmediately = true,
+  options: { notifyImmediately?: boolean } = {},
 ): () => void {
+  const notifyImmediately = options.notifyImmediately ?? true
+
   const state = iteratorStates.get(iterator)
 
   if (!state) {