Skip to main content

namespace Stream

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

Companion interface: Stream<T>

Interfaces

NameDescription
Stream.NonEmpty<T>A non-empty and possibly infinite sequence of elements of type T. See the Stream documentation and the Stream API documentation

Static Methods

always

Returns a Stream that eternally returns the given value.

Definition

always<T>(value: T): Stream.NonEmpty<T>;

Type parameters

NameDescription
Tthe element type

Parameters

NameTypeDescription
valueTthe value to return
example
console.log(Stream.always(5).take(4).toArray())
=> [5, 5, 5, 5]

applyFilter

For a Stream of tuples in given source, returns a Stream where the result of supplying each tuple element as an argument to given mapFun function for each element of the Stream, with the optionally given args as extra arguments, is true.

Definition

applyFilter<T extends readonly unknown[], A extends readonly unknown[]>(source: StreamSource<Readonly<T>>, options: {
    pred: (...args: [...T, ...A]) => boolean;
    negate?: boolean;
  }, ...args: A): Stream<T>;

Type parameters

NameConstraintsDescription
Treadonly unknown[]the Stream element type, should be a tuple
Areadonly unknown[]the optional arguments type

Parameters

NameTypeDescription
sourceStreamSource<Readonly<T>>a Stream of tuples
options{
    pred: (...args: [...T, ...A]) => boolean;
    negate?: boolean;
  }
the options used to create the Stream, containing:
- pred: a function receiving the tuple elements as arguments, and optionally receiving given extra args, and returning true if the element should be included in the result stream.
- negate: (default: false) if true will negate the predicate
argsA: given extra arguments to supply to the predicated if needed
note

used mostly for performance since a new function is not needed to spread the tuples to arguments

example
function sumEq(a: number, b: number, total: number): boolean {
return a + b === total
}
const s = Stream.applyFilter([[1, 3], [2, 4], [3, 3]], { pred: sumEq }, 6)
console.log(s.toArray())
// => [[2, 4], [3, 3]]
note

O(N)

applyForEach

For a Stream of tuples, supplied each tuple element as an argument to given function f for each element of the Stream, with the optionally given args as extra arguments.

Definition

applyForEach<T extends readonly unknown[], A extends readonly unknown[]>(source: StreamSource<Readonly<T>>, f: (...args: [...T, ...A]) => void, ...args: A): void;

Type parameters

NameConstraintsDescription
Treadonly unknown[]the Stream element type, should be a tuple
Areadonly unknown[]the optional arguments type

Parameters

NameTypeDescription
sourceStreamSource<Readonly<T>>a Stream of tuples
f(...args: [...T, ...A]) => voidthe function to perform, receiving each Stream tuple element, and optionally receiving given extra args.
argsA(optional) a list of extra arguments to pass to given f for each element
note

used mostly for performance since a new function is not needed to spread the tuples to arguments

example
Stream.applyForEach([[1, 'a'], [2, 'b']], console.log, 'bongo')
// => logs:
// 1 a bongo
// 2 b bongo
note

O(N)

applyMap

For a Stream of tuples in given source, returns a Stream with the result of supplying each tuple element as an argument to given mapFun function for each element of the Stream, with the optionally given args as extra arguments.

Definitions

applyMap<T extends readonly unknown[], A extends readonly unknown[], R>(source: StreamSource.NonEmpty<Readonly<T>>, mapFun: (...args: [...T, ...A]) => R, ...args: A): Stream.NonEmpty<R>;

applyMap<T extends readonly unknown[], A extends readonly unknown[], R>(source: StreamSource<Readonly<T>>, mapFun: (...args: [...T, ...A]) => R, ...args: A): Stream<R>;

Type parameters

NameConstraintsDescription
Treadonly unknown[]the Stream element type, should be a tuple
Areadonly unknown[]the optional arguments type
Rthe result Stream element type

Parameters

NameTypeDescription
sourceStreamSource.NonEmpty<Readonly<T>>a Stream of tuples
mapFun(...args: [...T, ...A]) => Ra function receiving the tuple elements as arguments, and optionally receiving given extra args, and returning the result Stream element.
argsA(optional) extra arguments to pass to given mapFun for each element
note

used mostly for performance since a new function is not needed to spread the tuples to arguments

example
const s = Stream.applyMap([[1, 'a'], [2, 'b']], List.of, true)
console.log(s.toArray())
// => [List(1, 'a', true), List(2, 'b', true)]
note

