iterators/README.md

# typescript/iterators

[![Build Status](https://thunderk.visualstudio.com/typescript/_apis/build/status/iterators?branchName=master)](https://dev.azure.com/thunderk/typescript/_build?pipelineNameFilter=iterators)

## About

Lazy iterators to work on dynamic data sets without materializing them.

They allow to work on infinite streams of values, with limited memory
consumption.

Functions in this library that do not return an Iterable are "materializing",
meaning that they may consume iterators up to the end, and will not work well on
infinite iterators (a limit is often provided to break out).

These iterators are guaranteed to be repeatable, meaning that calling
Symbol.iterator on them will start over.

## Import

In deno:

```typescript
import { iarray, isum } from "https://js.thunderk.net/iterators/mod.ts";
```

In browser:

```html
<script type="module">
import { iarray, isum } from "https://js.thunderk.net/iterators/mod.js";
</script>
```

## Use

Examples (edge cases can be found in each function's documentation):

```typescript
// Create iterables
const i1 = iarray([1, 2, 3]); // 1 2 3
const i2 = isingle(4); // 4
const i3 = irecur(0, (x) => x - 1); // 0 -1 -2 -3 -4 ...
const i4 = irange(5); // 0 1 2 3 4
const i5 = irange(5, 1, 2); // 1 3 5 7 9
const i6 = istep(4, iarray([1, 10, 1, -1])); // 4 5 15 16 15
const i7 = irepeat(2); // 2 2 2 2 2 ...

// Consume iterables
iforeach(i1, console.log);
ifirst(i6); // 4
ifirstmap(i1, (x) => x > 1 ? -x : null); // -2
imaterialize(i1); // [1, 2, 3]
ilength(i1); // 3
iat(i5, 3); // 7
ireduce(i1, (a, b) => a + b, 0); // 6
isum(i1); // 6
icat(iarray(["a", "b", "c"])); // abc
imin(i1); // 1
imax(i1); // 3

// Transform iterables
iloop(i1); // 1 2 3 1 2 3 ...
iskip(i3, 2); // -2 -3 -4 -5 -6 ...
imap(i1, (x) => x * 2); // 2 4 6
ifilter(i3, (x) => x % 4 == 0); // 0 -4 -8 -12 ...
imapfilter(i1, (x) => x != 4 ? x * 2 : null); // 2 6
ipartition(i3, (x) => x % 4 == 0); // [0 -4 -8 ..., -1 -2 -3 -5 ...]
iunique(iarray([1, 4, 2, 4, 3, 1, 5])); // 1 4 2 3 5

// Combine iterables
ichain(i1, i2); // 1 2 3 4
ichainit(iarray([i1, i2])); // 1 2 3 4
icombine(iarray([0, 1]), iarray(["a", "b"])); // [0, "a"] [0, "b"] [1, "a"] [2, "b"]
izip(iarray([0, 1]), iarray(["a", "b"])); // [0, "a"] [1, "b"]
ialternate(iarray([0, 1]), iarray(["a", "b"])); // 0 "a" 1 "b"

// Type filter (result is a typed iterable)
ifiltertype(iarray([1, "a", 2, "b"]), (x): x is number => typeof x == "number"); // 1 2
class A {}
class B {}
ifilterclass(iarray([new A(), new B(), new A()]), A); // A A
```