Skip to main content

API

Collections​

FunctionDescription

join

Returns the string concatenation of the values of iterable, separated by separator.

Like Array.prototype.join, but for iterables, except it does not treat null, undefined, or [] specially.

Example

import { join, map, pipe } from 'lfi'

console.log(
  pipe(
    [`sloth`, `lazy`, `sleep`],
    map(word => word.toUpperCase()),
    join(`, `),
  ),
)
//=> SLOTH, LAZY, SLEEP
Playground

Since

v0.0.1

joinAsync

Returns a promise that resolves to the string concatenation of the values of asyncIterable, separated by separator.

Like Array.prototype.join, but for async iterables, except it does not treat null, undefined, or [] specially.

Example

import { asAsync, joinAsync, mapAsync, pipe } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`

console.log(
  await pipe(
    asAsync([`sloth`, `lazy`, `sleep`]),
    mapAsync(async word => {
      const response = await fetch(`${API_URL}/${word}`)
      return (await response.json())[0].phonetic
    }),
    joinAsync(`, `),
  ),
)
//=> /slɑθ/, /ˈleɪzi/, /sliːp/
Playground

Since

v0.0.1

joinConcur

Returns a promise that resolves to the string concatenation of the values of concurIterable, separated by separator.

Like Array.prototype.join, but for concur iterables, except it does not treat null, undefined, or [] specially.

WARNING: The iteration order of concur iterables is not deterministic, so the values will be concatenated in an arbitrary order.

Example

import { asConcur, joinConcur, mapConcur, pipe } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`

console.log(
  await pipe(
    asConcur([`sloth`, `lazy`, `sleep`]),
    mapConcur(async word => {
      const response = await fetch(`${API_URL}/${word}`)
      return (await response.json())[0].phonetic
    }),
    joinConcur(`, `),
  ),
)
// NOTE: This order may change between runs
//=> /slɑθ/, /ˈleɪzi/, /sliːp/
Playground

Since

v0.0.2

toArray

Returns a Reducer that collects values to an Array.

Example

import { cycle, pipe, reduce, take, toArray } from 'lfi'

console.log(
  pipe(
    cycle([`sloth`, `lazy`, `sleep`]),
    take(4),
    reduce(toArray()),
  ),
)
//=> [ 'sloth', 'lazy', 'sleep', 'sloth' ]
Playground

Since

v0.0.1

toGrouped

Returns a Reducer that reduces key-value pairs using outerReducer and reduces values with the same key using innerReducer.

Example

import { map, pipe, reduce, toArray, toGrouped, toMap } from 'lfi'

console.log(
  pipe(
    [`sloth`, `lazy`, `sleep`],
    map(word => [word.length, word]),
    reduce(toGrouped(toArray(), toMap())),
  ),
)
//=> Map(2) {
//=>   5 => [ 'sloth', 'sleep' ],
//=>   4 => [ 'lazy' ]
//=> }
Playground

Since

v2.0.0

toJoin

Returns a Reducer that concatenates values to a string where values are separated by separator.

Joins like Array.prototype.join, but does not treat null, undefined, or [] specially.

Use when composing reducers. Prefer join, joinAsync, and joinConcur for direct use on iterables.

Example

import { map, pipe, reduce, toGrouped, toJoin, toMap } from 'lfi'

console.log(
  pipe(
    [`sloth`, `lazy`, `sleep`],
    map(word => [word.length, word]),
    reduce(toGrouped(toJoin(`,`), toMap())),
  ),
)
//=> Map(2) {
//=>   5 => 'sloth,sleep',
//=>   4 => 'lazy'
//=> }
Playground

Since

v2.0.0

toMap

Returns a KeyedReducer that collects key-value pairs to a Map.

In the case of pairs with duplicate keys, the value of the last one wins.

Example

import { map, pipe, reduce, toMap } from 'lfi'

console.log(
  pipe(
    [`sloth`, `lazy`, `sleep`],
    map(word => [word, word.length]),
    reduce(toMap()),
  ),
)
//=> Map(3) {
//=>   'sloth' => 5,
//=>   'lazy' => 4,
//=>   'sleep' => 5
//=> }
Playground

Since

v0.0.1

toMultiple

Returns a Reducer or OptionalReducer that reduces values to an object or array of the same shape as reducers using all of the reducers in reducers.

Returns an OptionalReducer if at least one of the input reducers is an OptionalReducer. Otherwise, returns a Reducer.

Example

import { map, pipe, reduce, toCount, toJoin, toMultiple, toSet } from 'lfi'

console.log(
  pipe(
    [`sloth`, `lazy`, `sleep`],
    map(word => word.length),
    reduce(toMultiple([toSet(), toCount(), toJoin(`,`)])),
  ),
)
//=> [
//=>   Set(2) { 5, 4 },
//=>   3,
//=>   '5,4,5'
//=> ]

console.log(
  pipe(
    [`sloth`, `lazy`, `sleep`],
    map(word => word.length),
    reduce(
      toMultiple({
        set: toSet(),
        count: toCount(),
        string: toJoin(`,`),
      }),
    ),
  ),
)
//=> {
//=>   set: Set(2) { 5, 4 },
//=>   count: 3,
//=>   string: '5,4,5'
//=> }
Playground

Since

v2.0.0

toObject

Returns a KeyedReducer that collects key-value pairs to an object.

In the case of pairs with duplicate keys, the value of the last one wins.

Example

import { map, pipe, reduce, toObject } from 'lfi'

console.log(
  pipe(
    [`sloth`, `lazy`, `sleep`],
    map(word => [word, word.length]),
    reduce(toObject()),
  ),
)
//=> {
//=>   sloth: 5,
//=>   lazy: 4,
//=>   sleep: 5
//=> }
Playground

Since

v0.0.1

toSet

Returns a Reducer that collects values to a Set.

Example

import { cycle, pipe, reduce, take, toSet } from 'lfi'

console.log(
  pipe(
    cycle([`sloth`, `lazy`, `sleep`]),
    take(4),
    reduce(toSet()),
  ),
)
//=> Set(3) {
//=>   'sloth',
//=>   'lazy',
//=>   'sleep'
//=> }
Playground

Since

v0.0.1

toWeakMap

Returns a KeyedReducer that collects key-value pairs to a WeakMap.

In the case of pairs with duplicate keys, the value of the last one wins.

Example

import { map, pipe, reduce, toWeakMap } from 'lfi'

console.log(
  pipe(
    [`sloth`, `lazy`, `sleep`],
    map(word => [{ sloth: word }, word.length]),
    reduce(toWeakMap()),
  ),
)
//=> WeakMap { <items unknown> }
Playground

Since

v0.0.1

toWeakSet

Returns a Reducer that collects objects to a WeakSet.

Example

import { cycle, map, pipe, reduce, take, toWeakSet } from 'lfi'

console.log(
  pipe(
    cycle([`sloth`, `lazy`, `sleep`]),
    take(4),
    map(word => ({ sloth: word })),
    reduce(toWeakSet()),
  ),
)
//=> WeakSet { <items unknown> }
Playground

Since

v0.0.1

Core​

Type alias, Variable, FunctionDescription

ConcurIterable

Represents a lazy collection of values, each of type Value, that can be iterated concurrently.

The collection can be iterated by invoking the concur iterable with an apply callback. The callback is applied to each value in the collection, potentially asynchronously, in some order.

Invoking the concur iterable returns a promise that resolves when apply has been applied to each value in the concur iterable and each result returned by apply is awaited.

A concur iterable is effectively a cold push-based observable backed by some asynchronous operations.

Example

import { asConcur, mapConcur, pipe } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`

const concurIterable = pipe(
  asConcur([`sloth`, `lazy`, `sleep`]),
  mapConcur(async word => {
    const response = await fetch(`${API_URL}/${word}`)
    return (await response.json())[0].phonetic
  }),
)

await concurIterable(console.log)
// NOTE: This order may change between runs
//=> /slɑθ/
//=> /ˈleɪzi/
//=> /sliːp/
Playground

Since

v0.0.2

ConcurIterableApply

The callback invoked for each value of a ConcurIterable.

Since

v2.0.0

empty

An iterable that contains zero values.

Can be used as an iterable of any type.

Like [], but opaque.

Example

import { empty } from 'lfi'

console.log([...empty])
//=> []
Playground

Since

v0.0.1

emptyAsync

An async iterable that contains zero values.

Can be used as an async iterable of any type.

Like [], but for async iterables.

Example

import { emptyAsync, pipe, reduceAsync, toArray } from 'lfi'

console.log(
  await pipe(
    emptyAsync,
    reduceAsync(toArray()),
  ),
)
//=> []
Playground

Since

v0.0.1

asAsync

Returns an async iterable wrapper around iterable.

WARNING: When passing a concur iterable the returned async iterable will buffer the values yielded by the concur iterable if they are not read from the async iterable as quickly as they are yielded by the concur iterable. This happens because concur iterables are push-based while async iterables are pull-based, which creates backpressure.

Example

import { asAsync } from 'lfi'

const asyncIterable = asAsync([`sloth`, `lazy`, `sleep`])

console.log(typeof asyncIterable[Symbol.asyncIterator])
//=> function

for await (const value of asyncIterable) {
  console.log(value)
}
//=> sloth
//=> lazy
//=> sleep
Playground

Since

v0.0.2

asConcur

Returns a concur iterable wrapper around iterable.

Example

import { asConcur, forEachConcur } from 'lfi'

const concurIterable = asConcur([`sloth`, `lazy`, `sleep`])

await forEachConcur(console.log, concurIterable)
//=> sloth
//=> lazy
//=> sleep
Playground

Since

v0.0.2

compose

Returns a function that takes a single parameter and pipes it through the given functions.

Example

import { compose, map, reduce, toArray } from 'lfi'

const screamify = compose(
  map(word => word.toUpperCase()),
  reduce(toArray()),
  // Also works with non-`lfi` functions!
  array => array.sort(),
)

console.log(screamify([`sloth`, `lazy`, `sleep`]))
//=> [ 'SLOTH', 'LAZY', 'SLEEP' ]
Playground

Since

v0.0.2

curry

Returns a curried version of fn.

Example

import { curry } from 'lfi'

function slothLog(a, b, c) {
  console.log(`${a} Sloth ${b} Sloth ${c}`)
}

const curriedSlothLog = curry(slothLog)

console.log(curriedSlothLog.name)
//=> slothLog

console.log(curriedSlothLog.length)
//=> 3

curriedSlothLog(`Hello`, `World`, `!`)
curriedSlothLog(`Hello`)(`World`, `!`)
curriedSlothLog(`Hello`, `World`)(`!`)
curriedSlothLog(`Hello`)(`World`)(`!`)
//=> Hello Sloth World Sloth !
//=> Hello Sloth World Sloth !
//=> Hello Sloth World Sloth !
//=> Hello Sloth World Sloth !
Playground

Since

v0.0.1

emptyConcur

A concur iterable that contains zero values.

Can be used as a concur iterable of any type.

Like [], but for concur iterables.

Example

import { emptyConcur, pipe, reduceConcur, toArray } from 'lfi'

console.log(
  await pipe(
    emptyConcur,
    reduceConcur(toArray()),
  ),
)
//=> []
Playground

Since

v0.0.2

opaque

Returns an iterable equivalent, but not referentially equal, to iterable.

Example

import { opaque } from 'lfi'

const array = [`sloth`, `lazy`, `sleep`]
const iterable = opaque(array)

console.log(array === iterable)
//=> false

console.log([...iterable])
//=> [ 'sloth', 'lazy', 'sleep' ]
Playground

Since

v2.0.0

opaqueAsync

Returns an async iterable equivalent, but not referentially equal, to asyncIterable.

Example

import { asAsync, opaqueAsync, pipe, reduceAsync, toArray } from 'lfi'

const asyncIterable = asAsync([`sloth`, `lazy`, `sleep`])
asyncIterable.property = 42
const opaqueAsyncIterable = opaqueAsync(asyncIterable)

console.log(asyncIterable === opaqueAsyncIterable)
//=> false

console.log(opaqueAsyncIterable.property)
//=> undefined

console.log(
  await pipe(
    opaqueAsyncIterable,
    reduceAsync(toArray()),
  ),
)
//=> [ 'sloth', 'lazy', 'sleep' ]
Playground

Since

v2.0.0

opaqueConcur

Returns an concur iterable equivalent, but not referentially equal, to concurIterable.

Example

import { asConcur, opaqueConcur, pipe, reduceConcur, toArray } from 'lfi'

const concurIterable = asConcur([`sloth`, `lazy`, `sleep`])
concurIterable.property = 42
const opaqueConcurIterable = opaqueConcur(concurIterable)

console.log(concurIterable === opaqueConcurIterable)
//=> false

console.log(opaqueConcurIterable.property)
//=> undefined

console.log(
  await pipe(
    opaqueConcurIterable,
    reduceConcur(toArray()),
  ),
)
//=> [ 'sloth', 'lazy', 'sleep' ]
Playground

Since

v2.0.0

pipe

Returns the result of piping value through the given functions.

Example

import { map, pipe, reduce, toArray } from 'lfi'

console.log(
  pipe(
    [`sloth`, `lazy`, `sleep`],
    map(word => word.toUpperCase()),
    reduce(toArray()),
    // Also works with non-`lfi` functions!
    array => array.sort(),
  ),
)
//=> [ 'SLOTH', 'LAZY', 'SLEEP' ]
Playground

Since

v0.0.1

Filters​

FunctionDescription

exclude

Returns an iterable containing the values of iterable in iteration order excluding the values of excluded.

Example

import { exclude, pipe, reduce, toArray } from 'lfi'

console.log(
  pipe(
    [`sloth`, `lazy`, `active`, `sleep`, `awake`],
    exclude([`awake`, `active`]),
    reduce(toArray()),
  ),
)
//=> [ 'sloth', 'lazy', 'sleep' ]
Playground

Since

v2.0.0

excludeAsync

Returns an async iterable containing the values of asyncIterable in iteration order excluding the values of excluded.

Example

import { asAsync, excludeAsync, flatMapAsync, map, pipe, reduceAsync, toArray } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`

console.log(
  await pipe(
    asAsync([`sloth`, `lazy`, `sleep`]),
    flatMapAsync(async word => {
      const response = await fetch(`${API_URL}/${word}`)
      const [{ meanings }] = await response.json()
      return map(meaning => meaning.partOfSpeech, meanings)
    }),
    excludeAsync([`adjective`, `verb`]),
    reduceAsync(toArray()),
  ),
)
//=> [ 'noun', 'noun' ]
Playground

Since

v2.0.0

excludeConcur

Returns a concur iterable containing the values of concurIterable in iteration order excluding the values of excluded.

Example

