Итератор

Объект Iterator — это объект, который соответствует протоколу итератора, предоставляя метод next(), который возвращает объект результата итератора. Все встроенные итераторы наследуются от класса Iterator. Класс Iterator предоставляет метод [Symbol.iterator](), который возвращает сам объект итератора, делая итератор также итерируемым. Он также предоставляет некоторые вспомогательные методы для работы с итераторами.

Описание

Ниже приведены все встроенные итераторы JavaScript:

• Итератор массива (Array Iterator), возвращаемый Array.prototype.values(), Array.prototype.keys(), Array.prototype.entries(), Array.prototype[Symbol.iterator](), TypedArray.prototype.values(), TypedArray.prototype.keys(), TypedArray.prototype.entries(), TypedArray.prototype[Symbol.iterator]() и arguments[Symbol.iterator]().
• Итератор строки (String Iterator), возвращаемый String.prototype[Symbol.iterator]().
• Итератор Map (Map Iterator), возвращаемый Map.prototype.values(), Map.prototype.keys(), Map.prototype.entries() и Map.prototype[Symbol.iterator]().
• Итератор Set (Set Iterator), возвращаемый Set.prototype.values(), Set.prototype.keys(), Set.prototype.entries() и Set.prototype[Symbol.iterator]().
• Итератор строк RegExp (RegExp String Iterator), возвращаемый RegExp.prototype[Symbol.matchAll]() и String.prototype.matchAll().
• Объект Generator, возвращаемый функциями-генераторами.
• Итератор сегментов (Segments Iterator), возвращаемый методом [Symbol.iterator]() объекта Segments, возвращаемого Intl.Segmenter.prototype.segment().
• Вспомогательный итератор (Iterator Helper), возвращаемый вспомогательными методами итератора, такими как Iterator.prototype.filter() и Iterator.prototype.map().

Веб-API также могут возвращать итераторы. Некоторые из них повторно используют основные итераторы JavaScript, а другие определяют свои собственные итераторы. Например:

• Объекты, похожие на массивы (Array-Like), такие как NodeList, возвращают Array Iterator из своих соответствующих методов keys(), values(), entries() и [Symbol.iterator]().
• Объекты, похожие на Map, из веб-API, такие как Headers, возвращают свой собственный тип итератора, такой как Headers Iterator, из своих соответствующих методов keys(), values(), entries() и [Symbol.iterator]().
• Объекты, похожие на Set, из веб-API, такие как FontFaceSet, возвращают свой собственный тип итератора, такой как FontFaceSet Iterator, из своих соответствующих методов keys(), values(), entries() и [Symbol.iterator]().

Каждый из этих итераторов имеет отдельный объект прототипа, который определяет метод next(), используемый конкретным итератором. Например, все итераторы строк наследуют от скрытого объекта StringIteratorPrototype, у которого есть метод next(), который итерирует строку по кодовым точкам. StringIteratorPrototype также имеет свойство [Symbol.toStringTag], начальное значение которого — строка "String Iterator". Это свойство используется в Object.prototype.toString(). Аналогично, другие прототипы итераторов также имеют свои собственные значения [Symbol.toStringTag], которые совпадают с названиями, приведенными выше.

Все эти объекты прототипов наследуют от Iterator.prototype, который предоставляет метод [Symbol.iterator](), возвращающий сам объект итератора, что делает итератор также итерируемым.

Вспомогательные методы итератора

Сам класс Iterator предоставляет некоторые вспомогательные методы для работы с итераторами. Например, вы можете захотеть сделать следующее:

const nameToDeposit = new Map([
  ["Anne", 1000],
  ["Bert", 1500],
  ["Carl", 2000],
]);

const totalDeposit = [...nameToDeposit.values()].reduce((a, b) => a + b);

Это сначала преобразует итератор, возвращаемый Map.prototype.values(), в массив, а затем использует метод Array.prototype.reduce() для вычисления суммы. Однако это создает промежуточный массив и дважды итерирует массив. Вместо этого вы можете использовать метод reduce() самого итератора:

const totalDeposit = nameToDeposit.values().reduce((a, b) => a + b);

Этот метод может быть более эффективным, особенно с точки зрения памяти, потому что он итерирует итератор только один раз, не запоминая никаких промежуточных значений. Вспомогательные методы итератора необходимы для работы с бесконечными итераторами:

function* fibonacci() {
  let current = 1;
  let next = 1;
  while (true) {
    yield current;
    [current, next] = [next, current + next];
  }
}

const seq = fibonacci();
const firstThreeDigitTerm = seq.find((n) => n >= 100);

Вы не можете преобразовать seq в массив, потому что он бесконечен. Вместо этого вы можете использовать метод find() самого итератора, который итерирует seq только настолько, насколько это необходимо для поиска первого значения, удовлетворяющего условию.

Вы найдете множество методов итератора, аналогичных методам массива, таких как:

Iterator.prototype.drop() и Iterator.prototype.take() в совокупности в некоторой степени аналогичны Array.prototype.slice().

Вспомогательные объекты итератора

Среди вспомогательных методов итератора, filter(), flatMap(), map(), drop() и take() возвращают новый объект Iterator Helper. Вспомогательный итератор также является экземпляром Iterator, что делает эти вспомогательные методы цепочными. Все вспомогательные объекты итератора наследуют от общего объекта прототипа, который реализует протокол итератора:

next()

Вызывает метод next() базового итератора, применяет вспомогательный метод к результату и возвращает результат.

return()

Вызывает метод return() базового итератора и возвращает результат.

Вспомогательный итератор использует тот же источник данных, что и базовый итератор, поэтому итерация по вспомогательному итератору также итерирует базовый итератор. Нет способа «разветвить» итератор, чтобы он мог быть итерирован несколько раз.

const it = [1, 2, 3].values();
const it2 = it.drop(0); // Essentially a copy
console.log(it.next().value); // 1
console.log(it2.next().value); // 2
console.log(it.next().value); // 3

Правильные итераторы

Существует два типа «итераторов»: объекты, соответствующие протоколу итератора (который, как минимум, требует только наличия метода next()), и объекты, наследующие от класса Iterator, которые пользуются вспомогательными методами. Они не подразумевают друг друга — объекты, наследующие от Iterator, автоматически не становятся итераторами, потому что класс Iterator не определяет метод next(). Вместо этого объект должен сам определить метод next(). Правильный итератор — это тот, который одновременно соответствует протоколу итератора и наследует от Iterator, и большинство кода ожидает, что итераторы будут правильными итераторами, а итерируемые объекты будут возвращать правильные итераторы. Чтобы создать правильные итераторы, определите класс, который расширяет Iterator, или используйте метод Iterator.from().

class MyIterator extends Iterator {
  next() {
    // …
  }
}

const myIterator = Iterator.from({
  next() {
    // …
  },
});

Конструктор

Iterator()

Предназначен для расширения другими классами, которые создают итераторы. Вызывает ошибку при конструировании самостоятельно.

Статические методы

Iterator.concat()

Создает новый объект Iterator из списка итерируемых объектов. Новый итератор выдает значения из каждого входного итерируемого объекта последовательно.

Iterator.from()

Создает новый объект Iterator из итератора или итерируемого объекта.

Iterator.zip()

Создает новый объект Iterator, который агрегирует элементы из нескольких итерируемых объектов, выдавая массивы, содержащие элементы на одной и той же позиции.

Iterator.zipKeyed()

Создает новый объект Iterator, который агрегирует элементы из нескольких итерируемых объектов, выдавая объекты, содержащие элементы на одной и той же позиции, с ключами, указанными во входных данных.

Свойства экземпляра

Эти свойства определены на Iterator.prototype и разделяются всеми экземплярами Iterator.

Iterator.prototype.constructor

Конструктор, который создал экземпляр объекта. Для экземпляров Iterator начальное значение — конструктор Iterator.

Iterator.prototype[Symbol.toStringTag]

