Skip to content

Latest commit

 

History

History
139 lines (114 loc) · 7.86 KB

README.ru.md

File metadata and controls

139 lines (114 loc) · 7.86 KB
Raw

Iter8or

npm version

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

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