@promistream/simple-sink

A generic sink stream for Promistreams that can cover most usecases. It automatically drives the pipeline above it once it is read from once, in its default configuration.

Note that if you simply need to collect all of the values that came from a pipeline into an array, you are probably looking for @promistream/collect instead, which is built on top of this stream. This library (@promistream/simple-sink) is only useful if you need lower-level control over reads and cumulative results than that.

Stream characteristics:

• Promistream version: 0
• Stream type: Sink
• Supports parallelization: No, queues parallel reads
• Buffering: None

Examples

Both of these examples are included in the package in runnable form.

A simple stream (example-simple.js):

"use strict";

const pipe = require("@promistream/pipe");
const fromIterable = require("@promistream/from-iterable");
const simpleSink = require("@promistream/simple-sink");

(async () => {
	let result = await pipe([
		fromIterable([ 1, 2, 3, 4, 5 ]),
		simpleSink(async (value, abort) => {
			console.log("value seen:", value);
		})
	]).read();

	console.log("result:", result);
})();

/* Output:
value seen: 1
value seen: 2
value seen: 3
value seen: 4
value seen: 5
result: undefined
*/

A stream that uses more of the features (example.js):

"use strict";

const pipe = require("@promistream/pipe");
const fromIterable = require("@promistream/from-iterable");
const simpleSink = require("@promistream/simple-sink");

(async () => {
	try {
		let result = await pipe([
			fromIterable([ 1, 2, 3, 4, 5 ]),
			simpleSink({
				onValue: async (value, abort) => {
					console.log("value seen:", value);
					// if (value === 3) { abort(new Error("uncomment this to trigger an abort")); }
				},
				onEnd: async () => {
					console.log("stream finished");
					return "arbitrary value";
				},
				onAbort: async (error) => {
					console.log("stream aborted due to reason:", error);
				}
			})
		]).read();

		console.log("result:", result);
	} catch (error) {
		console.log("caught error:", error);
	}
})();

/* Output:
value seen: 1
value seen: 2
value seen: 3
value seen: 4
value seen: 5
stream finished
result: arbitrary value
*/

API

simpleSink(options)

In the typical, simple usecase, all you need to do is to specify a single async callback that does something with each value, and returns (resolves) once it is done. You may also need to specify an onEnd handler to produce a cumulative result once the pipeline ends. The other options are mainly for more complex cases.

• options: Either a function (which will be interpreted as the onValue option), or an object of options:
  • onValue: Required. An async callback that is called for every value that is read from upstream. It receives the arguments (value, abort), where the value is the value that has been read, and abort is a callable function. There are a few things that this callback can do:
    • Return, call, or throw nothing: This is the most common case, and lets the sink do its job of just continuously reading values from upstream and invoking your callback.
    • Return a Promise that rejects, or throw an error: As you would expect, this signals an error condition and causes the pipeline to be terminated early with an error condition.
    • Return a Promise that resolves to undefined: This pauses the reading by the sink until the Promise has resolved, and so can be used to delay reads (by having the Promise resolve at a later time).
    • Return a Promise that resolves to a non-undefined value: This causes the pipeline's read operation to return before the source stream has ended; this can be used to do some internal reading of a pipeline before handing it over to user code, for example, like in a protocol handler. Note that in this case, the stream-end handlers will not be called! The sink simply detaches and leaves the rest of the pipeline untouched.
    • Call the provided abort function with true as the argument: This asks the source stream to terminate early. It is equivalent to the abort method in the Promistream spec, and should only be used under success conditions (ie. the stream should terminate early for an expected and normal reason). Note that source streams are not required to honour this request.
    • Call the provided abort function with an Error object as the argument: This terminates the stream early, under error conditions. It is again equivalent to abort in the spec, and should be used in case of unexpected errors. Note that an Error that's thrown/rejected from the callback is handled the same way, so you should rarely need this.
  • onEnd: Optional. An async callback that is called when the stream ends normally, ie. the source stream has ended and the pipeline is being torn down. This is where you would do cleanup of underlying resources under success conditions. You can also generate and return a cumulative value here, which is returned from the read that started the sink processing.
  • onAbort: Optional. An async callback that is called when the stream terminates abnormally, ie. some sort of error has occurred, and the pipeline was aborted. This where you would do cleanup of underlying resources under error conditions, when the pipeline has not fully completed and never will.
  • onSourceChanged: Optional. An async callback that is called whenever the stream that is being read from, changes. In typical use (using @promistream/pipe), this will never happen, but you need to account for it if your stream logic depends on knowing what stream a value came from.