@symmio/trading-core 3.0.0 → 3.1.0

package/dist/websocket/socket/create-reconnecting-socket.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-reconnecting-socket.js","names":[],"sources":["../../../src/websocket/socket/create-reconnecting-socket.ts"],"sourcesContent":["import type { WebSocketConstructor, WebSocketLike } from \"../../shared/types/websocket\";\nimport { computeBackoffDelay } from \"./backoff\";\nimport { SOCKET_READY_STATE, type SocketStatus } from \"./socket-status\";\n\n/**\n * Reconnect tuning for {@link createReconnectingSocket}. All fields optional;\n * defaults match the SDK's notifications behavior (unlimited retries, 500ms →\n * 10s exponential backoff with jitter).\n */\nexport interface ReconnectingSocketReconnectOptions {\n  /** Reconnect after an unclean close. Default `true`. */\n  enabled?: boolean;\n  /** Max consecutive retries before giving up. Default `Infinity`. */\n  maxAttempts?: number;\n  /** Delay before the first retry, in ms. Default `500`. */\n  baseDelayMs?: number;\n  /** Upper bound on any single retry delay, in ms. Default `10_000`. */\n  maxDelayMs?: number;\n  /** Apply random jitter to retry delays. Default `true`. */\n  jitter?: boolean;\n}\n\n/**\n * Heartbeat tuning for {@link createReconnectingSocket}. Disabled by default —\n * enable only when the server expects periodic client keepalive frames.\n */\nexport interface ReconnectingSocketHeartbeatOptions {\n  /** Send a periodic keepalive frame while open. Default `false`. */\n  enabled?: boolean;\n  /** Interval between keepalive frames, in ms. Default `30_000`. */\n  intervalMs?: number;\n  /** The keepalive frame to send. Default `\"ping\"`. */\n  message?: string;\n}\n\n/**\n * Reason a socket closed, delivered to {@link ReconnectingSocketOptions.onClose}.\n */\nexport interface SocketCloseInfo {\n  /** WebSocket close code, if the implementation supplied one. */\n  code?: number;\n  /** WebSocket close reason, if any. */\n  reason?: string;\n  /** Whether the socket will attempt to reconnect after this close. */\n  willReconnect: boolean;\n}\n\n/**\n * Options for {@link createReconnectingSocket}.\n */\nexport interface ReconnectingSocketOptions {\n  /** Endpoint URL (`ws://` / `wss://`). */\n  url: string;\n  /** Optional subprotocol(s), forwarded to the WebSocket constructor. */\n  protocols?: string | string[];\n  /** WebSocket implementation to dial with (resolve from `config.getWebSocketConstructor()`). */\n  webSocketConstructor: WebSocketConstructor;\n  /**\n   * Frames sent on every (re)open, in order, before any buffered `send`s.\n   * Put subscribe messages here so subscriptions are re-established after a\n   * reconnect without consumer involvement.\n   */\n  getOpenMessages?: () => string[];\n  /** Reconnect tuning. */\n  reconnect?: ReconnectingSocketReconnectOptions;\n  /** Heartbeat tuning. */\n  heartbeat?: ReconnectingSocketHeartbeatOptions;\n  /** Called each time the socket transitions to `open`. */\n  onOpen?: () => void;\n  /** Called each time the underlying connection closes (transient or terminal). */\n  onClose?: (info: SocketCloseInfo) => void;\n  /** Called on a transport-level error; receives the raw error event. */\n  onError?: (event: unknown) => void;\n  /** Called for each inbound frame; `data` is the raw `event.data` (usually a JSON string). */\n  onMessage?: (data: unknown) => void;\n  /** Called whenever {@link SocketStatus} changes. */\n  onStatusChange?: (status: SocketStatus) => void;\n  /** Randomness source for backoff jitter. Injectable for tests; defaults to `Math.random`. */\n  random?: () => number;\n}\n\n/**\n * A managed, self-reconnecting WebSocket handle.\n */\nexport interface ReconnectingSocket {\n  /** Send a text frame now if open, otherwise buffer it until the next open. */\n  send(data: string): void;\n  /** Close permanently (no reconnect), flushing timers. Idempotent. */\n  close(): void;\n  /** Current connection status. */\n  getStatus(): SocketStatus;\n}\n\n/**\n * Create a self-reconnecting WebSocket around an injected implementation.\n *\n * Handles the reliability concerns a raw `WebSocket` does not: exponential\n * backoff with jitter, status transitions, outbound buffering while not open,\n * and re-sending `getOpenMessages()` on every (re)open so subscriptions survive\n * reconnects. Framework-agnostic — no DOM or React assumptions; the socket\n * implementation and randomness are injected.\n *\n * The returned socket starts dialing immediately.\n *\n * @example\n * ```ts\n * const socket = createReconnectingSocket({\n *   url: \"wss://example/ws\",\n *   webSocketConstructor: config.getWebSocketConstructor(),\n *   getOpenMessages: () => [JSON.stringify({ subscribe: account })],\n *   onMessage: (data) => handle(JSON.parse(String(data))),\n * });\n * // later\n * socket.close();\n * ```\n */\nexport function createReconnectingSocket(options: ReconnectingSocketOptions): ReconnectingSocket {\n  const reconnect = {\n    enabled: options.reconnect?.enabled ?? true,\n    maxAttempts: options.reconnect?.maxAttempts ?? Number.POSITIVE_INFINITY,\n    baseDelayMs: options.reconnect?.baseDelayMs ?? 500,\n    maxDelayMs: options.reconnect?.maxDelayMs ?? 10_000,\n    jitter: options.reconnect?.jitter ?? true,\n  };\n  const heartbeat = {\n    enabled: options.heartbeat?.enabled ?? false,\n    intervalMs: options.heartbeat?.intervalMs ?? 30_000,\n    message: options.heartbeat?.message ?? \"ping\",\n  };\n\n  let ws: WebSocketLike | null = null;\n  let status: SocketStatus = \"connecting\";\n  let attempt = 0;\n  let closedByUser = false;\n  let outbox: string[] = [];\n  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;\n  let heartbeatTimer: ReturnType<typeof setInterval> | null = null;\n\n  function setStatus(next: SocketStatus): void {\n    if (status === next) return;\n    status = next;\n    options.onStatusChange?.(next);\n  }\n\n  function clearReconnectTimer(): void {\n    if (reconnectTimer !== null) {\n      clearTimeout(reconnectTimer);\n      reconnectTimer = null;\n    }\n  }\n\n  function stopHeartbeat(): void {\n    if (heartbeatTimer !== null) {\n      clearInterval(heartbeatTimer);\n      heartbeatTimer = null;\n    }\n  }\n\n  function safeSend(target: WebSocketLike, data: string): void {\n    try {\n      if (target.readyState === SOCKET_READY_STATE.OPEN) target.send(data);\n    } catch (err) {\n      options.onError?.(err);\n    }\n  }\n\n  function startHeartbeat(target: WebSocketLike): void {\n    if (!heartbeat.enabled) return;\n    stopHeartbeat();\n    heartbeatTimer = setInterval(() => safeSend(target, heartbeat.message), heartbeat.intervalMs);\n  }\n\n  function connect(): void {\n    clearReconnectTimer();\n    setStatus(\"connecting\");\n\n    let socket: WebSocketLike;\n    try {\n      socket = new options.webSocketConstructor(options.url, options.protocols);\n    } catch (err) {\n      options.onError?.(err);\n      scheduleReconnect();\n      return;\n    }\n    ws = socket;\n\n    socket.onopen = () => {\n      if (ws !== socket) return;\n      attempt = 0;\n      setStatus(\"open\");\n      options.onOpen?.();\n      for (const message of options.getOpenMessages?.() ?? []) safeSend(socket, message);\n      if (outbox.length > 0) {\n        const pending = outbox;\n        outbox = [];\n        for (const message of pending) safeSend(socket, message);\n      }\n      startHeartbeat(socket);\n    };\n\n    socket.onmessage = (event) => {\n      if (ws !== socket) return;\n      options.onMessage?.(event.data);\n    };\n\n    socket.onerror = (event) => {\n      if (ws !== socket) return;\n      options.onError?.(event);\n    };\n\n    socket.onclose = (event) => {\n      if (ws !== socket) return;\n      stopHeartbeat();\n      ws = null;\n\n      const willReconnect = !closedByUser && reconnect.enabled && attempt < reconnect.maxAttempts;\n      options.onClose?.({ code: event?.code, reason: event?.reason, willReconnect });\n\n      if (!willReconnect) {\n        setStatus(\"closed\");\n        return;\n      }\n      scheduleReconnect();\n    };\n  }\n\n  function scheduleReconnect(): void {\n    setStatus(\"reconnecting\");\n    const delay = computeBackoffDelay(attempt, reconnect, options.random);\n    attempt += 1;\n    reconnectTimer = setTimeout(connect, delay);\n  }\n\n  function send(data: string): void {\n    if (ws && ws.readyState === SOCKET_READY_STATE.OPEN) {\n      safeSend(ws, data);\n    } else {\n      outbox.push(data);\n    }\n  }\n\n  function close(): void {\n    if (closedByUser) return;\n    closedByUser = true;\n    clearReconnectTimer();\n    stopHeartbeat();\n    outbox = [];\n\n    if (ws) {\n      setStatus(\"closing\");\n      try {\n        ws.close();\n      } catch {\n        // ignore — onclose may not fire if the socket never opened\n        setStatus(\"closed\");\n      }\n    } else {\n      setStatus(\"closed\");\n    }\n  }\n\n  connect();\n\n  return {\n    send,\n    close,\n    getStatus: () => status,\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"create-reconnecting-socket.js","names":[],"sources":["../../../src/websocket/socket/create-reconnecting-socket.ts"],"sourcesContent":["import type { WebSocketConstructor, WebSocketLike } from \"../../shared/types/websocket\";\nimport { computeBackoffDelay } from \"./backoff\";\nimport { SOCKET_READY_STATE, type SocketStatus } from \"./socket-status\";\n\n/**\n * Reconnect tuning for {@link createReconnectingSocket}. All fields optional;\n * defaults match the SDK's notifications behavior (unlimited retries, 500ms →\n * 10s exponential backoff with jitter).\n */\nexport interface ReconnectingSocketReconnectOptions {\n  /**\n   * Redial when the connection closes, or a dial throws, without `close()`\n   * having been called. The close code is not inspected. Default `true`.\n   */\n  enabled?: boolean;\n  /** Max consecutive retries before giving up. Default `Infinity`. */\n  maxAttempts?: number;\n  /** Delay before the first retry, in ms. Default `500`. */\n  baseDelayMs?: number;\n  /** Upper bound on any single retry delay, in ms. Default `10_000`. */\n  maxDelayMs?: number;\n  /** Apply random jitter to retry delays. Default `true`. */\n  jitter?: boolean;\n}\n\n/**\n * Heartbeat tuning for {@link createReconnectingSocket}. Disabled by default —\n * enable only when the server expects periodic client keepalive frames.\n */\nexport interface ReconnectingSocketHeartbeatOptions {\n  /** Send a periodic keepalive frame while open. Default `false`. */\n  enabled?: boolean;\n  /** Interval between keepalive frames, in ms. Default `30_000`. */\n  intervalMs?: number;\n  /** The keepalive frame to send. Default `\"ping\"`. */\n  message?: string;\n}\n\n/**\n * Reason a socket closed, delivered to {@link ReconnectingSocketOptions.onClose}.\n */\nexport interface SocketCloseInfo {\n  /** WebSocket close code, if the implementation supplied one. */\n  code?: number;\n  /** WebSocket close reason, if any. */\n  reason?: string;\n  /** Whether the connection closed cleanly (the closing handshake completed), if the implementation reported it. */\n  wasClean?: boolean;\n  /**\n   * Whether the socket will attempt to reconnect after this close. Calling\n   * {@link ReconnectingSocket.close} from inside `onClose` cancels a reconnect\n   * reported here as `true`.\n   */\n  willReconnect: boolean;\n}\n\n/**\n * Options for {@link createReconnectingSocket}.\n */\nexport interface ReconnectingSocketOptions {\n  /** Endpoint URL (`ws://` / `wss://`). */\n  url: string;\n  /** Optional subprotocol(s), forwarded to the WebSocket constructor. */\n  protocols?: string | string[];\n  /** WebSocket implementation to dial with (resolve from `config.getWebSocketConstructor()`). */\n  webSocketConstructor: WebSocketConstructor;\n  /**\n   * Frames sent on every (re)open, in order, before any buffered `send`s.\n   * Put subscribe messages here so subscriptions are re-established after a\n   * reconnect without consumer involvement.\n   */\n  getOpenMessages?: () => string[];\n  /** Reconnect tuning. */\n  reconnect?: ReconnectingSocketReconnectOptions;\n  /** Heartbeat tuning. */\n  heartbeat?: ReconnectingSocketHeartbeatOptions;\n  /** Called each time the socket transitions to `open`. */\n  onOpen?: () => void;\n  /**\n   * Called each time the underlying connection closes (transient or terminal).\n   * A dial that throws is reported to `onError` instead, and `close()` while no\n   * connection exists (for example during a backoff wait) settles the status\n   * without calling this.\n   */\n  onClose?: (info: SocketCloseInfo) => void;\n  /** Called on a transport-level error; receives the raw error event. */\n  onError?: (event: unknown) => void;\n  /**\n   * Called for each inbound frame; `data` is the raw `event.data` (usually a\n   * JSON string). Not called after `close()`, even for a frame the\n   * implementation still delivers while the connection finishes closing.\n   */\n  onMessage?: (data: unknown) => void;\n  /** Called whenever {@link SocketStatus} changes. */\n  onStatusChange?: (status: SocketStatus) => void;\n  /** Randomness source for backoff jitter. Injectable for tests; defaults to `Math.random`. */\n  random?: () => number;\n}\n\n/**\n * A managed, self-reconnecting WebSocket handle.\n */\nexport interface ReconnectingSocket {\n  /** Send a text frame now if open, otherwise buffer it until the next open. */\n  send(data: string): void;\n  /**\n   * Close permanently: cancel any pending reconnect, stop the heartbeat, drop\n   * buffered sends, and close the current connection. From this call on no\n   * frame reaches `onMessage`, even while the connection is still closing. Safe\n   * to call from any callback, including `onClose` and `onStatusChange`.\n   * Idempotent — only the first call acts, so a later call's `code` and\n   * `reason` are ignored.\n   *\n   * `code` and `reason` are checked before the connection is touched, the same\n   * way for every implementation and whether or not a connection is open. When\n   * either breaks the limits below, a `RangeError` goes to `onError` and the\n   * connection closes without them.\n   *\n   * @param code - Close code to send: `1000`, or an integer from `3000` to `4999` — the codes the WebSocket standard lets a client send. Any other code is rejected, even one the implementation would send (the `ws` package accepts `1001`).\n   * @param reason - Close reason to send, at most 123 UTF-8 bytes.\n   */\n  close(code?: number, reason?: string): void;\n  /** Current connection status. */\n  getStatus(): SocketStatus;\n}\n\n/** The longest reason a WebSocket close frame can carry, in UTF-8 bytes. */\nconst MAX_CLOSE_REASON_BYTES = 123;\n\n/** Whether a client may send `code`: `1000`, or an integer from `3000` to `4999`. */\nfunction isClientCloseCode(code: number): boolean {\n  return code === 1000 || (Number.isInteger(code) && code >= 3000 && code <= 4999);\n}\n\n/**\n * Why `close(code, reason)` must not send these arguments, or `undefined` when\n * it may. Applies the WebSocket standard's limits for a client.\n */\nfunction getCloseArgumentsError(code?: number, reason?: string): RangeError | undefined {\n  if (code !== undefined && !isClientCloseCode(code)) {\n    return new RangeError(`WebSocket close code ${code} is not allowed; use 1000 or an integer from 3000 to 4999.`);\n  }\n  if (reason === undefined) return undefined;\n  const reasonBytes = new TextEncoder().encode(reason).length;\n  if (reasonBytes <= MAX_CLOSE_REASON_BYTES) return undefined;\n  return new RangeError(\n    `WebSocket close reason is ${reasonBytes} UTF-8 bytes; the limit is ${MAX_CLOSE_REASON_BYTES}.`,\n  );\n}\n\n/**\n * Create a self-reconnecting WebSocket around an injected implementation.\n *\n * Handles the reliability concerns a raw `WebSocket` does not: exponential\n * backoff with jitter, status transitions, outbound buffering while not open,\n * and re-sending `getOpenMessages()` on every (re)open so subscriptions survive\n * reconnects. Framework-agnostic — no DOM or React assumptions; the socket\n * implementation and randomness are injected.\n *\n * The returned socket starts dialing immediately.\n *\n * @example\n * ```ts\n * const socket = createReconnectingSocket({\n *   url: \"wss://example/ws\",\n *   webSocketConstructor: config.getWebSocketConstructor(),\n *   getOpenMessages: () => [JSON.stringify({ subscribe: account })],\n *   onMessage: (data) => handle(JSON.parse(String(data))),\n * });\n * // later\n * socket.close();\n * ```\n */\nexport function createReconnectingSocket(options: ReconnectingSocketOptions): ReconnectingSocket {\n  const reconnect = {\n    enabled: options.reconnect?.enabled ?? true,\n    maxAttempts: options.reconnect?.maxAttempts ?? Number.POSITIVE_INFINITY,\n    baseDelayMs: options.reconnect?.baseDelayMs ?? 500,\n    maxDelayMs: options.reconnect?.maxDelayMs ?? 10_000,\n    jitter: options.reconnect?.jitter ?? true,\n  };\n  const heartbeat = {\n    enabled: options.heartbeat?.enabled ?? false,\n    intervalMs: options.heartbeat?.intervalMs ?? 30_000,\n    message: options.heartbeat?.message ?? \"ping\",\n  };\n\n  let ws: WebSocketLike | null = null;\n  let status: SocketStatus = \"connecting\";\n  let attempt = 0;\n  let closedByUser = false;\n  let outbox: string[] = [];\n  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;\n  let heartbeatTimer: ReturnType<typeof setInterval> | null = null;\n\n  function setStatus(next: SocketStatus): void {\n    if (status === next) return;\n    status = next;\n    options.onStatusChange?.(next);\n  }\n\n  function clearReconnectTimer(): void {\n    if (reconnectTimer !== null) {\n      clearTimeout(reconnectTimer);\n      reconnectTimer = null;\n    }\n  }\n\n  function stopHeartbeat(): void {\n    if (heartbeatTimer !== null) {\n      clearInterval(heartbeatTimer);\n      heartbeatTimer = null;\n    }\n  }\n\n  /**\n   * Whether `target` is still the live connection. Every consumer callback runs\n   * synchronously and may call `close()`, so handlers re-check this after each\n   * callback instead of trusting what they read before it.\n   */\n  function isCurrent(target: WebSocketLike): boolean {\n    return !closedByUser && ws === target;\n  }\n\n  /** Whether a lost connection or failed dial should be retried. */\n  function canReconnect(): boolean {\n    return !closedByUser && reconnect.enabled && attempt < reconnect.maxAttempts;\n  }\n\n  function safeSend(target: WebSocketLike, data: string): void {\n    try {\n      if (target.readyState === SOCKET_READY_STATE.OPEN) target.send(data);\n    } catch (err) {\n      options.onError?.(err);\n    }\n  }\n\n  function startHeartbeat(target: WebSocketLike): void {\n    /** Arming the interval for a connection that is already closed would leak it. */\n    if (!heartbeat.enabled || !isCurrent(target)) return;\n    stopHeartbeat();\n    heartbeatTimer = setInterval(() => safeSend(target, heartbeat.message), heartbeat.intervalMs);\n  }\n\n  function connect(): void {\n    clearReconnectTimer();\n    if (closedByUser) return;\n    setStatus(\"connecting\");\n    /** A status listener may have closed the socket; a dial now would open a connection nothing can close. */\n    if (closedByUser) return;\n\n    let socket: WebSocketLike;\n    try {\n      socket = new options.webSocketConstructor(options.url, options.protocols);\n    } catch (err) {\n      options.onError?.(err);\n      if (canReconnect()) scheduleReconnect();\n      else setStatus(\"closed\");\n      return;\n    }\n    ws = socket;\n\n    socket.onopen = () => {\n      if (!isCurrent(socket)) return;\n      attempt = 0;\n      setStatus(\"open\");\n      if (!isCurrent(socket)) return;\n      options.onOpen?.();\n      if (!isCurrent(socket)) return;\n      for (const message of options.getOpenMessages?.() ?? []) safeSend(socket, message);\n      if (outbox.length > 0) {\n        const pending = outbox;\n        outbox = [];\n        for (const message of pending) safeSend(socket, message);\n      }\n      startHeartbeat(socket);\n    };\n\n    socket.onmessage = (event) => {\n      /**\n       * `isCurrent` also drops frames after `close()`: the `ws` package keeps\n       * delivering what it parses until the closing handshake completes.\n       */\n      if (!isCurrent(socket)) return;\n      options.onMessage?.(event.data);\n    };\n\n    socket.onerror = (event) => {\n      if (ws !== socket) return;\n      options.onError?.(event);\n    };\n\n    socket.onclose = (event) => {\n      if (ws !== socket) return;\n      stopHeartbeat();\n      ws = null;\n\n      const willReconnect = canReconnect();\n      options.onClose?.({ code: event?.code, reason: event?.reason, wasClean: event?.wasClean, willReconnect });\n\n      /** `onClose` may have called `close()`, which overrides the reconnect it was told about. */\n      if (willReconnect && !closedByUser) {\n        scheduleReconnect();\n        return;\n      }\n      setStatus(\"closed\");\n    };\n  }\n\n  function scheduleReconnect(): void {\n    if (closedByUser) return;\n    setStatus(\"reconnecting\");\n    /** A status listener may have closed the socket; a timer armed now would redial after a permanent close. */\n    if (closedByUser) return;\n    const delay = computeBackoffDelay(attempt, reconnect, options.random);\n    attempt += 1;\n    reconnectTimer = setTimeout(connect, delay);\n  }\n\n  function send(data: string): void {\n    if (ws && ws.readyState === SOCKET_READY_STATE.OPEN) {\n      safeSend(ws, data);\n    } else {\n      outbox.push(data);\n    }\n  }\n\n  /**\n   * Close the transport without arguments, then report why they were dropped.\n   * The report goes out even when the implementation refuses to close.\n   */\n  function closeWithoutArguments(target: WebSocketLike, error: unknown): void {\n    try {\n      target.close();\n    } finally {\n      options.onError?.(error);\n    }\n  }\n\n  /**\n   * Close the transport with arguments that passed the check in `close`. A bare\n   * `close()` is forwarded without arguments, so an implementation that\n   * branches on argument count sees the call it always has.\n   */\n  function closeTransport(target: WebSocketLike, code?: number, reason?: string): void {\n    if (code === undefined && reason === undefined) {\n      target.close();\n      return;\n    }\n    try {\n      target.close(code, reason);\n    } catch (err) {\n      /** An implementation stricter than the standard; this recovers one that rejects before it changes state. */\n      closeWithoutArguments(target, err);\n    }\n  }\n\n  function close(code?: number, reason?: string): void {\n    if (closedByUser) return;\n    closedByUser = true;\n    clearReconnectTimer();\n    stopHeartbeat();\n    outbox = [];\n\n    /**\n     * Checked here rather than left to the implementation: browsers and Node's\n     * global `WebSocket` reject before they change state, but the `ws` package\n     * marks itself closing first, so a bare `close()` after its throw does\n     * nothing and the connection stays open. Checked with or without a\n     * connection, so a bad argument is reported whatever the timing.\n     */\n    const argumentsError = getCloseArgumentsError(code, reason);\n    const target = ws;\n    if (!target) {\n      setStatus(\"closed\");\n      if (argumentsError) options.onError?.(argumentsError);\n      return;\n    }\n    setStatus(\"closing\");\n    try {\n      if (argumentsError) {\n        closeWithoutArguments(target, argumentsError);\n      } else {\n        closeTransport(target, code, reason);\n      }\n    } catch {\n      /** The implementation refused to close, so `onclose` may never fire; settle the status here. */\n      setStatus(\"closed\");\n    }\n  }\n\n  connect();\n\n  return {\n    send,\n    close,\n    getStatus: () => status,\n  };\n}\n"],"mappings":";;;AA+HA,IAAM,IAAyB;AAG/B,SAAS,EAAkB,GAAuB;CAChD,OAAO,MAAS,OAAS,OAAO,UAAU,CAAI,KAAK,KAAQ,OAAQ,KAAQ;AAC7E;AAMA,SAAS,EAAuB,GAAe,GAAyC;CACtF,IAAI,MAAS,KAAA,KAAa,CAAC,EAAkB,CAAI,GAC/C,OAAO,gBAAI,WAAW,wBAAwB,EAAK,2DAA2D;CAEhH,IAAI,MAAW,KAAA,GAAW;CAC1B,IAAM,IAAc,IAAI,YAAY,EAAE,OAAO,CAAM,EAAE;CACjD,WAAe,IACnB,OAAO,gBAAI,WACT,6BAA6B,EAAY,6BAA6B,EAAuB,EAC/F;AACF;AAyBA,SAAgB,EAAyB,GAAwD;CAC/F,IAAM,IAAY;EAChB,SAAS,EAAQ,WAAW,WAAW;EACvC,aAAa,EAAQ,WAAW,eAAe;EAC/C,aAAa,EAAQ,WAAW,eAAe;EAC/C,YAAY,EAAQ,WAAW,cAAc;EAC7C,QAAQ,EAAQ,WAAW,UAAU;CACvC,GACM,IAAY;EAChB,SAAS,EAAQ,WAAW,WAAW;EACvC,YAAY,EAAQ,WAAW,cAAc;EAC7C,SAAS,EAAQ,WAAW,WAAW;CACzC,GAEI,IAA2B,MAC3B,IAAuB,cACvB,IAAU,GACV,IAAe,IACf,IAAmB,CAAC,GACpB,IAAuD,MACvD,IAAwD;CAE5D,SAAS,EAAU,GAA0B;EACvC,MAAW,MACf,IAAS,GACT,EAAQ,iBAAiB,CAAI;CAC/B;CAEA,SAAS,IAA4B;EACnC,AAAI,MAAmB,SACrB,aAAa,CAAc,GAC3B,IAAiB;CAErB;CAEA,SAAS,IAAsB;EAC7B,AAAI,MAAmB,SACrB,cAAc,CAAc,GAC5B,IAAiB;CAErB;CAOA,SAAS,EAAU,GAAgC;EACjD,OAAO,CAAC,KAAgB,MAAO;CACjC;CAGA,SAAS,IAAwB;EAC/B,OAAO,CAAC,KAAgB,EAAU,WAAW,IAAU,EAAU;CACnE;CAEA,SAAS,EAAS,GAAuB,GAAoB;EAC3D,IAAI;GACF,AAAI,EAAO,eAAe,EAAmB,QAAM,EAAO,KAAK,CAAI;EACrE,SAAS,GAAK;GACZ,EAAQ,UAAU,CAAG;EACvB;CACF;CAEA,SAAS,EAAe,GAA6B;EAE/C,CAAC,EAAU,WAAW,CAAC,EAAU,CAAM,MAC3C,EAAc,GACd,IAAiB,kBAAkB,EAAS,GAAQ,EAAU,OAAO,GAAG,EAAU,UAAU;CAC9F;CAEA,SAAS,IAAgB;EAKvB,IAJA,EAAoB,GAChB,MACJ,EAAU,YAAY,GAElB,IAAc;EAElB,IAAI;EACJ,IAAI;GACF,IAAS,IAAI,EAAQ,qBAAqB,EAAQ,KAAK,EAAQ,SAAS;EAC1E,SAAS,GAAK;GAEZ,AADA,EAAQ,UAAU,CAAG,GACjB,EAAa,IAAG,EAAkB,IACjC,EAAU,QAAQ;GACvB;EACF;EAiCA,AAhCA,IAAK,GAEL,EAAO,eAAe;GACf,MAAU,CAAM,MACrB,IAAU,GACV,EAAU,MAAM,GACX,EAAU,CAAM,MACrB,EAAQ,SAAS,GACZ,EAAU,CAAM,KACrB;SAAK,IAAM,KAAW,EAAQ,kBAAkB,KAAK,CAAC,GAAG,EAAS,GAAQ,CAAO;IACjF,IAAI,EAAO,SAAS,GAAG;KACrB,IAAM,IAAU;KAChB,IAAS,CAAC;KACV,KAAK,IAAM,KAAW,GAAS,EAAS,GAAQ,CAAO;IACzD;IACA,EAAe,CAAM;GAN4D;EAOnF,GAEA,EAAO,aAAa,MAAU;GAKvB,EAAU,CAAM,KACrB,EAAQ,YAAY,EAAM,IAAI;EAChC,GAEA,EAAO,WAAW,MAAU;GACtB,MAAO,KACX,EAAQ,UAAU,CAAK;EACzB,GAEA,EAAO,WAAW,MAAU;GAC1B,IAAI,MAAO,GAAQ;GAEnB,AADA,EAAc,GACd,IAAK;GAEL,IAAM,IAAgB,EAAa;GAInC,IAHA,EAAQ,UAAU;IAAE,MAAM,GAAO;IAAM,QAAQ,GAAO;IAAQ,UAAU,GAAO;IAAU;GAAc,CAAC,GAGpG,KAAiB,CAAC,GAAc;IAClC,EAAkB;IAClB;GACF;GACA,EAAU,QAAQ;EACpB;CACF;CAEA,SAAS,IAA0B;EAIjC,IAHI,MACJ,EAAU,cAAc,GAEpB,IAAc;EAClB,IAAM,IAAQ,EAAoB,GAAS,GAAW,EAAQ,MAAM;EAEpE,AADA,KAAW,GACX,IAAiB,WAAW,GAAS,CAAK;CAC5C;CAEA,SAAS,EAAK,GAAoB;EAChC,AAAI,KAAM,EAAG,eAAe,EAAmB,OAC7C,EAAS,GAAI,CAAI,IAEjB,EAAO,KAAK,CAAI;CAEpB;CAMA,SAAS,EAAsB,GAAuB,GAAsB;EAC1E,IAAI;GACF,EAAO,MAAM;EACf,UAAU;GACR,EAAQ,UAAU,CAAK;EACzB;CACF;CAOA,SAAS,EAAe,GAAuB,GAAe,GAAuB;EACnF,IAAI,MAAS,KAAA,KAAa,MAAW,KAAA,GAAW;GAC9C,EAAO,MAAM;GACb;EACF;EACA,IAAI;GACF,EAAO,MAAM,GAAM,CAAM;EAC3B,SAAS,GAAK;GAEZ,EAAsB,GAAQ,CAAG;EACnC;CACF;CAEA,SAAS,EAAM,GAAe,GAAuB;EACnD,IAAI,GAAc;EAIlB,AAHA,IAAe,IACf,EAAoB,GACpB,EAAc,GACd,IAAS,CAAC;EASV,IAAM,IAAiB,EAAuB,GAAM,CAAM,GACpD,IAAS;EACf,IAAI,CAAC,GAAQ;GAEX,AADA,EAAU,QAAQ,GACd,KAAgB,EAAQ,UAAU,CAAc;GACpD;EACF;EACA,EAAU,SAAS;EACnB,IAAI;GACF,AAAI,IACF,EAAsB,GAAQ,CAAc,IAE5C,EAAe,GAAQ,GAAM,CAAM;EAEvC,QAAQ;GAEN,EAAU,QAAQ;EACpB;CACF;CAIA,OAFA,EAAQ,GAED;EACL;EACA;EACA,iBAAiB;CACnB;AACF"}

