`interface Stream<T>`

A possibly infinite sequence of elements of type T. See the Stream documentation and the Stream API documentation

Companion namespace: Stream

Extends: Streamable<T>, FastIterable<T>

Implemented by: Stream.NonEmpty<T>, StreamBase<T>

Type parameters

Name	Description
T	the element type

example

const s1 = Stream.empty<number>()
const s2 = Stream.of(1, 3, 2)
const s3 = Stream.range({ start: 10, amount: 15 })

Methods

`[Symbol.iterator]`

Returns a FastIterator instance used to iterate over the values of this Iterable.

Definition

[Symbol.iterator](): FastIterator<T>;

Overrides

FastIterable.[Symbol.iterator]

`append`

Returns the current stream succeeded by the given value

Definition

append(value: OptLazy<T>): Stream.NonEmpty<T>;

Parameters

Name	Type	Description
`value`	`OptLazy<T>`	the value to append

example

Stream.of(1, 2, 3).append(4).toArray()
// => [1, 2, 3, 4]

note

O(1)

`assumeNonEmpty`

Returns the stream as a non-empty instance.

Definition

assumeNonEmpty(): Stream.NonEmpty<T>;

throws

RimbuError.EmptyCollectionAssumedNonEmptyError if the stream is known to be empty.

example

Stream.range({ amount: 100 }).assumeNonEmpty()
// => type: Stream.NonEmpty<number>

note

the function does not actually check if the stream is empty, so treat with extra care @note O(1)

`collect`

Returns a Stream containing the resulting elements from applying the given collectFun to each element in this Stream.

Definition

collect<R>(collectFun: CollectFun<T, R>): Stream<R>;

Type parameters

Name	Description
R	the result element type

Parameters

Name	Type	Description
`collectFun`	`CollectFun<T, R>`	a function taking the parameters below and returning a new element or a skip token - value: the next element - index: the element index - skip: an element that can be returned if the current element should be skipped - halt: a function that, if called, ensures that no new elements are passed

example

Stream.of(1, 2, 3).collect((v, i, skip, halt) => {
if (i === 0) return skip;
if (i === 1) halt();
return String(v)
}).toArray();
// => ['1']

note

O(1)

`concat`

Returns a Stream containing the elements of this Stream followed by all elements produced by the others array of StreamSources.

Definitions

concat<T2 = T>(...others: ArrayNonEmpty<StreamSource.NonEmpty<T2>>): Stream.NonEmpty<T | T2>;

concat<T2 = T>(...others: ArrayNonEmpty<StreamSource<T2>>): Stream<T | T2>;

Type parameters

Name	Default	Description
T2	`T`	the element type of the stream to concatenate

Parameters

Name	Type	Description
`others`	`ArrayNonEmpty<StreamSource.NonEmpty<T2>>`	a series of StreamSources to concatenate.

example

Stream.of(1, 2, 3).concat([4, 5], [6, 7]).toArray()
// [1, 2, 3, 4, 5, 6, 7]

note

O(1)

`contains`

Returns true if the Stream contains given amount instances of given value, using given eq function.

Definition

contains(value: T, amount?: number, eq?: Eq<T>): boolean;

Parameters

Name	Type	Description
`value`	`T`	the value to search for
`amount`	`number`	(default: 1) the amount of values the Stream should contain
`eq`	`Eq<T>`	(optional) the equality function to use

example

Stream.from('marmot').contains('m')    // => true
Stream.from('marmot').contains('m', 2) // => true
Stream.from('marmot').contains('m', 3) // => false
Stream.from('marmot').contains('q')    // => false

note

O(N)

`containsSlice`

Returns true if this stream contains the same sequence of elements as the given source, false otherwise.

Definition

containsSlice(source: StreamSource.NonEmpty<T>, eq?: Eq<T>): boolean;

Parameters

Name	Type	Description
`source`	`StreamSource.NonEmpty<T>`	a non-empty stream source containing the element sequence to find
`eq`	`Eq<T>`	(default: `Eq.objectIs`) the function to use to test element equality

example

Stream.of(1, 2, 3, 4, 5).containsSlice([2, 3, 4])
// => true
Stream.of(1, 2, 3, 4, 5).containsSlice([4, 3, 2])
// => false

`count`

Returns the amount of elements in the Stream.

Definition

count(): number;

example

Stream.of(1, 2, 3).count() // => 3

note

O(N) for most types of Stream @note be careful not to use on infinite streams

`countElement`

Returns the amount of elements that are equal according to the given eq to the given value in the Stream.

Definition

countElement(value: T, eq?: Eq<T>): number;

Parameters

Name	Type	Description
`value`	`T`	the value to compare to
`eq`	`Eq<T>`	(optional) the Eq instance to use to test equality

