Is pipeline( ) now recommended over .pipe( )? [yes]

[rootwork]

Gulp 4 documentation for Working with files says:

The main API of a stream is the .pipe() method for chaining Transform or Writable streams.

However, over at #2499, @phated mentions several times in his code review that we should use pipeline() instead, for instance:

Let's use pipeline() (from node's Stream module) syntax any time things are being piped.

Also back in 2018 @phated said on #2182:

It should be the default going forward (and switched to stream.pipeline from node core once 10 becomes LTS and 8 rotates out).

Node 14 is LTS now (though of course if you want to use watch, gulp is currently limited to Node 12 because of gulpjs/glob-watcher#55).

So should pipeline() be used going forward? If so, I'd be happy to work on documentation PRs. But I didn't want to open one (or a bug report) before getting some feedback about whether this is indeed the right path.

It's not necessarily as simple as swapping out .pipe() for pipeline() because the latter expects error-handling, and previously common patterns like .on('end'...) and .on('finish'...) would no longer apply -- and some gulp plugins like gulp-hb expect that sort of thing. So all the more important to publicize this if the accepted use needs to change.

FWIW, a big part of my motivation here is wanting to get a fully up-to-date step-by-step guide on using Gulp 4 with it's current syntax (e.g. src() not gulp.src() or gulp.task()), using module exports and ECMAScript 2015 standards (at least!), running on Node 12. The vast majority of guides (not to mention things like SO answers) are out of date in all these different ways. So if pipeline() should be part of that new standard, I want to include it.

Thanks for your feedback! And if you've written any modern guides like I'm describing already, please share. There's really a dearth of updated information out there.

[phated]

@rootwork Yep! Using pipeline is actually the suggestion now, though we didn't want to add that to the main website docs as it is yet-another-hurdle for anyone that doesn't know node. I was even able to get an upstream change in node that causes the pipeline to fail properly if you don't specify a callback, such that export function foo() { return pipeline(src(), dest()) } would work.

Happy to review anything you want to send over!

[phated]

Also, thank you for being a great open-source citizen with this very detailed and thoughtful approach to your questions!

[rootwork]

Glad to help and thanks for responding so quickly! Your explanation for the documentation on the main site makes sense.

I'm still working out some of the bugs in my own code, but I do want to write something up when I've got it fully working, so I'll put something together.