package/dist/websocket/socket/socket-status.d.ts

@@ -1,11 +1,16 @@
 /**
  * Lifecycle state of a managed SDK WebSocket connection.
  *
- * - `connecting` — a socket is dialing for the first time.
+ * - `connecting` — dialing: on the first connect and again each time a backoff wait ends.
  * - `open` — connected; frames flow.
- * - `reconnecting` — the connection dropped and a retry is scheduled (backoff).
+ * - `reconnecting` — the connection dropped, or a dial failed, and a retry is scheduled (backoff).
  * - `closing` — a consumer-initiated close is in progress.
  * - `closed` — terminally closed; no further reconnects.
+ *
+ * A `reconnecting` → `connecting` → `open` cycle is normal after a dropped
+ * connection. No single status marks an outage: a failing endpoint keeps
+ * switching between `reconnecting` and `connecting`, and a server that drops
+ * every connection right after accepting it keeps passing through `open`.
  */
 export type SocketStatus = "connecting" | "open" | "reconnecting" | "closing" | "closed";
 /**

package/dist/websocket/socket/socket-status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"socket-status.d.ts","sourceRoot":"","sources":["../../../src/websocket/socket/socket-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG,MAAM,GAAG,cAAc,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEzF;;;GAGG;AACH,eAAO,MAAM,kBAAkB;;;;;CAKrB,CAAC"}
+{"version":3,"file":"socket-status.d.ts","sourceRoot":"","sources":["../../../src/websocket/socket/socket-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG,MAAM,GAAG,cAAc,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEzF;;;GAGG;AACH,eAAO,MAAM,kBAAkB;;;;;CAKrB,CAAC"}

package/dist/websocket/socket/socket-status.js.map

@@ -1 +1 @@
-{"version":3,"file":"socket-status.js","names":[],"sources":["../../../src/websocket/socket/socket-status.ts"],"sourcesContent":["/**\n * Lifecycle state of a managed SDK WebSocket connection.\n *\n * - `connecting` — a socket is dialing for the first time.\n * - `open` — connected; frames flow.\n * - `reconnecting` — the connection dropped and a retry is scheduled (backoff).\n * - `closing` — a consumer-initiated close is in progress.\n * - `closed` — terminally closed; no further reconnects.\n */\nexport type SocketStatus = \"connecting\" | \"open\" | \"reconnecting\" | \"closing\" | \"closed\";\n\n/**\n * Numeric `readyState` values defined by the WebSocket standard. Named here so\n * the SDK never compares against bare integer literals.\n */\nexport const SOCKET_READY_STATE = {\n  CONNECTING: 0,\n  OPEN: 1,\n  CLOSING: 2,\n  CLOSED: 3,\n} as const;\n"],"mappings":";AAeA,IAAa,IAAqB;CAChC,YAAY;CACZ,MAAM;CACN,SAAS;CACT,QAAQ;AACV"}
+{"version":3,"file":"socket-status.js","names":[],"sources":["../../../src/websocket/socket/socket-status.ts"],"sourcesContent":["/**\n * Lifecycle state of a managed SDK WebSocket connection.\n *\n * - `connecting` — dialing: on the first connect and again each time a backoff wait ends.\n * - `open` — connected; frames flow.\n * - `reconnecting` — the connection dropped, or a dial failed, and a retry is scheduled (backoff).\n * - `closing` — a consumer-initiated close is in progress.\n * - `closed` — terminally closed; no further reconnects.\n *\n * A `reconnecting` → `connecting` → `open` cycle is normal after a dropped\n * connection. No single status marks an outage: a failing endpoint keeps\n * switching between `reconnecting` and `connecting`, and a server that drops\n * every connection right after accepting it keeps passing through `open`.\n */\nexport type SocketStatus = \"connecting\" | \"open\" | \"reconnecting\" | \"closing\" | \"closed\";\n\n/**\n * Numeric `readyState` values defined by the WebSocket standard. Named here so\n * the SDK never compares against bare integer literals.\n */\nexport const SOCKET_READY_STATE = {\n  CONNECTING: 0,\n  OPEN: 1,\n  CLOSING: 2,\n  CLOSED: 3,\n} as const;\n"],"mappings":";AAoBA,IAAa,IAAqB;CAChC,YAAY;CACZ,MAAM;CACN,SAAS;CACT,QAAQ;AACV"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symmio/trading-core",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Framework-agnostic SYMMIO SDK. Contract calls, calculations, and transformations with no framework assumptions.",
   "license": "MIT",
   "homepage": "https://github.com/SYMM-IO/Trading-SDK/tree/main/packages/trading-core#readme",