# ts-iterable-functions

[![npm](https://img.shields.io/npm/v/ts-iterable-functions.svg?style=flat)](https://npmjs.org/package/ts-iterable-functions "View this project on npm")
[![build](https://github.com/biggyspender/ts-iterable-functions/actions/workflows/ts-iterable-functions.yml/badge.svg?branch=master)](https://github.com/biggyspender/ts-iterable-functions/actions/workflows/ts-iterable-functions.yml)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue?logo=typescript)](https://www.typescriptlang.org/)
[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](#)
[![Bundle Size](https://img.shields.io/bundlephobia/minzip/ts-iterable-functions)](https://bundlephobia.com/package/ts-iterable-functions)

> Type-safe, LINQ-inspired iterable utilities for TypeScript and JavaScript, built for fluent composition and modern functional pipelines.

## Highlights

- **Composable by default** – every operator ships in source-first and pipe-first forms so you can pivot between array-style calls and unary pipelines without adapters.
- **Zero-dependency core** – tiny footprint with native ESM and CJS bundles generated by esbuild for fast installs and rapid builds.
- **End-to-end type safety** – aggressive generics keep key selectors, reducers, and joins fully inferred across long pipelines.
- **Drop-in LINQ ergonomics** – familiar primitives like [map](https://biggyspender.github.io/ts-iterable-functions/functions/map.html), [groupBy](https://biggyspender.github.io/ts-iterable-functions/functions/groupBy.html), [orderBy](https://biggyspender.github.io/ts-iterable-functions/functions/orderBy.html), and [zip](https://biggyspender.github.io/ts-iterable-functions/functions/zip.html) behave the way seasoned C# and F# developers expect.
- **Pipe-friendly ecosystem** – pairs naturally with [ts-functional-pipe](https://www.npmjs.com/package/ts-functional-pipe) and other unary-first composition helpers.

<!-- <p align="center">
  <img src="https://placehold.co/720x160?text=Compose+Iterables+Beautifully" alt="ts-iterable-functions hero"/>
</p> -->

## Quick start

**Install**

```sh
npm install ts-iterable-functions ts-functional-pipe ts-equality-comparer ts-comparer-builder
```

**Compose a strongly typed pipeline**

```typescript
import { pipeInto } from "ts-functional-pipe";
import { map, orderBy, thenBy, toArray } from "ts-iterable-functions";

const cars = [
  { manufacturer: "Ford", model: "Escort" },
  { manufacturer: "Ford", model: "Cortina" },
  { manufacturer: "Renault", model: "Clio" },
  { manufacturer: "Vauxhall", model: "Corsa" },
  { manufacturer: "Ford", model: "Fiesta" },
  { manufacturer: "Fiat", model: "500" },
];

const orderedCars = pipeInto(
  cars,
  orderBy((c) => c.manufacturer),
  thenBy((c) => c.model),
  toArray()
);

console.log(orderedCars);
// → deterministically ordered list with full type inference at every hop
```

## Works great for

- Data transformation pipelines in backends or frontends
- Analytics dashboards and reporting utilities
- Lightweight ETL tasks without pulling in stream frameworks
- Crafting reusable collection helpers for design systems and SDKs
- Replacing brittle nested loops with readable, testable pipelines

## Pipe-first or source-first—your call

Every transformer is available as `_operator(source, ...args)` and `operator(...args)(source)`.

```typescript
import { _map, map, toArray } from "ts-iterable-functions";
import { pipeInto } from "ts-functional-pipe";

const numbers = [1, 2, 3];

const doubledLegacy = _map(numbers, (value) => value * 2);
const doubledPipeline = pipeInto(numbers, map((value) => value * 2), toArray());
```

Switching between forms keeps refactors painless while preserving full generic inference.

## Core building blocks

- **Generators** – [range](https://biggyspender.github.io/ts-iterable-functions/functions/range.html), [repeat](https://biggyspender.github.io/ts-iterable-functions/functions/repeat.html), [repeatGenerate](https://biggyspender.github.io/ts-iterable-functions/functions/repeatGenerate.html), [fromSingleValue](https://biggyspender.github.io/ts-iterable-functions/functions/fromSingleValue.html)
- **Transformers** – [aggregate](https://biggyspender.github.io/ts-iterable-functions/functions/aggregate.html), [concat](https://biggyspender.github.io/ts-iterable-functions/functions/concat.html), [distinctBy](https://biggyspender.github.io/ts-iterable-functions/functions/distinctBy.html), [groupBy](https://biggyspender.github.io/ts-iterable-functions/functions/groupBy.html), [intersect](https://biggyspender.github.io/ts-iterable-functions/functions/intersect.html), [orderBy](https://biggyspender.github.io/ts-iterable-functions/functions/orderBy.html), [selectMany](https://biggyspender.github.io/ts-iterable-functions/functions/selectMany.html), [union](https://biggyspender.github.io/ts-iterable-functions/functions/union.html), [zip](https://biggyspender.github.io/ts-iterable-functions/functions/zip.html), and dozens more
- **Aggregations** – [average](https://biggyspender.github.io/ts-iterable-functions/functions/average.html), [count](https://biggyspender.github.io/ts-iterable-functions/functions/count.html), [maxBy](https://biggyspender.github.io/ts-iterable-functions/functions/maxBy.html), [minBy](https://biggyspender.github.io/ts-iterable-functions/functions/minBy.html), [sum](https://biggyspender.github.io/ts-iterable-functions/functions/sum.html)
- **Materializers** – [toArray](https://biggyspender.github.io/ts-iterable-functions/functions/toArray.html), [toLookup](https://biggyspender.github.io/ts-iterable-functions/functions/toLookup.html), [toMap](https://biggyspender.github.io/ts-iterable-functions/functions/toMap.html), [toSet](https://biggyspender.github.io/ts-iterable-functions/functions/toSet.html)

Browse the full API reference in the [online docs](https://biggyspender.github.io/ts-iterable-functions/modules.html) for detailed signatures and examples.

## Plays nicely with ts-functional-pipe

- Leverages `pipe`, `pipeInto`, and `compose` while preserving discriminated unions and narrowed types
- Ships lightweight helpers like [indexed](https://biggyspender.github.io/ts-iterable-functions/functions/indexed.html), [groupAdjacent](https://biggyspender.github.io/ts-iterable-functions/functions/groupAdjacent.html), and [fullOuterJoin](https://biggyspender.github.io/ts-iterable-functions/functions/fullOuterJoin.html) that plug directly into unary pipelines

## Learn more

- Read the full documentation: [biggyspender.github.io/ts-iterable-functions](https://biggyspender.github.io/ts-iterable-functions/)
- Explore class definitions and helpers: [Docs hierarchy](https://biggyspender.github.io/ts-iterable-functions/hierarchy.html)
- Generated API listings for every operator: [Docs functions/_map](https://biggyspender.github.io/ts-iterable-functions/functions/_map.html)

> Heads up: versions 5.x and later are bundled with [esbuild](https://esbuild.github.io/) and drop IE11 support.

## 🤝 Contributing and community

We welcome issues, feature ideas, and pull requests. Start a conversation in [issues](https://github.com/biggyspender/ts-iterable-functions/issues) or [discussions](https://github.com/biggyspender/ts-iterable-functions/discussions), and check [CONTRIBUTING.md](CONTRIBUTING.md) before raising a PR.