Drop-in replacement for run-sequence for gulp 4

Run a sequence of tasks, in the order you specify, as part of a greater task.
(This package aims to help tasks, formerly dependent on run-sequence for gulp 3, run in gulp 4.)

Use

 const gulp = require('gulp');
const runSequence = require('gulp4-run-sequence');
const fs = require('fs');

// This will run in this order:
// * 'boil-water'
// * 'steep-tea' and 'boil-egg' concurrently
// * 'peel-egg'
// * Finally, the callback function.
gulp.task('breakfast', function (callback) {
  runSequence(
    'boil-water',
    ['steep-tea', 'boil-egg'],
    'peel-egg',
    callback
//  ^^^^^^^^
//  This informs that the sequence is complete.
  );
});

// Configure boil-water, steep-tea, boil-egg, and peel-egg as you wish,
// but make sure they return a stream or promise, or handle the callback.
// Examples:

gulp.task('boil-water', function () {
  // Return the stream from gulp.
  return gulp.src('water').pipe(...)...
});

gulp.task('boil-egg', function () {
  return new Promise(function (resolve, reject) {
    // Make sure asynchronous tasks are resolved or rejected.
  });
});

gulp.task('peel-egg', function (callback) {
  fs.readFile('egg', function (err, data) {
    // Consume data...
    callback();
//  ^^^^^^^^
//  This informs that the task is complete.
  });
});

Use within gulp submodules

If you have a complex gulp setup, with your tasks split up across different
files, gulp4-run-sequence might not be able to find every task, and will error
that such tasks were never defined. In this case, you can configure
gulp4-run-sequence to look at the gulp within the submodule, like so:

 // Explicitly declare gulp particular to your submodule.
const gulp = require('./path/to/gulp');
// Explicitly assign this gulp to gulp4-run-sequence.
const runSequence = require('gulp4-run-sequence').use(gulp);

// ...and then use normally.
gulp.task('supertask', function (callback) {
  runSequence('subtask0', 'subtask1', callback);
});

Options

errorOnInvalidArgumentType: Set this to true in order to throw an error if an
invalid argument type has been passed. The only valid argument types are string,
array, and function.

Example:

 runSequence.options.errorOnInvalidArgumentType = true;

gulp.task('task', function (cb) {
  // null is neither string, array, nor function, so this will error:
  runSequence('foo', null, 'bar', cb);
});

The options in the gulp 3 version of run-sequence no longer apply.

showErrorStackTrace no longer applies because errors are handled entirely
within the gulp 4 stack. A good command of streams, promises, and callback
functions will deliver the desired amount of error verbosity.

ignoreUndefinedTasks no longer applies because falsy arguments will either be
skipped without warning (default behavior), or cause an error if
errorOnInvalidArgumentType is set to true.

Why the culinary task names?

Computational tasks might be too abstract for visualizing sequences and
concurrency. It's much easier to visualize steeping tea and boiling eggs
concurrently, but only after water has come to a boil.

It might also be irresponsible to suggest running certain tasks concurrently,
when concurrent operation would not be optimal for those tasks.

First, we need to understand what "parallel", "concurrent", and
"asynchrony" mean in terms of computing.

"Parallel" computing refers to distributing processes across multiple
processor cores.

"Concurrent" computing refers to running multiple processes in such a way,
that they appear to be running at the same time. This can be accomplished by
rapidly switching between the processes on one processor core.

"Asynchrony" refers to when a process runs outside the main execution flow,
and the main execution might need a response. If it does, it must not block
other processes that don't depend on the response, while it waits.

JavaScript, and Node.js in particular, are frequently referred to as being
"single-threaded". In recent years, this has become wholly untrue. If you are
working on production-level parallel JavaScript, firstly, kudos! Secondly, we're
not sure why you're reading this, but thanks for checking out
gulp4-run-sequence!

Now consider a procedure found in nearly every gulp implementation: a file
read. It is not a good idea to read files concurrently on a single machine, even
if it has many processor cores. We should assume the machine has a single disk
drive, and that the drive has a single read/write head. Even if those aren't the
case, we should assume there is only one pathway open at a given time, on which
the data can travel from drive to memory.

Let's make a culinary analogy: Assume we need 2 liters of warm water evenly
mixed from a cold tap and a hot tap. However, the taps are 10 meters apart. Any
rational person would mix the water sequentially, filling a liter of cold water,
walking the 10 meters, and filling another liter of hot water.

Trying to make this water gathering appear concurrent by filling smaller
amounts of water at a time, and walking more, is called "thrashing" if applied
to a disk drive!

Acknowledgements

This package is inspired entirely by
run-sequence for gulp 3.
Credit and gratitude are due for
its contributors.

Also recommended: gulp 3 with long-term support