Skip to content

Commit

Permalink
Docs: Update series() documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
janiceilene authored and phated committed Oct 19, 2018
1 parent d680487 commit 4169cb6
Showing 1 changed file with 94 additions and 20 deletions.
114 changes: 94 additions & 20 deletions docs/api/series.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,35 +5,109 @@ hide_title: true
sidebar_label: series()
-->

# `gulp.series(...tasks)`
# series()

Takes a number of task names or functions and returns a function of the composed
tasks or functions.
Combines task functions and/or composed operations into larger operations that will be executed one after another, in sequential order. The composed operations from `series()` and `parallel()` can be nested to any depth.

When using task names, the task should already be registered.
## Usage

When the returned function is executed, the tasks or functions will be executed
in series, each waiting for the prior to finish. If an error occurs,
execution will stop.
```js
const { series } = require('gulp');

function javascript(cb) {
// body omitted
cb();
}

function css(cb) {
// body omitted
cb();
}

exports.build = series(javascript, css);
```

## Signature

```js
series(...tasks)
```

### Parameters

| parameter | type | note |
|:--------------:|:------:|-------|
| tasks <br> **(required)** | function <br> string | Any number of task functions can be passed as individual arguments. Strings can be used if you've registered tasks previously, but this is not recommended. |

### Returns

A composed operation to be registered as a task or nested within other `series` and/or `parallel` compositions.

When the composed operation is executed, all tasks will be run sequentially. If an error occurs in one task, no subsequent tasks will be run.

### Errors

When no tasks are passed, throws an error with the message, "One or more tasks should be combined using series or parallel".

When invalid tasks or unregistered tasks are passed, throws an error with the message, "Task never defined".

## Forward references

A forward reference is when you compose tasks, using string references, that haven't been registered yet. This was a common practice in older versions, but this feature was removed to achieve faster task runtime and promote the use of named functions.

In newer versions, you'll get an error, with the message "Task never defined", if you try to use forward references. You may experience this when trying to use `exports` for your task registration *and* composing tasks by string. In this situation, use named functions instead of string references.

During migration, you may need to use the [forward reference registry][undertaker-forward-reference-external]. This will add an extra closure to every task reference and dramatically slow down your build. **Don't rely on this fix for very long**.

## Avoid duplicating tasks

When a composed operation is run, each task will be executed every time it was supplied.

A `clean` task referenced in two different compositions would be run twice and lead to undesired results. Instead, refactor the `clean` task to be specified in the final composition.

If you have code like this:
```js
gulp.task('one', function(done) {
// do stuff
done();
// This is INCORRECT
const { series, parallel } = require('gulp');

const clean = function(cb) {
// body omitted
cb();
};

const css = series(clean, function(cb) {
// body omitted
cb();
});

gulp.task('two', function(done) {
// do stuff
done();
const javascript = series(clean, function(cb) {
// body omitted
cb();
});

gulp.task('default', gulp.series('one', 'two', function(done) {
// do more stuff
done();
}));
exports.build = parallel(css, javascript);
```

## tasks
Type: `Array`, `String` or `Function`
Migrate to this:
```js
const { series, parallel } = require('gulp');

function clean(cb) {
// body omitted
cb();
}

function css(cb) {
// body omitted
cb();
}

function javascript(cb) {
// body omitted
cb();
}

exports.build = series(clean, parallel(css, javascript));
```

A task name, a function or an array of either.
[undertaker-forward-reference-external]: https://github.com/gulpjs/undertaker-forward-reference

0 comments on commit 4169cb6

Please sign in to comment.