Extended WebSocket client

BigStateWsDeliveryClientExtended stores the delivery host and credential, opens the socket when you add deliveries, resends delivery.listen after reconnect, and keeps the handler list.

The base BigStateWsDeliveryClient is documented on Connect to WebSocket delivery. React, Angular, and Vue call this extended client for you.

WS
new BigStateWsDeliveryClientExtended(options)

Install#

  • npm
    npm install bigstate.client.javascript

constructor(options)#

Create the client once. Assign client.apiKey or client.token later to replace the credential used on the next connect. The host is the delivery origin without /v1.
  • baseUrlstring
    Required

    Delivery host. The client appends `/v1` automatically.

    example: https://ws.delivery.bigstate.dev
  • apiKeystring
    Optional

    API key used to authenticate the socket. Provide either `apiKey` or `token`.

    example: YOUR_RESTRICTED_API_KEY
  • tokenstring
    Optional

    Session token used to authenticate the socket. Provide either `apiKey` or `token`.

  • maxReconnectCountnumber
    Optional

    Maximum reconnect attempts per outage before giving up. Default: `500`.

    example: 500
  • reconnectTimenumber
    Optional

    Base delay in milliseconds for the rapid reconnect phase. Default: `5000`.

    example: 5000
  • reconnectLinearStepMsnumber
    Optional

    Step in milliseconds for the long reconnect phase after the rapid window. Default: `300000` (5 minutes).

    example: 300000
  • debugboolean
    Optional

    Enable verbose lifecycle logs. Pass `true` for console output, or a function `(message, ...args) => void` for a custom logger.

    example: true

Deliveries#

The client remembers delivery ids. The first add or set opens the socket and sends delivery.listen for each id. Later adds send listen only for the new ids. After a reconnect, listen is sent again for every id still tracked.

addDeliveries(deliveries)#

Append ids. An empty array does nothing.
  • deliveriesarray[string]
    Required

    Delivery identifiers to append without removing existing ones.

    example: 
    [

      "deliveryWsCharts"

    ]

setDeliveries(deliveries)#

Replace the tracked ids. An empty array clears them and closes the socket.
  • deliveriesarray[string]
    Required

    Delivery identifiers to listen to.

    example: 
    [

      "deliveryWsQuickstart"

    ]

clearDeliveries()#

Drops every tracked id and closes the socket. This close does not reconnect.

Handlers#

A handler is (notification) => void. The same function reference is stored once.

addMessageHandler(handler)#

  • handlerobject
    Required

    Handler to append. Duplicates by reference are ignored.

setMessageHandlers(handlers)#

  • handlersarray
    Required

    Handlers that receive message, info, and error notifications.

removeMessageHandler(handler)#

  • handlerobject
    Required

    Handler reference previously passed to add or set.

clearMessageHandlers()#

Removes every handler. Tracked deliveries stay in place.

disconnect()#

Clears deliveries and handlers, then closes the socket. This close does not reconnect.

isSocketConnected()#

Returns whether the client currently holds a socket. client.api is the base BigStateWsDeliveryClient underneath.

Notifications#

Every handler receives this object.
  • typestring
    Required

    Notification kind from `NotificationType`.

    Values

    • NotificationType.Message — `"message"`
    • NotificationType.Info — `"info"`
    • NotificationType.Error — `"error"`
    example: message
  • dataobject
    Required

    Payload shape depends on `type`.

    • data.actionnumber
      Optional

      Present on `message`. Object action that triggered the delivery.

      Values

      • 1 — create
      • 2 — update
      • 3 — delete
    • data.ownerstring
      Optional

      Present on `message`. Owner of the delivered object.

    • data.objectstring
      Optional

      Present on `message`. Fully qualified object name.

    • data.stateobject
      Optional

      Present on `message` when included. Snapshot with `at`, `version`, `type`, and `value` or `valueRef`.

    • data.messagestring
      Optional

      Present on `info`. Lifecycle description, such as `webSocket opened` or `webSocket closed`.

    • data.errorstring
      Optional

      Present on `error`. Error summary.

    • data.codeany
      Optional

      Present on `error`. Optional numeric or string error code.

    • data.descriptionstring
      Optional

      Present on `error`. Optional human-readable details.

    • data.requestedobject
      Optional

      Present on `error`. Original subscribe frame that caused the error, when available.

Close and reconnect#

An unintentional close starts reconnect. For the first five minutes the client retries immediately once, then waits reconnectTime (default 5000 ms) and doubles that wait up to five minutes. After five minutes the wait becomes 1×, 2×, 3× reconnectLinearStepMs (default five minutes).

Reconnect stops after maxReconnectCount attempts (default 500). The client then clears handlers and deliveries and emits an error notification. disconnect(), clearDeliveries(), and close code 3001 do not reconnect. A successful open resets the counters and sends delivery.listen again.

Example#

Subscribe with a restricted credential. The socket opens on setDeliveries.
  • Listen
    import {

    	BigStateWsDeliveryClientExtended,

    	NotificationType,

    } from 'bigstate.client.javascript';

    

    const delivery = new BigStateWsDeliveryClientExtended({

    	baseUrl: 'https://ws.delivery.bigstate.dev',

    	apiKey: 'YOUR_RESTRICTED_API_KEY',

    });

    

    delivery.setDeliveries(['deliveryWsQuickstart']);

    delivery.setMessageHandlers([

    	(notice) => {

    		if (notice.type !== NotificationType.Message) return;

    		console.log(notice.data.object, notice.data.state);

    	},

    ]);
JavaScriptFrameworks

© 2024 BigState