@metarhia/iterator - efficient and composable iteration

Installation

$ npm install @metarhia/iterator

API

• Iterator
  • Iterator.range
  • Iterator.zip
  • Iterator.prototype.constructor
  • Iterator.prototype.apply
  • Iterator.prototype.chain
  • Iterator.prototype.chainApply
  • Iterator.prototype.collectTo
  • Iterator.prototype.collectWith
  • Iterator.prototype.count
  • Iterator.prototype.each
  • Iterator.prototype.enumerate
  • Iterator.prototype.every
  • Iterator.prototype.filter
  • Iterator.prototype.filterMap
  • Iterator.prototype.find
  • Iterator.prototype.findCompare
  • Iterator.prototype.flat
  • Iterator.prototype.flatMap
  • Iterator.prototype.forEach
  • Iterator.prototype.groupBy
  • Iterator.prototype.includes
  • Iterator.prototype.join
  • Iterator.prototype.map
  • Iterator.prototype.max
  • Iterator.prototype.min
  • Iterator.prototype.next
  • Iterator.prototype.partition
  • Iterator.prototype.reduce
  • Iterator.prototype.skip
  • Iterator.prototype.skipWhile
  • Iterator.prototype.some
  • Iterator.prototype.someCount
  • Iterator.prototype.take
  • Iterator.prototype.takeWhile
  • Iterator.prototype.toArray
  • Iterator.prototype.toObject
  • Iterator.prototype.zip
• iter
• iterEntries
• iterKeys
• iterValues
• AsyncIterator
  • AsyncIterator.prototype.constructor
  • AsyncIterator.prototype.chain
  • AsyncIterator.prototype.collectTo
  • AsyncIterator.prototype.collectWith
  • AsyncIterator.prototype.count
  • AsyncIterator.prototype.each
  • AsyncIterator.prototype.enumerate
  • AsyncIterator.prototype.every
  • AsyncIterator.prototype.filter
  • AsyncIterator.prototype.find
  • AsyncIterator.prototype.flat
  • AsyncIterator.prototype.flatMap
  • AsyncIterator.prototype.forEach
  • AsyncIterator.prototype.includes
  • AsyncIterator.prototype.join
  • AsyncIterator.prototype.map
  • AsyncIterator.prototype.next
  • AsyncIterator.prototype.parallel
  • AsyncIterator.prototype.reduce
  • AsyncIterator.prototype.skip
  • AsyncIterator.prototype.some
  • AsyncIterator.prototype.someCount
  • AsyncIterator.prototype.take
  • AsyncIterator.prototype.takeWhile
  • AsyncIterator.prototype.throttle
  • AsyncIterator.prototype.toArray
  • AsyncIterator.prototype.zip
• asyncIter

class Iterator

Iterator.range(start, stop[, step])

• start: <number>
• stop: <number>
• step: <number> (optional), default: 1

Returns: <Iterator>

Create iterator iterating over the range

Iterator.zip(...iterators)

• iterators: <Array>

Returns: <Iterator>

Create iterator by zipping multiple provided iterators into one

Iterator.prototype.constructor(base)

Iterator.prototype.apply(fn)

• fn: <Function>
  • this: <Iterator>

Returns: the result of fn(this) call.

Call a function with this. Will be equivalent to calling fn(it).

Iterator.prototype.chain(...iterators)

Iterator.prototype.chainApply(fn)

• fn: <Function>
  • this: <Iterator>

Returns: <Iterator> result of fn(this) wrapped in an Iterator.

Call a function with this and wrap the result in an Iterator.

Example:

iter([1, 2])
  .chainApply(([a, b]) => [a + b, a - b])
  .join(', ');

Result:

'3, -1';

Iterator.prototype.collectTo(CollectionClass)

Iterator.prototype.collectWith(obj, collector)

Iterator.prototype.count()

Iterator.prototype.each(fn, thisArg)

Iterator.prototype.enumerate()

Iterator.prototype.every(predicate, thisArg)

Iterator.prototype.filter(predicate, thisArg)

Iterator.prototype.filterMap(mapper[, thisArg[, filterValue]])

• mapper: <Function> function that maps values and returns either new value that will be the next value of the new iterator or filterValue that will be ignored.
  • value: <any> iterator element
• thisArg: <any> value to be used as this when calling mapper
• filterValue: <any> value to filter out mapper results.

Creates an iterator that both filters and maps with the passed mapper.

This iterator will call mapper on each element and if mapper returns NOT filterValue it will be returned, otherwise it is ignored.

Iterator.prototype.find(predicate, thisArg)

Iterator.prototype.findCompare(comparator[, accessor[, thisArg]])

• comparator: <Function> returns true if new value should be accepted
  • currValue: <any> current value, starts with undefined
  • nextValue: <any> next value
  • Returns: <boolean> true if next value should be accepted
