node package manager

composer

API-first task runner with three methods: task, run and watch.

composer

API-first task runner with three methods: task, run and watch.

Install with npm:

$ npm install composer --save

Heads up the .watch method was removed in version 0.11.0. If you need watch functionality, use base-tasks and base-watch.

var Composer = require('composer');

.task

Register a new task with it's options and dependencies.

Dependencies may also be specified as a glob pattern. Be aware that the order cannot be guarenteed when using a glob pattern.

Params

  • name {String}: Name of the task to register
  • options {Object}: Options to set dependencies or control flow.
  • options.deps {Object}: array of dependencies
  • options.flow {Object}: How this task will be executed with it's dependencies (series, parallel, settleSeries, settleParallel)
  • deps {String|Array|Function}: Additional dependencies for this task.
  • fn {Function}: Final function is the task to register.
  • returns {Object}: Return the instance for chaining

Example

// register task "site" with composer 
app.task('site', ['styles'], function() {
  return app.src('templates/pages/*.hbs')
    .pipe(app.dest('_gh_pages'));
});

.build

Build a task or array of tasks.

Params

  • tasks {String|Array|Function}: List of tasks by name, function, or array of names/functions. (Defaults to [default]).
  • options {Object}: Optional options object to merge onto each task's options when building.
  • cb {Function}: Callback function to be called when all tasks are finished building.

Example

app.build('default', function(errresults) {
  if (err) return console.error(err);
  console.log(results);
});

.series

Compose task or list of tasks into a single function that runs the tasks in series.

Params

  • tasks {String|Array|Function}: List of tasks by name, function, or array of names/functions.
  • returns {Function}: Composed function that may take a callback function.

Example

app.task('foo', function(done) {
  console.log('this is foo');
  done();
});
 
var fn = app.series('foo', function bar(done) {
  console.log('this is bar');
  done();
});
 
fn(function(err) {
  if (err) return console.error(err);
  console.log('done');
});
//=> this is foo 
//=> this is bar 
//=> done 

.parallel

Compose task or list of tasks into a single function that runs the tasks in parallel.

Params

  • tasks {String|Array|Function}: List of tasks by name, function, or array of names/functions.
  • returns {Function}: Composed function that may take a callback function.

Example

app.task('foo', function(done) {
  setTimeout(function() {
    console.log('this is foo');
    done();
  }, 500);
});
 
var fn = app.parallel('foo', function bar(done) {
  console.log('this is bar');
  done();
});
 
fn(function(err) {
  if (err) return console.error(err);
  console.log('done');
});
//=> this is bar 
//=> this is foo 
//=> done 

composer is an event emitter that may emit the following events:

This event is emitted when a build is starting.

The event emits 2 arguments, the current instance of composer as the app and an object containing the build runtime information.

app.on('starting', function(appbuild) {});
  • build exposes a .date object that has a .start property containing the start time as a Date object.
  • build exposes a .hr object that has a .start property containing the start time as an hrtime array.

This event is emitted when a build has finished.

The event emits 2 arguments, the current instance of composer as the app and an object containing the build runtime information.

app.on('finished', function(appbuild) {});
  • build exposes a .date object that has .start and .end properties containing start and end times of the build as Date objects.
  • build exposes a .hr object that has .start, .end, .duration, and .diff properties containing timing information calculated using process.hrtime

This event is emitted when an error occurrs during a build. The event emits 1 argument as an Error object containing additional information about the build and the task running when the error occurred.

app.on('error', function(err) {});

Additional properties:

  • app: current composer instance running the build
  • build: current build runtime information
  • task: current task instance running when the error occurred
  • run: current task runtime information

This event is emitted when a task is starting. The event emits 2 arguments, the current instance of the task object and an object containing the task runtime information.

app.on('task:starting', function(taskrun) {});

The run parameter exposes:

  • .date {Object}: has a .start property containing the start time as a Date object.
  • .hr {Object}: has a .start property containing the start time as an hrtime array.

This event is emitted when a task has finished.

The event emits 2 arguments, the current instance of the task object and an object containing the task runtime information.

app.on('task:finished', function(taskrun) {});

The run parameter exposes:

  • .date {Object}: has a .date object that has .start and .end properties containing start and end times of the task as Date objects.
  • run {Object}: has an .hr object that has .start, .end, .duration, and .diff properties containing timing information calculated using process.hrtime

This event is emitted when an error occurrs while running a task. The event emits 1 argument as an Error object containing additional information about the task running when the error occurred.

app.on('task:error', function(err) {});

Additional properties

  • task: current task instance running when the error occurred
  • run: current task runtime information
  • Skip tasks by setting the options.skip option to the name of the task or an array of task names.
  • Making additional err properties non-enumerable to cut down on error output.
  • You can no longer get a task from the .task() method by passing only the name. Instead do var task = app.tasks[name];
  • Passing only a name and no dependencies to .task() will result in a noop task being created.
  • options may be passed to .build(), .series() and .parallel()
  • options passed to .build() will be merged onto task options before running the task.
  • Skip tasks by setting their options.run option to false.
  • Allow passing es2015 javascript generator functions to .task().
  • Allow using glob patterns for task dependencies.
  • BREAKING CHANGE: Removed .watch(). Watch functionality can be added to base applications using base-watch.
  • Removes session.
  • Use default when no tasks are passed to .build().
  • Ensure task dependencies are unique.
  • Emitting task when adding a task through .task()
  • Returning task when calling .task(name) with only a name.
  • Emitting task:* events instead of generic * events. See event docs for more information.
  • No longer returning the current task when .task() is called without a name.
  • Throwing an error when .task() is called without a name.
  • Adding properties to err instances and emitting instead of emitting multiple parameters.
  • Adding series and parallel flows/methods.
  • BREAKING CHANGE Renamed .run() to .build()
  • .watch returns an instance of FSWatcher
  • Currently running task returned when calling .task() without a name.
  • Add session-cache to enable per-task data contexts.
  • Event bubbling/emitting changed.
  • Initial release.

You might also be interested in these projects:

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Generate readme and API documentation with verb:

$ npm install verb && npm run docs

Or, if verb is installed globally:

$ verb

Install dev dependencies:

$ npm install -d && npm test

Jon Schlinkert

Copyright © 2016, Jon Schlinkert. Released under the MIT license.


This file was generated by verb, v0.9.0, on May 25, 2016.