Iterables Reference

Coverage License NPM Version Open Issues

🔁 Iterable and AsyncIterable utils.

Usage

By default, all utils are meant to be used with Iterable values, to use AsyncIterable values the functions have to be imported from @lou.codes/iterables/asynchronous.

📦 Node

Install @lou.codes/iterables as a dependency:

1
pnpm add @lou.codes/iterables
2
# or
3
npm install @lou.codes/iterables
4
# or
5
yarn add @lou.codes/iterables

Import it and use it:

1
import { iterableToArray, map } from "@lou.codes/iterables";
2

3
const mapDouble = map((value: number) => value * 2);
4

5
iterableToArray(mapDouble([1, 2, 3])); // [2, 4, 6]

🦕 Deno

Import @lou.codes/iterables using the npm: prefix, and use it directly:

1
import { iterableToArray, map } from "npm:@lou.codes/iterables";
2

3
const mapDouble = map((value: number) => value * 2);
4

5
iterableToArray(mapDouble([1, 2, 3])); // [2, 4, 6]

🌎 Browser

Import @lou.codes/iterables using esm.sh, and use it directly:

1
<script type="module">
2
	import { iterableToArray, map } from "https://esm.sh/@lou.codes/iterables";
3

4
	const mapDouble = map(value => value * 2);
5

6
	iterableToArray(mapDouble([1, 2, 3])); // [2, 4, 6]
7
</script>

Useful links

📝 Documentation: TypeDoc generated documentation.
⏳ Changelog: List of changes between versions.
✅ Tests Coverage: Coveralls page with tests coverage.

Asynchronous

Asynchronous Common

createIterableIterator()

1
function createIterableIterator<GeneratorFunction>(
2
	generatorFunction: GeneratorFunction,
3
): GeneratorFunction extends () => IsomorphicIterator<Item> ?
4
	Readonly<
5
		GeneratorFunction<GeneratorFunction> extends (
6
			(..._arguments: _Arguments) => AsyncIterator<Item, any, any>
7
		) ?
8
			AsyncIterableIterator<Item, any, any>
9
		:	IterableIterator<Item, any, any>
10
	>
11
:	never;

Takes a generator function and returns an iterable iterator or asynchronous iterable iterator object.

Type parameters

Type parameter
`GeneratorFunction` extends () => `IsomorphicIterator`

Parameters

Parameter	Type	Description
`generatorFunction`	`GeneratorFunction`	Generator to be used every time `[Symbol.iterator]` is called.

Returns

GeneratorFunction extends () => IsomorphicIterator<Item> ? Readonly<GeneratorFunction<GeneratorFunction> extends (…_arguments: _Arguments) => AsyncIterator<Item, any, any> ? AsyncIterableIterator<Item, any, any> : IterableIterator<Item, any, any>> : never

Iterable iterator object.

Example

1
const identityGenerator = function* (value) {
2
	yield value;
3
};
4
const iterableIterator = createIterableIterator(identityGenerator);
5

6
const fooIdentity = iterableIterator("foo");
7

8
for (const value of fooIdentity) {
9
	console.log(value); // "foo"
10
}
11

12
// Same IterableIterator as above, return values again:
13

14
for (const value of fooIdentity) {
15
	console.log(value); // "foo"
16
}

forEach()

1
function forEach<Item>(
2
	callback: Unary<Item, Awaitable<void>>,
3
): (iterable: IsomorphicIterable<Item>) => Promise<void>;

For each function for iterables and asynchronous iterables.

Type parameters

Type parameter
`Item`

Parameters

Parameter	Type	Description
`callback`	`Unary`<`Item`, `Awaitable`<`void`>>	Function to be called for every item of the iterable.

Returns

Function

Curried function that expects an iterable to loop over and has callback set in context.

Parameters

Parameter	Type
`iterable`	`IsomorphicIterable`<`Item`>

Returns

Promise<void>

Example

1
const logEach = forEach(console.log);
2

3
logEach([1, 2, 3]); // Logs 1, 2 and 3 separately

Asynchronous Generators

append()

1
function append<TailItem>(
2
	tailIterable: IsomorphicIterable<TailItem>,
3
): <InitialItem>(
4
	initialIterable: IsomorphicIterable<InitialItem>,
5
) => Readonly<
6
	AsyncIterableIterator<Awaited<InitialItem> | Awaited<TailItem>, any, any>
7
>;

Appends one iterable or asynchronous iterable to another.

Type parameters

Type parameter
`TailItem`

Parameters

Parameter	Type	Description
`tailIterable`	`IsomorphicIterable`<`TailItem`>	Iterable or asynchronous to be appended.

Returns

Function

Curried generator function with tailIterable set in context.

Type parameters

Type parameter
`InitialItem`

Parameters

Parameter	Type
`initialIterable`	`IsomorphicIterable`<`InitialItem`>

Returns

Readonly<AsyncIterableIterator<Awaited<InitialItem> | Awaited<TailItem>, any, any>>

Example

1
const appendNumbers = append([0, 1, 2, 3, 4]);
2

3
appendNumbers(["foo", "bar"]); // ["foo", "bar", 0, 1, 2, 3, 4]
4
appendNumbers([]); // [0, 1, 2, 3, 4]

drop()

1
function drop(
2
	amount: Numeric,
3
): <Item>(
4
	iterable: IsomorphicIterable<Item>,
5
) => Readonly<AsyncIterableIterator<Awaited<Item>, any, any>>;

Drop the specified amount of items from the given iterable or asynchronous iterable.

Parameters

Parameter	Type	Description
`amount`	`Numeric`	Amount of items to drop.

Returns

Function

Curried function with amount in context.

Type parameters

Type parameter
`Item`

Parameters

Parameter	Type
`iterable`	`IsomorphicIterable`<`Item`>

Returns

Readonly<AsyncIterableIterator<Awaited<Item>, any, any>>

Example

1
const drop2 = drop(2);
2
drop2([1, 2, 3, 4, 5]); // [3, 4, 5]

filter()

1
function filter<Item, Filtered>(
2
	predicate: Single<Filtered> extends Single<never> ? Unary<Item, boolean>
3
	:	Predicate<Item, Filtered>,
4
): (
5
	iterable: IsomorphicIterable<Item>,
6
) => Readonly<AsyncIterableIterator<Awaited<Filtered>, any, any>>;

Filters items in an iterable or asynchronous iterable against a predicate and returns items that evaluated to true.

Type parameters

Type parameter	Value
`Item`	-
`Filtered`	`never`

Parameters

Parameter	Type	Description
`predicate`	`Single`<`Filtered`> extends `Single`<`never`> ? `Unary`<`Item`, `boolean`> : `Predicate`<`Item`, `Filtered`>	Predicate function to evaluate each item.

Returns

Function

Curried function with predicate set in context.

Parameters

Parameter	Type
`iterable`	`IsomorphicIterable`<`Item`>

Returns

Readonly<AsyncIterableIterator<Awaited<Filtered>, any, any>>

Example

1
const filterEven = filter((number: number) => number % 2 === 0);
2

3
iterableToArray(filterEven([1, 2, 3, 4])); // [2, 4]
4
iterableToArray(filterEven([1, 3, 5, 7])); // []

flat()