O(N)

empty

Returns an empty Stream of given type T.

Definition

empty<T>(): Stream<T>;

Type parameters

NameDescription
Tthe Stream element type
example
Stream.empty<number>().toArray()   // => []

flatten

Returns a Stream concatenating the given source StreamSource containing StreamSources.

Definitions

flatten<T extends StreamSource.NonEmpty<S>, S>(source: StreamSource.NonEmpty<T>): Stream.NonEmpty<S>;

flatten<T extends StreamSource<S>, S>(source: StreamSource<T>): Stream<S>;

Type parameters

NameConstraintsDescription
TStreamSource.NonEmpty<S>
S

Parameters

NameTypeDescription
sourceStreamSource.NonEmpty<T>
example
Stream.flatten(Stream.of([[1, 2], [3], [], [4]])).toArray()  // => [1, 2, 3, 4]
Stream.flatten(Stream.of(['ma', 'r', '', 'mot')).toArray() // => ['m', 'a', 'r', 'm', 'o', 't']

from

Returns a Stream containing the values in the given sources concatenated

Definitions

from<T>(...sources: ArrayNonEmpty<StreamSource.NonEmpty<T>>): Stream.NonEmpty<T>;

from<T>(...sources: ArrayNonEmpty<StreamSource<T>>): Stream<T>;

Type parameters

NameDescription
Tthe Stream element type

Parameters

NameTypeDescription
sourcesArrayNonEmpty<StreamSource.NonEmpty<T>>a non-empty array of StreamSource instances containing values
example
Stream.from([1, 2, 3]).toArray()          // => [1, 2, 3]
Stream.from('marmot').toArray() // => ['m', 'a', 'r', 'm', 'o', 't']
Stream.from([1, 2, 3], [4, 5]).toArray() // => [1, 2, 3, 4, 5]

fromArray

Returns a Stream returning elements from the given array, taking into account the given options.

Definitions

fromArray<T>(array: ArrayNonEmpty<T>, options?: {
    range?: undefined;
    reversed?: boolean;
  }): Stream.NonEmpty<T>;

fromArray<T>(array: readonly T[], options?: {
    range?: IndexRange | undefined;
    reversed?: boolean;
  }): Stream<T>;

Type parameters

NameDescription
Tthe Stream element type

Parameters

NameTypeDescription
arrayArrayNonEmpty<T>the source of the values for the Stream
options{
    range?: undefined;
    reversed?: boolean;
  }
(optional) the options used to create the Stream, containing:
- range: (optional) a sub index range of the array
- reversed: (default: false) if true reverses the order of the Stream
example
Stream.fromArray([1, 2, 3]).toArray()                                            // => [1, 2, 3]
Stream.fromArray([1, 2, 3], { range: { start: -2 } }).toArray() // => [1, 2]
Stream.fromArray([1, 2, 3], { range: { start: 1 }, reversed: true }).toArray() // => [3, 2]

fromObject

Returns a Stream consisting of the object entries as tuples from the given obj object.

Definition

fromObject<K extends string |number|symbol, V>(obj: Record<K, V>):Stream<[K, V]>;

Type parameters

NameConstraintsDescription
Kstring |number| symbolthe object key type
Vthe object value type

Parameters

NameTypeDescription
objRecord<K, V>the source object
example
Stream.fromObject({ a: 1, b: 'b' }).toArray()   // => [['a', 1], ['b', 'b']]

fromObjectKeys

Returns a Stream consisting of the object keys from the given obj object.

Definition

fromObjectKeys<K extends string |number|symbol>(obj: Record<K, any>):Stream<K>;

Type parameters

NameConstraintsDescription
Kstring |number| symbolthe object key type

Parameters

NameTypeDescription
objRecord<K, any>the source object
example
Stream.fromObjectKeys({ a: 1, b: 'b' }).toArray()  // => ['a', 'b']

fromObjectValues

Returns a Stream consisting of the object values from the given obj object.

Definition

fromObjectValues<V>(obj: Record<any, V> |readonly V[]):Stream<V>;

Type parameters

NameDescription
Vthe object value type

Parameters

NameTypeDescription
objRecord<any, V> | readonly V[]the source object
example
Stream.fromObjectValues({ a: 1, b: 'b' }).toArray()  // => [1, 'b']

fromString

Returns a Stream consisting of the characters from given string source, taking into account the given options.

Definitions

fromString<S extends string>(source: StringNonEmpty<S>, options?: {
    range?: undefined;
    reversed?: boolean;
  }): Stream.NonEmpty<string>;

fromString(source: string, options?: {
    range?: IndexRange;
    reversed?: boolean;
  }): Stream<string>;

Type parameters

NameConstraintsDescription
Sstringthe input string type

Parameters

NameTypeDescription
sourceStringNonEmpty<S>the source string
options{
    range?: undefined;
    reversed?: boolean;
  }
(optional) the options used to create the Stream, containing:
- range: (optional) a sub index range of the string
- reversed: (default: false) if true reverses the order of the Stream
example
Stream.fromString('marmot').toArray()                       // => ['m', 'a', 'r', 'm', 'o', 't']
Stream.fromString('marmot', { range: { start: -3 } }).toArray() // => ['m', 'o', 't']
Stream.fromString('marmot', { range: { amount: 3 }, reversed: true}).toArray() // => ['r', 'a', 'm']

of

Returns a non-empty Stream containing the given values

Definition

of<T>(...values: ArrayNonEmpty<T>): Stream.NonEmpty<T>;

Type parameters

NameDescription
Tthe Stream element type

Parameters

NameTypeDescription
valuesArrayNonEmpty<T>the values the Stream should return
example
Stream.of(1, 2, 3).toArray()   // => [1, 2, 3]

random

Returns an infinite Stream containing random numbers between 0 and 1.

Definition

random(): Stream.NonEmpty<number>;

example
Stream.random().take(3).toArray()     // => [0.3243..., 0.19524...., 0.78324...]

randomInt

Returns an infinite Stream containing random integer numbers between given min and max

Definition

randomInt(min: number, max: number): Stream.NonEmpty<number>;

Parameters

NameTypeDescription
minnumberthe minimum value
maxnumberthe maximum value
example
Stream.randomInt(0, 10).take(3).toArray()    // => [4, 9, 3]

range

Returns a Stream of numbers within the given range, increasing or decreasing with optionally given delta.

Definition

range(range: IndexRange, options?: {
    delta?: number;
  }): Stream<number>;

Parameters

NameTypeDescription
rangeIndexRangethe range of numbers the Stream can contain
options{
    delta?: number;
  }
the options used to create the Stream, containing:
- delta: (default: 1) the difference between a number and the next returned number
example
Stream.range({ amount: 3 }).toArray()              // => [0, 1, 2]
Stream.range({ start: 2, amount: 3 }).toArray() // => [2, 3, 4]
Stream.range({ start: 5 }, { delta: 2 }).toArray() // => [5, 7, 9, .... ]

unfold

Returns a possibly infinite Stream starting with given init value, followed by applying given next function to the previous value.

Definition

unfold<T>(init: T, next: (current: T, index: number, stop: Token) => T |Token):Stream.NonEmpty<T>;

Type parameters

NameDescription
T

Parameters

NameTypeDescription
initTan initial value
next(current: T, index: number, stop: Token) => T | Tokena function taking the last value, its index, and a stop token, and returning a new value or a stop token
example
Stream.unfold(2, v => v * v).take(4).toArray()   // => [2, 4, 16, 256]

unzip

Returns an array containing a Stream for each tuple element in this stream.

Definitions

unzip<T extends readonly unknown[] & {
    length: L;
  }, L extends number>(source: Stream.NonEmpty<T>, options: {
    length: L;
  }): {
    [K in keyof T]: Stream.NonEmpty<T[K]>;
  };

unzip<T extends readonly unknown[] & {
    length: L;
  }, L extends number>(source: Stream<T>, options: {
    length: L;
  }): {
    [K in keyof T]: Stream<T[K]>;
  };

Type parameters

NameConstraintsDescription
Treadonly unknown[] & {
    length: L;
  }
Lnumber

Parameters

NameTypeDescription
sourceStream.NonEmpty<T>
options{
    length: L;
  }
the options used to create the result, containing:
- length: the stream element tuple length
example
const [a, b] = Stream.unzip(Stream.of([[1, 'a'], [2, 'b']]), 2)
a.toArray() // => [1, 2]
b.toArray() // => ['a', 'b']

zip

Returns a Stream with tuples containing each successive value from the given sources.

Definitions

zip<I extends readonly [unknown, ...unknown[]]>(...sources: {
    [K in keyof I]: StreamSource.NonEmpty<I[K]>;
  } & unknown[]): Stream.NonEmpty<I>;

zip<I extends readonly [unknown, ...unknown[]]>(...sources: {
    [K in keyof I]: StreamSource<I[K]>;
  } & unknown[]): Stream<I>;

Type parameters

NameConstraintsDescription
Ireadonly [unknown, ...unknown[]]

Parameters

NameTypeDescription
sources{
    [K in keyof I]: StreamSource.NonEmpty<I[K]>;
  } & unknown[]
the input stream sources
example
Stream.zip([1, 2, 3], [4, 5], ['a', 'b', 'c']).toArray()    // => [[1, 4, 'a'], [2, 5, 'b']]
note

ends the Stream when any of the given streams ends

zipAll

Returns a Stream with tuples containing each successive value from the given sources, adding given fillValue to any Streams that end before all streams have ended.

Definitions

zipAll<I extends readonly [unknown, ...unknown[]], O>(fillValue: OptLazy<O>, ...sources: {
    [K in keyof I]: StreamSource.NonEmpty<I[K]>;
  } & unknown[]): Stream.NonEmpty<{
    [K in keyof I]: I[K] | O;
  }>;

zipAll<I extends readonly [unknown, ...unknown[]], O>(fillValue: OptLazy<O>, ...sources: {
    [K in keyof I]: StreamSource<I[K]>;
  } & unknown[]): Stream<{
    [K in keyof I]: I[K] | O;
  }>;

Type parameters

NameConstraintsDescription
Ireadonly [unknown, ...unknown[]]
O

Parameters

NameTypeDescription
fillValueOptLazy<O>the value to add to streams that end early
sources{
    [K in keyof I]: StreamSource.NonEmpty<I[K]>;
  } & unknown[]
the input stream sources
example
Stream.zipAll(
0,
[1, 2, 3],
[4, 5],
['a', 'b', 'c']
).toArray()
// => [[1, 4, 'a'], [2, 5, 'b'], [3, 0, 'c']]

zipAllWith

Returns a Stream with the result of applying given zipFun to each successive value resulting from the given sources, adding given fillValue to any Streams that end before all streams have ended.

Definitions

zipAllWith<I extends readonly [unknown, ...unknown[]]>(...sources: {
    [K in keyof I]: StreamSource.NonEmpty<I[K]>;
  } & unknown[]): <O, R>(fillValue: OptLazy<O>, zipFun: (...values: {
    [K in keyof I]: I[K] | O;
  }) => R) => Stream.NonEmpty<R>;

zipAllWith<I extends readonly [unknown, ...unknown[]]>(...sources: {
    [K in keyof I]: StreamSource<I[K]>;
  } & unknown[]): <O, R>(fillValue: OptLazy<O>, zipFun: (...values: {
    [K in keyof I]: I[K] | O;
  }) => R) => Stream<R>;

Type parameters

NameConstraintsDescription
Ireadonly [unknown, ...unknown[]]

Parameters

NameTypeDescription
sources{
    [K in keyof I]: StreamSource.NonEmpty<I[K]>;
  } & unknown[]
the input stream sources
example
Stream.zipAllWith(
[1, 2],
[3, 4, 5],
[6, 7]
)(
0,
(a, b, c) => a + b + c,
).toArray()
// => [10, 13, 5]

zipWith

Returns a Stream with the result of applying given zipFun to each successive value resulting from the given sources.

Definitions

zipWith<I extends readonly [unknown, ...unknown[]]>(...sources: {
    [K in keyof I]: StreamSource.NonEmpty<I[K]>;
  } & unknown[]): <R>(zipFun: (...values: I) => R) => Stream.NonEmpty<R>;

zipWith<I extends readonly [unknown, ...unknown[]]>(...sources: {
    [K in keyof I]: StreamSource<I[K]>;
  } & unknown[]): <R>(zipFun: (...values: I) => R) => Stream<R>;

Type parameters

NameConstraintsDescription
Ireadonly [unknown, ...unknown[]]

Parameters

NameTypeDescription
sources{
    [K in keyof I]: StreamSource.NonEmpty<I[K]>;
  } & unknown[]
the input stream sources
example
Stream.zipWith(
[1, 2],
[3, 4, 5],
[true, false]
)(
(a, b, c) => c ? a + b : a - b
).toArray()
// => [4, -2]
note

ends the Stream when any of the given streams ends