Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

composer

doowb154.4kMIT4.1.0

Run and compose async tasks. Easily define groups of tasks to run in series or parallel.

async, await, build, build-system, compose, composer, composition, control, flow, run, system, task, workflow

readme

composer NPM version NPM monthly downloads NPM total downloads Linux Build Status Windows Build Status

Run and compose async tasks. Easily define groups of tasks to run in series or parallel.

Please consider following this project's author, Brian Woodward, and consider starring the project to show your :heart: and support.

(TOC generated by verb using markdown-toc)

Install

Install with npm:

$ npm install --save composer

Usage

// Create an instance of `Composer`
const Composer = require('composer');
const composer = new Composer();

// Define tasks with the .task() method
composer.task('foo', callback => {
  callback(); // do stuff
});
composer.task('bar', callback => {
  callback(); // do stuff
});

composer.task('baz', ['foo'. 'bar']);

// Run tasks with the .build() method
composer.build('baz')
  .then(() => console.log('done!'))
  .catch(console.error);

API

.factory

Factory for creating a custom Tasks class that extends the given Emitter. Or, simply call the factory function to use the built-in emitter.

Params

  • Emitter {function}: Event emitter.
  • returns {Class}: Returns a custom Tasks class.

Example

// custom emitter
const Emitter = require('events');
const Tasks = require('composer/lib/tasks')(Emitter);
// built-in emitter
const Tasks = require('composer/lib/tasks')();
const composer = new Tasks();

Tasks

Create an instance of Tasks with the given options.

Params

  • options {object}

Example

const Tasks = require('composer').Tasks;
const composer = new Tasks();

.task

Define a task. Tasks run asynchronously, either in series (by default) or parallel (when options.parallel is true). In order for the build to determine when a task is complete, one of the following things must happen: 1) the callback must be called, 2) a promise must be returned, or 3) a stream must be returned. Inside tasks, the "this" object is a composer Task instance created for each task with useful properties like the task name, options and timing information, which can be useful for logging, etc.

Params

  • name {String}: The task name.
  • deps {Object|Array|String|Function}: Any of the following: task dependencies, callback(s), or options object, defined in any order.
  • callback {Function}: (optional) If the last argument is a function, it will be called after all of the task's dependencies have been run.
  • returns {undefined}

Example

// 1. callback
app.task('default', cb => {
  // do stuff
  cb();
});
// 2. promise
app.task('default', () => {
  return Promise.resolve(null);
});
// 3. stream (using vinyl-fs or your stream of choice)
app.task('default', function() {
  return vfs.src('foo/*.js');
});

.build

Run one or more tasks.

Params

  • tasks {object|array|string|function}: One or more tasks to run, options, or callback function. If no tasks are defined, the default task is automatically run.
  • callback {function}: (optional)
  • returns {undefined}

Example

const build = app.series(['foo', 'bar', 'baz']);
// promise
build().then(console.log).catch(console.error);
// or callback
build(function() {
  if (err) return console.error(err);
});

.series

Compose a function to run the given tasks in series.

Params

  • tasks {object|array|string|function}: Tasks to run, options, or callback function. If no tasks are defined, the default task is automatically run, if one exists.
  • callback {function}: (optional)
  • returns {promise|undefined}: Returns a promise if no callback is passed.

Example

const build = app.series(['foo', 'bar', 'baz']);
// promise
build().then(console.log).catch(console.error);
// or callback
build(function() {
  if (err) return console.error(err);
});

.parallel

Compose a function to run the given tasks in parallel.

Params

  • tasks {object|array|string|function}: Tasks to run, options, or callback function. If no tasks are defined, the default task is automatically run, if one exists.
  • callback {function}: (optional)
  • returns {promise|undefined}: Returns a promise if no callback is passed.

Example

// call the returned function to start the build
const build = app.parallel(['foo', 'bar', 'baz']);
// promise
build().then(console.log).catch(console.error);
// callback
build(function() {
  if (err) return console.error(err);
});
// example task usage
app.task('default', build);

.create

