API · Aggregate

`sortBy()`

Buffer the complete stream and order it with a synchronous comparison function.

Signature

sortBy(
  fn: (left: T, right: T, leftContext: C, rightContext: C) => number,
): Exstream<T, C>

Example

const ranked = exstream(products).sortBy((left, right) => right.score - left.score)

Parameters

fn

Type (left, right, leftContext, rightContext) => numberRequired

Return a negative number for left-first, a positive number for right-first, or zero to preserve their relative order. Context arguments are supplied only when the callback declares at least three parameters.

Behavior

All successful values and contexts are retained until upstream ends. Sorting is stable for equal comparisons and each emitted value keeps its original context. No output is available before completion, and infinite input never finishes. Existing record errors pass through immediately and are excluded from sorting.

The comparator is synchronous. Promise results are coerced by the platform sort algorithm and are not useful.

Errors

A thrown comparator failure produces one record error whose input is the array of collected successful values; its aggregate context contains their contexts. No sorted values are emitted after that failure.

Forms

stream.sortBy(compare)
exstream.pipeline().sortBy(compare)
exstream.sortBy(compare, stream)
stream.through(exstream.sortBy(compare))

sort(), sortedGroupBy(), sortedJoin()

sortBy()