Начальное значение свойства [Symbol.toStringTag] — строка "Iterator". Это свойство используется в Object.prototype.toString().

Примечание: В отличие от [Symbol.toStringTag] в большинстве встроенных классов, Iterator.prototype[Symbol.toStringTag] является записываемым по причинам совместимости с веб-API.

Методы экземпляра

Iterator.prototype.chunks() Экспериментально

Возвращает новый объект вспомогательного итератора, который разбивает элементы из исходного итератора на последовательные блоки массива. Каждый раз, когда вспомогательный объект итерируется, он получает указанное количество элементов из базового итератора и выдает их вместе.

Iterator.prototype.drop()

Возвращает новый объект вспомогательного итератора, который пропускает указанное количество элементов в начале этого итератора.

Iterator.prototype.every()

Возвращает false, если найден элемент, который не удовлетворяет предоставленной тестовой функции. В противном случае, если итератор исчерпан без нахождения такого элемента, возвращает true.

Iterator.prototype.filter()

Возвращает новый объект вспомогательного итератора, который выдает только те элементы итератора, для которых предоставленная функция обратного вызова возвращает true.

Iterator.prototype.find()

Возвращает первый элемент, произведенный итератором, который удовлетворяет предоставленной тестовой функции. Если ни одно значение не удовлетворяет тестовой функции, возвращается undefined.

Iterator.prototype.flatMap()

Возвращает новый объект вспомогательного итератора, который берет каждый элемент из исходного итератора, пропускает его через функцию сопоставления и выдает элементы, возвращаемые функцией сопоставления (которые содержатся в другом итераторе или итерируемом объекте).

Iterator.prototype.forEach()

Выполняет предоставленную функцию один раз для каждого элемента, произведенного итератором.

Iterator.prototype.includes() Экспериментально

Возвращает true, если элемент, произведенный итератором, равен заданному значению. В противном случае, если итератор исчерпан без нахождения такого элемента, возвращает false.

Iterator.prototype.join()

Возвращает строку, представляющую собой конкатенацию всех элементов, произведенных итератором, разделенных запятыми или указанной строкой-разделителем.

Iterator.prototype.map()

Возвращает новый объект вспомогательного итератора, который выдает элементы итератора, каждый из которых преобразован функцией сопоставления.

Iterator.prototype.reduce()

Выполняет пользовательскую функцию обратного вызова «редуктора» для каждого элемента, произведенного итератором, передавая результат вычисления предыдущего элемента. Конечным результатом выполнения редуктора по всем элементам является одно значение.

Iterator.prototype.some()

Возвращает true, если найден элемент, удовлетворяющий предоставленной тестовой функции. В противном случае, если итератор исчерпан без нахождения такого элемента, возвращает false.

Iterator.prototype.take()

Возвращает новый объект вспомогательного итератора, который выдает указанное количество элементов из этого итератора, а затем завершается.

Iterator.prototype.toArray()

Создает новый экземпляр Array, заполненный элементами, полученными из итератора.

Iterator.prototype.windows() Экспериментально

Возвращает новый объект вспомогательного итератора, который выдает скользящее окно элементов. Каждый раз, когда вспомогательный объект итерируется, он выдает массив, удаляя первый элемент из предыдущей итерации и добавляя следующий элемент из исходного итератора.

Iterator.prototype[Symbol.dispose]()

Вызывает метод return() this, если он существует. Это реализует протокол disposability и позволяет освобождать ресурсы при использовании с using или await using.

Iterator.prototype[Symbol.iterator]()

Возвращает сам объект итератора. Это позволяет объектам-итераторам также быть итерируемыми.

Примеры

Использование итератора как итерируемого объекта

Все встроенные итераторы также являются итерируемыми, поэтому вы можете использовать их в цикле for...of:

const arrIterator = [1, 2, 3].values();
for (const value of arrIterator) {
  console.log(value);
}
// Logs: 1, 2, 3

Спецификации

Совместимость с браузерами

См. также

• Polyfill of Iterator in core-js
• es-shims polyfill of Iterator and associated helpers
• function*
• Iteration protocols