1
function flat<Iterable>(
2
	iterable: Iterable,
3
): Iterable extends IsomorphicIterable<Item> ?
4
	Readonly<
5
		Item extends IsomorphicIterable<SubItem> ?
6
			AsyncIterableIterator<SubItem, any, any>
7
		:	AsyncIterableIterator<Item, any, any>
8
	>
9
:	never;

Flattens one level of the given iterable or asynchronous iterable.

Type parameters

Type parameter
`Iterable` extends `IsomorphicIterable`

Parameters

Parameter	Type	Description
`iterable`	`Iterable`	Iterable to flatten.

Returns

Iterable extends IsomorphicIterable<Item> ? Readonly<Item extends IsomorphicIterable<SubItem> ? AsyncIterableIterator<SubItem, any, any> : AsyncIterableIterator<Item, any, any>> : never

Iterable with flatten items.

Example

1
flat([1, 2, [3, 4]]); // [1, 2, 3, 4]

initial()

1
function initial<Iterable>(
2
	iterable: Iterable,
3
): IsomorphicIterableIterator<IsomorphicIterableItem<Iterable>>;

Get all elements except the last one of an iterable or asynchronous iterable.

Type parameters

Type parameter
`Iterable` extends `IsomorphicIterable`

Parameters

Parameter	Type	Description
`iterable`	`Iterable`	Iterable to get the items from.

Returns

IsomorphicIterableIterator<IsomorphicIterableItem<Iterable>>

Iterable with all items except the last one.

Example

1
initial([1, 2, 3]); // [1, 2]

intersperse()

1
function intersperse<Separator>(
2
	separator: Separator,
3
): <Item>(
4
	iterable: IsomorphicIterable<Item>,
5
) => IsomorphicIterableIterator<Item | Awaited<Separator> | Awaited<Item>>;

Add the given separator between each element of the given iterable or asynchronous iterable.

Type parameters

Type parameter
`Separator`

Parameters

Parameter	Type	Description
`separator`	`Separator`	Separator to add between each element.

Returns

Function

Curried function with separator in context.

Type parameters

Type parameter
`Item`

Parameters

Parameter	Type
`iterable`	`IsomorphicIterable`<`Item`>

Returns

IsomorphicIterableIterator<Item | Awaited<Separator> | Awaited<Item>>

Example

1
const intersperseComma = intersperse(",");
2
intersperseComma([1, 2, 3]); // [1, ",", 2, ",", 3]

map()

1
function map<Item, MappedItem>(
2
	mapper: Unary<Item, MappedItem>,
3
): (
4
	iterable: IsomorphicIterable<Item>,
5
) => Readonly<AsyncIterableIterator<Awaited<MappedItem>, any, any>>;

Map for iterables and asynchronous iterables.

Type parameters

Type parameter
`Item`
`MappedItem`

Parameters

Parameter	Type	Description
`mapper`	`Unary`<`Item`, `MappedItem`>	Mapper function.

Returns

Function

Generator function with mapper function set in context.

Parameters

Parameter	Type
`iterable`	`IsomorphicIterable`<`Item`>

Returns

Readonly<AsyncIterableIterator<Awaited<MappedItem>, any, any>>

Example

1
const double = value => value * 2;
2
const mapDouble = map(double);
3

4
mapDouble([1, 2, 3]); // [2, 4, 6]

objectToEntries()

1
function objectToEntries<Key, Value>(
2
	input: Readonly<Record<Key, Value>>,
3
): Readonly<AsyncIterableIterator<Entry<Key, Value>, any, any>>;

Yields all entries of an object (including symbols).

Type parameters

Type parameter
`Key` extends `PropertyKey`
`Value`

Parameters

Parameter	Type	Description
`input`	`Readonly`<`Record`<`Key`, `Value`>>	Object to get entries from.

Returns

Readonly<AsyncIterableIterator<Entry<Key, Value>, any, any>>

Iterable with entries of the given object (including symbols).

Example

1
const entries = objectEntries({ a: 1, b: 2 });
2
entries.next(); // { value: ["a", 1], done: false }
3
entries.next(); // { value: ["b", 2], done: false }
4
entries.next(); // { value: undefined, done: true }

prepend()

1
function prepend<InitialItem>(
2
	initialIterable: IsomorphicIterable<InitialItem>,
3
): <TailItem>(
4
	tailIterable: IsomorphicIterable<TailItem>,
5
) => Readonly<
6
	AsyncIterableIterator<Awaited<InitialItem> | Awaited<TailItem>, any, any>
7
>;

Prepends one iterable or asynchronous iterable to another.

Type parameters

Type parameter
`InitialItem`

Parameters

Parameter	Type	Description
`initialIterable`	`IsomorphicIterable`<`InitialItem`>	Iterable or asynchronous iterable to be appended.

Returns

Function

Curried generator function with initialIterable set in context.

Type parameters

Type parameter
`TailItem`

Parameters

Parameter	Type
`tailIterable`	`IsomorphicIterable`<`TailItem`>

Returns

Readonly<AsyncIterableIterator<Awaited<InitialItem> | Awaited<TailItem>, any, any>>

Example

1
const prependNumbers = prepend([0, 1, 2, 3, 4]);
2
prependNumbers(["foo", "bar"]); // [0, 1, 2, 3, 4, "foo", "bar"]

random()

1
function random(
2
	seed: string | Numeric,
3
): (
4
	from: number,
5
) => (to: number) => Readonly<AsyncIterableIterator<number, any, any>>;

Deterministic pseudo-random number generator.

⚠️ IMPORTANT: This only works in secure contexts (HTTPS/Node).

Parameters

Parameter	Type	Description
`seed`	`string` \| `Numeric`	Seed to be used to generate random numbers.

Returns

Function

Curried generator function with seed set in context.

Parameters

Parameter	Type
`from`	`number`

Returns

Function

Parameters

Parameter	Type
`to`	`number`

Returns

Readonly<AsyncIterableIterator<number, any, any>>

Example

1
const seededRandom = random("some seed");
2
const random0To10 = seededRandom(0)(10);
3

4
[...pick(2)(random0To10)]; // Two "random" values between 0 and 10
5
[...pick(2)(random0To10)]; // Same two "random" values between 0 and 10

See

range()

1
function range<Step>(
2
	step: Step,
3
): (
4
	from: Step extends bigint ? bigint : number,
5
) => (
6
	to: Step extends bigint ? bigint : number,
7
) => Readonly<
8
	AsyncIterableIterator<Step extends bigint ? bigint : number, any, any>
9
>;

Range iterable generator (from from to to).

Type parameters

Type parameter
`Step` extends `Numeric`

Parameters

Parameter	Type	Description
`step`	`Step`	Step size.

Returns

Function

Curried function with step set in context.

Parameters

Parameter	Type
`from`	`Step` extends `bigint` ? `bigint` : `number`

Returns

Function

Parameters

Parameter	Type
`to`	`Step` extends `bigint` ? `bigint` : `number`

Returns

Readonly<AsyncIterableIterator<Step extends bigint ? bigint : number, any, any>>

Example

1
[...range(1)(0)(5)]; // [0, 1, 2, 3, 4, 5]
2
[...range(1)(5)(0)]; // [5, 4, 3, 2, 1, 0]

repeat()