import { asConcur, excludeConcur, flatMapConcur, map, pipe, reduceConcur, toArray } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`

console.log(
  await pipe(
    asConcur([`sloth`, `lazy`, `sleep`]),
    flatMapConcur(async word => {
      const response = await fetch(`${API_URL}/${word}`)
      const [{ meanings }] = await response.json()
      return map(meaning => meaning.partOfSpeech, meanings)
    }),
    excludeConcur([`adjective`, `verb`]),
    reduceConcur(toArray()),
  ),
)
//=> [ 'noun', 'noun' ]
Playground

Since

v2.0.0

filter

Returns an iterable that contains the values of iterable in iteration order excluding the values for which fn returns a falsy value.

Like Array.prototype.filter, but for iterables.

Example

import { filter, pipe, reduce, toArray } from 'lfi'

console.log(
  pipe(
    [`sloth`, `lazy`, `sleep`],
    filter(word => word.startsWith(`s`)),
    reduce(toArray()),
  ),
)
//=> [ 'sloth', 'sleep' ]
Playground

Since

v0.0.1

filterAsync

Returns an async iterable that contains the values of asyncIterable in iteration order excluding the values for which fn returns a value awaitable to a falsy value.

Like Array.prototype.filter, but for async iterables.

Example

import { asAsync, filterAsync, pipe, reduceAsync, toArray } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`

console.log(
  await pipe(
    asAsync([`sloth`, `lazy`, `sleep`]),
    filterAsync(async word => {
      const response = await fetch(`${API_URL}/${word}`)
      const [{ meanings }] = await response.json()
      return meanings.some(meaning => meaning.partOfSpeech === `adjective`)
    }),
    reduceAsync(toArray()),
  ),
)
//=> [ 'lazy' ]
Playground

Since

v0.0.1

filterConcur

Returns a concur iterable that contains the values of concurIterable excluding the values for which fn returns a value awaitable to a falsy value.

Like Array.prototype.filter, but for concur iterables.

Example

import { asConcur, filterConcur, pipe, reduceConcur, toArray } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`

console.log(
  await pipe(
    asConcur([`sloth`, `lazy`, `sleep`]),
    filterConcur(async word => {
      const response = await fetch(`${API_URL}/${word}`)
      const [{ meanings }] = await response.json()
      return meanings.some(meaning => meaning.partOfSpeech === `adjective`)
    }),
    reduceConcur(toArray()),
  ),
)
//=> [ 'lazy' ]
Playground

Since

v0.0.1

filterMap

Returns an iterable containing the values of iterable transformed by fn in iteration order excluding the values for which fn returns null or undefined.

Example

import { filterMap, pipe, reduce, toArray } from 'lfi'

console.log(
  pipe(
    [
      { sloth: `sloth` },
      { sloth: `lazy` },
      { notSloth: `active` },
      { sloth: `sleep` },
      { notSloth: `awake` },
    ],
    filterMap(object => object.sloth),
    reduce(toArray()),
  ),
)
//=> [ 'sloth', 'lazy', 'sleep' ]
Playground

Since

v0.0.1

filterMapAsync

Returns an async iterable containing the values of asyncIterable transformed by fn in iteration order excluding the values for which fn returns a value awaitable to null or undefined.

Example

import { asAsync, filterMapAsync, pipe, reduceAsync, toArray } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`

console.log(
  await pipe(
    asAsync([
      { sloth: `sloth` },
      { sloth: `lazy` },
      { notSloth: `active` },
      { sloth: `sleep` },
      { notSloth: `awake` },
    ]),
    filterMapAsync(async object => {
      if (!object.sloth) {
        return null
      }

      const response = await fetch(`${API_URL}/${object.sloth}`)
      return (await response.json())[0].phonetic
    }),
    reduceAsync(toArray()),
  ),
)
//=> [ '/slɑθ/', '/ˈleɪzi/', '/sliːp/' ]
Playground

Since

v0.0.1

filterMapConcur

Returns a concur iterable containing the values of concurIterable transformed by fn excluding the values for which fn returns a value awaitable to null or undefined.

Example

import { asConcur, filterMapConcur, pipe, reduceConcur, toArray } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`

console.log(
  await pipe(
    asConcur([
      { sloth: `sloth` },
      { sloth: `lazy` },
      { notSloth: `active` },
      { sloth: `sleep` },
      { notSloth: `awake` },
    ]),
    filterMapConcur(async object => {
      if (!object.sloth) {
        return null
      }

      const response = await fetch(`${API_URL}/${object.sloth}`)
      return (await response.json())[0].phonetic
    }),
    reduceConcur(toArray()),
  ),
)
// NOTE: This order may change between runs
//=> [ '/slɑθ/', '/ˈleɪzi/', '/sliːp/' ]
Playground

Since

v0.0.1

find

Returns an iterable containing the first value of iterable for which fn returns a truthy value. Otherwise, returns an empty iterable.

Like Array.prototype.find, but for iterables.

Example

import { find, or, pipe } from 'lfi'

console.log(
  pipe(
    [`sloth`, `lazy`, `sleep`],
    find(word => word.includes(`s`)),
    or(() => `not found!`),
  ),
)
//=> sloth

console.log(
  pipe(
    [`sloth`, `lazy`, `sleep`],
    find(word => word.includes(`x`)),
    or(() => `not found!`),
  ),
)
//=> not found!
Playground

Since

v0.0.1

findAsync

Returns an async iterable containing the first value of asyncIterable for which fn returns a value awaitable to a truthy value. Otherwise, returns an empty async iterable.

Like Array.prototype.find, but for async iterables.

Example

import { asAsync, findAsync, orAsync, pipe } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`
const getPartsOfSpeech = async word => {
  const response = await fetch(`${API_URL}/${word}`)
  const [{ meanings }] = await response.json()
  return meanings.map(meaning => meaning.partOfSpeech)
}

console.log(
  await pipe(
    asAsync([`sloth`, `lazy`, `sleep`]),
    findAsync(async word => (await getPartsOfSpeech(word)).includes(`verb`)),
    orAsync(() => `not found!`),
  ),
)
//=> sloth

console.log(
  await pipe(
    asAsync([`sloth`, `lazy`, `sleep`]),
    findAsync(async word => (await getPartsOfSpeech(word)).includes(`adverb`)),
    orAsync(() => `not found!`),
  ),
)
//=> not found!
Playground

Since

v0.0.1

findConcur

Returns a concur iterable containing the first value of concurIterable for which fn returns a value awaitable to a truthy value. Otherwise, returns an empty concur iterable.

Like Array.prototype.find, but for concur iterables.

Example

import { asConcur, findConcur, orConcur, pipe } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`
const getPartsOfSpeech = async word => {
  const response = await fetch(`${API_URL}/${word}`)
  const [{ meanings }] = await response.json()
  return meanings.map(meaning => meaning.partOfSpeech)
}

console.log(
  await pipe(
    asConcur([`sloth`, `lazy`, `sleep`]),
    findConcur(async word => (await getPartsOfSpeech(word)).includes(`verb`)),
    orConcur(() => `not found!`),
  ),
)
// NOTE: This word may change between runs
//=> sloth

console.log(
  await pipe(
    asConcur([`sloth`, `lazy`, `sleep`]),
    findConcur(async word => (await getPartsOfSpeech(word)).includes(`adverb`)),
    orConcur(() => `not found!`),
  ),
)
//=> not found!
Playground

Since

v0.0.1

findLast

Returns an iterable containing the last value of iterable for which fn returns a truthy value. Otherwise, returns an empty iterable.

Example

import { findLast, or, pipe } from 'lfi'

console.log(
  pipe(
    [`sloth`, `lazy`, `sleep`],
    findLast(word => word.includes(`s`)),
    or(() => `not found!`),
  ),
)
//=> sleep

console.log(
  pipe(
    [`sloth`, `lazy`, `sleep`],
    findLast(word => word.includes(`x`)),
    or(() => `not found!`),
  ),
)
//=> not found!
Playground

Since

v0.0.1

findLastAsync

Returns an async iterable containing the last value of asyncIterable for which fn returns a value awaitable to a truthy value. Otherwise, returns an empty async iterable.

Example

import { asAsync, findLastAsync, orAsync, pipe } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`
const getPartsOfSpeech = async word => {
  const response = await fetch(`${API_URL}/${word}`)
  const [{ meanings }] = await response.json()
  return meanings.map(meaning => meaning.partOfSpeech)
}

console.log(
  await pipe(
    asAsync([`sloth`, `lazy`, `sleep`]),
    findLastAsync(async word => (await getPartsOfSpeech(word)).includes(`verb`)),
    orAsync(() => `not found!`),
  ),
)
//=> sleep

console.log(
  await pipe(
    asAsync([`sloth`, `lazy`, `sleep`]),
    findLastAsync(async word => (await getPartsOfSpeech(word)).includes(`adverb`)),
    orAsync(() => `not found!`),
  ),
)
//=> not found!
Playground

Since

v0.0.1

findLastConcur

Returns a concur iterable containing the last value of concurIterable for which fn returns a value awaitable to a truthy value. Otherwise, returns an empty concur iterable.

Example

import { asConcur, findLastConcur, orConcur, pipe } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`
const getPartsOfSpeech = async word => {
  const response = await fetch(`${API_URL}/${word}`)
  const [{ meanings }] = await response.json()
  return meanings.map(meaning => meaning.partOfSpeech)
}

console.log(
  await pipe(
    asConcur([`sloth`, `lazy`, `sleep`]),
    findLastConcur(async word => (await getPartsOfSpeech(word)).includes(`verb`)),
    orConcur(() => `not found!`),
  ),
)
// NOTE: This word may change between runs
//=> sleep

console.log(
  await pipe(
    asConcur([`sloth`, `lazy`, `sleep`]),
    findLastConcur(async word => (await getPartsOfSpeech(word)).includes(`adverb`)),
    orConcur(() => `not found!`),
  ),
)
//=> not found!
Playground

Since

v0.0.2

unique

Returns an iterable containing the values of iterable in iteration order, except values are deduplicated if they are equal using Object.is.

Example

import { pipe, reduce, toArray, unique } from 'lfi'

console.log(
  pipe(
    [`sloth`, `lazy`, `lazy`, `sleep`, `sloth`],
    unique,
    reduce(toArray()),
  ),
)
//=> [ 'sloth', 'lazy', 'sleep' ]
Playground

Since

v0.0.1

uniqueAsync

Returns an async iterable containing the values of asyncIterable in iteration order, except values are deduplicated if they are equal using Object.is.

Example

import { asAsync, flatMapAsync, map, pipe, reduceAsync, toArray, uniqueAsync } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`

console.log(
  await pipe(
    asAsync([`sloth`, `lazy`, `sleep`]),
    flatMapAsync(async word => {
      const response = await fetch(`${API_URL}/${word}`)
      const [{ meanings }] = await response.json()
      return map(meaning => meaning.partOfSpeech, meanings)
    }),
    uniqueAsync,
    reduceAsync(toArray()),
  ),
)
//=> [ 'noun', 'verb', 'adjective' ]
Playground

Since

v0.0.2

uniqueBy

Returns an iterable containing the values of iterable in iteration order, except values for which fn returns the same value are deduplicated.

When values are deduplicated, the value earlier in iteration order wins.

Example

import { pipe, reduce, toArray, uniqueBy } from 'lfi'

console.log(
  pipe(
    [`sloth`, `lazy`, `sleep`],
    uniqueBy(word => word.length),
    reduce(toArray()),
  ),
)
//=> [ 'sloth', 'lazy' ]
Playground

Since

v0.0.1

uniqueByAsync

Returns an async iterable containing the values of asyncIterable in iteration order, except values for which fn returns a value awaitable to the same value are deduplicated.

When values are deduplicated, the value earlier in iteration order wins.

Example

import { asAsync, pipe, reduceAsync, toArray, uniqueByAsync } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`

console.log(
  await pipe(
    asAsync([`sloth`, `lazy`, `sleep`]),
    uniqueByAsync(async word => {
      const response = await fetch(`${API_URL}/${word}`)
      const [{ meanings }] = await response.json()
      return meanings[0].partOfSpeech
    }),
    reduceAsync(toArray()),
  ),
)
//=> [ 'sloth', 'sleep' ]
Playground

Since

v0.0.2

uniqueByConcur

Returns a concur iterable containing the values of concurIterable, except values for which fn returns a value awaitable to the same value are deduplicated.

When values are deduplicated, the value earlier in iteration order wins.

Example

import { asConcur, pipe, reduceConcur, toArray, uniqueByConcur } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`

console.log(
  await pipe(
    asConcur([`sloth`, `lazy`, `sleep`]),
    uniqueByConcur(async word => {
      const response = await fetch(`${API_URL}/${word}`)
      const [{ meanings }] = await response.json()
      return meanings[0].partOfSpeech
    }),
    reduceConcur(toArray()),
  ),
)
// NOTE: These words may change between runs
//=> [ 'sloth', 'sleep' ]
Playground

Since

v0.0.2

uniqueConcur

Returns a concur iterable containing the values of concurIterable in iteration order, except values are deduplicated if they are equal using Object.is.

Example

import { asConcur, flatMapConcur, map, pipe, reduceConcur, toArray, uniqueConcur } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`

console.log(
  await pipe(
    asConcur([`sloth`, `lazy`, `sleep`]),
    flatMapConcur(async word => {
      const response = await fetch(`${API_URL}/${word}`)
      const [{ meanings }] = await response.json()
      return map(meaning => meaning.partOfSpeech, meanings)
    }),
    uniqueConcur,
    reduceConcur(toArray()),
  ),
)
// NOTE: This order may change between runs
//=> [ 'noun', 'verb', 'adjective' ]
Playground

Since

v0.0.2

Generators​

Type alias, FunctionDescription

RangeIterable

An iterable that yields integers in a range.

See RangeIterable.step for obtaining a new iterable that skips integers in steps.

Since

v2.0.0

cycle

Returns an infinite iterable that repeatedly yields the values of iterable in iteration order.

WARNING: This function does not buffer the values of iterable for future cycles. It reiterates iterable each cycle.

Example

import { cycle, join, pipe, take } from 'lfi'

console.log(
  pipe(
    cycle([`sloth`, `lazy`]),
    take(6),
    join(`, `),
  ),
)
//=> sloth, lazy, sloth, lazy, sloth, lazy
Playground

Since

v0.0.1

cycleAsync

Returns an infinite async iterable that repeatedly yields the values of asyncIterable.

WARNING: This function does not buffer the values of asyncIterable for future cycles. It reiterates asyncIterable each cycle.

Example

import { asAsync, cycleAsync, joinAsync, mapAsync, pipe, takeAsync } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`

console.log(
  await pipe(
    asAsync([`sloth`, `lazy`, `sleep`]),
    mapAsync(async word => {
      const response = await fetch(`${API_URL}/${word}`)
      return (await response.json())[0].phonetic
    }),
    cycleAsync,
    takeAsync(6),
    joinAsync(`, `),
  ),
)
//=> /slɑθ/, /ˈleɪzi/, /sliːp/, /slɑθ/, /ˈleɪzi/, /sliːp/
Playground

Since

v0.0.1

entries

Returns an iterable containing the entries of object.

This differs from Map.prototype.entries in that the returned iterable can be iterated multiple times and differs from Object.entries in that the returned iterable is opaque.

Example

import { entries, pipe, reduce, toArray } from 'lfi'

