cycle-plugins

Provides observable-based plugins to cycle.js applications.

Installation

npm i cycle-plugins --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

Plugins

Static class for registering and consuming Plugin instances dynamically.

Kind: global namespace

• Plugins : object
  • .register(plugins)
  • .unregister(plugins)
  • .get(criteria)

plugins.register(plugins)

Makes one or more Plugins available to consumers.

Kind: instance method of Plugins

| Param | Type | Description | | --- | --- | --- | | plugins | Plugin | Array.<Plugin> | One or more Plugin instances to make available to consumers. |

Example

Plugins.register(new Plugin({
  name: 'console',
  log: function log(msg) { ... }
}));

Plugins.get({name: 'console'}).first()
  .tap(console => console.log('hello'));

plugins.unregister(plugins)

Makes a Plugin unavailable to consumers.

Kind: instance method of Plugins

| Param | Type | Description | | --- | --- | --- | | plugins | Plugin | Array.<Plugin> | One or more Plugin instances to unregister. |

Example

var plugin = new Plugin({name: 'temp'});
Plugins.register(plugin); // available to consumers
Plugins.unregister(plugin); // unavailable to consumers

plugins.get(criteria)

Returns an Observable populated with an array of Plugin instances matching the specified criteria. The array contains a utility method called toDAG that will return a DAG instance you can use to iterate safely over the returned Plugin instances in a way that respects the index and after properties of each Plugin.

Kind: instance method of Plugins
Throws:

• Error Invalid criteria was specified.

| Param | Type | Description | | --- | --- | --- | | criteria | Object | A map of criteria to apply against each registered Plugin. Only Plugin instances matching the specified criteria will be included in the resulting Observable. |

Example

// retrieve a single Plugin by name
var single$ = Plugins.get({name: 'my-one-plugin'}).first();

Example

// retrieve all registered Plugin instances
var allPlugins$ = Plugins.get(); // or Plugins.get({})

Example

// retrieve all Plugin instances targeting a specific type
var targeted$ = Plugins.get({targetType: MyClass});

Example

// retrieve Plugin instances matching a specific filter;
// the Plugin would need 'my-criteria' in its `filter.any`
// string array and NOT in its `filter.none` string array.
var filtered$ = Plugins.get({filter: 'my-criteria'});

Example

// iterating through Plugins concurrently and in a
// dependency-safe order:
let savePlugins$ = Plugins.get({
  targetType: MyClass, filter: 'save'
});

function save() {
  return savePlugins$.map(plugins =>
    new Observable(observer =>
      plugins.toDAG().forEach(
        (plugin, next) => plugin.doSomething(), next(),
        (err) => err ? observer.error(err) : observer.next()
      );
    ));
}

Plugin

Kind: global class
Inherits: Broker
Properties

| Name | Type | Default | Description | | --- | --- | --- | --- | | name | String | | The name of this plugin. | | index | Number | 0 | Provides a way to order multiple Plugins whenever a sequence is requested. | | after | Array.<String> | [] | Provides a way to order multiple Plugins based on dependencies. Ensures that this Plugin will be sequenced after the specified Plugin names. If you prepend a name with ?, it will be treated as an optional dependency. | | enabled | Boolean | true | Some consumers may use this property to determine which Plugins should be consumed or which can be skipped during iteration. | | targetType | function | Object | Used in conjunction with Plugins.get to ensure both Plugin creators and Plugin consumers agree on who can consume this Plugin instance. | | filter | Filter | {any:[], none:[]} | A way to restrict the list of Plugins retrieved by Plugins.get at runtime. |

• Plugin
  • new Plugin(props)
  • .Events : Object

new Plugin(props)

An extensible object.

| Param | Type | Description | | --- | --- | --- | | props | Object | A map of property names and values to apply to the Plugin instance. The only required property is name. |

Example

import {extend, matches} from 'lodash';

const COMMAND_PROPS = { ... };