1
function repeat(
2
	times: Numeric,
3
): <Item>(
4
	item: Item,
5
) => Readonly<AsyncIterableIterator<Awaited<Item>, any, any>>;

Repeat given item the specified amount of times (can be BigInt or Infinity times) as an iterable.

Parameters

Parameter	Type
`times`	`Numeric`

Returns

Function

Curried function with item in context.

Type parameters

Type parameter
`Item`

Parameters

Parameter	Type
`item`	`Item`

Returns

Readonly<AsyncIterableIterator<Awaited<Item>, any, any>>

Example

1
const repeat3Times = repeat(3);
2
repeat3Times("foo"); // ["foo", "foo", "foo"]

take()

1
function take(
2
	amount: Numeric,
3
): <Item>(
4
	iterable: IsomorphicIterable<Item>,
5
) => Readonly<AsyncIterableIterator<Awaited<Item>, any, any>>;

Take the given amount of items from the iterable or asynchronous iterable.

Parameters

Parameter	Type	Description
`amount`	`Numeric`	Amount of items to take.

Returns

Function

Curried function with amount in context.

Type parameters

Type parameter
`Item`

Parameters

Parameter	Type
`iterable`	`IsomorphicIterable`<`Item`>

Returns

Readonly<AsyncIterableIterator<Awaited<Item>, any, any>>

Example

1
const take2 = take(2);
2
take2([1, 2, 3, 4, 5]); // [1, 2]

toIterable()

1
function toIterable<ValueOrAsyncIterable>(
2
	valueOrIterable: ValueOrAsyncIterable,
3
): Readonly<
4
	AsyncIterableIterator<
5
		ValueOrAsyncIterable extends IsomorphicIterable ?
6
			IsomorphicIterableItem<ValueOrAsyncIterable<ValueOrAsyncIterable>>
7
		:	ValueOrAsyncIterable,
8
		any,
9
		any
10
	>
11
>;

Takes a value, iterable or asynchronous iterable and yields it.

Type parameters

Type parameter
`ValueOrAsyncIterable`

Parameters

Parameter	Type	Description
`valueOrIterable`	`ValueOrAsyncIterable`	Vale or iterable to yield.

Returns

Readonly<AsyncIterableIterator<ValueOrAsyncIterable extends IsomorphicIterable ? IsomorphicIterableItem<ValueOrAsyncIterable<ValueOrAsyncIterable>> : ValueOrAsyncIterable, any, any>>

Yielded item or iterable.

Example

1
const iterable = toIterable(1);
2
const iterator = getIterator(iterable);
3
iterator.next(); // { value: 1, done: false }
4
iterator.next(); // { value: undefined, done: true }

See

createIterableIterator

unique()

1
function unique<Item>(
2
	iterable: IsomorphicIterable<Item>,
3
): Readonly<AsyncIterableIterator<Awaited<Item>, any, any>>;

Returns a single instance of each item in the iterable or asynchronous iterable.

Type parameters

Type parameter
`Item`

Parameters

Parameter	Type	Description
`iterable`	`IsomorphicIterable`<`Item`>	Iterable to be filtered.

Returns

Readonly<AsyncIterableIterator<Awaited<Item>, any, any>>

Generators with a single instance of each item of the iterable.

Example

1
unique([1, 2, 3, 4, 1, 2, 3, 4]); // [1, 2, 3, 4]

zip()

1
function zip<ItemFirst>(
2
	iterableFirst: IsomorphicIterable<ItemFirst>,
3
): <ItemSecond>(
4
	iterableSecond: IsomorphicIterable<ItemSecond>,
5
) => Readonly<
6
	AsyncIterableIterator<
7
		readonly [ItemFirst | Awaited<ItemFirst>, ItemSecond],
8
		any,
9
		any
10
	>
11
>;

Takes two iterables or asynchronous iterable and returns a new iterable or asynchronous iterable with the length of the shortest iterable with tuples containing the items from both.

Type parameters

Type parameter
`ItemFirst`

Parameters

Parameter	Type	Description
`iterableFirst`	`IsomorphicIterable`<`ItemFirst`>	One of the iterables to be zipped.

Returns

Function

Curried function with iterableFirst in context.

Type parameters

Type parameter
`ItemSecond`

Parameters

Parameter	Type
`iterableSecond`	`IsomorphicIterable`<`ItemSecond`>

Returns

Readonly<AsyncIterableIterator<readonly [ItemFirst | Awaited<ItemFirst>, ItemSecond], any, any>>

Example

1
const zipNumbers = zip([0, 1, 2]);
2
zipNumbers([3, 4, 5]); // [[0, 3], [1, 4], [2, 5]]

zipIndex()

1
function zipIndex<ItemSecond>(
2
	iterableSecond: IsomorphicIterable<ItemSecond>,
3
): Readonly<AsyncIterableIterator<readonly [number, ItemSecond], any, any>>;

Yields a tuple for each item in the iterable with the index of said item.

Type parameters

Type parameter
`ItemSecond`

Parameters

Parameter	Type
`iterableSecond`	`IsomorphicIterable`<`ItemSecond`>

Returns

Readonly<AsyncIterableIterator<readonly [number, ItemSecond], any, any>>

Example

1
zipIndex(["foo", "bar"]); // [[0, "foo"], [1, "bar"]]

Yields

Tuples with the index of each item.

Asynchronous Reducers

count()

1
function count<Item>(
2
	predicate: Filter<Item>,
3
): (iterable: IsomorphicIterable<Item>) => Promise<number>;

Counts the number of items that satisfy a predicate in the given iterable or asynchronous iterable.

Type parameters

Type parameter
`Item`

Parameters

Parameter	Type	Description
`predicate`	`Filter`<`Item`>	Predicate function for items to be counted.

Returns

Function

Curried function with predicate in context.

Parameters

Parameter	Type
`iterable`	`IsomorphicIterable`<`Item`>

Returns

Promise<number>

Example

1
const countOdds = count((number: number) => number % 2 !== 1);
2
countOdds([1, 2, 3, 4, 5]); // 3
3
countOdds([0, 2, 4, 6, 8]); // 0

entriesToObject()

1
function entriesToObject<Item>(
2
	iterable: IsomorphicIterable<Item>,
3
): Promise<Readonly<Record<EntryKey<Item>, EntryValue<Item>>>>;

Takes an entries iterable or asynchronous iterable and returns an object.

Type parameters

Type parameter
`Item` extends `Entry`

Parameters

Parameter	Type
`iterable`	`IsomorphicIterable`<`Item`>

Returns

Promise<Readonly<Record<EntryKey<Item>, EntryValue<Item>>>>

Object constructed from entries.

Example

1
entriesToObject([["key", "value"]]); // { key: "value" }
2
entriesToObject([
3
	["foo", "bar"],
4
	["number", 1],
5
]); // { foo: "bar", number: 1 }

every()

1
function every<Item, Predicated>(
2
	predicate: Single<Predicated> extends Single<never> ? Unary<Item, boolean>
3
	:	Predicate<Item, Predicated>,
4
): (iterable: IsomorphicIterable<Item>) => Promise<boolean>;

Evaluates items in an iterable or asynchronous iterable against a predicate and returns true if all items evaluates to true.

Type parameters

Type parameter	Value
`Item`	-
`Predicated`	`never`

