@ircam/parameters

Tiny and extendable library for class parameters type checking and reflection.

Install

npm install [--save] @ircam/parameters

Usage

import parameters from '@ircam/parameters'

const definitions = {
  myBooleanParam: {
    type: 'boolean',
    default: false,
    constant: false,
    metas: { kind: 'static' }
  },
  myIntegerParam: {
    type: 'integer',
    min: 0,
    max: Infinity,
    default: 0,
    constant: false,
    metas: {
      kind: 'static',
      shortDescr: 'My First Integer Param',
      fullDescr: 'This parameter is my first integer parameter in this example.',
      unit: '%',
      step: 1,
      max: 100,
    }
  },
  // ...
};

class MyClass {
  constructor(options) {
    this.params = parameters(definitions, options);

    this.params.addListener((name, value, metas) => {
      // ...
    });

    this.params.addParamListener('myIntegerParam', (value, metas) => {
      // ...
    });
  }
}

const myInstance = new MyClass({ myIntegerParam: 42 });

const bValue = myInstance.params.get('myBooleanParam');
> false

const iValue = myInstance.params.get('myIntegerParam');
> 42

myInstance.params.set('myIntegerParam', definitions.myIntegerParam.min - 1);

API

ParameterBag

Bag of parameters. Main interface of the library

Kind: global class

• ParameterBag
  • instance
    • .getDefinitions() ⇒ Object
    • .getValues() ⇒ Object
    • .get(name) ⇒ Mixed
    • .set(name, value, [forcePropagation]) ⇒ Mixed
    • .has(name) ⇒ Boolean
    • .reset([name])
    • .addListener(callback)
    • .removeListener(callback)
    • .addParamListener(name, callback, [trigger])
    • .removeParamListener(name, callback)
  • inner
    • ~listenerCallback : function
    • ~paramListenerCallack : function

parameterBag.getDefinitions() ⇒ Object

Return the given definitions along with the initialization values.

Kind: instance method of ParameterBag

parameterBag.getValues() ⇒ Object

Return values of all parameters as a flat object.

Kind: instance method of ParameterBag

parameterBag.get(name) ⇒ Mixed

Return the value of the given parameter.

Kind: instance method of ParameterBag
Returns: Mixed - - Value of the parameter.

| Param | Type | Description | | --- | --- | --- | | name | String | Name of the parameter. |

parameterBag.set(name, value, [forcePropagation]) ⇒ Mixed

Set the value of a parameter. If the value of the parameter is updated (aka if previous value is different from new value) all registered callbacks are registered.

Kind: instance method of ParameterBag
Returns: Mixed - - New value of the parameter.

| Param | Type | Default | Description | | --- | --- | --- | --- | | name | String | | Name of the parameter. | | value | Mixed | | Value of the parameter. | | [forcePropagation] | Boolean | false | if true, propagate value even if the value has not changed. |

parameterBag.has(name) ⇒ Boolean

Define if the name parameter exists or not.

Kind: instance method of ParameterBag

| Param | Type | Description | | --- | --- | --- | | name | String | Name of the parameter. |

parameterBag.reset([name])

Reset a parameter to its init value. Reset all parameters if no argument.

Kind: instance method of ParameterBag

| Param | Type | Default | Description | | --- | --- | --- | --- | | [name] | String | | Name of the parameter to reset. |

parameterBag.addListener(callback)

Add listener to all param updates.

Kind: instance method of ParameterBag

| Param | Type | Description | | --- | --- | --- | | callback | ParameterBag~listenerCallack | Listener to register. |

parameterBag.removeListener(callback)

Remove listener from all param changes.

Kind: instance method of ParameterBag

| Param | Type | Default | Description | | --- | --- | --- | --- | | callback | ParameterBag~listenerCallack | | Listener to remove. If null remove all listeners. |

parameterBag.addParamListener(name, callback, [trigger])

Add listener to a given param updates.

Kind: instance method of ParameterBag

| Param | Type | Default | Description | | --- | --- | --- | --- | | name | String | | Parameter name. | | callback | paramListenerCallack | | Function to apply when the value of the parameter changes. | | [trigger] | Boolean | false | Execute the callback immediately with current parameter value. |

parameterBag.removeParamListener(name, callback)

Remove listener from a given param updates.

Kind: instance method of ParameterBag

| Param | Type | Default | Description | | --- | --- | --- | --- | | name | String | | Parameter name. | | callback | paramListenerCallack | | Listener to remove. If null remove all listeners. |

ParameterBag~listenerCallback : function

Kind: inner typedef of ParameterBag

| Param | Type | Description | | --- | --- | --- | | name | String | Parameter name. | | value | Mixed | Updated value of the parameter. | | [meta=] | Object | Given meta data of the parameter. |

