Skip to content

Iterables Reference

Coverage License NPM Version Open Issues Size

🔁 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:

Terminal window
pnpm add @lou.codes/iterables
# or
npm install @lou.codes/iterables
# or
yarn add @lou.codes/iterables

Import it and use it:

import { iterableToArray, map } from "@lou.codes/iterables";
const mapDouble = map((value: number) => value * 2);
iterableToArray(mapDouble([1, 2, 3])); // [2, 4, 6]

🦕 Deno

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

import { iterableToArray, map } from "npm:@lou.codes/iterables";
const mapDouble = map((value: number) => value * 2);
iterableToArray(mapDouble([1, 2, 3])); // [2, 4, 6]

🌎 Browser

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

<script type="module">
import { iterableToArray, map } from "https://esm.sh/@lou.codes/iterables";
const mapDouble = map(value => value * 2);
iterableToArray(mapDouble([1, 2, 3])); // [2, 4, 6]
</script>

Common

createIterableIterator

createIterableIterator<Item>(generatorFunction): Object

Takes a generator function and returns an iterable iterator object.

Type parameters

Name
Item

Parameters

NameTypeDescription
generatorFunction() => { next: (…args: [] | [void]) => IteratorResult<Item, void> ; return?: (value?: void) => IteratorResult<Item, void> ; throw?: (e?: any) => IteratorResult<Item, void> }Generator to be used every time [Symbol.iterator] is called.

Returns

Object

Iterable iterator object.

NameType
[iterator]() => IterableIterator<Item>
next(…args: [] | [undefined]) => IteratorResult<Item, any>
return (optional)(value?: any) => IteratorResult<Item, any>
throw (optional)(e?: any) => IteratorResult<Item, any>

Example

const identityGenerator = function* (value) {
yield value;
};
const iterableIterator = createIterableIterator(identityGenerator);
const fooIdentity = iterableIterator("foo");
for (const value of fooIdentity) {
console.log(value); // "foo"
}
// Same IterableIterator as above, return values again:
for (const value of fooIdentity) {
console.log(value); // "foo"
}

View source


forEach

forEach<Item>(callback): (iterable: { [iterator]: () => Iterator<Item, any, undefined> }) => void

For each function for iterables.

Type parameters

Name
Item

Parameters

NameTypeDescription
callbackUnary<Item, void>Function to be called for every item of the iterable.

Returns

fn

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

▸ (iterable): void

Parameters
NameType
iterableObject
iterable.[iterator]() => Iterator<Item, any, undefined>
Returns

void

Example

const logEach = forEach(console.log);
logEach([1, 2, 3]); // Logs 1, 2 and 3 separately

View source

Generators

ReadOnlyIterable

Ƭ ReadOnlyIterable<Item>: ReadOnly<Iterable<Item>>

Read-only Iterable.

Remarks

This is just an read-only alternative to Iterable to avoid unwanted mutations.

Type parameters

NameTypeDescription
ItemunknownType of the items in the Iterable.

View source


ReadOnlyIterableIterator

Ƭ ReadOnlyIterableIterator<Item>: ReadOnly<IterableIterator<Item>>

Read-only IterableIterator.

Remarks

This is just an read-only alternative to IterableIterator to avoid unwanted mutations.

Type parameters

NameTypeDescription
ItemunknownType of the items in the IterableIterator.

View source


ReadOnlyIterator

Ƭ ReadOnlyIterator<Item, Return, Next>: ReadOnly<Iterator<Item, Return, Next>>

Read-only Iterator.

Remarks

This is just an read-only alternative to Iterator to avoid unwanted mutations.

Type parameters

NameTypeDescription
ItemunknownType of the items in the Iterator.
ReturnvoidType of the return value in the Iterator.
NextvoidType of the next value in the Iterator.

View source


append