Parameters

Parameter	Type	Description
`predicate`	`Single`<`Predicated`> extends `Single`<`never`> ? `Unary`<`Item`, `boolean`> : `Predicate`<`Item`, `Predicated`>	Predicate function to evaluate each item.

Returns

Function

Curried function with predicate set in context.

Parameters

Parameter	Type
`iterable`	`IsomorphicIterable`<`Item`>

Returns

Promise<boolean>

Example

1
const everyEven = every((number: number) => number % 2 === 0);
2
everyEven([2, 4, 6, 8]); // true
3
everyEven([1, 2, 3, 4]); // false

find()

1
function find<Item>(
2
	predicate: Unary<Item, boolean>,
3
): (iterable: IsomorphicIterable<Item>) => Promise<Maybe<Item>>;

Returns the value of the first item in the iterable or asynchronous iterable where predicate is true, undefined otherwise.

Type parameters

Type parameter
`Item`

Parameters

Parameter	Type	Description
`predicate`	`Unary`<`Item`, `boolean`>	Predicate function to search for item.

Returns

Function

Curried function with predicate set in context.

Parameters

Parameter	Type
`iterable`	`IsomorphicIterable`<`Item`>

Returns

Promise<Maybe<Item>>

Example

1
const findEven = find((number: number) => number % 2 === 0);
2
findEven([1, 2, 3, 4]); // 2
3
findEven([1, 3, 5, 7]); // undefined

groupBy()

1
function groupBy<Item, Key>(
2
	grouper: Unary<Item, Key>,
3
): <Iterable>(
4
	iterable: Iterable,
5
) => Iterable extends AsyncIterable<unknown, any, any> ?
6
	Promise<Readonly<Record<Key, ReadOnlyArray<Item>>>>
7
:	Readonly<Record<Key, ReadOnlyArray<Item>>>;

Groups values of an iterable or asynchronous iterable in an object based on the output of the grouper function.

Type parameters

Type parameter
`Item`
`Key` extends `PropertyKey`

Parameters

Parameter	Type	Description
`grouper`	`Unary`<`Item`, `Key`>	Grouper function.

Returns

Function

Object with grouped values.

Type parameters

Type parameter
`Iterable` extends `IsomorphicIterable`<`Item`>

Parameters

Parameter	Type
`iterable`	`Iterable`

Returns

Iterable extends AsyncIterable<unknown, any, any> ? Promise<Readonly<Record<Key, ReadOnlyArray<Item>>>> : Readonly<Record<Key, ReadOnlyArray<Item>>>

Example

1
const groupByType = groupBy((value: number) =>
2
	number % 2 === 0 ? "even" : "odd",
3
);
4
groupByType([1, 2, 3, 4, 5]); // { even: [2, 4], odd: [1, 3, 5] }

head()

1
function head<Iterable>(
2
	iterable: Iterable,
3
): Iterable extends ReadOnlyArray ? Head<Iterable<Iterable>>
4
:	Maybe<IsomorphicIterableItem<Iterable>>;

Get first element of an iterable or asynchronous iterable (undefined if it is empty).

Type parameters

Type parameter
`Iterable` extends `IsomorphicIterable`

Parameters

Parameter	Type	Description
`iterable`	`Iterable`	Iterable to get the first element from.

Returns

Iterable extends ReadOnlyArray ? Head<Iterable<Iterable>> : Maybe<IsomorphicIterableItem<Iterable>>

First element of the iterable (undefined if empty).

Example

1
head([1, 2, 3]); // 1

includes()

1
function includes<SearchItem>(
2
	searchItem: SearchItem,
3
): (iterable: IsomorphicIterable<unknown>) => Promise<boolean>;

Tries to find the given searchItem in iterable or asynchronous iterable.

Type parameters

Type parameter
`SearchItem`

Parameters

Parameter	Type	Description
`searchItem`	`SearchItem`	Item to search.

Returns

Function

Curried function with searchItem set in context.

Parameters

Parameter	Type
`iterable`	`IsomorphicIterable`<`unknown`>

Returns

Promise<boolean>

Example

1
const includesTwo = includes(2);
2
includesTwo([1, 2, 3, 4]); // true
3
includesTwo([1, 3, 5, 7]); // false

iterableToArray()

1
function iterableToArray<Iterable>(
2
	iterable: Iterable,
3
): Promise<ReadOnlyArray<IsomorphicIterableItem<Iterable>>>;

Turns given iterable or asynchronous iterable into an array.

Type parameters

Type parameter
`Iterable` extends `IsomorphicIterable`

Parameters

Parameter	Type	Description
`iterable`	`Iterable`	Iterable to be turned into an array.

Returns

Promise<ReadOnlyArray<IsomorphicIterableItem<Iterable>>>

Array made of iterable items.

Example

1
iterableToArray([1, 2, 3, 4]); // [1, 2, 3, 4]

join()

1
function join<Separator>(
2
	separator: Separator,
3
): <Iterable>(
4
	iterable: Iterable,
5
) => Iterable extends AsyncIterable<unknown, any, any> ?
6
	Promise<`${string}${Separator}${string}`>
7
:	`${string}${Separator}${string}`;

Takes a separator string and a iterable or asynchronous iterable and returns a string with the concatenation of all the elements separated by the separator.

Type parameters

Type parameter
`Separator` extends `string`

Parameters

Parameter	Type	Description
`separator`	`Separator`	String to use as separator.

Returns

Function

Curried function with separator in context.

Type parameters

Type parameter
`Iterable` extends `IsomorphicIterable`

Parameters

Parameter	Type
`iterable`	`Iterable`

Returns

Iterable extends AsyncIterable<unknown, any, any> ? Promise<`${string}${Separator}${string}`> : `${string}${Separator}${string}`

Example

1
const joinWithSpaces = join(" ");
2
joinWithSpaces([1, 2, 3]); // "1 2 3"

length()

1
function length<Iterable>(
2
	iterable: Iterable,
3
): Iterable extends AsyncIterable<unknown, any, any> ? Promise<number> : number;

Get the length of an iterable or asynchronous iterable.

Type parameters

Type parameter
`Iterable` extends `IsomorphicIterable`<`unknown`>

Parameters

Parameter	Type	Description
`iterable`	`Iterable`	Iterable or asynchronous iterable to get the length from.

Returns

Iterable extends AsyncIterable<unknown, any, any> ? Promise<number> : number

Promise with the length of the iterable.

Example

1
length([1, 2, 3]); // 3

reduce()

1
function reduce<Item, Accumulator>(
2
	reducer: Unary<Item, Unary<Accumulator, Awaitable<Accumulator>>>,
3
): (
4
	initialValue: Accumulator,
5
) => <Iterable>(
6
	iterable: Iterable,
7
) => Iterable extends AsyncIterable<unknown, any, any> ? Promise<Accumulator>
8
:	Accumulator;

Reducer function for iterables and asynchronous iterables.

Type parameters

Type parameter
`Item`
`Accumulator`

Parameters

Parameter	Type	Description
`reducer`	`Unary`<`Item`, `Unary`<`Accumulator`, `Awaitable`<`Accumulator`>>>	Reducer function.

Returns

Function

Curried function with reducer in context.

Parameters

Parameter	Type
`initialValue`	`Accumulator`

