A slice of time in an application. Provides hooks to allow functions to be executed before, during and after, the defined slice. Handlers can be registered to a phase using before(), use(), or after() so that they are placed into one of the three stages.

var Phase = require('loopback-phase').Phase;

// Create a phase without id
var anonymousPhase = new Phase();

// Create a named phase
var myPhase1 = new Phase('my-phase');

// Create a named phase with id & options
var myPhase2 = new Phase('my-phase', {parallel: true});

// Create a named phase with options only
var myPhase3 = new Phase({id: 'my-phase', parallel: true});

Register a phase handler to be executed after the phase completes. See use() for an example.

Register a phase handler to be executed before the phase begins. See use() for an example.

Begin the execution of a phase and its handlers. Provide a context object to be passed as the first argument for each handler function.

The handlers are executed in serial stage by stage: beforeHandlers, handlers, and afterHandlers. Handlers within the same stage are executed in serial by default and in parallel only if the options.parallel is true,

Return the Phase as a string.

Register a phase handler. The handler will be executed once the phase is launched. Handlers must callback once complete. If the handler calls back with an error, the phase will immediately halt execution and call the callback provided to phase.run(callback).

Example

phase.use(function(ctx, next) {
  // specify an error if one occurred...
  var err = null;
  console.log(ctx.message, 'world!'); // => hello world
  next(err);
});

phase.run({message: 'hello'}, function(err) {
  if(err) return console.error('phase has errored', err);
  console.log('phase has finished');
});

An ordered list of phases.

var PhaseList = require('loopback-phase').PhaseList;
var phases = new PhaseList();
phases.add('my-phase');

Add one or more phases to the list.

Add a new phase as the next one after the given phase.

Add a new phase at the specified index.

Add a new phase as the previous one before the given phase.

Find a Phase from the list.

Find or add a Phase from/into the list.

Get the first Phase in the list.

Get an array of phase identifiers.

Get the last Phase in the list.

Remove a Phase from the list.

Launch the phases contained in the list. If there are no phases in the list process.nextTick is called with the provided callback.

Get the list of phases as an array of Phase objects.

Merge the provided list of names with the existing phases in such way that the order of phases is preserved.

Example

// Initial list of phases
phaseList.add(['initial', 'session', 'auth', 'routes', 'files', 'final']);

// zip-merge more phases
phaseList.zipMerge([
  'initial', 'postinit', 'preauth', 'auth',
  'routes', 'subapps', 'final', 'last'
]);

// print the result
console.log('Result:', phaseList.getPhaseNames());
// Result: [
//   'initial', 'postinit', 'preauth', 'session', 'auth',
//   'routes', 'subapps', 'files', 'final', 'last'
// ]

Extend the list of builtin phases by merging in an array of phases requested by a user while preserving the relative order of phases as specified by both arrays.

If the first new name does not match any existing phase, it is inserted as the first phase in the new list. The same applies for the second phase, and so on, until an existing phase is found.

Any new names in the middle of the array are inserted immediatelly after the last common phase. For example, extending ["initial", "session", "auth"] with ["initial", "preauth", "auth"] results in ["initial", "preauth", "session", "auth"].

Example

var result = mergePhaseNameLists(
  ['initial', 'session', 'auth', 'routes', 'files', 'final'],
  ['initial', 'postinit', 'preauth', 'auth',
    'routes', 'subapps', 'final', 'last']
);

// result: [
//   'initial', 'postinit', 'preauth', 'session', 'auth',
//   'routes', 'subapps', 'files', 'final', 'last'
// ]