console.log(
  pipe(
    entries([`sloth`, `lazy`, `sleep`]),
    reduce(toArray()),
  ),
)
//=> [
//=>   [ 0, 'sloth' ],
//=>   [ 1, 'lazy' ],
//=>   [ 2, 'sleep' ]
//=> ]

console.log(
  pipe(
    entries({
      sloth: 1,
      lazy: 2,
      sleep: 3,
    }),
    reduce(toArray()),
  ),
)
//=> [
//=>   [ 'sloth', 1 ],
//=>   [ 'lazy', 2 ],
//=>   [ 'sleep', 3 ]
//=> ]

console.log(
  pipe(
    entries(
      new Map([
        [`sloth`, 1],
        [`lazy`, 2],
        [`sleep`, 3],
      ]),
    ),
    reduce(toArray()),
  ),
)
//=> [
//=>   [ 'sloth', 1 ],
//=>   [ 'lazy', 2 ],
//=>   [ 'sleep', 3 ]
//=> ]
Playground

Since

v0.1.0

generate

Returns an infinite iterable that yields seed for its first value and then yields the result of applying fn to its previously yielded value for every subsequent value.

Example

import { generate, pipe, reduce, take, toArray } from 'lfi'

console.log(
  pipe(
    `sloth`,
    generate(previousValue => `${previousValue} ${previousValue}`),
    take(4),
    reduce(toArray()),
  ),
)
//=> [
//=>   'sloth',
//=>   'sloth sloth',
//=>   'sloth sloth sloth sloth',
//=>   'sloth sloth sloth sloth sloth sloth sloth sloth'
//=> ]
Playground

Since

v0.0.1

generateAsync

Returns an infinite async iterable that yields seed for its first value and then yields the awaited result of applying fn to its previously yielded value for every subsequent value.

Example

import { generateAsync, pipe, reduceAsync, takeAsync, toArray } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`

console.log(
  await pipe(
    `sleep`,
    generateAsync(async previousWord => {
      const response = await fetch(`${API_URL}/${previousWord}`)
      const [{ meanings }] = await response.json()
      return meanings[0].partOfSpeech
    }),
    takeAsync(4),
    reduceAsync(toArray()),
  ),
)
//=> [ 'sleep', 'verb', 'noun', 'noun' ]
Playground

Since

v0.0.1

keys

Returns an iterable containing the keys of object.

This differs from Map.prototype.keys in that the returned iterable can be iterated multiple times and differs from Object.keys in that the returned iterable is opaque.

Example

import { keys, pipe, reduce, toArray } from 'lfi'

console.log(
  pipe(
    keys([`sloth`, `lazy`, `sleep`]),
    reduce(toArray()),
  ),
)
//=> [ 0, 1, 2 ]

console.log(
  pipe(
    keys({
      sloth: 1,
      lazy: 2,
      sleep: 3,
    }),
    reduce(toArray()),
  ),
)
//=> [ 'sloth', 'lazy', 'sleep' ]

console.log(
  pipe(
    keys(
      new Map([
        [`sloth`, 1],
        [`lazy`, 2],
        [`sleep`, 3],
      ]),
    ),
    reduce(toArray()),
  ),
)
//=> [ 'sloth', 'lazy', 'sleep' ]
Playground

Since

v0.1.0

rangeTo

Returns a RangeIterable that yields the integers between start and end, including start and end.

Throws

if either start or end is not an integer.

Example

import { join, pipe, rangeTo } from 'lfi'

console.log(
  pipe(
    rangeTo(0, 6),
    join(`, `),
  ),
)
//=> 0, 1, 2, 3, 4, 5, 6

console.log(
  pipe(
    rangeTo(0, 6).step(2),
    join(`, `),
  ),
)
//=> 0, 2, 4, 6
Playground

Since

v0.0.1

rangeUntil

Returns a RangeIterable that yields the integers between start and end including start, but excluding end.

Throws

if either start or end is not an integer.

Example

import { join, pipe, rangeUntil } from 'lfi'

console.log(
  pipe(
    rangeUntil(0, 6),
    join(`, `),
  ),
)
//=> 0, 1, 2, 3, 4, 5

console.log(
  pipe(
    rangeUntil(0, 6).step(2),
    join(`, `),
  ),
)
//=> 0, 2, 4
Playground

Since

v0.0.1

repeat

Returns an infinite iterable that repeatedly yields value.

Example

import { join, pipe, repeat, take } from 'lfi'

console.log(
  pipe(
    repeat(`sloth`),
    take(4),
    join(`, `),
  ),
)
//=> sloth, sloth, sloth, sloth
Playground

Since

v0.0.1

values

Returns an iterable containing the values of object.

This differs from Map.prototype.values and Set.prototype.values in that the returned iterable can be iterated multiple times and differs from Object.values in that the returned iterable is opaque.

Example

import { pipe, reduce, toArray, values } from 'lfi'

console.log(
  pipe(
    values([`sloth`, `lazy`, `sleep`]),
    reduce(toArray()),
  ),
)
//=> [ 'sloth', 'lazy, 'sleep' ]

console.log(
  pipe(
    values({
      sloth: 1,
      lazy: 2,
      sleep: 3,
    }),
    reduce(toArray()),
  ),
)
//=> [ 1, 2, 3 ]

console.log(
  pipe(
    values(new Set([`sloth`, `lazy`, `sleep`])),
    reduce(toArray()),
  ),
)
//=> [ 'sloth', 'lazy, 'sleep' ]

console.log(
  pipe(
    values(
      new Map([
        [`sloth`, 1],
        [`lazy`, 2],
        [`sleep`, 3],
      ]),
    ),
    reduce(toArray()),
  ),
)
//=> [ 1, 2, 3 ]
Playground

Since

v0.1.0

Optionals​

Type alias, FunctionDescription

AsyncOptional

An async iterable containing exactly zero or one values.

Since

v2.0.0

ConcurOptional

A concur iterable containing exactly zero or one values.

Since

v2.0.0

Optional

An iterable containing exactly zero or one values.

Since

v2.0.0

get

Returns the only value in iterable if it contains exactly one value. Otherwise, throws an error.

Example

import { get } from 'lfi'

console.log(get([`sloth`]))
//=> sloth

try {
  console.log(get([]))
} catch {
  console.log(`Oh no! It was empty...`)
}
//=> Oh no! It was empty...

try {
  console.log(get([`sloth`, `lazy`, `sleep`]))
} catch {
  console.log(`Oh no! It had more than one value...`)
}
//=> Oh no! It had more than one value...
Playground

Since

v0.0.1

getAsync

Returns a promise that resolves to the only value in asyncIterable if it contains exactly one value. Otherwise, returns a promise that rejects.

Example

import { asAsync, findAsync, getAsync, pipe } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`

const findWordWithPartOfSpeech = partOfSpeech =>
  pipe(
    asAsync([`sloth`, `lazy`, `sleep`]),
    findAsync(async word => {
      const response = await fetch(`${API_URL}/${word}`)
      const [{ meanings }] = await response.json()
      return meanings.some(meaning => meaning.partOfSpeech === partOfSpeech)
    }),
    getAsync,
  )

console.log(await findWordWithPartOfSpeech(`noun`))
//=> sloth
console.log(await findWordWithPartOfSpeech(`verb`))
//=> sloth
console.log(await findWordWithPartOfSpeech(`adjective`))
//=> lazy
try {
  console.log(await findWordWithPartOfSpeech(`adverb`))
} catch {
  console.log(`Oh no! It was empty...`)
}
//=> Oh no! It was empty...
Playground

Since

v0.0.1

getConcur

Returns a promise that resolves to the only value in concurIterable if it contains exactly one value. Otherwise, returns a promise that rejects.

Example

import { asConcur, findConcur, getConcur, pipe } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`

const findWordWithPartOfSpeech = partOfSpeech =>
  pipe(
    asConcur([`sloth`, `lazy`, `sleep`]),
    findConcur(async word => {
      const response = await fetch(`${API_URL}/${word}`)
      const [{ meanings }] = await response.json()
      return meanings.some(meaning => meaning.partOfSpeech === partOfSpeech)
    }),
    getConcur,
  )

console.log(await findWordWithPartOfSpeech(`noun`))
// NOTE: This word may change between runs
//=> sloth
console.log(await findWordWithPartOfSpeech(`verb`))
// NOTE: This word may change between runs
//=> sloth
console.log(await findWordWithPartOfSpeech(`adjective`))
//=> lazy
try {
  console.log(await findWordWithPartOfSpeech(`adverb`))
} catch {
  console.log(`Oh no! It was empty...`)
}
//=> Oh no! It was empty...
Playground

Since

v0.0.2

next

Returns a pair of iterables. If iterable is empty, then both of the returned iterables are empty. Otherwise, the first iterable contains the first value of iterable and the second iterable contains the rest of the values of iterable. The second iterable can only be iterated once.

Example

import { count, get, next } from 'lfi'

const [first, rest] = next([`sloth`, `lazy`, `sleep`])

console.log(get(first))
//=> sloth

console.log([...rest])
//=> [ 'lazy', 'sleep' ]

const [first2, rest2] = next([])

console.log(count(first2))
//=> 0

console.log(count(rest2))
//=> 0
Playground

Since

v0.0.1

nextAsync

Returns a promise that resolves to a pair of async iterables. If asyncIterable is empty, then both of the returned async iterables are empty. Otherwise, the first async iterable contains the first value of asyncIterable and the second async iterable contains the rest of the values of asyncIterable. The second async iterable can only be iterated once.

Example

import { asAsync, countAsync, emptyAsync, getAsync, mapAsync, nextAsync, pipe, reduceAsync, toArray } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`

const [first, rest] = await pipe(
  asAsync([`sloth`, `lazy`, `sleep`]),
  mapAsync(async word => {
    const response = await fetch(`${API_URL}/${word}`)
    return (await response.json())[0].phonetic
  }),
  nextAsync,
)

console.log(await getAsync(first))
//=> /slɑθ/

console.log(
  await pipe(
    rest,
    reduceAsync(toArray()),
  ),
)
//=> [ '/ˈleɪzi/', '/sliːp/' ]

const [first2, rest2] = await nextAsync(emptyAsync)

console.log(await countAsync(first2))
//=> 0

console.log(await countAsync(rest2))
//=> 0
Playground

Since

v0.0.1

or

Returns the only value in iterable if it contains exactly one value. Otherwise, returns the result of invoking fn.

Example

import { or, pipe } from 'lfi'

console.log(
  pipe(
    [`sloth`],
    or(() => `never called`),
  ),
)
//=> sloth

console.log(
  pipe(
    [],
    or(() => `called!`),
  ),
)
//=> called!

console.log(
  pipe(
    [`sloth`, `lazy`, `sleep`],
    or(() => `called!`),
  ),
)
//=> called!
Playground

Since

v0.0.1

orAsync

Returns a promise that resolves to the only value in asyncIterable if it contains exactly one value. Otherwise, returns a promise that resolves to the awaited result of invoking fn.

Example

import { asAsync, findAsync, orAsync, pipe } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`

const findWordWithPartOfSpeech = partOfSpeech =>
  pipe(
    asAsync([`sloth`, `lazy`, `sleep`]),
    findAsync(async word => {
      const response = await fetch(`${API_URL}/${word}`)
      const [{ meanings }] = await response.json()
      return meanings.some(meaning => meaning.partOfSpeech === partOfSpeech)
    }),
    orAsync(() => `no ${partOfSpeech}???`),
  )

console.log(await findWordWithPartOfSpeech(`noun`))
//=> sloth
console.log(await findWordWithPartOfSpeech(`verb`))
//=> sloth
console.log(await findWordWithPartOfSpeech(`adjective`))
//=> lazy
console.log(await findWordWithPartOfSpeech(`adverb`))
//=> no adverb???
Playground

Since

v0.0.1

orConcur

Returns a promise that resolves to the only value in concurIterable if it contains exactly one value. Otherwise, returns a promise that resolves to the awaited result of invoking fn.

Example

import { asConcur, findConcur, orConcur, pipe } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`

const findWordWithPartOfSpeech = partOfSpeech =>
  pipe(
    asConcur([`sloth`, `lazy`, `sleep`]),
    findConcur(async word => {
      const response = await fetch(`${API_URL}/${word}`)
      const [{ meanings }] = await response.json()
      return meanings.some(meaning => meaning.partOfSpeech === partOfSpeech)
    }),
    orConcur(() => `no ${partOfSpeech}???`),
  )

console.log(await findWordWithPartOfSpeech(`noun`))
// NOTE: This word may change between runs
//=> sloth
console.log(await findWordWithPartOfSpeech(`verb`))
// NOTE: This word may change between runs
//=> sloth
console.log(await findWordWithPartOfSpeech(`adjective`))
//=> lazy
console.log(await findWordWithPartOfSpeech(`adverb`))
//=> no adverb???
Playground

Since

v0.0.2

Predicates​

FunctionDescription

all

Returns true if fn returns a truthy value for all values of iterable. Otherwise returns false.

Like Array.prototype.every, but for iterables.

Example

import { all, pipe } from 'lfi'

console.log(
  pipe(
    [`sloth`, `lazy`, `sleep`],
    all(word => word.includes(`l`)),
  ),
)
//=> true

console.log(
  pipe(
    [`sloth`, `lazy`, `sleep`],
    all(word => word.includes(`s`)),
  ),
)
//=> false
Playground

Since

v0.0.1

allAsync

Returns a promise that resolves to true if fn returns a truthy value or a promise that resolves to a truthy value for all values of asyncIterable. Otherwise returns a promise that resolves to false.

Like Array.prototype.every, but for async iterables.

Example

import { allAsync, asAsync, pipe } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`
const getPartsOfSpeech = async word => {
  const response = await fetch(`${API_URL}/${word}`)
  const [{ meanings }] = await response.json()
  return meanings.map(meaning => meaning.partOfSpeech)
}

console.log(
  await pipe(
    asAsync([`sloth`, `lazy`, `sleep`]),
    allAsync(async word => (await getPartsOfSpeech(word)).includes(`verb`)),
  ),
)
//=> true

console.log(
  await pipe(
    asAsync([`sloth`, `lazy`, `sleep`]),
    allAsync(async word => (await getPartsOfSpeech(word)).includes(`noun`)),
  ),
)
//=> false
Playground

Since

v0.0.1

allConcur

Returns a promise that resolves to true if fn returns a truthy value or a promise that resolves to a truthy value for all values of concurIterable. Otherwise returns a promise that resolves to false.

Like Array.prototype.every, but for concur iterables.

Example

import { allConcur, asConcur, pipe } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`
const getPartsOfSpeech = async word => {
  const response = await fetch(`${API_URL}/${word}`)
  const [{ meanings }] = await response.json()
  return meanings.map(meaning => meaning.partOfSpeech)
}

console.log(
  await pipe(
    asConcur([`sloth`, `lazy`, `sleep`]),
    allConcur(async word => (await getPartsOfSpeech(word)).includes(`verb`)),
  ),
)
//=> true