Returns

Function

Type parameters

Type parameter
`Iterable` extends `IsomorphicIterable`<`Item`>

Parameters

Parameter	Type
`iterable`	`Iterable`

Returns

Iterable extends AsyncIterable<unknown, any, any> ? Promise<Accumulator> : Accumulator

Example

1
const sum = Accumulator<number>(item => total => total + item);
2
const sumFrom0 = sum(0);
3

4
sumFrom0([1, 2, 3]); // 6

some()

1
function some<Item, Predicated>(
2
	predicate: Single<Predicated> extends Single<never> ? Unary<Item, boolean>
3
	:	Predicate<Item, Predicated>,
4
): (iterable: IsomorphicIterable<Item>) => Promise<boolean>;

Evaluates items in an iterable or asynchronous iterable against a predicate and returns true if any item evaluates to true.

Type parameters

Type parameter	Value
`Item`	-
`Predicated`	`never`

Parameters

Parameter	Type	Description
`predicate`	`Single`<`Predicated`> extends `Single`<`never`> ? `Unary`<`Item`, `boolean`> : `Predicate`<`Item`, `Predicated`>	Predicate function to evaluate each item.

Returns

Function

Curried function with predicate set in context.

Parameters

Parameter	Type
`iterable`	`IsomorphicIterable`<`Item`>

Returns

Promise<boolean>

Example

1
const someEven = some((number: number) => number % 2 === 0);
2
someEven([1, 2, 3, 4]); // true
3
someEven([1, 3, 5, 7]); // false

Internal

setAsyncIterator()

1
function setAsyncIterator<Value>(
2
	value: Value,
3
): <Source>(
4
	object: Source,
5
) => Omit<Source, typeof asyncIterator> &
6
	Readonly<Record<typeof asyncIterator, Value>>;

Set Symbol.asyncIterator to the given value to the given object.

Type parameters

Type parameter
`Value`

Parameters

Parameter	Type
`value`	`Value`

Returns

Function

Curried function with key in context.

Type parameters

Type parameter
`Source` extends `object`

Parameters

Parameter	Type
`object`	`Source`

Returns

Omit<Source, typeof asyncIterator> & Readonly<Record<typeof asyncIterator, Value>>

Example

1
setAsyncIterator("🟢")({ foo: "bar" }); // { [Symbol.asyncIterator]: "🟢", foo: "bar" }

Synchronous

Common

createIterableIterator()

1
function createIterableIterator<Item>(
2
	generatorFunction: () => Readonly<Iterator<Item, void, void>>,
3
): Readonly<IterableIterator<Item, any, any>>;

Takes a generator function and returns an iterable iterator object.

Type parameters

Type parameter
`Item`

Parameters

Parameter	Type	Description
`generatorFunction`	() => `Readonly`<`Iterator`<`Item`, `void`, `void`>>	Generator to be used every time `[Symbol.iterator]` is called.

Returns

Readonly<IterableIterator<Item, any, any>>

Iterable iterator object.

Example

1
const identityGenerator = function* (value) {
2
	yield value;
3
};
4
const iterableIterator = createIterableIterator(identityGenerator);
5

6
const fooIdentity = iterableIterator("foo");
7

8
for (const value of fooIdentity) {
9
	console.log(value); // "foo"
10
}
11

12
// Same IterableIterator as above, return values again:
13

14
for (const value of fooIdentity) {
15
	console.log(value); // "foo"
16
}

forEach()

1
function forEach<Item>(
2
	callback: Unary<Item, void>,
3
): (iterable: Readonly<Iterable<Item, any, any>>) => void;

For each function for iterables.

Type parameters

Type parameter
`Item`

Parameters

Parameter	Type	Description
`callback`	`Unary`<`Item`, `void`>	Function to be called for every item of the iterable.

Returns

Function

Curried function that expects an iterable to loop over and has callback set in context.

Parameters

Parameter	Type
`iterable`	`Readonly`<`Iterable`<`Item`, `any`, `any`>>

Returns

void

Example

1
const logEach = forEach(console.log);
2

3
logEach([1, 2, 3]); // Logs 1, 2 and 3 separately

Generators

append()

1
function append<TailItem>(
2
	tailIterable: Readonly<Iterable<TailItem, any, any>>,
3
): <InitialItem>(
4
	initialIterable: Readonly<Iterable<InitialItem, any, any>>,
5
) => Readonly<IterableIterator<TailItem | InitialItem, any, any>>;

Appends one iterable to another.

Type parameters

Type parameter
`TailItem`

Parameters

Parameter	Type	Description
`tailIterable`	`Readonly`<`Iterable`<`TailItem`, `any`, `any`>>	Iterable to be appended.

Returns

Function

Curried generator function with tailIterable set in context.

Type parameters

Type parameter
`InitialItem`

Parameters

Parameter	Type
`initialIterable`	`Readonly`<`Iterable`<`InitialItem`, `any`, `any`>>

Returns

Readonly<IterableIterator<TailItem | InitialItem, any, any>>

Example

1
const appendNumbers = append([0, 1, 2, 3, 4]);
2

3
appendNumbers(["foo", "bar"]); // ["foo", "bar", 0, 1, 2, 3, 4]
4
appendNumbers([]); // [0, 1, 2, 3, 4]

drop()

1
function drop(
2
	amount: Numeric,
3
): <Item>(
4
	iterable: Readonly<Iterable<Item, any, any>>,
5
) => Readonly<IterableIterator<Item, any, any>>;

Drop the specified amount of items from the given iterable.

Parameters

Parameter	Type	Description
`amount`	`Numeric`	Amount of items to drop.

Returns

Function

Curried function with amount in context.

Type parameters

Type parameter
`Item`

Parameters

Parameter	Type
`iterable`	`Readonly`<`Iterable`<`Item`, `any`, `any`>>

Returns

Readonly<IterableIterator<Item, any, any>>

Example

1
const drop2 = drop(2);
2
drop2([1, 2, 3, 4, 5]); // [3, 4, 5]

filter()

1
function filter<Item, Filtered>(
2
	predicate: Single<Filtered> extends Single<never> ? Unary<Item, boolean>
3
	:	Predicate<Item, Filtered>,
4
): (
5
	iterable: Readonly<Iterable<Item, any, any>>,
6
) => Readonly<IterableIterator<Filtered, any, any>>;

Filters items in an iterable against a predicate and returns items that evaluated to true.

Type parameters

Type parameter	Value
`Item`	-
`Filtered`	`never`

Parameters

Parameter	Type	Description
`predicate`	`Single`<`Filtered`> extends `Single`<`never`> ? `Unary`<`Item`, `boolean`> : `Predicate`<`Item`, `Filtered`>	Predicate function to evaluate each item.

Returns

Function

Curried function with predicate set in context.

Parameters

Parameter	Type
`iterable`	`Readonly`<`Iterable`<`Item`, `any`, `any`>>

Returns

Readonly<IterableIterator<Filtered, any, any>>

Example

1
const filterEven = filter((number: number) => number % 2 === 0);
2

3
iterableToArray(filterEven([1, 2, 3, 4])); // [2, 4]
4
iterableToArray(filterEven([1, 3, 5, 7])); // []

flat()

