JavaScript quickstart

Create an object definition and publish its first state with the BigState JavaScript client.

What you will build#

The script creates one object:

quickstart:counter@YOUR_OWNER

It then publishes this JSON state:

{
  "value": {
    "count": 1
  }
}

The object definition is the stable contract and configuration. State is the changing, versioned value associated with that object.

Before you begin#

You need Node.js 22.12 or later, your owner identifier, and an API key that can create objects and set state.

If you do not have these values yet, follow Create an account and save your credentials.

Create the project#

mkdir bigstate-quickstart
cd bigstate-quickstart
npm init -y
npm pkg set type=module
npm install bigstate.client.javascript

Create .env:

BIGSTATE_OWNER=YOUR_OWNER
BIGSTATE_API_KEY=YOUR_API_KEY

Initialize the client#

Create index.js and initialize the HTTP client:

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

const { BIGSTATE_OWNER: owner, BIGSTATE_API_KEY: apiKey } = process.env;

if (!owner || !apiKey) {
  throw new Error('BIGSTATE_OWNER and BIGSTATE_API_KEY are required.');
}

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

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

BIGSTATE_OWNER identifies your namespace and becomes part of OBJECT_NAME. BIGSTATE_API_KEY authenticates every request made by the client.

Publish the first state#

The shortest path starts with stateSet. If OBJECT_NAME does not exist, BigState creates the object automatically and stores the value as its first state.

const publishInitialState = async () => {
  const { data, error } = await client.stateSet(OBJECT_NAME, {
    at: new Date().toISOString(),
    value: { count: 1 },
  });

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

  console.log('Initial state published:', data);
};

You can also include an object definition in this request when you need to control its type, lifetime, validity, version history, or descriptive metadata.

Use the extended flow below when you want object configuration to remain an explicit, separate operation.

See Set object state for all publication modes, request fields, and response parameters.

Create the object separately#

For explicit provisioning, create the definition before publishing any state:

const createObject = async () => {
  const { data, error } = await client.objectCreate(OBJECT_NAME, {
    type: ObjectStateType.JSON,
    ttl: 86400,
    validity: 60,
    versionDeep: 10,
    info: {
      name: 'Quickstart counter',
      desc: 'Counter created by the JavaScript quickstart',
      example: { count: 1 },
    },
  });

  if (error) throw new Error(`Could not create the object: ${error.message}`);
  console.log('Object configured:', data);
};

objectCreate creates the definition when the name is new and updates the existing definition when the same name already exists.

The definition controls how BigState handles this object's state:

• type — the encoding expected for state values; this example uses JSON.
• ttl — the lifetime of the object and its related data, in seconds.
• validity — how long a state is considered current, in seconds.
• versionDeep — how many previous state versions BigState retains.

The info fields describe the object for people reading its configuration. They are not the current counter state. This separate operation is useful when resource provisioning and state publication belong to different application stages or services.

See Create or update an object for the complete object definition and supported field values.

Publish state to the existing object#

After createObject succeeds, publish state without repeating the definition:

const publishState = async () => {
  const { data, error } = await client.stateSet(OBJECT_NAME, {
    at: new Date().toISOString(),
    value: { count: 1 },
  });

  if (error) throw new Error(`Could not publish state: ${error.message}`);
  console.log('State published:', data);
};

stateSet writes the object's current value. The at field records when the publisher produced it, and value contains the JSON data accepted by the object definition.

In the two-request flow, the startup order is intentional: the object must exist before the script publishes state to it. Each successful publication receives its own version number.

To inspect the result afterward, use Get object state or List object versions.

Run the script#

Choose one flow and append its startup code.

For the single-request flow:

const run = async () => {
  await publishInitialState();
};

For separate provisioning and publication:

const run = async () => {
  await createObject();
  await publishState();
};

Finish index.js with the shared error handler:

run().catch(error => {
  console.error(error);
  process.exitCode = 1;
});

Run the selected flow:

node --env-file=.env index.js

A successful single request prints the state result and its new version number:

Initial state published: { action: 1, version: 1 }

The separate flow prints the object result first, followed by the state result. Exact actions and versions can differ when you run either flow again.

Next steps#