Description
An iterator / async-iterator library with support for old platforms that don't have iterables or async-iterables.
Iterly provides several useful functions for composing, manipulating and iterating through iterables,
async-iterables, arrays, streams, and array-like objects such as nodejs Buffer.
Even though iterly doesn't use async functions or generators, and should work on browsers as far back as ie10,
you will still need to pass your code through Babel or similar to transpile modern syntax used in this library,
such as destructuring.
Install
yarn add iterly
or npm install iterly
API
Table of Contents
- Iteration helpers
- Function composition
- Sync operators
- Async operators
- Sync / Async operators
- Range
- range
each
Loops over any iterable, async-iterable, iterator, async-iterator or array-like,
calling fn for each item. If looping over an async-iterable / async-iterator
a promise will be returned by each with the value of the final return from fn.
Parameters
x
number The number of async items to run in parallel, has no effect on sync iterables. (optional, default 1
)fn
(function (value) | function (value, done)) The fn to call for each item. The function will be called
for every value in the iterable / async-iterable. If the function has a second param (done) then
the loop function will be called when the iterable / async-iterable is done, with a done value of true.
If no second param (done) is provided then the loop function will only be called with the values from
the iterable / async-iterable.it
(iterable | asyncIterable) The iterable, async-iterable, iterator, async-iterator or array-like
to loop over.
Examples
each((value) => console.log(value), [1, 2, 3, 4])
Returns (Promise | undefined) Returns a Promise that resolves to the last value returned by fn if looping
over an async-iterable. If looping over an iterable returns undefined.
iter
Gets an iterator / async-iterator for any iterable, async-iterable, array-like, or function with a sentinel.
Parameters
obj
Object The possible iterable to create an iterator for.options
Object (optional, default {}
)
options.sentinel
Any distinct value to use as a stop indicator when creating an iterator from a function,
see iterFn.options.isAsync
Boolean If true and obj is a function, an async-iterator will be returned. (optional, default false
)
Returns (@@iterator | @@asyncIterator | undefined) Returns an iterator, async-iterator, or undefined if obj is not iterable.
iterArray
Gets an iterator for any array-like; that is anything with a length property that
can be indexed with array[index] notation.
Parameters
a
(Array | arrayLike) The array-like to create an iterator from.chunkSize
number If set larger than zero, will break the array up
into chunks of length chunkSize. (optional, default 0
)
Examples
var it = iterArray([1, 2, 3, 4])
var it = iterArray([1, 2, 3, 4], 2)
Returns @@iterator Returns an iterator with the values from the array-like.
iterObject
Gets an iterator of [key, value] pairs for any javascript object.
Parameters
o
Object The object to create an iterator from. Only iterates over an objects own-properties.
Examples
var it = iterObject({a: 1, b: 2, c: 3})
Returns @@iterator Returns an iterator with the [key, value] pairs from the object.
iterFn
Turns a function into an iterator.
Parameters
fn
function ({i, sentinel}) The iterator will return whatever this function returns,
until it returns the sentinel value, then it will stop. The function is given an object with
an index i and the sentinel value, you can add any other state you want to keep between iterations
to this object if you like.options
Object This options object must contain the sentinel property, the sentinel
is returned by fn to signal the end of iteration.
options.sentinel
Any distinct value to use as an indicator that the iterator function is done.options.isAsync
Boolean If true an async-iterator will be returned. (optional, default false
)
Examples
var it = iterFn(({i, sentinel}) => i >= 4 ? sentinel : i * 2, {sentinel: {}})
Returns (@@iterator | @@asyncIterator) Returns an iterator or async-iterator with the values returned by fn.
compose
Perhaps the most useful function here; allows you to compose (combine)
other functions into one new function that takes one argument of
an iterable, async-iterable, iterator, or async-iterator.
Parameters
fns
...function Any number of functions to combine.
Examples
var urlPrefix = 'http://some.resource.com/'
var files = ['file.txt', 'file2.txt', 'file3.txt', 'file4.txt']
var getShortTexts = compose(
filter.curry(file => file != 'file3.txt'),
map.curry(file => urlPrefix + file),
amap.curry(url => fetch(url).then(res => res.text())),
afilter.curry(txt => txt.length <= 140),
)
each(txt => console.log(txt), getShortTexts([files]))
Returns function (it: anyIterableOrAsyncIterable) The composed function.
curry
Returns a curried version of the provided function.
Parameters
fn
function The function to curry.args
...any? Any arguments to bind.
Returns function Returns the curried function.
map
A function that maps iterator or iterable values over a function.
Parameters
fn
function (value: any, index: number) The function to modify each value in the iterator.it
@@iterator The iterator or iterable to map over.
Examples
var it = map(v => 2 * v, [1, 2, 3, 4])
Returns @@iterator Returns an iterator with values that will be updated by fn.
curry
Allows you to curry the arguments, most useful when used with compose.
Parameters
args
...any The arguments to bind.
Examples
var curried = map.curry(v => 2 * v)
var it = [1, 2, 3, 4]
it = curried(it)
Returns curriedFunction The curried version of the original function, with bindable args.
reduce
A function that reduces all the items in an iterator or iterable to one value.
Parameters
fn
function (accumulator: any, value: any, index: number) The reducer function continually updates
the accumulator, until the iterator ends, then the accumulated value is returned.acc
The accumulator's initial value, each item in the iterator or iterable will be added to this by fn.it
@@iterator The iterator or iterable to reduce.
Examples
var it = reduce((acc, v) => acc += v, 0, [1, 2, 3, 4])
var it = reduce((acc, v, i) => (acc[i] = v, acc), [], [1, 2, 3, 4])
Returns @@iterator Returns an iterator with only one value.
curry
Allows you to curry the arguments, most useful when used with compose.
Parameters
args
...any The arguments to bind.
Examples
var curried = reduce.curry((acc, val) => acc + val)
var it = [1, 2, 3, 4]
it = curried(it)
Returns curriedFunction The curried version of the original function, with bindable args.
filter
A function that keeps values in an iterator or iterable only if fn returns true.
Parameters
fn
function (value: any, index: number) The test function to filter items,
return true to keep the item, false to remove it.it
@@iterator The iterator or iterable to filter.
Examples
var it = filter(v => v != 2, [1, 2, 3, 4])
Returns @@iterator Returns an iterator with only the values that passed the test fn.
curry
Allows you to curry the arguments, most useful when used with compose.
Parameters
args
...any The arguments to bind.
Examples
var curried = filter.curry(v => v != 2)
var it = [1, 2, 3, 4]
it = curried(it)
Returns curriedFunction The curried version of the original function, with bindable args.
amap
A function that maps iterator, iterable, async-iterator or async-iterable values over a function.
Parameters
fn
function (value: any, index: number) The function to modify each value in the iterator.it
(@@iterator | @@asyncIterator) The iterator, iterable, async-iterator or async-iterable to map over.
Examples
var it = amap(v => 2 * v, [1, 2, 3, 4])
var urls = ['http://some.resource.com/file.txt', 'http://some.resource.com/file2.txt']
var it = amap(url => fetch(url).then(res => res.text()), urls)
it = amap(txt => txt.slice(0, 140), it)
each(txt => console.log(txt), it)
Returns @@asyncIterator Returns an async-iterator with values returned by fn.
curry
Allows you to curry the arguments, most useful when used with compose.
Parameters
args
...any The arguments to bind.
Examples
var curried = amap.curry(v => 2 * v)
var it = [1, 2, 3, 4]
it = curried(it)
Returns curriedFunction The curried version of the original function, with bindable args.
areduce
A function that reduces an iterator, iterable, async-iterator or async-iterable to one promised value.
Parameters
n
number If a value greater than 0 is provided, then areduce will create multiple,
grouped reductions, each made of n
items, like a scan fn. (optional, default 0
)fn
function (accumulator: any, value: any, index: number) The reducer function continually updates
the accumulator, until the iterator / async-iterator ends, then the accumulated value is returned.acc
The accumulator's initial value, each item in the iterator or iterable will be added to this by fn.it
(@@iterator | @@asyncIterator) The iterator, iterable, async-iterator or async-iterable to reduce.
Examples
var it = areduce((acc, v) => acc += v, 0, [1, 2, 3, 4])
var urls = ['http://some.resource.com/file.txt', 'http://some.resource.com/file2.txt']
var it = amap(url => fetch(url).then(res => res.text()), urls)
it = areduce((acc, txt) => acc + txt.slice(0, 140), '', it)
each(txt => console.log(txt), it)
Returns @@asyncIterator Returns an async-iterator with only one promised value.
curry
Allows you to curry the arguments, most useful when used with compose.
Parameters
args
...any The arguments to bind.
Examples
var curried = areduce.curry((acc, val) => acc + val)
var it = [1, 2, 3, 4]
it = curried(it)
Returns curriedFunction The curried version of the original function, with bindable args.
afilter
A function that keeps values in an iterator, iterable, async-iterator or async-iterable,
only if fn returns true.
Parameters
fn
function (value: any, index: number) The test function to filter items,
return true to keep the item, false to remove it.it
(@@iterator | @@asyncIterator) The iterator, iterable, async-iterator or async-iterable to filter.
Examples
var it = afilter(v => v != 2, [1, 2, 3, 4])
var urls = ['http://some.resource.com/file.txt', 'http://some.resource.com/file2.txt']
var it = amap(url => fetch(url).then(res => res.text()), urls)
it = afilter(txt => txt.length < 140, it)
each(txt => console.log(txt), it)
Returns @@asyncIterator Returns an async-iterator with the values that passed the test fn.
curry
Allows you to curry the arguments, most useful when used with compose.
Parameters
args
...any The arguments to bind.
Examples
var curried = afilter.curry(v => v != 2)
var it = [1, 2, 3, 4]
it = curried(it)
Returns curriedFunction The curried version of the original function, with bindable args.
enumerate
Enumerate takes an iterable, async-iterable, iterator, or async-iterator
and returns the same with its values updated with an [index, value] pair,
starting at 0 or at the optional start arg.
Parameters
start
number The optional index start. (optional, default 0
)it
(iterable | asyncIterable) The iterable or async-iterable to return.
Examples
var arr = ['a', 'b', 'c', 'd']
var it = enumerate(arr)
Returns (iterator | asyncIterator) Returns an iterator or async-iterator with
the [index, value] pair items.
Range
Creates a Range object that can be iterated over.
Parameters
start
number The start of the range (inclusive). (optional, default 0
)stop
number The end of the range (exclusive).step
number The stride of the range. (optional, default 1
)
Returns Range
ITERATOR
Creates an iterator of all the values in the range.
Returns Iterator
values
Creates an iterator of all the values in the range.
Returns Iterator
entries
Creates an iterator of all the entries in the range.
Returns Iterator Returns value pairs [value, value], like Set.
get
Get an item from a range by index.
Parameters
idx
number The index of the value in the range.
Returns number Returns the value at the index, or undefined.
has
Check if a value exists in a range.
Parameters
val
number The value to look for.
Returns boolean Returns true if the value exists.
indexOf
Find the index of a value in the range.
Parameters
val
number The value to look for.
Returns number Returns the index if the value exists, -1 otherwise.
new
An alternative, static method, Range constructor.
Parameters
start
number The start of the range (inclusive). (optional, default 0
)stop
number The end of the range (exclusive).step
number The stride of the range. (optional, default 1
)
Returns Range
range
An alternative, functional, Range constructor.
Parameters
start
number The start of the range (inclusive). (optional, default 0
)stop
number The end of the range (exclusive).step
number The stride of the range. (optional, default 1
)
Returns Range