composer

composer

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

Table of Contents

• Install
• Usage
• API
• Task execution
• Events
• History
• About

(TOC generated by verb using markdown-toc)

Install

Install with npm:

$ npm install --save composer

Install with yarn:

$ yarn add composer

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.

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(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

Task execution

When an individual task is executed (or run), a new Run instance is created with start, end, and duration information. This run object is emitted with some events and also exposed on the task instance as the .runInfo property.

The run instance has the the following properties

.date

The .date property is an object containing the .start and .end date timestamps created with new Date().

.hr

The .hr property is an object containing the .start, .end and .duration properties that are created by using process.hrtime(). These properties are the actual arrays returned from process.hrtime(). There is also .diff and .offset computed properties that use the other properties to calculate the difference between .start and .end times (.diff) and the offset (error for time calculations) between the .duration and the .diff (this is usually very small).

.duration

The .duration property is a computed property that uses pretty-time to format the .hr.duration value into a human readable format.

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

History

v0.14.0

• Updates bach to 1.0.0.
• Errors emitted from inside a task now have the 'in task "foo":' prefixed to the error message. see issue #22
• Expose .runInfo on the task object for use in event listeners and task functions.
• Add .duration to the .run/.runInfo object that shows the duration in a human friendly format. This will also show the current duration from the time the task started to the time it's called if used inside a task function. see issue #23

app.task('foo', function(cb) {
  console.log(this.runInfo.duration);
});

v0.13.0

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

v0.12.0

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

v0.11.3

• Allow passing es2015 javascript generator functions to .task().

v0.11.2

• Allow using glob patterns for task dependencies.

v0.11.0

• BREAKING CHANGE: Removed .watch(). Watch functionality can be added to base applications using base-watch.

v0.10.0

• Removes session.

v0.9.0

• Use default when no tasks are passed to .build().

v0.8.4

• Ensure task dependencies are unique.

v0.8.2

• Emitting task when adding a task through .task()
• Returning task when calling .task(name) with only a name.

v0.8.0

• Emitting task:* events instead of generic * events. See event docs for more information.

v0.7.0

• No longer returning the current task when .task() is called without a name.
• Throwing an error when .task() is called without a name.

v0.6.0

• Adding properties to err instances and emitting instead of emitting multiple parameters.
• Adding series and parallel flows/methods.

v0.5.0

• BREAKING CHANGE Renamed .run() to .build()

v0.4.2

• .watch returns an instance of FSWatcher

v0.4.1

• Currently running task returned when calling .task() without a name.

v0.4.0

• Add session-cache to enable per-task data contexts.

v0.3.0

• Event bubbling/emitting changed.

v0.1.0

• Initial release.

About

Related projects

• assemble: Get the rocks out of your socks! Assemble makes you fast at creating web projects… 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: Command line tool and developer framework for scaffolding out new GitHub projects. Generate offers the… more | homepage
• update: Be scalable! Update is a new, open source developer framework and CLI for automating updates… 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.

Contributors

Commits	Contributor
195	doowb
36	jonschlinkert

Building docs

(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)

To generate the readme, run the following command:

$ npm install -g verbose/verb#dev verb-generate-readme && verb

Running tests

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

$ npm install && npm test

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright © 2017, Jon Schlinkert. Released under the MIT License.

---

This file was generated by verb-generate-readme, v0.6.0, on May 26, 2017.