console.log(
  await pipe(
    asConcur([`sloth`, `lazy`, `sleep`]),
    allConcur(async word => (await getPartsOfSpeech(word)).includes(`noun`)),
  ),
)
//=> false
Playground

Since

v0.0.2

any

Returns true if fn returns a truthy value for any value of iterable. Otherwise returns false.

Like Array.prototype.some, but for iterables.

Example

import { any, pipe } from 'lfi'

console.log(
  pipe(
    [`sloth`, `lazy`, `sleep`],
    any(word => word.includes(`s`)),
  ),
)
//=> true

console.log(
  pipe(
    [`sloth`, `lazy`, `sleep`],
    any(word => word.includes(`x`)),
  ),
)
//=> false
Playground

Since

v0.0.1

anyAsync

Returns a promise that resolves to true if fn returns a truthy value or a promise that resolves to a truthy value for any value of asyncIterable. Otherwise returns a promise that resolves to false.

Like Array.prototype.some, but for async iterables.

Example

import { anyAsync, asAsync, pipe } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`
const getPartsOfSpeech = async word => {
  const response = await fetch(`${API_URL}/${word}`)
  const [{ meanings }] = await response.json()
  return meanings.map(meaning => meaning.partOfSpeech)
}

console.log(
  await pipe(
    asAsync([`sloth`, `lazy`, `sleep`]),
    anyAsync(async word => (await getPartsOfSpeech(word)).includes(`noun`)),
  ),
)
//=> true

console.log(
  await pipe(
    asAsync([`sloth`, `lazy`, `sleep`]),
    anyAsync(async word => (await getPartsOfSpeech(word)).includes(`adverb`)),
  ),
)
//=> false
Playground

Since

v0.0.1

anyConcur

Returns a promise that resolves to true if fn returns a truthy value or a promise that resolves to a truthy value for any value of concurIterable. Otherwise returns a promise that resolves to false.

Like Array.prototype.some, but for concur iterables.

Example

import { anyConcur, asConcur, pipe } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`
const getPartsOfSpeech = async word => {
  const response = await fetch(`${API_URL}/${word}`)
  const [{ meanings }] = await response.json()
  return meanings.map(meaning => meaning.partOfSpeech)
}

console.log(
  await pipe(
    asConcur([`sloth`, `lazy`, `sleep`]),
    anyConcur(async word => (await getPartsOfSpeech(word)).includes(`noun`)),
  ),
)
//=> true

console.log(
  await pipe(
    asConcur([`sloth`, `lazy`, `sleep`]),
    anyConcur(async word => (await getPartsOfSpeech(word)).includes(`adverb`)),
  ),
)
//=> false
Playground

Since

v0.0.2

includes

Returns true if any value of iterable is equal to searchElement using Object.is. Otherwise returns false.

Like Array.prototype.includes, but for iterables.

Example

import { includes, pipe } from 'lfi'

console.log(
  pipe(
    [`sloth`, `lazy`, `sleep`],
    includes(`lazy`),
  ),
)
//=> true

console.log(
  pipe(
    [`sloth`, `lazy`, `sleep`],
    includes(`awake`),
  ),
)
//=> false
Playground

Since

v0.0.2

includesAsync

Returns a promise that resolves to true if any value of asyncIterable is equal to searchElement using Object.is. Otherwise returns a promise that resolves to false.

Like Array.prototype.includes, but for async iterables.

Example

import { asAsync, flatMapAsync, includesAsync, pipe } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`
const getPartsOfSpeech = async word => {
  const response = await fetch(`${API_URL}/${word}`)
  const [{ meanings }] = await response.json()
  return meanings.map(meaning => meaning.partOfSpeech)
}

console.log(
  await pipe(
    asAsync([`sloth`, `lazy`, `sleep`]),
    flatMapAsync(getPartsOfSpeech),
    includesAsync(`noun`),
  ),
)
//=> true

console.log(
  await pipe(
    asAsync([`sloth`, `lazy`, `sleep`]),
    flatMapAsync(getPartsOfSpeech),
    includesAsync(`adverb`),
  ),
)
//=> false
Playground

Since

v0.0.2

includesConcur

Returns a promise that resolves to true if any value of concurIterable is equal to searchElement using Object.is. Otherwise returns a promise that resolves to false.

Like Array.prototype.includes, but for concur iterables.

Example

import { asConcur, flatMapConcur, includesConcur, pipe } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`
const getPartsOfSpeech = async word => {
  const response = await fetch(`${API_URL}/${word}`)
  const [{ meanings }] = await response.json()
  return meanings.map(meaning => meaning.partOfSpeech)
}

console.log(
  await pipe(
    asConcur([`sloth`, `lazy`, `sleep`]),
    flatMapConcur(getPartsOfSpeech),
    includesConcur(`noun`),
  ),
)
//=> true

console.log(
  await pipe(
    asConcur([`sloth`, `lazy`, `sleep`]),
    flatMapConcur(getPartsOfSpeech),
    includesConcur(`adverb`),
  ),
)
//=> false
Playground

Since

v0.0.2

none

Returns true if fn returns a falsy value for all values of iterable. Otherwise returns false.

Example

import { none, pipe } from 'lfi'

console.log(
  pipe(
    [`sloth`, `lazy`, `sleep`],
    none(word => word.includes(`s`)),
  ),
)
//=> false

console.log(
  pipe(
    [`sloth`, `lazy`, `sleep`],
    none(word => word.includes(`x`)),
  ),
)
//=> true
Playground

Since

v0.0.1

noneAsync

Returns a promise that resolves to true if fn returns a falsy value or a promise that resolves to a falsy value for all values of asyncIterable. Otherwise returns a promise that resolves to false.

Example

import { noneAsync, asAsync, pipe } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`
const getPartsOfSpeech = async word => {
  const response = await fetch(`${API_URL}/${word}`)
  const [{ meanings }] = await response.json()
  return meanings.map(meaning => meaning.partOfSpeech)
}

console.log(
  await pipe(
    asAsync([`sloth`, `lazy`, `sleep`]),
    noneAsync(async word => (await getPartsOfSpeech(word)).includes(`noun`)),
  ),
)
//=> false

console.log(
  await pipe(
    asAsync([`sloth`, `lazy`, `sleep`]),
    noneAsync(async word => (await getPartsOfSpeech(word)).includes(`adverb`)),
  ),
)
//=> true
Playground

Since

v0.0.1

noneConcur

Returns a promise that resolves to true if fn returns a falsy value or a promise that resolves to a falsy value for all values of concurIterable. Otherwise returns a promise that resolves to false.

Example

import { noneConcur, asConcur, pipe } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`
const getPartsOfSpeech = async word => {
  const response = await fetch(`${API_URL}/${word}`)
  const [{ meanings }] = await response.json()
  return meanings.map(meaning => meaning.partOfSpeech)
}

console.log(
  await pipe(
    asConcur([`sloth`, `lazy`, `sleep`]),
    noneConcur(async word => (await getPartsOfSpeech(word)).includes(`noun`)),
  ),
)
//=> true

console.log(
  await pipe(
    asConcur([`sloth`, `lazy`, `sleep`]),
    noneConcur(async word => (await getPartsOfSpeech(word)).includes(`adverb`)),
  ),
)
//=> false
Playground

Since

v0.0.2

Reducers​

Type alias, Variable, FunctionDescription

AsyncFunctionReducer

An async reducer that reduces by combining pairs of values using function application.

Since

v2.0.0

AsyncKeyedReducer

An async keyed reducer that reduces by creating an initial accumulator using RawAsyncReducerWithoutFinish.create and then adding key-value pairs to the accumulator values using RawAsyncReducerWithoutFinish.add. The async keyed reducer is optionally able to combine pairs of accumulators using RawAsyncReducerWithoutFinish.combine. The accumulator can be queried for values by key using RawAsyncKeyedReducer.get.

Since

v2.0.0

AsyncOptionalReducer

An async reducer that reduces by combining pairs of values using RawAsyncOptionalReducerWithoutFinish.add and then transforming the final value using RawAsyncOptionalReducerWithFinish.finish.

Since

v2.0.0

AsyncReducer

An async reducer that reduces by creating an initial accumulator using RawAsyncReducerWithoutFinish.create, then adding values to the accumulator values using RawAsyncReducerWithoutFinish.add, and then transforming the final accumulator using RawAsyncReducerWithFinish.finish. The async reducer is optionally able to combine pairs of accumulators using RawAsyncReducerWithoutFinish.combine.

Since

v2.0.0

FunctionReducer

A reducer that reduces by combining pairs of values using function application.

Example

import { or, pipe, reduce } from 'lfi'

console.log(
  pipe(
    [1, 2, 3, 4],
    reduce(
      // This is a `FunctionReducer`
      (number1, number2) => number1 + number2,
    ),
    or(() => 0),
  ),
)
//=> 10
Playground

Since

v2.0.0

KeyedReducer

A keyed reducer that reduces by creating an initial accumulator using RawReducerWithoutFinish.create and then adding key-value pairs to the accumulator values using RawReducerWithoutFinish.add. The accumulator can be queried for values by key using RawKeyedReducer.get.

Since

v2.0.0

OptionalReducer

A reducer that reduces by combining pairs of values using RawOptionalReducerWithoutFinish.add and then transforming the final value using RawOptionalReducerWithFinish.finish.

It's identical to RawOptionalReducerWithFinish except its this is bound by normalizeReducer.

Example

import { or, pipe, reduce } from 'lfi'

console.log(
  pipe(
    [1, 2, 3, 4],
    reduce(
      // This will be an `OptionalReducer` once it's normalized by `reduce`
      {
        add: (number1, number2) => number1 + number2,
        finish: sum => `The sum is ${sum}`,
      },
    ),
    or(() => `There are no numbers`),
  ),
)
//=> The sum is 10
Playground

Since

v2.0.0

RawAsyncKeyedReducer

An async keyed reducer that reduces by creating an initial accumulator using RawAsyncReducerWithoutFinish.create and then adding key-value pairs to the accumulator values using RawAsyncReducerWithoutFinish.add. The async keyed reducer is optionally able to combine pairs of accumulators using RawAsyncReducerWithoutFinish.combine. The accumulator can be queried for values by key using RawAsyncKeyedReducer.get.

Since

v2.0.0

RawAsyncOptionalReducerWithFinish

An async reducer that reduces by combining pairs of values using RawAsyncOptionalReducerWithoutFinish.add and then transforming the final value using RawAsyncOptionalReducerWithFinish.finish.

Since

v2.0.0

RawAsyncOptionalReducerWithoutFinish

An async reducer that reduces by combining pairs of values using RawAsyncOptionalReducerWithoutFinish.add.

Since

v2.0.0

RawAsyncReducerWithFinish

An async reducer that reduces by creating an initial accumulator using RawAsyncReducerWithoutFinish.create, then adding values to the accumulator values using RawAsyncReducerWithoutFinish.add, and then transforming the final accumulator using RawAsyncReducerWithFinish.finish. The async reducer is optionally able to combine pairs of accumulators using RawAsyncReducerWithoutFinish.combine.

Since

v2.0.0

RawAsyncReducerWithoutFinish

An async reducer that reduces by creating an initial accumulator using RawAsyncReducerWithoutFinish.create and then adding values to the accumulator values using RawAsyncReducerWithoutFinish.add. The async reducer is optionally able to combine pairs of accumulators using RawAsyncReducerWithoutFinish.combine.

Since

v2.0.0

RawKeyedReducer

A keyed reducer that reduces by creating an initial accumulator using RawReducerWithoutFinish.create and then adding key-value pairs to the accumulator values using RawReducerWithoutFinish.add. The accumulator can be queried for values by key using RawKeyedReducer.get.

Since

v2.0.0

RawOptionalReducerWithFinish

A reducer that reduces by combining pairs of values using RawOptionalReducerWithoutFinish.add and then transforming the final value using RawOptionalReducerWithFinish.finish.

Example

import { or, pipe, reduce } from 'lfi'

console.log(
  pipe(
    [1, 2, 3, 4],
    reduce(
      // This is a `RawOptionalReducerWithFinish`
      {
        add: (number1, number2) => number1 + number2,
        finish: sum => `The sum is ${sum}`,
      },
    ),
    or(() => `There are no numbers`),
  ),
)
//=> The sum is 10
Playground

Since

v2.0.0

RawOptionalReducerWithoutFinish

A reducer that reduces by combining pairs of values using RawOptionalReducerWithoutFinish.add.

Example

import { or, pipe, reduce } from 'lfi'

console.log(
  pipe(
    [1, 2, 3, 4],
    reduce(
      // This is a `RawOptionalReducerWithoutFinish`
      {
        add: (number1, number2) => number1 + number2,
      },
    ),
    or(() => 0),
  ),
)
//=> 10
Playground

Since

v2.0.0

RawReducerWithFinish

A reducer that reduces by creating an initial accumulator using RawReducerWithoutFinish.create, then adding values to the accumulator values using RawReducerWithoutFinish.add, and then transforming the final accumulator using RawReducerWithFinish.finish.

Example

import { pipe, reduce } from 'lfi'

console.log(
  pipe(
    [1, 2, 3, 4],
    reduce(
      // This is a `RawReducerWithFinish`
      {
        create: () => 0,
        add: (number1, number2) => number1 + number2,
        finish: sum => `The sum is ${sum}`,
      },
    ),
  ),
)
//=> The sum is 10
Playground

Since

v2.0.0

RawReducerWithoutFinish

A reducer that reduces by creating an initial accumulator using RawReducerWithoutFinish.create and then adding values to the accumulator values using RawReducerWithoutFinish.add.

Example

import { pipe, reduce } from 'lfi'

console.log(
  pipe(
    [1, 2, 3, 4],
    reduce(
      // This is a `RawReducerWithoutFinish`
      {
        create: () => 0,
        add: (number1, number2) => number1 + number2,
      },
    ),
  ),
)
//=> 10
Playground

Since

v2.0.0

Reducer

A reducer that reduces by creating an initial accumulator using RawReducerWithoutFinish.create, then adding values to the accumulator values using RawReducerWithoutFinish.add, and then transforming the final accumulator using RawReducerWithFinish.finish.

It's identical to RawReducerWithFinish except its this is bound by normalizeReducer.

Example

import { pipe, reduce } from 'lfi'

console.log(
  pipe(
    [1, 2, 3, 4],
    reduce(
      // This will be a `Reducer` once it's normalized by `reduce`
      {
        create: () => 0,
        add: (number1, number2) => number1 + number2,
        finish: sum => `The sum is ${sum}`,
      },
    ),
  ),
)
//=> The sum is 10
Playground

Since

v2.0.0

NO_ENTRY

A unique value representing the lack of an entry for some key in a KeyedReducer or AsyncKeyedReducer.

Keyed reducers use this instead of null or undefined because they are valid values. Furthermore, introducing a has method for the purpose of disambiguation would be less performant due to the need to perform the lookup twice when the entry exists: has followed by get for the same key.

Since

v2.0.0

mapAsyncReducer

Returns an AsyncReducer equivalent to reducer except its final value is transformed using fn.

Since

v2.0.0

mapReducer

