npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

into-iter

v2.0.0

Published

Lazy chainable adapters for iterables

Readme

into-iter

Ленивые адаптеры для любых iterable. Цепочка не обходит источник, пока её не начинают читать, и один и тот же результат можно прочитать повторно. Для источников, которые умеют читаться с обоих концов, reversed идёт с конца без копирования.

Пакет собран как ES-модули и рассчитан на Node.js 22+.

История версий — в CHANGELOG.md.

Установка

npm install into-iter

Подключение методов

Основной вход отдаёт intoIter без методов. Каждый метод подключается отдельным импортом и не попадает в сборку, пока этот импорт не написан:

import { intoIter, range } from "into-iter";
import "into-iter/map";
import "into-iter/enumerate";
import "into-iter/filter";
import "into-iter/limit";
import "into-iter/skip";
import "into-iter/flat-map";
import "into-iter/collect";
import "into-iter/math";
import "into-iter/reduce";
import "into-iter/fold";
import "into-iter/every";
import "into-iter/find";
import "into-iter/nth";
import "into-iter/take-while";
import "into-iter/skip-while";
import "into-iter/map-while";
import "into-iter/chain";

const values = intoIter([1, 2, 3, 4])
  .map((n) => n * 2)
  .filter((n) => n > 4);

console.log([...values]); // [6, 8]
console.log([...values]); // [6, 8]

reversed есть всегда, отдельный импорт ему не нужен. Все синхронные методы сразу подключает import "into-iter/all".

Источники

intoIter принимает любой iterable. Диапазон создаёт range: число задаёт конец (0 .. end с шагом 1), объект — start, end и step.

import { intoIter, range } from "into-iter";

[...intoIter([1, 2, 3])]; // [1, 2, 3]
[...intoIter("abc")]; // ["a", "b", "c"]
[...intoIter(new Set([1, 2]))]; // [1, 2]

[...range(4)]; // [0, 1, 2, 3]
[...range({ start: 1, end: 8, step: 2 })]; // [1, 3, 5, 7]

Диапазон не включает end. Если start >= end, он пустой.

Массивы, строки, typed array и диапазоны читаются с обоих концов. Остальные iterable (Set, Map, генераторы) читаются только вперёд.

Асинхронный iterable (Symbol.asyncIterator) даёт AsyncIntoIter. Массив, строка, Set и Map остаются IntoIter. range тоже возвращает IntoIter. Если есть оба символа, выбирается асинхронный курсор.

const values = intoIter(
  (async function* () {
    yield 1;
    yield 2;
  })(),
);

for await (const value of values) {
  console.log(value);
}

Обход начинается при чтении. Источник, который каждый раз отдаёт новый [Symbol.asyncIterator], читается заново. Асинхронный генератор после первого прохода пуст.

Ранний выход закрывает курсор через return(). У источника выполняется finally. Незавершённый next() сразу завершается как { done: true }, и позднее значение наружу не проходит.

Асинхронные методы подключаются отдельно. Импорт into-iter/map их не добавляет. Все сразу подключает import "into-iter/async/all":

import { intoIter } from "into-iter";
import "into-iter/async/map";
import "into-iter/async/enumerate";
import "into-iter/async/filter";
import "into-iter/async/limit";
import "into-iter/async/skip";
import "into-iter/async/flat-map";
import "into-iter/async/collect";
import "into-iter/async/math";
import "into-iter/async/reduce";
import "into-iter/async/fold";
import "into-iter/async/every";
import "into-iter/async/find";
import "into-iter/async/nth";
import "into-iter/async/take-while";
import "into-iter/async/skip-while";
import "into-iter/async/map-while";
import "into-iter/async/chain";
import "into-iter/async/count";

const values = intoIter(
  (async function* () {
    yield 1;
    yield 2;
    yield 3;
    yield 4;
  })(),
)
  .map(async (n) => n * 10)
  .filter((n) => n > 20);

console.log(await values.toArray()); // [30, 40]

