feat(iii-browser): expose addConnectionStateListener on ISdk

Author: ytallo

sdk/packages/node/iii-browser/src/iii.ts

@@ -79,6 +79,7 @@ class Sdk implements ISdk {
   private reconnectionConfig: IIIReconnectionConfig
   private reconnectAttempt = 0
   private connectionState: IIIConnectionState = 'disconnected'
+  private connectionListeners = new Set<(state: IIIConnectionState) => void>()
   private isShuttingDown = false
 
   constructor(
@@ -435,11 +436,35 @@ class Sdk implements ISdk {
     this.setConnectionState('disconnected')
   }
 
+  /**
+   * Subscribe to connection-state transitions. The handler is fired immediately
+   * with the current state, then on every transition. Multiple listeners are
+   * supported. Returns an unsubscribe function.
+   */
+  addConnectionStateListener = (handler: (state: IIIConnectionState) => void): (() => void) => {
+    this.connectionListeners.add(handler)
+    try {
+      handler(this.connectionState)
+    } catch (e) {
+      console.error('[iii] connection listener threw on initial fire', e)
+    }
+    return () => {
+      this.connectionListeners.delete(handler)
+    }
+  }
+
   // private methods
 
   private setConnectionState(state: IIIConnectionState): void {
     if (this.connectionState !== state) {
       this.connectionState = state
+      for (const handler of this.connectionListeners) {
+        try {
+          handler(state)
+        } catch (e) {
+          console.error('[iii] connection listener threw', e)
+        }
+      }
     }
   }
 

sdk/packages/node/iii-browser/src/index.ts

@@ -1,6 +1,7 @@
 export { ChannelReader, ChannelWriter } from './channels'
 
 export { EngineFunctions, EngineTriggers } from './iii-constants'
+export type { IIIConnectionState } from './iii-constants'
 
 export { type InitOptions, registerWorker, TriggerAction } from './iii'
 

sdk/packages/node/iii-browser/src/types.ts

@@ -1,4 +1,5 @@
 import type { ChannelReader, ChannelWriter } from './channels'
+import type { IIIConnectionState } from './iii-constants'
 import type {
   RegisterFunctionMessage,
   RegisterServiceMessage,
@@ -242,6 +243,23 @@ export interface ISdk {
    * ```
    */
   shutdown(): Promise<void>
+
+  /**
+   * Subscribe to connection-state transitions. The handler is fired immediately
+   * with the current state, then on every transition. Multiple listeners are
+   * supported. Returns an unsubscribe function.
+   *
+   * @example
+   * ```typescript
+   * const unsub = iii.addConnectionStateListener((state) => {
+   *   console.log('connection state:', state)
+   * })
+   *
+   * // Later, stop receiving updates
+   * unsub()
+   * ```
+   */
+  addConnectionStateListener(handler: (state: IIIConnectionState) => void): () => void
 }
 
 /**

sdk/packages/node/iii-browser/tests/connection.test.ts

@@ -0,0 +1,74 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { registerWorker } from '../src/iii'
+import type { IIIConnectionState } from '../src/iii-constants'
+import type { ISdk } from '../src/types'
+import { MockEngine } from './mock-websocket'
+
+describe('addConnectionStateListener', () => {
+  let engine: MockEngine
+  let sdk: ISdk
+
+  beforeEach(() => {
+    engine = new MockEngine()
+    engine.install()
+    sdk = registerWorker('ws://test:49135')
+  })
+
+  afterEach(async () => {
+    await sdk.shutdown()
+    engine.uninstall()
+  })
+
+  it('returns an unsubscribe function', () => {
+    const unsub = sdk.addConnectionStateListener(() => {})
+    expect(typeof unsub).toBe('function')
+  })
+
+  it('fires immediately with the current state on subscribe', () => {
+    const states: IIIConnectionState[] = []
+    sdk.addConnectionStateListener((s) => states.push(s))
+    expect(states.length).toBeGreaterThanOrEqual(1)
+    expect(['connecting', 'connected', 'disconnected', 'reconnecting', 'failed']).toContain(states[0])
+  })
+
+  it('multiple listeners receive same events', async () => {
+    const a: IIIConnectionState[] = []
+    const b: IIIConnectionState[] = []
+    sdk.addConnectionStateListener((s) => a.push(s))
+    sdk.addConnectionStateListener((s) => b.push(s))
+
+    // Trigger a transition by waiting for the open event the engine schedules.
+    await engine.waitForOpen()
+
+    expect(a.length).toBe(b.length)
+    expect(a[0]).toBe(b[0])
+    if (a.length > 1) {
+      expect(a).toEqual(b)
+    }
+  })
+
+  it('unsubscribe stops further calls', async () => {
+    const calls: IIIConnectionState[] = []
+    const unsub = sdk.addConnectionStateListener((s) => calls.push(s))
+
+    await engine.waitForOpen()
+    const beforeUnsub = calls.length
+
+    unsub()
+
+    // Trigger another transition (close should drive a state change).
+    engine.socket.simulateClose()
+
+    expect(calls.length).toBe(beforeUnsub)
+  })
+
+  it('emits transitions through connecting -> connected', async () => {
+    const states: IIIConnectionState[] = []
+    sdk.addConnectionStateListener((s) => states.push(s))
+
+    await engine.waitForOpen()
+
+    // Should have observed at minimum the initial state and a transition to connected.
+    expect(states).toContain('connected')
+  })
+})