class Command extends Plugin
  constructor(props) {
    super(extend({}, COMMAND_PROPS, props));
    Plugins.register(this);
  }
  execute() {}
  undo() {}
}

class RecordCommand extends Command {
  constructor(props) {
    super({
      targetType: Record,
      enabled: User.hasPrivilege(props.name)
    });
  }
}

class SaveRecord extends RecordCommand
  constructor() {
    super({name: 'save-record');
  }
  execute() { ... }
  undo() { ... }
}

class DeleteRecord extends RecordCommand
  constructor() {
    super({name: 'delete-record');
  }
  execute() { ... }
  undo() { ... }
}

class Record extends Broker {
  constructor() {
    this.commands$ = Plugins.get({
      baseType: RecordCommand,
      targetType: Record,
      enabled: true
    });
  }

  save() {
    return this.commands$
      .filter(matches({name: 'save-record'}))
      .map(command => command.execute(this))
      .tap(() => this.emit('record-saved'))
      .toPromise();
  }

}

Plugin.Events : Object

Events specific to Plugins.

Kind: static property of Plugin
Properties

| Name | Type | Description | | --- | --- | --- | | PLUGIN_CHANGED | String | A property on the plugin has changed. Emit this event when you wish for any search criteria passed to Plugins.get to be re-evaluated, with observers notified of any changes. |

DAG (Directed Acyclic Graph)

Kind: global class

• DAG
  • new DAG(plugins)
  • .toArray() ⇒ Array.<Plugin>
  • .forEach(callback, [finish], [concurrency])

new DAG(plugins)

Provides a dependency-safe way to iterate through plugins.

Throws:

• Error If a dependent Plugin is not optional and not in the set of Plugins provided to the constructor, an error will be thrown. You can mark a dependency as optional by prepending it with a question mark. See the documentation for Plugin for more information.

| Param | Type | Description | | --- | --- | --- | | plugins | Plugin | Array.<Plugin> | One or more Plugin instances the DAG should manage. |

Example

var dag = new DAG(pluginA, pluginB, pluginC);
dag.forEach(function iterate(plugin, next) {
  // do something with plugin
  next(); // invoke this callback with the next plugin
  // if you wish to stop iteration immediately, invoke
  // next with an argument: next(0) or next('stop') or
  // next(new Error()) -- the argument will be passed
  // to your success handler function
}, function finished(err) {
  if (err) {
    console.log('An error occurred:', err);
  }
});

daG.toArray() ⇒ Array.<Plugin>

Converts the DAG into a dependency-safe sequence of Plugin instances.

Kind: instance method of DAG
Returns: Array.<Plugin> - An array of Plugin instances in dependency-safe order.
Example

var dag = new DAG(pluginA, pluginB, pluginC);
var names = dag.toArray().map(function(plugin) {
  return plugin.name;
});
log(names);

daG.forEach(callback, [finish], [concurrency])

Iterates through the DAG in dependency-safe order using the specified callback function and concurrency settings.

Kind: instance method of DAG
Throws:

• Error Parameter callback must be a function.
• Error Parameter concurrency must be a positive integer.

| Param | Type | Default | Description | | --- | --- | --- | --- | | callback | function | | A method that will be invoked for each Plugin instance. Arguments will be: - {Plugin} plugin - the current plugin - {Function} next - method to invoke to continue iteration - {Number} percent - a number between 0 and 100 indicating how much of the DAG has been processed | | [finish] | function | | An optional method to invoke when the DAG has been completely processed. If an error has occurred or the iteration ended early, the only argument will be the exit reason. | | [concurrency] | Number | 5 | How many Plugins to iterate concurrently. The number must be a positive integer. |

Example

new DAG(pluginA, pluginB, pluginC)
  .forEach((plugin, next, percent) => {
    log(`running ${plugin.name} - ${percent}% complete`);
    next('stop'); // stop iterating early
  }, err => {
    if (err) {
      log('stopped early because:', err);
    }
  });