@phasor/array

Lightweight ordered function execution; phases.

Add "phases" and add functions to the phases and they will be executed in order.

The main concept is functions can be ordered in groups, phases, without needing to be ordered within each phase.

For example, a client router may want phases:

1. Analyze Location - look at new location and do some work analyzing it
2. Exiting Location - consider whether location can be or should be exited
3. Entering Location - what to do when entering a new location (route)
4. Before Actions - preparation for Actions
5. Actions - location specific actions
6. After Actions - cleanup or other after effects

This allows expanding third party modules by adding your own phases and functions to a phasor they made.

Install

$ npm install @phasor/array --save

API

phasor.add(object)

Used to both add a phase and add a function to a phase.

You may add a phase and add a function to it at the same time.

Instead of specifying a single object argument you may specify a string for the first argument as the id and optionally a function as the second argument.

Add a Phase

// specify the phase via the `id` property.
// with no `before` or `after` property the phase will
// be added last
phasor.add({ id: 'some phase name' })

// add the phase *before* another phase by specifying the `before`
phasor.add({ id: 'diff phase name', before: 'other phase' })

// add the phase *after* another phase by specifying the `after`
phasor.add({ id: 'third phase name', after: 'other phase' })

// NOTE: if you specify both before and after the before will be ignored

Add a Function to a Phase

var fn = function() {} # some function

// specify the phase via the `id` property.
// specify the function via the `fn` property
phasor.add({ id: 'phase name', fn:fn })

// add a new phase and add a function to it at the same time
phasor.add({ id: 'new phase', before:'phase name', fn:fn })

// use individual arguments
// NOTE: you can't specify after/before values using this style
phasor.add('third phase', fn)

phasor.run(object)

Executes the functions for each phase in order.

The specified object is provided to each function as both the argument and the this context.

Note:

1. The this in each function is the object passed to phasor.run(object).
2. A function can stop the execution by returning false.
3. When adding a function to a phase it becomes the first function in that phase. This allows a newly added function the chance to prevent previously added functions from running, or, altering the inputs they receive.

var fn = function(context) {
  if (this.someValue) { // same as context.someValue
    // set a new value into the context for future functions
    this.newValue = 'blah'
  } else {
    // false causes the run() to stop
    return false
  }
}

var context = { someValue:'value' }
phasor.run(context)

Future

I can think of several other implementation styles for the phasor idea. I made the @phasor scope so those implementations can be grouped together. Please let me know if you have an idea for an implementation or you'd like to add your module to the @phasor scope.

For example, a phasor could be implemented with async utilities, or, chain-builder (I made chain-builder...). These could provide some more advanced features for execution.

MIT License