@playfast/reform-remote-web 0.0.5 → 1.0.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@playfast/reform-remote-web",
   "playbook": "./playbook",
-  "version": "0.0.5",
+  "version": "1.0.1",
   "type": "module",
   "description": "Browser/web WebSocket client transport for reform-remote — streams a server-run reform scene to a thin renderer.",
   "keywords": [

package/src/transport.ts

@@ -1,4 +1,4 @@
-import { Redacted } from 'effect'
+import { Option, Redacted } from 'effect'
 import type { InvokeMessage, RemoteTransport, ServerMessage } from '@playfast/reform-remote'
 import { MissingWebSocket } from './errors.js'
 
@@ -17,12 +17,20 @@ import { MissingWebSocket } from './errors.js'
 
 export type ClientStatus = 'connecting' | 'open' | 'reconnecting' | 'closed'
 
+/** First reconnect delay; doubles each attempt up to {@link DEFAULT_MAX_DELAY_MS}. */
+const DEFAULT_BASE_DELAY_MS = 250
+/** Ceiling for the exponential backoff delay. */
+const DEFAULT_MAX_DELAY_MS = 5000
+
 /**
  * Options for {@link createWebSocketClientTransport}. A single named-options object
  * (no positional args) so every reform-remote adapter constructor has the same
  * shape and the client transports stay drop-in swappable.
+ *
+ * The `ExternalApi` postfix marks this as the package's public consumer-facing
+ * surface, where optional config fields are idiomatic.
  */
-export interface WebSocketClientTransportOptions {
+export interface WebSocketClientTransportOptionsExternalApi {
   /** The WebSocket URL to connect to (e.g. `ws://127.0.0.1:8787/reform`). */
   readonly url: string
   /** First reconnect delay; doubles each attempt up to `maxDelayMs`. Default 250ms. */
@@ -44,6 +52,9 @@ export interface WebSocketClientTransportOptions {
   readonly onStatus?: (status: ClientStatus) => void
 }
 
+/** Back-compat alias for the public options type. */
+export type WebSocketClientTransportOptions = WebSocketClientTransportOptionsExternalApi
+
 /** A `RemoteTransport` that also exposes its connection status and a manual close. */
 export type WebSocketClientTransport = RemoteTransport<InvokeMessage, ServerMessage> & {
   readonly status: () => ClientStatus
@@ -57,9 +68,16 @@ export type WebSocketClientTransport = RemoteTransport<InvokeMessage, ServerMess
   readonly close: () => void
 }
 
+/** DOM-boundary view of the global scope: the optional global `WebSocket` constructor. */
+interface GlobalWebSocketHolderExternalApi {
+  readonly WebSocket?: typeof WebSocket
+}
+
 const resolveWebSocket = (injected: typeof WebSocket | undefined): typeof WebSocket => {
-  const impl = injected ?? (globalThis as { WebSocket?: typeof WebSocket }).WebSocket
+  const globalScope: GlobalWebSocketHolderExternalApi = globalThis
+  const impl = injected ?? globalScope.WebSocket
   if (impl === undefined) {
+    // oxlint-disable-next-line reform-rules/no-throw -- sync public transport factory invariant; no Effect context at construction
     throw new MissingWebSocket({
       message: 'No global WebSocket; pass `WebSocket` in options (e.g. the `ws` package in Node <22).',
     })
@@ -71,9 +89,9 @@ export const createWebSocketClientTransport = (
   options: WebSocketClientTransportOptions,
 ): WebSocketClientTransport => {
   const url = options.url
-  const WS = resolveWebSocket(options.WebSocket)
-  const baseDelayMs = options.baseDelayMs ?? 250
-  const maxDelayMs = options.maxDelayMs ?? 5000
+  const WebSocketImpl = resolveWebSocket(options.WebSocket)
+  const baseDelayMs = options.baseDelayMs ?? DEFAULT_BASE_DELAY_MS
+  const maxDelayMs = options.maxDelayMs ?? DEFAULT_MAX_DELAY_MS
 
   // Normalize `protocols` to an array and fold in the auth token as a `bearer.<token>`
   // subprotocol. Computed once (the token doesn't change across reconnects). `undefined`
@@ -93,58 +111,73 @@ export const createWebSocketClientTransport = (
 
   const handlers = new Set<(message: ServerMessage) => void>()
   const statusListeners = new Set<() => void>()
-  const queue: Array<InvokeMessage> = []
   // A const holder whose fields swap — the codebase's no-`let` idiom.
   const state: {
-    socket: WebSocket | null
+    socket: Option.Option<WebSocket>
     status: ClientStatus
     attempts: number
-    timer: ReturnType<typeof setTimeout> | null
-  } = { socket: null, status: 'connecting', attempts: 0, timer: null }
+    timer: Option.Option<ReturnType<typeof setTimeout>>
+    queue: ReadonlyArray<InvokeMessage>
+  } = { socket: Option.none(), status: 'connecting', attempts: 0, timer: Option.none(), queue: [] }
 
   const setStatus = (status: ClientStatus): void => {
-    if (status === state.status) return
+    if (status === state.status) {
+      return
+    }
     state.status = status
     options.onStatus?.(status)
-    for (const listener of statusListeners) listener()
+    statusListeners.forEach((listener) => listener())
   }
 
   const flush = (): void => {
-    const socket = state.socket
-    if (socket === null || socket.readyState !== WS.OPEN) return
-    const pending = queue.splice(0, queue.length)
-    for (const message of pending) socket.send(JSON.stringify(message))
+    if (!Option.isSome(state.socket)) {
+      return
+    }
+    const socket = state.socket.value
+    if (socket.readyState !== WebSocketImpl.OPEN) {
+      return
+    }
+    const pending = state.queue
+    state.queue = []
+    // oxlint-disable-next-line reform-rules/no-json-parse-stringify -- wire frame encode; InvokeMessage is a structural type with no Schema here
+    pending.forEach((message) => socket.send(JSON.stringify(message)))
   }
 
   const scheduleReconnect = (): void => {
-    if (state.status === 'closed') return
+    if (state.status === 'closed') {
+      return
+    }
     setStatus('reconnecting')
     const delay = Math.min(maxDelayMs, baseDelayMs * 2 ** state.attempts)
     state.attempts += 1
-    state.timer = setTimeout(connect, delay)
+    // oxlint-disable-next-line reform-rules/no-set-timeout-interval -- DOM transport reconnect backoff; sync factory has no Effect runtime
+    state.timer = Option.some(setTimeout(connect, delay))
   }
 
   // A drop while live (or a failed connect) backs off and retries. A socket can
-  // fire both `error` and `close`, so guard on identity — null out the current
+  // fire both `error` and `close`, so guard on identity — clear the current
   // socket on the first drop, so the second event is a no-op and only one
   // reconnect is scheduled. A user `close` flips the status, making this inert.
   const handleDrop = (socket: WebSocket): void => {
-    if (state.socket !== socket) return
-    state.socket = null
+    if (Option.isNone(state.socket) || state.socket.value !== socket) {
+      return
+    }
+    state.socket = Option.none()
     scheduleReconnect()
   }
 
   function connect(): void {
-    const socket = protocols === undefined ? new WS(url) : new WS(url, [...protocols])
-    state.socket = socket
+    const socket = protocols === undefined ? new WebSocketImpl(url) : new WebSocketImpl(url, [...protocols])
+    state.socket = Option.some(socket)
     socket.addEventListener('open', () => {
       state.attempts = 0
       setStatus('open')
       flush()
     })
     socket.addEventListener('message', (event: MessageEvent) => {
+      // oxlint-disable-next-line reform-rules/no-json-parse-stringify, reform-rules/no-type-assertion -- wire frame decode; ServerMessage is a structural type with no Schema here
       const message = JSON.parse(event.data as string) as ServerMessage
-      for (const handler of handlers) handler(message)
+      handlers.forEach((handler) => handler(message))
     })
     socket.addEventListener('close', () => handleDrop(socket))
     socket.addEventListener('error', () => handleDrop(socket))
@@ -154,7 +187,7 @@ export const createWebSocketClientTransport = (
 
   return {
     send: (message) => {
-      queue.push(message)
+      state.queue = [...state.queue, message]
       flush()
     },
     onMessage: (handler) => {
@@ -168,8 +201,12 @@ export const createWebSocketClientTransport = (
     },
     close: () => {
       setStatus('closed')
-      if (state.timer !== null) clearTimeout(state.timer)
-      state.socket?.close()
+      if (Option.isSome(state.timer)) {
+        clearTimeout(state.timer.value)
+      }
+      if (Option.isSome(state.socket)) {
+        state.socket.value.close()
+      }
     },
   }
 }