it-al

It-al

A TypeScript iterable utility library providing functional programming utilities for working with iterables as well as a class based interface with an easy chainable and typed API.

Installation

npm install it-al

Features

• 🔄 Lazy Evaluation - Iterator-based operations are efficient and composable
• 🍛 Currying Support - Most functions support both direct and curried forms
• 🔗 Method Chaining - Fluent API via Iter and PeekableIter classes
• 🏷️ Type Safe - Full TypeScript support with proper type inference
• 🧩 Functional - Supports composition via pipe and apply

Quick Start

import { Iter, map, filter, take } from 'it-al';

// Functional style
const result = pipe([
  map((x: number) => x * 2),
  filter((x: number) => x > 5),
  take(3)
])([1, 2, 3, 4, 5, 6]);

// Method chaining style
const result2 = Iter.from([1, 2, 3, 4, 5, 6])
  .map(x => x * 2)
  .filter(x => x > 5)
  .take(3)
  .toArray();

API Reference

Transformation Functions

Function	Description	Signature
map	Transform each item in an iterable	<T, U>(iter: Iterable<T>, fn: IterFn<T, U>) => IterableIterator<U>
filter	Filter items based on a predicate	<T>(iter: Iterable<T>, fn: IterFn<T>) => IterableIterator<T>
flat	Flatten nested iterables by depth	<T, D>(iter: Iterable<T>, depth?: D) => IterableIterator<FlatItem<T, D>>
enumerate	Return index-value pairs	<T>(iter: Iterable<T>) => IterableIterator<[number, T]>
pluck	Extract a property from each item	<T, K>(iter: Iterable<T>, key: K) => IterableIterator<T[K]>
tap	Run side effects without modifying items	<T>(iter: Iterable<T>, fn: IterFn<T>) => IterableIterator<T>
scan	Like reduce but yields intermediate values	<T, U>(iter: Iterable<T>, fn, start?: U) => IterableIterator<U>

Slicing & Limiting

Function	Description	Signature
take	Take first n items	<T>(iter: Iterable<T>, n: number) => IterableIterator<T>
skip	Skip first n items	<T>(iter: Iterable<T>, n: number) => IterableIterator<T>
takeWhile	Take items while predicate is true	<T>(iter: Iterable<T>, fn: IterFn<T>) => IterableIterator<T>
skipWhile	Skip items while predicate is true	<T>(iter: Iterable<T>, fn: IterFn<T>) => IterableIterator<T>
until	Take items until predicate is true	<T>(iter: Iterable<T>, fn: IterFn<T>) => IterableIterator<T>
chunk	Split into chunks of size n	<T>(iter: Iterable<T>, n: number) => IterableIterator<T[]>
windows	Create sliding windows of size n	<T>(iter: Iterable<T>, n: number) => IterableIterator<T[]>

Aggregation & Reduction

Function	Description	Signature
reduce	Reduce to a single value	<T, U>(iter: Iterable<T>, fn, start: U) => U
sum	Sum all numbers	(iter: Iterable<number>) => number
product	Multiply all numbers	(iter: Iterable<number>) => number
average	Average all numbers	(iter: Iterable<number>) => number
count	Count items	<T>(iter: Iterable<T>) => number
join	Join items into string	<T>(iter: Iterable<T>, delimiter?: string) => string
groupBy	Group items by key	<T, U>(iter: Iterable<T>, fn) => Map<U, T[]>

Searching & Testing

Function	Description	Signature
find	Find first matching item	<T>(iter: Iterable<T>, fn: IterFn<T>) => T | null
findIndex	Find index of first match	<T>(iter: Iterable<T>, fn: IterFn<T>) => number
includes	Check if value exists	<T>(iter: Iterable<T>, value: T) => boolean
some	Test if any item matches	<T>(iter: Iterable<T>, fn: IterFn<T>) => boolean
every	Test if all items match	<T>(iter: Iterable<T>, fn: IterFn<T>) => boolean
first	Get first item	<T>(iter: Iterable<T>) => T
last	Get last item	<T>(iter: Iterable<T>) => T | undefined
isEmpty	Check if empty	(iter: Iterable<unknown>) => boolean
search	Recursively search object	<U>(obj: unknown, fn) => IterableIterator<KeyValuePair<U>>

