orsa-listeners v0.0.1

Orsa Listeners

The Orsa listeners classes are the easiest way to write a new plugin. They let you focus on doing the processing part of the work, without having to worry about the event stream from Orsa.

There are four classes:

The two critical methods on ProjectListener and FileListener that you need to override are shouldProcess(domElement) and process(domElement, done). The shouldProcess method is called to determine if now is the right time to run. And the process method is called when shouldProcess returns true.

In shouldProcess you should inspect the attributes and metadata of the DOM element to make sure that you have the data you need to run. In process you do the work and then call done when you are done.

You also have access to this.orsa any time you want to log something.

An example file listener watches for a Javascript AST to become available and then does something with it, like so:

const get = require('lodash.get');

class MyCoolPlugin extends FileListener {
  shouldProcess(domElement) {
    return get(domElement.metadata, 'js.ast', null) !== null;
  }

  process(domElement, callback) {
    domElement.metadata.set('js.woohoo', 'yay!');
    callback();
  }
}

Naming

Naming your plugin class appropriately is really important. Orsa uses the class name of your Plugin to disambiguate it from other plugins. So it's really important that it's unique. We recommend naming your plugin class as a camel-cased version of the package name. For example orsa-my-scanner-plugin would become OrsaMyScannerPlugin as shown below:

class OrsaMyScannerPlugin extends ProjectListener {
  ...
}

Locking

The TypeListener class provides a helpful locking behavior. Because a process method might make multiple changes to a DOM element, which would cause multiple events, it's likely that you would get into an event stream endless death spiral. Locking ensures that if process is already running against a particular element, it will not be run again until process has been completed.