@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