example

Stream.of(1, 2, 3).countElement(2) // => 1

note

O(N) for most types of Stream @note be careful not to use on infinite streams

`countNotElement`

Returns the amount of elements that are not equal according to the given eq to the given value in the Stream.

Definition

countNotElement(value: T, eq?: Eq<T>): number;

Parameters

Name	Type	Description
`value`	`T`	the value to compare to
`eq`	`Eq<T>`	(optional) the Eq instance to use to test equality

example

Stream.of(1, 2, 3).countNotElement(2) // => 2

note

O(N) for most types of Stream @note be careful not to use on infinite streams

`distinctPrevious`

Returns a Stream containing non-repetitive elements of the source stream, where repetitive elements are compared using the optionally given eq equality function.

Definition

distinctPrevious(eq?: Eq<T>): Stream<T>;

Parameters

Name	Type	Description
`eq`	`Eq<T>`	the `Eq` instance to use to test equality of elements

example

Stream.of(1, 1, 2, 2, 3, 1).distinctPrevious().toArray()
// => [1, 2, 3, 1]

`drop`

Returns a stream that skips the first amount elements of this Stream and returns the rest.

Definition

drop(amount: number): Stream<T>;

Parameters

Name	Type	Description
`amount`	`number`	the amount of elements to skip

example

Stream.of(1, 2, 3).drop(1).toArray()   // => [2, 3]

note

O(N) for most types of Stream

`dropWhile`

Returns a Stream that contains the elements of this Stream starting from the first element that does not satisfy given pred function.

Definition

dropWhile(pred: (value: T, index: number) => boolean): Stream<T>;

Parameters

Name	Type	Description
`pred`	`(value: T, index: number) => boolean`	a predicate function taking an element and its index

example

Stream.of(1, 2, 3).dropWhile(v => v < 2).toArray()
// => [2, 3]

note

O(N)

`elementAt`

Returns the element in the Stream at the given index, or a fallback value (default undefined) otherwise.

Definitions

elementAt(index: number): T | undefined;

elementAt<O>(index: number, otherwise: OptLazy<O>): T | O;

Parameters

Name	Type	Description
`index`	`number`	the index of the element to retrieve

example

Stream.of(1, 2, 3).elementAt(1)        // => 2
Stream.of(1, 2, 3).elementAt(5)        // => undefined
Stream.of(1, 2, 3).elementAt(5, 'a')   // => 'a'

note

O(N) for most types of Stream

`equals`

Returns true if the sequence of elements in this stream are equal to the sequence in the other stream according to the provided eq function.

Definition

equals(other: StreamSource<T>, eq?: Eq<T>): boolean;

Parameters

Name	Type	Description
`other`	`StreamSource<T>`	the other stream to compare
`eq`	`Eq<T>`	(optional) the equality function

example

Stream.of(1, 2, 3).equals([1, 2, 3])     // => true
Stream.of(1, 2, 3, 4).equals([1, 2, 3])  // => false

note

don't use on potentially infinite streams @note O(N)

`every`

Returns true if every element of the Stream satifies given pred function.

Definition

every(pred: (value: T, index: number) => boolean): boolean;

Parameters

Name	Type	Description
`pred`	`(value: T, index: number) => boolean`	a predicate function taking an element and its index

example

Stream.of(1, 2, 3).every((v, i) => v + i > 10)  // => false
Stream.of(1, 2, 3).every((v, i) => v + i < 10)  // => true

note

O(N)

`filter`

Returns a Stream containing only those elements from this Stream for which the given pred function returns true.

Definition

filter(pred: (value: T, index: number, halt: () => void) => boolean): Stream<T>;

Parameters

Name	Type	Description
`pred`	`(value: T, index: number, halt: () => void) => boolean`	a function taking an element and its index, and returning true if the element should be included in the resulting Stream.

note

O(1)

example

Stream.of(1, 2, 3).filter((v, i) => v + i !== 3).toArray()
// => [1, 3]

`filterNot`

Returns a Stream containing only those elements from this Stream for which the given pred function returns false.

Definition

filterNot(pred: (value: T, index: number, halt: () => void) => boolean): Stream<T>;

Parameters

Name	Type	Description
`pred`	`(value: T, index: number, halt: () => void) => boolean`	a function taking an element and its index, and returning false if the element should be included in the resulting Stream.

note

O(1)

example

Stream.of(1, 2, 3).filterNot((v, i) => v + i !== 3).toArray()
// => [2]

`filterNotPure`

Returns a Stream containing only those elements from this Stream for which the given pred function returns false.

Definition

filterNotPure<A extends readonly unknown[]>(pred: (value: T, ...args: A) => boolean, ...args: A): Stream<T>;

Type parameters

