extra-iterator
    Preparing search index...

    Class ExtraIterator<T>

    An extended iterator class that provides additional chainable utility methods for working with iterables.

    // Creating an iterator from an array
    const iter = ExtraIterator.from([1, 2, 3, 4, 5]);

    // Using static factory methods
    ExtraIterator.range(1, 5)
      .map(n => n * n)
      .toArray()
      // returns [1, 4, 9, 16]

    Type Parameters

    • T

      The type of values yielded by this iterator.

    Hierarchy

    • Iterator<T, any, any>
      • ExtraIterator
    Index

    Properties

    [toStringTag]

    Methods

    [dispose] [iterator] every find forEach reduce return? some throw? toArray

    Aggregation methods

    at collect count first groupBy last sum testUnique toMap toSet

    Iterator protocol methods

    next

    Miscellaneous methods

    withEach

    Static constructors

    concat count empty from random randomBytes range repeat single zip

    Transformation methods

    append chunk chunkBy chunkWith compact concat defaultIfEmpty defaultIfEmptyWith drop dropWhile filter flat flatMap interleave interpose interposeWith loop map prepend prependAll splice take takeWhile unique zip

    Properties

    "[toStringTag]": string

    Methods

    • Returns void

    • Returns void

    • Returns IteratorObject<T, any, any>

    • Returns this iterator.

      Returns IteratorObject<T, any, any>

    • Determines whether all the members of this iterator satisfy the specified test.

      Parameters

      • predicate: (value: T, index: number) => unknown

        A function that accepts up to two arguments. The every method calls the predicate function for each element in this iterator until the predicate returns false, or until the end of this iterator.

      Returns boolean

    • Returns the value of the first element in this iterator where predicate is true, and undefined otherwise.

      Type Parameters

      • S

      Parameters

      • predicate: (value: T, index: number) => value is S

        find calls predicate once for each element of this iterator, in order, until it finds one where predicate returns true. If such an element is found, find immediately returns that element value. Otherwise, find returns undefined.

      Returns S | undefined

    • Parameters

      • predicate: (value: T, index: number) => unknown

      Returns T | undefined

    • Performs the specified action for each element in the iterator.

      Parameters

      • callbackfn: (value: T, index: number) => void

        A function that accepts up to two arguments. forEach calls the callbackfn function one time for each element in the iterator.

      Returns void

    • Calls the specified callback function for all the elements in this iterator. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function.

      Parameters

      • callbackfn: (previousValue: T, currentValue: T, currentIndex: number) => T

        A function that accepts up to three arguments. The reduce method calls the callbackfn function one time for each element in the iterator.

      Returns T

    • Parameters

      • callbackfn: (previousValue: T, currentValue: T, currentIndex: number) => T
      • initialValue: T

      Returns T

    • Calls the specified callback function for all the elements in this iterator. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function.

      Type Parameters

      • U

      Parameters

      • callbackfn: (previousValue: U, currentValue: T, currentIndex: number) => U

        A function that accepts up to three arguments. The reduce method calls the callbackfn function one time for each element in the iterator.

      • initialValue: U

        If initialValue is specified, it is used as the initial value to start the accumulation. The first call to the callbackfn function provides this value as an argument instead of a value from the iterator.

      Returns U

    • Parameters

      • Optionalvalue: any

      Returns IteratorResult<T, any>

    • Determines whether the specified callback function returns true for any element of this iterator.

      Parameters

      • predicate: (value: T, index: number) => unknown

        A function that accepts up to two arguments. The some method calls the predicate function for each element in this iterator until the predicate returns a value true, or until the end of the iterator.

      Returns boolean

    • Parameters

      • Optionale: any

      Returns IteratorResult<T, any>

    • Creates a new array from the values yielded by this iterator.

      Returns T[]

    Aggregation methods

    • Consumes the iterator and returns the value at the provided index, or undefined if the index is out of bounds.

      Parameters

      • index: number

        The index of the value to return. If negative, it counts from the end of the iterator, starting with -1 for the last element, -2 for the second to last, and so on.

      Returns T | undefined

      The value at the provided index, or undefined if the index is out of bounds (i.e., if there are not enough elements in the iterator).

      ExtraIterator.from([1, 2, 3, 4]).at(2) // returns 3
      ExtraIterator.from([1, 2, 3, 4]).at(-1) // returns 4
      ExtraIterator.from([1, 2, 3, 4]).at(10) // returns undefined

    • Consumes the iterator and returns a value determined by calling the provided function using the iterator as argument.

      Type Parameters

      • U

        The type of the value returned by the provided function.

      Parameters

      • callback: (iter: Iterable<T>) => U

        A function that takes this iterator as argument and returns a value.

      Returns U

      The value returned by calling the provided callback function with this iterator as argument.

      This is an utility method that can be used perform some operation on the iterator during a method call chain.

      ExtraIterator.from(Object.entries({ a: 1, b: 2 }))
          .map(([key, value]) => ['_' + key, value * 2])
          .collect(Object.fromEntries)
          // returns { _a: 2, _b: 4 }

    • Consumes the iterator and returns the number of elements it contained.

      Returns number

      The number of elements in the iterator.

      ExtraIterator.from([1, 2, 3, 4]).count() // returns 4

    • Returns the first element of the iterator, or undefined if the iterator is empty.

      Returns T | undefined

      The first element of the iterator, or undefined if the iterator is empty.

      ExtraIterator.from([1, 2, 3]).first() // returns 1
      ExtraIterator.from([]).first() // returns undefined

    • Groups the elements in this iterator into separate arrays and returns an object containing all the groups.

      The returned object is composed of keys generated by calling the provided callback function on each element of this iterator, and the value for each key is an array containing all the elements that were assigned to that key.

      This method is similar to toMap, but the returned object is a plain, null-prototype, object, instead of a Map.

      Type Parameters

      • K extends string | number | symbol

        The union type that contains all the key values of returned group object.

      Parameters

      • callbackfn: (value: T, index: number) => K

        A function that takes a value from this iterator and returns a key.

      Returns Partial<Record<K, T[]>>

      An object that contains all the groups of elements from this iterator, based on the keys returned by the callback function.

      ExtraIterator.from([1, 2, 3, 4, 5])
       .groupBy(value => value % 2 === 0 ? 'even' : 'odd')
       .toArray()
       // returns { even: [2, 4], odd: [1, 3, 5] }

    • Consumes the iteratror and returns the last yielded value; or undefined if the iterator is empty.

      Returns T | undefined

      The last element of the iterator, or undefined if the iterator is empty.

      ExtraIterator.from([1, 2, 3]).last() // returns 3
      ExtraIterator.from([]).last() // returns undefined

    • Sums the numeric value of all elements in the iterator and returns the total.

      Returns number

      The sum of the numeric value of all elements in the iterator.

      ExtraIterator.from([5, 8, 13]).sum() // returns 26

    • Consumes the iterator and returns a boolean indicating whether all elements in the iterator were unique.

      Returns boolean

      true if the iterator contains no pair of elements that are equal, including when the iterator is empty; or false if there was at least one pair of equal elements.

      If it returns false, then the iterator had at least one duplicated element.

      If the iterator is empty, this method returns true.

      ExtraIterator.from([1, 2, 3]).testUnique() // returns true
      ExtraIterator.from([1, 2, 3, 1]).testUnique() // returns false
      ExtraIterator.from([]).testUnique() // returns true

    • Groups elements into separate arrays and returns a Map containing each group.

      The returned Map is composed of keys generated by calling the provided callback function on each element of this iterator, and the value for each key is an array containing all the elements to which the callback function returned that key.

      This method is similar to groupBy, but the returned object is a Map instead of a plain object.

      Type Parameters

      • K extends string | number | symbol

        The union type that contains all the key values of returned Map.

      Parameters

      • callbackfn: (value: T, index: number) => K

        A function that takes a value from this iterator and returns a key.

      Returns Map<K, T[]>

      A Map that contains all the groups of elements from this iterator, based on the keys returned by the callback function.

      ExtraIterator.from([1, 2, 3, 4, 5])
          .toMap(value => value % 2 === 0 ? 'even' : 'odd')
          .toArray()
          // returns Map { 'even' => [2, 4], 'odd' => [1, 3, 5] }

    • Creates a set containing all the values yielded by this iterator.

      Returns Set<T>

      A set containing all the values yielded by this iterator.

    Iterator protocol methods

    • Parameters

      • Optionalvalue: any

      Returns IteratorResult<T, any>

    Miscellaneous methods

    • Lazily executes a function over each element of this iterator as the values are iterated.

      Parameters

      • callbackfn: (value: T, index: number) => void

        A function that takes a value from this iterator and its index, and performs some side effect.

      Returns ExtraIterator<T>

      An iterator that yields the same values as this iterator, but executes the provided callback function for each yielded element.

      Unlike forEach, this method does not execute the provided callback function immediately. Instead, it returns a new iterator that executes the callback function lazily as the values are iterated.

      The returned iterator yields the same values as this iterator, without any modification.

      const iterator = ExtraIterator.from(['Alice', 'Bob', 'Charlie']).withEach(name => console.log(name));

      // Nothing is printed yet

      const names = iterator.toArray(); // Prints the names to the console, then return ['Alice', 'Bob', 'Charlie']

    Static constructors

    • Creates a new iterator by concatenating multiple iterables or array-like objects.

      Type Parameters

      • T

        The type of values yielded by the provided iterables.

      Parameters

      Returns ExtraIterator<T>

      An iterator that is the concatenation of the provided iterables, yielding the values from each of them in sequence.

      The resulting iterator iterates over each argument iterable in the order they are provided. For each one, it yields all of its values before moving on to the next iterable.

      If any of the provided iterables is infinite, the resulting iterator will also be infinite and will never yield values from the subsequent iterables.

      ExtraIterator.concat([1, 2], [3, 4], [5, 6]).toArray() // returns [1, 2, 3, 4, 5, 6]

    • Creates an iterator that yields incrementing numbers.

      Parameters

      • options: { increment?: number; start?: number } = {}

        An optional object to configure the behavior of the returned iterator.

        • Optionalincrement?: number

          The difference between each pair of consecutive numbers yielded by the returned iterator. If you set a negative increment, the iterator will count downwards. Default is 1.

        • Optionalstart?: number

          The first number yielded by the iterator. Default is 0.

      Returns ExtraIterator<number>

      An iterator that yields incrementing numbers starting from start and incrementing by increment.

      ⚠ This iterator is infinite. Use take method if you want a specific number of values.

      ExtraIterator.count().take(5).toArray() // returns [0, 1, 2, 3, 4]
      ExtraIterator.count({ start: 10, increment: -1 }).take(5).toArray() // returns [10, 9, 8, 7, 6]

    • Creates an iterator that yields no value.

      Type Parameters

      • T = any

        The type parameter of the returned iterator. If omitted, the returned iterator will be of any type.

      Returns ExtraIterator<T>

      An iterator that yields no value.

      ExtraIterator.empty().toArray() // returns []

    • Creates a new ExtraIterator from an iterable, iterator, or array-like object.

      Type Parameters

      • T

        The type of the elements of the source parameter.

      Parameters

      • source: ExtraIteratorSource<T>

        The source to create the iterator from. This can be any object that is either an Iterator, an Iterable, or an array-like object (i.e., has a length property and numerically indexed elements).

      Returns ExtraIterator<T>

      A new ExtraIterator instance.

      // Creating an iterator from an array
      ExtraIterator.from([1, 2, 3]).toArray() // returns [1, 2, 3]

    • Generates an infinite sequence of random numbers between 0 and 1 (inclusive–exclusive) using Math.random or another specified random number generator.

      Parameters

      • rng: () => number = Math.random

        An optional random number generator function that returns a number between 0 and 1 (inclusive–exclusive). If not provided, Math.random will be used as the default random number generator.

          • (): number

          • Returns a pseudorandom number between 0 and 1.

            Returns number

      Returns ExtraIterator<number>

      An iterator that generates an infinite sequence of random numbers between 0 and 1.

      ⚠ This iterator is infinite. Use take method if you want a specific number of values.

      // Produces an array of 5 random numbers, e.g. `[0.123, 0.456, 0.789, 0.012, 0.345]`
      const randomNumbers = ExtraIterator.random().take(5).toArray()

    • Generates an infinite sequence of cryptographically strong random bytes using crypto.getRandomValues, in chunks of bufferSize bytes.

      Parameters

      • options: { bufferSize?: number; sharedBuffer?: boolean } = {}

        An optional object to configure the behavior of the returned iterator.

        • OptionalbufferSize?: number

          The number of random bytes to generate in each chunk. Default is 1024.

        • OptionalsharedBuffer?: boolean

          If false (which is the default), each yielded Uint8Array instance owns its own buffer containing the random bytes. This is safer since you won't accidentally modify the values of a previously yielded chunk by modifying a later one, but the iterator has to allocate a new buffer for each chunk. If this option is set to true, the resulting iterator will yield new Uint8Array views of the same underlying buffer, refilling the buffer with new random bytes between each iteration. This is more performant, but you should be careful to not keep references to the old views since the values will change.

      Returns ExtraIterator<Uint8Array<ArrayBufferLike>>

      An iterator that generates an infinite sequence of cryptographically strong random bytes in chunks of bufferSize bytes.

      If you want a flat sequence of individual byte values instead of chunks, you can chain the returned iterator with the flat method. The resulting iterator will contain interger values from 0 to 255 (inclusive).

      ⚠ This iterator is infinite. Use take method if you want a specific number of values.

      // Produces an array with 3 chunks of random bytes, each containing 16 bytes, e.g. // // [ // Uint8Array(16) [ 0x12, 0x34, ..., 0x56 ], // Uint8Array(16) [ 0x78, 0x9a, ..., 0xbc ], // Uint8Array(16) [ 0xde, 0xf0, ..., 0x12 ], // ] // const chunks = ExtraIterator.randomBytes({ bufferSize: 16 }) .take(3) .toArray();

      // Produces an array of 128 random byte values (integers from 0 to 255)
      const bytes = ExtraIterator.randomBytes().flatten().take(128).toArray();

    • Creates an iterator that yields numbers in a "from-to" range. (exclusive)

      Parameters

      • start: number

        The number at which the returned iterator starts yielding values.

      • end: number

        The number at which the returned iterator stops yielding values. This value is not included in the range unless inclusive is set to true.

      • options: { inclusive?: boolean; step?: number } = {}

        An optional object to configure the behavior of the returned iterator.

        • Optionalinclusive?: boolean

          A boolean that indicates whether the end value should be included in the range. Default is false.

        • Optionalstep?: number

          The increment (or decrement) between each yielded number. Default is 1.

      Returns ExtraIterator<number>

      An iterator that yields numbers starting from start and incrementing (or decrementing) by step, up to end.

      The returned iterator yields all numbers in the specified range. By default, the end value is not included in the range. If you want to include the end value as well, you can set the inclusive option to true.

      The third argument is an optional "step" that defines the increment (or decrement) between each yielded number.

      Note that setting inclusive option to true does not guarantee that the end value will be yielded, since it also depends on the step value. For example, if start is 0, end is 5, and step is 2, the returned iterator will not yield 5 regardless of the inclusive option, because it is not included in the range.

      ExtraIterator.range(5, 10).toArray() // returns [5, 6, 7, 8, 9]
      ExtraIterator.range(5, 10, { inclusive: true }).toArray() // returns [5, 6, 7, 8, 9, 10]

      // Counting down:
      ExtraIterator.range(10, 0).toArray() // return [10, 9, 8, 7, 6, 5, 4, 3, 2, 1]
      ExtraIterator.range(10, 0, { inclusive: true }).toArray() // return [10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0]

      // Custom stepping value:
      ExtraIterator.range(1, 10, { step: 2 }).toArray() // returns [1, 3, 5, 7, 9]
      ExtraIterator.range(0, 1, { step: 0.25 }).toArray() // returns [0, 0.25, 0.5, 0.75]
      ExtraIterator.range(10, 0, { step: 2 }).toArray() // returns [10, 8, 6, 4, 2]

    • Creates an iterator that repeatedly yields the provided value.

      Type Parameters

      • T

        The type of the value yielded by the returned iterator.

      Parameters

      • value: T

        The value to be repeatedly yielded by the returned iterator.

      Returns ExtraIterator<T>

      An iterator that repeatedly yields the provided value.

      ⚠ This iterator is infinite. Use take method if you want a specific number of values.

      ExtraIterator.repeat(3, 'a').toArray() // returns ['a', 'a', 'a']

    • Creates an iterator that yields a single value.

      Type Parameters

      • T

        The type of the value yielded by the returned iterator.

      Parameters

      • value: T

        The value the returned iterator will yield.

      Returns ExtraIterator<T>

      An iterator that yields the provided value once, then ends.

      ExtraIterator.single(42).toArray() // returns [42]

    Transformation methods

    • Appends a new value to the end of the iterator.

      Type Parameters

      • U

      Parameters

      • item: U

        The value to append to the end of the iterator.

      Returns ExtraIterator<T | U>

      A new iterator that yields the values of this iterator, followed by the provided value.

      ExtraIterator.from([1, 2, 3])
          .append(4)
          .toArray()
          // returns [1, 2, 3, 4]

    • Groups the elements in this iterator into arrays of fixed size.

      Parameters

      • size: number

        The size of the chunks. Must be a positive integer.

      Returns ExtraIterator<T[]>

      A new iterator that yields arrays of elements from this iterator, grouped by chunks of the specified size.

      This method produces a new iterator that contains all elements of this iterator, grouped by chunks of fixed size.

      The returned iterator yields arrays, each one containing a subset of the elements of this iterator.

      Each array has the length specified by the size parameter, except possibly the last one, which may contain fewer elements if the total number of elements in this iterator is not divisible by size.

      If the provided size parameter is not a positive integer.

      ExtraIterator.from([1, 2, 3, 4, 5, 6, 7])
          .chunk(3)
          .toArray()
          // returns [[1, 2, 3], [4, 5, 6], [7]]

    • Groups the elements in this iterator into arrays based on a key provided by a callback function.

      Parameters

      • callback: (value: T, index: number) => unknown

        A function that takes a value from this iterator and returns a key. Adjacent values for which this function returns the same key will be grouped together in the output.

      Returns ExtraIterator<T[]>

      A new iterator that yields arrays of elements from this iterator, grouped based on the keys returned by the callback function.

      The provided callback function will be called for each element in this iterator. It should return a key value. Adjacent elements for which the callback function returns the same key will be grouped together.

      The returned iterator yields arrays, each one containing a subset of the elements of this iterator that share the same key according to the provided callback function.

      The order of the elements is preserved, and the grouping is stable. This means that if two adjacent elements have the same key, they will appear in the same order in the output as they do in the input.

      ExtraIterator.from(['Alice', 'Antony', 'Charlie', 'Bob', 'Ashley'])
          .chunkBy(name => name.startsWith('A'))
          .toArray()
          // returns [['Alice', 'Antony'], ['Charlie', 'Bob'], ['Ashley']]

    • Groups the elements in this iterator into groups of variable size.

      Parameters

      • predicate: (lhs: T, rhs: T, index: number, chunk: [T, ...T[]]) => boolean

        A function that takes two adjacent elements of this iterator, and returns a boolean indicating whether the two elements should belong to the same group (if true) or not (if false).

      Returns ExtraIterator<T[]>

      An iterator that yields the elements from this iterator, grouped into arrays based on the provided predicate.

      This method calls the provided predicate function for each pair of adjacent elements in this iterator. The predicate should return true if the elements should belong to the same group, or false otherwise.

      ExtraIterator.from([1, 1, 2, 3, 3, 3, 2, 2])
          .chunkWith((lhs, rhs) => lhs === rhs)
          .toArray()
          // returns [[1, 1], [2], [3, 3, 3], [2, 2]]

    • Creates a new iterator that yields the values of this iterator, but won't yield any null or undefined values.

      Returns ExtraIterator<Exclude<T, null | undefined>>

      A new iterator that yields the non-null and non-undefined values of this iterator.

      ExtraIterator.from([0, 1, null, 3, undefined, 5])
         .compact()
         .toArray()
         // returns [0, 1, 3, 5]

    • Concatenates multiple values to the end of this iterator.

      Type Parameters

      • U

      Parameters

      • items: Iterable<U>

        An iterable of values to concatenate to the end of this iterator.

      Returns ExtraIterator<T | U>

      A new iterator that yields the values of this iterator, followed by the values of the provided items iterable.

      The order of the values is preserved.

      ExtraIterator.from([1, 2, 3])
          .concat([4, 5, 6])
          .toArray()
          // returns [1, 2, 3, 4, 5, 6]

    • If this iterator is empty, returns an iterator with the provided element as its only element; otherwise, it returns a copy of this iterator.

      Parameters

      • value: T

        A value to yield if this iterator is empty.

      Returns ExtraIterator<T>

      A new iterator that yields the values of this iterator, or the provided default value if this iterator is empty.

      ExtraIterator.from([]).defaultIfEmpty(42).toArray() // returns [42]
      ExtraIterator.from([1, 2, 3]).defaultIfEmpty(42).toArray() // returns [1, 2, 3]

    • If this iterator is empty, calls the provided callback function and yields the returned value as the iterator's only element; otherwise, returns a copy of this iterator.

      Parameters

      • provider: () => T

        A function that provides the default value to yield if this iterator is empty.

      Returns ExtraIterator<T>

      A new iterator that yields the values of this iterator, or the provided default value if this iterator is empty.

      ExtraIterator.from([]).defaultIfEmptyWith(Math.random).toArray() // returns an array with a random number
      ExtraIterator.from([1, 2, 3]).defaultIfEmptyWith(Math.random).toArray() // returns [1, 2, 3]

    • Creates a new iterator that skips the first count values of this iterator and yields the remaining values.

      Parameters

      • count: number

        The number of values to skip. If negative, skips values from the end.

      Returns ExtraIterator<T>

      A new iterator that yields the remaining values.

      If count is equal to or greater than the length of this iterator, then the resulting iterator will be empty.

      If count is negative, then this iterator will be consumed and the returned iterator will yield all the values of this iterator except the last -count values.

      ExtraIterator.from([1, 2, 3, 4, 5]).drop(2).toArray() // returns [3, 4, 5]
      ExtraIterator.from([1, 2, 3, 4, 5]).drop(-2).toArray() // returns [1, 2, 3]
      ExtraIterator.from([1, 2, 3, 4, 5]).drop(10).toArray() // returns []

    • Creates a new iterator that invokes the provided predicate function for each element of this iterator and skips the elements for which the function returns true, but only for as long as it returns true.

      Parameters

      • predicate: (value: T, index: number) => boolean

        A function that takes a value and its index, and returns a boolean indicating whether the value should be skipped (if true) or yielded (if false). Iteration stops once this function returns false.

      Returns ExtraIterator<T>

      A new iterator that yields the values of this iterator starting from the first value for which the provided predicate function returns false.

      Iteration stops once the predicate function returns false. The returned iterator will yield the first value for which the predicate returns false, and all the subsequent elements.

      ExtraIterator.from(['Alice', 'Antony', 'Charlie', 'Ashley'])
         .dropWhile(name => name[0] === 'A')
         .toArray()
         // returns ['Charlie', 'Ashley']

    • Type Parameters

      • S

      Parameters

      • predicate: (value: T, index: number) => value is S

      Returns ExtraIterator<S>

    • Creates an iterator whose values are those from this iterator for which the provided predicate returns true.

      Parameters

      • predicate: (value: T, index: number) => unknown

        A function that accepts up to two arguments to be used to test values from the underlying iterator.

      Returns ExtraIterator<T>

    • Flattens the iterator by one level. If the iterator yields iterables, it will yield their values. If the iterator yields non-iterables, it will yield the values as is.

      Parameters

      • options: { arraylike?: boolean } = {}

        An optional object to configure the behavior of the flattening process.

        • Optionalarraylike?: boolean

          If true, the flattening process will also flatten "array-like" objects (i.e., objects that have a length property and numerically indexed elements) as iterables. By default, only objects that implement the iterable protocol (i.e., have a [Symbol.iterator] method) are flattened.

      Returns FlattenedExtraIterator<T>

      A new iterator that yields the flattened values of this iterator.

      This methods recursivelly flattens the iterator until all yielded values are non-iterable. This means that if the iterator yields nested iterables, all of them will be flattened.

      ExtraIterator.from([[1, 2], [3, 4]]).flatten().toArray() // returns [1, 2, 3, 4]

    • Type Parameters

      • U

      Parameters

      • callback: (
            value: T,
            index: number,
        ) => Iterator<U, unknown, undefined> | Iterable<U, unknown, undefined>

      Returns ExtraIterator<U>

    • Creates a new iterator that yields the values of this iterator and the values of the provided iterator interleaved (alternating).

      Type Parameters

      • U

        The type of the elements of the other iterator.

      Parameters

      Returns ExtraIterator<T | U>

      A new iterator that yields the values of this iterator and the values of the provided other iterator interleaved.

      The resulting iterator yields the first value of this iterator, then the first value of the other iterator, then the second value of this iterator, then the second value of the other iterator, and so on, alternating between the two iterators until both of them are exhausted. The elements of this iterator always come before the elements of the other iterator in the corresponding index.

      Once one of the iterators is exhausted, the resulting iterator will yield the remaining values of the other iterator until it is also exhausted.

      ExtraIterator.from([1, 2, 3])
          .interleave(['a', 'b', 'c'])
          .toArray()
          // returns [1, 'a', 2, 'b', 3, 'c']

      ExtraIterator.from([1, 2, 3, 4, 5, 6])
          .interleave(['a', 'b', 'c'])
          .toArray()
          // returns [1, 'a', 2, 'b', 3, 'c', 4, 5, 6]

    • Creates a new iterator that yields the values of this iterator interposed by a separator value. i.e., The separator is inserted between each pair of subsequent elements of this iterator.

      Type Parameters

      • U

        The type of the separator value.

      Parameters

      • separator: U

        The value to interpose between each pair of subsequent elements of this iterator.

      Returns ExtraIterator<T | U>

      A new iterator that yields the values of this iterator interposed by the provided separator.

      ExtraIterator.from([1, 2, 3, 4])
          .interpose('-')
          .toArray()
          // returns [1, '-', 2, '-', 3, '-', 4]

    • Creates a new iterator that yields the values of this iterator interposed by separator values produced by calling the callback function provided as argument.

      Type Parameters

      • U

        The type of the separator value.

      Parameters

      • separatorProvider: (lhs: T, rhs: T, index: number) => U

        A function that provides the separator value for a given pair of adjacent elements.

      Returns ExtraIterator<T | U>

      A new iterator that yields the values of this iterator interposed by the provided separator values.

      The callback function is called for each pair of adjacent elements in this iterator. The returned value will be inserted as an element between the pair in the resulting iterator.

      ExtraIterator.from([2, 3, 5, 8])
          .interposeWith((lhs, rhs) => (lhs + rhs) / 2)
          .toArray()
          // returns [2, 2.5, 3, 4, 5, 6.5, 8]

    • Creates a new iterator that loops over this iterator, yielding the same values repeatedly.

      Parameters

      • Optionaloptions: { pingpong?: boolean }

      Returns ExtraIterator<T>

      A new iterator that loops over this iterator the specified number of times.

      Creates a new iterator that yields the elements of this iterator a number of times specified by the {@param times} parameter. The resulting iterator first iterates over this iterator, yielding all its values in order, and then reiterates over the same values and yields each of them again, again and again, until it has looped the specified number of times.

      If the times parameter is Infinity (the default), the resulting iterator will loop indefinitely.

      ExtraIterator.from([1, 2, 3]).loop(3).toArray() // returns [1, 2, 3, 1, 2, 3, 1, 2, 3]

    • Creates a new iterator that loops over this iterator, yielding the same values repeatedly.

      Parameters

      • Optionaltimes: number

        The number of times to loop over this iterator. Must be an integer number or Infinity (which is the default). If negative, the resulting iterator will be inverted. If zero, the resulting iterator will be empty.

      • Optionaloptions: { pingpong?: boolean }

      Returns ExtraIterator<T>

      A new iterator that loops over this iterator the specified number of times.

      Creates a new iterator that yields the elements of this iterator a number of times specified by the {@param times} parameter. The resulting iterator first iterates over this iterator, yielding all its values in order, and then reiterates over the same values and yields each of them again, again and again, until it has looped the specified number of times.

      If the times parameter is Infinity (the default), the resulting iterator will loop indefinitely.

      ExtraIterator.from([1, 2, 3]).loop(3).toArray() // returns [1, 2, 3, 1, 2, 3, 1, 2, 3]

    • Prepends a new value to the beginning of the iterator. The new value will be yielded first, then the rest of this iterator will be yielded.

      Type Parameters

      • U

      Parameters

      • item: U

        The value to prepend to the beginning of the iterator.

      Returns ExtraIterator<T | U>

      A new iterator that yields the provided value, followed by the values of this iterator.

      ExtraIterator.from([1, 2, 3])
          .prepend(0)
          .toArray()
          // returns [0, 1, 2, 3]

    • Concatenates multiple values to the start of this iterator.

      Type Parameters

      • U

      Parameters

      • items: Iterable<U>

        An iterable of values to concatenate to the start of this iterator.

      Returns ExtraIterator<T | U>

      A new iterator that yields the values of the provided items iterable, followed by the values of this iterator.

      The order of the values is preserved.

      ExtraIterator.from([4, 5, 6])
          .prependAll([1, 2, 3])
          .toArray()
          // returns [1, 2, 3, 4, 5, 6]

    • Replaces some elements of this iterator with new values.

      Parameters

      • startIndex: number

        The index of the first element to be replaced; and the index where the new elements will be inserted. If negative, it will begin that many elements from the end of the iterator.

      • deleteCount: number

        The number of elements to be removed.

      • ...newItems: T[]

        The new elements to be inserted.

      Returns ExtraIterator<T>

      // Replaces 'Bob' and 'Charlie' with 'Eve' and 'Frank'
      ExtraIterator.from(['Alice', 'Bob', 'Charlie', 'David'])
          .splice(1, 2, 'Eve', 'Frank')
          .toArray()
          // returns ['Alice', 'Eve', 'Frank', 'David']

      // Removes 'Bob' and 'Charlie' without replacement.
      ExtraIterator.from(['Alice', 'Bob', 'Charlie', 'David'])
          .splice(1, 2)
          .toArray()
          // returns ['Alice', 'David']

      // Inserts 'Eve' and 'Frank' without any removal.
      ExtraIterator.from(['Alice', 'Bob', 'Charlie', 'David'])
          .splice(1, 0, 'Eve', 'Frank')
          .toArray()
          // returns ['Alice', 'Eve', 'Frank', 'Bob', 'Charlie', 'David']

    • Creates a new iterator that yields only the first limit values of this iterator. If limit is negative, it yields the last -limit values instead.

      Parameters

      • limit: number

        The number of values to take. If negative, takes values from the end.

      Returns ExtraIterator<T>

      A new iterator that yields the specified number of values.

      If limit is greater than the number of elements in this iterator, then the returned iterator will yield all the values of this iterator.

      If limit is negative, the returned iterator will consume the iterator and return the last -limit values, preserving the order of the original iterator. (i.e., the last element yielded by this iterator will be yielded last by the resulting iterator)

      Be careful when using a negative limit with infinite iterators, as it will cause an infinite loop.

      ExtraIterator.from([1, 2, 3, 4, 5]).take(3).toArray() // returns [1, 2, 3]
      ExtraIterator.from([1, 2, 3, 4, 5]).take(-2).toArray() // returns [4, 5]

    • Creates a new iterator that invokes the provided callback function for each element of this iterator and yields the elements for which the callback returns true, only for as long as the callback returns true.

      Parameters

      • predicate: (value: T, index: number) => boolean

        A function that takes a value and its index, and returns a boolean indicating whether the value should be kept (if true) or discarded (if false). Iteration stops once this function returns false.

      Returns ExtraIterator<T>

      A new iterator that yields the values of this iterator for which the provided predicate function returns true.

      This is similar to filter, except iteration stops once the callback returns false for the first time.

      ExtraIterator.from(['Alice', 'Antony', 'Charlie', 'Ashley'])
          .takeWhile(name => name[0] === 'A')
          .toArray()
          // returns ['Alice', 'Antony']

      // ℹ Note that, in the example above, `filter()` would have returned `['Alice', 'Antony', 'Ashley']` instead.

    • Creates a new iterator that yields the values of this iterator, but won't yield any duplicates.

      Parameters

      • keyProvider: (value: T) => unknown = ...

        An optional function that returns a key for each value. The keys are used to determine whether two values are equal or not. If two values have the same key, only the first one will be yielded. The other is ignored.

      Returns ExtraIterator<T>

      A new iterator that yields the unique values of this iterator.

      The returned iterator yields the first occurrence of each value in this iterator.

      ExtraIteartor.from('determination')
          .unique()
          .toArray()
           // returns ['d', 'e', 't', 'r', 'm', 'i', 'n', 'a', 'o']

    • If the elements of this iterator are also iterable, then this method creates a new iterator that iterates on all those iterable elements simultaneously.

      Returns T extends Iterable<U, any, any> ? ExtraIterator<U[]> : never

      A new iterator that iterates on all the iterable elements of this iterator simultaneously.

      For each iteration of the resulting iterator, it yields an array. The array contains one element from each of the child iterable, at the corresponding position.

      ExtraIterator.from([
              [1, 2, 3],
              ['a', 'b', 'c'],
              [true, false, true],
          ])
          .zip()
          .toArray() // returns [[1, 'a', true], [2, 'b', false], [3, 'c', true]]

    • Creates a new iterator that iterates on this iterator and the proviuded other iterator, yielding arrays of pairs of elements from this iterator and the other.

      Type Parameters

      • U

      Parameters

      • other: Iterable<U>

        An iterable to zip with this iterator.

      Returns ExtraIterator<[T, U]>

      A new iterator that iterates on this iterator and the provided other iterator simultaneously.

      ExtraIterator.from([1, 2, 3])
          .zip(['a', 'b', 'c'])
          .toArray()
          // returns [[1, 'a'], [2, 'b'], [3, 'c']]

    • If the elements of this iterator are also iterable, then this method creates a new iterator that iterates on all those iterable elements simultaneously.

      Type Parameters

      • U1
      • U2

      Parameters

      • other1: Iterable<U1>
      • other2: Iterable<U2>

      Returns ExtraIterator<[T, U1, U2]>

      A new iterator that iterates on all the iterable elements of this iterator simultaneously.

      For each iteration of the resulting iterator, it yields an array. The array contains one element from each of the child iterable, at the corresponding position.

      ExtraIterator.from([
              [1, 2, 3],
              ['a', 'b', 'c'],
              [true, false, true],
          ])
          .zip()
          .toArray() // returns [[1, 'a', true], [2, 'b', false], [3, 'c', true]]

    • If the elements of this iterator are also iterable, then this method creates a new iterator that iterates on all those iterable elements simultaneously.

      Type Parameters

      • U1
      • U2
      • U3

      Parameters

      • other1: Iterable<U1>
      • other2: Iterable<U2>
      • other3: Iterable<U3>

      Returns ExtraIterator<[T, U1, U2, U3]>

      A new iterator that iterates on all the iterable elements of this iterator simultaneously.

      For each iteration of the resulting iterator, it yields an array. The array contains one element from each of the child iterable, at the corresponding position.

      ExtraIterator.from([
              [1, 2, 3],
              ['a', 'b', 'c'],
              [true, false, true],
          ])
          .zip()
          .toArray() // returns [[1, 'a', true], [2, 'b', false], [3, 'c', true]]

    • If the elements of this iterator are also iterable, then this method creates a new iterator that iterates on all those iterable elements simultaneously.

      Type Parameters

      • U1
      • U2
      • U3
      • U4

      Parameters

      • other1: Iterable<U1>
      • other2: Iterable<U2>
      • other3: Iterable<U3>
      • other4: Iterable<U4>

      Returns ExtraIterator<[T, U1, U2, U3, U4]>

      A new iterator that iterates on all the iterable elements of this iterator simultaneously.

      For each iteration of the resulting iterator, it yields an array. The array contains one element from each of the child iterable, at the corresponding position.

      ExtraIterator.from([
              [1, 2, 3],
              ['a', 'b', 'c'],
              [true, false, true],
          ])
          .zip()
          .toArray() // returns [[1, 'a', true], [2, 'b', false], [3, 'c', true]]

    • Creates a new iterator that iterates on this iterator and the proviuded other iterators simultaneously, yielding arrays with the elements these iterators at the corresponding position.

      Type Parameters

      • U

      Parameters

      • ...others: Iterable<U, any, any>[]

        Several iterables to zip with this iterator.

      Returns ExtraIterator<(T | U)[]>

      A new iterator that iterates on this iterator and the provided other iterators simultaneously.

      ExtraIterator.from([1, 2, 3])
          .zip(['a', 'b', 'c'], [true, false, true])
          .toArray()
          // returns [[1, 'a', true], [2, 'b', false], [3, 'c', true]]

    Settings

    Member Visibility

    On This Page

    Properties
    Methods
    Aggregation methods
    Iterator protocol methods
    Miscellaneous methods
    Static constructors
    Transformation methods