1
function flat<Iterable>(iterable: Iterable): Iterable extends (
2
	Readonly<Iterable<Item, any, any>>
3
) ?
4
	Item extends Readonly<Iterable<SubItem, any, any>> ?
5
		Readonly<IterableIterator<SubItem, any, any>>
6
	:	Readonly<IterableIterator<Item, any, any>>
7
:	never;

Flattens one level of the given iterable.

Type parameters

Type parameter
`Iterable` extends `Readonly`<`Iterable`<`unknown`, `any`, `any`>>

Parameters

Parameter	Type	Description
`iterable`	`Iterable`	Iterable to flatten.

Returns

Iterable extends Readonly<Iterable<Item, any, any>> ? Item extends Readonly<Iterable<SubItem, any, any>> ? Readonly<IterableIterator<SubItem, any, any>> : Readonly<IterableIterator<Item, any, any>> : never

Iterable with flatten items.

Example

1
flat([1, 2, [3, 4]]); // [1, 2, 3, 4]

initial()

1
function initial<Iterable>(
2
	iterable: Iterable,
3
): Readonly<
4
	IterableIterator<
5
		Iterable extends ReadOnlyArray ? Initial<Iterable<Iterable>>[number]
6
		:	IsomorphicIterableItem<Iterable>,
7
		any,
8
		any
9
	>
10
>;

Get all elements except the last one of an iterable.

Type parameters

Type parameter
`Iterable` extends `Readonly`<`Iterable`<`unknown`, `any`, `any`>>

Parameters

Parameter	Type	Description
`iterable`	`Iterable`	Iterable to get the items from.

Returns

Readonly<IterableIterator<Iterable extends ReadOnlyArray ? Initial<Iterable<Iterable>>[number] : IsomorphicIterableItem<Iterable>, any, any>>

Iterable with all items except the last one.

Example

1
initial([1, 2, 3]); // [1, 2]

intersperse()

1
function intersperse<Separator>(
2
	separator: Separator,
3
): <Item>(
4
	iterable: Readonly<Iterable<Item, any, any>>,
5
) => Readonly<IterableIterator<Separator | Item, any, any>>;

Add the given separator between each element of the given iterable.

Type parameters

Type parameter
`Separator`

Parameters

Parameter	Type	Description
`separator`	`Separator`	Separator to add between each element.

Returns

Function

Curried function with separator in context.

Type parameters

Type parameter
`Item`

Parameters

Parameter	Type
`iterable`	`Readonly`<`Iterable`<`Item`, `any`, `any`>>

Returns

Readonly<IterableIterator<Separator | Item, any, any>>

Example

1
const intersperseComma = intersperse(",");
2
intersperseComma([1, 2, 3]); // [1, ",", 2, ",", 3]

map()

1
function map<Item, MappedItem>(
2
	mapper: Unary<Item, MappedItem>,
3
): (
4
	iterable: Readonly<Iterable<Item, any, any>>,
5
) => Readonly<IterableIterator<MappedItem, any, any>>;

Map for iterables.

Type parameters

Type parameter
`Item`
`MappedItem`

Parameters

Parameter	Type	Description
`mapper`	`Unary`<`Item`, `MappedItem`>	Mapper function.

Returns

Function

Generator function with mapper function set in context.

Parameters

Parameter	Type
`iterable`	`Readonly`<`Iterable`<`Item`, `any`, `any`>>

Returns

Readonly<IterableIterator<MappedItem, any, any>>

Example

1
const double = value => value * 2;
2
const mapDouble = map(double);
3

4
mapDouble([1, 2, 3]); // [2, 4, 6]

objectToEntries()

1
function objectToEntries<Key, Value>(
2
	input: Readonly<Record<Key, Value>>,
3
): Readonly<IterableIterator<Entry<Key, Value>, any, any>>;

Yields all entries of an object (including symbols).

Type parameters

Type parameter
`Key` extends `PropertyKey`
`Value`

Parameters

Parameter	Type	Description
`input`	`Readonly`<`Record`<`Key`, `Value`>>	Object to get entries from.

Returns

Readonly<IterableIterator<Entry<Key, Value>, any, any>>

Iterable with entries of the given object (including symbols).

Example

1
const entries = objectEntries({ a: 1, b: 2 });
2
entries.next(); // { value: ["a", 1], done: false }
3
entries.next(); // { value: ["b", 2], done: false }
4
entries.next(); // { value: undefined, done: true }

prepend()

1
function prepend<InitialItem>(
2
	initialIterable: Readonly<Iterable<InitialItem, any, any>>,
3
): <TailItem>(
4
	tailIterable: Readonly<Iterable<TailItem, any, any>>,
5
) => Readonly<IterableIterator<InitialItem | TailItem, any, any>>;

Prepends one iterable to another.

Type parameters

Type parameter
`InitialItem`

Parameters

Parameter	Type	Description
`initialIterable`	`Readonly`<`Iterable`<`InitialItem`, `any`, `any`>>	Iterable to be appended.

Returns

Function

Curried generator function with initialIterable set in context.

Type parameters

Type parameter
`TailItem`

Parameters

Parameter	Type
`tailIterable`	`Readonly`<`Iterable`<`TailItem`, `any`, `any`>>

Returns

Readonly<IterableIterator<InitialItem | TailItem, any, any>>

Example

1
const prependNumbers = prepend([0, 1, 2, 3, 4]);
2
prependNumbers(["foo", "bar"]); // [0, 1, 2, 3, 4, "foo", "bar"]

range()

1
function range<Step>(
2
	step: Step,
3
): (
4
	from: Step extends bigint ? bigint : number,
5
) => (
6
	to: Step extends bigint ? bigint : number,
7
) => Readonly<
8
	IterableIterator<Step extends bigint ? bigint : number, any, any>
9
>;

Range iterable generator (from from to to).

Type parameters

Type parameter
`Step` extends `Numeric`

Parameters

Parameter	Type	Description
`step`	`Step`	Step size.

Returns

Function

Curried function with step set in context.

Parameters

Parameter	Type
`from`	`Step` extends `bigint` ? `bigint` : `number`

Returns

Function

Parameters

Parameter	Type
`to`	`Step` extends `bigint` ? `bigint` : `number`

Returns

Readonly<IterableIterator<Step extends bigint ? bigint : number, any, any>>

Example

1
[...range(1)(0)(5)]; // [0, 1, 2, 3, 4, 5]
2
[...range(1)(5)(0)]; // [5, 4, 3, 2, 1, 0]

repeat()

1
function repeat(
2
	times: Numeric,
3
): <Item>(item: Item) => Readonly<IterableIterator<Item, any, any>>;

Repeat given item the specified amount of times (can be BigInt or Infinity times) as an iterable.

Parameters

Parameter	Type
`times`	`Numeric`

Returns

Function

Curried function with item in context.

Type parameters

Type parameter
`Item`

Parameters

Parameter	Type
`item`	`Item`

Returns

Readonly<IterableIterator<Item, any, any>>

Example

1
const repeat3Times = repeat(3);
2
repeat3Times("foo"); // ["foo", "foo", "foo"]

take()

1
function take(
2
	amount: Numeric,
3
): <Item>(
4
	iterable: Readonly<Iterable<Item, any, any>>,
5
) => Readonly<IterableIterator<Item, any, any>>;