Контракт совпадает с синхронными методами. Адаптер возвращает AsyncIntoIter, терминальный метод возвращает Promise. Колбэки могут вернуть Promise. flatMap и chain принимают обычную или асинхронную последовательность; если есть оба символа, берётся асинхронный итератор.

reversed, foldRight и nthBack нет. last и findLast читают источник с начала. remaining сохраняют map, enumerate, limit, skip и chain, когда длина известна. count в этом случае возвращает её без чтения элементов. Символ своего коллектора по-прежнему импортируется из into-iter/collector.

Методы

map(fn)

Применяет fn к каждому элементу. fn вызывается только для прочитанных элементов.

[...intoIter([1, 2, 3]).map((n) => n * 10)]; // [10, 20, 30]

enumerate()

Нумерует элементы с нуля. Каждая пара — это индекс и значение. Индекс относится к тому итератору, на котором вызван enumerate: после filter или skip счёт начинается заново. Подключается отдельным импортом into-iter/enumerate.

[...intoIter(["a", "b", "c"]).enumerate()]; // [[0, "a"], [1, "b"], [2, "c"]]
[
  ...intoIter([1, 2, 3, 4])
    .filter((n) => n % 2 === 0)
    .enumerate(),
]; // [[0, 2], [1, 4]]

enumerate всегда считает с нуля в том порядке, в котором читается его источник. Сначала развернуть, потом нумеровать — индексы начинаются с нуля. Сначала нумеровать, потом развернуть — разворачиваются уже готовые пары, и индексы остаются прежними:

[...intoIter([1, 2, 3, 4]).reversed.enumerate()]; // [[0, 4], [1, 3], [2, 2], [3, 1]]
[...intoIter([1, 2, 3, 4]).enumerate().reversed]; // [[3, 4], [2, 3], [1, 2], [0, 1]]

Повторное чтение начинает нумерацию с нуля. Для enumerate().reversed нужна длина. После filter её нет, поэтому такая цепочка выбрасывает Cannot walk backwards.

filter(predicate)

Оставляет элементы, для которых predicate вернул true.

[...range(10).filter((n) => n % 3 === 0)]; // [0, 3, 6, 9]

limit(count)

Берёт первые count элементов и дальше источник не читает, поэтому работает и с бесконечными генераторами:

[...range(10).limit(3)]; // [0, 1, 2]
[...intoIter([1, 2]).limit(5)]; // [1, 2]
[...intoIter([1, 2]).limit(0)]; // []

count должен быть неотрицательным целым числом, иначе limit выбрасывает TypeError.

skip(count)

Пропускает первые count элементов. Дальше источник читается как обычно, в том числе бесконечный генератор, если после skip стоит limit:

[...range(10).skip(3)]; // [3, 4, 5, 6, 7, 8, 9]
[...intoIter([1, 2, 3]).skip(0)]; // [1, 2, 3]
[...intoIter([1, 2, 3]).skip(10)]; // []

count должен быть неотрицательным целым числом, иначе skip выбрасывает TypeError. Ноль элементов пропускать можно.

Несколько skip подряд складываются: skip(2).skip(3) пропускает пять элементов.

takeWhile(predicate)

Отдаёт элементы, пока predicate истинен. Первый неподходящий элемент читается и в результат не входит, дальше источник не читается. Подключается импортом into-iter/take-while.

[...intoIter([1, 2, 5, 3]).takeWhile((n) => n < 4)]; // [1, 2]
[...intoIter([1, 2, 5, 3]).reversed.takeWhile((n) => n < 4)]; // [3]

Длины у результата нет, и с конца он не читается. takeWhile(...).reversed выбрасывает Cannot walk backwards.

skipWhile(predicate)

Отбрасывает элементы, пока predicate истинен. С первого неподходящего элемента отдаёт весь хвост, включая его самого. Предикат для хвоста больше не вызывается. Подключается импортом into-iter/skip-while.

[...intoIter([1, 2, 5, 3]).skipWhile((n) => n < 4)]; // [5, 3]
[...intoIter([1, 5, 2]).skipWhile((n) => n < 4)]; // [5, 2]
[...intoIter([1, 2, 5, 3]).reversed.skipWhile((n) => n < 4)]; // [5, 2, 1]