Name	Constraints	Description
A	`readonly unknown[]`	the arguments to be supplied to the `pred` function after each element

Parameters

Name	Type	Description
`pred`	`(value: T, ...args: A) => boolean`	a function taking an element and the optionally given `args`, and returning false if the element should be included in the resulting Stream.
`args`	`A`	(optional) the extra arguments to pass to the given `mapFun`

note

O(1)

example

Stream.of(1, 2, 3).filterNotPure(Object.is, 2).toArray()
// => [1, 3]

`filterPure`

Returns a Stream containing only those elements from this Stream for which the given pred function returns true.

Definition

filterPure<A extends readonly unknown[]>(pred: (value: T, ...args: A) => boolean, ...args: A): Stream<T>;

Type parameters

Name	Constraints	Description
A	`readonly unknown[]`	the arguments to be supplied to the `pred` function after each element

Parameters

Name	Type	Description
`pred`	`(value: T, ...args: A) => boolean`	a function taking an element the optionaly given `args`, and returning true if the element should be included in the resulting Stream.
`args`	`A`	(optional) the extra arguments to pass to the given `mapFun`

note

O(1)

example

Stream.of(1, 2, 3).filterPure(Object.is, 2).toArray()
// => [2]

`find`

Returns the first element for which the given pred function returns true, or a fallback value otherwise.

Definitions

find(pred: (value: T, index: number) => boolean, occurrance?: number): T | undefined;

find<O>(pred: (value: T, index: number) => boolean, occurrance: number |undefined, otherwise:OptLazy<O>): T | O;

Parameters

Name	Type	Description
`pred`	`(value: T, index: number) => boolean`	a predicate function taking an element and its index
`occurrance`	`number`	(default: 1) the occurrance number to look for

example

const isEven = (v: number) => v % 2 === 0
Stream.of(1, 2, 3, 4).find(isEven)           // => 2
Stream.of(1, 2, 3, 4).find(isEven, 2)        // => 4
Stream.of(1, 2, 3, 4).find(isEven, 3)        // => undefined
Stream.of(1, 2, 3, 4).find(isEven, 3, 'a')   // => 'a'

note

O(N) for most types of Stream

`first`

Returns the first element of the Stream, or a fallback value (default undefined) if the Stream is empty.

Definitions

first(): T | undefined;

first<O>(otherwise: OptLazy<O>): T | O;

example

Stream.of(1, 2, 3).first()      // => 1
Stream.empty<number>().first()  // => undefined
Stream.empty<number>().first(0) // => 0

note

O(1)

`flatMap`

Returns a Stream consisting of the concatenation of flatMapFun applied to each element.

Definition

flatMap<T2>(flatMapFun: (value: T, index: number, halt: () => void) => StreamSource<T2>): Stream<T2>;

Type parameters

Name	Description
T2	the resulting element type

Parameters

Name	Type	Description
`flatMapFun`	`(value: T, index: number, halt: () => void) =>` `StreamSource<T2>`	a function receiving the inputs described below and returning a `StreamSource` of new elements - value: the next element - index: the index of the element - halt: a function that, if called, ensures that no new elements are passed

note

O(1)

example

Stream.of(1, 2, 3).flatMap((v, i, halt) => {
if (i >= 1) halt();
return [v, i, v + i]
}).toArray()
// => [1, 0, 1, 2, 1, 3]

`flatZip`

Returns a Stream consisting of the concatenation of flatMapFun applied to each element, zipped with the element that was provided to the function.

Definition

flatZip<T2>(flatMapFun: (value: T, index: number, halt: () => void) => StreamSource<T2>): Stream<[T, T2]>;

Type parameters

Name	Description
T2	the result element type

Parameters

Name	Type	Description
`flatMapFun`	`(value: T, index: number, halt: () => void) =>` `StreamSource<T2>`	a function receiving the inputs described below and returning a `StreamSource` of new elements - value: the next element - index: the index of the element - halt: a function that, if called, ensures that no new elements are passed

note

O(1)

example

Stream.of(1, 2, 3).flatZip((v, i, halt) => {
if (i >= 1) halt();
return [v, i, v + i]
}).toArray()
// => [[1, 1], [1, 0], [1, 1], [2, 2], [2, 1], [2, 3]]

`fold`

Returns the value resulting from applying the given the given next function to a current state (initially the given init value), and the next Stream value, and returning the new state. When all elements are processed, the resulting state is returned.

Definition

fold<R>(init: OptLazy<R>, next: (current: R, value: T, index: number, halt: () => void) => R): R;

Type parameters

Name	Description
R	the resulting element type

Parameters

