Module sinks

Terminal operations that consume the items of a feed and compute the final result.

Sinks close a pipe: applying one to a Feed triggers execution and returns a promise resolving to the final result. Those that can decide their outcome early stop consuming rather than draining the source, while those collecting items into a container return it deeply immutable, freezing the container together with the items, keys and values collected into it. Those reducing the feed to a single value, whether computed over its items or selected among them, resolve to undefined when the feed carries none and no result is defined, leaving the choice of a fallback to the caller; seek fails instead, so the item it hands back is usable as is.

The item type of a sink is taken from the feed it is applied to, or from the Sink type it is declared under, never from the consumer, predicate, extractor, reducer or comparator handed to it: a function accepting any item, console.log or Boolean among them, leaves the item type untouched, while one accepting a different type is rejected. A sink composed on its own, outside a pipe, states its item type in the type it is declared under or as an explicit type argument.

Every sink is classified along three axes:

incremental or exhaustive, for how much of the feed it draws before resolving
streaming or materialising, for what it holds in memory
stateless or stateful, for whether its result depends on every item drawn

Warning

An exhaustive sink never resolves on an infinite feed, and a materialising one may exhaust memory on a large feed, bounded or not. Every sink but find, seek, some and every is exhaustive, and the ones collecting items, into a container or into a single string, materialise the whole feed as well. Bound the feed upstream with take.

Custom Sinks close a pipe, consuming the items and returning a promise for the final result; a computation delegating to operations already available applies them to the feed it draws from, which is drained by a single pass, however repeatable the source behind it:

import { pipe } from '@metreeca/flow';
import { items } from '@metreeca/flow/feeds';
import type { Sink } from '@metreeca/flow';

function histogram<V>(): Sink<V, Map<V, number>> {
  return async source => {
    const counts = new Map<V, number>();
    for await (const item of source) { counts.set(item, (counts.get(item) ?? 0)+1); }
    return counts;
  };
}

await pipe(
  (items(["a", "b", "a"]))
  (histogram())
);  // Map(2) { "a" => 2, "b" => 1 }

Functions

avg: Creates a sink averaging the items of the feed.
count: Creates a sink counting the items of the feed.
each: Creates a sink handing every item to a consumer.
every: Creates a sink reporting whether every item matches a predicate.
find: Creates a sink retrieving the first matching item of the feed.
max: Creates a sink selecting the greatest item of the feed.
min: Creates a sink selecting the least item of the feed.
reduce: Creates a sink reducing the feed to a single value, with or without an initial value.
seek: Creates a sink retrieving the first matching item of the feed, failing if none does.
some: Creates a sink reporting whether some item matches a predicate.
sum: Creates a sink summing the items of the feed.
toArray: Creates a sink collecting the items of the feed into an array.
toMap: Creates a sink collecting items or extracted values into a map under extracted keys.
toObject: Creates a sink collecting items or extracted values into an object under extracted keys.
toSet: Creates a sink collecting the distinct items of the feed into a set.
toString: Creates a sink joining the items of the feed into a string.

Module sinks

Functions

Settings

On This Page