SharedStateManagerServer

server. SharedStateManagerServer

Component dedicated at managing distributed states among the application. The SharedStateManagerServer extends the SharedStateManagerClient with additionnal functionnalities to register schemas and handle clients.

An instance of SharedStateManagerServer is automatically created by the soundworks.Server at initialization (cf. server.Server#stateManager).

Tutorial: https://collective-soundworks.github.io/tutorials/state-manager.html

Constructor

new SharedStateManagerServer()

Source:
See:

Extends

Methods

(async) attach(schemaName, stateIdopt)

Source:
Overrides:
See:

Attach to an existing common.SharedState instance.

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:

common.SharedState

(async) create(schemaName, initValuesopt)

Source:
Overrides:
See:

Create a common.SharedState instance from a previsouly registered 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:

common.SharedState

deleteSchema(schemaName)

Source:

Delete a schema and all associated states. When a schema is deleted, all states created from this schema are deleted as well, therefore all attached clients are detached and the onDetach and onDelete callbacks are called on the related states.

Parameters:
Name Type Description
schemaName String

Name of the schema.

observe(callback)

Source:
Overrides:

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

Example
this.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 Description
callback client.SharedStateManagerClient~observeCallback

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

registerSchema(schemaName, schema)

Source:
See:

Register a schema from which shared states (cf. common.SharedState) can be instanciated.

Example
server.stateManager.registerSchema('my-schema', {
  myBoolean: {
    type: 'boolean'
    default: false,
  },
  myFloat: {
    type: 'float'
    default: 0.1,
    min: -1,
    max: 1
  }
})
Parameters:
Name Type Description
schemaName String

Name of the schema.
schema server.SharedStateManagerServer~schema

Data structure describing the states that will be created from this schema.

registerUpdateHook(schemaName, updateHook)

Source:

Register a function for a given schema (e.g. will be applied on all states created from this schema) that will be executed before the update values are propagated. For example, this could be used to implement a preset system where all the values of the state are updated from e.g. some data stored in filesystem while the consumer of the state only want to update the preset name.

The hook is associated to every state of its kind (i.e. schemaName) and executed on every update (call of set). Note that the hooks are executed server-side regarless the node on which set has been called and before the "actual" update of the state (e.g. before the call of subscribe).

Example
server.stateManager.registerSchema('hooked', schema);
server.stateManager.registerUpdateHook('hooked', (updates, currentValues) => {
  return {
    ...updates
    numUpdates: currentValues.numUpdates + 1,
  };
});

const state = await server.stateManager.create('hooked');

await state.set({ name: 'test' });
state.getValues();
// > { name: 'test', numUpdates: 1 };
Parameters:
Name Type Description
schemaName String

Kind of states on which applying the hook.
updateHook server.SharedStateManagerServer~updateHook

Function called between the set call and the actual update.

Type Definitions

schema

Source:

Description of a schema to be register by the server.ServerStateManagerServer A schema consists of a combinaison of key value pairs where the key is the name of the parameter, and the value is an object describing the parameter.

Available types are:

Type:
  • Object
Example
{
  myBoolean: {
    type: 'boolean'
    default: false,
  },
  myFloat: {
    type: 'float'
    default: 0.1,
    min: -1,
    max: 1,
    event: true,
  }
}

schemaAnyDef

Source:
Properties:
Name Type Attributes Default Description
type String <optional>
 'any'

Parameter of any type.
default Mixed

Default value of the parameter.
nullable Boolean <optional>
 false

Define if the parameter is nullable. If set to true the parameter default is set to null.
event Boolean <optional>
 false

Define if the parameter is a volatile, e.g. set its value back to null after propagation. When true, nullable is automatically set to true and default to null.
filterChange Boolean <optional>
 true

Setting this option to false forces the propagation of a parameter even when its value do not change. It offers a kind of middle ground between the default bahavior (e.g. where only changed values are propagated) and the behavior of the event option (which has no state per se). As such, setting this options to false if event=true does not make sens.
immediate Boolean <optional>
 false

Setting this option to true will trigger any change (e.g. call the subscribe listeners) immediately on the state that generate the update (i.e. calling set), before propagating the change on the network. This option can be usefull in cases the network would introduce a noticeable latency on the client. If for some reason the value is overriden server-side (e.g. in an updateHook) the listeners will be called again on when the "real" / final value will be received.
metas Object <optional>
 {}

Optionnal metadata of the parameter.

Note that the any type always return a shallow copy of the state internal value. Mutating the returned value will not modify the internal state.

Type:
  • Object

schemaBooleanDef

Source:
Properties:
Name Type Attributes Default Description
type String 'boolean'

Define a boolean parameter.
default Boolean

Default value of the parameter.
nullable Boolean <optional>
 false

Define if the parameter is nullable. If set to true the parameter default is set to null.
event Boolean <optional>
 false

Define if the parameter is a volatile, e.g. set its value back to null after propagation. When true, nullable is automatically set to true and default to null.
filterChange Boolean <optional>
 true

Setting this option to false forces the propagation of a parameter even when its value do not change. It offers a kind of middle ground between the default bahavior (e.g. where only changed values are propagated) and the behavior of the event option (which has no state per se). As such, setting this options to false if event=true does not make sens.
immediate Boolean <optional>
 false

Setting this option to true will trigger any change (e.g. call the subscribe listeners) immediately on the state that generate the update (i.e. calling set), before propagating the change on the network. This option can be usefull in cases the network would introduce a noticeable latency on the client. If for some reason the value is overriden server-side (e.g. in an updateHook) the listeners will be called again on when the "real" / final value will be received.
metas Object <optional>
 {}

Optionnal metadata of the parameter.
Type:
  • Object

schemaEnumDef

Source:
Properties:
Name Type Attributes Default Description
type String <optional>
 'enum'

Enum parameter.
default Mixed

Default value of the parameter.
list Array

Possible values of the parameter.
nullable Boolean <optional>
 false

Define if the parameter is nullable. If set to true the parameter default is set to null.
event Boolean <optional>
 false

Define if the parameter is a volatile, e.g. set its value back to null after propagation. When true, nullable is automatically set to true and default to null.
filterChange Boolean <optional>
 true

Setting this option to false forces the propagation of a parameter even when its value do not change. It offers a kind of middle ground between the default bahavior (e.g. where only changed values are propagated) and the behavior of the event option (which has no state per se). As such, setting this options to false if event=true does not make sens.
immediate Boolean <optional>
 false

Setting this option to true will trigger any change (e.g. call the subscribe listeners) immediately on the state that generate the update (i.e. calling set), before propagating the change on the network. This option can be usefull in cases the network would introduce a noticeable latency on the client. If for some reason the value is overriden server-side (e.g. in an updateHook) the listeners will be called again on when the "real" / final value will be received.
metas Object <optional>
 {}

Optionnal metadata of the parameter.
Type:
  • Object

schemaFloatDef

Source:
Properties:
Name Type Attributes Default Description
type String <optional>
 'float'

Float parameter.
default Mixed

Default value.
min Number <optional>
 -Infinity

Minimum value.
max Number <optional>
 +Infinity

Maximum value.
nullable Boolean <optional>
 false

Define if the parameter is nullable. If set to true the parameter default is set to null.
event Boolean <optional>
 false

Define if the parameter is a volatile, e.g. set its value back to null after propagation. When true, nullable is automatically set to true and default to null.
filterChange Boolean <optional>
 true

Setting this option to false forces the propagation of a parameter even when its value do not change. It offers a kind of middle ground between the default bahavior (e.g. where only changed values are propagated) and the behavior of the event option (which has no state per se). As such, setting this options to false if event=true does not make sens.
immediate Boolean <optional>
 false

Setting this option to true will trigger any change (e.g. call the subscribe listeners) immediately on the state that generate the update (i.e. calling set), before propagating the change on the network. This option can be usefull in cases the network would introduce a noticeable latency on the client. If for some reason the value is overriden server-side (e.g. in an updateHook) the listeners will be called again on when the "real" / final value will be received.
metas Object <optional>
 {}

Optionnal metadata of the parameter.
Type:
  • Object

schemaIntegerDef

Source:
Properties:
Name Type Attributes Default Description
type String 'integer'

Define a boolean parameter.
default Mixed

Default value of the parameter.
min Number <optional>
 -Infinity

Minimum value of the parameter.
max Number <optional>
 +Infinity

Maximum value of the parameter.
nullable Boolean <optional>
 false

Define if the parameter is nullable. If set to true the parameter default is set to null.
event Boolean <optional>
 false

Define if the parameter is a volatile, e.g. set its value back to null after propagation. When true, nullable is automatically set to true and default to null.
filterChange Boolean <optional>
 true

Setting this option to false forces the propagation of a parameter even when its value do not change. It offers a kind of middle ground between the default bahavior (e.g. where only changed values are propagated) and the behavior of the event option (which has no state per se). As such, setting this options to false if event=true does not make sens.
immediate Boolean <optional>
 false

Setting this option to true will trigger any change (e.g. call the subscribe listeners) immediately on the state that generate the update (i.e. calling set), before propagating the change on the network. This option can be usefull in cases the network would introduce a noticeable latency on the client. If for some reason the value is overriden server-side (e.g. in an updateHook) the listeners will be called again on when the "real" / final value will be received.
metas Object <optional>
 {}

Optionnal metadata of the parameter.
Type:
  • Object

schemaStringDef

Source:
Properties:
Name Type Attributes Default Description
type String 'string'

Define a boolean parameter.
default Mixed

Default value of the parameter.
nullable Boolean <optional>
 false

Define if the parameter is nullable. If set to true the parameter default is set to null.
event Boolean <optional>
 false

Define if the parameter is a volatile, e.g. set its value back to null after propagation. When true, nullable is automatically set to true and default to null.
filterChange Boolean <optional>
 true

Setting this option to false forces the propagation of a parameter even when its value do not change. It offers a kind of middle ground between the default bahavior (e.g. where only changed values are propagated) and the behavior of the event option (which has no state per se). As such, setting this options to false if event=true does not make sens.
immediate Boolean <optional>
 false

Setting this option to true will trigger any change (e.g. call the subscribe listeners) immediately on the state that generate the update (i.e. calling set), before propagating the change on the network. This option can be usefull in cases the network would introduce a noticeable latency on the client. If for some reason the value is overriden server-side (e.g. in an updateHook) the listeners will be called again on when the "real" / final value will be received.
metas Object <optional>
 {}

Optionnal metadata of the parameter.
Type:
  • Object

updateHook(updates, currentValues, contextopt) → {Object}

Source:
Parameters:
Name Type Attributes Default Description
updates Object

Update object as given on a set callback, or result of the previous hook
currentValues Object

Current values of the state.
context Object <optional>
 null

Optionnal context passed by the creator of the update.
Returns:

The "real" updates to be applied on the state.

Type
Object