Returns a Reducer or OptionalReducer equivalent to reducer except its final value is transformed using fn.

Since

v2.0.0

normalizeReducer

Returns a non-raw version of reducer.

Since

v2.0.0

reduce

Returns the result of reducing iterable using reducer.

An initial accumulator is created using RawReducerWithoutFinish.create. Then each value in iterable is added to the accumulator and the current accumulator is updated using RawReducerWithoutFinish.add. Finally, the resulting accumulator is transformed using RawReducerWithFinish.finish if specified.

If reducer is an optional reducer (no RawReducerWithoutFinish.create method), then an empty iterable is returned if iterable is empty. Otherwise, an iterable containing the result of reducing using the first value of the iterable as the initial accumulator is returned.

Like Array.prototype.reduce, but for iterables.

Example

console.log(
  pipe(
    [`Hello`, `Sloth!`, `What`, `an`, `interesting`, `program!`],
    reduce((a, b) => `${a} ${b}`),
    get,
  ),
)
//=> Hello Sloth! What an interesting program!

console.log(
  pipe(
    [`Hello`, `Sloth!`, `What`, `an`, `interesting`, `program!`],
    reduce({ create: () => ``, add: (a, b) => `${a} ${b}` }),
  ),
)
//=> Hello Sloth! What an interesting program!

Since

v0.0.1

reduceAsync

Returns the result of reducing the asyncIterable using asyncReducer.

Informally, an initial accumulator is created using RawAsyncReducerWithoutFinish.create. Then each value in asyncIterable is added to the accumulator and the current accumulator is updated using RawAsyncReducerWithoutFinish.add. Finally, the resulting accumulator is transformed using RawAsyncReducerWithFinish.finish if specified. Multiple accumulators may be created, added to, and then combined if supported via RawAsyncReducerWithoutFinish.combine and the next value of asyncIterable is ready before promises from RawAsyncReducerWithoutFinish.add resolve.

If asyncReducer is an async optional reducer (no RawAsyncReducerWithoutFinish.create method), then an empty async iterable is returned if asyncIterable is empty. Otherwise, an async iterable containing the result of reducing using the first value of the async iterable as the initial accumulator is returned.

Like Array.prototype.reduce, but for async iterables.

Example

console.log(
  await pipe(
    asAsync([`Hello`, `World!`, `What`, `an`, `interesting`, `program!`]),
    reduceAsync((a, b) => `${a} ${b}`),
    getAsync,
  ),
)
//=> Hello World! What an interesting program!

console.log(
  await pipe(
    asAsync([`Hello`, `World!`, `What`, `an`, `interesting`, `program!`]),
    reduceAsync({ create: () => ``, add: (a, b) => `${a} ${b}` }),
  ),
)
//=> Hello World! What an interesting program!

Since

v0.0.1

reduceConcur

Returns the result of reducing the concurIterable using asyncReducer.

Informally, an initial accumulator is created using RawAsyncReducerWithoutFinish.create. Then each value in concurIterable is added to the accumulator and the current accumulator is updated using RawAsyncReducerWithoutFinish.add. Finally, the resulting accumulator is transformed using RawAsyncReducerWithFinish.finish if specified. Multiple accumulators may be created, added to, and then combined if supported via RawAsyncReducerWithoutFinish.combine and the next value of concurIterable is ready before promises from RawAsyncReducerWithoutFinish.add resolve.

If asyncReducer is an async optional reducer (no RawAsyncReducerWithoutFinish.create method), then an empty concur iterable is returned if concurIterable is empty. Otherwise, an concur iterable containing the result of reducing using the first value of the concur iterable as the initial accumulator is returned.

Like Array.prototype.reduce, but for concur iterables.

Example

console.log(
  await pipe(
    asAsync([`Hello`, `World!`, `What`, `an`, `interesting`, `program!`]),
    reduceAsync((a, b) => `${a} ${b}`),
    getAsync,
  ),
)
//=> Hello World! What an interesting program!

console.log(
  await pipe(
    asAsync([`Hello`, `World!`, `What`, `an`, `interesting`, `program!`]),
    reduceAsync({ create: () => ``, add: (a, b) => `${a} ${b}` }),
  ),
)
//=> Hello World! What an interesting program!

Since

v0.0.1

Side effects​

FunctionDescription

cache

Returns an iterable equivalent to iterable that iterates over iterable at most once by lazily caching the values from the first iteration.

Example

import { each, cache, pipe } from 'lfi'

const iterable = pipe(
  [`sloth`, `lazy`, `sleep`],
  each(console.log),
  cache,
)
// No output

console.log([...iterable])
//=> sloth
//=> lazy
//=> sleep
//=> [ 'sloth', 'lazy', 'sleep' ]

console.log([...iterable])
//=> [ 'sloth', 'lazy', 'sleep' ]
Playground

Since

v2.0.0

cacheAsync

Returns an async iterable equivalent to asyncIterable that iterates over asyncIterable at most once by lazily caching the values from the first iteration.

Example

import { asAsync, eachAsync, cacheAsync, mapAsync, pipe, reduceAsync, toArray } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`

const asyncIterable = pipe(
  asAsync([`sloth`, `lazy`, `sleep`]),
  mapAsync(async word => {
    const response = await fetch(`${API_URL}/${word}`)
    return (await response.json())[0].phonetic
  }),
  eachAsync(console.log),
  cacheAsync,
)
// No output

console.log(
  await pipe(
    asyncIterable,
    reduceAsync(toArray()),
  ),
)
//=> /slɑθ/
//=> /ˈleɪzi/
//=> /sliːp/
//=> [ '/slɑθ/', '/ˈleɪzi/', '/sliːp/' ]

console.log(
  await pipe(
    asyncIterable,
    reduceAsync(toArray()),
  ),
)
//=> [ '/slɑθ/', '/ˈleɪzi/', '/sliːp/' ]
Playground

Since

v2.0.0

cacheConcur

Returns a concur iterable equivalent to concurIterable that iterates over concurIterable at most once by lazily caching the values from the first iteration.

Example

import { asConcur, eachConcur, cacheConcur, mapConcur, pipe, reduceConcur, toArray } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`

const asyncIterable = pipe(
  asConcur([`sloth`, `lazy`, `sleep`]),
  mapConcur(async word => {
    const response = await fetch(`${API_URL}/${word}`)
    return (await response.json())[0].phonetic
  }),
  eachConcur(console.log),
  cacheConcur,
)
// No output

console.log(
  await pipe(
    asyncIterable,
    reduceConcur(toArray()),
  ),
)
// NOTE: This order may change between runs
//=> /slɑθ/
//=> /ˈleɪzi/
//=> /sliːp/
//=> [ '/slɑθ/', '/ˈleɪzi/', '/sliːp/' ]

console.log(
  await pipe(
    asyncIterable,
    reduceConcur(toArray()),
  ),
)
// NOTE: This order may change between runs
//=> [ '/slɑθ/', '/ˈleɪzi/', '/sliːp/' ]
Playground

Since

v2.0.0

consume

Iterates through iterable causing lazy operations to run.

Example

import { consume, each, pipe } from 'lfi'

const iterable = pipe(
  [`sloth`, `lazy`, `sleep`],
  each(console.log),
)
// No output

consume(iterable)
//=> sloth
//=> lazy
//=> sleep
Playground

Since

v2.0.0

consumeAsync

Iterates through asyncIterable causing lazy operations to run.

Example

import { asAsync, consumeAsync, eachAsync, mapAsync, pipe } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`

const asyncIterable = pipe(
  asAsync([`sloth`, `lazy`, `sleep`]),
  mapAsync(async word => {
    const response = await fetch(`${API_URL}/${word}`)
    return (await response.json())[0].phonetic
  }),
  eachAsync(console.log),
)
// No output

await consumeAsync(asyncIterable)
//=> /slɑθ/
//=> /ˈleɪzi/
//=> /sliːp/
Playground

Since

v2.0.0

consumeConcur

Iterates through the concurIterable causing lazy operations to run.

Example

import { asConcur, consumeConcur, eachConcur, mapConcur, pipe } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`

const asyncIterable = pipe(
  asConcur([`sloth`, `lazy`, `sleep`]),
  mapConcur(async word => {
    const response = await fetch(`${API_URL}/${word}`)
    return (await response.json())[0].phonetic
  }),
  eachConcur(console.log),
)
// No output

await consumeConcur(asyncIterable)
// NOTE: This order may change between runs
//=> /slɑθ/
//=> /ˈleɪzi/
//=> /sliːp/
Playground

Since

v2.0.0

each

Returns an iterable equivalent to iterable that applies fn to each value of iterable as it is iterated.

Example

import { each, pipe, reduce, toArray } from 'lfi'

console.log(
  pipe(
    [`sloth`, `lazy`, `sleep`],
    each(console.log),
    reduce(toArray()),
  ),
)
//=> sloth
//=> lazy
//=> sleep
//=> [ 'sloth', 'lazy', 'sleep' ]
Playground

Since

v0.0.1

eachAsync

Returns an async iterable equivalent to asyncIterable that applies fn to each value of asyncIterable as it is iterated.

The result of applying fn to a value is awaited before yielding and then moving on to the next value.

Example

import { asAsync, eachAsync, mapAsync, pipe, reduceAsync, toArray } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`

console.log(
  await pipe(
    asAsync([`sloth`, `lazy`, `sleep`]),
    mapAsync(async word => {
      const response = await fetch(`${API_URL}/${word}`)
      return (await response.json())[0].phonetic
    }),
    eachAsync(console.log),
    reduceAsync(toArray()),
  ),
)
//=> /slɑθ/
//=> /ˈleɪzi/
//=> /sliːp/
//=> [ '/slɑθ/', '/ˈleɪzi/', '/sliːp/' ]
Playground

Since

v0.0.1

eachConcur

Returns an concur iterable equivalent to concurIterable that applies fn to each value of concurIterable as it is iterated.

The result of applying fn to a value is awaited before yielding.

Example

import { asConcur, eachConcur, mapConcur, pipe, reduceConcur, toArray } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`

console.log(
  await pipe(
    asConcur([`sloth`, `lazy`, `sleep`]),
    mapConcur(async word => {
      const response = await fetch(`${API_URL}/${word}`)
      return (await response.json())[0].phonetic
    }),
    eachConcur(console.log),
    reduceConcur(toArray()),
  ),
)
// NOTE: This order may change between runs
//=> /slɑθ/
//=> /ˈleɪzi/
//=> /sliːp/
//=> [ '/slɑθ/', '/ˈleɪzi/', '/sliːp/' ]
Playground

Since

v0.0.1

forEach

Applies fn to each value of iterable.

Like Array.prototype.forEach, but for iterables.

Example

import { forEach, pipe } from 'lfi'

console.log(
  pipe(
    [`sloth`, `lazy`, `sleep`],
    forEach(console.log),
  ),
)
//=> sloth
//=> lazy
//=> sleep
Playground

Since

v0.0.1

forEachAsync

Returns a promise that resolves when fn has been applied to each value of asyncIterable and the result of each application has been awaited.

The result of applying fn to a value is awaited before moving on to the next value.

Like Array.prototype.forEach, but for async iterables.

Example

import { asAsync, forEachAsync, mapAsync, pipe } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`

console.log(
  await pipe(
    asAsync([`sloth`, `lazy`, `sleep`]),
    mapAsync(async word => {
      const response = await fetch(`${API_URL}/${word}`)
      return (await response.json())[0].phonetic
    }),
    forEachAsync(console.log),
  ),
)
//=> /slɑθ/
//=> /ˈleɪzi/
//=> /sliːp/
Playground

Since

v0.0.1

forEachConcur

Returns a promise that resolves when fn has been applied to each value of concurIterable and the result of each application has been awaited.

Like Array.prototype.forEach, but for concur iterables.

Example

import { asConcur, forEachConcur, mapConcur, pipe } from 'lfi'

const API_URL = `https://api.dictionaryapi.dev/api/v2/entries/en`

console.log(
  await pipe(
    asConcur([`sloth`, `lazy`, `sleep`]),
    mapConcur(async word => {
      const response = await fetch(`${API_URL}/${word}`)
      return (await response.json())[0].phonetic
    }),
    forEachConcur(console.log),
  ),
)
// NOTE: This order may change between runs
//=> /slɑθ/
//=> /ˈleɪzi/
//=> /sliːp/
Playground

Since

v0.0.1

Splices​

Type alias, FunctionDescription

WindowOptions

Options for window, windowAsync, and windowConcur.

Since

v2.0.0

at

Returns an iterable containing the value at the given index of iterable or an empty iterable if index is out of bounds.

WARNING: This function linearly iterates up to index because iterables do not support random access.

Throws

if index is not a non-negative integer.

Example

const iterable = [`sloth`, `more sloth`, `even more sloth`]

console.log(
  pipe(
    iterable,
    at(1),
    get,
  ),
)
//=> 'more sloth'

Since

v3.5.0

atAsync

Returns an async iterable containing the value at the given index of asyncIterable or an empty async iterable if index is out of bounds.

WARNING: This function linearly iterates up to index because async iterables do not support random access.

Throws

if index is not a non-negative integer.

Example

const asyncIterable = asAsync([`sloth`, `more sloth`, `even more sloth`])

console.log(
  await pipe(
    asyncIterable,
    atAsync(1),
    getAsync,
  ),
)
//=> 'more sloth'

Since

v3.5.0

atConcur

Returns a concur iterable containing the value at the given index of concurIterable in iteration order, or an empty concur iterable if index is out of bounds.

WARNING: This function linearly iterates up to index because concur iterables do not support random access.

Throws

if index is not a non-negative integer.

Example

const concurIterable = asConcur([`sloth`, `more sloth`, `even more sloth`])

console.log(
  await pipe(
    concurIterable,
    atConcur(1),
    getConcur,
  ),
)
//=> 'more sloth'

Since

v3.5.0

chunk

Returns an iterable equivalent to iterable except its values are grouped into arrays that each contain size values.

The last array in the returned iterable will contain fewer than size values (but at least one) if the number of values in iterable is not divisible by size.

Throws

if size is not a positive integer.

Example

console.log(
  pipe(
    [1, 2, 3, 4, 5, 6, 7, 8, 9],
    chunk(3),
    reduce(toArray()),
  ),
)
//=> [ [ 1, 2, 3 ], [ 4, 5, 6 ], [ 7, 8, 9 ] ]

console.log(
  pipe(
    [`S`, `L`, `O`, `T`, `H`],
    chunk(2),
    reduce(toArray()),
  ),
)
//=> [ [ 'S', 'L' ], [ 'O', 'T' ], [ 'H' ] ]

Since

v2.0.0

chunkAsync

Returns an async iterable equivalent to asyncIterable except its values are grouped into arrays that each contain size values.

The last array in the returned async iterable will contain fewer than size values (but at least one) if the number of values in asyncIterable is not divisible by size.

Throws

if size is not a positive integer.

Example

console.log(
  await pipe(
    asAsync([1, 2, 3, 4, 5, 6, 7, 8, 9]),
    chunkAsync(3),
    reduceAsync(toArray()),
  ),
)
//=> [ [ 1, 2, 3 ], [ 4, 5, 6 ], [ 7, 8, 9 ] ]