Take the given amount of items from the iterable.

Parameters

Parameter	Type	Description
`amount`	`Numeric`	Amount of items to take.

Returns

Function

Curried function with amount in context.

Type parameters

Type parameter
`Item`

Parameters

Parameter	Type
`iterable`	`Readonly`<`Iterable`<`Item`, `any`, `any`>>

Returns

Readonly<IterableIterator<Item, any, any>>

Example

1
const take2 = take(2);
2
take2([1, 2, 3, 4, 5]); // [1, 2]

toIterable()

1
function toIterable<ValueOrIterable>(
2
	valueOrIterable: ValueOrIterable,
3
): Readonly<
4
	IterableIterator<
5
		ValueOrIterable extends IsomorphicIterable ?
6
			IsomorphicIterableItem<ValueOrIterable<ValueOrIterable>>
7
		:	ValueOrIterable,
8
		any,
9
		any
10
	>
11
>;

Takes a value, iterable and yields it.

Type parameters

Type parameter	Description
`ValueOrIterable`	Generic of value or iterable to yield.

Parameters

Parameter	Type	Description
`valueOrIterable`	`ValueOrIterable`	Vale or iterable to yield.

Returns

Readonly<IterableIterator<ValueOrIterable extends IsomorphicIterable ? IsomorphicIterableItem<ValueOrIterable<ValueOrIterable>> : ValueOrIterable, any, any>>

Yielded item or iterable.

Example

1
const iterable = toIterable(1);
2
const iterator = getIterator(iterable);
3
iterator.next(); // { value: 1, done: false }
4
iterator.next(); // { value: undefined, done: true }

See

createIterableIterator

unique()

1
function unique<Item>(
2
	iterable: Readonly<Iterable<Item, any, any>>,
3
): Readonly<IterableIterator<Item, any, any>>;

Returns a single instance of each item in the iterable.

Type parameters

Type parameter
`Item`

Parameters

Parameter	Type	Description
`iterable`	`Readonly`<`Iterable`<`Item`, `any`, `any`>>	Iterable to be filtered.

Returns

Readonly<IterableIterator<Item, any, any>>

Generators with a single instance of each item of the iterable.

Example

1
unique([1, 2, 3, 4, 1, 2, 3, 4]); // [1, 2, 3, 4]

zip()

1
function zip<ItemFirst>(
2
	iterableFirst: Readonly<Iterable<ItemFirst, any, any>>,
3
): <ItemSecond>(
4
	iterableSecond: Readonly<Iterable<ItemSecond, any, any>>,
5
) => Readonly<IterableIterator<readonly [ItemFirst, ItemSecond], any, any>>;

Takes two iterables and returns a new iterable with the length of the shortest iterable with tuples containing the items from both.

Type parameters

Type parameter
`ItemFirst`

Parameters

Parameter	Type	Description
`iterableFirst`	`Readonly`<`Iterable`<`ItemFirst`, `any`, `any`>>	One of the iterables to be zipped.

Returns

Function

Curried function with iterableFirst in context.

Type parameters

Type parameter
`ItemSecond`

Parameters

Parameter	Type
`iterableSecond`	`Readonly`<`Iterable`<`ItemSecond`, `any`, `any`>>

Returns

Readonly<IterableIterator<readonly [ItemFirst, ItemSecond], any, any>>

Example

1
const zipNumbers = zip([0, 1, 2]);
2
zipNumbers([3, 4, 5]); // [[0, 3], [1, 4], [2, 5]]

zipIndex()

1
function zipIndex<ItemSecond>(
2
	iterableSecond: Readonly<Iterable<ItemSecond, any, any>>,
3
): Readonly<IterableIterator<readonly [number, ItemSecond], any, any>>;

Yields a tuple for each item in the iterable with the index of said item.

Type parameters

Type parameter
`ItemSecond`

Parameters

Parameter	Type
`iterableSecond`	`Readonly`<`Iterable`<`ItemSecond`, `any`, `any`>>

Returns

Readonly<IterableIterator<readonly [number, ItemSecond], any, any>>

Example

1
zipIndex(["foo", "bar"]); // [[0, "foo"], [1, "bar"]]

Yields

Tuples with the index of each item.

Internal

setIterator()

1
function setIterator<Value>(
2
	value: Value,
3
): <Source>(
4
	object: Source,
5
) => Omit<Source, typeof iterator> & Readonly<Record<typeof iterator, Value>>;

Set Symbol.iterator to the given value to the given object.

Type parameters

Type parameter
`Value`

Parameters

Parameter	Type
`value`	`Value`

Returns

Function

Curried function with key in context.

Type parameters

Type parameter
`Source` extends `object`

Parameters

Parameter	Type
`object`	`Source`

Returns

Omit<Source, typeof iterator> & Readonly<Record<typeof iterator, Value>>

Example

1
setIterator("🟢")({ foo: "bar" }); // { [Symbol.iterator]: "🟢", foo: "bar" }

Reducers

count()

1
function count<Item>(
2
	predicate: Filter<Item>,
3
): (iterable: Readonly<Iterable<Item, any, any>>) => number;

Counts the number of items that satisfy a predicate in the given iterable.

Type parameters

Type parameter
`Item`

Parameters

Parameter	Type	Description
`predicate`	`Filter`<`Item`>	Predicate function for items to be counted.

Returns

Function

Curried function with predicate in context.

Parameters

Parameter	Type
`iterable`	`Readonly`<`Iterable`<`Item`, `any`, `any`>>

Returns

number

Example

1
const countOdds = count((number: number) => number % 2 !== 1);
2
countOdds([1, 2, 3, 4, 5]); // 3
3
countOdds([0, 2, 4, 6, 8]); // 0

entriesToObject()

1
function entriesToObject<Item>(
2
	iterable: Readonly<Iterable<Item, any, any>>,
3
): Readonly<Record<EntryKey<Item>, EntryValue<Item>>>;

Takes an entries iterable and returns an object.

Type parameters

Type parameter
`Item` extends `Entry`

Parameters

Parameter	Type
`iterable`	`Readonly`<`Iterable`<`Item`, `any`, `any`>>

Returns

Readonly<Record<EntryKey<Item>, EntryValue<Item>>>

Object constructed from entries.

Example

1
entriesToObject([["key", "value"]]); // { key: "value" }
2
entriesToObject([
3
	["foo", "bar"],
4
	["number", 1],
5
]); // { foo: "bar", number: 1 }

every()

1
function every<Item, Predicated>(
2
	predicate: Single<Predicated> extends Single<never> ? Unary<Item, boolean>
3
	:	Predicate<Item, Predicated>,
4
): (iterable: Readonly<Iterable<Item, any, any>>) => boolean;

Evaluates items in an iterable against a predicate and returns true if all items evaluates to true.

Type parameters

Type parameter	Value
`Item`	-
`Predicated`	`never`

Parameters

Parameter	Type	Description
`predicate`	`Single`<`Predicated`> extends `Single`<`never`> ? `Unary`<`Item`, `boolean`> : `Predicate`<`Item`, `Predicated`>	Predicate function to evaluate each item.

Returns

Function

Curried function with predicate set in context.

Parameters

Parameter	Type
`iterable`	`Readonly`<`Iterable`<`Item`, `any`, `any`>>

