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

Name	Description
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

Name	Description
T	the element type

Parameters

Name	Type	Description
value	T	the 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

Name	Constraints	Description
T	readonly unknown[]	the Stream element type, should be a tuple
A	readonly unknown[]	the optional arguments type

Parameters

Name	Type	Description
source	StreamSource<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
args	A	: 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

Name	Constraints	Description
T	readonly unknown[]	the Stream element type, should be a tuple
A	readonly unknown[]	the optional arguments type

Parameters

Name	Type	Description
source	StreamSource<Readonly<T>>	a Stream of tuples
f	(...args: [...T, ...A]) => void	the function to perform, receiving each Stream tuple element, and optionally receiving given extra args.
args	A	(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

Name	Constraints	Description
T	readonly unknown[]	the Stream element type, should be a tuple
A	readonly unknown[]	the optional arguments type
R		the result Stream element type

Parameters

Name	Type	Description
source	StreamSource.NonEmpty<Readonly<T>>	a Stream of tuples
mapFun	(...args: [...T, ...A]) => R	a function receiving the tuple elements as arguments, and optionally receiving given extra args, and returning the result Stream element.
args	A	(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

Name	Description
T	the 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

Name	Constraints	Description
T	StreamSource.NonEmpty<S>
S

Parameters

Name	Type	Description
source	StreamSource.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

Name	Description
T	the Stream element type

Parameters

Name	Type	Description
sources	ArrayNonEmpty<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

Name	Description
T	the Stream element type

Parameters

Name	Type	Description
array	ArrayNonEmpty<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

Name	Constraints	Description
K	string |number| symbol	the object key type
V		the object value type

Parameters

Name	Type	Description
obj	Record<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

Name	Constraints	Description
K	string |number| symbol	the object key type

Parameters

Name	Type	Description
obj	Record<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

Name	Description
V	the object value type

Parameters

Name	Type	Description
obj	Record<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

Name	Constraints	Description
S	string	the input string type

Parameters

Name	Type	Description
source	StringNonEmpty<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

Name	Description
T	the Stream element type

Parameters

Name	Type	Description
values	ArrayNonEmpty<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

Name	Type	Description
min	number	the minimum value
max	number	the 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

Name	Type	Description
range	IndexRange	the 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

Name	Description
T

Parameters

Name	Type	Description
init	T	an initial value
next	(current: T, index: number, stop: Token) => T | Token	a 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

Name	Constraints	Description
T	readonly unknown[] & {     length: L;   }
L	number

Parameters

Name	Type	Description
source	Stream.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

Name	Constraints	Description
I	readonly [unknown, ...unknown[]]

Parameters

Name	Type	Description
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

Name	Constraints	Description
I	readonly [unknown, ...unknown[]]
O

Parameters

Name	Type	Description
fillValue	OptLazy<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

Name	Constraints	Description
I	readonly [unknown, ...unknown[]]

Parameters

Name	Type	Description
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

Name	Constraints	Description
I	readonly [unknown, ...unknown[]]

Parameters

Name	Type	Description
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