interface AsyncStream.NonEmpty<T>

A non-empty and possibly infinite asynchronous sequence of elements of type T. See the Stream documentation and the AsyncStream API documentation

Type parameters

Name	Description
T	the element type

example

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

Methods

asNormal

Returns this collection typed as a 'possibly empty' collection.

Definition

asNormal(): AsyncStream<T>;

example

AsyncStream.of(0, 1, 2).asNormal();  // type: AsyncStream<number>

asyncStream

Returns a non-empty async stream of elements of type T.

Definition

asyncStream(): this;

example

AsyncStream.of(1, 2, 3).asyncStream()
// => returns itself

concat

Returns a non-empty AsyncStream containing the elements of this stream followed by all elements produced by the others array of AsyncStreamSources.

Definition

concat<T2 = T>(...others: ArrayNonEmpty<AsyncStreamSource<T>>): AsyncStream.NonEmpty<T | T2>;

Type parameters

Name	Default	Description
T2	T	the result value type

Parameters

Name	Type	Description
others	ArrayNonEmpty<AsyncStreamSource<T>>	a series of AsyncStreamSources to concatenate.

example

await AsyncStream.of(1, 2, 3).concat([4, 5], () => [6, 7]).toArray()
// [1, 2, 3, 4, 5, 6, 7]

note

O(1)

distinctPrevious

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

Definition

distinctPrevious(options?: {
      eq?: Eq<T> | undefined;
      negate?: boolean | undefined;
    }): AsyncStream.NonEmpty<T>;

Parameters

Name	Type	Description
options	{       eq?: Eq<T> | undefined;       negate?: boolean | undefined;     }	(optional) object specifying the following properties - eq: (default: Eq.objectIs) the Eq instance to use to test equality of elements - negate: (default: false) when true will negate the given predicate

example

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

first

Returns the first element of the AsyncStream.

Definition

first(): Promise<T>;

example

await AsyncStream.of(1, 2, 3).first()      // => 1

note

O(1)

flatMap

Returns an AsyncStream consisting of the concatenation of flatMapFun applied to each element.

Definitions

flatMap<T2>(flatMapFun: (value: T, index: number) => AsyncStreamSource.NonEmpty<T2>): AsyncStream.NonEmpty<T2>;

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

Type parameters

Name	Description
T2	the result value type

Parameters

Name	Type	Description
flatMapFun	(value: T, index: number) => AsyncStreamSource.NonEmpty<T2>	a potentially asynchronous 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

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

flatZip

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

Definitions

flatZip<T2>(flatMapFun: (value: T, index: number) => AsyncStreamSource.NonEmpty<T2>): AsyncStream.NonEmpty<[T, T2]>;

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

Type parameters

Name	Description
T2	the result element type

Parameters

Name	Type	Description
flatMapFun	(value: T, index: number) => AsyncStreamSource.NonEmpty<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

await AsyncStream.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]]

foldStream

Returns an AsyncStream 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.

Definitions

foldStream<R>(init: AsyncOptLazy<R>, next: (current: R, value: T, index: number) => MaybePromise<R>): AsyncStream.NonEmpty<R>;

foldStream<R>(init: AsyncOptLazy<R>, next: (current: R, value: T, index: number, halt: () => void) => MaybePromise<R>): AsyncStream<R>;

Type parameters

Name	Description
R	the resulting element type

Parameters

Name	Type	Description
init	AsyncOptLazy<R>	the initial result/state value
next	(current: R, value: T, index: number) => MaybePromise<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(
await AsyncStream.empty<number>()
.foldStream(5, async (current, value) => current + value)
.toArray()
)
// => []
console.log(
await AsyncStream.of(1, 2, 3)
.foldStream(() => 5, (current, value) => current + value)
.toArray()
)
// => [6, 8, 11]

indexed

Returns a non-empty AsyncStream where each element in this stream is paired with its index

Definition

indexed(options?: {
      startIndex?: number | undefined;
    }): AsyncStream.NonEmpty<[number, T]>;

Parameters

Name	Type	Description
options	{       startIndex?: number | undefined;     }	(optional) object specifying the following properties - startIndex: (optional) an alternative start index to use

example

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

note

O(1)

intersperse