append<TailItem>(tailIterable): <InitialItem>(initialIterable: { [iterator]: () => Iterator<InitialItem, any, undefined> }) => { [iterator]: () => IterableIterator<TailItem | InitialItem> ; next: (…args: [] | [undefined]) => IteratorResult<TailItem | InitialItem, any> ; return?: (value?: any) => IteratorResult<TailItem | InitialItem, any> ; throw?: (e?: any) => IteratorResult<TailItem | InitialItem, any> }

Appends one iterable to another.

Type parameters

Name
TailItem

Parameters

NameTypeDescription
tailIterableObjectIterable to be appended.
tailIterable.[iterator]() => Iterator<TailItem, any, undefined>-

Returns

fn

Curried generator function with tailIterable set in context.

▸ <InitialItem>(initialIterable): Object

Type parameters
Name
InitialItem
Parameters
NameType
initialIterableObject
initialIterable.[iterator]() => Iterator<InitialItem, any, undefined>
Returns

Object

NameType
[iterator]() => IterableIterator<TailItem | InitialItem>
next(…args: [] | [undefined]) => IteratorResult<TailItem | InitialItem, any>
return (optional)(value?: any) => IteratorResult<TailItem | InitialItem, any>
throw (optional)(e?: any) => IteratorResult<TailItem | InitialItem, any>

Example

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

View source


drop

drop(amount): <Item>(iterable: { [iterator]: () => Iterator<Item, any, undefined> }) => { [iterator]: () => IterableIterator<Item> ; next: (…args: [] | [undefined]) => IteratorResult<Item, any> ; return?: (value?: any) => IteratorResult<Item, any> ; throw?: (e?: any) => IteratorResult<Item, any> }

Drop the specified amount of items from the given iterable.

Parameters

NameTypeDescription
amountnumber | bigintAmount of items to drop.

Returns

fn

Curried function with amount in context.

▸ <Item>(iterable): Object

Type parameters
Name
Item
Parameters
NameType
iterableObject
iterable.[iterator]() => Iterator<Item, any, undefined>
Returns

Object

NameType
[iterator]() => IterableIterator<Item>
next(…args: [] | [undefined]) => IteratorResult<Item, any>
return (optional)(value?: any) => IteratorResult<Item, any>
throw (optional)(e?: any) => IteratorResult<Item, any>

Example

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

View source


filter

filter<Item, Filtered>(predicate): (iterable: { [iterator]: () => Iterator<Item, any, undefined> }) => { [iterator]: () => IterableIterator<Filtered> ; next: (…args: [] | [undefined]) => IteratorResult<Filtered, any> ; return?: (value?: any) => IteratorResult<Filtered, any> ; throw?: (e?: any) => IteratorResult<Filtered, any> }

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

Type parameters

NameType
ItemItem
Filterednever

Parameters

NameTypeDescription
predicateSingle<Filtered> extends Single<never> ? Unary<Item, boolean> : Predicate<Item, Filtered>Predicate function to evaluate each item.

Returns

fn

Curried function with predicate set in context.

▸ (iterable): Object

Parameters
NameType
iterableObject
iterable.[iterator]() => Iterator<Item, any, undefined>
Returns

Object

NameType
[iterator]() => IterableIterator<Filtered>
next(…args: [] | [undefined]) => IteratorResult<Filtered, any>
return (optional)(value?: any) => IteratorResult<Filtered, any>
throw (optional)(e?: any) => IteratorResult<Filtered, any>

Example

const filterEven = filter((number: number) => number % 2 === 0);
iterableToArray(filterEven([1, 2, 3, 4])); // [2, 4]
iterableToArray(filterEven([1, 3, 5, 7])); // []

View source


flat

flat<Iterable>(iterable): Iterable extends { [iterator]: () => Iterator<Item, any, undefined> } ? Item extends { [iterator]: () => Iterator<SubItem, any, undefined> } ? { [iterator]: () => IterableIterator<SubItem> ; next: (…args: [] | [undefined]) => IteratorResult<SubItem, any> ; return?: (value?: any) => IteratorResult<SubItem, any> ; throw?: (e?: any) => IteratorResult<SubItem, any> } : { [iterator]: () => IterableIterator<Item> ; next: (…args: [] | [undefined]) => IteratorResult<Item, any> ; return?: (value?: any) => IteratorResult<Item, any> ; throw?: (e?: any) => IteratorResult<Item, any> } : never

