LazyStream.TS

Inspired by Java 8 Streams and .NET LINQ, this small library provides an easy way to work with collections in FP-like and SQL-like styles.

Class: Stream <T>

Stream class that wraps Iterable<T> and provides most of the common FP-style operations like map, filter, flatMap etc. as well as SQL-style select, where, join etc. Stream does also implement Iterable<T> so it can wrap other stream, and since most of the operations return Stream<T>, the calls can be easily chained with each other, for example:

const numbers: Array<number> = ...
const evenSquares = new Stream(numbers)
   .filter(v => v % 2 == 0)
   .map(v => v * v)
   .toArray();

Types can be primitives (as in the example above) but can also be Objects, so SQL-like instructions can be used:

const users: Array<{name: string, age: number, city: string}> = ...
const usersByCity = new Stream(users)
  .where("age", ">=", 25)
  .groupBy("city")
  .toArray();

Type parameters

▪ T

Type of elements in the stream. Can be any type including Object, primitives, Iterable etc.

Summary of operations

FP-style

• filter
• map
• reduce
• flat
• flatMap

SQL-style

• groupBy
• join
• select
• where

Collectors

• forEach
• toArray
• toMap

Shortcuts

• last
• max
• min

Constructors

constructor

+ new Stream(iterableOrIteratorFactory: Iterable‹T› | function): Stream

Defined in index.ts:149

Creates a new instance of Stream by wrapping existing Iterable<T> or just a function that returns Iterator<T> (so generator function can be passed as well). For example:

// from Iterable<T>
const fromIterable = new Stream([1,2,3,4]);

// from () => Iterator<T>
function* generator() {
  yield 1;
  yield 2;
  yield 3;
}
const fromGenerator = new Stream(generator);

Parameters:

Name | Type | Description | ------ | ------ | ------ | iterableOrIteratorFactory | Iterable‹T› | function | instance of Iterable<T> or () => Iterator<T> |

Returns: Stream

Methods

[Symbol.iterator]

▸ [Symbol.iterator](): Iterator‹T›

Defined in index.ts:179

Returns: Iterator‹T›

filter

▸ filter(predicate: function): Stream‹T›

Defined in index.ts:210

Filters elements given a predicate function. Example of usage:

const evens = new Stream([1, 2, 3])
  .filter(i => i % 2 == 0)
  .toArray();

expect(even).toStrictEqual([2]);

Parameters:

▪ predicate: function

function that accepts element and return true or false

▸ (t: T): boolean

Parameters:

Name | Type | ------ | ------ | t | T |

Returns: Stream‹T›

flat

▸ flat(this: Stream‹Iterable‹any››): Stream‹T extends Iterable ? E : never›

Defined in index.ts:238

Flattens elements of this Stream<Iterable<T>> into Stream<T>. Example of usage:

const flattened = new Stream([[1,3], [2,4]])
   .flat()
   .toArray();

expect(flattened).toStrictEqual([1, 3, 2, 4]);

Parameters:

Name | Type | ------ | ------ | this | Stream‹Iterable‹any›› |

Returns: Stream‹T extends Iterable ? E : never›

flatMap

▸ flatMap<K>(field: K): Stream‹Val<T, K> extends Iterable ? E : never›

Defined in index.ts:259

First maps elements of Stream<T> to Stream<Iterable<R>> and then flattens into Stream<R>. For example:

const flattened = new Stream([{numbers: [1, 3]}, {numbers: [2, 4]}])
  .flatMap("numbers") 
  .toArray();
// "numbers" - name of a field that contains Iterable

expect(flattened).toStrictEqual([1, 3, 2, 4]);

Type parameters:

▪ K: FieldOrFn‹T›

Parameters:

Name | Type | Description | ------ | ------ | ------ | field | K | field extractor see FieldOrFn<T> |

Returns: Stream‹Val<T, K> extends Iterable ? E : never›

forEach

▸ forEach(fn: Fn‹T›): void

