ClientStateManager

ClientStateManager

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

An instance of ClientStateManager 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, stateIdOrFilteropt, filteropt) → {Promise.<SharedState>}

Description:

  • Attach to an existing SharedState instance.

    Alternative signatures:

    • stateManager.attach(schemaName)
    • stateManager.attach(schemaName, stateId)
    • stateManager.attach(schemaName, filter)
    • stateManager.attach(schemaName, stateId, filter)
Source:
Inherited From:
Example
const state = await client.stateManager.attach('my-class');
Parameters:
Name Type Attributes Default Description
schemaName string

Name of the schema as given on registration
stateIdOrFilter number | Array.<string> <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).
filter Array.<string> <optional>
 null

List of parameters of interest in the returned state. If set to null, no filter is applied.
Returns:
Type
Promise.<SharedState>

(async) create(schemaName, initValuesopt) → {Promise.<SharedState>}

Description:

  • Create a SharedState instance from a registered schema.

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

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

Default values for the state.
Returns:
Type
Promise.<SharedState>

(async) getCollection(schemaName, filteropt, optionsopt) → {Promise.<SharedStateCollection>}

Description:

  • Returns a collection of all the states created from the schema name.

    Alternative signatures:

    • stateManager.getCollection(schemaName)
    • stateManager.getCollection(schemaName, filter)
    • stateManager.getCollection(schemaName, options)
    • stateManager.getCollection(schemaName, filter, options)
Source:
Inherited From:
Example
const collection = await client.stateManager.getCollection(schemaName);
Parameters:
Name Type Attributes Default Description
schemaName string

Name of the schema.
filter array | null <optional>
 null

Filter parameter of interest for each state of the collection. If set to null, no filter applied.
options object <optional>
 {}

Options.

Properties
Name Type Attributes Default Description
excludeLocal boolean <optional>
 false

If set to true, exclude states created by the same node from the collection.
Returns:
Type
Promise.<SharedStateCollection>

(async) getSchema(schemaName) → {SharedStateSchema}

Description:

  • Return the schema from a given registered schema name

Source:
Inherited From:
Example
const schema = await client.stateManager.getSchema('my-class');
Parameters:
Name Type Description
schemaName String

Name of the schema as given on registration (cf. ServerStateManager)
Returns:
Type
SharedStateSchema

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

Description:

  • Observe all the SharedState instances that are created on the network.

    Notes:

    • The order of execution is not guaranted between nodes, i.e. a state attached in the observe callback can be instantiated before the async create method resolves on the creator node.
    • Filtering, i.e. observedSchemaName and options.excludeLocal are handled on the node side, the server just notify all state creation activity and the node executes the given callbacks according to the different filter rules. Such strategy allows to simply share the observe notifications between all observers.

    Alternative signatures:

    • stateManager.observe(callback)
    • stateManager.observe(schemaName, callback)
    • stateManager.observe(callback, options)
    • stateManager.observe(schemaName, callback, options)
Source:
Inherited From:
Example
client.stateManager.observe(async (schemaName, stateId) => {
  if (schemaName === 'my-shared-state-class') {
    const attached = await client.stateManager.attach(schemaName, stateId);
  }
});
Parameters:
Name Type Attributes Description
schemaName string <optional>

optionnal schema name to filter the observed states.
callback stateManagerObserveCallback

Function to be called when a new state is created on the network.
options object

Options.

Properties
Name Type Attributes Default Description
excludeLocal boolean <optional>
 false

If set to true, exclude states created locally, i.e. by the same node, from the collection.
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.<stateManagerDeleteObserveCallback>

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