Uniqueness & Filtering

Function	Description	Signature
uniqueBy	Get unique items by selector	<T>(iter: Iterable<T>, fn: IterFn<T>) => IterableIterator<T>
partition	Split into passed/failed arrays	<T>(iter: Iterable<T>, fn: IterFn<T>) => [T[], T[]]

Combining & Zipping

Function	Description	Signature
zip	Combine multiple iterables	<I>(...iters: I, stopOnMin?: boolean) => ZipOutput<I>
unzip	Transpose iterable of arrays	<T>(iter: Iterable<T>) => UnzipOutput<T>

Generation & Repetition

Function	Description	Signature
range	Generate range of numbers	(stop: number, start?: number, step?: number) => IterableIterator<number>
repeat	Repeat iterable n times	<T>(iter: Iterable<T>, n: number) => IterableIterator<T>
cycle	Cycle through iterable infinitely	<T>(iter: Iterable<T>) => IterableIterator<T>
gen	Create infinite generator	<T>(fn: (n: number) => T) => () => IterableIterator<T>

Object/Entry Operations

Function	Description	Signature
entries	Get key-value pairs	<T>(input: T) => IterableIterator<Entry<T>>
allEntries	Get entries including Symbols	<T>(input: T) => IterableIterator<Entry<T>>
fromEntries	Create object from entries	<K, V>(iter: Iterable<[K, V]>) => Record<K, V>

Utilities

Function	Description	Signature
pipe	Compose functions left-to-right	<I, O>(fns: Function[]) => (item: I) => O
apply	Apply functions in order	<I, O>(input: I, fns: Function[]) => O
peekable	Create peekable iterable	<T>(iter: Iterable<T>) => Peekable<T>
isIterable	Check if value is iterable	<T>(x: unknown) => x is Iterable<T>
isNonStringIterable	Check iterable (not string)	<T>(x: unknown) => x is Iterable<T>
isAsyncIterable	Check if async iterable	<T>(x: unknown) => x is AsyncIterable<T>

Class-Based API

Iter<T>

Chainable wrapper around iterables providing a fluent API.

Static Methods

Method	Description	Return Type
Iter#from(iterable)	Create an Iter from any iterable	Iter<T>
Iter#safeFrom(maybeIterable?)	Create an Iter from unknown input, returns empty Iter if not iterable	Iter<T>
Iter#fromAsync(iterable)	Create an Iter from async iterable or promises	Iter<T>
Iter#fromEntries(obj)	Create an Iter from object entries	Iter<[K, V]>
Iter#safeFromEntries(obj?)	Create an Iter from object entries, returns empty Iter if null/undefined	Iter<[K, V]>
Iter#fromRange(stop, start?, step?)	Create an Iter from a numeric range	Iter<number>
Iter#gen(fn)	Create infinite Iter using generator function	() => Iter<T>
Iter#zip(iterables, stopOnMin?)	Zip multiple iterables into tuples	Iter<[...]>
Iter#search(obj, fn, skipAfterYield?)	Recursively search object for matching values	Iter<KeyValuePair<U>>

Chainable Methods

Returns a new Iter<T> instance for continued chaining.