Defined in index.ts:562

Fetches all elements from the stream and executes given function for each element. Example of usage:

var sum = 0;
new Stream([1, 2, 3])
  .forEach(v => sum += v);

expect(sum).toStrictEqual(6);

Parameters:

Name | Type | Description | ------ | ------ | ------ | fn | Fn‹T› | function to invoke |

Returns: void

groupBy

▸ groupBy<K>(keyFieldOrFn?: K): Stream‹object›

Defined in index.ts:516

Mimics SQL GROUP BY operator. Groups elements with the same given key. Keys must be in a sorted order, otherwise will raise an exception. Next element is emitted only once the element with the next key appears in the stream. Example of usage:

const ungrouped = [{a: 1, b: "val 1"}, {a: 1, b: "val 2"}, 
                   {a: 2, b: "val 3"}, {a: 2, b: "val 4"}];
const grouped = new Stream(ungrouped)
  .groupBy("a")
  .toArray();

expect(grouped).toStrictEqual([
  {key: 1, values: [{a: 1, b: "val 1"}, {a: 1, b: "val 2"}]},
  {key: 2, values: [{a: 2, b: "val 3"}, {a: 2, b: "val 4"}]}
]);

Type parameters:

▪ K: FieldOrFn‹T›

Parameters:

Name | Type | Description | ------ | ------ | ------ | keyFieldOrFn? | K | |

Returns: Stream‹object›

join

▸ join<O, KC, KL, KR, JT>(other: Iterable‹O›, params: object): Stream‹JoinEntry‹T, O, JT››

Defined in index.ts:369

Mimics SQL JOIN operator. Depending on type of join, for each element of source stream lookups a corresponding element from joined stream, using join parameter that can either be a field, or a function.

If using SORTED join type, it will ensure that keys from both set come in the specified order, otherwise will raise an exception. This is the most intended usage of this operation as it won't need to pre-fetch all elements from second stream in memory. The output keys order is preserved, i.e. if join order is ascending, then join entries will be emitted with the keys being in ascending order.

If using UNSORTED join type, it will pre-fetch all elements from second stream into a hash map before any join entries can be emitted.

Keys are not required to be unique, for duplicate keys, join entries will be multiplied, like it happens in SQL:

[1,2,2] left join [2,2,3] = [{1,null}, {2,2}, {2,2}, {2,2}, {2,2}]

Example of usage:

let collectionA = [{a: 1, b: "val 1",}, {a: 2, b: "val 2",}, {a: 3, b: "val 3",}];
let collectionB = [{a: 1, b: "val a",}, {a: 2, b: "val b",}];
const joined = new Stream(collectionA)
  .join(collectionB, {joinType: JoinType.INNER_ASC, commonKey: "a"})
  .toArray();

expect(result).toStrictEqual([
  {key: 1, left: {a: 1, b: "val 1"}, right: {a: 1, b: "val a"}},
  {key: 2, left: {a: 2, b: "val 2"}, right: {a: 2, b: "val b"}}
]);

Type parameters:

▪ O - type of elements in the other stream being joined

Parameters:

▪ other: Iterable‹O› - other stream to join (right-side)

▪ params: Optional object= {joinType?, commonKey?, leftKey?, rightKey?}

Name | Type | Description | ------ | ------------ | ----------------------- | commonKey? | FieldOrFn‹T | O› | Common field that belongs to both streams elements, or a function that can extract key from T | O; if provided, next 2 will be ignored. | leftKey? | FieldOrFn‹O› | Field that belongs to current (left) stream elements, or a function that can extract key from T. If not provided, then elements will be used as keys and are supposed to be primitive. | rightKey? | JoinType | Field that belongs to other (right) stream elements, or a function that can extract key from O. If not provided, then elements will be used as keys and are supposed to be primitive. | joinType? | FieldOrFn‹T› | Join mode, default value is JoinType.INNER_ASC. |

JoinType is defining a semantic of a join operation as follows:

JoinType | Left | Right | Result | -------- | ------- | ---- | ----| INNER_ASC | [1,2] | [2,3] | [{key: 2, left: 2, right: 2}] | LEFT_ASC | [1,2] | [2,3] | [{key: 1, left: 2, right: null}, {key: 2, left: 2, right: 2}] | RIGHT_ASC | [1,2] | [2,3] | [{key: 2, left: 2, right: 2}, {key: 3, left: null, right: 3}] | FULL_ASC | [1,2] | [2,3] | [{key: 1, left: 1, right: null}, {key: 2, left: 2, right: 2}, {key: 3, left: null, right: 3}] | INNER_DESC | [2,1] | [3,2] | [{key: 2, left: 2, right: 2}] | LEFT_DESC | [2,1] | [3,2] | [{key: 2, left: 2, right: 2}, {key: 1, left: 2, right: null}] | RIGHT_DESC | [2,1] | [3,2] | [{key: 3, left: 3, right: null}, {key: 2, left: 2, right: 2}] | FULL_DESC | [2,1] | [3,2] | [{key: 3, left: 3, right: null}, {key: 2, left: 2, right: 2}, {key: 1, left: 2, right: null}] | INNER_UNSORTED | [1,3,2] | [2,1,4] | [{key: 1, left: 2, right: 1}, {key: 2, left: 2, right: 2}] LEFT_UNSORTED | [1,3,2] | [2,1,4] | [{key: 1, left: 2, right: 1}, {key: 3, left: null, right: 3}, {key: 2, left: 2, right: 2}]

Returns: Stream‹JoinEntry‹T, O, JT››

last

▸ last(): T

Defined in index.ts:638

Fetches all elements from the stream and returns the last element. Example of usage:

const result = new Stream([1, 2, 3]).last();
expect(result).toStrictEqual(3);

Returns: T

map

▸ map<R>(mapFn: function): Stream‹R›

Defined in index.ts:225

Maps each element of a current stream with a mapper function and returns new Stream of newly created elements. Example of usage:

const squares = new Stream([1, 2, 3])
  .map(i => i * i)
  .toArray();

Type parameters:

▪ R

Parameters:

▪ mapFn: function

function that accepts current element and returns a new one. The function can optionally accept prev element (original and mapped one).

▸ (t: T, prevT?: T, prevR?: R): R

Parameters:

Name | Type | ------ | ------ | t | T | prevT? | T | prevR? | R |

Returns: Stream‹R›

max

▸ max(this: Stream‹number›): number

Defined in index.ts:664

Fetches all elements from the stream and returns the maximal one. Example of usage:

const result = new Stream([1, 2, 3]).max();
expect(result).toStrictEqual(3);

Currently only supports numeric streams, proper comparator support to be added soon.

Parameters:

Name | Type | ------ | ------ | this | Stream‹number› |

Returns: number

min

▸ min(this: Stream‹number›): number

Defined in index.ts:651

Fetches all elements from the stream and returns the minimal one. Example of usage:

const result = new Stream([1, 2, 3]).min();
expect(result).toStrictEqual(1);

Currently only supports numeric streams, proper comparator support be added soon.

Parameters:

Name | Type | ------ | ------ | this | Stream‹number› |

Returns: number

reduce

▸ reduce<R>(reduceFn: function): R

Defined in index.ts:618

Fetches all elements from the stream and recursively applies reduceFn to each element providing previous result to each call. Example of usage:

const result = new Stream([1, 2, 3])
 .reduce<number>((a, b) => (a === undefined ? 0 : a) + b);

expect(result).toStrictEqual(6);

Type parameters:

▪ R

Parameters:

▪ reduceFn: function

function(accumulator: R | undefined, current: T, index: number) => R

▸ (accumulator: R | undefined, current: T, index: number): R

Parameters:

Name | Type | ------ | ------ | accumulator | R | undefined | current | T | index | number |

Returns: R

select

