immutable iterator that supports lazy evaluation and chain methods
npm install lazy-iter.jsfor more infomation about Maybe, Just and Nothing, see error-null-handle
``shell`
npm install lazy-iter.js
* append
* chain
* chunks
* compact
* concat
* count
* cycle
* dedup
* dedupBy
* dedupByKey
* each
* enumerate
* eq
* eqBy
* every
* filter
* filterMap
* flatMap
* flat
* find
* findIndex
* findMap
* first
* groupToMap
* groupToObject
* interleave
* interleaveShortest
* inspect
* intersperse
* isEmpty
* isIter
* isUnique
* isUniqueByKey
* iter
* join
* last
* map
* max
* maxBy
* maxByKey
* merge
* mergeBy
* mergeByKey
* min
* minBy
* minByKey
* ne
* neBy
* nth
* partition
* prepend
* range
* reduce
* repeat
* rev
* scan
* skip
* skipWhile
* slice
* some
* stepBy
* take
* takeWhile
* toArray
* toMap
* toObject
* toSet
* toString
* unique
* uniqueByKey
* withPosition
* zip
* zipWith
* iter :: \
Creates an Iter object from the given value.null
If no value or is given, returns an empty Iter.Iter
If the value is an iterable, returns an that yields each value from the iterable.Iter
If the value is any other type, returns an that yields the value once.
* repeat :: \
Repeat the given value endlessly.
* range :: (config: RangeConfig | number = {}, end?: number, step?: number) => Iter\
Generates a sequence of numbers within a specified range.
* isIter :: \
Test if a variable is an Iter instance.
#### lazy evaluation methods
* append :: (item: T): Iter\
Append a single element to the end of an Iter.
* chain :: (other: Iterable\
Concatenates the current Iter with the given iterable.
* chunks :: (size: number): Iter\
Split an Iter into chunks of the given size.size
Panics if is not a positive integer.
* compact :: Iter\
Remove all null and undefined elements from the Iter, and unwraps Maybe values.
* concat :: (...others: Iterable\
Concatenates the given iterators to this Iter.
* cycle :: () => Iter\
Repeats the Iter endlessly.
* dedup :: () => Iter\
Removes all but the first of consecutive duplicate elements in the Iter.
Duplicates are detected using deep equality.
* dedupBy :: (sameBucket: (a: T, b: T) => boolean) => Iter\
Removes all but the first of consecutive elements in the Iter satisfying a given equality relation.a
Consecutive elements and b are considered duplicates if sameBucket(a, b) returns true.
* dedupByKey :: \
Removes all but the first of consecutive elements in the iterator based on a key derived from each element.
Consecutive elements are considered duplicates if they map to the same key (tests with Object.is).
* enumerate :: () => Iter<[number, T]>
Creates an Iter which gives the current iteration count as well as the value.
* filter :: (fn: (value: T) => boolean) => Iter\
Filters the values in the current Iter using the provided predicate function.
* filterMap :: \(fn: (value: T) => U | undefined | null | Maybe\) => Iter\
Filter and map the values in the current Iter using the provided function.T
The filter function takes a value of type and returns a value of type U | undefined | null | Maybe.null
The resulting iterator will only contain the values where the filter function returns a non-/undefined value.Maybe
If the filter function returns a , the resulting iterator will only contain the values where the filter function returns a Just value.
* flatMap :: \(fn: (value: T) => Iterable\) => Iter\
Maps each value of the current Iter to an Iter using the given function and flattens the result.
* flat :: \
Flattens an iterable to a specified depth.
Panics if the depth is not a positive integer.
* inspect :: (fn: (value: T) => void) => Iter\
Does something with each element of an Iter, passing the value on.
When using iterators, you’ll often chain several of them together.
While working on such code, you might want to check out what’s happening at various parts in the pipeline.
To do that, insert a call to inspect().
It’s more common for inspect() to be used as a debugging tool than to exist in your final code,
but applications may find it useful in certain situations when errors need to be logged before being discarded.
* interleave :: (other: Iterable\
Alternate elements from two iterators until both have run out.
* interleaveShortest :: (other: Iterable\
Alternate elements from two iterators until at least one of them has run out.
* intersperse :: (value: T) => Iter\
Returns a new Iter that intersperses the given value between each of the elements of the current Iter.Iter
The new will yield the first element of the current Iter, then the given value,Iter
then the second element of the current , then the given value again, and so on.
The given value can be a function that returns a value,
in which case the value returned by the function will be used as the interspersed value.
* map :: \(fn: (value: T) => U) => Iter\
Creates a new Iter by applying the given function to each value in the current Iter.
* merge :: (other: Iterable\
Merge the current Iter with the given iterable.Iter
The merged iterator will yield elements in ascending order.
If two elements are equal, the first element from the current will come first.
If both base iterators are sorted (ascending), the result is sorted.
* mergeBy :: (other: Iterable\
Merges the current Iter with the given iterable using the provided isFirst function.isFirst
The function takes two values, first from the current Iter and second from the given iterable,
and returns true if the first value should be yielded before the second value.
* mergeByKey :: \
Merges the current Iter with the given iterable using the given function to extract a key from each element.
The elements are merged in ascending order of their keys.
* partition :: (fn: (value: T) => boolean) => [Iter\
Splits the current Iter into two separate Iter instances based on the provided predicate function.Iter
The first contains all elements for which the predicate function returns true,Iter
and the second contains all elements for which the predicate function returns false.
* prepend :: (item: T): Iter\
Prepends a single element to the beginning of the Iter.
* scan :: \(fn: (acc: U, value: T) => U | null | undefined | Maybe\, initial: U) => Iter\
Similar to reduce, but yields all intermediate results.
The function given to this method takes an accumulator and a value from the current Iter,Maybe
and returns the next accumulator value.
If the function returns null or undefined, the iteration stops.
If the function returns a that is a Nothing, the iteration also stops.
* skip :: (n: number) => Iter\
Skips the first n elements of the Iter and returns a new Iter starting from the (n+1)th element.n
Panics if is not a natural integer.
* skipWhile :: (shouldSkip: (value: T) => boolean) => Iter\
Skips elements in the Iter until the given function returns false.
After the first false result, the rest of the elements are yielded.
* slice :: (start: number, end: number): Iter\
Returns a new Iter that yields the elements of the current Iter in the given range.
Panics if the start index is greater than the end index.
Panics if the start or end index is not a natural integer.
* stepBy :: (step: number): Iter\
Creates an Iter starting at the start point, but stepping by the given amount at each iteration.
Note the first element of the iterator will always be returned, regardless of the step given.
Panics if the step amount is not a positive integer.
* take :: (n: number) => Iter\
Takes the first n values from the current Iter.Iter
If the current is shorter than n, the resulting Iter will be shorter than n.n
Panics if is not a natural integer.
* takeWhile :: (shouldTake: (value: T) => boolean) => Iter\
Takes elements from the Iter as long as the given function returns true.
Once the function returns false, the iteration stops.
* unique :: (): Iter\
Return an Iter that filters out elements that have already been produced once during the iteration.Iter
Duplicates are detected by comparing the elements by value and reference.
The values are stored in a set in the iterator.
The is stable, returning the non-duplicate items in the order in which they occur in the adapted Iter.
In a set of duplicate items, the first item encountered is the item retained.
* uniqueByKey :: \
Return an Iter that filters out elements that have already been produced once during the iteration.fn
Duplicates are detected by comparing the key they map to with the keying function by hash and equality.Iter
The keys are stored in a hash set in the iterator.
The is stable, returning the non-duplicate items in the order in which they occur in the adapted Iter.
In a set of duplicate items, the first item encountered is the item retained.
* withPosition :: : Iter<[Position, T]>
Returns an Iter that yields tuples containing the position of each element in the original Iter and the element itself.Position
The position is represented by the enum, which includes First, Middle, Last, and Only.Iter
- If the has only one element, it is marked as Only.First
- The first element is marked as .Last
- The last element is marked as .Middle
- All other elements are marked as .
* zip :: \(other: Iterable\) => Iter<[T, U]>
Zip this Iter with another iterator.Iter
This method takes another iterator and returns a new that yields tuples of elements from both iterators.Iter
The new will stop when either iterator stops.
* zipWith :: \
Creates a new Iter that pairs each element of the current Iter with the corresponding element of another Iter,Iter
and applies a function to each pair, yielding the results.
The new will stop when either iterator stops.
#### eager evaluation methods
* count :: () => number
Returns the number of items in the Iter.
* each :: (fn: (value: T) => void) => void
Executes the given function once for each element in the Iter.
* eq :: (other: Iter\
Tests if the current Iter is equal to the given Iter.Iter
Two s are considered equal if they contain the same elements(tests with deep equality) in the same order.
* eqBy :: (other: Iter\
Tests if the current Iter is equal to the given Iter according to the given equality function.Iter
Two s are considered equal if they contain the same elements in the same order.T
The equality function takes two values of type and returns a boolean that indicates the two values are equalare equal.
* every :: (fn: (value: T) => boolean) => boolean
Checks if every element of the Iter satisfies the given predicate.
* find :: (fn: (value: T) => boolean) => Maybe\
Returns the first value wrapped in Just in the Iter for which the given predicate function returns true.Nothing
If no element satisfies the predicate, returns .
* findIndex :: (fn: (value: T) => boolean) => Maybe\
Returns the index of the first element wrapped in Just in the Iter that satisfies the given predicate function.Nothing
If no element satisfies the predicate, returns .
* findMap :: \(fn: (value: T) => U | undefined | null | Maybe\): Maybe\
Applies function to the elements of Iter and returns the first valid result.iter.findMap(fn)
is equivalent to iter.filterMap(fn).first().
* first :: : Maybe\
Returns the first value wrapped in Just in the Iter.Iter
If the is empty, returns Nothing.
* groupToMap :: \
Reduces the Iter to a Map where the keys are values returned by the given function,Iter
and the values are s of the elements that were grouped by the given function.
* groupToObject :: \
Reduces the Iter to a Object where the keys are values returned by the given function,Iter
and the values are s of the elements that were grouped by the given function.
* isEmpty :: (): boolean
Tests if the current Iter contains no elements.
* isUnique :: (): boolean
Tests if the current Iter contains non duplicate elements.
Duplicates are detected by by hash and equality.
* isUniqueByKey :: \
Tests if the current Iter contains non duplicate elements according to the given keying function.fn
Duplicates are detected by comparing the key they map to with the keying function by hash and equality.Set
The keys are stored in a in the iterator.
* join :: (sep: string): string
Join all elements of the Iter into a single string, separated by the given separator.
* last :: () => Maybe\
Returns the last value in the Iter, wrapped in Just.Iter
If the is empty, returns Nothing.
* max :: () => Maybe\
Returns the maximum value in the Iter.Iter
If several elements are equally maximum, the last element is returned.
If the is empty, returns Nothing.
* maxBy :: (fn: (a: T, b: T) => Ordering): Maybe\
Returns the element that gives the maximum value with respect to the specified comparison function.
If several elements are equally maximum, the last element is returned.
If the Iter is empty, returns Nothing.
* maxBykey :: (fn: (value: T) => Comparable) => Maybe\
Returns the element that gives the maximum value from the specified function.
If several elements are equally maximum, the last element is returned.
If the Iter is empty, returns Nothing.
* min :: () => Maybe\
Returns the minimum value in the Iter.Iter
If several elements are equally minimum, the first element is returned.
If the is empty, returns Nothing.
* minBy :: (fn: (a: T, b: T) => Ordering) => Maybe\
Returns the element that gives the minimum value from the specified function.
If several elements are equally minimum, the first element is returned.
If the Iter is empty, returns Nothing.
* minByKey :: (fn: (value: T) => Comparable) => Maybe\
Returns the element that gives the minimum value from the specified function.
If several elements are equally minimum, the first element is returned.
If the Iter is empty, returns Nothing.
* ne :: (item: T): Iter\
Checks if the current Iter is not equal to the given Iter.Iter
Two s are considered not equal if they contain different elements (tests with deep equality) in the same order,
or if they have different lengths.
* neBy :: (other: Iter\
Tests if the current Iter is not equal to the given Iter using the given comparison function.Iter
Two s are considered not equal if they contain the different elements in the same order,T
or if they have different lengths.
The comparison function takes two values of type and
returns a boolean that indicates the two values are not equal.
* nth :: (n: number) => Maybe\
Returns the nth element of the Iter, if it exists.
* some :: (fn: (value: T) => boolean) => boolean
Checks if any element of the Iter satisfies the given predicate function.
* reduce :: \(fn: (acc: U, value: T) => U, initial: U) => U
Reduces the Iter to a single value using the provided reducer function and an initial accumulator value.
* toArray :: () => T[]
Returns an array containing all elements of the Iter.
* toMap :: \
Converts an Iter to a Map.toEntry
The provided function takes a value of type T and returns a tuple of type [K, V].Map
The resulting will have the resulting keys of type K and the resulting values of type V.
* toObject :: \
Returns a new object, mapping each element of the Iter to its corresponding entry in the object.toEntry
The provided function takes a value of type T and returns a tuple of type [K, V].Object
The resulting will have the resulting keys of type K and the resulting values of type V.
* toSet :: () => Set\
Converts the Iter to a Set.Set
Note that the order of the elements in the resulting is not guaranteedIter
to be the same as the order of elements in the original ,Iter
because the might contain duplicates.
* toString :: () => string
Returns a string representation of the Iter.
#### eager evaluate values and return lazy Iter
* rev :: () => Iter\
Reverses an Iter's direction.Iter
Usually, s iterate from left to right.Iter
After using rev(), an will instead iterate from right to left.Iter
This is only possible if the has an end.
* Position
`ts`
const enum Position {
First = 'first',
Middle = 'middle',
Last = 'last',
Only = 'only',
}
Exported as object P and Position. import { P } from 'lazy-iter.js'
import { Position } from 'lazy-iter.js'
- P.First: This is the first element.P.Middle
- : This is neither the first nor the last element.P.Last
- : This is the last element.P.Only
- : This is the only element.
* Ordering
`ts`
const enum Ordering {
Less = -1,
Equal = 0,
Greater = 1,
}
Exported as object O and Ordering. import { O } from 'lazy-iter.js'
import { Ordering } from 'lazy-iter.js'
- O.Less: The first element is less than the secendO.Equal
- : The two elements are equal.O.Greater`: The first element is greater than the second.
-