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?.(); // 5intoIter([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 backwardslimit и reversed вместе
Результат зависит от порядка:
[...range(10).limit(3).reversed]; // [2, 1, 0] — первые 3, с конца
[...range(10).reversed.limit(3)]; // [9, 8, 7] — последние 3reversed.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 backwardsskip вместе с 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); // undefinedreversed меняет, какой элемент считается первым:
intoIter([1, 2, 3, 4]).reversed.reduce((acc, n) => acc - n); // -2fold(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); // falsefind(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