Iterable Functions

Really simple functions for working with iterable types, inspired by F#'s seq module design.

Features

Full type-safety with TypeScript
Zero dependency
Pure functions

Installation

Add package using NPM or yarn

npm i --save iterable-fns

yarn add iterable-fns

You can import the top level modules directly:

import { groupBy } from 'iterable-fns'

Examples

Calculating primes lazily with iterators can either be done by calling each of the basic functions:

import { count, initRaw, map, filter } from '../src/iterable-fns'

const range = initRaw({ from: 1, to: 100 })
const mapped = map(range, (x) => ({
  x,
  factors: filter(initRaw({ from: 1, to: x }), (y) => x % y === 0),
}))
const filtered = filter(mapped, (num) => count(num.factors) === 2)
const primes = map(filtered, (num) => num.x)

or can utilise the chain methods:

import { init } from 'iterable-fns'

const primes = init({ from: 1, to: 100 })
  .map((x) => ({
    x,
    factors: init({ from: 1, to: x }).filter((y) => x % y === 0),
  }))
  .filter((num) => num.factors.count() === 2)
  .map((num) => num.x)

for (const prime of primes) {
  console.log(prime)
}

Grouping numbers into odd and even buckets

import { init, toArray } from 'iterable-fns'

const oddAndEven = init({ from: 1, to: 25 })
  .groupBy((i) => (i % 2 === 0 ? 'even' : 'odd'))
  .map(([key, values]) => [key, toArray(values)])

NPM scripts