skipWhile(...).reversed выбрасывает Cannot walk backwards.

mapWhile(fn)

Вызывает fn один раз на элемент и отдаёт её значение. null и undefined означают конец: этот элемент уже прочитан и в результат не входит, дальше источник не читается. 0, false и "" остаются. Подключается импортом into-iter/map-while.

[
  ...intoIter(["1", "2", "x", "4"]).mapWhile((s) => {
    const n = Number(s);
    return Number.isNaN(n) ? undefined : n;
  }),
]; // [1, 2]

[...intoIter([1, 0, 2]).mapWhile((n) => (n === 2 ? undefined : n))]; // [1, 0]
[...intoIter([1, 2, 0, 4]).reversed.mapWhile((n) => (n === 0 ? undefined : n))]; // [4]

mapWhile(...).reversed выбрасывает Cannot walk backwards.

chain(iterable)

Лениво склеивает текущую последовательность со второй того же типа элементов. Вперёд сначала читается первая, и только когда она закончилась — вторая. С конца можно идти, если обе стороны двусторонние: сначала вторая с конца, потом первая с конца. remaining есть, только когда длину знают обе стороны, и равен их сумме. Set или генератор на любой стороне убирает чтение с конца и remaining. Подключается импортом into-iter/chain.

[...intoIter([1, 2]).chain([3, 4])]; // [1, 2, 3, 4]
[...intoIter([1, 2]).chain([3, 4]).reversed]; // [4, 3, 2, 1]
[...intoIter([1, 2]).chain([3, 4]).chain([5])]; // [1, 2, 3, 4, 5]
[...intoIter([1, 2]).chain([3, 4]).chain([5]).reversed]; // [5, 4, 3, 2, 1]

const cursor = intoIter([1, 2]).chain([3, 4, 5])[Symbol.iterator]();
cursor.remaining?.(); // 5

intoIter([1, 2]).chain(new Set([3, 4])).reversed выбрасывает Cannot walk backwards.

flatMap(fn)

Вызывает fn для каждого элемента и склеивает последовательности, которые она вернула. fn должна вернуть Iterable: массив, строку, Set, Map, генератор или другой IntoIter. Одно значение передаётся массивом из одного элемента, [value]. Число, объект и null вызывают TypeError при чтении.

[...intoIter([1, 2, 3]).flatMap((n) => [n, n * 10])]; // [1, 10, 2, 20, 3, 30]
[...intoIter(["foo bar", "baz"]).flatMap((line) => line.split(" "))]; // ["foo", "bar", "baz"]

Пустая последовательность выпадает из результата. Строка разбирается на символы, Set отдаёт значения, Map отдаёт пары [key, value]:

[...intoIter([1, 2, 3]).flatMap((n) => (n === 2 ? [n] : []))]; // [2]
[...intoIter([1]).flatMap(() => "ab")]; // ["a", "b"]
[...intoIter(["a", "b"]).flatMap((key) => new Map([[key, key.length]]))]; // [["a", 1], ["b", 1]]

fn вызывается, только когда нужна следующая последовательность. Длины у результата нет: сколько элементов вернёт fn, заранее неизвестно.

flatten()

Склеивает один уровень вложенности. Это flatMap, который подставляет сам элемент как последовательность. Элемент должен быть Iterable, иначе при чтении будет TypeError.

[
  ...intoIter([
    [1, 2],
    [3, 4],
  ]).flatten(),
]; // [1, 2, 3, 4]

[...intoIter([[1], [], [2, 3]]).flatten()]; // [1, 2, 3]

Глубже одного уровня flatten не заглядывает. Следующий уровень снимает ещё один вызов:

[...intoIter([[[1, 2]], [[3]]]).flatten()]; // [[1, 2], [3]]
[
  ...intoIter([[[1, 2]], [[3]]])
    .flatten()
    .flatten(),
]; // [1, 2, 3]

