Repository files navigation

This loopback component provides a finite state machine (powered byhttps://github.com/vstirbu/fsm-as-promised) for loopback model instances, enabling precise control over when model instance methods may be called.

When a model method that is controlled by the Finite State Machine is called it will set a global lock that will prevent other copies of the same instance from being transitioned whist the existing transition is still underway. The state machine governs which state transitions may take place at any time given the current state of the instance and handles state change persistence on completion of a given transition.

1. Install in you loopback project:

npm install --save loopback-component-fsm

2. Create a component-config.json file in your server folder (if you don't already have one)

3. Enable the component insidecomponent-config.json.

{"loopback-component-fsm": { }}

1. Define a state machine events in the mixin configuration for you models.

"mixins": {"StateMachine": {"stateProperty":"status","settings": {"allowForce":true    },"events": [      {"name":"activate","from":"none","to":"active","transitionOptions": {"skipBeforeSave" :true } },      {"name":"cancel","from":"active","to":"canceled" },      {"name":"reactivate","from":"canceled","to":"active" },      {"name":"expire","from": ["active","canceled" ],"to":"expired" }    ]  }}

Options:

• stateProperty

  [String] : The name of the model's state property.(default: 'state')

• settings

  [Object] : Settings used to control state machine operations. Currently the only supported option isallowForce which when set totrue makes it possible to carry out an otherwise invalid state change by passing in{ force: true } at method call time. This option can also be set per event.(default: {})

• events

  [Array] : A list of events available to the state machine. Refer to theFSM As Promised documentation for details on how events should be defined.(default: [])

For each event in the State Machine, a series of model notifications will be sent - one for each stage in a transition - in the following order:

You can act on any of these transition stages by observing the notification. For example:

MyModel.observe('fsm:oncancel',ctx=>ctx.instance.doSomething().then(()=>ctx))

If you intend to perform an asynchronous operation in a given transition stage, your observer should return a promise that resolves to thectx argument that was passed to it. Otherwise, you should simply return thectx object.

Return values

Thectx object will be passed through the entire transition call chain and returned to the original caller. If you would like your caller to receive something other than the fullctx object you can setctx.res which will be returned instead.More information

Prototype methods will be attached to model instances for each of the named events in your mixin configuration. Forexample, the above mixin configuration will result in the following methods being added to MyModel.

• MyModel.prototype.activate
• MyModel.prototype.cancel
• MyModel.prototype.reactivate
• MyModel.prototype.expire

These methods all accept a first argument that is a settings object that is used by the fsm to determine how it functions (eg passing{ force: true } (seeallowForce above). All arguments will be available from within the various fsm notifications.

MyModel.findOne().then(instance=>{log.debug(`Current state is:${instance.state}`)// Current state is: activereturninstance.cancel()}).then(instance=>{log.debug(`Current state is:${instance.state}`)// Current state is: canceledreturninstance.reactivate({force:true})}).then(instance=>{log.debug(`Current state is:${instance.state}`)// Current state is: active})

In this example, a model instance is loaded from the database and a finite state machine is initialized using the current status of the model instance. The instance is then transitioned to the canceled state, then back to the active state.

Please refer to theFSM As Promised documentation for more detail on the internals of the state machine implementation.