Flattens one level of the given iterable.

Type parameters

NameType
Iterableextends Object

Parameters

NameTypeDescription
iterableIterableIterable to flatten.

Returns

Iterable extends { [iterator]: () => Iterator<Item, any, undefined> } ? Item extends { [iterator]: () => Iterator<SubItem, any, undefined> } ? { [iterator]: () => IterableIterator<SubItem> ; next: (…args: [] | [undefined]) => IteratorResult<SubItem, any> ; return?: (value?: any) => IteratorResult<SubItem, any> ; throw?: (e?: any) => IteratorResult<SubItem, any> } : { [iterator]: () => IterableIterator<Item> ; next: (…args: [] | [undefined]) => IteratorResult<Item, any> ; return?: (value?: any) => IteratorResult<Item, any> ; throw?: (e?: any) => IteratorResult<Item, any> } : never

Iterable with flatten items.

Example

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

View source


initial

initial<Iterable>(iterable): Object

Get all elements except the last one of an iterable.

Type parameters

NameType
Iterableextends Object

Parameters

NameTypeDescription
iterableIterableIterable to get the items from.

Returns

Object

Iterable with all items except the last one.

NameType
[iterator]() => IterableIterator<Iterable extends ReadOnlyArray ? Initial<Iterable>[number] : IsomorphicIterableItem<Iterable>>
next(…args: [] | [undefined]) => IteratorResult<Iterable extends ReadOnlyArray ? Initial<Iterable>[number] : IsomorphicIterableItem<Iterable>, any>
return (optional)(value?: any) => IteratorResult<Iterable extends ReadOnlyArray ? Initial<Iterable>[number] : IsomorphicIterableItem<Iterable>, any>
throw (optional)(e?: any) => IteratorResult<Iterable extends ReadOnlyArray ? Initial<Iterable>[number] : IsomorphicIterableItem<Iterable>, any>

Example

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

View source


intersperse

intersperse<Separator>(separator): <Item>(iterable: { [iterator]: () => Iterator<Item, any, undefined> }) => { [iterator]: () => IterableIterator<Separator | Item> ; next: (…args: [] | [undefined]) => IteratorResult<Separator | Item, any> ; return?: (value?: any) => IteratorResult<Separator | Item, any> ; throw?: (e?: any) => IteratorResult<Separator | Item, any> }

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

Type parameters

Name
Separator

Parameters

NameTypeDescription
separatorSeparatorSeparator to add between each element.

Returns

fn

Curried function with separator in context.

▸ <Item>(iterable): Object

Type parameters
Name
Item
Parameters
NameType
iterableObject
iterable.[iterator]() => Iterator<Item, any, undefined>
Returns

Object

NameType
[iterator]() => IterableIterator<Separator | Item>
next(…args: [] | [undefined]) => IteratorResult<Separator | Item, any>
return (optional)(value?: any) => IteratorResult<Separator | Item, any>
throw (optional)(e?: any) => IteratorResult<Separator | Item, any>

Example

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

View source


map

map<Item, MappedItem>(mapper): (iterable: { [iterator]: () => Iterator<Item, any, undefined> }) => { [iterator]: () => IterableIterator<MappedItem> ; next: (…args: [] | [undefined]) => IteratorResult<MappedItem, any> ; return?: (value?: any) => IteratorResult<MappedItem, any> ; throw?: (e?: any) => IteratorResult<MappedItem, any> }

Map for iterables.

Type parameters

Name
Item
MappedItem

Parameters

NameTypeDescription
mapperUnary<Item, MappedItem>Mapper function.

Returns

fn

Generator function with mapper function set in context.

▸ (iterable): Object

Parameters
NameType
iterableObject
iterable.[iterator]() => Iterator<Item, any, undefined>
Returns

Object

