immutable iterator that supports lazy evaluation and chain methods

for more infomation about Maybe, Just and Nothing, see error-null-handle

$3

``shell
npm install lazy-iter.js
`

API reference

* 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

$3

* iter :: \(iterable: Iterable\) => Iter\

Creates an Iter object from the given value.

If no value or null is given, returns an empty Iter.

If the value is an iterable, returns an Iter that yields each value from the iterable.

If the value is any other type, returns an Iter that yields the value once.

* repeat :: \(value: T | (() => T)) => Iter\

Repeat the given value endlessly.

* range :: (config: RangeConfig | number = {}, end?: number, step?: number) => Iter\

Generates a sequence of numbers within a specified range.

$3

* isIter :: \(value: unknown) => value is Iter\

Test if a variable is an Iter instance.

$3

#### lazy evaluation methods

* append :: (item: T): Iter\

Append a single element to the end of an Iter.

* chain :: (other: Iterable\) => Iter\

Concatenates the current Iter with the given iterable.

* chunks :: (size: number): Iter\>

Split an Iter into chunks of the given size.

Panics if size is not a positive integer.

* compact :: Iter\>

Remove all null and undefined elements from the Iter, and unwraps Maybe values.

* concat :: (...others: Iterable\[]) => Iter\

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.

Consecutive elements a and b are considered duplicates if sameBucket(a, b) returns true.

* dedupByKey :: \(getKey: (value: T) => K) => Iter\

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.

The filter function takes a value of type T and returns a value of type U | undefined | null | Maybe.

The resulting iterator will only contain the values where the filter function returns a non-null/undefined value.

If the filter function returns a Maybe, 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 :: \(depth?: D): FlattedIter\

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\): Iter\

Alternate elements from two iterators until both have run out.

* interleaveShortest :: (other: Iterable\): Iter\

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.

The new Iter will yield the first element of the current Iter, then the given value,

then the second element of the current Iter, 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\): Iter\

Merge the current Iter with the given iterable.

The merged iterator will yield elements in ascending order.

If two elements are equal, the first element from the current Iter will come first.

If both base iterators are sorted (ascending), the result is sorted.


* mergeBy :: (other: Iterable\, isFirst: (a: T, b: T) => boolean): Iter\

Merges the current Iter with the given iterable using the provided isFirst function.

The isFirst 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 :: \(other: Iterable\, getKey: (value: T) => K): Iter\

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\, Iter\]

Splits the current Iter into two separate Iter instances based on the provided predicate function.

The first Iter contains all elements for which the predicate function returns true,

and the second Iter 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,

and returns the next accumulator value.

If the function returns null or undefined, the iteration stops.

If the function returns a Maybe 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.

Panics if n 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.

If the current Iter is shorter than n, the resulting Iter will be shorter than n.

Panics if n 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.

Duplicates are detected by comparing the elements by value and reference.

The values are stored in a set in the iterator.

The Iter 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 :: \(fn: (value: T) => V): Iter\

Return an Iter that filters out elements that have already been produced once during the iteration.

Duplicates are detected by comparing the key they map to with the keying function fn by hash and equality.

The keys are stored in a hash set in the iterator.

The Iter 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.

The position is represented by the Position enum, which includes First, Middle, Last, and Only.

- If the Iter has only one element, it is marked as Only.
- The first element is marked as First.
- The last element is marked as Last.
- All other elements are marked as Middle.

* zip :: \(other: Iterable\) => Iter<[T, U]>

Zip this Iter with another iterator.

This method takes another iterator and returns a new Iter that yields tuples of elements from both iterators.

The new Iter will stop when either iterator stops.

* zipWith :: \(other: Iter\, fn: (a: T, b: U) => V): Iter\

Creates a new Iter that pairs each element of the current Iter with the corresponding element of another Iter,

and applies a function to each pair, yielding the results.

The new Iter 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\) => boolean

Tests if the current Iter is equal to the given Iter.

Two Iters are considered equal if they contain the same elements(tests with deep equality) in the same order.

* eqBy :: (other: Iter\, fn: (a: T, b: T) => boolean) => boolean

Tests if the current Iter is equal to the given Iter according to the given equality function.

Two Iters are considered equal if they contain the same elements in the same order.

The equality function takes two values of type T 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.

If no element satisfies the predicate, returns Nothing.

* 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.

If no element satisfies the predicate, returns Nothing.

* 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.

If the Iter is empty, returns Nothing.

* groupToMap :: \(keySelector: (value: T) => K): Map\>

Reduces the Iter to a Map where the keys are values returned by the given function,

and the values are Iters of the elements that were grouped by the given function.

* groupToObject :: \(keySelector: (value: T) => K): Record\>

Reduces the Iter to a Object where the keys are values returned by the given function,

and the values are Iters 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 :: \(fn: (value: T) => K): boolean

Tests if the current Iter contains non duplicate elements according to the given keying function.

Duplicates are detected by comparing the key they map to with the keying function fn by hash and equality.

The keys are stored in a Set 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.

If the Iter is empty, returns Nothing.

* max :: () => Maybe\

Returns the maximum value in the Iter.

If several elements are equally maximum, the last element is returned.

If the Iter 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.

If several elements are equally minimum, the first element is returned.

If the Iter 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.

Two Iters 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\, fn: (a: T, b: T) => boolean): boolean

Tests if the current Iter is not equal to the given Iter using the given comparison function.

Two Iters are considered not equal if they contain the different elements in the same order,

or if they have different lengths.

The comparison function takes two values of type T 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 :: \(toEntry: (value: T) => [K, V]): Map\

Converts an Iter to a Map.

The provided function toEntry takes a value of type T and returns a tuple of type [K, V].

The resulting Map will have the resulting keys of type K and the resulting values of type V.


* toObject :: \(toEntry: (value: T) => [K, V]): Record\

Returns a new object, mapping each element of the Iter to its corresponding entry in the object.

The provided function toEntry takes a value of type T and returns a tuple of type [K, V].

The resulting Object will have the resulting keys of type K and the resulting values of type V.


* toSet :: () => Set\

Converts the Iter to a Set.

Note that the order of the elements in the resulting Set is not guaranteed
to be the same as the order of elements in the original Iter,

because the Iter 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.

Usually, Iters iterate from left to right.

After using rev(), an Iter will instead iterate from right to left.

This is only possible if the Iter has an end.

$3

* 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 secend
- O.Equal: The two elements are equal.
- O.Greater`: The first element is greater than the second.