Name	Type	Description
`init`	`OptLazy<R>`	the initial result/state value
`next`	`(current: R, value: T, index: number, halt: () => void) => R`	a function taking the parameters below and returning the new result/state value - current: the current result/state value, initially `init`. - value: the next Stream value - index: the index of the given value - halt: a function that, if called, ensures that no new elements are passed

example

console.log(Stream.empty<number>().fold(5, (current, value) => current + value))
// => 5
console.log(Stream.of(1, 2, 3).fold(5, (current, value) => current + value))
// => 11  (= 5 + 1 + 2 + 3)

`foldStream`

Returns a Stream containing the values resulting from applying the given the given next function to a current state (initially the given init value), and the next Stream value, and returning the new state.

Definition

foldStream<R>(init: OptLazy<R>, next: (current: R, value: T, index: number, halt: () => void) => R): Stream<R>;

Type parameters

Name	Description
R	the resulting element type

Parameters

Name	Type	Description
`init`	`OptLazy<R>`	the initial result/state value
`next`	`(current: R, value: T, index: number, halt: () => void) => R`	a function taking the parameters below and returning the new result/state value - current: the current result/state value, initially `init`. - value: the next Stream value - index: the index of the given value - halt: a function that, if called, ensures that no new elements are passed

example

console.log(
Stream.empty<number>()
.foldStream(5, (current, value) => current + value)
.toArray()
)
// => []
console.log(
Stream.of(1, 2, 3)
.foldStream(5, (current, value) => current + value)
.toArray()
)
// => [6, 8, 11]

`forEach`

Performs given function f for each element of the Stream, using given state as initial traversal state.

Definition

forEach(f: (value: T, index: number, halt: () => void) => void, state?: TraverseState): void;

Parameters

Name	Type	Description
`f`	`(value: T, index: number, halt: () => void) => void`	the function to perform for each element, receiving: - value: the next element - index: the index of the element - halt: a function that, if called, ensures that no new elements are passed
`state`	`TraverseState`	(optional) the traverse state

example

Stream.of(1, 2, 3).forEach((v, i, halt) => {
console.log(v);
if (i >= 1) halt();
})
// => 1, 2

note

O(N)

`forEachPure`

Performs given function f for each element of the Stream, with the optionally given args as extra arguments.

Definition

forEachPure<A extends readonly unknown[]>(f: (value: T, ...args: A) => void, ...args: A): void;

Type parameters

Name	Constraints	Description
A	`readonly unknown[]`	the type of the arguments to be passed to the `f` function after each element

Parameters

Name	Type	Description
`f`	`(value: T, ...args: A) => void`	the function to perform for each element, optionally receiving given extra `args`.
`args`	`A`	(optional) a list of extra arguments to pass to given `f` for each element

example

Stream.of(1, 2, 3).forEachPure(console.log, 'sheep')
// => logs:
// 1 sheep
// 2 sheep
// 3 sheep

note

O(N)

`indexed`

Returns a Stream where each element in this Stream is paired with its index

Definition

indexed(startIndex?: number): Stream<[number, T]>;

Parameters

Name	Type	Description
`startIndex`	`number`	(optional) an alternative start index to use

example

Stream.of(1, 2, 3).indexed().toArray()
// => [[0, 1], [1, 2], [2, 3]]

note

O(1)

`indexOf`

Returns the index of the occurrance instance of given searchValue in the Stream, using given eq function, or undefined if no such value is found.

Definition

indexOf(searchValue: T, occurrance?: number, eq?: Eq<T>): number | undefined;

Parameters

Name	Type	Description
`searchValue`	`T`	the element to search for
`occurrance`	`number`	(default: 1) the occurrance to search for
`eq`	`Eq<T>`	(optional) the equality function to use

example

const source = Stream.from('marmot')
source.indexOf('m')     // => 0
source.indexOf('m', 2)  // => 3
source.indexOf('m', 3)  // => undefined
source.indexOf('q')     // => undefined

note

O(N)

`indexWhere`

Returns the index of the given occurrance instance of the element in the Stream that satisfies given pred function, or undefined if no such instance is found.

Definition

indexWhere(pred: (value: T, index: number) => boolean, occurrance?: number): number | undefined;

Parameters

Name	Type	Description
`pred`	`(value: T, index: number) => boolean`	a predicate function taking an element and its index
`occurrance`	`number`	(default: 1) the occurrance to search for

example

Stream.of(1, 2, 3).indexWhere((v, i) => v + i > 2)      // => 1
Stream.of(1, 2, 3).indexWhere((v, i) => v + i > 2, 2)   // => 2

note

O(N)

`indicesOf`

Returns a Stream containing the indicies of the occurrance of the given searchValue, according to given eq function.

Definition

indicesOf(searchValue: T, eq?: Eq<T>): Stream<number>;

Parameters

Name	Type	Description
`searchValue`	`T`	the value to search for
`eq`	`Eq<T>`	(optional) the equality function to use