yarn test: Run test suite
yarn start: Run yarn build in watch mode
yarn test:watch: Run test suite in interactive watch mode
yarn test:prod: Run linting and generate coverage
yarn build: Generate bundles and typings, create docs
yarn lint: Lints code
yarn commit: Commit using conventional commit style (husky will tell you to use it if you haven't :wink:)

Index

Classes

ChainableIterable

Interfaces

Variables

length

Functions

Variables

Const length

length: count = count

Returns the number of items in the collection.

param: The input collection.
alias: count
example: length(init(5)) // Returns: 5

Functions

append

append<T>(first: Iterable<T>, second: Iterable<T>): Iterable<T>

- Defined in iterable-fns.ts:129
Wraps the two given iterables as a single concatenated iterable.

example

append( init({ from: 1, to: 3 }), init({ from: 8, to: 10 }) ) // Yields: 1, 2, 3, 8, 9, 10

Type parameters
- T
Parameters
- first: Iterable<T>
 
 The first iterable.
- second: Iterable<T>
 
 The second iterable.
Returns Iterable<T>

chain

chain<T>(source: Iterable<T>): ChainableIterable<T>

- Defined in iterable-fns.ts:1279
Create a new chainable iterator from an existing iterable source.

example

function* source() { yield { name: 'CAT', age: 18 } yield { name: 'Amy', age: 21 } yield { name: 'bob', age: 2 } } chain(source()) .filter((x) => x.age >= 18) .map((x) => x.name) .sortBy((x) => x.toLowerCase()) .toArray()

Type parameters
- T
Parameters
- source: Iterable<T>
 
 The input collection.
Returns ChainableIterable<T>

choose

choose<T, U>(source: Iterable<T>, chooser: (item: T, index: number) => U | undefined): Iterable

- Defined in iterable-fns.ts:72
Applies the given function to each element of the sequence and returns a new sequence comprised of the results for each element where the function returns a value. This can be thought of as doing both a filter and a map at the same time.

example

choose( init({ start: 1, count: 3 }), (x) => (x % 2 === 1 ? x * 2 : undefined) ) // Yields: 2, 6

Type parameters
- T
- U
Parameters
- source: Iterable<T>
 
 The input collection.
- chooser: (item: T, index: number) => U | undefined
 
 A function to transform items from the input collection to a new value to be included, or undefined to be excluded.
 - - (item: T, index: number): U | undefined
 - Parameters
 - item: T
 - index: number
 Returns U | undefined
Returns Iterable

collect

collect<T, U>(source: Iterable<T>, mapping: (item: T, index: number) => Iterable): Iterable

- Defined in iterable-fns.ts:105
Applies the given function to each element of the source iterable and concatenates all the results.

example

collect( init({ start: 1, count: 3 }), function* (x) { yield x yield x } ) // Yields: 1, 1, 2, 2, 3, 3

// You can also just return an array from your mapping function collect( init({ start: 1, count: 3 }), (x) => [x, x] )

Type parameters
- T
- U
Parameters
- source: Iterable<T>
 
 The input collection.
- mapping: (item: T, index: number) => Iterable
 
 A function to transform elements of the input collection into collections that are concatenated.
 - - (item: T, index: number): Iterable
 - Parameters
 - item: T
 - index: number
 Returns Iterable
Returns Iterable

concat

concat<T>(sources: Iterable<Iterable<T>>): Iterable<T>

- Defined in iterable-fns.ts:148
Combines the given collection-of-iterables as a single concatenated iterable.

example

concat([ init({ from: 1, to: 2 }), init({ from: 4, to: 5 }), init({ from: 8, to: 9 }) ]) // Yields 1, 2, 4, 5, 8, 9

Type parameters
- T
Parameters
- sources: Iterable<Iterable<T>>
 
 The input collection.
Returns Iterable<T>

count

count<T>(source: Iterable<T>): number

- Defined in iterable-fns.ts:498
Returns the number of items in the collection.

example

count(init(5)) // Returns: 5

Type parameters
- T
Parameters
- source: Iterable<T>
 
 The input collection.
Returns number

distinct

distinct<T>(source: Iterable<T>): Iterable<T>

- Defined in iterable-fns.ts:171
Returns a iterable that contains no duplicate entries according to the equality comparisons on the elements. If an element occurs multiple times in the sequence then the later occurrences are discarded.

example

function* source() { yield 'bob' yield 'cat' yield 'bob' yield 'amy' } distinct(source()) // Yields: 'bob', 'cat', 'amy'

Type parameters
- T
Parameters
- source: Iterable<T>
 
 The input collection.
Returns Iterable<T>

distinctBy

distinctBy<T, Key>(source: Iterable<T>, selector: (item: T, index: number) => Key): Iterable<T>

- Defined in iterable-fns.ts:202
Returns a iterable that contains no duplicate entries according to the equality comparisons on the keys returned by the given key-generating function. If an element occurs multiple times in the sequence then the later occurrences are discarded.

example

function* source() { yield { name: 'amy', id: 1 } yield { name: 'bob', id: 2 } yield { name: 'bob', id: 3 } yield { name: 'cat', id: 3 } } distinctBy(source(), (x) => x.name) // Yields: // { name: 'amy', id: 1 } // { name: 'bob', id: 2 } // { name: 'cat', id: 3 }

Type parameters
- T
- Key
Parameters
- source: Iterable<T>
 
 The input collection.
- selector: (item: T, index: number) => Key
 
 A function that transforms the collection items into comparable keys.
 - - (item: T, index: number): Key
 - Parameters
 - item: T
 - index: number
 Returns Key
Returns Iterable<T>

every

every<T>(source: Iterable<T>, predicate: (item: T, index: number) => boolean): boolean

- Defined in iterable-fns.ts:248
Tests if every element of the collection satisfies the given predicate.

example

every(init({ from: 1, to: 3 }), (x) => x > 0) // Returns: true every(init({ from: 1, to: 3 }), (x) => x < 2) // Returns: false

Type parameters
- T
Parameters
- source: Iterable<T>
 
 The input collection.
- predicate: (item: T, index: number) => boolean
 
 A function to test against each item of the input collection.
 - - (item: T, index: number): boolean
 - Parameters
 - item: T
 - index: number
 Returns boolean
Returns boolean

exists

exists<T>(source: Iterable<T>, predicate: (item: T, index: number) => boolean): boolean

- Defined in iterable-fns.ts:226
Tests if any element of the collection satisfies the given predicate.

example

exists(init({ from: 1, to: 3 }), (x) => x === 2) // Returns: true exists(init({ from: 1, to: 3 }), (x) => x === 4) // Returns: false

Type parameters
- T
Parameters
- source: Iterable<T>
 
 The input collection.
- predicate: (item: T, index: number) => boolean
 
 A function to test each item of the input collection.
 - - (item: T, index: number): boolean
 - Parameters
 - item: T
 - index: number
 Returns boolean
Returns boolean

filter

filter<T>(source: Iterable<T>, predicate: (item: T, index: number) => boolean): Iterable<T>

- Defined in iterable-fns.ts:48
Returns a new iterable containing only the elements of the collection for which the given predicate returns true.

example

filter( init({ start: 1, count: 4 }), (x) => x % 2 === 0 ) // Yields: 2, 4

Type parameters
- T
Parameters
- source: Iterable<T>
 
 The input collection.
- predicate: (item: T, index: number) => boolean
 
 A function to test whether each item in the input collection should be included in the output.
 - - (item: T, index: number): boolean
 - Parameters
 - item: T
 - index: number
 Returns boolean
Returns Iterable<T>

find

find<T>(source: Iterable<T>, predicate: (item: T, index: number) => boolean): T | undefined

- Defined in iterable-fns.ts:298
Returns the first element for which the given function returns true, otherwise undefined.

example

function* source() { yield { name: 'amy', id: 1 } yield { name: 'bob', id: 2 } } find(source(), (p) => p.name === 'bob') // Returns: { name: 'bob', id: 2 } find(source(), (p) => p.name === 'cat') // Returns: undefined

Type parameters
- T
Parameters
- source: Iterable<T>
 
 The input collection.
- predicate: (item: T, index: number) => boolean
 
 A function to test whether an item in the collection should be returned.
 - - (item: T, index: number): boolean
 - Parameters
 - item: T
 - index: number
 Returns boolean
Returns T | undefined

get

get<T>(source: Iterable<T>, predicate: (item: T, index: number) => boolean): T

- Defined in iterable-fns.ts:275
Returns the first element for which the given function returns true.

throws

If no item is found matching the criteria of the predicate.

example

function* source() { yield { name: 'amy', id: 1 } yield { name: 'bob', id: 2 } } get(source(), (p) => p.name === 'bob') // Returns: { name: 'bob', id: 2 } get(source(), (p) => p.name === 'cat') // Throws: Element not found matching criteria

Type parameters
- T
Parameters
- source: Iterable<T>
 
 The input collection.
- predicate: (item: T, index: number) => boolean
 
 A function to test whether an item in the collection should be returned.
 - - (item: T, index: number): boolean
 - Parameters
 - item: T
 - index: number
 Returns boolean
Returns T

groupBy

groupBy<T, Key>(source: Iterable<T>, selector: (item: T, index: number) => Key): Map<Key, T[]>

- Defined in iterable-fns.ts:330
Applies a key-generating function to each element of a collection and yields a iterable of unique keys and an array of all elements that have each key.

NOTE: Requires complete iteration of source before yielding first element.

example

function* source() { yield { name: 'amy', age: 1 } yield { name: 'bob', age: 2 } yield { name: 'cat', age: 2 } } groupBy(source(), (x) => x.age) // Yields: // [1, [{ name: 'amy', age: 1 }]] // [2, [{ name: 'bob', age: 2 }, { name: 'cat', age: 2 }]]

Type parameters
- T
- Key
Parameters
- source: Iterable<T>
 
 The input collection.
- selector: (item: T, index: number) => Key
 
 A function that transforms an element of the collection into a comparable key.
 - - (item: T, index: number): Key
 - Parameters
 - item: T
 - index: number
 Returns Key
Returns Map<Key, T[]>

init

init(options: number | InitRange | InitCount): ChainableIterable<number>

- Defined in iterable-fns.ts:1244
Generates a new chainable iterable which, when iterated, will return the specified number sequence.

throws

When the options would result in a sequence that would not complete. If this is the desired behaviour, use initInfinite.

example

init(3) // Yields: 0, 1, 2 init({ from: 2, to: 5 }) // Yields: 2, 3, 4, 5 init({ from: 0, to: 100, increment: 25 }) // Yields: 0, 25, 50, 75, 100

Parameters
- options: number | InitRange | InitCount
 
 The sequence of numbers to generate.
Returns ChainableIterable<number>

initInfinite

initInfinite(options?: undefined | { increment?: undefined | number; start?: undefined | number }): ChainableIterable<number>

- Defined in iterable-fns.ts:1257
Generates a new chainable iterable which, when iterated, will return the specified number sequence.

example

initInfinite() // Yields: 0, 1, 2, ... initInfinite({ start: 99 }) // Yields: 99, 100, 101 ... initInfinite({ start: 1, increment: -0.5 }) // Yields: 1, 0.5, 0, -0.5, -1, ...

Parameters
- Optional options: undefined | { increment?: undefined | number; start?: undefined | number }
 
 The sequence of numbers to generate.
Returns ChainableIterable<number>

initInfiniteRaw

initInfiniteRaw(options?: undefined | { increment?: undefined | number; start?: undefined | number }): Iterable<number>

- Defined in iterable-fns.ts:441
Generates a new iterable which, when iterated, will return the specified number sequence.

example

initInfiniteRaw() // Yields: 0, 1, 2, ... initInfiniteRaw({ start: 99 }) // Yields: 99, 100, 101 ... initInfiniteRaw({ start: 1, increment: -0.5 }) // Yields: 1, 0.5, 0, -0.5, -1, ...

Parameters
- Optional options: undefined | { increment?: undefined | number; start?: undefined | number }
 
 The sequence of numbers to generate.
Returns Iterable<number>

initRaw

initRaw(options: number | InitRange | InitCount): Iterable<number>

- Defined in iterable-fns.ts:392
Generates a new iterable which, when iterated, will return the specified number sequence.

throws

When the options would result in a sequence that would not complete. If this is the desired behaviour, use initInfinite.

example

initRaw(3) // Yields: 0, 1, 2 initRaw({ from: 2, to: 5 }) // Yields: 2, 3, 4, 5 initRaw({ from: 0, to: 100, increment: 25 }) // Yields: 0, 25, 50, 75, 100

Parameters
- options: number | InitRange | InitCount
 
 The sequence of numbers to generate.
Returns Iterable<number>

map

map<T, U>(source: Iterable<T>, mapping: (item: T, index: number) => U): Iterable

- Defined in iterable-fns.ts:27
Creates a new iterable whose elements are the results of applying the specified mapping to each of the elements of the source collection.

example

map( init({ start: 1, count: 3 }), (x) => x * 2 ) // Yields: 2, 4, 6

Type parameters
- T
- U
Parameters
- source: Iterable<T>
 
 The input collection.
- mapping: (item: T, index: number) => U
 
 A function to transform items from the input collection.
 - - (item: T, index: number): U
 - Parameters
 - item: T
 - index: number
 Returns U
Returns Iterable

max

max(source: Iterable<number>): number

- Defined in iterable-fns.ts:688
Returns the maximum of the values in the collection.

throws

If the collection is empty.

example

max(init({ from: 5, to: 10 })) // Returns: 10

Parameters
- source: Iterable<number>
 
 The input collection.
Returns number

maxBy

maxBy<T>(source: Iterable<T>, selector: (item: T) => number): number

- Defined in iterable-fns.ts:715
Returns the maximum of the values returned by the selector for each element in the collection.

throws

If the collection is empty.

example

function* source() { yield { name: 'amy', age: 21 } yield { name: 'bob', age: 2 } yield { name: 'cat', age: 18 } } maxBy(source(), (x) => x.age) // Returns: 21

Type parameters
- T
Parameters
- source: Iterable<T>
 
 The input collection.
- selector: (item: T) => number
 
 A function to transform each element into a comparable value.
 - - (item: T): number
 - Parameters
 - item: T
 Returns number
Returns number

mean

mean(source: Iterable<number>): number

- Defined in iterable-fns.ts:786
Returns the mean (average) of the values in the collection.

throws

If the collection is empty.

example

mean(init({ from: 5, to: 10 })) // Returns: 7.5

Parameters
- source: Iterable<number>
 
 The input collection.
Returns number

meanBy

meanBy<T>(source: Iterable<T>, selector: (item: T) => number): number

- Defined in iterable-fns.ts:814
Returns the mean (average) of the values returned by the selector for each element in the collection.

throws

If the collection is empty.

example

function* source() { yield { name: 'amy', age: 21 } yield { name: 'bob', age: 2 } yield { name: 'cat', age: 18 } yield { name: 'dot', age: 39 } } meanBy(source(), (x) => x.age) // Returns: 20

Type parameters
- T
Parameters
- source: Iterable<T>
 
 The input collection.
- selector: (item: T) => number
 
 A function to transform each element into a summable value.
 - - (item: T): number
 - Parameters
 - item: T
 Returns number
Returns number

min

min(source: Iterable<number>): number

- Defined in iterable-fns.ts:737
Returns the minimum of the values in the collection.

throws

If the collection is empty.

example

min(init({ from: 5, to: 10 })) // Returns: 5

Parameters
- source: Iterable<number>
 
 The input collection.
Returns number

minBy

minBy<T>(source: Iterable<T>, selector: (item: T) => number): number

- Defined in iterable-fns.ts:764
Returns the minimum of the values returned by the selector for each element in the collection.

throws

If the collection is empty.

example

function* source() { yield { name: 'amy', age: 21 } yield { name: 'bob', age: 2 } yield { name: 'cat', age: 18 } } minBy(source(), (x) => x.age) // Returns: 2

Type parameters
- T
Parameters
- source: Iterable<T>
 
 The input collection.
- selector: (item: T) => number
 
 A function to transform each element into a comparable value.
 - - (item: T): number
 - Parameters
 - item: T
 Returns number
Returns number

pairwise

pairwise<T>(source: Iterable<T>): Iterable<[T, T]>

- Defined in iterable-fns.ts:357
Returns an interable of each element in the input sequence and its predecessor, with the exception of the first element which is only returned as the predecessor of the second element.

example

pairwise(init({ from: 1, to: 4 })) // Yields: [1, 2], [2, 3], [3, 4]

Type parameters
- T
Parameters
- source: Iterable<T>
 
 The input collection
Returns Iterable<[T, T]>

reverse

reverse<T>(source: Iterable<T>): Iterable<T>

- Defined in iterable-fns.ts:637
Yields each element of the iterable in reverse order.

NOTE: Requires complete iteration of source before yielding first element.

example

function* source() { yield 'cat' yield 'amy' yield 'bob' } reverse(source()) // Yields: 'bob', 'amy', 'cat'

Type parameters
- T
Parameters
- source: Iterable<T>
 
 The input collection.
Returns Iterable<T>

skip

skip<T>(source: Iterable<T>, count: number): Iterable<T>

- Defined in iterable-fns.ts:460
Returns the elements of the iterable after a specified count.

example

skip(init({ from: 1, to: 5}), 2) // Yields: 3, 4, 5

Type parameters
- T
Parameters
- source: Iterable<T>
 
 The input collection.
- count: number
 
 The number of items to skip.
Returns Iterable<T>

sort

sort<T, Key>(source: Iterable<T>, selector?: undefined | ((item: T) => Key)): Iterable<T>

- Defined in iterable-fns.ts:534
Yields an iterable ordered by the selected key. If no selector is specified, the elements will be compared directly.

NOTE: Requires complete iteration of source before yielding first element.

example

sort(init({ from 3, to: 1 })) // Yields 1, 2, 3

function* source() { yield 'Cat' yield 'amy' yield 'BOB' } sort(source(), (n) => n.toLowerCase()) // Yields: 'amy', 'BOB', 'Cat'

Type parameters
- T
- Key
Parameters
- source: Iterable<T>
 
 The input collection.
- Optional selector: undefined | ((item: T) => Key)
 
 An optional function to transform items of the input sequence into comparable keys.
Returns Iterable<T>

sortBy

sortBy<T, Key>(source: Iterable<T>, selector: (item: T) => Key): Iterable<T>

- Defined in iterable-fns.ts:589
Applies a key-generating function to each element of the collection and yields an iterable ordered by keys.

NOTE: Requires complete iteration of source before yielding first element.

example

function* source() { yield 'Cat' yield 'amy' yield 'BOB' } sortBy(source(), (n) => n.toLowerCase()) // Yields: 'amy', 'BOB', 'Cat'

Type parameters
- T
- Key
Parameters
- source: Iterable<T>
 
 The input collection.
- selector: (item: T) => Key
 
 A function to transform items of the input sequence into comparable keys.
 - - (item: T): Key
 - Parameters
 - item: T
 Returns Key
Returns Iterable<T>

sortByDescending

sortByDescending<T, Key>(source: Iterable<T>, selector: (item: T) => Key): Iterable<T>

- Defined in iterable-fns.ts:612
Applies a key-generating function to each element of the collection and yields an iterable ordered by keys, descending.

NOTE: Requires complete iteration of source before yielding first element.

example

function* source() { yield 'Cat' yield 'amy' yield 'BOB' } sortByDescending(source(), (n) => n.toLowerCase()) // Yields: 'Cat', 'BOB', 'amy'

Type parameters
- T
- Key
Parameters
- source: Iterable<T>
 
 The input collection.
- selector: (item: T) => Key
 
 A function to transform items of the input sequence into comparable keys.
 - - (item: T): Key
 - Parameters
 - item: T
 Returns Key
Returns Iterable<T>

sortDescending

sortDescending<T, Key>(source: Iterable<T>, selector?: undefined | ((item: T) => Key)): Iterable<T>

- Defined in iterable-fns.ts:562
Yields an iterable ordered by the selected key descending. If no selector is specified, the elements will be compared directly.

NOTE: Requires complete iteration of source before yielding first element.

example

sortDescending(init({ from 1, to: 3 })) // Yields 3, 2, 1

function* source() { yield 'Cat' yield 'amy' yield 'BOB' } sortDescending(source(), (n) => n.toLowerCase()) // Yields: 'Cat', 'BOB', 'amy'

Type parameters
- T
- Key
Parameters
- source: Iterable<T>
 
 The input collection.
- Optional selector: undefined | ((item: T) => Key)
 
 An optional function to transform items of the input sequence into comparable keys.
Returns Iterable<T>

sum

sum(source: Iterable<number>): number

- Defined in iterable-fns.ts:651
Returns the sum of the values in the collection.

example

sum(init({ from: 5, to: 10 })) // Returns: 45

Parameters
- source: Iterable<number>
 
 The input collection.
Returns number

sumBy

sumBy<T>(source: Iterable<T>, selector: (item: T) => number): number

- Defined in iterable-fns.ts:672
Returns the sum of the values returned by the selector for each element in the collection.

example

function* source() { yield { name: 'amy', age: 21 } yield { name: 'bob', age: 2 } yield { name: 'cat', age: 18 } } sumBy(source(), (x) => x.age) // Returns: 41

Type parameters
- T
Parameters
- source: Iterable<T>
 
 The input collection.
- selector: (item: T) => number
 
 A function to transform each element into a summable value.
 - - (item: T): number
 - Parameters
 - item: T
 Returns number
Returns number

take

take<T>(source: Iterable<T>, count: number): Iterable<T>

- Defined in iterable-fns.ts:479
Returns the elements of the iterable up to a specified count.

example

take(init({ from: 1, to: 4 }), 2) // Yields: 1, 2

Type parameters
- T
Parameters
- source: Iterable<T>
 
 The input collection.
- count: number
 
 The number of items to take.
Returns Iterable<T>

toArray

toArray<T>(source: Iterable<T>): T[]

- Defined in iterable-fns.ts:13
Creates an array from the source iterable object.

alias

Array.from

example

function* source() { yield 1 yield 2 } toArray(source()) // Returns: [1, 2]

Type parameters
- T
Parameters
- source: Iterable<T>
 
 An Iterable objext to convert to an array.
Returns T[]

Generated using TypeDoc

Iterable Functions

Features

Installation

Examples

NPM scripts

Index

Classes

Interfaces

Variables

Functions

Variables

Const length

Functions

append

Type parameters

T

Parameters

first: Iterable<T>

second: Iterable<T>

Returns Iterable<T>

chain

Type parameters

T

Parameters

source: Iterable<T>

Returns ChainableIterable<T>

choose

Type parameters

T

U

Parameters

source: Iterable<T>

chooser: (item: T, index: number) => U | undefined

Parameters

item: T

index: number

Returns U | undefined

Returns Iterable<U>

collect

Type parameters

T

U

Parameters

source: Iterable<T>

mapping: (item: T, index: number) => Iterable<U>

Parameters

item: T

index: number

Returns Iterable<U>

Returns Iterable<U>

concat

Type parameters

T

Parameters

sources: Iterable<Iterable<T>>

Returns Iterable<T>

count

Type parameters

T

Parameters

source: Iterable<T>

Returns number

distinct

Type parameters

T

Parameters

source: Iterable<T>

Returns Iterable<T>

distinctBy

Type parameters

T

Key

Parameters

source: Iterable<T>

selector: (item: T, index: number) => Key

Parameters

item: T

index: number

Returns Key

Returns Iterable<T>