Iter8or

Документация

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

Особенности

• Поддержка синхронных и асинхронных итераторов: Обрабатывайте как синхронные, так и асинхронные данные с помощью единого API.
• Поддержка функций-генераторов: Поддержка как синхронных, так и асинхронных функций-генераторов. Функция будет вызвана автоматически, и возвращаемый генератор будет использоваться для итерации.
• Создание итераторов из неитерируемых объектов:
  • Для чисел (number):
    • По умолчанию создается итератор, который проходит от 1 (или -1, если передано число меньше 0) до указанного числа включительно (диапазон).
    • Опция digits: Если передана опция { digits: true }, число разбивается на отдельные разряды, создавая итератор по цифрам числа. Поддерживается как обычные числа, так и BigInt.
    • Если используется итератор диапазона, можно передавать числа в пределах от -(2 ** 32 - 1) до 2 ** 32 - 1. Это ограничение введено для предотвращения чрезмерного использования памяти и ресурсов.
  • Для объектов (object): Создается итератор, который проходит по ключам и значениям объекта.
• Мощные методы обработки данных: Встроенные методы для фильтрации, маппинга, группировки, разделения, объединения и других операций с данными.
• Поддержка ES-модулей и CommonJS: Библиотека может использоваться как с современными ES-модулями, так и с традиционными CommonJS-модулями.

Установка

Установите библиотеку с помощью npm:

npm install iter8or

Пример использования

• с массивом

import Iter8or from 'iter8or';

const iter = new Iter8or([1, 2, 3]);
const mapped = iter.map(x => x * 2);
console.log([...mapped]); // [2, 4, 6]

• с числом

const rangeIter = new Iter8or(3);
console.log([...rangeIter]); // [1, 2, 3]

• с числом и опцией digits

const digitsIter = new Iter8or(12345, { digits: true });
console.log([...digitsIter]); // [1, 2, 3, 4, 5]

• с объектом

const objIter = new Iter8or({ a: 1, b: 2 });
for (const [key, value] of objIter) {
    console.log(key, value);
}
// a 1
// b 2

• с функциями-генераторами

function* generatorFunction() {
  yield 1;
  yield 2;
  yield 3;
}

const iter = new Iter8or(generatorFunction);
console.log([...iter]); // [1, 2, 3]

• с асинхронными генераторами

async function* asyncGeneratorFunction() {
  yield 1;
  yield 2;
  yield 3;
}

const iter = new Iter8or(asyncGeneratorFunction, { async: true });
(async () => {
  for await (const value of iter) {
    console.log(value); // 1, 2, 3
  }
})();

Работа с асинхронными итераторами

Чтобы использовать асинхронные итераторы, необходимо передать опцию { async: true } в конструктор. Это позволит корректно обработать асинхронные данные с использованием await. В противном случае итератор будет обрабатываться как синхронный. Например:

const asyncIter = new Iter8or([
  async () => 'apple',
  async () => 'banana',
  async () => 'cherry'
], { async: true });

for await (const value of asyncIter) {
  console.log(value);
}
// 'apple'
// 'banana'
// 'cherry'

Важные замечания о числах

• Опция digits: true: Позволяет итерировать по отдельным цифрам числа, поддерживая как обычные числа, так и BigInt.
• Цифры (number) всегда обрабатываются как синхронные итераторы, независимо от того, передана опция { async: true } или нет.
• Отрицательные числа при digits: true: Знак отбрасывается, и число обрабатывается как положительное.
• Числа с плавающей точкой не поддерживаются при digits: true: Такие числа приводят к выбросу исключения RangeError.

Итерация по диапазонам (RangeIterable):

Итераторы диапазонов (range) ограничены числами от -(2^53 - 1) до 2^53 - 1 (что соответствует значению Number.MAX_SAFE_INTEGER). Это ограничение гарантирует, что диапазон может быть обработан без ошибок потери точности. Если вы попытаетесь создать диапазон за пределами этих значений, библиотека выбросит исключение RangeError.

• Внимание: При работе с очень большими диапазонами использование оператора spread (например, ...rangeIter) может привести к проблемам с памятью и производительностью. Вместо этого рекомендуется вручную обрабатывать большие диапазоны в цикле, чтобы избежать переполнения памяти:

const largeRangeIter = new Iter8or(1000000000); // Очень большой диапазон

for (let num of largeRangeIter) {
  // Обрабатываем каждое число
  if (num > 100) break; // Пример: Останавливаемся после обработки первых 100 чисел
}

Пример с диапазоном RangeIterable:

const rangeIter = new Iter8or(5);
console.log([...rangeIter]); // [1, 2, 3, 4, 5]

Пример с BigInt и опцией digits: true:

const bigIntIter = new Iter8or(12345678901234567890n, { digits: true });
console.log([...bigIntIter]); // [1, 2, 3, 4, 5, 6, 7, 8, 9, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0]

🔍 Подробнее о каждом методе класса Iter8or

🇬🇧 Switch to English