gulpプラグインエラー時に発生するイベントの調査

gulpプラグインでは、エラー時の処理として emit('error') した後に callback() を実行しているものをよく見かける（例えばこれとか）。

if (...) {
  this.emit('error', errorObject);
  callback();
}

このような場合、プラグイン呼び出し側で発生するイベントは'error'イベントなのか'end'イベントなのか、理解が曖昧だったので調査してみる。

調査の概要

'error'イベントおよび'end'イベントの発生条件を調べる。組み合わせる条件は以下の通り。

a. プラグイン内で emit('error') を実行するか
b. プラグイン内で callback を実行するか
c. プラグイン内で callback を実行する場合、callback に引数与えるか

調査用に使ったソースは以下のとおり。コマンドライン引数で実行条件を指定できるようになっている。

var gulp    = require('gulp');
var gutil   = require('gulp-util');
var through = require('through2');

/*
 * テスト条件をコマンドライン引数から受け取る
 */
var emit       = gutil.env.emit;      // plugin内でemit('error')するか
var cb         = gutil.env.cb;        // plugin内でcallbackを呼び出すか
var cbWithArg  = gutil.env.cbWithArg; // plugin内でcallbackに引数与えるか

/*
 * テスト用のプラグイン関数
 */
function testPlugin(emit, cb, cbWithArg) {
  return through.obj(function (file, encoding, callback) {

    if (emit)
      this.emit('error', 'emit error');

    if (cb) {
      if (cbWithArg)
        callback('callback argument');
      else
        callback();
    }

  });
}

/*
 * テスト用gulpタスク
 */
gulp.task('default', function() {

  gulp.src('src/file')
      .pipe(testPlugin(emit, cb, cbWithArg))
        .on('error', function(error) {
          console.log('* error handler: ' + error);
        })
        .on('end', function() {
          console.log('* end handler: ');
        })
      .pipe(gulp.dest('dest/'));

});

調査結果

条件a	条件b	条件c	結果
emitなし	callbackなし	-	発生するイベントなし
emitなし	callback有り	callback引数なし	'end'イベントのみ発生
emitなし	callback有り	callback引数有り	'error'イベントのみ発生
emit有り	callbackなし	-	'error'イベントのみ発生
emit有り	callback有り	callback引数なし	'error'イベントのみ発生
emit有り	callback有り	callback引数有り	'error'イベントのみ発生

どうやら'error'と'end'が同時に発生することは無さそう。