composer

composer

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

Install

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.

Usage

var Composer = require('composer');

API

.task

Register a new task with it's options and dependencies. To return the task object of an already registered task, pass the name of the task without any additional parameters.

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'));
});

// get the "site" task object
var task = app.task('site');

.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]).
• cb {Function}: Callback function to be called when all tasks are finished building.

Example

app.build('default', function(err, results) {
  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

Events

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

starting

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(app, build) {});

• 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.

finished

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(app, build) {});

• 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

error

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

task:starting

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(task, run) {});

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.

task:finished

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(task, run) {});

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

task:error

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

Related projects

You might also be interested in these projects:

• assemble: Assemble is a powerful, extendable and easy to use static site generator for node.js. Used… more | homepage
• base-tasks: base-methods plugin that provides a very thin wrapper around https://github.com/jonschlinkert/composer for adding task methods to… more | homepage
• generate: Fast, composable, highly extendable project generator with a user-friendly and expressive API. | homepage
• update: Easily keep anything in your project up-to-date by installing the updaters you want to use… more | homepage
• verb: Documentation generator for GitHub projects. Verb is extremely powerful, easy to use, and is used… more | homepage

Contributing

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

Building docs

Generate readme and API documentation with verb:

$ npm install verb && npm run docs

Or, if verb is installed globally:

$ verb

Running tests

Install dev dependencies:

$ npm install -d && npm test

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

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

---

This file was generated by verb, v0.9.0, on April 20, 2016.