console.log(
  await pipe(
    asAsync([`S`, `L`, `O`, `T`, `H`]),
    chunkAsync(2),
    reduceAsync(toArray()),
  ),
)
//=> [ [ 'S', 'L' ], [ 'O', 'T' ], [ 'H' ] ]

Since

v2.0.0

chunkConcur

Returns a concur iterable equivalent to concurIterable except its values are grouped into arrays that each contain size values.

The last array in the returned concur iterable will contain fewer than size values (but at least one) if the number of values in concurIterable is not divisible by size.

Throws

if size is not a positive integer.

Example

console.log(
  await pipe(
    asConcur([1, 2, 3, 4, 5, 6, 7, 8, 9]),
    chunkConcur(3),
    reduceConcur(toArray()),
  ),
)
//=> [ [ 1, 2, 3 ], [ 4, 5, 6 ], [ 7, 8, 9 ] ]

console.log(
  await pipe(
    asConcur([`S`, `L`, `O`, `T`, `H`]),
    chunkConcur(2),
    reduceConcur(toArray()),
  ),
)
//=> [ [ 'S', 'L' ], [ 'O', 'T' ], [ 'H' ] ]

Since

v2.0.0

concat

Returns an iterable that contains the values of each iterable in iterables in iteration order.

Like Array.prototype.concat, but for iterables.

Example

console.log(
  pipe(
    concat([1, 2], [3, `sloth`, 5], [6, 7]),
    reduce(toArray()),
  ),
)
//=> [ 1, 2, 3, 'sloth', 5, 6, 7 ]

Since

v0.0.2

concatAsync

Returns an async iterable that contains the values of each iterable in iterables in iteration order.

Like Array.prototype.concat, but for async iterables.

Example

console.log(
  await pipe(
    concatAsync(asAsync([1, 2]), [3, `sloth`, 5], asAsync([6, 7])),
    reduceAsync(toArray()),
  ),
)
//=> [ 1, 2, 3, 'sloth', 5, 6, 7 ]

Since

v0.0.2

concatConcur

Returns a concur iterable that contains the values of each iterable in iterables.

Like Array.prototype.concat, but for concur iterables.

Example

console.log(
  await pipe(
    concatConcur(asAsync([1, 2]), [3, `sloth`, 5], asConcur([6, 7])),
    reduceConcur(toArray()),
  ),
)
//=> [ 1, 2, 3, 'sloth', 5, 6, 7 ]

Since

v0.0.1

drop

Returns an iterable containing the values of iterable in iteration order except for the first count values.

If the count is greater than the number of values in iterable, then an empty iterable is returned.

Throws

if count isn't a non-negative integer.

Example

console.log(
  pipe(
    [1, 2, 3, 4, 5, `sloth`],
    drop(3),
    reduce(toArray()),
  ),
)
//=> [ 4, 5, 'sloth' ]

Since

v0.0.1

dropAsync

Returns an async iterable containing the values of asyncIterable in iteration order except for the first count values.

If the count is greater than the number of values in asyncIterable, then an empty async iterable is returned.

Throws

if count isn't a non-negative integer.

Example

console.log(
  await pipe(
    asAsync([1, 2, 3, 4, 5, `sloth`]),
    dropAsync(3),
    reduceAsync(toArray()),
  ),
)
//=> [ 4, 5, 'sloth' ]

Since

v0.0.1

dropConcur

Returns a concur iterable containing the values of concurIterable in iteration order except for the first count values.

If the count is greater than the number of values in concurIterable, then an empty concur iterable is returned.

Throws

if count isn't a non-negative integer.

Example

console.log(
  await pipe(
    asConcur([1, 2, 3, 4, 5, `sloth`]),
    dropConcur(3),
    reduceConcur(toArray()),
  ),
)
//=> [ 4, 5, 'sloth' ]

Since

v0.0.2

dropWhile

Returns an iterable containing the values of iterable in iteration order starting with the first value for which fn returns a falsy value.

Example

console.log(
  pipe(
    [1, 2, 3, 4, 5, 6, 7, 8, `sloth`],
    dropWhile(value => value < 5),
    reduce(toArray()),
  ),
)
//=> [ 5, 6, 7, 8, 'sloth' ]

Since

v0.0.1

dropWhileAsync

Returns an async iterable containing the values of asyncIterable in iteration order starting with the first value for which fn returns a value awaitable to a falsy value.

Example

console.log(
  await pipe(
    asAsync([1, 2, 3, 4, 5, 6, 7, 8, `sloth`]),
    dropWhileAsync(value => value < 5),
    reduceAsync(toArray()),
  ),
)
//=> [ 5, 6, 7, 8, 'sloth' ]

Since

v0.0.1

dropWhileConcur

Returns a concur iterable containing the values of concurIterable in iteration order starting with the first value for which fn returns a value awaitable to a falsy value.

Example

console.log(
  await pipe(
    asConcur([1, 2, 3, 4, 5, 6, 7, 8, `sloth`]),
    dropWhileConcur(value => value < 5),
    reduceConcur(toArray()),
  ),
)
//=> [ 5, 6, 7, 8, 'sloth' ]

Since

v0.0.2

first

Returns an iterable containing the first value of iterable, or an empty iterable if iterable is empty.

Example

console.log(
  pipe(
    [`sloth`, `more sloth`, `even more sloth`],
    first,
    reduce(toArray()),
  ),
)
//=> [ 'sloth' ]

Since

v0.0.1

firstAsync

Returns an async iterable containing the first value of asyncIterable, or an empty async iterable if asyncIterable is empty.

Example

console.log(
  await pipe(
    asAsync([`sloth`, `more sloth`, `even more sloth`]),
    firstAsync,
    reduceAsync(toArray()),
  ),
)
//=> [ 'sloth' ]

Since

v0.0.1

firstConcur

Returns a concur iterable containing the first value of concurIterable, or an empty concur iterable if concurIterable is empty.

Example

console.log(
  await pipe(
    asConcur([`sloth`, `more sloth`, `even more sloth`]),
    firstConcur,
    reduceConcur(toArray()),
  ),
)
//=> [ 'sloth' ]

Since

v0.0.2

last

Returns an iterable containing the last value of iterable, or an empty iterable if iterable is empty.

Example

console.log(
  pipe(
    [`sloth`, `more sloth`, `even more sloth`],
    last,
    reduce(toArray()),
  ),
)
//=> [ 'even more sloth' ]

Since

v0.0.1

lastAsync

Returns an async iterable containing the last value of asyncIterable, or an empty async iterable if asyncIterable is empty.

Example

console.log(
  await pipe(
    asAsync([`sloth`, `more sloth`, `even more sloth`]),
    lastAsync,
    reduceAsync(toArray()),
  ),
)
//=> [ 'even more sloth' ]

Since

v0.0.1

lastConcur

Returns a concur iterable containing the last value of concurIterable, or an empty concur iterable if concurIterable is empty.

Example

console.log(
  await pipe(
    asConcur([`sloth`, `more sloth`, `even more sloth`]),
    lastConcur,
    reduceConcur(toArray()),
  ),
)
//=> [ 'even more sloth' ]

Since

v0.0.2

slice

Returns an iterable containing the values of iterable between start and end (exclusive) of iterable.

If any part of the range between start and end is outside the bounds of the iterable, then that part is excluded from the returned iterable. Thus, the returned iterable may be empty.

WARNING: This function linearly iterates up to end because iterables do not support random access.

Throws

if either start or end is not a non-negative integer, or if start is greater than end.

Example

const iterable = [`sloth`, `more sloth`, `even more sloth`]

console.log(
  pipe(
    iterable,
    slice(0, 3),
    reduce(toArray()),
  ),
)
//=> [ 'sloth', 'more sloth', 'even more sloth' ]

console.log(
  pipe(
    iterable,
    slice(0, 42),
    reduce(toArray()),
  ),
)
//=> [ 'sloth', 'more sloth', 'even more sloth' ]

console.log(
  pipe(
    iterable,
    slice(1, 3),
    reduce(toArray()),
  ),
)
//=> [ 'more sloth', 'even more sloth' ]

console.log(
  pipe(
    iterable,
    slice(3, 5),
    reduce(toArray()),
  ),
)
//=> []

Since

v3.5.0

sliceAsync

Returns an async iterable containing the values of asyncIterable between start and end (exclusive) of asyncIterable.

If any part of the range between start and end is outside the bounds of the async iterable, then that part is excluded from the returned async iterable. Thus, the returned async iterable may be empty.

WARNING: This function linearly iterates up to end because async iterables do not support random access.

Throws

if either start or end is not a non-negative integer, or if start is greater than end.

Example

const asyncIterable = asAsync([`sloth`, `more sloth`, `even more sloth`])

console.log(
  await pipe(
    asyncIterable,
    sliceAsync(0, 3),
    reduceAsync(toArray()),
  ),
)
//=> [ 'sloth', 'more sloth', 'even more sloth' ]

console.log(
  await pipe(
    asyncIterable,
    sliceAsync(0, 42),
    reduceAsync(toArray()),
  ),
)
//=> [ 'sloth', 'more sloth', 'even more sloth' ]

console.log(
  await pipe(
    asyncIterable,
    sliceAsync(1, 3),
    reduceAsync(toArray()),
  ),
)
//=> [ 'more sloth', 'even more sloth' ]

console.log(
  await pipe(
    asyncIterable,
    sliceAsync(3, 5),
    reduceAsync(toArray()),
  ),
)
//=> []

Since

v3.5.0

sliceConcur

Returns a concur iterable containing the values of concurIterable between start and end (exclusive) of concurIterable in iteration order.

If any part of the range between start and end is outside the bounds of the concur iterable, then that part is excluded from the returned concur iterable. Thus, the returned concur iterable may be empty.

WARNING: This function linearly iterates up to end because concur iterables do not support random access.

Throws

if either start or end is not a non-negative integer, or if start is greater than end.

Example

const concurIterable = asConcur([`sloth`, `more sloth`, `even more sloth`])

console.log(
  await pipe(
    concurIterable,
    sliceConcur(0, 3),
    reduceConcur(toArray()),
  ),
)
//=> [ 'sloth', 'more sloth', 'even more sloth' ]

console.log(
  await pipe(
    concurIterable,
    sliceConcur(0, 42),
    reduceConcur(toArray()),
  ),
)
//=> [ 'sloth', 'more sloth', 'even more sloth' ]

console.log(
  await pipe(
    concurIterable,
    sliceConcur(1, 3),
    reduceConcur(toArray()),
  ),
)
//=> [ 'more sloth', 'even more sloth' ]

console.log(
  await pipe(
    concurIterable,
    sliceConcur(3, 5),
    reduceConcur(toArray()),
  ),
)
//=> []

Since

v3.5.0

take

Returns an iterable containing the first count values of iterable in iteration order.

If the count is greater than the number of values in iterable, then an iterable equivalent iterable is returned.

Throws

if count isn't a non-negative integer.

Example

console.log(
  pipe(
    [1, 2, 3, 4, 5, `sloth`],
    take(3),
    reduce(toArray()),
  ),
)
//=> [ 1, 2, 3 ]

Since

v0.0.1

takeAsync

Returns an async iterable containing the first count values of asyncIterable in iteration order.

If the count is greater than the number of values in asyncIterable, then an async iterable equivalent asyncIterable is returned.

Throws

if count isn't a non-negative integer.

Example

console.log(
  await pipe(
    asAsync([1, 2, 3, 4, 5, `sloth`]),
    takeAsync(3),
    reduceAsync(toArray()),
  ),
)
//=> [ 1, 2, 3 ]

Since

v0.0.1

takeConcur

Returns a concur iterable containing the first count values of concurIterable in iteration order.

If the count is greater than the number of values in concurIterable, then a concur iterable equivalent concurIterable is returned.

Throws

if count isn't a non-negative integer.

Example

console.log(
  await pipe(
    asConcur([1, 2, 3, 4, 5, `sloth`]),
    takeConcur(3),
    reduceConcur(toArray()),
  ),
)
//=> [ 1, 2, 3 ]

Since

v0.0.2

takeWhile

Returns an iterable containing the values of iterable in iteration order up until but not including the first value for which fn returns a falsy value.

Example

console.log(
  pipe(
    [1, 2, 3, 4, 5, 6, 7, 8, `sloth`],
    takeWhile(value => value < 5),
    reduce(toArray()),
  ),
)
//=> [ 1, 2, 3, 4 ]

Since

v0.0.1

takeWhileAsync

Returns an async iterable containing the values of asyncIterable in iteration order up until but not including the first value for which fn returns a value awaitable to a falsy value.

Example

console.log(
  await pipe(
    asAsync([1, 2, 3, 4, 5, 6, 7, 8, `sloth`]),
    takeWhileAsync(value => value < 5),
    reduceAsync(toArray()),
  ),
)
//=> [ 1, 2, 3, 4 ]

Since

v0.0.1

takeWhileConcur

Returns a concur iterable containing the values of concurIterable in iteration order up until but not including the first value for which fn returns a value awaitable to a falsy value.

Example

console.log(
  await pipe(
    asConcur([1, 2, 3, 4, 5, 6, 7, 8, `sloth`]),
    takeWhileConcur(value => value < 5),
    reduceConcur(toArray()),
  ),
)
//=> [ 1, 2, 3, 4 ]

Since

v0.0.2

window

Returns an iterable containing a rolling window of the values of iterable as arrays of length size.

Throws

if size is not a positive integer.

Example

console.log(
  pipe(
    [1, 2, 3, 4, 5, 6, `sloth`],
    window(3),
    reduce(toArray()),
  ),
)
//=> [ [ 1, 2, 3 ], [ 2, 3, 4 ], [ 3, 4, 5 ], [ 4, 5, 6 ], [ 5, 6, 'sloth' ] ]

console.log(
  pipe(
    [1, 2, 3, 4, 5, 6, `sloth`],
    window({ size: 3, partialStart: true }),
    reduce(toArray()),
  ),
)
//=> [ [ 1 ], [ 1, 2 ], [ 1, 2, 3 ], [ 2, 3, 4 ], [ 3, 4, 5 ], [ 4, 5, 6 ], [ 5, 6, 'sloth' ] ]

console.log(
  pipe(
    [1, 2, 3, 4, 5, 6, `sloth`],
    window({ size: 3, partialStart: true, partialEnd: true }),
    reduce(toArray()),
  ),
)
//=> [ [ 1 ], [ 1, 2 ], [ 1, 2, 3 ], [ 2, 3, 4 ], [ 3, 4, 5 ], [ 4, 5, 6 ], [ 5, 6, 'sloth' ], [ 6, 'sloth' ], [ 'sloth' ] ]

Since

v2.0.0

windowAsync

Returns an async iterable containing a rolling window of the values of asyncIterable as arrays of length size.

Throws

if size is not a positive integer.

Example

