gear

Gear.js

Task-Based Build System

Gear.js is a scriptable build system using simple tasks that act like a sequence of piped commands.

Features include:

• Basic building blocks that can be combined to perform complex builds.
• Tasks are simply defined and keep system internals to a minimum.
• Asynchronous execution.
• Extensible task loading via NPM, file, or directory.
• Advanced flow control for complex task execution.

Installation

To get the most out of Gear.js, you will want to install gear-lib which contains tasks for linting, minifying, and deploying JS/CSS assets.

$ npm install gear
$ npm install gear-lib

Quick Examples

Chaining Tasks

new gear.Queue()
 .load('foo.js')
 .log('read foo.js')
 .inspect()
 .write('foobarbaz.js')
 .run();

Execute Tasks Using Array Style

new gear.Queue()
 .load(['foo.js', {file: 'bar.js'}, 'baz.js'])
 .log('read foo.js')
 .inspect()
 .write(['newfoo.js', 'newbar.js']) // Not writing 'baz.js'
 .run();

Complex Task Execution

new gear.Queue()
 .load('foo.js')
 .log('Complex Task')
 .tasks({
    read: {task: 'load', options: ['foo.js', 'bar.js', 'baz.js']}
    combine: {task: 'concat', requires: ['read']}
    minify: {task: 'jsminify', requires: ['combine']}
    print: {task: 'inspect', requires: ['read', 'combine', 'minify']} // Runs when read, combine, and minify complete
    parallel: {task: 'log', options: "Hello gear world!"} // Run parallel to read
 }).run();

Documentation

Core

• Queue
• Queue.task
• Queue.run
• Registry
• Registry.load

Core Tasks

• load
• write
• concat
• inspect
• log
• tasks

Library Tasks

Custom Tasks

## Core ### Queue(options)

Queue constructor.

Arguments

• options.registry - Registry loaded with available tasks.

Example

new gear.Queue()
 .log('test')
 .run();

---

### Queue.task(name, options)

Helper method to run the specified task. Preferred task execution style is to call the task directly i.e. inspect() instead of task('inspect').

Arguments

• name - Name of task in registry.

Example

new gear.Queue()
 .task('log', 'Hello, world!')
 .run();

---

### Queue.run(callback)

Runs the queue.

Arguments

• callback - (optional) Callback accepting (err, results)

Example

new gear.Queue()
 .log('test')
 .run();

---

### Registry()

Creates a new Registry instance. Registries contain available tasks.

Arguments

• options - (optional) Same as .load

Example

gear.Registry();

---

### Registry.load(options)

Load tasks from NPM, directory, or file.

Arguments

• options.module - Module to load tasks from.
• options.dirname - Directory to load tasks from.
• options.filename - File to load tasks from.

Example

gear.Registry().load({dirname: 'foo'});

---

## Tasks ### load(sources)

Loads blobs from different sources.

Arguments

• sources - List of sources.

Example

// source - Filename or object to load.
// source.file - Filename of resource.
.load(['foo', 'baz'])
.load([{file: 'foo'}, {file: 'bar'}, {file: 'baz'}])

---

### write(options)

Arguments

• options.file - File to write, will replace {checksum} with hash of blob content.

Write the blob to disk.

Example

.write({file: 'foo'})

---

### concat()

Concatenates blobs.

Example

.concat()

---

### inspect()

Inspects blobs.

Example

.inspect()

---

### log(string)

Arguments

• string - String to log.

Log a message.

Example

.log('Finished')

---

### tasks(workflow)

Arguments

• workflow - Task workflow.

Execute tasks in parallel with optional dependencies. Data is joined on completion.

Example

// label - Task instance name.
// label.task - Task name.
// label.options - Task options.
// label.requires - List of labels that must be executed before this task runs.
.tasks({
    label_1: {task: 'log', options: 'Hello, world!'}
    label_2: {task: 'log', options: 'Hello, world 2!', requires: ['label_1']}
})

## Library Tasks

Install gear-lib which contains tasks such as:

• jslint
• jsminify
• csslint
• cssminify
• s3

$ npm install gear-lib

## Custom Tasks

Writing a task is especially easy compared to other Node build systems. There is no need to use Gear.js internals within a task. Tasks operate on immutable blobs. Blobs have a body property. The task returns transformed data via its callback.

Arguments

• options - Options for the task.
• blob - Immutable blob.
• done(err, result) - Callback executed when task is complete.

Example

// example.js
// Example task creates new blob containing `string`
exports.example = function(string, blob, done) {
    done(null, blob.create(string)); // blob.create() is equivalent to new Blob()
};

Running Example Task

new gear.Queue({registry: new gear.Registry({filename: 'example.js'})})
 .example('EXAMPLE')
 .run();

Who's Using Gear.js

• Mojito Shaker by Yahoo.

Special Thanks

Gear.js takes inspiration from a few sources:

• buildy created by mosen.
• grunt created by cowboy.