example

Stream.from('marmot').indicesOf('m').toArray()
// => [0, 3]

note

O(N)

`indicesWhere`

Returns a Stream containing the indices of the elements for which the given pred function returns true.

Definition

indicesWhere(pred: (value: T) => boolean): Stream<number>;

Parameters

Name	Type	Description
`pred`	`(value: T) => boolean`	a predicate function taking an element

example

Stream.of(1, 2, 3).indicesWhere((v, i) => v + i !== 3).toArray()
// => [0, 2]

note

O(N)

`intersperse`

Returns a Stream with all elements from the given sep StreamSource between two elements of this Stream.

Definition

intersperse(sep: StreamSource<T>): Stream<T>;

Parameters

Name	Type	Description
`sep`	`StreamSource<T>`	the StreamSource to insert between each element of this Stream

example

Stream.of(1, 2, 3).intersperse("ab").toArray()
// => [1, 'a', 'b', 2, 'a', 'b', 3]

note

O(1)

`join`

Returns a string resulting from converting each element to string with options.valueToString, interspersed with options.sep, starting with options.start and ending with options.end.

Definition

join(options?: {
    sep?: string | undefined;
    start?: string | undefined;
    end?: string | undefined;
    valueToString?: ((value: T) => string) | undefined;
    ifEmpty?: string | undefined;
  }): string;

Parameters

Name	Type	Description
`options`	`{` `sep?: string` `\|` `undefined;` `start?: string` `\|` `undefined;` `end?: string` `\|` `undefined;` `valueToString?: ((value: T) => string)` `\|` `undefined;` `ifEmpty?: string` `\|` `undefined;` `}`	(optional) object specifying the following properties - sep: (optional) a seperator to insert between each Stream element - start: (optional) a start string to prepend at the start - end: (optional) an end string to append at the end - valueToString: (default: String) a function converting a Stream element to a string - ifEmpty: (optional) a string to return instead of the start and end tag if the stream is empty

example

Stream.of(1, 2, 3).join({ start: '<', sep: ', ', end: '>' })
// => '<1, 2, 3>'

note

O(N)

`last`

Returns the last element of the Stream, or a fallback value (default undefined) if the Stream is empty.

Definitions

last(): T | undefined;

last<O>(otherwise: OptLazy<O>): T | O;

example

Stream.of(1, 2, 3).last()      // => 3
Stream.empty<number>().last()  // => undefined
Stream.empty<number>().last(0) // => 0

note

O(N) for most types of Stream

`map`

Returns a Stream where mapFun is applied to each element.

Definition

map<T2>(mapFun: (value: T, index: number) => T2): Stream<T2>;

Type parameters

Name	Description
T2	the resulting element type

Parameters

Name	Type	Description
`mapFun`	`(value: T, index: number) => T2`	a function taking an element and its index, and returning some new element

example

Stream.of(1, 2, 3).map((v, i) => `[${i}]: ${v}`).toArray()
// => ['[0]: 1', '[1]: 2', '[2]: 3']

note

O(1)

`mapPure`

Returns a Stream where the given mapFun is applied to each value in the stream, with optionally as extra arguments the given args.

Definition

mapPure<T2, A extends readonly unknown[]>(mapFun: (value: T, ...args: A) => T2, ...args: A): Stream<T2>;

Type parameters

Name	Constraints	Description
T2		the result value type
A	`readonly unknown[]`	the type of arguments to be supplied to the mapFun after each element

Parameters

Name	Type	Description
`mapFun`	`(value: T, ...args: A) => T2`	a function taking an element and the given args, and returning the resulting stream value
`args`	`A`	(optional) the extra arguments to pass to the given `mapFun`

note

is mostly aimed to increase performance so that an extra function is not required @note can be used on function that really expect 1 argument, since the normal map will also pass more arguments

example

const s = Stream.of({ a: 1 }, { a: 2, c: { d: true } })
const s2 = s.mapPure(JSON.stringify, ['a'], 5)
// when stream is evaluated, will call JSON.stringify on each stream element with the given extra arguments
console.log(s2.toArray())
// => ["{\n \"a\": 1\n}", "{\n \"a\": 2\n}"]

`max`

Returns the maximum element of the Stream according to a default compare function, or the provided otherwise fallback value if the Stream is empty.

Definitions

max(): T | undefined;

max<O>(otherwise: OptLazy<O>): T | O;

example

Stream.of(5, 1, 3).max()         // => 1
Stream.empty<number>().max()     // => undefined
Stream.empty<number>().max('a')  // => 'a'

note

O(N)

`maxBy`