NameType
[iterator]() => IterableIterator<MappedItem>
next(…args: [] | [undefined]) => IteratorResult<MappedItem, any>
return (optional)(value?: any) => IteratorResult<MappedItem, any>
throw (optional)(e?: any) => IteratorResult<MappedItem, any>

Example

const double = value => value * 2;
const mapDouble = map(double);
mapDouble([1, 2, 3]); // [2, 4, 6]

View source


objectToEntries

objectToEntries<Key, Value>(input): Object

Yields all entries of an object (including symbols).

Type parameters

NameType
Keyextends PropertyKey
ValueValue

Parameters

NameTypeDescription
inputReadOnlyRecord<Key, Value>Object to get entries from.

Returns

Object

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

NameType
[iterator]() => IterableIterator<Entry<Key, Value>>
next(…args: [] | [undefined]) => IteratorResult<Entry<Key, Value>, any>
return (optional)(value?: any) => IteratorResult<Entry<Key, Value>, any>
throw (optional)(e?: any) => IteratorResult<Entry<Key, Value>, any>

Example

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

View source


prepend

prepend<InitialItem>(initialIterable): <TailItem>(tailIterable: { [iterator]: () => Iterator<TailItem, any, undefined> }) => { [iterator]: () => IterableIterator<InitialItem | TailItem> ; next: (…args: [] | [undefined]) => IteratorResult<InitialItem | TailItem, any> ; return?: (value?: any) => IteratorResult<InitialItem | TailItem, any> ; throw?: (e?: any) => IteratorResult<InitialItem | TailItem, any> }

Prepends one iterable to another.

Type parameters

Name
InitialItem

Parameters

NameTypeDescription
initialIterableObjectIterable to be appended.
initialIterable.[iterator]() => Iterator<InitialItem, any, undefined>-

Returns

fn

Curried generator function with initialIterable set in context.

▸ <TailItem>(tailIterable): Object

Type parameters
Name
TailItem
Parameters
NameType
tailIterableObject
tailIterable.[iterator]() => Iterator<TailItem, any, undefined>
Returns

Object

NameType
[iterator]() => IterableIterator<InitialItem | TailItem>
next(…args: [] | [undefined]) => IteratorResult<InitialItem | TailItem, any>
return (optional)(value?: any) => IteratorResult<InitialItem | TailItem, any>
throw (optional)(e?: any) => IteratorResult<InitialItem | TailItem, any>

Example

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

View source


range

range<Step>(step): (from: Step extends bigint ? bigint : number) => (to: Step extends bigint ? bigint : number) => { [iterator]: () => IterableIterator<number | Step extends bigint ? bigint : number> ; next: (…args: [] | [undefined]) => IteratorResult<number | Step extends bigint ? bigint : number, any> ; return?: (value?: any) => IteratorResult<number | Step extends bigint ? bigint : number, any> ; throw?: (e?: any) => IteratorResult<number | Step extends bigint ? bigint : number, any> }

Range iterable generator (from from to to).

Type parameters

NameType
Stepextends number | bigint

Parameters

NameTypeDescription
stepStepStep size.

Returns

fn

Curried function with step set in context.

▸ (from): (to: Step extends bigint ? bigint : number) => { [iterator]: () => IterableIterator<number | Step extends bigint ? bigint : number> ; next: (…args: [] | [undefined]) => IteratorResult<number | Step extends bigint ? bigint : number, any> ; return?: (value?: any) => IteratorResult<number | Step extends bigint ? bigint : number, any> ; throw?: (e?: any) => IteratorResult<number | Step extends bigint ? bigint : number, any> }

Parameters
NameType
fromStep extends bigint ? bigint : number
Returns

fn

▸ (to): Object

Parameters
NameType
toStep extends bigint ? bigint : number
Returns

Object

NameType
[iterator]() => IterableIterator<number | Step extends bigint ? bigint : number>
next(…args: [] | [undefined]) => IteratorResult<number | Step extends bigint ? bigint : number, any>
return (optional)(value?: any) => IteratorResult<number | Step extends bigint ? bigint : number, any>
throw (optional)(e?: any) => IteratorResult<number | Step extends bigint ? bigint : number, any>