ParameterBag~paramListenerCallack : function

Kind: inner typedef of ParameterBag

| Param | Type | Description | | --- | --- | --- | | value | Mixed | Updated value of the parameter. | | [meta=] | Object | Given meta data of the parameter. |

parameters(definitions, values) ⇒ ParameterBag

Factory for the ParameterBag class.

Kind: global function

| Param | Type | Description | | --- | --- | --- | | definitions | [ 'Object' ].<String, paramDefinition> | Object describing the parameters. | | values | [ 'Object' ].<String, Mixed> | Initialization values for the parameters. |

parameters.defineType(typeName, parameterDefinition)

Register a new type for the parameters factory.

Kind: static method of parameters

| Param | Type | Description | | --- | --- | --- | | typeName | String | Value that will be available as the type of a param definition. | | parameterDefinition | parameterDefinition | Object describing the parameter. |

booleanDefinition : Object

Kind: global typedef
Properties

| Name | Type | Default | Description | | --- | --- | --- | --- | | type | String | 'boolean' | Define a boolean parameter. | | default | Boolean | | Default value of the parameter. | | constant | Boolean | false | Define if the parameter is constant. | | nullable | Boolean | false | Define if the parameter is nullable. | | event | Boolean | true | Define if the parameter is a volatile, e.g. set its value back to null after propagation of its value. When true, nullable is automatically set to true and default to null. | | metas | Object | {} | Optionnal metadata of the parameter. |

integerDefinition : Object

Kind: global typedef
Properties

| Name | Type | Default | Description | | --- | --- | --- | --- | | type | String | 'integer' | Define a boolean parameter. | | default | Mixed | | Default value of the parameter. | | min | Number | -Infinity | Minimum value of the parameter. | | max | Number | +Infinity | Maximum value of the parameter. | | constant | Boolean | false | Define if the parameter is constant. | | nullable | Boolean | false | Define if the parameter is nullable. | | event | Boolean | true | Define if the parameter is a volatile, e.g. set its value back to null after propagation of its value. When true, nullable is automatically set to true and default to null. | | metas | Object | {} | Optionnal metadata of the parameter. |

floatDefinition : Object

Kind: global typedef
Properties

| Name | Type | Default | Description | | --- | --- | --- | --- | | type | String | 'float' | Define a boolean parameter. | | default | Mixed | | Default value of the parameter. | | min | Number | -Infinity | Minimum value of the parameter. | | max | Number | +Infinity | Maximum value of the parameter. | | constant | Boolean | false | Define if the parameter is constant. | | nullable | Boolean | false | Define if the parameter is nullable. | | event | Boolean | true | Define if the parameter is a volatile, e.g. set its value back to null after propagation of its value. When true, nullable is automatically set to true and default to null. | | metas | Object | {} | Optionnal metadata of the parameter. |

stringDefinition : Object

Kind: global typedef
Properties

| Name | Type | Default | Description | | --- | --- | --- | --- | | type | String | 'string' | Define a boolean parameter. | | default | Mixed | | Default value of the parameter. | | constant | Boolean | false | Define if the parameter is constant. | | nullable | Boolean | false | Define if the parameter is nullable. | | event | Boolean | true | Define if the parameter is a volatile, e.g. set its value back to null after propagation of its value. When true, nullable is automatically set to true and default to null. | | metas | Object | {} | Optionnal metadata of the parameter. |

enumDefinition : Object

Kind: global typedef
Properties

| Name | Type | Default | Description | | --- | --- | --- | --- | | type | String | 'enum' | Define a boolean parameter. | | default | Mixed | | Default value of the parameter. | | list | Array | | Possible values of the parameter. | | constant | Boolean | false | Define if the parameter is constant. | | nullable | Boolean | false | Define if the parameter is nullable. | | event | Boolean | true | Define if the parameter is a volatile, e.g. set its value back to null after propagation of its value. When true, nullable is automatically set to true and default to null. | | metas | Object | {} | Optionnal metadata of the parameter. |

anyDefinition : Object

Kind: global typedef
Properties

| Name | Type | Default | Description | | --- | --- | --- | --- | | type | String | 'enum' | Define a parameter of any type. | | default | Mixed | | Default value of the parameter. | | constant | Boolean | false | Define if the parameter is constant. | | nullable | Boolean | false | Define if the parameter is nullable. | | event | Boolean | true | Define if the parameter is a volatile, e.g. set its value back to null after propagation of its value. When true, nullable is automatically set to true and default to null. | | metas | Object | {} | Optionnal metadata of the parameter. |

License

BSD-3-Clause