cycle-workflows

Provides Plugin-based workflow functionality for cycle.js applications.

Installation

npm i cycle-workflows --save

Scripts

NOTE: Make sure you've installed all dependencies using npm install first.

To generate documentation: npm run doc. This will create documentation in the build/docs folder.

To run unit tests: npm test

API

Workflow

Executes any WorkflowStep instances associated with the name of the Workflow instance, in dependency-safe order, with automatic rollback of executed steps if any steps fail. See the examples for more information.

Kind: global class
Emits: StepsChanged
Inherits: Plugin

• Workflow
  • new Workflow(props)
  • instance
    • .asReadOnly() ⇒ Workflow
    • .asObservable() ⇒ Rx.Observable
    • .delete()
    • .dispatch([args]) ⇒ Promise.<WorkflowResult>
  • static
    • .States : Object
    • .Errors : Object
    • .Events : Object
    • "Deleted" (instance)
    • "Dispatched" (instance, arguments, promise)
    • "StepsChanged" (instance, steps)

new Workflow(props)

| Param | Type | Description | | --- | --- | --- | | props | Object | A map of property names and values to associate with the workflow. The only required attribute is name, which will be used to subscribe to any Plugin instances targeting this Workflow instance. |

Example

var stepOne = new WorkflowStep({
  name: 'step-one',
  filter: {any: ['my-workflow']},
  execute: function(arg) {
    return new Promise(function(resolve) {
      // represents a long-running operation
      resolve('step one results');
    });
  }
);

var stepTwo = new WorkflowStep({
  name: 'step-two',
  after: ['step-one'],
  filter: {any: ['my-workflow', 'my-other-workflow']},
  execute: function(arg) {
    return 'step two results';
  }
);

var workflow = new Workflow({name: 'my-workflow'});
workflow.dispatch('argument passed to execute methods')
  then(function processResults(dispatch) {
    // dispatch never rejects, always resolves;
    // we need to check the status to see what
    // to do next:
    switch (dispatch.status) {
      case Workflow.States.SUCCESS:
        log(dispatch.results); break;
      case Workflow.States.CANCELLED:
        log(dispatch.reason); break;
      case Workflow.States.FAILED:
        log(dispatch.error); break;
    }
  });

workflow.asReadOnly() ⇒ Workflow

Converts the Workflow into a version that cannot be deleted. Useful when you need to share a workflow without risking it being deleted.

Kind: instance method of Workflow
Returns: Workflow - A readonly version of the Workflow instance.
Example

var myWorkflow = new Workflow({name: 'safe-workflow'});
return {
  getWorkflow: function() {
    return myWorkflow.asReadOnly(); // cannot be deleted
  }
};

workflow.asObservable() ⇒ Rx.Observable

Provides a shared stream consumers can subscribe to in order to receive subsequent dispatch results.

Kind: instance method of Workflow
Example

someWorkflow.asObservable()
  .filter(dispatch => dispatch.status === Workflow.States.SUCCESS)
  .pluck('results') // the values returned by executed steps
  .tap(results => log(results));

workflow.delete()

Deletes the workflow and any associated streams. Trying to invoke any methods on a deleted workflow will cause an Error to be thrown.

Kind: instance method of Workflow
Emits: Deleted
Example

myWorkflow.delete();
myWorkflow.dispatch(); // throws Error

workflow.dispatch([args]) ⇒ Promise.<WorkflowResult>

Executes any enabled steps associated with this Workflow instance, passing the dispatch arguments to each step's execute method and saving each step's execute result.

Kind: instance method of Workflow
Returns: Promise.<WorkflowResult> - A promise that will never be rejected. If a step's execute method returns a promise that never resolves, this promise will also never resolve. Examine the resulting value's status member to determine whether the dispatch ended successfully, failed, or was cancelled.
Emits: Dispatched

| Param | Type | Description | | --- | --- | --- | | [args] | * | One or more arguments to pass to each step's execute method. |

Example

myWorkflow.dispatch(arg1, arg2)
  .then(dispatch => {
    switch (dispatch.status) {
      case Workflow.States.CANCELLED:
      case Workflow.States.FAILED:
        log('dispatch ended early:', dispatch.reason || dispatch.error);
        break;
      case Workflow.States.SUCCESS:
        log(dispatch.results);
    }
  });

Workflow.States : Object

Represents the state of the Workflow dispatch result. Handlers attached to the dispatch method should examine the state property to determine how to process the results.

Kind: static property of Workflow
Properties

| Name | Type | Description | | --- | --- | --- | | SUCCESS | String | The dispatch succeeded. Check the results property. | | FAILED | String | The dispatch failed. Check the error property. | | CANCELLED | String | The dispatch was cancelled. Check the reason property. |

Workflow.Errors : Object

A collection of possible Error messages the Workflow could generate.

Kind: static property of Workflow
Properties

| Name | Type | Description | | --- | --- | --- | | READONLY_MODE | String | A readonly workflow cannot be deleted. | | WORKFLOW_DELETED | String | A deleted workflow cannot be invoked. |

Workflow.Events : Object

Events specific to Workflows. Also includes events related to all Plugin instances.

Kind: static property of Workflow
Properties

| Name | Type | Description | | --- | --- | --- | | WF_DELETED | String | The workflow was deleted. | | WF_DISPATCHED | String | The workflow was dispatched. | | WF_STEPS_CHANGED | String | The steps associated with the workflow were changed. |

"Deleted" (instance)

The workflow was deleted.

Kind: event emitted by Workflow

| Param | Type | | --- | --- | | instance | Workflow |

"Dispatched" (instance, arguments, promise)

The workflow was dispatched.

Kind: event emitted by Workflow

| Param | Type | Description | | --- | --- | --- | | instance | Workflow | | | arguments | Array | The arguments passed to dispatch. | | promise | Promise | A promise that will be resolved when the dispatch completes. |

"StepsChanged" (instance, steps)

Kind: event emitted by Workflow

| Param | Type | Description | | --- | --- | --- | | instance | Workflow | | | steps | Array | The updated array of steps. The array will have a toDAG method to convert it into a structure that respects dependencies between steps. |

WorkflowStep

Represents a single step in a Workflow instance.

Each WorkflowStep has a lifecycle Workflow follows during dispatch that you can hook into to control what happens.

First, the init method is called. This can be used to initialize instance values used in the other methods. The init method is guaranteed to only be called once per dispatch.

Next, the execute method is invoked, and passed any arguments provided to the Workflow.dispatch method. If execute returns a Promise, any dependent steps will not run (and the Workflow dispatch promise will not be resolved) until the execute promise resolves. Whatever value the execute method returns (or a returned Promise resolves with) will be stored in an internal results map that is accessible to subsequent steps and provided to the WorkflowResult that the dispatch promise is resolved with.

If the execute method throws an error or returns a promise that rejects, then retry will be called and provided with the error reason. If retry returns a rejected promise or throws an error (which is the default implementation if none is provided), then the dispatch will be considered failed. Otherwise, returning anything else (or nothing at all) will cause execute to be invoked again -- potentially an unlimited number of times.

If the dispatch enters a failed state, then all of the executed steps' rollback methods will be invoked and provided with the failure reason. Rollbacks are invoked in the reverse order the execute methods were invoked. This allows your executed steps to perform any cleanup operations that may be necessary.

If the dispatch fails, then ALL steps -- even steps that never had a chance to be executed -- will have their failure method invoked with the reason the dispatch failed.

Only if all steps succeed will each executed step's success method be invoked. This method will be passed the results object that maps step names to the values returned by their execute methods.

All step lifecycle methods have access to the following properties on their context (i.e., this):

| Param | Type | Description | | --- | --- | --- | |workflow | String | The name of the workflow being dispatched. This is useful when your step might be associated with multiple workflows. | |results | Object | A map of previously executed steps and the results of their execute methods. This is useful when your step is set to run after another step, and you would like to access the results of that step. | | cancel | Function | A method you can invoke to cancel the dispatch immediately. Note that this method is only available from init, execute, and retry. |

Kind: global class
Inherits: Plugin
Properties

| Name | Type | Description | | --- | --- | --- | | init | function | A no-op, unless overridden. | | execute | function | A no-op, unless overridden. | | retry | function | Rejects, unless overridden. | | rollback | function | A no-op, unless overridden. | | success | function | A no-op, unless overridden. | | failure | function | A no-op, unless overridden. |

new WorkflowStep(props)

| Param | Type | Description | | --- | --- | --- | | props | Object | The properties to associate with this WorkflowStep instance. The only required property is name. You can provide Plugin-specific values such as after, filter, and targetType to restrict which Workflows your WorkflowStep will be associated with. You can also override any of the built-in WorkflowStep properties, such as execute. |

Example

// create a step that attempts to log in 3 times before
// failing the dispatch -- if the execute method succeeds,
// the dispatch results will contain a property called
// 'login-step' whose value will be whatever value the
// `postLogin(...)` promise resolves with
Plugins.register(new WorkflowStep({
  name: 'login-step',
  filter: {any: 'login-workflow'},
  retryCount: 0, // steps can have instance members
  init: () => retryCount = 0, // runs once per dispatch
  execute: (user, hash) => postLogin(user, hash), // return promise
  retry: err => {
    if (++retryCount > 3) {
      throw err; // throwing from retry fails the dispatch
    }
    // wait 1 second and then try again; returning nothing
    // would cause execute to be re-invoked immediately
    return Promise.delay(1000);
  }
}));

new Workflow({name: 'login-workflow'})
  .dispatch(username, hashPassword)
  .then(dispatch => {
     if (dispatch.status !== Workflow.States.SUCCESS) {
       showErrorMessage(dispatch.error || dispatch.reason);
     }
  });

WorkflowResult

Represents the result of a dispatched workflow. The dispatch promise will be resolved with an instance of WorkflowResult that can be examined to learn more about how the dispatch concluded.

Kind: global class
Properties

| Name | Type | Description | | --- | --- | --- | | status | States | The status of the dispatch. | | executed | Array.<String> | The names of the steps that executed during the dispatch. Useful for determining where an error may have occurred. | | error | Error | The error that caused the dispatch to fail. This property only exists if status is Workflow.States.FAILED. | | reason | String | Error | The reason the dispatch ended early. This property only exists if status is Workflow.States.CANCELLED. | | results | Object | A map of step names to the results of that step's execute method. This property only exists if status is Workflow.States.SUCCESS. |

new WorkflowResult(data)

| Param | Type | Description | | --- | --- | --- | | data | Object | Data about the dispatch. This information is provided automatically by the dispatch method. |