ECMAScript: Iterator

Modules

es.iterator.constructor, es.iterator.chunks, es.iterator.concat, es.iterator.dispose, es.iterator.drop, es.iterator.every, es.iterator.filter, es.iterator.find, es.iterator.flat-map, es.iterator.for-each, es.iterator.from, es.iterator.includes, es.iterator.join, es.iterator.map, es.iterator.reduce, es.iterator.some, es.iterator.take, es.iterator.to-array, es.iterator.windows, es.iterator.zip, es.iterator.zip-keyed.

Built-ins signatures

class Iterator {
  constructor(): Iterator; // abstract
  static concat(...items: Array<IterableObject>): Iterator<any>;
  static from(iterable: Iterable<any> | Iterator<any>): Iterator<any>;
  static zip<T extends readonly Iterable<unknown>[]>(
    iterables: T,
    options?: {
      mode?: 'shortest' | 'longest' | 'strict';
      padding?: { [K in keyof T]?: T[K] extends Iterable<infer U> ? U : never };
    }
  ): Iterator<{ [K in keyof T]: T[K] extends Iterable<infer U> ? U : never }>;
  static zipKeyed<K extends PropertyKey, V extends Record<K, Iterable<unknown>>>(
    iterables: V,
    options?: {
      mode?: 'shortest' | 'longest' | 'strict';
      padding?: { [P in keyof V]?: V[P] extends Iterable<infer U> ? U : never };
    }
  ): Iterator<{ [P in keyof V]: V[P] extends Iterable<infer U> ? U : never }>;
  chunks(chunkSize: number): Iterator<any>;
  drop(limit: uint): Iterator<any>;
  every(callbackfn: (value: any, counter: uint) => boolean): boolean;
  filter(callbackfn: (value: any, counter: uint) => boolean): Iterator<any>;
  find(callbackfn: (value: any, counter: uint) => boolean): any;
  flatMap(callbackfn: (value: any, counter: uint) => Iterable<any> | Iterator<any>): Iterator<any>;
  forEach(callbackfn: (value: any, counter: uint) => void): void;
  includes(searchElement: any, skippedElements?: number): boolean;
  join(separator?: string): string;
  map(callbackfn: (value: any, counter: uint) => any): Iterator<any>;
  reduce(callbackfn: (memo: any, value: any, counter: uint) => any, initialValue?: any): any;
  some(callbackfn: (value: any, counter: uint) => boolean): boolean;
  take(limit: uint): Iterator<any>;
  toArray(): Array<any>;
  windows(windowSize: number, undersized?: 'only-full' | 'allow-partial' | undefined): Iterator<any>;
  @@dispose(): undefined;
  @@toStringTag: 'Iterator';
}

Entry points

core-js(-pure)/es|stable|actual|full/iterator
core-js(-pure)/es|stable|actual|full/iterator/chunks
core-js(-pure)/es|stable|actual|full/iterator/concat
core-js(-pure)/es|stable|actual|full/iterator/dispose
core-js(-pure)/es|stable|actual|full/iterator/drop
core-js(-pure)/es|stable|actual|full/iterator/every
core-js(-pure)/es|stable|actual|full/iterator/filter
core-js(-pure)/es|stable|actual|full/iterator/find
core-js(-pure)/es|stable|actual|full/iterator/flat-map
core-js(-pure)/es|stable|actual|full/iterator/for-each
core-js(-pure)/es|stable|actual|full/iterator/from
core-js(-pure)/es|stable|actual|full/iterator/includes
core-js(-pure)/es|stable|actual|full/iterator/join
core-js(-pure)/es|stable|actual|full/iterator/map
core-js(-pure)/es|stable|actual|full/iterator/reduce
core-js(-pure)/es|stable|actual|full/iterator/some
core-js(-pure)/es|stable|actual|full/iterator/take
core-js(-pure)/es|stable|actual|full/iterator/to-array
core-js(-pure)/es|stable|actual|full/iterator/windows
core-js(-pure)/es|stable|actual|full/iterator/zip
core-js(-pure)/es|stable|actual|full/iterator/zip-keyed

Examples

[1, 2, 3, 4, 5, 6, 7].values()
  .drop(1)
  .take(5)
  .filter(it => it % 2)
  .map(it => it ** 2)
  .toArray(); // => [9, 25]

Iterator.from({
  next: () => ({ done: Math.random() > 0.9, value: Math.random() * 10 | 0 }),
}).toArray(); // => [7, 6, 3, 0, 2, 8]

Iterator.concat([0, 1].values(), [2, 3], function * () {
  yield 4;
  yield 5;
}()).toArray(); // => [0, 1, 2, 3, 4, 5]

Iterator.zip([
  [0, 1, 2],
  [3, 4, 5],
]).toArray();  // => [[0, 3], [1, 4], [2, 5]]

Iterator.zipKeyed({
  a: [0, 1, 2],
  b: [3, 4, 5, 6],
  c: [7, 8, 9],
}, {
  mode: 'longest',
  padding: { c: 10 },
}).toArray(); // =>
/*
[
  { a: 0,         b: 3, c: 7  },
  { a: 1,         b: 4, c: 8  },
  { a: 2,         b: 5, c: 9  },
  { a: undefined, b: 6, c: 10 },
];
 */

const digits = () => [0, 1, 2, 3, 4, 5, 6, 7, 8, 9].values();

Array.from(digits().chunks(2));  // => [[0, 1], [2, 3], [4, 5], [6, 7], [8, 9]]

Array.from(digits().windows(2));  // => [[0, 1], [1, 2], [2, 3], [3, 4], [4, 5], [5, 6], [6, 7], [7, 8], [8, 9]]

Array.from([0, 1].values().windows(3, 'allow-partial'));  // => [[0, 1]]

Array.from([0, 1].values().windows(3));  // => []

[1, 2, 3].values().includes(2);     // => true
[1, 2, 3].values().includes(4);     // => false
[NaN].values().includes(NaN);       // => true
[1, 2, 3].values().includes(3, 2);  // => true
[1, 2, 3].values().includes(1, 1);  // => false

[1, 2, 3].values().join();     // => '1,2,3'
[1, 2, 3].values().join('-');  // => '1-2-3'
[1, null, 3].values().join();  // => '1,,3'