Static method for creating a custom Tasks class with the given `Emitter.

Params

  • Emitter {Function}
  • returns {Class}: Returns the custom class.

.create

Static factory method for creating a custom Composer class that extends the given Emitter.

Params

  • Emitter {Function}: Event emitter.
  • returns {Class}: Returns a custom Composer class.

Example

// Composer extends a basic event emitter by default
const Composer = require('composer');
const composer = new Composer();

// Create a custom Composer class with your even emitter of choice
const Emitter = require('some-emitter');
const CustomComposer = Composer.create(Emitter);
const composer = new CustomComposer();

Params

  • name {String}
  • options {Object}
  • returns {Object}: Returns an instance of Composer.

Example

const composer = new Composer();

Create a wrapped generator function with the given name, config, and fn.

Params

  • name {String}
  • config {Object}: (optional)
  • fn {Function}
  • returns {Function}

Returns true if the given value is a Composer generator object.

Params

  • val {Object}
  • returns {Boolean}

.register

Alias to .setGenerator.

Params

  • name {String}: The generator's name
  • options {Object|Function|String}: or generator
  • generator {Object|Function|String}: Generator function, instance or filepath.
  • returns {Object}: Returns the generator instance.

Example

app.register('foo', function(app, base) {
  // "app" is a private instance created for the generator
  // "base" is a shared instance
});

.generator

Get and invoke generator name, or register generator name with the given val and options, then invoke and return the generator instance. This method differs from .register, which lazily invokes generator functions when .generate is called.

Params

  • name {String}
  • fn {Function|Object}: Generator function, instance or filepath.
  • returns {Object}: Returns the generator instance or undefined if not resolved.

Example

app.generator('foo', function(app, options) {
  // "app" - private instance created for generator "foo"
  // "options" - options passed to the generator
});

.setGenerator

Store a generator by file path or instance with the given name and options.

Params

  • name {String}: The generator's name
  • options {Object|Function|String}: or generator
  • generator {Object|Function|String}: Generator function, instance or filepath.
  • returns {Object}: Returns the generator instance.

Example

app.setGenerator('foo', function(app, options) {
  // "app" - new instance of Generator created for generator "foo"
  // "options" - options passed to the generator
});

.getGenerator

Get generator name from app.generators, same as [findGenerator], but also invokes the returned generator with the current instance. Dot-notation may be used for getting sub-generators.

Params

  • name {String}: Generator name.
  • returns {Object|undefined}: Returns the generator instance or undefined.

Example

const foo = app.getGenerator('foo');

// get a sub-generator
const baz = app.getGenerator('foo.bar.baz');

.findGenerator

Find generator name, by first searching the cache, then searching the cache of the base generator. Use this to get a generator without invoking it.

Params

  • name {String}
  • options {Function}: Optionally supply a rename function on options.toAlias
  • returns {Object|undefined}: Returns the generator instance if found, or undefined.

Example

// search by "alias"
const foo = app.findGenerator('foo');

// search by "full name"
const foo = app.findGenerator('generate-foo');

Params

  • name {String}
  • returns {Boolean}

Example

console.log(app.hasGenerator('foo'));
console.log(app.hasGenerator('foo.bar'));

.generate

Run one or more tasks or sub-generators and returns a promise.

Params

  • name {String}
  • tasks {String|Array}
  • returns {Promise}

Events

  • emits: generate with the generator name and the array of tasks that are queued to run.

Example

// run tasks `bar` and `baz` on generator `foo`
app.generate('foo', ['bar', 'baz']);

// or use shorthand
app.generate('foo:bar,baz');

// run the `default` task on generator `foo`
app.generate('foo');

// run the `default` task on the `default` generator, if defined
app.generate();

.toAlias

Create a generator alias from the given name. By default, generate- is stripped from beginning of the generator name.

Params

  • name {String}
  • options {Object}
  • returns {String}: Returns the alias.

Example

// customize the alias
const app = new Generate({ toAlias: require('camel-case') });

.isGenerators

Returns true if every name in the given array is a registered generator.

Params

  • names {Array}
  • returns {Boolean}

.formatError

Format task and generator errors.

Params

  • name {String}
  • returns {Error}

.disableInspect

Disable inspect. Returns a function to re-enable inspect. Useful for debugging.

.base

Get the first ancestor instance of Composer. Only works if generator.parent is defined on child instances.

.name

Get or set the generator name.

Params

  • {String}

  • returns {String}

.alias

Get or set the generator alias. By default, the generator alias is created by passing the generator name to the .toAlias method.

Params

  • {String}

  • returns {String}

.namespace

Get the generator namespace. The namespace is created by joining the generator's alias to the alias of each ancestor generator.

Params

  • {String}

  • returns {String}

.depth

Get the depth of a generator - useful for debugging. The root generator has a depth of 0, sub-generators add 1 for each level of nesting.

  • returns {Number}

Composer#parse

Static method that returns a function for parsing task arguments.

Params

  • register {Function}: Function that receives a name of a task or generator that cannot be found by the parse function. This allows the register function to dynamically register tasks or generators.
  • returns {Function}: Returns a function for parsing task args.

Composer#isGenerator

Static method that returns true if the given val is an instance of Generate.

Params

  • val {Object}
  • returns {Boolean}

Composer#create

Static method for creating a custom Composer class with the given `Emitter.

Params

  • Emitter {Function}
  • returns {Class}: Returns the custom class.

Composer#Tasks

Static getter for getting the Tasks class with the same Emitter class as Composer.

Params

  • Emitter {Function}
  • returns {Class}: Returns the Tasks class.

Composer#Task

Static getter for getting the Task class.

Example

const { Task } = require('composer');

Events

task

app.on('task', function(task) {
  switch (task.status) {
    case 'starting':
      // Task is running
      break;
    case 'finished':
      // Task is finished running
      break;
  }
});

task-pending

Emitted after a task is registered.

task-preparing

Emitted when a task is preparing to run, right before it's called. You can use this event to dynamically skip tasks by updating task.skip to true or a function.

Release history

See the changelog.

About

<summary>Contributing</summary>

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

<summary>Running Tests</summary>

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
<summary>Building docs</summary>

(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

You might also be interested in these projects:

  • assemble: Get the rocks out of your socks! Assemble makes you fast at creating web projects… more | homepage
  • enquirer: Stylish, intuitive and user-friendly prompt system. Fast and lightweight enough for small projects, powerful and… 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

Contributors

Commits Contributor
227 doowb
72 jonschlinkert

Author

Brian Woodward

License

Copyright © 2018, Brian Woodward. Released under the MIT License.


This file was generated by verb-generate-readme, v0.8.0, on November 11, 2018.

changelog

v3.0.0

Breaking changes

  • Support for custom inspect methods was removed. Please follow Node's recommended practices for creating a custom inspect method.

v3.0.0

  • Completely refactored from the ground up.
  • For the most part, .task, .build, .series and .parallel work the same way. However, event handling has changed. Please see the readme for more information and documentation.

v2.0.0

  • Now requires Node.js v4.0 or higher

v1.0.0

  • Updates the events that are emitted and adds statuses to the objects emitted on the events. see issues #20 and #21
  • Updates the event objects to expose human readable durations. see issue #23
  • Removes unused properties. see issue #24
  • Updates .build to return a promise when the callback is not passed in. see issue #28

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.