npm package: @osjwnpm/nesciunt-voluptatem-quo
Description: [![npm](https://img.shields.io/npm/v/@osjwnpm/nesciunt-voluptatem-quo.svg)](https://www.npmjs.com/package/@osjwnpm/nesciunt-voluptatem-quo) [![npm](https://img.shields.io/npm/dm/@osjwnpm/nesciunt-voluptatem-quo.svg?style=flat)](https://www.npmjs.com/packa
Author: OSJW
Latest version: 1.0.0

# IterTools for TypeScript and JavaScript

[![npm](https://img.shields.io/npm/v/@osjwnpm/nesciunt-voluptatem-quo.svg)](https://www.npmjs.com/package/@osjwnpm/nesciunt-voluptatem-quo)
[![npm](https://img.shields.io/npm/dm/@osjwnpm/nesciunt-voluptatem-quo.svg?style=flat)](https://www.npmjs.com/package/@osjwnpm/nesciunt-voluptatem-quo)
[![Coverage Status](https://coveralls.io/repos/github/Smoren/@osjwnpm/nesciunt-voluptatem-quo/badge.svg?branch=master&rand=123)](https://coveralls.io/github/Smoren/@osjwnpm/nesciunt-voluptatem-quo?branch=master)
![Build and test](https://github.com/osjwnpm/nesciunt-voluptatem-quo/actions/workflows/test_master.yml/badge.svg)
[![Minified Size](https://badgen.net/bundlephobia/minzip/@osjwnpm/nesciunt-voluptatem-quo)](https://bundlephobia.com/result?p=@osjwnpm/nesciunt-voluptatem-quo)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

![IterTools Logo](docs/images/itertools-logo.png)

Inspired by Python — designed for TypeScript.

Features
--------

IterTools makes you an iteration superstar by providing two types of tools:

* Loop iteration tools
* Stream iteration tools

**Loop Iteration Tools Example**

```typescript
import { multi } from '@osjwnpm/nesciunt-voluptatem-quo';

for (const [letter, number] of multi.zip(['a', 'b'], [1, 2])) {
  console.log(`${letter}${number}`);  // a1, b2
}

// Async example
const letters = ['a', 'b'].map((x) => Promise.resolve(x));
const numbers = [1, 2].map((x) => Promise.resolve(x));

for await (const [letter, number] of multi.zipAsync(letters, numbers)) {
  console.log(`${letter}${number}`);  // a1, b2
}
```

**Stream Iteration Tools Example**

```typescript
import { Stream, AsyncStream } from '@osjwnpm/nesciunt-voluptatem-quo';

const result1 = Stream.of([1, 1, 2, 2, 3, 4, 5])
  .distinct()             // [1, 2, 3, 4, 5]
  .map((x) => x**2)       // [1, 4, 9, 16, 25]
  .filter((x) => x < 10)  // [1, 4, 9]
  .toSum();               // 14

// Async example
const result2 = await AsyncStream.of([1, 1, 2, 2, 3, 4, 5].map((x) => Promise.resolve(x)))
  .distinct()             // [1, 2, 3, 4, 5]
  .map((x) => x**2)       // [1, 4, 9, 16, 25]
  .filter((x) => x < 10)  // [1, 4, 9]
  .toSum();               // 14
```

[More about Streams](#Stream-and-Async-Stream)

All functions work on iterable collections and iterators:
* `Array`
* `Set`
* `Map`
* `String`
* `Generator`
* `Iterable`
* `Iterator`

Every function have an analog with "Async"-suffixed name for working with async iterable and iterators (e.g. `zip` and `zipAsync`):
* `AsyncIterable`
* `AsyncIterator`

If an asynchronous function takes other functions as input, they can also be asynchronous.

```typescript
import { single } from '@osjwnpm/nesciunt-voluptatem-quo';

const starWarsEpisodes = [1, 2, 3, 4, 5, 6, 7, 8, 9];

for await (const goodMovie of single.filterAsync(
  starWarsEpisodes,
  async (episode) => {
    return Promise.resolve(episode > 3 && episode < 8);
  }
)) {
  console.log(goodMovie);
}
// 4, 5, 6, 7
```

Setup
-----

```bash
npm i @osjwnpm/nesciunt-voluptatem-quo
```

### Similar Libraries in Other Languages

IterTools functionality is not limited to TypeScript and Python. Other languages have similar libraries.
Familiar functionality is available when working in other languages.

* [IterTools PHP](https://github.com/markrogoyski/itertools-php)
* [IterTools Python](https://docs.python.org/3/library/itertools.html): The original!

Quick Reference
---------------

### Loop Iteration Tools

#### Multi Iteration
| Iterator                     | Description                                                                                                       | Sync Code Snippet                            | Async Code Snippet                                |
|------------------------------|-------------------------------------------------------------------------------------------------------------------|----------------------------------------------|---------------------------------------------------|
| [`chain`](#chain)            | Chain multiple iterables together                                                                                 | `multi.chain(list1, list2, ...)`             | `multi.chainAsync(list1, list2, ...)`             |
| [`zip`](#zip)                | Iterate multiple collections simultaneously until the shortest iterator completes                                 | `multi.zip(list1, list2, ...)`               | `multi.zipAsync(list1, list2, ...)`               |
| [`zipEqual`](#zip-equal)     | Iterate multiple collections of equal length simultaneously, error if lengths not equal                           | `multi.zipEqual(list1, list2, ...)`          | `multi.zipEqualAsync(list1, list2, ...)`          |
| [`zipFilled`](#zip-filled)   | Iterate multiple collections simultaneously until the longest iterator completes (with filler for uneven lengths) | `multi.zipFilled(filler, list1, list2, ...)` | `multi.zipFilledAsync(filler, list1, list2, ...)` |
| [`zipLongest`](#zip-longest) | Iterate multiple collections simultaneously until the longest iterator completes                                  | `multi.zipLongest(list1, list2, ...)`        | `multi.zipLongestAsync(list1, list2, ...)`        |

#### Single Iteration
| Iterator                                 | Description                                 | Sync Code Snippet                                       | Async Code Snippet                                           |
|------------------------------------------|---------------------------------------------|---------------------------------------------------------|--------------------------------------------------------------|
| [`chunkwise`](#chunkwise)                | Iterate by chunks                           | `single.chunkwise(data, chunkSize)`                     | `single.chunkwiseAsync(data, chunkSize)`                     |
| [`chunkwiseOverlap`](#chunkwise-overlap) | Iterate by overlapped chunks                | `single.chunkwiseOverlap(data, chunkSize, overlapSize)` | `single.chunkwiseOverlapAsync(data, chunkSize, overlapSize)` |
| [`compress`](#compress)                  | Filter out elements not selected            | `single.compress(data, selectors)`                      | `single.compressAsync(data, selectors)`                      |
| [`dropWhile`](#drop-while)               | Drop elements while predicate is true       | `single.dropWhile(data, predicate)`                     | `single.dropWhileAsync(data, predicate)`                     |
| [`enumerate`](#enumerate)                | Enumerates elements of collection           | `single.enumerate(data)`                                | `single.enumerateAsync(data)`                                |
| [`filter`](#filter)                      | Filter for elements where predicate is true | `single.filter(data, predicate)`                        | `single.filterAsync(data, predicate)`                        |
| [`flatMap`](#flat-map)                   | Map function onto items and flatten result  | `single.flatMap(data, mapper)`                          | `single.flatMapAsync(data, mapper)`                          |
| [`flatten`](#flatten)                    | Flatten multidimensional iterable           | `single.flatten(data, [dimensions])`                    | `single.flattenAsync(data, [dimensions])`                    |
| [`groupBy`](#group-by)                   | Group data by a common element              | `single.groupBy(data, groupKeyFunction, [itemKeyFunc])` | `single.groupByAsync(data, groupKeyFunction, [itemKeyFunc])` |
| [`limit`](#limit)                        | Iterate up to a limit                       | `single.limit(data, limit)`                             | `single.limitAsync(data, limit)`                             |
| [`keys`](#keys)                          | Iterate keys of key-value pairs             | `single.keys(data)`                                     | `single.keysAsync(data)`                                     |
| [`map`](#map)                            | Map function onto each item                 | `single.map(data, mapper)`                              | `single.mapAsync(data, mapper)`                              |
| [`pairwise`](#pairwise)                  | Iterate successive overlapping pairs        | `single.pairwise(data)`                                 | `single.pairwiseAsync(data)`                                 |
| [`repeat`](#repeat)                      | Repeat an item a number of times            | `single.repeat(item, repetitions)`                      | `single.repeatAsync(item, repetitions)`                      |
| [`skip`](#skip)                          | Iterate after skipping elements             | `single.skip(data, count, [offset])`                    | `single.skipAsync(data, count, [offset])`                    |
| [`slice`](#slice)                        | Extract a slice of the iterable             | `single.slice(data, [start], [count], [step])`          | `single.sliceAsync(data, [start], [count], [step])`          |
| [`sort`](#sort)                          | Iterate a sorted collection                 | `single.sort(data, [comparator])`                       | `single.sortAsync(data, [comparator])`                       |
| [`takeWhile`](#take-while)               | Iterate elements while predicate is true    | `single.takeWhile(data, predicate)`                     | `single.takeWhileAsync(data, predicate)`                     |
| [`values`](#values)                      | Iterate values of key-value pairs           | `single.values(data)`                                   | `single.valuesAsync(data)`                                   |

#### Infinite Iteration
| Iterator              | Description                | Code Snippet                      |
|-----------------------|----------------------------|-----------------------------------|
| [`count`](#Count)     | Count sequentially forever | `infinite.count([start], [step])` |
| [`cycle`](#Cycle)     | Cycle through a collection | `infinite.cycle(iterable)`        |
| [`repeat`](#Repeat-1) | Repeat an item forever     | `infinite.repeat(item)`           |

#### Math Iteration
| Iterator                                   | Description                     | Sync Code Snippet                                 | Async Code Snippet                                     |
|--------------------------------------------|---------------------------------|---------------------------------------------------|--------------------------------------------------------|
| [`runningAverage`](#Running-Average)       | Running average accumulation    | `math.runningAverage(numbers, [initialValue])`    | `math.runningAverageAsync(numbers, [initialValue])`    |
| [`runningDifference`](#Running-Difference) | Running difference accumulation | `math.runningDifference(numbers, [initialValue])` | `math.runningDifferenceAsync(numbers, [initialValue])` |
| [`runningMax`](#Running-Max)               | Running maximum accumulation    | `math.runningMax(numbers, [initialValue])`        | `math.runningMax(numbers, [initialValue])`             |
| [`runningMin`](#Running-Min)               | Running minimum accumulation    | `math.runningMin(numbers, [initialValue])`        | `math.runningMinAsync(numbers, [initialValue])`        |
| [`runningProduct`](#Running-Product)       | Running product accumulation    | `math.runningProduct(numbers, [initialValue])`    | `math.runningProductAsync(numbers, [initialValue])`    |
| [`runningTotal`](#Running-Total)           | Running total accumulation      | `math.runningTotal(numbers, [initialValue])`      | `math.runningTotalAsync(numbers, [initialValue])`      |

#### Reduce
| Reducer                                | Description                                | Sync Code Snippet                             | Async Code Snippet                                 |
|----------------------------------------|--------------------------------------------|-----------------------------------------------|----------------------------------------------------|
| [`toAverage`](#To-Average)             | Mean average of elements                   | `reduce.toAverage(numbers)`                   | `reduce.toAverageAsync(numbers)`                   |
| [`toCount`](#To-Count)                 | Reduce to length of iterable               | `reduce.toCount(data)`                        | `reduce.toCountAsync(data)`                        |
| [`toFirst`](#To-First)                 | Reduce to its first value                  | `reduce.toFirst(data)`                        | `reduce.toFirstAsync(data)`                        |
| [`toFirstAndLast`](#To-First-And-Last) | Reduce to its first and last values        | `reduce.toFirstAndLast(data)`                 | `reduce.toFirstAndLastAsync(data)`                 |
| [`toLast`](#To-Last)                   | Reduce to its last value                   | `reduce.toLast(data)`                         | `reduce.toLastAsync(data)`                         |
| [`toMax`](#To-Max)                     | Reduce to its greatest element             | `reduce.toMax(numbers, [compareBy])`          | `reduce.toMaxAsync(numbers, [compareBy])`          |
| [`toMin`](#To-Min)                     | Reduce to its smallest element             | `reduce.toMin(numbers, [compareBy])`          | `reduce.toMinAsync(numbers, [compareBy])`          |
| [`toMinMax`](#To-Min-Max)              | Reduce to its lower and upper bounds       | `reduce.toMinMax(numbers, [compareBy])`       | `reduce.toMinMaxAsync(numbers, [compareBy])`       |
| [`toProduct`](#To-Product)             | Reduce to the product of its elements      | `reduce.toProduct(numbers)`                   | `reduce.toProductAsync(numbers)`                   |
| [`toRange`](#To-Range)                 | Reduce to difference of max and min values | `reduce.toRange(numbers)`                     | `reduce.toRangeAsync(numbers)`                     |
| [`toSum`](#To-Sum)                     | Reduce to the sum of its elements          | `reduce.toSum(numbers)`                       | `reduce.toSumAsync(numbers)`                       |
| [`toValue`](#To-Value)                 | Reduce to value using callable reducer     | `reduce.toValue(data, reducer, initialValue)` | `reduce.toValueAsync(data, reducer, initialValue)` |

#### Set and multiset Iteration
| Iterator                                       | Description                            | Sync Code Snippet                                 | Async Code Snippet                                     |
|------------------------------------------------|----------------------------------------|---------------------------------------------------|--------------------------------------------------------|
| [`cartesianProduct`](#cartesian-product)       | Iterate cartesian product of iterables | `set.cartesianProduct(...iterables)`              | `set.cartesianProductAsync(...iterables)`              |
| [`distinct`](#distinct)                        | Iterate only distinct items            | `set.distinct(data)`                              | `set.distinctAsync(data)`                              |
| [`intersection`](#intersection)                | Intersection of iterables              | `set.intersection(...iterables)`                  | `set.intersectionAsync(...iterables)`                  |
| [`partialIntersection`](#partial-intersection) | Partial intersection of iterables      | `set.partialIntersection(minCount, ...iterables)` | `set.partialIntersectionAsync(minCount, ...iterables)` |
| [`symmetricDifference`](#symmetric-difference) | Symmetric difference of iterables      | `set.symmetricDifference(...iterables)`           | `set.symmetricDifferenceAsync(...iterables)`           |
| [`union`](#union)                              | Union of iterables                     | `set.union(...iterables)`                         | `set.unionAsync(...iterables)`                         |

#### Summary
| Summary                                 | Description                                             | Sync Code Snippet                      | Async Code Snippet                          |
|-----------------------------------------|---------------------------------------------------------|----------------------------------------|---------------------------------------------|
| [`allMatch`](#all-match)                | True if all items are true according to predicate       | `summary.allMatch(data, predicate)`    | `summary.allMatchAsync(data, predicate)`    |
| [`allUnique`](#all-unique)              | True if all elements in collection are unique           | `summary.allUnique(data)`              | `summary.allUniqueAsync(data)`              |
| [`anyMatch`](#any-match)                | True if any item is true according to predicate         | `summary.anyMatch(data, predicate)`    | `summary.anyMatchAsync(data, predicate)`    |
| [`exactlyN`](#exactly-n)                | True if exactly n items are true according to predicate | `summary.exactlyN(data, n, predicate)` | `summary.exactlyNAsync(data, n, predicate)` |
| [`isAsyncIterable`](#is-async-iterable) | True if given data is async iterable                    | `summary.isAsyncIterable(data)`        | —                                           |
| [`isIterable`](#is-iterable)            | True if given data is iterable                          | `summary.isIterable(data)`             | —                                           |
| [`isIterator`](#is-iterator)            | True if given data is iterator                          | `summary.isIterator(data)`             | —                                           |
| [`isReversed`](#is-reversed)            | True if iterable reverse sorted                         | `summary.isReversed(data)`             | `summary.isReversedAsync(data)`             |
| [`isSorted`](#is-sorted)                | True if iterable sorted                                 | `summary.isSorted(data)`               | `summary.isSortedAsync(data)`               |
| [`isString`](#is-string)                | True if given data is string                            | `summary.isString(data)`               | `summary.isStringAsync(data)`               |
| [`noneMatch`](#none-match)              | True if none of items true according to predicate       | `summary.noneMatch(data, predicate)`   | `summary.noneMatchAsync(data, predicate)`   |
| [`same`](#same)                         | True if collections are the same                        | `summary.same(...collections)`         | `summary.sameAsync(...collections)`         |
| [`sameCount`](#same-count)              | True if collections have the same lengths               | `summary.sameCount(...collections)`    | `summary.sameCountAsync(...collections)`    |

#### Transform
| Iterator                                | Description                             | Sync Code Snippet                 | Async Code Snippet                |
|-----------------------------------------|-----------------------------------------|-----------------------------------|-----------------------------------|
| [`tee`](#tee)                           | Iterate duplicate iterables             | `transform.tee(data, count)`      | `transform.teeAsync(data, count)` |
| [`toArray`](#to-array)                  | Transforms collection to array          | `transform.toArray(data)`         | `transform.toArrayAsync(data)`    |
| [`toAsyncIterable`](#to-async-iterable) | Transforms collection to async iterable | `transform.toAsyncIterable(data)` | —                                 |
| [`toAsyncIterator`](#to-async-iterator) | Transforms collection to async iterator | `transform.toAsyncIterator(data)` | —                                 |
| [`toIterable`](#to-iterable)            | Transforms collection to iterable       | `transform.toIterable(data)`      | —                                 |
| [`toIterator`](#to-iterator)            | Transforms collection to iterator       | `transform.toIterator(data)`      | —                                 |
| [`toMap`](#to-map)                      | Transforms collection to map            | `transform.toMap(pairs)`          | `transform.toMapAsync(pairs)`     |
| [`toSet`](#to-set)                      | Transforms collection to set            | `transform.toSet(data)`           | `transform.toSetAsync(data)`      |

### Stream and AsyncStream Iteration Tools
#### Stream Sources
| Source                   | Description                         | Sync Code Snippet                 | Async Code Snippet                     |
|--------------------------|-------------------------------------|-----------------------------------|----------------------------------------|
| [`of`](#of)              | Create a stream from an iterable    | `Stream.of(iterable)`             | `AsyncStream.of(iterable)`             |
| [`ofEmpty`](#of-empty)   | Create an empty stream              | `Stream.ofEmpty()`                | `AsyncStream.ofEmpty()`                |
| [`ofCount`](#of-count)   | Create an infinite count stream     | `Stream.ofCount([start], [step])` | `AsyncStream.ofCount([start], [step])` |
| [`ofCycle`](#of-cycle)   | Create an infinite cycle stream     | `Stream.ofCycle(iterable)`        | `AsyncStream.ofCycle(iterable)`        |
| [`ofRepeat`](#of-repeat) | Create an infinite repeating stream | `Stream.ofRepeat(item)`           | `AsyncStream.ofRepeat(item)`           |

#### Stream Operations
| Operation                                               | Description                                                                               | Code Snippet                                                         |
|---------------------------------------------------------|-------------------------------------------------------------------------------------------|----------------------------------------------------------------------|
| [`cartesianProductWith`](#cartesian-product-with)       | Iterate cartesian product of iterable source with another iterable collections            | `stream.cartesianProductWith(...iterables)`                          |
| [`chainWith`](#chain-with)                              | Chain iterable source withs given iterables together into a single iteration              | `stream.chainWith(...iterables)`                                     |
| [`chunkwise`](#chunkwise-1)                             | Iterate by chunks                                                                         | `stream.chunkwise(chunkSize)`                                        |
| [`chunkwiseOverlap`](#chunkwise-overlap-1)              | Iterate by overlapped chunks                                                              | `stream.chunkwiseOverlap(chunkSize, overlap)`                        |
| [`compress`](#compress-1)                               | Compress source by filtering out data not selected                                        | `stream.compress(selectors)`                                         |
| [`distinct`](#distinct-1)                               | Filter out elements: iterate only unique items                                            | `stream.distinct()`                                                  |
| [`dropWhile`](#drop-while-1)                            | Drop elements from the iterable source while the predicate function is true               | `stream.dropWhile(predicate)`                                        |
| [`enumerate`](#enumerate-1)                             | Enumerates elements of stream                                                             | `stream.enumerate()`                                                 |
| [`filter`](#filter-1)                                   | Filter for only elements where the predicate function is true                             | `stream.filter(predicate)`                                           |
| [`flatMap`](#flat-map-1)                                | Map function onto elements and flatten result                                             | `stream.flatMap(mapper)`                                             |
| [`flatten`](#flatten-1)                                 | Flatten multidimensional stream                                                           | `stream.flatten([dimensions])`                                       |
| [`intersectionWith`](#intersection-with)                | Intersect stream and given iterables                                                      | `stream.intersectionWith(...iterables)`                              |
| [`groupBy`](#group-by-1)                                | Group stram data by a common data element                                                 | `stream.groupBy(groupKeyFunction, [itemKeyFunc])`                    |
| [`keys`](#keys-1)                                       | Iterate keys of key-value pairs from stream                                               | `stream.keys()`                                                      |
| [`limit`](#limit-1)                                     | Limit the stream's iteration                                                              | `stream.limit(limit)`                                                |
| [`map`](#map-1)                                         | Map function onto elements                                                                | `stream.map(mapper)`                                                 |
| [`pairwise`](#pairwise-1)                               | Return pairs of elements from iterable source                                             | `stream.pairwise()`                                                  |
| [`partialIntersectionWith`](#partial-intersection-with) | Partially intersect stream and given iterables                                            | `stream.partialIntersectionWith(minIntersectionCount, ...iterables)` |
| [`runningAverage`](#running-average-1)                  | Accumulate the running average (mean) over iterable source                                | `stream.runningAverage([initialValue])`                              |
| [`runningDifference`](#running-difference-1)            | Accumulate the running difference over iterable source                                    | `stream.runningDifference([initialValue])`                           |
| [`runningMax`](#running-max-1)                          | Accumulate the running max over iterable source                                           | `stream.runningMax([initialValue])`                                  |
| [`runningMin`](#running-min-1)                          | Accumulate the running min over iterable source                                           | `stream.runningMin([initialValue])`                                  |
| [`runningProduct`](#running-product-1)                  | Accumulate the running product over iterable source                                       | `stream.runningProduct([initialValue])`                              |
| [`runningTotal`](#running-total-1)                      | Accumulate the running total over iterable source                                         | `stream.runningTotal([initialValue])`                                |
| [`skip`](#skip-1)                                       | Skip some elements of the stream                                                          | `stream.skip(count, [offset])`                                       |
| [`slice`](#slice-1)                                     | Extract a slice of the stream                                                             | `stream.slice([start], [count], [step])`                             |
| [`sort`](#sort-1)                                       | Sorts the stream                                                                          | `stream.sort([comparator])`                                          |
| [`symmetricDifferenceWith`](#symmetric-difference-with) | Symmetric difference of stream and given iterables                                        | `stream.symmetricDifferenceWith(...iterables)`                       |
| [`takeWhile`](#take-while-1)                            | Return elements from the iterable source as long as the predicate is true                 | `stream.takeWhile(predicate)`                                        |
| [`unionWith`](#union-with)                              | Union of stream and given iterables                                                       | `stream.union(...iterables)`                                         |
| [`values`](#values-1)                                   | Iterate values of key-value pairs from stream                                             | `stream.values()`                                                    |
| [`zipWith`](#zip-with)                                  | Iterate iterable source with another iterable collections simultaneously                  | `stream.zipWith(...iterables)`                                       |
| [`zipEqualWith`](#zip-equal-with)                       | Iterate iterable source with another iterable collections of equal lengths simultaneously | `stream.zipEqualWith(...iterables)`                                  |
| [`zipFilledWith`](#zip-filled-with)                     | Iterate iterable source with another iterable collections simultaneously (with filler)    | `stream.zipFilledWith(filler, ...iterables)`                         |
| [`zipLongestWith`](#zip-longest-with)                   | Iterate iterable source with another iterable collections simultaneously                  | `stream.zipLongestWith(...iterables)`                                |

#### Stream Terminal Operations
##### Transformation Terminal Operations
| Terminal Operation       | Description                                      | Code Snippet        |
|--------------------------|--------------------------------------------------|---------------------|
| [`tee`](#tee-1)          | Returns array of multiple identical Streams      | `stream.tee(count)` |
| [`toArray`](#to-array-1) | Returns array of stream elements                 | `stream.toArray()`  |
| [`toMap`](#to-map-1)     | Returns map of stream elements (key-value pairs) | `stream.toMap()`    |
| [`toSet`](#to-set-1)     | Returns set of stream elements                   | `stream.toSet()`    |

##### Reduction Terminal Operations
| Terminal Operation                       | Description                                        | Code Snippet                            |
|------------------------------------------|----------------------------------------------------|-----------------------------------------|
| [`toAverage`](#to-average-1)             | Reduces stream to the mean average of its items    | `stream.toAverage()`                    |
| [`toCount`](#to-count-1)                 | Reduces stream to its length                       | `stream.toCount()`                      |
| [`toFirst`](#to-first-1)                 | Reduces stream to its first value                  | `stream.toFirst()`                      |
| [`toFirstAndLast`](#to-first-and-last-1) | Reduces stream to its first and last values        | `stream.toFirstAndLast()`               |
| [`toLast`](#to-last-1)                   | Reduces stream to its last value                   | `stream.toLast()`                       |
| [`toMax`](#to-max-1)                     | Reduces stream to its max value                    | `stream.toMax([compareBy])`             |
| [`toMin`](#to-min-1)                     | Reduces stream to its min value                    | `stream.toMin([compareBy])`             |
| [`toMin`](#to-min-max-1)                 | Reduce stream to its lower and upper bounds        | `stream.toMinMax([compareBy])`          |
| [`toProduct`](#to-product-1)             | Reduces stream to the product of its items         | `stream.toProduct()`                    |
| [`toRange`](#to-range-1)                 | Reduces stream to difference of max and min values | `stream.toRange()`                      |
| [`toSum`](#to-sum-1)                     | Reduces stream to the sum of its items             | `stream.toSum()`                        |
| [`toValue`](#to-value-1)                 | Reduces stream like array.reduce() function        | `stream.toValue(reducer, initialValue)` |

##### Summary Terminal Operations
| Terminal Operation                  | Description                                                            | Code Snippet                           |
|-------------------------------------|------------------------------------------------------------------------|----------------------------------------|
| [`allMatch`](#all-match-1)          | Returns true if all items in stream match predicate                    | `stream.allMatch(predicate)`           |
| [`allUnique`](#all-unique-1)        | Returns true if all elements of stream are unique                      | `stream.allUnique(predicate)`          |
| [`anyMatch`](#any-match-1)          | Returns true if any item in stream matches predicate                   | `stream.anyMatch(predicate)`           |
| [`exactlyN`](#exactly-n-1)          | Returns true if exactly n items are true according to predicate        | `stream.exactlyN(n, predicate)`        |
| [`isReversed`](#is-reversed-1)      | Returns true if stream is sorted in reverse descending order           | `stream.isReversed()`                  |
| [`isSorted`](#is-sorted-1)          | Returns true if stream is sorted in ascending order                    | `stream.isSorted()`                    |
| [`noneMatch`](#none-match-1)        | Returns true if none of the items in stream match predicate            | `stream.noneMatch(predicate)`          |
| [`sameWith`](#same-with)            | Returns true if stream and all given collections are the same          | `stream.sameWith(...collections)`      |
| [`sameCountWith`](#same-count-with) | Returns true if stream and all given collections have the same lengths | `stream.sameCountWith(...collections)` |

#### Stream Debug Operations
| Debug Operation              | Description                                    | Code Snippet                  |
|------------------------------|------------------------------------------------|-------------------------------|
| [`peek`](#peek)              | Peek at each element between stream operations | `stream.peek(peekFunc)`       |
| [`peekStream`](#peek-stream) | Peek at the entire stream between operations   | `stream.peekStream(peekFunc)` |

Usage
-----

## Multi Iteration
### Chain
Chain multiple iterables together into a single continuous sequence.

```
function* chain<T>(
  ...iterables: Array<Iterable<T> | Iterator<T>>
): Iterable<T>
```
```typescript
import { multi } from '@osjwnpm/nesciunt-voluptatem-quo';

const prequels = ['Phantom Menace', 'Attack of the Clones', 'Revenge of the Sith'];
const originals = ['A New Hope', 'Empire Strikes Back', 'Return of the Jedi'];

for (const movie of multi.chain(prequels, originals)) {
  console.log(movie);
}
// 'Phantom Menace', 'Attack of the Clones', 'Revenge of the Sith', 'A New Hope', 'Empire Strikes Back', 'Return of the Jedi'
```

### Zip
Iterate multiple iterable collections simultaneously.

```
function* zip<T extends Array<Iterable<unknown> | Iterator<unknown>>>(
  ...iterables: T
): Iterable<ZipTuple<T, never>>
```

```typescript
import { multi } from '@osjwnpm/nesciunt-voluptatem-quo';

const languages = ['PHP', 'Python', 'Java', 'Go'];
const mascots = ['elephant', 'snake', 'bean', 'gopher'];

for (const [language, mascot] of multi.zip(languages, mascots)) {
  console.log(`The ${language} language mascot is an ${mascot}.`);
}
// The PHP language mascot is an elephant.
// ...
```

Zip works with multiple iterable inputs - not limited to just two.
```typescript
import { multi } from '@osjwnpm/nesciunt-voluptatem-quo';

const names          = ['Ryu', 'Ken', 'Chun Li', 'Guile'];
const countries      = ['Japan', 'USA', 'China', 'USA'];
const signatureMoves = ['hadouken', 'shoryuken', 'spinning bird kick', 'sonic boom'];

for (const [name, country, signatureMove] of multi.zip(names, countries, signatureMoves)) {
  const streetFighter = new StreetFighter(name, country, signatureMove);
}
```
Note: For uneven lengths, iteration stops when the shortest iterable is exhausted.

### Zip Filled
Iterate multiple iterable collections simultaneously.

```
function* zipFilled<T extends Array<Iterable<unknown> | Iterator<unknown>>, F>(
  filler: F,
  ...iterables: T
): Iterable<ZipTuple<T, F>>
```

For uneven lengths, the exhausted iterables will produce `filler` value for the remaining iterations.

```typescript
import { multi } from '@osjwnpm/nesciunt-voluptatem-quo';

const letters = ['A', 'B', 'C'];
const numbers = [1, 2];

for (const [letter, number] of multi.zipFilled('filler', letters, numbers)) {
  // ['A', 1], ['B', 2], ['C', 'filler']
}
```

### Zip Longest
Iterate multiple iterable collections simultaneously.

```
function* zipLongest<T extends Array<Iterable<unknown> | Iterator<unknown>>>(
  ...iterables: T
): Iterable<ZipTuple<T, undefined>>
```

For uneven lengths, the exhausted iterables will produce `undefined` for the remaining iterations.

```typescript
import { multi } from '@osjwnpm/nesciunt-voluptatem-quo';

const letters = ['A', 'B', 'C'];
const numbers = [1, 2];

for (const [letter, number] of multi.zipLongest(letters, numbers)) {
  // ['A', 1], ['B', 2], ['C', undefined]
}
```

### Zip Equal
Iterate multiple iterable collections with equal lengths simultaneously.

Throws `LengthException` if lengths are not equal, meaning that at least one iterator ends before the others.

```
function* zipEqual<T extends Array<Iterable<unknown> | Iterator<unknown>>>(
  ...iterables: T
): Iterable<ZipTuple<T, never>>
```

```typescript
import { multi } from '@osjwnpm/nesciunt-voluptatem-quo';

const letters = ['A', 'B', 'C'];
const numbers = [1, 2, 3];

for (const [letter, number] of multi.zipEqual(letters, numbers)) {
    // ['A', 1], ['B', 2], ['C', 3]
}
```

## Single Iteration
### Chunkwise
Return elements in chunks of a certain size.

```
function* chunkwise<T>(
  data: Iterable<T>|Iterator<T>,
  chunkSize: number,
): Iterable<Array<T>>
```

Chunk size must be at least 1.

```typescript
import { single } from '@osjwnpm/nesciunt-voluptatem-quo';

const movies = [
    'Phantom Menace', 'Attack of the Clones', 'Revenge of the Sith',
    'A New Hope', 'Empire Strikes Back', 'Return of the Jedi',
    'The Force Awakens', 'The Last Jedi', 'The Rise of Skywalker',
];
const trilogies = [];

for (const trilogy of single.chunkwise(movies, 3)) {
    trilogies.push(trilogy);
}
// [
//     ['Phantom Menace', 'Attack of the Clones', 'Revenge of the Sith'],
//     ['A New Hope', 'Empire Strikes Back', 'Return of the Jedi'],
//     ['The Force Awakens', 'The Last Jedi', 'The Rise of Skywalker]',
// ]
```

### Chunkwise Overlap
Return overlapped chunks of elements.

```
function* chunkwiseOverlap<T>(
  data: Iterable<T>|Iterator<T>,
  chunkSize: number,
  overlapSize: number,
  includeIncompleteTail: boolean = true,
): Iterable<Array<T>>
```

* Chunk size must be at least 1.
* Overlap size must be less than chunk size.

```typescript
import { single } from '@osjwnpm/nesciunt-voluptatem-quo';

const numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

for (const chunk of single.chunkwiseOverlap(numbers, 3, 1)) {
  // [1, 2, 3], [3, 4, 5], [5, 6, 7], [7, 8, 9], [9, 10]
}
```

### Compress
Compress an iterable by filtering out data that is not selected.

```
function* compress<T>(
  data: Iterable<T> | Iterator<T>,
  selectors: Iterable<number|boolean> | Iterator<number|boolean>
): Iterable<T>
```

```typescript
import { single } from '@osjwnpm/nesciunt-voluptatem-quo';

const movies = [
  'Phantom Menace', 'Attack of the Clones', 'Revenge of the Sith',
  'A New Hope', 'Empire Strikes Back', 'Return of the Jedi',
  'The Force Awakens', 'The Last Jedi', 'The Rise of Skywalker'
];
const goodMovies = [0, 0, 0, 1, 1, 1, 1, 0, 0];

for (const goodMovie of single.compress(movies, goodMovies)) {
  console.log(goodMovie);
}
// 'A New Hope', 'Empire Strikes Back', 'Return of the Jedi', 'The Force Awakens'
```

### Drop While
Drop elements from the iterable while the predicate function is true.

Once the predicate function returns false once, all remaining elements are returned.

```
function* dropWhile<T>(
  data: Iterable<T>|Iterator<T>,
  predicate: (item: T) => boolean
): Iterable<T>
```

```typescript
import { single } from '@osjwnpm/nesciunt-voluptatem-quo';

const scores    = [50, 60, 70, 85, 65, 90];
const predicate = (x) => x < 70;

for (const score of single.dropWhile(scores, predicate)) {
  console.log(score);
}
// 70, 85, 65, 90
```

### Enumerate
Enumerates elements of given collection.

```
function* enumerate<T>(data: Iterable<T>|Iterator<T>): Iterable<[number, T]>
```

```typescript
import { single } from '@osjwnpm/nesciunt-voluptatem-quo';

const letters = ['a', 'b', 'c', 'd', 'e'];

for (const item of single.enumerate(letters)) {
  // [[0, 'a'], [1, 'b'], [2, 'c'], [3, 'd'], [4, 'e']]
}
```

### Filter
Filter out elements from the iterable only returning elements where the predicate function is true.

```
function* filter<T>(
  data: Iterable<T>|Iterator<T>,
  predicate: (datum: T) => boolean,
): Iterable<T>
```

```typescript
import { single } from '@osjwnpm/nesciunt-voluptatem-quo';

const starWarsEpisodes = [1, 2, 3, 4, 5, 6, 7, 8, 9];
const goodMoviePredicate = (episode) => episode > 3 && episode < 8;

for (const goodMovie of single.filter(starWarsEpisodes, goodMoviePredicate)) {
  console.log(goodMovie);
}
// 4, 5, 6, 7
```

### Flat Map
Map a function only the elements of the iterable and then flatten the results.

```
function* flatMap<TInput, TOutput>(
  data: Iterable<TInput>|Iterator<TInput>,
  mapper: FlatMapper<TInput, TOutput>,
): Iterable<TOutput>
```

```typescript
import { single } from '@osjwnpm/nesciunt-voluptatem-quo';

const data = [1, 2, 3, 4, 5];
const mapper = (item) => [item, -item];

for (number of single.flatMap(data, mapper)) {
  console.log(number);
}
// 1 -1 2 -2 3 -3 4 -4 5 -5
```

### Flatten
Flatten a multidimensional iterable.

```
function* flatten(
  data: Iterable<unknown>|Iterator<unknown>,
  dimensions: number = Infinity,
): Iterable<unknown>
```

```typescript
import { single } from '@osjwnpm/nesciunt-voluptatem-quo';

const multidimensional = [1, [2, 3], [4, 5]];

const flattened = [];
for (const number of single.flatten(multidimensional)) {
    flattened.push(number);
}
// [1, 2, 3, 4, 5]
```

### Group By
Group data by a common data element.

Iterate pairs of group name and collection of grouped items.

```
function* groupBy<T>(
  data: Iterable<T> | Iterator<T>,
  groupKeyFunction: (item: T) => string,
  itemKeyFunction?: (item: T) => string,
): Iterable<[string, Array<T>] | [string, Record<string, T>]>
```

* The `groupKeyFunction` determines the key to group elements by.
* The optional `itemKeyFunction` allows custom indexes within each group member.
* Collection of grouped items may be an array or an object (depends on presence of `itemKeyFunction` param).

```typescript
import { single } from '@osjwnpm/nesciunt-voluptatem-quo';

const cartoonCharacters = [
    ['Garfield', 'cat'],
    ['Tom', 'cat'],
    ['Felix', 'cat'],
    ['Heathcliff', 'cat'],
    ['Snoopy', 'dog'],
    ['Scooby-Doo', 'dog'],
    ['Odie', 'dog'],
    ['Donald', 'duck'],
    ['Daffy', 'duck'],
];

const charactersGroupedByAnimal = {};
for (const [animal, characters] of single.groupBy(cartoonCharacters, (x) => x[1])) {
    charactersGroupedByAnimal[animal] = characters;
}
/*
{
  cat: [
    ['Garfield', 'cat'],
    ['Tom', 'cat'],
    ['Felix', 'cat'],
    ['Heathcliff', 'cat'],
  ],
  dog: [
    ['Snoopy', 'dog'],
    ['Scooby-Doo', 'dog'],
    ['Odie', 'dog'],
  ],
  duck: [
    ['Donald', 'duck'],
    ['Daffy', 'duck'],
  ],
}
*/
```

### Keys
Iterate keys of key-value pairs.

```
function* keys<TKey, TValue>(
  collection: Iterable<[TKey, TValue]>|Iterator<[TKey, TValue]>,
): Iterable<TKey>
```

```typescript
import { single } from '@osjwnpm/nesciunt-voluptatem-quo';

const dict = new Map([['a', 1], ['b', 2], ['c', 3]]);

for (const key of single.keys(dict)) {
  console.log(key);
}
// 'a', 'b', 'c'
```

### Limit
Iterate up to a limit.

Stops even if more data available if limit reached.

```
function* limit<T>(data: Iterable<T>|Iterator<T>, count: number): Iterable<T>
```

```typescript
import { single } from '@osjwnpm/nesciunt-voluptatem-quo';

const matrixMovies = ['The Matrix', 'The Matrix Reloaded', 'The Matrix Revolutions', 'The Matrix Resurrections'];
const limit = 1;

for (const goodMovie of single.limit(matrixMovies, limit)) {
    console.log(goodMovie);
}
// 'The Matrix' (and nothing else)
```

### Map
Map a function onto each element.

```
function* map<TInput, TOutput>(
  data: Iterable<TInput>|Iterator<TInput>,
  mapper: (datum: TInput) => TOutput,
): Iterable<TOutput>
```

```typescript
import { single } from '@osjwnpm/nesciunt-voluptatem-quo';

const grades = [100, 99, 95, 98, 100];
const strictParentsOpinion = (g) => (g === 100) ? 'A' : 'F';

for (const actualGrade of single.map(grades, strictParentsOpinion)) {
  console.log(actualGrade);
}
// A, F, F, F, A
```

### Pairwise
Returns successive overlapping pairs.

Returns empty generator if given collection contains fewer than 2 elements.

```
function* pairwise<T>(data: Iterable<T>|Iterator<T>): Iterable<Pair<T>>
```

```typescript
import { single } from '@osjwnpm/nesciunt-voluptatem-quo';

const friends = ['Ross', 'Rachel', 'Chandler', 'Monica', 'Joey', 'Phoebe'];

for (const [leftFriend, rightFriend] of single.pairwise(friends)) {
  console.log(`${leftFriend} and ${rightFriend}`);
}
// Ross and Rachel, Rachel and Chandler, Chandler and Monica, ...
```

### Repeat
Repeat an item.

```
function* repeat<T>(item: T, repetitions: number): Iterable<T>
```

```typescript
import { single } from '@osjwnpm/nesciunt-voluptatem-quo';

data = 'Beetlejuice';
repetitions = 3;

for (const repeated of single.repeat(data, repetitions)) {
  console.log(repeated);
}
// 'Beetlejuice', 'Beetlejuice', 'Beetlejuice'
```

### Skip
Skip n elements in the iterable after optional offset offset.

```
function* skip<T>(
  data: Iterable<T> | Iterator<T>,
  count: number,
  offset: number = 0
): Iterable<T>
```

```typescript
import { single } from '@osjwnpm/nesciunt-voluptatem-quo';

const movies = [
    'The Phantom Menace', 'Attack of the Clones', 'Revenge of the Sith',
    'A New Hope', 'The Empire Strikes Back', 'Return of the Jedi',
    'The Force Awakens', 'The Last Jedi', 'The Rise of Skywalker'
];

const prequelsRemoved = [];
for (const nonPrequel of Single.skip(movies, 3)) {
  prequelsRemoved.push(nonPrequel);
} // Episodes IV - IX

const onlyTheBest = [];
for (const nonSequel of Single.skip(prequelsRemoved, 3, 3)) {
  onlyTheBest.push(nonSequel);
}
// 'A New Hope', 'The Empire Strikes Back', 'Return of the Jedi'
```

### Slice
Extract a slice of the iterable.

```
function* slice<T>(
  data: Iterable<T>|Iterator<T>,
  start: number = 0,
  count?: number,
  step: number = 1,
): Iterable<T>
```

```typescript
import { single } from '@osjwnpm/nesciunt-voluptatem-quo';

const olympics = [1992, 1994, 1996, 1998, 2000, 2002, 2004, 2006, 2008, 2010, 2012, 2014, 2016, 2018, 2020, 2022];
const winterOlympics = [];

for (const winterYear of single.slice(olympics, 1, 8, 2)) {
    winterOlympics.push(winterYear);
}
// [1994, 1998, 2002, 2006, 2010, 2014, 2018, 2022]
```

### Sort
Iterate the collection sorted.

```
function* sort<T>(
  data: Iterable<T> | Iterator<T>,
  comparator?: Comparator<T>,
): Iterable<T>
```

Uses default sorting if optional comparator function not provided.

```typescript
import { single } from '@osjwnpm/nesciunt-voluptatem-quo';

const data = [3, 4, 5, 9, 8, 7, 1, 6, 2];

for (const datum of single.sort(data)) {
  console.log(datum);
}
// 1, 2, 3, 4, 5, 6, 7, 8, 9
```

### Take While
Return elements from the iterable as long as the predicate is true.

Stops iteration as soon as the predicate returns false, even if other elements later on would eventually return true (different from filterTrue).

```
function* takeWhile<T>(
  data: Iterable<T> | Iterator<T>,
  predicate: (item: T) => boolean
): Iterable<T>
```

```typescript
import { single } from '@osjwnpm/nesciunt-voluptatem-quo';

const prices = [0, 0, 5, 10, 0, 0, 9];
const isFree = (price) => price == 0;

for (const freePrice of single.takeWhile(prices, isFree)) {
  console.log(freePrice);
}
// 0, 0
```

### Values
Iterate values of key-value pairs.

```
function* values<TKey, TValue>(
  collection: Iterable<[TKey, TValue]>|Iterator<[TKey, TValue]>,
): Iterable<TValue>
```

```typescript
import { single } from '@osjwnpm/nesciunt-voluptatem-quo';

const dict = new Map([['a', 1], ['b', 2], ['c', 3]]);

for (const value of single.keys(dict)) {
  console.log(value);
}
// 1, 2, 3
```

## Infinite Iteration

### Count
Count sequentially forever.

```
function* count(start: number = 1, step: number = 1): Iterable<number>
```

```typescript
import { infinite } from '@osjwnpm/nesciunt-voluptatem-quo';

for (const i of infinite.count()) {
  console.log(i);
}
// 1, 2, 3, 4, 5, ...
```

### Cycle
Cycle through the elements of a collection sequentially forever.

```
function* cycle<T>(iterable: Iterable<T> | Iterator<T>): Iterable<T>
```

```typescript
import { infinite } from '@osjwnpm/nesciunt-voluptatem-quo';

for (const item of infinite.cycle(['rock', 'paper', 'scissors'])) {
  console.log(item);
}
// 'rock', 'paper', 'scissors', 'rock', 'paper', 'scissors', 'rock', ...
```

### Repeat
Repeat an item forever.

```
function* repeat<T>(item: T): Iterable<T>
```

```typescript
import { infinite } from '@osjwnpm/nesciunt-voluptatem-quo';

for (const item of infinite.repeat('bla')) {
  console.log(item);
}
// bla, bla, bla, bla, bla, ...
```

## Math Iteration

### Running Average
Accumulate the running average over a list of numbers.

```
function* runningAverage<T>(
  numbers: Iterable<T> | Iterator<T>,
  initialValue?: number
): Iterable<number>
```

```typescript
import { math } from '@osjwnpm/nesciunt-voluptatem-quo';

const grades = [100, 80, 80, 90, 85];

for (const runningAverage of math.runningAverage(grades)) {
  console.log(runningAverage);
}
// 100, 90, 86.667, 87.5, 87
```

### Running Difference
Accumulate the running difference over a list of numbers.

```
function* runningDifference<T>(
  numbers: Iterable<T> | Iterator<T>,
  initialValue?: number
): Iterable<number>
```

```typescript
import { math } from '@osjwnpm/nesciunt-voluptatem-quo';

const credits = [1, 2, 3, 4, 5];

for (const runningDifference of math.runningDifference(credits)) {
    console.log(runningDifference);
}
// -1, -3, -6, -10, -15
```

Provide an optional initial value to lead off the running difference.

```typescript
import { math } from '@osjwnpm/nesciunt-voluptatem-quo';

const dartsScores   = [50, 50, 25, 50];
const startingScore = 501;

for (const runningScore of math.runningDifference(dartsScores, startingScore)) {
  console.log(runningScore);
}
// 501, 451, 401, 376, 326
```

### Running Max
Accumulate the running maximum over a list of numbers.

```
function* runningMax<T>(
  numbers: Iterable<T> | Iterator<T>,
  initialValue?: number
): Iterable<number>
```

```typescript
import { math } from '@osjwnpm/nesciunt-voluptatem-quo';

const numbers = [1, 2, 1, 3, 5];

for (const runningMax of math.runningMax(numbers)) {
  console.log(runningMax);
}
// 1, 2, 2, 3, 5
```

### Running Min
Accumulate the running minimum over a list of numbers.

```
function* runningMin<T>(
  numbers: Iterable<T> | Iterator<T>,
  initialValue?: number
): Iterable<number>
```

```typescript
import { math } from '@osjwnpm/nesciunt-voluptatem-quo';

const numbers = [3, 4, 2, 5, 1];

for (const runningMin of math.runningMin(numbers)) {
    console.log(runningMin);
}
// 3, 3, 2, 2, 1
```

### Running Product
Accumulate the running product over a list of numbers.

```
function* runningProduct<T>(
  numbers: Iterable<T> | Iterator<T>,
  initialValue?: number
): Iterable<number>
```

```typescript
import { math } from '@osjwnpm/nesciunt-voluptatem-quo';

const numbers = [1, 2, 3, 4, 5];

for (const runningProduct of math.runningProduct(numbers)) {
  console.log(runningProduct);
}
// 1, 2, 6, 24, 120
```

Provide an optional initial value to lead off the running product.

```typescript
import { math } from '@osjwnpm/nesciunt-voluptatem-quo';

const numbers = [1, 2, 3, 4, 5];
const initialValue = 5;

for (const runningProduct of math.runningProduct(numbers, initialValue)) {
  console.log(runningProduct);
}
// 5, 5, 10, 30, 120, 600
```

### Running Total
Accumulate the running total over a list of numbers.

```
function* runningTotal<T>(
  numbers: Iterable<T> | Iterator<T>,
  initialValue?: number
): Iterable<number>
```

```typescript
import { math } from '@osjwnpm/nesciunt-voluptatem-quo';

const prices = [1, 2, 3, 4, 5];

for (const runningTotal of math.runningTotal(prices)) {
    console.log(runningTotal);
}
// 1, 3, 6, 10, 15
```

Provide an optional initial value to lead off the running total.
```typescript
import { math } from '@osjwnpm/nesciunt-voluptatem-quo';

const prices = [1, 2, 3, 4, 5];
const initialValue = 5;

for (const runningTotal of math.runningTotal(prices, initialValue)) {
  console.log(runningTotal);
}
// 5, 6, 8, 11, 15, 20
```

## Reduce
### To Average
Reduces to the mean average.

Returns `undefined` if collection is empty.

```
function toAverage(
  data: Iterable<number> | Iterator<number>,
): number | undefined
```

```typescript
import { reduce } from '@osjwnpm/nesciunt-voluptatem-quo';

const grades = [100, 90, 95, 85, 94];

const finalGrade = reduce.toAverage(numbers);
// 92.8
```

### To Count
Reduces iterable to its length.

```
function toCount(data: Iterable<unknown>|Iterator<unknown>): number
```

```typescript
import { reduce } from '@osjwnpm/nesciunt-voluptatem-quo';

const data = [1, 2, 3];

const length = reduce.toCount(data);
// 3
```

### To First
Reduces iterable to its first element.

```
function toFirst<T>(data: Iterable<T> | Iterator<T>): T
```

Throws `LengthException` if collection is empty.

```typescript
import { reduce } from '@osjwnpm/nesciunt-voluptatem-quo';

const medals = ['gold', 'silver', 'bronze'];

const first = reduce.toFirst(medals);
// gold
```

### To First And Last
Reduces iterable to its first and last elements.

```
function toFirstAndLast<T>(data: Iterable<T> | Iterator<T>): [T, T]
```

Throws `LengthException` if collection is empty.

```typescript
import { reduce } from '@osjwnpm/nesciunt-voluptatem-quo';

const medals = ['gold', 'silver', 'bronze'];

const result = reduce.toFirstAndLast(medals);
// [gold, bronze]
```

### To Last
Reduces iterable to its last element.

```
function toLast<T>(data: Iterable<T> | Iterator<T>): T
```

Throws `LengthException` if collection is empty.

```typescript
import { reduce } from '@osjwnpm/nesciunt-voluptatem-quo';

const medals = ['gold', 'silver', 'bronze'];

const first = reduce.toFirst(medals);
// bronze
```

### To Max
Reduces to the max value.

```
function toMax<TValue>(
  data: Iterable<TValue>|Iterator<TValue>,
  compareBy?: (datum: TValue) => Comparable,
): TValue|undefined
```

- Optional callable param `compareBy` must return comparable value.
- If `compareBy` is not provided then items of given collection must be comparable.
- Returns `undefined` if collection is empty.

```typescript
import { reduce } from '@osjwnpm/nesciunt-voluptatem-quo';

const numbers = [5, 3, 1, 2, 4];

const result = reduce.toMax(numbers);
// 1

const movieRatings = [
  {
    title: 'The Matrix',
    rating: 4.7,
  },
  {
    title: 'The Matrix Reloaded',
    rating: 4.3,
  },
  {
    title: 'The Matrix Revolutions',
    rating: 3.9,
  },
  {
    title: 'The Matrix Resurrections',
    rating: 2.5,
  },
];
const compareBy = (movie) => movie.rating;

const lowestRatedMovie = reduce.toMin(movieRatings, compareBy);
// {
//   title: 'The Matrix',
//   rating: 4.7,
// }
```

### To Min
Reduces to the min value.

```
function toMin<TValue>(
  data: Iterable<TValue>|Iterator<TValue>,
  compareBy?: (datum: TValue) => Comparable,
): TValue|undefined
```

- Optional callable param `compareBy` must return comparable value.
- If `compareBy` is not provided then items of given collection must be comparable.
- Returns `undefined` if collection is empty.

```typescript
import { reduce } from '@osjwnpm/nesciunt-voluptatem-quo';

const numbers = [5, 3, 1, 2, 4];

const result = reduce.toMin(numbers);
// 1

const movieRatings = [
  {
    title: 'The Matrix',
    rating: 4.7,
  },
  {
    title: 'The Matrix Reloaded',
    rating: 4.3,
  },
  {
    title: 'The Matrix Revolutions',
    rating: 3.9,
  },
  {
    title: 'The Matrix Resurrections',
    rating: 2.5,
  },
];
const compareBy = (movie) => movie.rating;

const lowestRatedMovie = reduce.toMin(movieRatings, compareBy);
// {
//   title: 'The Matrix Resurrections',
//   rating: 2.5,
// }
```

### To Min Max
Reduces collection to its lower and upper bounds.

```
function toMinMax<T>(
  data: Iterable<T> | Iterator<T>,
  compareBy?: (item: T) => Comparable
): [T?, T?]
```

- Optional callable param `compareBy` must return comparable value.
- If `compareBy` is not provided then items of given collection must be comparable.
- Returns `[undefined, undefined]` if collection is empty.

```typescript
import { reduce } from '@osjwnpm/nesciunt-voluptatem-quo';

const numbers = [5, 3, 1, 2, 4];

const result = reduce.toMinMax(numbers);
// [1, 5]

const movieRatings = [
  {
    title: 'The Matrix',
    rating: 4.7,
  },
  {
    title: 'The Matrix Reloaded',
    rating: 4.3,
  },
  {
    title: 'The Matrix Revolutions',
    rating: 3.9,
  },
  {
    title: 'The Matrix Resurrections',
    rating: 2.5,
  },
];
const compareBy = (movie) => movie.rating;

const lowestRatedMovie = reduce.toMin(movieRatings, compareBy);
// [{
//   title: 'The Matrix Resurrections',
//   rating: 2.5,
// },
// {
//   title: 'The Matrix',
//   rating: 4.7,
// }]
```

### To Product
Reduces to the product of its elements.

Returns `undefined` if collection is empty.

```
function toProduct(data: Iterable<number>|Iterator<number>): number|undefined
```

```typescript
import { reduce } from '@osjwnpm/nesciunt-voluptatem-quo';

const primeFactors = [5, 2, 2];

const number = reduce.toProduct(primeFactors);
// 20
```

### To Range
Reduces given collection to its range (difference between max and min).

```
function toRange(numbers: Iterable<number|string> | Iterator<number|string>): number
```

Returns `0` if iterable source is empty.

```typescript
import { reduce } from '@osjwnpm/nesciunt-voluptatem-quo';

const grades = [100, 90, 80, 85, 95];

const range = reduce.toRange(numbers);
// 20
```

### To Sum
Reduces to the sum of its elements.

```
function toSum(data: Iterable<number>|Iterator<number>): number
```

```typescript
import { reduce } from '@osjwnpm/nesciunt-voluptatem-quo';

const parts = [10, 20, 30];

const sum = reduce.toSum(parts);
// 60
```

### To Value
Reduce elements to a single value using reducer function.

```
function toValue<TInput, TOutput>(
  data: Iterable<TInput>|Iterator<TInput>,
  reducer: (carry: TOutput|undefined, datum: TInput) => TOutput,
  initialValue?: TOutput,
): TOutput|undefined
```

```typescript
import { reduce } from '@osjwnpm/nesciunt-voluptatem-quo';

const input = [1, 2, 3, 4, 5];
const sum = (carry, item) => carry + item;

const result = reduce.toValue(input, sum, 0);
// 15
```

## Set and multiset
### Cartesian Product
Iterates cartesian product of given iterables.

```
function* cartesianProduct<T extends Array<Iterable<unknown> | Iterator<unknown>>>(
  ...iterables: T
): Iterable<ZipTuple<T, never>>
```

```typescript
import { set } from '@osjwnpm/nesciunt-voluptatem-quo';

const numbers = [1, 2];
const letters = ['a', 'b'];
const chars = ['!', '?'];

for (const tuple of set.cartesianProduct(numbers, letters, chars)) {
  console.log(tuple);
}
/*
  [1, 'a', '!'],
  [1, 'a', '?'],
  [1, 'b', '!'],
  [1, 'b', '?'],
  [2, 'a', '!'],
  [2, 'a', '?'],
  [2, 'b', '!'],
  [2, 'b', '?'],
*/
```

### Distinct
Filter out elements from the iterable only returning distinct elements.

```
function* distinct<T>(
  data: Iterable<T>|Iterator<T>,
  compareBy?: (datum: T) => Comparable
): Iterable<T>
```

Always treats different instances of objects and arrays as unequal.

```typescript
import { set } from '@osjwnpm/nesciunt-voluptatem-quo';

const chessSet = ['rook', 'rook', 'knight', 'knight', 'bishop', 'bishop', 'king', 'queen', 'pawn', 'pawn'];

for (const chessPiece of set.distinct(chessSet)) {
  console.log(chessPiece);
}
// rook, knight, bishop, king, queen, pawn


const users = [
  { 'name': 'John', 'id': 1 },
  { 'name': 'Mary', 'id': 2 },
  { 'name': 'Mary', 'id': 3 },
  { 'name': 'John', 'id': 4 },
  { 'name': 'Jane', 'id': 5 },
];

for (const user of set.distinct(users, (item) => item['name'])) {
  console.log(user);
}
// { 'name': 'John', 'id': 1 }, { 'name': 'Mary', 'id': 2 }, { 'name': 'Jane', 'id': 5 }
```

### Intersection
Iterates intersection of iterables.

```
function* intersection<T>(...iterables: Array<Iterable<T> | Iterator<T>>): Iterable<T>
```

* Always treats different instances of objects and arrays as unequal.
* If input iterables produce duplicate items, then [multiset](https://en.wikipedia.org/wiki/Multiset) intersection rules apply.

```typescript
import { set } from '@osjwnpm/nesciunt-voluptatem-quo';

const chessPieces = ['rook', 'knight', 'bishop', 'queen', 'king', 'pawn'];
const shogiPieces = ['rook', 'knight', 'bishop', 'king', 'pawn', 'lance', 'gold general', 'silver general'];

for (const commonPiece of set.intersection(chessPieces, shogiPieces)) {
    console.log(commonPiece);
}
// rook, knight, bishop, king, pawn
```

### Partial Intersection
Iterates [M-partial intersection](https://github.com/Smoren/partial-intersection-php) of iterables.

```
function* partialIntersection<T>(
  minIntersectionCount: number,
  ...iterables: Array<Iterable<T> | Iterator<T>>
): Iterable<T>
```

* Always treats different instances of objects and arrays as unequal.
* If input iterables produce duplicate items, then [multiset](https://en.wikipedia.org/wiki/Multiset) intersection rules apply.

```typescript
import { set } from '@osjwnpm/nesciunt-voluptatem-quo';

const staticallyTyped    = ['c++', 'java', 'c#', 'go', 'haskell'];
const dynamicallyTyped   = ['php', 'python', 'javascript', 'typescript'];
const supportsInterfaces = ['php', 'java', 'c#', 'typescript'];

for (const language of set.partialIntersection(2, staticallyTyped, dynamicallyTyped, supportsInterfaces)) {
    console.log(language);
}
// c++, java, c#, go, php
```

### Symmetric difference
Iterates the symmetric difference of iterables.

```
function* symmetricDifference<T>(
  ...iterables: Array<Iterable<T> | Iterator<T>>
): Iterable<T>
```

* Always treats different instances of objects and arrays as unequal.
* If input iterables produce duplicate items, then [multiset](https://en.wikipedia.org/wiki/Multiset) difference rules apply.

```typescript
import { set } from '@osjwnpm/nesciunt-voluptatem-quo';

const a = [2, 3, 4, 7];
const b = [2, 3, 5, 8];
const c = [2, 3, 6, 9];

for (const item of set.symmetricDifference(a, b, c)) {
  console.log(item);
}
// 4, 5, 6, 7, 8, 9
```

### Union
Iterates the union of iterables.

```
function* union<T>(...iterables: Array<Iterable<T> | Iterator<T>>): Iterable<T>
```

* Always treats different instances of objects and arrays as unequal.
* If input iterables produce duplicate items, then [multiset](https://en.wikipedia.org/wiki/Multiset) difference rules apply.

```typescript
import { set } from '@osjwnpm/nesciunt-voluptatem-quo';

const a = [1, 2, 3];
const b = [2, 3, 4];
const c = [3, 4, 5];

for (const item of set.symmetricDifference(a, b, c)) {
    console.log(item);
}
// 1, 2, 3, 4, 5
```

## Summary
### All Match
Returns true if all elements match the predicate function.

```
function allMatch<T>(
  data: Iterable<T> | Iterator<T>,
  predicate: (item: T) => boolean
): boolean
```

Empty collections return true.

```typescript
import { summary } from "@osjwnpm/nesciunt-voluptatem-quo";

const finalFantasyNumbers = [4, 5, 6];
const isOnSuperNintendo   = (ff) => ff >= 4 && ff <= 6;

const trueResult = summary.allMatch(finalFantasyNumbers, isOnSuperNintendo);
// true

const isOnPlaystation = (ff) => ff >= 7 && ff <= 9;

const falseResult = summary.allMatch(finalFantasyNumbers, isOnPlaystation);
// false
```

### All Unique
Return true if all elements in given collection are unique.

```
function allUnique(data: Iterable<unknown> | Iterator<unknown>): boolean
```

Empty collections return true.

Considers different instances of data containers to be different, even if they have the same content.

```typescript
import { summary } from "@osjwnpm/nesciunt-voluptatem-quo";

const uniqueNumbers = [1, 2, 3, 4, 5];
summary.allUnique(uniqueNumbers);
// true

const notUniqueNumbers = [1, 1, 2, 2, 3];
summary.allUnique(notUniqueNumbers);
// false
```