Method	Description
Iter#flatMap(fn)	Map and flatten in one step
Iter#flat(depth?)	Flatten nested iterables
Iter#map(fn)	Transform each item
Iter#filter(fn)	Filter items by predicate
Iter#filterNullish()	Remove null and undefined values
Iter#unique()	Remove duplicate values
Iter#enumerate()	Add index to each item as [index, value]
Iter#uniqueBy(fn)	Remove duplicates by selector function
Iter#tap(fn)	Run side effects without modifying items
Iter#scan(fn, start?)	Like reduce but yields intermediate values
Iter#pluck(key)	Extract property from each item
Iter#take(n)	Take first n items
Iter#chunk(n)	Split into chunks of size n
Iter#skip(n)	Skip first n items
Iter#takeWhile(fn)	Take items while predicate is true
Iter#skipWhile(fn)	Skip items while predicate is true
Iter#until(fn)	Take items until predicate is true
Iter#windows(size)	Create sliding windows of size n
Iter#apply(fn)	Apply a function to the iterable
Iter#peekable()	Convert to PeekableIter
Iter#repeat(times)	Repeat the iterable n times
Iter#cycle()	Cycle through iterable infinitely

Terminal Methods

Consumes the iterator and returns a final value.

Method	Description	Return Type
Iter#first()	Get the first item	T
Iter#last()	Get the last item	T | undefined
Iter#find(fn)	Find first item matching predicate	T | null
Iter#findIndex(fn)	Find index of first match	number
Iter#includes(value)	Check if value exists	boolean
Iter#count()	Count total items	number
Iter#isEmpty()	Check if iterable is empty	boolean
Iter#forEach(fn)	Like Array.forEach but for Iter	void
Iter#reduce(fn, start)	Reduce to single value	U
Iter#every(fn)	Test if all items match predicate	boolean
Iter#some(fn)	Test if any item matches predicate	boolean
Iter#unzip()	Transpose iterable of arrays	UnzipOutput<T>
Iter#partition(fn)	Split into [passed, failed] arrays	[T[], T[]]
Iter#join(delimiter?)	Join items into string	string
Iter#groupBy(fn)	Group items by key	Map<K, T[]>
Iter#sum()	Sum all numbers	number
Iter#product()	Multiply all numbers	number
Iter#average()	Average all numbers	number
Iter#min()	Find minimum value	T
Iter#max()	Find maximum value	T
Iter#collect(collector?)	Collect using custom collector	U
Iter#toArray()	Collect all items into an array	T[]
Iter#toSet()	Collect all items into a Set	Set<T>
Iter#toMap()	Collect entries into a Map	Map<K, V>

PeekableIter<T>

Extends Iter<T> with the ability to peek at the next value without consuming it.

const iter = PeekableIter.from([1, 2, 3]);
console.log(iter.peek()); // 1 (doesn't consume)
console.log(iter.first()); // 1 (consumes)

Additional Method

Method	Description	Return Type
PeekableIter#peek()	Look at next value without consuming it	T | undefined

Examples

Currying

import { map, filter, pipe } from 'it-al';

// Curried form
const double = map((x: number) => x * 2);
const isPowerOfTwo = filter((x: number) => Math.sqrt(x, 2) % 1 === 0);

const result = pipe([double, isPowerOfTwo])([1, 2, 3, 4]);
// [2, 4, 8]

Method Chaining

import { Iter } from 'it-al';

const result = Iter.from([1, 2, 3, 4, 5])
  .map(x => x * 2)
  .filter(x => x > 5)
  .take(2)
  .toArray();
// [6, 8]

Lazy Evaluation

import { map, take } from 'it-al';

const expensive = map((x: number) => {
  console.log('Processing:', x);
  return x * 2;
});

// Only processes first 3 items
const result = take(expensive([1, 2, 3, 4, 5, 6, 7, 8]), 3);

for (const _ of result) {}
// Logs: Processing: 1, 2, 3

Working with Infinite Iterators

import { Iter } from 'it-al';

// Generate infinite sequence
const randomNumbers = Iter.gen((n) => Math.random());

// Generates 10 random numbers
const first10 = fibonacci().take(10).toArray();

Grouping and Aggregation

import { Iter } from 'it-al';

const data = [
  { category: 'A', value: 10 },
  { category: 'B', value: 20 },
  { category: 'A', value: 30 },
];

const grouped = Iter.from(data).groupBy(item => item.category);
// Map { 'A' => [{...}, {...}], 'B' => [{...}] }