Returns

boolean

Example

1
const everyEven = every((number: number) => number % 2 === 0);
2
everyEven([2, 4, 6, 8]); // true
3
everyEven([1, 2, 3, 4]); // false

find()

1
function find<Item>(
2
	predicate: Unary<Item, boolean>,
3
): (iterable: Readonly<Iterable<Item, any, any>>) => Maybe<Item>;

Returns the value of the first item in the iterable where predicate is true, undefined otherwise.

Type parameters

Type parameter
`Item`

Parameters

Parameter	Type	Description
`predicate`	`Unary`<`Item`, `boolean`>	Predicate function to search for item.

Returns

Function

Curried function with predicate set in context.

Parameters

Parameter	Type
`iterable`	`Readonly`<`Iterable`<`Item`, `any`, `any`>>

Returns

Maybe<Item>

Example

1
const findEven = find((number: number) => number % 2 === 0);
2
findEven([1, 2, 3, 4]); // 2
3
findEven([1, 3, 5, 7]); // undefined

groupBy()

1
function groupBy<Item, Key>(
2
	grouper: Unary<Item, Key>,
3
): (
4
	iterable: Readonly<Iterable<Item, any, any>>,
5
) => Readonly<Record<Key, ReadOnlyArray<Item>>>;

Groups values of an iterable in an object based on the output of the grouper function.

Type parameters

Type parameter
`Item`
`Key` extends `PropertyKey`

Parameters

Parameter	Type	Description
`grouper`	`Unary`<`Item`, `Key`>	Grouper function.

Returns

Function

Object with grouped values.

Parameters

Parameter	Type
`iterable`	`Readonly`<`Iterable`<`Item`, `any`, `any`>>

Returns

Readonly<Record<Key, ReadOnlyArray<Item>>>

Example

1
const groupByType = groupBy((value: number) =>
2
	number % 2 === 0 ? "even" : "odd",
3
);
4
groupByType([1, 2, 3, 4, 5]); // { even: [2, 4], odd: [1, 3, 5] }

head()

1
function head<Iterable>(
2
	iterable: Iterable,
3
): Iterable extends ReadOnlyArray ? Head<Iterable<Iterable>>
4
:	Maybe<IsomorphicIterableItem<Iterable>>;

Get first element of an iterable (undefined if it is empty).

Type parameters

Type parameter
`Iterable` extends `Readonly`<`Iterable`<`unknown`, `any`, `any`>>

Parameters

Parameter	Type	Description
`iterable`	`Iterable`	Iterable to get the first element from.

Returns

Iterable extends ReadOnlyArray ? Head<Iterable<Iterable>> : Maybe<IsomorphicIterableItem<Iterable>>

First element of the iterable (undefined if empty).

Example

1
head([1, 2, 3]); // 1

includes()

1
function includes<SearchItem>(
2
	searchItem: SearchItem,
3
): (iterable: Readonly<Iterable<unknown, any, any>>) => boolean;

Tries to find the given searchItem in iterable.

Type parameters

Type parameter
`SearchItem`

Parameters

Parameter	Type	Description
`searchItem`	`SearchItem`	Item to search.

Returns

Function

Curried function with searchItem set in context.

Parameters

Parameter	Type
`iterable`	`Readonly`<`Iterable`<`unknown`, `any`, `any`>>

Returns

boolean

Example

1
const includesTwo = includes(2);
2
includesTwo([1, 2, 3, 4]); // true
3
includesTwo([1, 3, 5, 7]); // false

iterableToArray()

1
function iterableToArray<Iterable>(
2
	iterable: Iterable,
3
): ReadOnlyArray<IsomorphicIterableItem<Iterable>>;

Turns given iterable into an array.

Type parameters

Type parameter
`Iterable` extends `Readonly`<`Iterable`<`unknown`, `any`, `any`>>

Parameters

Parameter	Type	Description
`iterable`	`Iterable`	Iterable to be turned into an array.

Returns

ReadOnlyArray<IsomorphicIterableItem<Iterable>>

Array made of iterable items.

Example

1
iterableToArray([1, 2, 3, 4]); // [1, 2, 3, 4]

join()

1
function join<Separator>(
2
	separator: Separator,
3
): <Item>(
4
	iterable: Readonly<Iterable<Item, any, any>>,
5
) => `${string}${Separator}${string}`;

Takes a separator string and a iterable and returns a string with the concatenation of all the elements separated by the separator.

Type parameters

Type parameter
`Separator` extends `string`

Parameters

Parameter	Type	Description
`separator`	`Separator`	String to use as separator.

Returns

Function

Curried function with separator in context.

Type parameters

Type parameter
`Item` extends `Strigifiable`

Parameters

Parameter	Type
`iterable`	`Readonly`<`Iterable`<`Item`, `any`, `any`>>

Returns

`${string}${Separator}${string}`

Example

1
const joinWithSpaces = join(" ");
2
joinWithSpaces([1, 2, 3]); // "1 2 3"

length()

1
function length(iterable: Readonly<Iterable<unknown, any, any>>): number;

Get the length of an iterable.

Parameters

Parameter	Type	Description
`iterable`	`Readonly`<`Iterable`<`unknown`, `any`, `any`>>	Iterable to get the length from.

Returns

number

Promise with the length of the iterable.

Example

1
length([1, 2, 3]); // 3

reduce()

1
function reduce<Item, Accumulator>(
2
	reducer: Reducer<Item, Accumulator>,
3
): (
4
	initialValue: Accumulator,
5
) => (iterable: Readonly<Iterable<Item, any, any>>) => Accumulator;

Reducer function for iterables.

Type parameters

Type parameter
`Item`
`Accumulator`

Parameters

Parameter	Type	Description
`reducer`	`Reducer`<`Item`, `Accumulator`>	Reducer function.

Returns

Function

Curried function with reducer in context.

Parameters

Parameter	Type
`initialValue`	`Accumulator`

Returns

Function

Parameters

Parameter	Type
`iterable`	`Readonly`<`Iterable`<`Item`, `any`, `any`>>

Returns

Accumulator

Example

1
const sum = reduce<number>(item => total => total + item);
2
const sumFrom0 = sum(0);
3

4
sumFrom0([1, 2, 3]); // 6

some()

1
function some<Item, Predicated>(
2
	predicate: Single<Predicated> extends Single<never> ? Unary<Item, boolean>
3
	:	Predicate<Item, Predicated>,
4
): (iterable: Readonly<Iterable<Item, any, any>>) => boolean;

Evaluates items in an iterable against a predicate and returns true if any item evaluates to true.

Type parameters

Type parameter	Value
`Item`	-
`Predicated`	`never`

Parameters

Parameter	Type	Description
`predicate`	`Single`<`Predicated`> extends `Single`<`never`> ? `Unary`<`Item`, `boolean`> : `Predicate`<`Item`, `Predicated`>	Predicate function to evaluate each item.

Returns

Function

Curried function with predicate set in context.

Parameters

Parameter	Type
`iterable`	`Readonly`<`Iterable`<`Item`, `any`, `any`>>

Returns

boolean

Example

1
const someEven = some((number: number) => number % 2 === 0);
2
someEven([1, 2, 3, 4]); // true
3
someEven([1, 3, 5, 7]); // false