Better mapping.

npm install --save gulp-map

Works with

var map = require('gulp-map');

When returning a promise, it is mapped asynchronously (in parallel):

var Q = require('kew');

// wait 500 ms and add a 'slow' tag to the file
.pipe(map(function (file) {
	return Q
		.delay(500)
		.then(function () {
			file.tags = (file.tags || []).push('slow')
			return file
		})
	})
}))

The stream 'end' event delayed until all promisses are finished.

When you return undefined from your promise or regular function, the file is filtered from the stream.

.pipe(map(function (file) {
	if (file.path.match(/gulpfile\.js/))
		return file
	// other files not emitted
}))

That's it.

Alternatives

For regular callback style mapping, just use map-stream.

var map = require('map-stream');
// ...
.pipe(map(function(file, done){
	done(null, file);
}))

For both data and end events, through2 works well:

var Through = require('through2').obj;
// ...
.pipe(Through(
	function handle_data(file, encoding, done) {
		this.push(file);
		done();
	}
	function handle_end(done) {
		done();
	}
))