npm package: @pipeline/pipe
Description: A package oriented task runner with a simple API like gulp.
Latest version: 1.0.1

# @pipelinejs/pipe
[![Build Status](https://travis-ci.org/pipelinejs/pipe.svg)](https://travis-ci.org/pipelinejs/pipe) [![Dependency Status](https://david-dm.org/pipelinejs/pipe.svg)](https://david-dm.org/pipelinejs/pipe) [![devDependency Status](https://david-dm.org/pipelinejs/pipe/dev-status.svg)](https://david-dm.org/pipelinejs/pipe#info=devDependencies) [![Code Climate](https://codeclimate.com/github/pipelinejs/pipe/badges/gpa.svg)](https://codeclimate.com/github/pipelinejs/pipe) [![Test Coverage](https://codeclimate.com/github/pipelinejs/pipe/badges/coverage.svg)](https://codeclimate.com/github/pipelinejs/pipe/coverage)

> A package oriented build tool with a simple API like gulp.

## Features
* Easily configure your build process for each package of your application.
* Automatic task creation based upon configured package objects.

## Installation
```js
npm i -D @pipeline/pipe
```

## Setup & Configuration
pipe is configured via a so called `pipefile.js` in your projects root.

#### Example `pipefile.js`
```js
import pipe from '@pipelinejs/pipe';
import scripts from '@pipelinejs/pipe-scripts';

// Register plugins.
pipe.use(scripts).configure({
	// The base identifier under which the plugin will be registered under.
	id: 'compile:scripts'
});

// Register application packages.
pipe.package('myPackage').configure({
	// The directory of 'myPackage'.
	directory: 'myPackage/',

	// Example configuration for the scripts task.
	scripts: {
		src: 'src/js/',
		dest: 'dist/js/',

		bundles: [{
			id: 'app',
			src: 'index.js',
			dest: 'index.min.js'
		}]
	}
});

// You can also register tasks the traditional 'gulp way'.
pipe.registerTask('default', () => {
	// Your task logic.
});
```

## API
#### pipe.use
Arguments: `Function` The plugin function.

Use a pipe plugin. Returns a `configure` method which requires a `id` key,
which is the prefix for the task names of the plugin.

#### pipe.package
Arguments: `String` The `id` of the package you want to register.

Registers a package. Returns a `configure` method which accepts the package configuration.

#### pipe.registerTask
Arguments:
1. `String` The `id` of the task you want to register.
2. `Function` The task `Function` you want to execute once executing `pipe yourTaskName`.

Registers a package. Returns a `configure` method which accepts the package configuration.

## Environment
Some pipe plugins want to interact with the environment of your system.
For example, on the production server we may want to concatenate and minify all assets on the task `build`.
Pipeline uses the system environment variable `PIPELINE_ENV`, the default value is `development`.
Because plugins rely on a consistent scheme for this value, it's not possible to use custom values here.
Valid values for the system environment variable `PIPELINE_ENV` are `development`, `staging` and `production`.

## Plugin API
All pipe plugins export a curry function, lets call it 'export'.
The export gets invoked for each package the user has configured.
Pipe passes an options object to the export, which contains `taskName`, `packages`, `env` and `registerTask` key/value pairs.

#### id
The `id` argument is the identifier under which the user has registered your plugin.

#### packages
The `packages` argument is an array which contains all registered packages.

#### environment
The `environment` argument holds the current environment of the user/system.
For more info regarding all possible values, take a look at [#environment](#environment).

#### registerTask
The `registerTask` function is the backbone of pipe.
Unlike most task runners, plugins can and should decide if / when a task should be registered.
This function can take 3 arguments, the first one should always be a string which is your task name.
The second one can be either a function, which will be executed once the task has been called,
or an array containing sub task names which should be run concurrent with the task.

If you have specified an array as the second argument, you are free to pass a third one which then will be used as your task.

#### Example plugin
Below is a pretty straight forward implementation for a pipe plugin.
```js
// Index.js
import taskFunction from './task.js';

export default ({id, packages, registerTask, environment} = {}) => {
	packages.forEach(packageModel => {
		const {packageId} = packageModel;

		registerTask(`${id}:${packageId}`, taskFunction);
	});
}
```

As you can see, the export registers the tasks, and the `taskFunction`
itself holds all the logic you want to execute when a task is being called.

## Contributing
We use xo to lint the code, please take care to run `npm test` before you commit something.
If you add or modify methods or the API, please add unit tests as specified in the `*.spec.js` files.

## License
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.