Beautiful Iterator

A powerful, type-safe, and highly extensible iterator library for TypeScript/JavaScript, supporting both synchronous and asynchronous processing with dedicated sequential and parallel modes.

Key Features

• Type-Safe: Built with TypeScript from the ground up.
• Synchronous & Asynchronous: Seamlessly switch between sync and async streams.
• Parallel Mode: Process async operations concurrently for better performance.
• Rich API: Inspired by Java Streams and Rust Iterators (map, filter, reduce, flatmap, zip, etc.).
• Sentinel-Based: Uses a unique NONE symbol instead of null, allowing null values as valid data.

Installation

npm install beautiful-iterator

Usage Examples

Synchronous Chaining

import { range } from 'beautiful-iterator';

const result = range(1, 100)
    .filter(n => n % 3 === 0)
    .map(n => `Number: ${n}`)
    .toArray();

console.log(result);

Parallel Async Processing

import { fromIterable } from 'beautiful-iterator';

const urls = ['https://api.example.com/1', 'https://api.example.com/2'];

await fromIterable(urls)
    .toAsync()
    .parallel()
    .forEachAsync(async (url) => {
        await fetch(url);
    });

Internal Mechanisms

The NONE Sentinel

Most iterator implementations use null or { done: true } to signal the end of a stream. This library uses a unique Symbol("NONE"). This allows you to process streams that contain null values as actual data without the iterator stopping prematurely.

Mode Transitions

When calling .toAsync(), the synchronous iterator is wrapped in a SequentialAsyncIterator.

• Sequential Mode (Default): Pulls and processes each element one by one. Ideal when order is critical or when resources are limited.
• Parallel Mode: Switched via .parallel(). Terminal operations pull elements in batches concurrently. This allows mapAsync, filterAsync, and other async intermediate steps to run in parallel.

License

MIT