Example

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

View source


repeat

repeat(times): <Item>(item: Item) => { [iterator]: () => IterableIterator<Item> ; next: (…args: [] | [undefined]) => IteratorResult<Item, any> ; return?: (value?: any) => IteratorResult<Item, any> ; throw?: (e?: any) => IteratorResult<Item, any> }

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

Parameters

NameType
timesnumber | bigint

Returns

fn

Curried function with item in context.

▸ <Item>(item): Object

Type parameters
Name
Item
Parameters
NameType
itemItem
Returns

Object

NameType
[iterator]() => IterableIterator<Item>
next(…args: [] | [undefined]) => IteratorResult<Item, any>
return (optional)(value?: any) => IteratorResult<Item, any>
throw (optional)(e?: any) => IteratorResult<Item, any>

Example

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

View source


take

take(amount): <Item>(iterable: { [iterator]: () => Iterator<Item, any, undefined> }) => { [iterator]: () => IterableIterator<Item> ; next: (…args: [] | [undefined]) => IteratorResult<Item, any> ; return?: (value?: any) => IteratorResult<Item, any> ; throw?: (e?: any) => IteratorResult<Item, any> }

Take the given amount of items from the iterable.

Parameters

NameTypeDescription
amountnumber | bigintAmount of items to take.

Returns

fn

Curried function with amount in context.

▸ <Item>(iterable): Object

Type parameters
Name
Item
Parameters
NameType
iterableObject
iterable.[iterator]() => Iterator<Item, any, undefined>
Returns

Object

NameType
[iterator]() => IterableIterator<Item>
next(…args: [] | [undefined]) => IteratorResult<Item, any>
return (optional)(value?: any) => IteratorResult<Item, any>
throw (optional)(e?: any) => IteratorResult<Item, any>

Example

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

View source


toIterable

toIterable<ValueOrIterable>(valueOrIterable): Object

Takes a value, iterable and yields it.

Type parameters

NameDescription
ValueOrIterableGeneric of value or iterable to yield.

Parameters

NameTypeDescription
valueOrIterableValueOrIterableVale or iterable to yield.

Returns

Object

Yielded item or iterable.

NameType
[iterator]() => IterableIterator<ValueOrIterable extends IsomorphicIterable ? IsomorphicIterableItem<ValueOrIterable> : ValueOrIterable>
next(…args: [] | [undefined]) => IteratorResult<ValueOrIterable extends IsomorphicIterable ? IsomorphicIterableItem<ValueOrIterable> : ValueOrIterable, any>
return (optional)(value?: any) => IteratorResult<ValueOrIterable extends IsomorphicIterable ? IsomorphicIterableItem<ValueOrIterable> : ValueOrIterable, any>
throw (optional)(e?: any) => IteratorResult<ValueOrIterable extends IsomorphicIterable ? IsomorphicIterableItem<ValueOrIterable> : ValueOrIterable, any>

Example

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

See

createIterableIterator

View source


unique

unique<Item>(iterable): Object

Returns a single instance of each item in the iterable.

Type parameters

Name
Item

Parameters

NameTypeDescription
iterableObjectIterable to be filtered.
iterable.[iterator]() => Iterator<Item, any, undefined>-

Returns

Object

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

NameType
[iterator]() => IterableIterator<Item>
next(…args: [] | [undefined]) => IteratorResult<Item, any>
return (optional)(value?: any) => IteratorResult<Item, any>
throw (optional)(e?: any) => IteratorResult<Item, any>

Example

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

View source


zip