Returns the maximum element of the Stream according to the provided compare function, or the provided `otherwise fallback value if the Stream is empty.

Definitions

maxBy(compare: (v1: T, v2: T) => number): T | undefined;

maxBy<O>(compare: (v1: T, v2: T) => number, otherwise: OptLazy<O>): T | O;

Parameters

Name	Type	Description
`compare`	`(v1: T, v2: T) => number`

example

function compareLength(a: string, b: string): number { return b.length - a.length };
Stream.of('abc', 'a', 'ab').maxBy(compareLength)   // => 'abc'
Stream.empty<string>().maxBy(compareLength)        // => undefined
Stream.empty<string>().maxBy(compareLength, 'a')   // => 'a'

note

O(N)

`min`

Returns the mimimum element of the Stream according to a default compare function, or the provided otherwise fallback value if the Stream is empty.

Definitions

min(): T | undefined;

min<O>(otherwise: OptLazy<O>): T | O;

example

Stream.of(5, 1, 3).min()         // => 1
Stream.empty<number>().min()     // => undefined
Stream.empty<number>().min('a')  // => 'a'

note

O(N)

`minBy`

Returns the mimimum element of the Stream according to the provided compare function, or the provided otherwise fallback value if the Stream is empty.

Definitions

minBy(compare: (v1: T, v2: T) => number): T | undefined;

minBy<O>(compare: (v1: T, v2: T) => number, otherwise: OptLazy<O>): T | O;

Parameters

Name	Type	Description
`compare`	`(v1: T, v2: T) => number`

example

function compareLength(a: string, b: string): number { return b.length - a.length };
Stream.of('abc', 'a', 'ab').minBy(compareLength)   // => 'a'
Stream.empty<string>().minBy(compareLength)        // => undefined
Stream.empty<string>().minBy(compareLength, 'a')   // => 'a'

note

O(N)

`mkGroup`

Returns a Stream starting with options.sep, then returning the elements of this Stream interspersed with options.sep, and ending with options.end.

Definition

mkGroup(options: {
    sep?: StreamSource<T>;
    start?: StreamSource<T>;
    end?: StreamSource<T>;
  }): Stream<T>;

Parameters

Name	Type	Description
`options`	`{` `sep?:` `StreamSource<T>;` `start?:` `StreamSource<T>;` `end?:` `StreamSource<T>;` `}`	object specifying the following properties - sep: (optional) a seperator StreamSource to insert between each Stream element - start: (optional) a start StreamSource to prepend - end: (optional) an end StreamSource to append

example

Stream.of(1, 2, 3).mkGroup({ start: '<<', sep: '-', end: '>>' }).toArray()
// => ['<', '<', 1, '-', 2, '-', 3, '>', '>']

note

O(N)

`prepend`

Returns the current stream preceded by the given value

Definition

prepend(value: OptLazy<T>): Stream.NonEmpty<T>;

Parameters

Name	Type	Description
`value`	`OptLazy<T>`	the value to prepend

example

Stream.of(1, 2, 3).prepend(0).toArray()
// => [0, 1, 2, 3]

note

O(1)

`reduce`

Applies the given reducer to each element in the Stream, and returns the final result.

Definition

reduce<R>(reducer: Reducer<T, R>): R;

Type parameters

Name	Description
R	the result type

Parameters

Name	Type	Description
`reducer`	`Reducer<T, R>`	the `Reducer` instance to use to apply to all Stream elements.

example

console.log(Stream.of(1, 2, 4).reduce(Reducer.sum))
// => 7
console.log(Stream.of(1, 2, 4).reduce(Reducer.product))
// => 8

`reduceAll`

Returns a tuple where each tuple element corresponds to result of applying all Stream elements to the corresponding Reducer instance of the given reducers.

Definition

reduceAll<R extends [unknown, unknown, ...unknown[]]>(...reducers: {
    [K in keyof R]: Reducer<T, R[K]>;
  }): R;

Type parameters

Name	Constraints	Description
R	`[unknown, unknown, ...unknown[]]`	the resulting tuple type

Parameters

Name	Type	Description
`reducers`	`{` `[K in keyof R]:` `Reducer<T, R[K]>;` `}`	a non-empty array of `Reducer` instances to use to apply to all Stream elements.

note

all reducers are processed in parallel, thus only one traversal is needed

example

console.log(Stream.of(1, 2, 4).reduceAll(Reducer.sum, Reducer.product))
// => [7, 8]

`reduceAllStream`

Returns a Stream of tuples where each tuple element corresponds to result of applying all Stream elements to the corresponding Reducer instance of the given reducers. Returns one element per input Stream element.

Definition

reduceAllStream<R extends [unknown, unknown, ...unknown[]]>(...reducers: {
    [K in keyof R]: Reducer<T, R[K]>;
  }): Stream<R>;

Type parameters

Name	Constraints	Description
R	`[unknown, unknown, ...unknown[]]`	the resulting tuple type

Parameters

Name	Type	Description
`reducers`	`{` `[K in keyof R]:` `Reducer<T, R[K]>;` `}`	a non-empty array of `Reducer` instances to use to apply to all Stream elements.

note

all reducers are processed in parallel, thus only one traversal is needed

example

console.log(
Stream.of(1, 2, 4)
.reduceAllStream(Reducer.sum, Reducer.product)
.toArray()
)
// => [[1, 1], [3, 2], [7, 8]]

`reduceStream`

Returns a Stream where the given reducer is applied to each element in the Stream.

Definition

reduceStream<R>(reducer: Reducer<T, R>): Stream<R>;

Type parameters

Name	Description
R	the resulting element type

Parameters

Name	Type	Description
`reducer`	`Reducer<T, R>`	the `Reducer` instance to use to apply to all Stream elements.

example

console.log(
Stream.of(1, 2, 4)
.reduceStream(Reducer.sum)
.toArray()
)
// => [1, 3, 7]
console.log(
Stream.of(1, 2, 4)
.reduce(Reducer.product)
.toArray()
)
// => [1, 2, 8]

`repeat`

Returns a Stream that returns the elements from this Stream given amount of times.

Definition

repeat(amount?: number): Stream<T>;

Parameters

Name	Type	Description
`amount`	`number`	(default: undefined) the amount of times to return this Stream

example

Stream.of(1, 2, 3).repeat()              // => Stream(1, 2, 3, 1, 2, 3, 1, 2, ...)
Stream.of(1, 2, 3).repeat(1).toArray()   // => [1, 2, 3]
Stream.of(1, 2, 3).repeat(3).toArray()   // => [1, 2, 3, 1, 2, 3, 1, 2, 3]
Stream.of(1, 2, 3).repeat(-3).toArray()  // => [1, 2, 3]

note

amount = undefined means that the Stream is repeated indefintely @note amount = 1 means that the Stream is not repeated @note amount < 1 will be normalized to amount = 1 @note O(1)

`single`

Returns the first element of the Stream if it only has one element, or a fallback value if the Stream does not have exactly one value.

Definitions

single(): T | undefined;

single<O>(otherwise: OptLazy<O>): T | O;

example

Stream.empty<number>().single()  // => undefined
Stream.of(1, 2, 3).single()      // => undefined
Stream.of(1).single()            // => 1
Stream.of(1, 2, 3).single(0)     // => 0

`some`

Returns true if any element of the Stream satifies given pred function.

Definition

some(pred: (value: T, index: number) => boolean): boolean;

Parameters

Name	Type	Description
`pred`	`(value: T, index: number) => boolean`	a predicate function taking an element and its index

example

Stream.of(1, 2, 3).some((v, i) => v + i > 10) // => false
Stream.of(1, 2, 3).some((v, i) => v + i > 1)  // => true

note

O(N)

`splitOn`

Returns a Stream of arrays of Stream elements, where each array is filled with elements of this Stream up to the next element that equals given sepElem according to the given eq function.

Definition

splitOn(sepElem: T, eq?: Eq<T>): Stream<T[]>;

Parameters

Name	Type	Description
`sepElem`	`T`	the separator element to look for
`eq`	`Eq<T>`	(optional) the equality function to use

example

Stream.from('marmot').splitOn('m').toArray()  // => [[], ['a', 'r'], ['o', 't']]

note

O(1)

`splitWhere`

Returns a Stream of arrays of Stream elements, where each array is filled with elements of this Stream up to the next element that satisfies give function pred.

Definition

splitWhere(pred: (value: T, index: number) => boolean): Stream<T[]>;

Parameters

Name	Type	Description
`pred`	`(value: T, index: number) => boolean`	a predicate function taking an element and its index

example

Stream.of(1, 2, 3, 4).splitWhere(v => v == 3).toArray()  // => [[1, 2], [4]]

note

O(1)

`stream`

Returns a stream of elements of type T.

Definition

stream(): this;

example

Stream.of(1, 2, 3).stream()
// => returns itself

Overrides

Streamable.stream

`take`

Returns a stream that contains the elements of this Stream up to a maximum of amount elements.

Definition

take(amount: number): Stream<T>;

Parameters

Name	Type	Description
`amount`	`number`	the maximum amount of elements to return from the resulting Stream

example

Stream.of(1, 2, 3).take(2).toArray()   // => [1, 2]

note

O(N) for most types of Stream

`takeWhile`

Returns a Stream that contains the elements of this Stream up to the first element that does not satisfy given pred function.

Definition

takeWhile(pred: (value: T, index: number) => boolean): Stream<T>;

Parameters

Name	Type	Description
`pred`	`(value: T, index: number) => boolean`	a predicate function taking an element and its index

example

Stream.of(1, 2, 3).takeWhile(v => v < 3).toArray()
// => [1, 2]

note

O(N)

`toArray`

Returns an Array containing all elements in the Stream.

Definition

toArray(): T[];

example

Stream.of(1, 2, 3).toArray()   // => [1, 2, 3]

`toJSON`

Returns a JSON representation of the Stream.

Definition

toJSON(): ToJSON<T[], 'Stream'>;

note

take care not to call on infinite Streams

example

Stream.of(1, 2, 3).toJSON()   // => { dataType: 'Stream', value: [1, 2, 3] }

`toString`

Returns a string representation of the Stream.

Definition

toString(): string;

note

to avoid issues with potentially infinite stream, this method does not list the Stream elements. To do this, use join.

example

Stream.of(1, 2, 3).toString()   // => 'Stream(...<potentially empty>)'

`transform`

Returns a Stream consisting of the concatenation of StreamSource elements resulting from applying the given reducer to each element.

Definition

transform<R>(transformer: Transformer<T, R>): Stream<R>;

Type parameters

Name	Description
R	the resulting element type

Parameters

Name	Type	Description
`transformer`	`Transformer<T, R>`	a reducer taking elements ot type T as input, and returing a `StreamSource` of element type R

note

O(1)

example

Stream.of(1, 2, 3, 4, 5, 6)
.transform(Transformer.window(3))
.toArray()
// => [[1, 2, 3], [4, 5, 6]]

`window`

Returns a Stream containing windows of windowSize consecutive elements of the source stream, with each window starting skipAmount elements after the previous one.

Definitions

window(windowSize: number, skipAmount?: number): Stream<T[]>;

window<R>(windowSize: number, skipAmount?: number, collector?: Reducer<T, R>): Stream<R>;

Parameters

Name	Type	Description
`windowSize`	`number`	the size in elements of the windows
`skipAmount`	`number`	(default: windowsize) the amount of elements to skip to start the next window

example

console.log(Stream.of(1, 2, 3, 4, 5, 6, 7).window(3).toArray())
// => [[1, 2, 3], [4, 5, 6]]
console.log(Stream.of(1, 2, 3, 4, 5).window(3, 1).toArray())
// => [[1, 2, 3], [2, 3, 4], [3, 4, 5]]
console.log(Stream.of(1, 2, 3, 4).window(2, 2, Reducer.toJSSet()).toArray())
// => [Set(1, 2), Set(3, 4)]

interface Stream<T>

Type parameters​

Methods​

[Symbol.iterator]​

Definition​

Overrides​

append​

Definition​

Parameters​

assumeNonEmpty​

Definition​

collect​

Definition​

Type parameters​

Parameters​

concat​

Definitions​

Type parameters​

Parameters​

contains​

Definition​

Parameters​

containsSlice​

Definition​

Parameters​

count​

Definition​

countElement​

Definition​

Parameters​

countNotElement​

Definition​

Parameters​

distinctPrevious​

Definition​

Parameters​

drop​

Definition​

Parameters​

dropWhile​

Definition​

Parameters​

elementAt​

Definitions​

Parameters​

equals​

Definition​

Parameters​

every​

Definition​

Parameters​

filter​

Definition​

Parameters​

filterNot​

Definition​

Parameters​

filterNotPure​

Definition​

Type parameters​

Parameters​

filterPure​

Definition​

Type parameters​

Parameters​

find​

Definitions​

Parameters​

first​

Definitions​

flatMap​

Definition​

Type parameters​

Parameters​

flatZip​

Definition​

Type parameters​

Parameters​

fold​

Definition​

`interface Stream<T>`

Type parameters

Methods

`[Symbol.iterator]`

Definition

Overrides

`append`

Definition

Parameters

`assumeNonEmpty`

Definition

`collect`

Definition

Type parameters

Parameters

`concat`

Definitions

Type parameters

Parameters

`contains`

Definition

Parameters

`containsSlice`

Definition

Parameters

`count`

Definition

`countElement`

Definition

Parameters

`countNotElement`

Definition

Parameters

`distinctPrevious`

Definition

Parameters

`drop`

Definition

Parameters

`dropWhile`

Definition

Parameters

`elementAt`

Definitions

Parameters

`equals`

Definition

Parameters

`every`

Definition

Parameters

`filter`

Definition

Parameters

`filterNot`

Definition

Parameters

`filterNotPure`

Definition

Type parameters

Parameters

`filterPure`

Definition

Type parameters

Parameters

`find`

Definitions

Parameters

`first`

Definitions

`flatMap`

Definition

Type parameters

Parameters

`flatZip`

Definition

Type parameters

Parameters

`fold`

Definition