Returns a non-empty AsyncStream with all elements from the given sep AsyncStreamSource between two elements of this stream.

Definition

intersperse(sep: AsyncStreamSource<T>): AsyncStream.NonEmpty<T>;

Parameters

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

example

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

note

O(1)

last

Returns the last element of the AsyncStream.

Definition

last(): Promise<T>;

example

await AsyncStream.of(1, 2, 3).last()      // => 3

note

O(N)

map

Returns a non-empty AsyncStream where mapFun is applied to each element.

Definition

map<T2>(mapFun: (value: T, index: number) => MaybePromise<T2>): AsyncStream.NonEmpty<T2>;

Type parameters

Name	Description
T2	the result element type

Parameters

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

example

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

note

O(1)

mapPure

Returns a non-empty AsyncStream 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) => MaybePromise<T2>, ...args: A): AsyncStream.NonEmpty<T2>;

Type parameters

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

Parameters

Name	Type	Description
mapFun	(value: T, ...args: A) => MaybePromise<T2>	a potentially asynchronous 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 = AsyncStream.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(await s2.toArray())
// => ["{\n \"a\": 1\n}", "{\n \"a\": 2\n}"]

max

Returns the maximum element of the AsyncStream according to a default compare function.

Definition

max(): Promise<T>;

example

await AsyncStream.of(5, 1, 3).max()         // => 5

note

O(N)

maxBy

Returns the maximum element of the AsyncStream according to the provided compare function.

Definition

maxBy(compare: (v1: T, v2: T) => number): Promise<T>;

Parameters

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

example

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

note

O(N)

min

Returns the mimimum element of the AsyncStream according to a default compare function.

Definition

min(): Promise<T>;

example

await AsyncStream.of(5, 1, 3).min()         // => 1

note

O(N)

minBy

Returns the mimimum element of the AsyncStream according to the provided compare function.

Definition

minBy(compare: (v1: T, v2: T) => number): Promise<T>;

Parameters

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

example

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

note

O(N)

mkGroup

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

Definition

mkGroup(options: {
      sep?: AsyncStreamSource<T> | undefined;
      start?: AsyncStreamSource<T> | undefined;
      end?: AsyncStreamSource<T> | undefined;
    }): AsyncStream.NonEmpty<T>;

Parameters

Name	Type	Description
options	{       sep?: AsyncStreamSource<T> | undefined;       start?: AsyncStreamSource<T> | undefined;       end?: AsyncStreamSource<T> | undefined;     }	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

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

note

O(N)

repeat

Returns a non-empty AsyncStream that returns the elements from this stream given amount of times.

Definition

repeat(amount?: number |undefined):AsyncStream.NonEmpty<T>;

Parameters

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

example

const source = AsyncStream.of(1, 2, 3)
source.repeat()              // => AsyncStream(1, 2, 3, 1, 2, 3, 1, 2, ...)
await source.repeat(1).toArray()   // => [1, 2, 3]
await source.repeat(3).toArray()   // => [1, 2, 3, 1, 2, 3, 1, 2, 3]
await source.repeat(-3).toArray()  // => [1, 2, 3]

note

amount = undefined means that the AsyncStream 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)

toArray

Returns a non-empty Array containing all elements in the AsyncStream.

Definition

toArray(): Promise<ArrayNonEmpty<T>>;

example

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

transform

Returns an AsyncStream consisting of the concatenation of AsyncStreamSource elements resulting from applying the given reducer to each element.

Definitions

transform<R, T2 extends T = T>(transformer: AsyncTransformer.AcceptNonEmpty<T |T2, R>):AsyncStream.NonEmpty<R>;

transform<R, T2 extends T = T>(transformer: AsyncTransformer.Accept<T |T2, R>):AsyncStream<R>;

Type parameters

Name	Constraints	Default	Description
R			the resulting element type
T2	T	T

Parameters

Name	Type	Description
transformer	AsyncTransformer.AcceptNonEmpty<T | T2, R>	an async reducer taking elements ot type T as input, and returing an AsyncStreamSource of element type R.

note

O(1)

example

await AsyncStream.of(1, 2, 3, 4, 5, 6).transform(AsyncTransformer.window(3)).toArray()
// => [[1, 2, 3], [4, 5, 6]]