StateManager

client. StateManager

The StateManager allows to create new client.SharedStates, or attach to client.SharedStates created by other nodes (clients or server). It can also track all the client.SharedStates created by other nodes.

An instance of StateManager is automatically created by the soundworks.Client at initialization (cf. client.Client#stateManager).

See client.Client#stateManager

Tutorial: https://soundworks.dev/guide/state-manager.html

// server-side
import { Server } from '@soundworks/server/index.js';

const server = new Server(config);
// declare and register the schema of a shared state.
server.stateManager.registerSchema('some-global-state', {
  myRandom: {
    type: 'float',
    default: 0,
  }
});

await server.start();

// create a global state server-side
const globalState = await server.stateManager.create('some-global-state');
// listen and react to the changes made by the clients
globalState.onUpdate(updates => console.log(updates));

// client-side
import { Client } from '@soundworks/client.index.js';

const client = new Client(config);
await client.start();

// attach to the global state created by the server
const globalState = await client.stateManager.attach('some-global-state');

// update the value of a `myRandom` parameter every seconds
setInterval(() => {
  globalState.set({ myRandom: Math.random() });
}, 1000);

Extends

Methods

(async) attach(schemaName, stateIdopt) → {client.SharedState|server.SharedState}

Description:

  • Attach to an existing SharedState instance.

Source:
Inherited From:
See:
Example
const state = await client.stateManager.attach('my-schema');
Parameters:
Name Type Attributes Default Description
schemaName String

Name of the schema as given on registration (cf. ServerStateManager)
stateId Object <optional>
 null

Id of the state to attach to. If null, attach to the first state found with the given schema name (usefull for globally shared states owned by the server).
Returns:
Type
client.SharedState | server.SharedState

(async) create(schemaName, initValuesopt) → {client.SharedState|server.SharedState}

Description:

  • Create a SharedState instance from a registered schema.

Source:
Inherited From:
See:
Example
const state = await client.stateManager.create('my-schema');
Parameters:
Name Type Attributes Default Description
schemaName String

Name of the schema as given on registration (cf. ServerStateManager)
initValues Object <optional>
 {}

Default values for the state.
Returns:
Type
client.SharedState | server.SharedState

(async) getCollection(schemaName) → {server.SharedStateCollection|client.SharedStateCollection}

Description:

  • Returns a collection of all the states created from the schema name. Except the ones created by the current node.

Source:
Inherited From:
Parameters:
Name Type Description
schemaName string

Name of the schema.
Returns:
Type
server.SharedStateCollection | client.SharedStateCollection

(async) observe(schemaNameopt, callback) → {Promise.<function()>}

Description:

  • Observe all the SharedState instances that are created on the network. This can be usefull for clients with some controller role that might want to track the state of all other clients of the application, to monitor them and/or take control over them from a single point.

    Notes:

    • The states that are created by the same node are not propagated through the observe callback.
    • The order of execution is not guaranted, i.e. an state attached in the observe callback could be created before the async create method resolves.
Source:
Inherited From:
Example
client.stateManager.observe(async (schemaName, stateId, nodeId) => {
  if (schemaName === 'something') {
    const state = await this.client.stateManager.attach(schemaName, stateId);
    console.log(state.getValues());
  }
});
Parameters:
Name Type Attributes Description
schemaName String <optional>

optionnal schema name to filter the observed states.
callback server.StateManager~ObserveCallback | client.StateManager~ObserveCallback

Function to be called when a new state is created on the network.
Returns:
  • Returns a Promise that resolves when the given callback as been executed on each existing states. The promise value is a function which allows to stop observing the states on the network.
Type
Promise.<function()>

Type Definitions

(async) ObserveCallback(schemaName, stateId, nodeId)

Source:
Parameters:
Name Type Description
schemaName String

name of the schema
stateId Number

id of the state
nodeId Number

id of the node that created the state