Строка, Set и Map тоже последовательности: "ab" развернётся в "a", "b". flatten и filterMap подключаются тем же импортом, что и flatMap: into-iter/flat-map.

filterMap(fn)

За один проход преобразует элемент и решает, оставлять ли его. fn возвращает новое значение или undefined, чтобы пропустить исходный элемент. null тоже пропускается. Ноль, false и пустая строка остаются:

[
  ...intoIter(["1", "x", "2"]).filterMap((s) => {
    const n = Number(s);
    return Number.isNaN(n) ? undefined : n;
  }),
]; // [1, 2]

[...intoIter([0, false, "", 1]).filterMap((value) => value)]; // [0, false, "", 1]

Возвращённый массив приходит как один элемент и дальше не разворачивается. Длины у результата нет, поэтому filterMap(...).limit(n).reversed выбрасывает Cannot walk backwards. filterMap(...).reversed читает оставленные значения с конца:

[...intoIter([1, 2, 3, 4, 5]).filterMap((n) => (n % 2 === 0 ? n * 10 : undefined)).reversed]; // [40, 20]

reversed

Геттер, который возвращает ту же цепочку, читаемую с конца. Исходная цепочка не меняется, а двойной reversed возвращает исходный порядок.

const source = intoIter([1, 2, 3]);

[...source.reversed]; // [3, 2, 1]
[...source]; // [1, 2, 3]
[...source.reversed.reversed]; // [1, 2, 3]

Разворот ничего не копирует. Первый элемент перевёрнутого диапазона из миллиона чисел вычисляется сразу:

range(1_000_000)
  .map((n) => n * n)
  .reversed[Symbol.iterator]()
  .next(); // { done: false, value: 999998000001 }

map и filter сохраняют возможность чтения с конца, поэтому reversed можно ставить в любом месте цепочки:

[...range(10).filter((n) => n % 3 === 0).reversed]; // [9, 6, 3, 0]
[...intoIter([1, 2, 3]).reversed.map((n) => n * 10)]; // [30, 20, 10]

Если источник читается только вперёд, reversed выбрасывает Error("Cannot walk backwards"). Ошибка возникает при чтении, а не при вызове геттера:

const iter = intoIter(new Set([1, 2, 3])).reversed; // ошибки нет
[...iter]; // Error: Cannot walk backwards

limit и reversed вместе

Результат зависит от порядка:

[...range(10).limit(3).reversed]; // [2, 1, 0] — первые 3, с конца
[...range(10).reversed.limit(3)]; // [9, 8, 7] — последние 3

reversed.limit(n) работает с любой цепочкой, которая читается с конца. Для limit(n).reversed нужно ещё знать длину, чтобы найти n-й элемент. Длину знают массивы, строки, typed array и диапазоны, а map, enumerate, limit, skip и reversed её сохраняют. После filter, flatMap, flatten и filterMap длина неизвестна, поэтому такая цепочка выбрасывает Cannot walk backwards:

[
  ...range(20)
    .filter((n) => n % 7 === 0)
    .reversed.limit(2),
]; // [14, 7]
[
  ...range(20)
    .filter((n) => n % 7 === 0)
    .limit(2).reversed,
]; // Error: Cannot walk backwards
[
  ...intoIter([[1], [2, 3, 4]])
    .flatten()
    .limit(2).reversed,
]; // Error: Cannot walk backwards

skip вместе с reversed тоже зависит от порядка. skip(n).reversed читает хвост с конца, reversed.skip(n) выбрасывает последние n элементов:

[...range(10).skip(3).reversed]; // [9, 8, 7, 6, 5, 4, 3]
[...range(10).reversed.skip(3)]; // [6, 5, 4, 3, 2, 1, 0]

flatMap(...).reversed и flatten().reversed читают внешние последовательности с конца, а каждую внутреннюю тоже с конца. Внутренняя последовательность должна уметь так читаться. Set и Map внутри выбрасывают Cannot walk backwards:

[
  ...intoIter([
    [1, 2],
    [3, 4],
  ]).flatten().reversed,
]; // [4, 3, 2, 1]

[...intoIter([1, 2]).flatMap((n) => new Set([n])).reversed]; // Error: Cannot walk backwards

Сборка результата

collect, toArray, toSet и toMap читают цепочку сразу. До их вызова она остаётся ленивой. Подключаются импортом into-iter/collect.

collect(target)

Заполняет переданную коллекцию. Для массива, Set и Map возвращает её же.

const numbers = intoIter([1, 2, 3]).map((n) => n * 10);

numbers.collect([]); // [10, 20, 30]
numbers.collect(new Set()); // Set { 10, 20, 30 }
intoIter([
  ["a", 1],
  ["b", 2],
] as [string, number][]).collect(new Map()); // Map { "a" => 1, "b" => 2 }

В массив элементы добавляются через push, в Set через add. В Map попадают пары [key, value]: повторный ключ перезаписывает значение. Уже лежащие в коллекции элементы не стираются.

Свой тип подключается символом collector. Символ и типы Collector и Collectable импортируются из into-iter/collector: этот модуль ничего не добавляет на IntoIter. Метод [collector] возвращает объект с add и finish. collect вызывает finish один раз после всех элементов и возвращает его результат:

import "into-iter/collect";
import { collector, type Collectable, type Collector } from "into-iter/collector";

const joined: Collectable<number, string> = {
  [collector](): Collector<number, string> {
    const items: number[] = [];
    return {
      add(value) {
        items.push(value);
      },
      finish() {
        return items.join(",");
      },
    };
  },
};

intoIter([1, 2, 3]).collect(joined); // "1,2,3"

toArray(), toSet(), toMap()

Короткие вызовы collect с новой пустой коллекцией. toMap доступен, когда элементы — пары [key, value].

intoIter([1, 2, 2, 3]).toArray(); // [1, 2, 2, 3]
intoIter([1, 2, 2, 3]).toSet(); // Set { 1, 2, 3 }
intoIter([
  ["a", 1],
  ["b", 2],
] as [string, number][]).toMap(); // Map { "a" => 1, "b" => 2 }

Числовые агрегаты

sum, product, avg, min и max читают цепочку сразу. До их вызова она остаётся ленивой. Подключаются импортом into-iter/math. Методы есть у последовательности чисел и у последовательности bigint. Смешивать эти типы в одной последовательности нельзя.

const numbers = intoIter([1, 2, 3, 4]);

numbers.sum(); // 10
numbers.product(); // 24
numbers.avg(); // 2.5
numbers.min(); // 1
numbers.max(); // 4

Пустая числовая последовательность: sum возвращает 0, product — 1, avg — NaN, min и max — undefined.

bigint считается отдельно. avg делит нацело, к нулю:

intoIter([1n, 2n, 3n]).sum(); // 6n
intoIter([1n, 2n, 3n]).product(); // 6n
intoIter([1n, 2n, 3n]).avg(); // 2n
intoIter([1n, 2n]).avg(); // 1n
intoIter([3n, 1n, 2n]).min(); // 1n
intoIter([3n, 1n, 2n]).max(); // 3n

Пустой bigint-итератор в рантайме не отличить от пустого числового, поэтому sum и product на нём возвращают 0 и 1, а avg — NaN. min и max и здесь возвращают undefined.

Свёртка

reduce, fold и foldRight читают цепочку сразу. До их вызова она остаётся ленивой. reduce подключается импортом into-iter/reduce, fold и foldRight — импортом into-iter/fold.

reduce(fn)

Сворачивает последовательность в значение того же типа. Первый элемент становится аккумулятором, и для него fn не вызывается. Пустая последовательность возвращает undefined, один элемент возвращается как есть.

intoIter([1, 2, 3, 4]).reduce((acc, n) => acc - n); // -8
intoIter([7]).reduce((acc, n) => acc + n); // 7
intoIter<number>([]).reduce((acc, n) => acc + n); // undefined

reversed меняет, какой элемент считается первым:

