doc: stream.pipeline documentation is misleading WRT 'Iterable' as a valid first argument.

[rbuckton]

📗 API Reference Docs Problem

• Version: v14.7.0
• Platform: Windows 10 (64-bit)
• Subsystem: stream

Location

Affected URL(s):

• https://nodejs.org/api/stream.html#stream_stream_pipeline_source_transforms_destination_callback

Description

The documentation states the following:

This is misleading, as an Array is a valid Iterable, yet using an Array as the first argument with multiple streams results in an error:

const stream = require("stream");

async function main() {
    await stream.pipeline(
        /*stream1*/ [1, 2, 3],
        /*stream2*/ new stream.PassThrough({ objectMode: true }),
        /*callback*/ () => { console.log("done"); });
}

main().catch(e => console.error(e));

Output:

TypeError [ERR_INVALID_ARG_TYPE]: The "source" argument must be of type function or an instance of Stream, Iterable, or AsyncIterable. Received type number (1)
    at Function.pipeline (internal/streams/pipeline.js:199:15)
    at main (D:\dev\scratch\pipeline\index.js:4:18)
    at Object.<anonymous> (D:\dev\scratch\pipeline\index.js:10:1)
    at Module._compile (internal/modules/cjs/loader.js:1256:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1277:10)
    at Module.load (internal/modules/cjs/loader.js:1105:32)
    at Function.Module._load (internal/modules/cjs/loader.js:967:14)
    at Function.executeUserEntryPoint [as runMain] (internal/modules/run_main.js:60:12)
    at internal/main/run_main_module.js:17:47 {
  code: 'ERR_INVALID_ARG_TYPE'
}

However, if you change [1, 2, 3] to [1, 2, 3].values() then the call evaluates successfully. It seems like stream.pipeline sees the first argument is an Array and always picks stream.pipeline(streams, callback), even if there is a destination and may be one or more transforms.

The way the parameters are represented is also confusing. It looks like they are sorted alphabetically rather than based on the "overload" being called, so the "Returns:" bullet points don't make much sense.

---

• I would like to work on this issue and submit a pull request.

[ronag]

sounds like a bug in pipeline