Deliver and read state in JavaScript

Choose between dynamic WebSocket delivery and direct HTTP reads based on how your application consumes state.

Choose a state access model#

BigState stores state independently from its delivery configuration:

• Use WebSocket delivery when a dashboard, browser, or service must react to changes continuously.
• Use the latest-state request when loading a page, restoring application state, or checking the current value on demand.
• Use a versioned request when you need one previously recorded state.

A common application combines both models: read the latest state during startup, then subscribe for subsequent updates.

Before you begin#

You need an existing object with published state, your owner identifier, and credentials that can access that object.

If you have not published state yet, complete the JavaScript quickstart.

Configure a WebSocket delivery#

A delivery is a routing configuration that selects object updates. Create it once from a trusted setup script:

import { BigStateHttpClient, DeliveryType } from 'bigstate.client.javascript';

const owner = process.env.BIGSTATE_OWNER;
const apiKey = process.env.BIGSTATE_API_KEY;

const OBJECT_NAME = `quickstart:counter@${owner}`;
const DELIVERY_NAME = 'deliveryWsQuickstart';

const client = new BigStateHttpClient({
  baseUrl: 'https://api.bigstate.dev',
  apiKey,
});

const { error } = await client.deliveryCreate(DELIVERY_NAME, {
  name: 'Quickstart WebSocket delivery',
  type: DeliveryType.WS,
  objects: [OBJECT_NAME],
});

if (error) {
  throw new Error(`Could not configure delivery: ${error.message}`);
}

objects determines which updates match this delivery. This example uses one fully qualified object name; delivery configurations can also use supported object patterns.

See Create or update a delivery for all delivery types, fields, and response codes.

Receive dynamic updates over WebSocket#

Initialize BigStateWsDeliveryClient with the subscriber credential:

import { BigStateWsDeliveryClient } from 'bigstate.client.javascript';

const OWNER = 'YOUR_OWNER';
const API_KEY = 'YOUR_RESTRICTED_API_KEY';

const OBJECT_NAME = `quickstart:counter@${OWNER}`;
const DELIVERY_NAME = 'deliveryWsQuickstart';

const deliveryClient = new BigStateWsDeliveryClient({
  baseUrl: 'https://ws.delivery.bigstate.dev',
  apiKey: API_KEY,
});

const handleNotification = message => {
  console.log('Delivery notification:', message);
};

deliveryClient.setDeliveries([DELIVERY_NAME]);
deliveryClient.setMessageHandlers([handleNotification]);

setDeliveries selects the configured delivery and opens the socket. setMessageHandlers installs the callbacks that process incoming notifications.

To open the same connection with the native browser WebSocket API instead of the SDK, see Connect to WebSocket delivery.

Notification types#

Every handler receives an object with type and data. The type determines the shape of data:

• message — an object event delivered by BigState. data contains action, owner, object, and, when applicable, state.
• info — a connection lifecycle notification, such as webSocket opened or webSocket closed. The description is available in data.message.
• error — a connection or server error. data contains error and may include code, description, and the original requested message.

A delivered state notification has this structure:

message
└── data
    ├── object
    └── state
        ├── at
        ├── version
        └── value

One delivery can match multiple objects, so applications can inspect message.type and message.data.object when they need to route notifications to different parts of the UI.

Read the latest state over HTTP#

Use the HTTP client when you need the current value immediately rather than waiting for the next delivery:

import { BigStateHttpClient } from 'bigstate.client.javascript';

const client = new BigStateHttpClient({
  baseUrl: 'https://api.bigstate.dev',
  apiKey: 'YOUR_API_KEY',
});

const { data, error } = await client.stateGet({
  object: 'quickstart:counter@YOUR_OWNER',
});

if (error) {
  throw new Error(`Could not get state: ${error.message}`);
}

console.log('Latest state:', data);

The response includes the object name, owner, timestamp, version, encoding type, and either value or valueRef.

Read a specific state version#

Pass version with the same object name:

const { data, error } = await client.stateGet({
  object: 'quickstart:counter@YOUR_OWNER',
  version: 3,
});

if (error) {
  throw new Error(`Could not get version 3: ${error.message}`);
}

console.log('State version 3:', data);

If you do not know the required version number, list the object's recorded versions first:

const { data, error } = await client.getVersionList(
  'quickstart:counter@YOUR_OWNER',
);

if (error) {
  throw new Error(`Could not list versions: ${error.message}`);
}

console.log('Available versions:', data);

See Get object state for latest and versioned reads, and List object versions for the version-history response.

Next steps#