Quickstart

Create an object definition and publish its first state.

Define the object

Create a named JSON resource that describes the state BigState will accept.

Publish state

Write a timestamped value and receive the version assigned by BigState.

What you will build#

This example 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 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.

Run this example in a trusted environment

The requests use an API key that can write data.

Keep the key out of browser code and source control.

Create the project#

Node.js 22.12 or later. The samples below belong in one index.js file.


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#

BIGSTATE_OWNER identifies your namespace and becomes part of the object name. BIGSTATE_API_KEY is sent as x-api-key on each request.

The constructor takes the API origin. The client does not store the API key, so each call carries it on the request. A successful call returns statusCode and, when the response has a body, data.


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('https://api.bigstate.dev');

Publish the first state#

The shortest path is to set object state. If the object does not exist, BigState creates it and stores the value as its first state.


const publishInitialState = async () => {
	const { statusCode, data } = await client.stateUpsert({
		apiKey,
		query: { object: OBJECT_NAME },
		body: {
			at: new Date().toISOString(),
			value: { count: 1 },
		},
	});

	if (statusCode < 200 || statusCode >= 300) {
		throw new Error(`Could not publish state: ${statusCode}`);
	}

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

A successful response is 200 and includes the action and the new version:


{ "action": 1, "version": 1 }

You can also include an object definition in the body when you need to control its type, lifetime, validity, version history, or descriptive metadata. Use the flow below when object configuration should stay a separate request.

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

Create the object separately#

For explicit provisioning, create or update an object before publishing any state. type 2 is JSON. See request parameters.


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

	if (statusCode < 200 || statusCode >= 300) {
		throw new Error(`Could not create the object: ${statusCode}`);
	}

	console.log('Object configured:', data);
};

The create-or-update call creates the definition when the name is new and updates it when the same name already exists. A successful response is 200 with "action": 1 when the object is created.

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

type — the encoding expected for state values; 2 is 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 the object exists, publish state without repeating the definition. The object name selects the object. at records when the publisher produced the value, and value contains the JSON data accepted by the definition.


const publishState = async () => {
	const { statusCode, data } = await client.stateUpsert({
		apiKey,
		query: { object: OBJECT_NAME },
		body: {
			at: new Date().toISOString(),
			value: { count: 1 },
		},
	});

	if (statusCode < 200 || statusCode >= 300) {
		throw new Error(`Could not publish state: ${statusCode}`);
	}

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

In the two-request flow, the object must exist before you publish 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#

Choose one flow and append it to index.js.

Single request:


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

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

Separate provisioning and publication:


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


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


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

Action 1 means created. Running either flow again can return action 2 and a higher version.

Next steps#

Authentication Deliver and read state

What you will build
Before you begin
Create the project
Initialize the client
Publish the first state
Create the object separately
Publish state to the existing object
Run
Next steps