console.log(
  await pipe(
    asAsync([1, 2, 3, 4, 5, 6, `sloth`]),
    windowAsync(3),
    reduceAsync(toArray()),
  ),
)
//=> [ [ 1, 2, 3 ], [ 2, 3, 4 ], [ 3, 4, 5 ], [ 4, 5, 6 ], [ 5, 6, 'sloth' ] ]

console.log(
  await pipe(
    asAsync([1, 2, 3, 4, 5, 6, `sloth`]),
    windowAsync({ size: 3, partialStart: true }),
    reduceAsync(toArray()),
  ),
)
//=> [ [ 1 ], [ 1, 2 ], [ 1, 2, 3 ], [ 2, 3, 4 ], [ 3, 4, 5 ], [ 4, 5, 6 ], [ 5, 6, 'sloth' ] ]

console.log(
  await pipe(
    asAsync([1, 2, 3, 4, 5, 6, `sloth`]),
    windowAsync({ size: 3, partialStart: true, partialEnd: true }),
    reduceAsync(toArray()),
  ),
)
//=> [ [ 1 ], [ 1, 2 ], [ 1, 2, 3 ], [ 2, 3, 4 ], [ 3, 4, 5 ], [ 4, 5, 6 ], [ 5, 6, 'sloth' ], [ 6, 'sloth' ], [ 'sloth' ] ]

Since

v2.0.0

windowConcur

Returns a concur iterable containing a rolling window of the values of concurIterable as arrays of length size.

Throws

if size is not a positive integer.

Example

console.log(
  await pipe(
    asConcur([1, 2, 3, 4, 5, 6, `sloth`]),
    windowConcur(3),
    reduceConcur(toArray()),
  ),
)
//=> [ [ 1, 2, 3 ], [ 2, 3, 4 ], [ 3, 4, 5 ], [ 4, 5, 6 ], [ 5, 6, 'sloth' ] ]

console.log(
  await pipe(
    asConcur([1, 2, 3, 4, 5, 6, `sloth`]),
    windowConcur({ size: 3, partialStart: true }),
    reduceConcur(toArray()),
  ),
)
//=> [ [ 1 ], [ 1, 2 ], [ 1, 2, 3 ], [ 2, 3, 4 ], [ 3, 4, 5 ], [ 4, 5, 6 ], [ 5, 6, 'sloth' ] ]

console.log(
  await pipe(
    asConcur([1, 2, 3, 4, 5, 6, `sloth`]),
    windowConcur({ size: 3, partialStart: true, partialEnd: true }),
    reduceConcur(toArray()),
  ),
)
//=> [ [ 1 ], [ 1, 2 ], [ 1, 2, 3 ], [ 2, 3, 4 ], [ 3, 4, 5 ], [ 4, 5, 6 ], [ 5, 6, 'sloth' ], [ 6, 'sloth' ], [ 'sloth' ] ]

Since

v2.0.0

zip

Returns an iterable that pairs up same-index values from the given iterables into tuples.

The iterables are iterated in parallel until the shortest one is done, at which point the returned iterable is done.

Example

console.log(
  pipe(
    zip(
     [1, 2, 3, 4],
     [5, `sloth`, 7],
     [8, 9, 10],
    ),
    reduce(toArray()),
  ),
)
//=> [ [ 1, 5, 8 ], [ 2, 'sloth', 9 ], [ 3, 7, 10 ] ]

Since

v3.8.0

zipAsync

Returns an async iterable that pairs up same-index values from the given iterables into tuples.

The iterables are iterated in parallel until the shortest one is done, at which point the returned async iterable is done.

Example

console.log(
  await pipe(
    zipAsync(
     asAsync([1, 2, 3, 4]),
     [5, `sloth`, 7],
     asAsync([8, 9, 10]),
    ),
    reduceAsync(toArray()),
  ),
)
//=> [ [ 1, 5, 8 ], [ 2, 'sloth', 9 ], [ 3, 7, 10 ] ]

Since

v3.8.0

zipConcur

Returns a concur iterable that pairs up same-index values, in iteration order, from the given iterables into tuples.

The iterables are iterated in parallel until the shortest one is done, at which point the returned concur iterable is done.

WARNING: If one of the concur iterables yields values more quickly than others, then an unbounded number of its values will be buffered so that they can be yielded with the values of other concur iterables at the same index.

Example

console.log(
  await pipe(
    zipConcur(
     asAsync([1, 2, 3, 4]),
     [5, `sloth`, 7],
     asConcur([8, 9, 10]),
    ),
    reduceConcur(toArray()),
  ),
)
//=> [ [ 1, 5, 8 ], [ 2, 'sloth', 9 ], [ 3, 7, 10 ] ]

Since

v3.8.0

Statistics​

Type alias, FunctionDescription

AsyncCompare

A function that compares two values of type Value possibly asynchronously.

A return value that awaits to:

  • Less than zero implies left < right
  • Equal to zero implies left === right
  • Greater than zero implies left > right

Since

v0.0.2

Compare

A function that compares two values of type Value.

A return value:

  • Less than zero implies left < right
  • Equal to zero implies left === right
  • Greater than zero implies left > right

Since

v0.0.2

MinMax

An object containing a minimum and maximum value.

Since

v0.0.2

count

Returns the number of values in iterable.

Like Array.prototype.length, but for iterables.

Example

console.log(count([`sloth`, `more sloth`, `even more sloth`]))
//=> 3

Since

v0.0.1

countAsync

Returns a promise that resolves to the number of values in asyncIterable.

Like Array.prototype.length, but for async iterables.

Example

console.log(
  await countAsync(asAsync([`sloth`, `more sloth`, `even more sloth`])),
)
//=> 3

Since

v0.0.1

countConcur

Returns a promise that resolves to the number of values in concurIterable.

Like Array.prototype.length, but for concur iterables.

Example

console.log(
  await countConcur(asConcur([`sloth`, `more sloth`, `even more sloth`])),
)
//=> 3

Since

v0.0.1

max

Returns an iterable containing a maximum value of iterable if iterable contains at least one value. Otherwise, returns an empty iterable.

Example

console.log(pipe([4, 1, 5, -3], max, get))
//=> 5

Since

v0.0.1

maxAsync

Returns an async iterable containing a maximum value of asyncIterable if asyncIterable contains at least one value. Otherwise, returns an empty async iterable.

Example

console.log(await pipe(asAsync([4, 1, 5, -3]), maxAsync, getAsync))
//=> 5

Since

v0.0.1

maxBy

Returns an iterable containing a maximum value of iterable based on the fn Compare function if iterable contains at least one value. Otherwise, returns an empty iterable.

Example

console.log(
  pipe(
    [`eating`, `sleeping`, `yawning`],
    maxBy((a, b) => a.length - b.length),
    get,
  ),
)
//=> sleeping

Since

v0.0.1

maxByAsync

Returns an async iterable containing a maximum value of asyncIterable based on the fn AsyncCompare function if asyncIterable contains at least one value. Otherwise, returns an empty async iterable.

Example

console.log(
  await pipe(
    asAsync([`eating`, `sleeping`, `yawning`]),
    maxByAsync((a, b) => a.length - b.length),
    getAsync,
  ),
)
//=> sleeping

Since

v0.0.1

maxByConcur

Returns a concur iterable containing a maximum value of concurIterable based on the fn AsyncCompare function if concurIterable contains at least one value. Otherwise, returns an empty concur iterable.

Example

console.log(
  await pipe(
    asConcur([`eating`, `sleeping`, `yawning`]),
    maxByConcur((a, b) => a.length - b.length),
    getConcur,
  ),
)
//=> sleeping

Since

v0.0.1

maxConcur

Returns a concur iterable containing a maximum value of concurIterable if concurIterable contains at least one value. Otherwise, returns an empty concur iterable.

Example

console.log(await pipe(asConcur([4, 1, 5, -3]), maxConcur, getConcur))
//=> 5

Since

v0.0.1

maxWith

Returns an iterable containing a maximum value of iterable by comparing the numerical values of each value, as defined by fn, if iterable contains at least one value. Otherwise, returns an empty iterable.

Example

console.log(
  pipe(
    [`eating`, `sleeping`, `yawning`],
    maxWith(value => value.length),
    get,
  ),
)
//=> sleeping

Since

v0.0.1

maxWithAsync

Returns an async iterable containing a maximum value of asyncIterable by comparing the numerical values of each value, as defined by fn, if asyncIterable contains at least one value. Otherwise, returns an empty async iterable.

Example

console.log(
  await pipe(
    asAsync([`eating`, `sleeping`, `yawning`]),
    maxWithAsync(value => value.length),
    getAsync,
  ),
)
//=> sleeping

Since

v0.0.1

maxWithConcur

Returns a concur iterable containing a maximum value of concurIterable by comparing the numerical values of each value, as defined by fn, if concurIterable contains at least one value. Otherwise, returns an empty concur iterable.

Example

console.log(
  await pipe(
    asConcur([`eating`, `sleeping`, `yawning`]),
    maxWithConcur(value => value.length),
    getConcur,
  ),
)
//=> sleeping

Since

v0.0.1

mean

Returns the mean of the numbers of iterable.

Returns NaN for an empty iterable.

Example

console.log(mean([1, 4, 6, 2]))
//=> 3.25

console.log(mean([]))
//=> NaN

Since

v3.5.0

meanAsync

Returns a promise that resolves to the mean of the numbers of asyncIterable.

Returns a promise that resolves to NaN for an empty async iterable.

Example

console.log(await meanAsync(asAsync([1, 4, 6, 2])))
//=> 3.25

console.log(await meanAsync(emptyAsync))
//=> NaN

Since

v3.5.0

meanConcur

Returns a promise that resolves to the mean of the numbers of concurIterable.

Returns a promise that resolves to NaN for an empty concur iterable.

Example

console.log(await meanConcur(asConcur([1, 4, 6, 2])))
//=> 3.25

console.log(await meanConcur(emptyConcur))
//=> NaN

Since

v3.5.0

min

Returns an iterable containing a minimum value of iterable if iterable contains at least one value. Otherwise, returns an empty iterable.

Example

console.log(pipe([4, 1, 5, -3], min, get))
//=> -3

Since

v0.0.1

minAsync

Returns an async iterable containing a minimum value of asyncIterable if asyncIterable contains at least one value. Otherwise, returns an empty async iterable.

Example

console.log(await pipe(asAsync([4, 1, 5, -3]), minAsync, getAsync))
//=> -3

Since

v0.0.1

minBy

Returns an iterable containing a minimum value of iterable based on the fn Compare function if iterable contains at least one value. Otherwise, returns an empty iterable.

Example

console.log(
  pipe(
    [`eating`, `sleeping`, `yawning`],
    minBy((a, b) => a.length - b.length),
    get,
  ),
)
//=> eating

Since

v0.0.1

minByAsync

Returns an async iterable containing a minimum value of asyncIterable based on the fn AsyncCompare function if asyncIterable contains at least one value. Otherwise, returns an empty async iterable.

Example

console.log(
  await pipe(
    asAsync([`eating`, `sleeping`, `yawning`]),
    minByAsync((a, b) => a.length - b.length),
    getAsync,
  ),
)
//=> eating

Since

v0.0.1

minByConcur

Returns a concur iterable containing a minimum value of concurIterable based on the fn AsyncCompare function if concurIterable contains at least one value. Otherwise, returns an empty concur iterable.

Example

console.log(
  await pipe(
    asConcur([`eating`, `sleeping`, `yawning`]),
    minByConcur((a, b) => a.length - b.length),
    getConcur,
  ),
)
//=> eating

Since

v0.0.1

minConcur

Returns a concur iterable containing a minimum value of concurIterable if concurIterable contains at least one value. Otherwise, returns an empty concur iterable.

Example

console.log(await pipe(asConcur([4, 1, 5, -3]), minConcur, getConcur))
//=> -3

Since

v0.0.1

minMax

Returns an iterable containing a MinMax value of iterable if iterable contains at least one value. Otherwise, returns an empty iterable.

Example

console.log(pipe([4, 1, 5, -3], minMax, get))
//=> { min: -3, max: 5 }

Since

v0.0.2

minMaxAsync

Returns an async iterable containing a MinMax value of asyncIterable if asyncIterable contains at least one value. Otherwise, returns an empty async iterable.

Example

console.log(await pipe(asAsync([4, 1, 5, -3]), minMaxAsync, getAsync))
//=> { min: -3, max: 5 }

Since

v0.0.2

minMaxBy

Returns an iterable containing a MinMax value of iterable based on the fn Compare function if iterable contains at least one value. Otherwise, returns an empty iterable.

Example

console.log(
  pipe(
    [`eating`, `sleeping`, `yawning`],
    minMaxBy((a, b) => a.length - b.length),
    get,
  ),
)
//=> { min: 'eating', max: 'sleeping' }

Since

v0.0.2

minMaxByAsync

Returns an async iterable containing a MinMax value of asyncIterable based on the fn AsyncCompare function if asyncIterable contains at least one value. Otherwise, returns an empty async iterable.

Example

console.log(
  await pipe(
    asAsync([`eating`, `sleeping`, `yawning`]),
    minMaxByAsync((a, b) => a.length - b.length),
    getAsync,
  ),
)
//=> { min: 'eating', max: 'sleeping' }

Since

v0.0.2

minMaxByConcur

Returns a concur iterable containing a MinMax value of concurIterable based on the fn AsyncCompare function if concurIterable contains at least one value. Otherwise, returns an empty concur iterable.

Example

console.log(
  await pipe(
    asConcur([`eating`, `sleeping`, `yawning`]),
    minMaxByConcur((a, b) => a.length - b.length),
    getConcur,
  ),
)
//=> { min: 'eating', max: 'sleeping' }

Since

v0.0.2

minMaxConcur

Returns a concur iterable containing a MinMax value of concurIterable if concurIterable contains at least one value. Otherwise, returns an empty concur iterable.

Example

console.log(await pipe(asConcur([4, 1, 5, -3]), minMaxConcur, getConcur))
//=> { min: -3, max: 5 }

Since

v0.0.2

minMaxWith

Returns an iterable containing a MinMax value of iterable by comparing the numerical values of each value, as defined by fn, if iterable contains at least one value. Otherwise, returns an empty iterable.

Example

console.log(
  pipe(
    [`eating`, `sleeping`, `yawning`],
    minMaxWith(value => value.length),
    get,
  ),
)
//=> { min: 'eating', max: 'sleeping' }

Since

v0.0.2

minMaxWithAsync

Returns an async iterable containing a MinMax value of asyncIterable by comparing the numerical values of each value, as defined by fn, if asyncIterable contains at least one value. Otherwise, returns an empty async iterable.

Example

console.log(
  await pipe(
    asAsync([`eating`, `sleeping`, `yawning`]),
    minMaxWithAsync(value => value.length),
    getAsync,
  ),
)
//=> { min: 'eating', max: 'sleeping' }

Since

v0.0.1

minMaxWithConcur

Returns a concur iterable containing a MinMax value of concurIterable by comparing the numerical values of each value, as defined by fn, if concurIterable contains at least one value. Otherwise, returns an empty concur iterable.

Example