zip<ItemFirst>(iterableFirst): <ItemSecond>(iterableSecond: { [iterator]: () => Iterator<ItemSecond, any, undefined> }) => { [iterator]: () => IterableIterator<readonly [ItemFirst, ItemSecond]> ; next: (…args: [] | [undefined]) => IteratorResult<readonly [ItemFirst, ItemSecond], any> ; return?: (value?: any) => IteratorResult<readonly [ItemFirst, ItemSecond], any> ; throw?: (e?: any) => IteratorResult<readonly [ItemFirst, ItemSecond], 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

Name
ItemFirst

Parameters

NameTypeDescription
iterableFirstObjectOne of the iterables to be zipped.
iterableFirst.[iterator]() => Iterator<ItemFirst, any, undefined>-

Returns

fn

Curried function with iterableFirst in context.

▸ <ItemSecond>(iterableSecond): Object

Type parameters
Name
ItemSecond
Parameters
NameType
iterableSecondObject
iterableSecond.[iterator]() => Iterator<ItemSecond, any, undefined>
Returns

Object

NameType
[iterator]() => IterableIterator<readonly [ItemFirst, ItemSecond]>
next(…args: [] | [undefined]) => IteratorResult<readonly [ItemFirst, ItemSecond], any>
return (optional)(value?: any) => IteratorResult<readonly [ItemFirst, ItemSecond], any>
throw (optional)(e?: any) => IteratorResult<readonly [ItemFirst, ItemSecond], any>

Example

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

View source


zipIndex

zipIndex<ItemSecond>(iterableSecond): Object

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

Type parameters

Name
ItemSecond

Parameters

NameType
iterableSecondObject
iterableSecond.[iterator]() => Iterator<ItemSecond, any, undefined>

Returns

Object

NameType
[iterator]() => IterableIterator<readonly [number, ItemSecond]>
next(…args: [] | [undefined]) => IteratorResult<readonly [number, ItemSecond], any>
return (optional)(value?: any) => IteratorResult<readonly [number, ItemSecond], any>
throw (optional)(e?: any) => IteratorResult<readonly [number, ItemSecond], any>

Example

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

Yields

Tuples with the index of each item.

View source

Reducers

count

count<Item>(predicate): (iterable: { [iterator]: () => Iterator<Item, any, undefined> }) => number

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

Type parameters

Name
Item

Parameters

NameTypeDescription
predicateFilter<Item>Predicate function for items to be counted.

Returns

fn

Curried function with predicate in context.

▸ (iterable): number

Parameters
NameType
iterableObject
iterable.[iterator]() => Iterator<Item, any, undefined>
Returns

number

Example

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

View source


entriesToObject

entriesToObject<Item>(iterable): ReadOnlyRecord<EntryKey<Item>, EntryValue<Item>>

Takes an entries iterable and returns an object.

Type parameters

NameType
Itemextends Entry

Parameters

NameType
iterableObject
iterable.[iterator]() => Iterator<Item, any, undefined>

Returns

ReadOnlyRecord<EntryKey<Item>, EntryValue<Item>>

Object constructed from entries.

Example

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

View source


every

every<Item, Predicated>(predicate): (iterable: { [iterator]: () => Iterator<Item, any, undefined> }) => boolean

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

Type parameters

NameType
ItemItem
Predicatednever

Parameters

NameTypeDescription
predicateSingle<Predicated> extends Single<never> ? Unary<Item, boolean> : Predicate<Item, Predicated>Predicate function to evaluate each item.

Returns

fn

Curried function with predicate set in context.

▸ (iterable): boolean

Parameters
NameType
iterableObject
iterable.[iterator]() => Iterator<Item, any, undefined>
Returns

boolean

Example

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

View source


find

find<Item>(predicate): (iterable: { [iterator]: () => Iterator<Item, any, undefined> }) => Maybe<Item>

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

Type parameters

Name
Item

Parameters

NameTypeDescription
predicateUnary<Item, boolean>Predicate function to search for item.

Returns

fn

Curried function with predicate set in context.

▸ (iterable): Maybe<Item>

Parameters
NameType
iterableObject
iterable.[iterator]() => Iterator<Item, any, undefined>
Returns

Maybe<Item>

Example

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

View source


groupBy

groupBy<Item, Key>(grouper): (iterable: { [iterator]: () => Iterator<Item, any, undefined> }) => ReadOnlyRecord<Key, ReadOnlyArray<Item>>

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

Type parameters

NameType
ItemItem
Keyextends PropertyKey

Parameters

NameTypeDescription
grouperUnary<Item, Key>Grouper function.

Returns

fn

Object with grouped values.

▸ (iterable): ReadOnlyRecord<Key, ReadOnlyArray<Item>>

Parameters
NameType
iterableObject
iterable.[iterator]() => Iterator<Item, any, undefined>
Returns

ReadOnlyRecord<Key, ReadOnlyArray<Item>>

Example

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

View source


head<Iterable>(iterable): Iterable extends ReadOnlyArray ? Head<Iterable> : Maybe<IsomorphicIterableItem<Iterable>>

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

Type parameters

NameType
Iterableextends Object

Parameters

NameTypeDescription
iterableIterableIterable to get the first element from.

Returns

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

First element of the iterable (undefined if empty).

Example

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

View source


includes

includes<SearchItem>(searchItem): (iterable: { [iterator]: () => Iterator<unknown, any, undefined> }) => boolean

Tries to find the given searchItem in iterable.

Type parameters

Name
SearchItem

Parameters

NameTypeDescription
searchItemSearchItemItem to search.

Returns

fn

Curried function with searchItem set in context.

▸ (iterable): boolean

Parameters
NameType
iterableObject
iterable.[iterator]() => Iterator<unknown, any, undefined>
Returns

boolean

Example

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

View source


iterableToArray

iterableToArray<Iterable>(iterable): ReadOnlyArray<IsomorphicIterableItem<Iterable>>

Turns given iterable into an array.

Type parameters

NameType
Iterableextends Object

Parameters

NameTypeDescription
iterableIterableIterable to be turned into an array.

Returns

ReadOnlyArray<IsomorphicIterableItem<Iterable>>

Array made of iterable items.

Example

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

View source


join

join(separator): <Item>(iterable: { [iterator]: () => Iterator<Item, any, undefined> }) => string

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

Parameters

NameTypeDescription
separatorstringString to use as separator.

Returns

fn

Curried function with separator in context.

▸ <Item>(iterable): string

Type parameters
NameType
Itemextends Strigifiable
Parameters
NameType
iterableObject
iterable.[iterator]() => Iterator<Item, any, undefined>
Returns

string

Example

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

View source


length

length(iterable): number

Get the length of an iterable.

Parameters

NameTypeDescription
iterableObjectIterable to get the length from.
iterable.[iterator]() => Iterator<unknown, any, undefined>-

Returns

number

Promise with the length of the iterable.

Example

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

View source


reduce

reduce<Item, Accumulator>(reducer): (initialValue: Accumulator) => (iterable: { [iterator]: () => Iterator<Item, any, undefined> }) => Accumulator

Reducer function for iterables.

Type parameters

Name
Item
Accumulator

Parameters

NameTypeDescription
reducerReducer<Item, Accumulator>Reducer function.

Returns

fn

Curried function with reducer in context.

▸ (initialValue): (iterable: { [iterator]: () => Iterator<Item, any, undefined> }) => Accumulator

Parameters
NameType
initialValueAccumulator
Returns

fn

▸ (iterable): Accumulator

Parameters
NameType
iterableObject
iterable.[iterator]() => Iterator<Item, any, undefined>
Returns

Accumulator

Example

const sum = Accumulator<number>(item => total => total + item);
const sumFrom0 = sum(0);
sumFrom0([1, 2, 3]); // 6

View source


some

some<Item, Predicated>(predicate): (iterable: { [iterator]: () => Iterator<Item, any, undefined> }) => boolean

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

Type parameters

NameType
ItemItem
Predicatednever

Parameters

NameTypeDescription
predicateSingle<Predicated> extends Single<never> ? Unary<Item, boolean> : Predicate<Item, Predicated>Predicate function to evaluate each item.

Returns

fn

Curried function with predicate set in context.

▸ (iterable): boolean

Parameters
NameType
iterableObject
iterable.[iterator]() => Iterator<Item, any, undefined>
Returns

boolean

Example

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

View source