• accessor: <Function> gets value to compare by, current iterator value is used by default
  • value: <any> current iterator value
  • Returns: <any> value to compare by
• thisArg: <any> value to be used as this when calling accessor and comparator

Returns: last iterator value where comparator returned true, <undefined> by default

Find value in this iterator by comparing every value with

the found one using comparator

Iterator.prototype.flat(depth = 1)

Iterator.prototype.flatMap(mapper, thisArg)

Iterator.prototype.forEach(fn, thisArg)

Iterator.prototype.groupBy(classifier[, thisArg])

• classifier: <Function> gets value to group by
  • value: <any> current iterator value
  • Returns: <any> value to group by
• thisArg: <any> value to be used as this when calling classifier
• Returns: <Map> map with arrays of iterator values grouped by keys returned by classifier

Consumes an iterator grouping values by keys

Iterator.prototype.includes(element)

Iterator.prototype.join(sep = ', ', prefix = '', suffix = '')

Iterator.prototype.map(mapper, thisArg)

Iterator.prototype.max([accessor[, thisArg]])

• accessor: <Function> gets value to compare by, current iterator value is used by default
  • value: <any> current iterator value
  • Returns: <any> value to compare by
• thisArg: <any> value to be used as this when calling accessor

Returns: element with maximum value or <undefined> if iterator is empty

Find the maximum value in this iterator

Iterator.prototype.min([accessor[, thisArg]])

• accessor: <Function> gets value to compare by, current iterator value is used by default
  • value: <any> current iterator value
  • Returns: <any> value to compare by
• thisArg: <any> value to be used as this when calling accessor

Returns: element with minimum value or <undefined> if iterator is empty

Find the minimum value in this iterator

Iterator.prototype.next()

Iterator.prototype.partition(predicate[, thisArg])

• predicate: <Function> function returns a value to partition this iterator
  • value: <any> current iterator element
  • Returns: <boolean>|<number> key denoting resulting partition this value will be assigned to. Number denotes index in the resulting array. Boolean will be cast to number
• thisArg: <any> value to be used as this when calling predicate
• Returns: <Array> array of partitions (arrays), will always have at least 2 arrays in it

Consumes an iterator, partitioning it into Arrays

Iterator.prototype.reduce(reducer, initialValue)

Iterator.prototype.skip(amount)

Iterator.prototype.skipWhile(predicate, thisArg)

Iterator.prototype.some(predicate, thisArg)

Iterator.prototype.someCount(predicate, count, thisArg)

Iterator.prototype.take(amount)

Iterator.prototype.takeWhile(predicate, thisArg)

Iterator.prototype.toArray()

Iterator.prototype.toObject()

Transforms an iterator of key-value pairs into an object.

This is similar to what {Object.fromEntries()} would offer.

Iterator.prototype.zip(...iterators)

iter(base)

iterEntries(obj)

iterKeys(obj)

iterValues(obj)

class AsyncIterator

AsyncIterator.prototype.constructor(base)

AsyncIterator.prototype.chain(...iterators)

async AsyncIterator.prototype.collectTo(CollectionClass)

async AsyncIterator.prototype.collectWith(obj, collector)

async AsyncIterator.prototype.count()

async AsyncIterator.prototype.each(fn, thisArg)

AsyncIterator.prototype.enumerate()

async AsyncIterator.prototype.every(predicate, thisArg)

AsyncIterator.prototype.filter(predicate, thisArg)

async AsyncIterator.prototype.find(predicate, thisArg)

AsyncIterator.prototype.flat(depth = 1)

AsyncIterator.prototype.flatMap(mapper, thisArg)

async AsyncIterator.prototype.forEach(fn, thisArg)

async AsyncIterator.prototype.includes(element)

async AsyncIterator.prototype.join(sep = ', ', prefix = '', suffix = '')

AsyncIterator.prototype.map(mapper, thisArg)

async AsyncIterator.prototype.next()

async AsyncIterator.prototype.parallel(fn, thisArg)

async AsyncIterator.prototype.reduce(reducer, initialValue)

AsyncIterator.prototype.skip(amount)

async AsyncIterator.prototype.some(predicate, thisArg)

async AsyncIterator.prototype.someCount(predicate, count, thisArg)

AsyncIterator.prototype.take(amount)

AsyncIterator.prototype.takeWhile(predicate, thisArg)

AsyncIterator.prototype.throttle(percent, min)

async AsyncIterator.prototype.toArray()

AsyncIterator.prototype.zip(...iterators)

asyncIter(base)

• base: <Iterable>|<AsyncIterable> an iterable that is wrapped in <AsyncIterator>

Returns: <AsyncIterator>

Create an AsyncIterator instance

Contributors

See github for full contributors list