intoIter([1, 2, 3, 4]).reversed.reduce((acc, n) => acc - n); // -2

fold(init, fn)

Начинает с переданного значения и вызывает fn для каждого элемента, включая первый. Пустая последовательность возвращает init. Тип аккумулятора может отличаться от типа элементов.

intoIter([1, 2, 3]).fold(10, (acc, n) => acc + n); // 16
intoIter<number>([]).fold(10, (acc, n) => acc + n); // 10
intoIter([1, 2, 3]).fold("", (acc, n) => acc + n); // "123"
intoIter([1, 2, 3]).reversed.fold("", (acc, n) => acc + n); // "321"

foldRight(init, fn)

Та же свёртка с конца. Источник должен уметь читаться назад, иначе вызов выбрасывает Error("Cannot walk backwards").

intoIter([1, 2, 3]).foldRight("", (acc, n) => acc + n); // "321"
intoIter([1, 2, 3]).reversed.foldRight("", (acc, n) => acc + n); // "123"
intoIter(new Set([1, 2, 3])).foldRight(0, (acc, n) => acc + n); // Error: Cannot walk backwards

Поиск

every, some, find, findMap, position и findLast читают цепочку сразу и останавливаются, как только ответ уже известен. До вызова цепочка остаётся ленивой.

every и some подключаются импортом into-iter/every. find, findMap, position и findLast — импортом into-iter/find.

every(fn) и some(fn)

every возвращает true, пока предикат истинен для каждого элемента, и останавливается на первом false. Пустая последовательность даёт true. some останавливается на первом true. Пустая последовательность даёт false.

intoIter([1, 2, 3, 4]).every((n) => n < 3); // false
intoIter([1, 2, 3, 4]).some((n) => n > 2); // true
intoIter<number>([]).every((n) => n > 0); // true
intoIter<number>([]).some((n) => n > 0); // false

find(fn), findMap(fn), position(fn), findLast(fn)

find возвращает первый подходящий элемент, иначе undefined. 0, false, "" и null остаются, если предикат их выбрал.

findMap пропускает null и undefined, которые вернула функция, и сразу отдаёт первое другое значение.

position возвращает индекс первого совпадения в текущем направлении, с нуля. После reversed счёт идёт с конца, после filter — по уже отфильтрованной последовательности.

findLast ищет с конца. Если источник умеет читаться назад, чтение останавливается на первом совпадении с конца. Set и генератор читаются с начала, и остаётся последнее совпадение.

intoIter([1, 2, 3, 4]).find((n) => n > 2); // 3
intoIter([1, 2, 3]).findMap((n) => (n === 2 ? undefined : n * 10)); // 10
intoIter([1, 2, 3, 4]).position((n) => n > 2); // 2
intoIter([1, 2, 3, 4]).reversed.position((n) => n === 2); // 2
intoIter([1, 2, 3, 4]).findLast((n) => n < 4); // 3
intoIter(new Set([1, 2, 3, 4])).findLast((n) => n % 2 === 0); // 4

Доступ по индексу

first, last, nth и nthBack подключаются импортом into-iter/nth. Индекс должен быть неотрицательным целым числом, иначе методы выбрасывают TypeError("Nth must be a non-negative integer").

nth(n) пропускает n элементов и возвращает следующий. Дальше источник не читается. first() — это nth(0). Если элементов меньше, результат undefined.

nthBack(n) считает с конца. У массива, строки и диапазона для этого хватает шагов назад. У Set и генератора метод один раз проходит последовательность с начала. last() — это nthBack(0).

intoIter([1, 2, 3, 4, 5]).nth(2); // 3
intoIter([1, 2, 3, 4, 5]).first(); // 1
intoIter([1, 2, 3, 4, 5]).nthBack(1); // 4
intoIter([1, 2, 3, 4, 5]).last(); // 5
intoIter(new Set([1, 2, 3, 4, 5])).nthBack(1); // 4
intoIter<number>([]).first(); // undefined
intoIter([1]).nth(-1); // TypeError: Nth must be a non-negative integer