console.log(
  await pipe(
    asConcur([`eating`, `sleeping`, `yawning`]),
    minMaxWithConcur(value => value.length),
    getConcur,
  ),
)
//=> { min: 'eating', max: 'sleeping' }

Since

v0.0.2

minWith

Returns an iterable containing a minimum value of iterable by comparing the numerical values of each value, as defined by fn, if iterable contains at least one value. Otherwise, returns an empty iterable.

Example

console.log(
  pipe(
    [`eating`, `sleeping`, `yawning`],
    minWith(value => value.length),
    get,
  ),
)
//=> eating

Since

v0.0.1

minWithAsync

Returns an async iterable containing a minimum value of asyncIterable by comparing the numerical values of each value, as defined by fn, if asyncIterable contains at least one value. Otherwise, returns an empty async iterable.

Example

console.log(
  await pipe(
    asAsync([`eating`, `sleeping`, `yawning`]),
    minWithAsync(value => value.length),
    getAsync,
  ),
)
//=> eating

Since

v0.0.1

minWithConcur

Returns a concur iterable containing a minimum value of concurIterable by comparing the numerical values of each value, as defined by fn, if concurIterable contains at least one value. Otherwise, returns an empty concur iterable.

Example

console.log(
  await pipe(
    asConcur([`eating`, `sleeping`, `yawning`]),
    minWithConcur(value => value.length),
    getConcur,
  ),
)
//=> eating

Since

v0.0.1

sum

Returns the sum of the numbers of iterable.

Example

console.log(sum([1, 4, 6, 2]))
//=> 13

Since

v0.0.1

sumAsync

Returns a promise that resolves to the sum of the numbers of asyncIterable.

Example

console.log(await sumAsync(asAsync([1, 4, 6, 2])))
//=> 3

Since

v0.0.1

sumConcur

Returns a promise that resolves to the sum of the numbers of concurIterable.

Example

console.log(await sumConcur(asConcur([1, 4, 6, 2])))
//=> 3

Since

v0.0.1

toCount

Returns a Reducer that counts the number of values it receives.

Use when composing reducers. Prefer count, countAsync, and countConcur for direct use on iterables.

Example

console.log(
  pipe(
    [`sloth`, `more sloth`, `sleep`, `some sloth`],
    map(string => [string.length, string]),
    reduce(toGrouped(toCount(), toMap())),
  ),
)
//=> Map(2) { 5 => 2, 10 => 2 }

Since

v2.0.0

toMax

Returns an optional reducer that finds the maximum value of the values it receives.

Use when composing reducers. Prefer max for direct use on iterables.

Example

console.log(
  pipe(
    [`sloth`, `more sloth`, `sleep`, `some sloth`],
    map(string => [string.length, string.codePointAt(0)]),
    reduce(toGrouped(toMax(), toMap())),
  ),
)
//=> Map(2) { 5 => 115, 10 => 115 }

Since

v2.0.0

toMaxBy

Returns an optional reducer that finds the maximum value of the values it receives based on the fn Compare function.

Use when composing reducers. Prefer maxBy for direct use on iterables.

Example

console.log(
  pipe(
    [`sloth`, `more sloth`, `sleep`, `some sloth`],
    map(string => [string.length, string]),
    reduce(toGrouped(toMaxBy((s1, s2) => s1.localeCompare(s2)), toMap())),
  ),
)
//=> Map(2) { 5 => 'sloth', 10 => 'some sloth' }

Since

v2.0.0

toMaxByAsync

Returns an async optional reducer that finds the maximum value of the values it receives based on the fn AsyncCompare function.

Use when composing reducers. Prefer maxByAsync and maxByConcur for direct use on iterables.

Since

v2.0.0

toMaxWith

Returns an optional reducer that finds the maximum value of the values it receives by comparing the numerical values of each value, as defined by fn.

Use when composing reducers. Prefer maxWith for direct use on iterables.

Example

console.log(
  pipe(
    [`sloth`, `more sloth`, `sleep`, `some sloth`],
    map(string => [string.length, string]),
    reduce(toGrouped(toMaxWith(string => string.codePointAt(0)), toMap())),
  ),
)
//=> Map(2) { 5 => 'sloth', 10 => 'some sloth' }

Since

v2.0.0

toMaxWithAsync

Returns an async optional reducer that finds the maximum value of the values it receives by comparing the numerical values of each value, as defined by fn.

Use when composing reducers. Prefer maxWithAsync and maxWithConcur for direct use on iterables.

Since

v2.0.0

toMean

Returns a Reducer that computes the mean of the numbers it receives.

Use when composing reducers. Prefer mean, meanAsync, and meanConcur for direct use on iterables.

Example

console.log(
  pipe(
    [`sloth`, `more sloth`, `sleep`, `some sloth`],
    map(string => [string.length, [...string].filter(c => c === `o`).length]),
    reduce(toGrouped(toMean(), toMap())),
  ),
)
//=> Map(2) { 5 => 0.5, 10 => 2 }

Since

v3.5.0

toMin

Returns an optional reducer that finds the minimum value of the values it receives.

Use when composing reducers. Prefer min for direct use on iterables.

Example

console.log(
  pipe(
    [`sloth`, `more sloth`, `sleep`, `some sloth`],
    map(string => [string.length, string.codePointAt(0)]),
    reduce(toGrouped(toMin(), toMap())),
  ),
)
//=> Map(2) { 5 => 115, 10 => 109 }

Since

v2.0.0

toMinBy

Returns an optional reducer that finds the minimum value of the values it receives based on the fn Compare function.

Use when composing reducers. Prefer minBy for direct use on iterables.

Example

console.log(
  pipe(
    [`sloth`, `more sloth`, `sleep`, `some sloth`],
    map(string => [string.length, string]),
    reduce(toGrouped(toMinBy((s1, s2) => s1.localeCompare(s2)), toMap())),
  ),
)
//=> Map(2) { 5 => 'sleep', 10 => 'more sloth' }

Since

v2.0.0

toMinByAsync

Returns an async optional reducer that finds the minimum value of the values it receives based on the fn AsyncCompare function.

Use when composing reducers. Prefer minByAsync and minByConcur for direct use on iterables.

Since

v2.0.0

toMinMax

Returns an optional reducer that finds the MinMax value of the values it receives.

Use when composing reducers. Prefer minMax for direct use on iterables.

Example

console.log(
  pipe(
    [`sloth`, `more sloth`, `sleep`, `some sloth`],
    map(string => [string.length, string.codePointAt(0)]),
    reduce(toGrouped(toMinMax(), toMap())),
  ),
)
//=> Map(2) { 5 => { min: 115, max: 115 }, 10 => { min: 109, max: 115 } }

Since

v2.0.0

toMinMaxBy

Returns an optional reducer that finds the MinMax value of the values it receives based on the fn Compare function.

Use when composing reducers. Prefer minMaxBy for direct use on iterables.

Example

console.log(
  pipe(
    [`sloth`, `more sloth`, `sleep`, `some sloth`],
    map(string => [string.length, string]),
    reduce(toGrouped(toMinMaxBy((s1, s2) => s1.localeCompare(s2)), toMap())),
  ),
)
//=> Map(2) {
//=>   5 => { min: 'sleep', max: 'sloth' },
//=>   10 => { min: 'more sloth', max: 'some sloth' }
//=> }

Since

v2.0.0

toMinMaxByAsync

Returns an async optional reducer that finds the MinMax value of the values it receives based on the fn AsyncCompare function.

Use when composing reducers. Prefer minMaxByAsync and minMaxByConcur for direct use on iterables.

Since

v2.0.0

toMinMaxWith

Returns an optional reducer that finds the MinMax value of the values it receives by comparing the numerical values of each value, as defined by fn.

Use when composing reducers. Prefer minMaxWith for direct use on iterables.

Example

console.log(
  pipe(
    [`sloth`, `more sloth`, `sleep`, `some sloth`],
    map(string => [string.length, string]),
    reduce(toGrouped(toMinMaxWith(string => string.codePointAt(0)), toMap())),
  ),
)
//=> Map(2) {
//=>   5 => { min: 'sloth', max: 'sloth' },
//=>   10 => { min: 'more sloth', max: 'some sloth' }
//=> }

Since

v2.0.0

toMinMaxWithAsync

Returns an async optional reducer that finds the MinMax value of the values it receives by comparing the numerical values of each value, as defined by fn.

Use when composing reducers. Prefer minMaxWithAsync and minMaxWithConcur for direct use on iterables.

Since

v2.0.0

toMinWith

Returns an optional reducer that finds the minimum value of the values it receives by comparing the numerical values of each value, as defined by fn.

Use when composing reducers. Prefer minWith for direct use on iterables.

Example

console.log(
  pipe(
    [`sloth`, `more sloth`, `sleep`, `some sloth`],
    map(string => [string.length, string]),
    reduce(toGrouped(toMinWith(string => string.codePointAt(0)), toMap())),
  ),
)
//=> Map(2) { 5 => 'sloth', 10 => 'more sloth' }

Since

v2.0.0

toMinWithAsync

Returns an async optional reducer that finds the minimum value of the values it receives by comparing the numerical values of each value, as defined by fn.

Use when composing reducers. Prefer minWithAsync and minWithConcur for direct use on iterables.

Since

v2.0.0

toSum

Returns a Reducer that sums the numbers it receives.

Use when composing reducers. Prefer sum, sumAsync, and sumConcur for direct use on iterables.

Example

console.log(
  pipe(
    [`sloth`, `more sloth`, `sleep`, `some sloth`],
    map(string => [string.length, string.length]),
    reduce(toGrouped(toSum(), toMap())),
  ),
)
//=> Map(2) { 5 => 10, 10 => 20 }

Since

v2.0.0

Transforms​

FunctionDescription

flatMap

Returns an iterable containing the values of the iterables returned from applying fn to each value of iterable in iteration order.

Like Array.prototype.flatMap, but for iterables.

Example

console.log(
  pipe(
    [`sloth`, `more sloth`, `even more sloth`],
    flatMap(string => [string, string.length]),
    reduce(toArray()),
  ),
)
//=> [ 'sloth', 5, 'more sloth', 10, 'even more sloth', 15 ]

Since

v0.0.1

flatMapAsync

Returns an async iterable containing the values of the async iterables returned, or resolving from promises returned, from applying fn to each value of asyncIterable in iteration order.

Like Array.prototype.flatMap, but for async iterables.

Example

console.log(
  await pipe(
    asAsync([`sloth`, `more sloth`, `even more sloth`]),
    flatMapAsync(string => [string, string.length]),
    reduceAsync(toArray()),
  ),
)
//=> [ 'sloth', 5, 'more sloth', 10, 'even more sloth', 15 ]

Since

v0.0.1

flatMapConcur

Returns an concur iterable containing the values of the concur iterables returned, or resolving from promises returned, from applying fn to each value of concurIterable.

Like Array.prototype.flatMap, but for concur iterables.

Example

console.log(
  await pipe(
    asConcur([`sloth`, `more sloth`, `even more sloth`]),
    flatMapConcur(string => [string, string.length]),
    reduceConcur(toArray()),
  ),
)
//=> [ 'sloth', 5, 'more sloth', 10, 'even more sloth', 15 ]

Since

v0.0.1

flatten

Returns an iterable that contains the values of each iterable in iterable in iteration order.

Like Array.prototype.flat, but for iterables.

Example

console.log(
  pipe(
    [[1, 2], [3, `sloth`, 5], [6, 7]],
    flatten,
    reduce(toArray()),
  ),
)
//=> [ 1, 2, 3, 'sloth', 5, 6, 7 ]

Since

v0.0.1

flattenAsync

Returns an async iterable that contains the values of each iterable in asyncIterable in iteration order.

Like Array.prototype.flat, but for async iterables.

Example

console.log(
  await pipe(
    asAsync([asAsync([1, 2]), [3, `sloth`, 5], asAsync([6, 7])]),
    flattenAsync,
    reduceAsync(toArray()),
  ),
)
//=> [ 1, 2, 3, 'sloth', 5, 6, 7 ]

Since

v0.0.1

flattenConcur

Returns a concur iterable that contains the values of each iterable in concurIterable.

Like Array.prototype.flat, but for concur iterables.

Unlike concat and concatAsync, this function does not necessarily iterate over each iterable in sequence.

Example

console.log(
  await pipe(
    asConcur([asConcur([1, 2]), [3, `sloth`, 5], asAsync([6, 7])]),
    flattenConcur,
    reduceConcur(toArray()),
  ),
)
//=> [ 1, 2, 3, 'sloth', 5, 6, 7 ]

Since

v0.0.1

index

Returns an iterable equivalent to iterable except each value of iterable is placed in an entry containing the value's 0-based index in the iteration order followed by the value itself.

Example

console.log(
  pipe(
    [`sloth`, `more sloth`, `even more sloth`],
    index,
    reduce(toArray()),
  ),
)
//=> [ [ 0, 'sloth' ], [ 1, 'more sloth' ], [ 2, 'even more sloth' ] ]

Since

v2.0.0

indexAsync

Returns an async iterable equivalent to asyncIterable except each value of asyncIterable is placed in an entry containing the value's 0-based index in the iteration order followed by the value itself.

Example

console.log(
  await pipe(
    asAsync([`sloth`, `more sloth`, `even more sloth`]),
    indexAsync,
    reduceAsync(toArray()),
  ),
)
//=> [ [ 0, 'sloth' ], [ 1, 'more sloth' ], [ 2, 'even more sloth' ] ]

Since

v2.0.0

indexConcur

Returns a concur iterable equivalent to concurIterable except each value of concurIterable is placed in an entry containing the value's 0-based index in the iteration order followed by the value itself.

Example

console.log(
  await pipe(
    asConcur([`sloth`, `more sloth`, `even more sloth`]),
    indexConcur,
    reduceConcur(toArray()),
  ),
)
//=> [ [ 0, 'sloth' ], [ 1, 'more sloth' ], [ 2, 'even more sloth' ] ]

Since

v2.0.0

map

Returns an iterable containing the values of iterable transformed by fn in iteration order.

Like Array.prototype.map, but for iterables.

Example

console.log(
  pipe(
    [`sloth`, `more sloth`, `even more sloth`],
    map(string => string.length),
    reduce(toArray()),
  ),
)
//=> [ 5, 10, 15 ]

Since

v0.0.1

mapAsync

Returns an async iterable containing the values of asyncIterable transformed by fn in iteration order.

Like Array.prototype.map, but for async iterables.

Example

console.log(
  await pipe(
    asAsync([`sloth`, `more sloth`, `even more sloth`]),
    mapAsync(string => string.length),
    reduceAsync(toArray()),
  ),
)
//=> [ 5, 10, 15 ]

Since

v0.0.1

mapConcur

Returns a concur iterable containing the values of concurIterable transformed by fn in iteration order.

Like Array.prototype.map, but for concur iterables.

Example

console.log(
  await pipe(
    asConcur([`sloth`, `more sloth`, `even more sloth`]),
    mapConcur(string => string.length),
    reduceConcur(toArray()),
  ),
)
//=> [ 5, 10, 15 ]

Since

v0.0.1