▸ select<U1, U2>(field1: U1, ...field2: U2[]): Stream‹[U2] extends [never] ? T[U1] : object›

Defined in index.ts:283

Mimics SQL SELECT operator, by restricting set of fields that need be returned. Accepts list of field names, and returns objects with only those fields, for example:

const selectedAB = stream([{a: 1, b: "str", c: 3}]).select("a", "b");
const selectedA = stream([{a: 1, b: "str", c: 3}]).select("a");

expect(selectedAB).toStrictEqual([{a: 1, b: "str"}]);
expect(selectedA).toStrictEqual([1]);

Type parameters:

▪ U1: Field‹T›

▪ U2: Field‹T›

Parameters:

Name | Type | Description | ------ | ------ | ------ | field1 | U1 | field name | ...field2 | U2[] | field name (none or many) |

Returns: Stream‹[U2] extends [never] ? T[U1] : object›

toArray

▸ toArray(): Array‹T›

Defined in index.ts:571

Fetches all elements from the stream and collect them int Array<T>.

Returns: Array‹T›

toMap

▸ toMap<K, V>(key: K, val?: V): Map‹Val‹T, K›, Val‹T, V››

Defined in index.ts:594

Fetches all elements from the stream and collect them int Map<K, V>. Example of usage:

const result = new Stream([1, 2, 3])
  .toMap(t => `${t}`);

expect(result).toStrictEqual(new Map([['1', 1], ['2', 2], ['3', 3]]));

Type parameters:

▪ K: FieldOrFn‹T›

▪ V: FieldOrFn‹T›

Parameters:

Name | Type | Description | ------ | ------ | ------ | key | K | key field or function | val? | V | value field or function |

Returns: Map‹Val‹T, K›, Val‹T, V››

where

▸ where<K>(field: K, compareOp: ComparisonOp, value: Val‹T, K›): Stream‹T›

Defined in index.ts:314

Mimics SQL WHERE clause, by including only the records that satisfy given parameters. Example of usages:

const objs = [{a: 1, b: "val a", c: 3}, {a: 2, b: "val b", c: 4}, 
              {a: 3, b: "val c", c: 4}];
const result = new Stream(objs)
  .where("a", "<", 3)
  .where("b", "!=", "val a")
  .toArray();

expect(result).toStrictEqual([{a: 2, b: "val b", c: 4}]);

Type parameters:

▪ K: FieldOrFn‹T›

Parameters:

Name | Type | Description | ------ | ------ | ------ | field | K | field name, see Field<T> | compareOp | ComparisonOp | comparison operation, see ComparisonOp | value | Val‹T, K› | value of type T[Field] to compare with |

Returns: Stream‹T›

Creating streams from existing collections

from

▸ from<T>(first: Iterable‹T›, second: Iterable‹T›, ...rest: Iterable‹T›[]): Stream‹T[]›

Defined in index.ts:21

Cross-multiplies multiple Iterable's of the same type T into Stream<T[]>. Can accept any number of args. This function can be used as a shortcut - from(someIterable) instead of new Stream(someIterable).

Example of usage:

const result = from([1, 3], [2, 4])
  .toArray();

expect(result).toStrictEqual([[1, 3], [1, 4], [2, 3], [2, 4]]);

Type parameters:

▪ T

Parameters:

Name | Type | Description | ------ | ------ | ------ | first | Iterable‹T› | (required) first Iterable | second | Iterable‹T› | (optional) second Iterable | ...rest | Iterable‹T›[] | (optional) other Iterables |

Returns: Stream‹T[]›

range

▸ range(from: number, to: number): Stream‹number›

Defined in index.ts:60

Creates a Stream<number> with all numbers from the range. Example of usage:

const result = range(0, 10)
  .toArray();

expect(result).toStrictEqual([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);

Parameters:

Name | Type | Description | ------ | ------ | ------ | from | number | start of range (inclusive) | to | number | end of range (inclusive) |

Returns: Stream‹number›