@osmium/iterate

A powerful, type-safe iteration library for JavaScript and TypeScript that provides unified iteration over various data types with advanced mapping, parallel processing, and control flow features.

✨ Features

• 🔄 Universal Iteration - Iterate over arrays, objects, sets, maps, strings, numbers, and more
• ⚡ Async/Sync Support - Full support for both synchronous and asynchronous operations
• 🚀 Parallel Processing - Built-in parallel iteration with configurable limits
• 🎯 Type Safety - Full TypeScript support with advanced type inference
• 🛠️ Advanced Mapping - Transform data while iterating with various mapping strategies
• 🎮 Flow Control - Break, skip, repeat, and shift operations during iteration
• 📦 Zero Dependencies - Lightweight and self-contained
• 🧪 Well Tested - 99.24% test coverage with 331+ tests

📦 Installation

npm install @osmium/iterate

yarn add @osmium/iterate

pnpm add @osmium/iterate

🚀 Quick Start

import {iterateSync, iterateAsync, iterateParallel} from '@osmium/iterate';

// Synchronous iteration
iterateSync([1, 2, 3], (value, index) => {
	console.log(`Item ${index}: ${value}`);
});

// Asynchronous iteration
await iterateAsync([1, 2, 3], async (value, index) => {
	const result = await processAsync(value);
	console.log(`Processed ${index}: ${result}`);
});

// Parallel processing
await iterateParallel([1, 2, 3], async (value) => {
	return await heavyComputation(value);
});

📚 Supported Data Types

| Type | Example | Description | |--------------|-----------------------|-------------------------------------| | Array | [1, 2, 3] | Iterate over array elements | | Object | {a: 1, b: 2} | Iterate over object key-value pairs | | Set | new Set([1, 2, 3]) | Iterate over set values | | Map | new Map([['a', 1]]) | Iterate over map entries | | String | "hello" | Iterate over each character | | Number | 5 | Iterate N times (0 to N-1) | | Boolean | true | Infinite iteration until break | | Iterable | Custom iterables | Any object with Symbol.iterator |

🎯 Core Functions

iterateSync(values, callback, map?, mapUndefined?)

Synchronous iteration over any iterable data type.

// Basic iteration
iterateSync([1, 2, 3], (value, index, control) => {
	console.log(`${index}: ${value}`);
});

// With mapping to array
const doubled = iterateSync([1, 2, 3], (value) => value * 2, []);
// Result: [2, 4, 6]

// With flow control
iterateSync([1, 2, 3, 4, 5], (value, index, control) => {
	if (value === 3) control.break();
	console.log(value);
});
// Output: 1, 2

iterateAsync(values, callback, map?, mapUndefined?)

Asynchronous iteration with Promise support.

// Async iteration
await iterateAsync([1, 2, 3], async (value, index) => {
	const result = await fetch(`/api/data/${value}`);
	return await result.json();
});

// With async mapping
const results = await iterateAsync(
	['file1.txt', 'file2.txt'],
	async (filename) => await readFile(filename),
	[]
);

iterateParallel(values, callback, map?, mapUndefined?)

Parallel execution of async callbacks (like Promise.all).

// Process all items in parallel
const results = await iterateParallel(
	[1, 2, 3, 4, 5],
	async (value) => {
		await delay(1000); // All delays happen in parallel
		return value * 2;
	},
	[]
);
// Completes in ~1 second instead of ~5 seconds

iterateParallelLimit(limit, values, callback)

Parallel execution with concurrency limit.

// Process max 2 items at a time
await iterateParallelLimit(2, urls, async (url) => {
	return await fetch(url);
});

🗝️ Key-First Iteration

All functions have "Keys" variants that pass the index/key as the first parameter:

// Regular: (value, index, control)
iterateSync({a: 1, b: 2}, (value, key) => {
	console.log(`${key} = ${value}`);
});

// Keys variant: (key, value, control)
iterateKeysSync({a: 1, b: 2}, (key, value) => {
	console.log(`${key} = ${value}`);
});

Available functions:

• iterateKeysSync / iterateKeysAsync
• iterateKeys (auto-detect sync/async)
• iterateKeysParallel

🎮 Flow Control

The control parameter provides powerful flow control options:

iterateSync([1, 2, 3, 4, 5], (value, index, control) => {
	// Skip current iteration
	if (value === 2) {
		control.skip();
		return;
	}

	// Repeat current iteration
	if (value === 3 && !repeated) {
		repeated = true;
		control.repeat();
		return;
	}

	// Break out of loop
	if (value === 4) {
		control.break();
		return;
	}

	// Shift position
	control.shift(1); // Move forward by 1

	console.log(value);
});

Control Methods

| Method | Description | |-----------------------|--------------------------------| | control.break() | Exit the iteration immediately | | control.skip() | Skip to next iteration | | control.repeat() | Repeat current iteration | | control.shift(n) | Move position by n steps | | control.key(newKey) | Set custom mapping key | | control.length | Get total length of iterable |

🗺️ Mapping Strategies

Array Mapping

const doubled = iterateSync([1, 2, 3], (x) => x * 2, []);
// Result: [2, 4, 6]

Object Mapping

const mapped = iterateSync(
	{a: 1, b: 2},
	(value, key) => value * 2,
	{}
);
// Result: {a: 2, b: 4}

Set Mapping

const uniqueDoubled = iterateSync([1, 2, 2, 3], (x) => x * 2, new Set());
// Result: Set {2, 4, 6}

Map Mapping

const keyValueMap = iterateSync(
	['a', 'b', 'c'],
	(value, index) => value.toUpperCase(),
	new Map()
);
// Result: Map {'a' => 'A', 'b' => 'B', 'c' => 'C'}

Number Mapping (Counter)

const count = iterateSync([1, 2, undefined, 3], (x) => x, 0);
// Result: 3 (counts non-undefined returns)

Boolean Mapping (Flag)

const hasEven = iterateSync([1, 3, 4, 5], (x) => x % 2 === 0, false);
// Result: true (flips to true when callback returns truthy)

🔧 Advanced Examples

Processing Files in Batches

import {iterateParallelLimit} from '@osmium/iterate';

const files = ['file1.txt', 'file2.txt', /* ... many files ... */];

// Process max 3 files at a time
await iterateParallelLimit(3, files, async (filename) => {
	const content = await fs.readFile(filename, 'utf8');
	const processed = await processContent(content);
	await fs.writeFile(filename.replace('.txt', '.processed.txt'), processed);
});

Data Transformation Pipeline

const data = [
	{id: 1, name: 'John', age: 25},
	{id: 2, name: 'Jane', age: 30},
	{id: 3, name: 'Bob', age: 35}
];

// Transform to Map with custom keys
const userMap = iterateSync(
	data,
	(user, index, control) => {
		control.key(`user_${user.id}`);
		return {
			...user,
			isAdult: user.age >= 18
		};
	},
	new Map()
);

Infinite Iteration with Break Condition

let counter = 0;
iterateSync(true, (value, index, control) => {
	counter++;
	console.log(`Iteration ${counter}`);

	if (counter >= 10) {
		control.break();
	}
});

Error Handling in Async Iteration

const results = await iterateAsync(
	urls,
	async (url, index) => {
		try {
			const response = await fetch(url);
			return await response.json();
		} catch (error) {
			console.error(`Failed to fetch ${url}:`, error);
			return null; // Continue with other URLs
		}
	},
	[]
);

🔍 Utility Functions

seriesPageableRange(start, end, pageSize)

Generate paginated ranges for batch processing:

import {seriesPageableRange} from '@osmium/iterate';

const ranges = seriesPageableRange(0, 100, 10);
// Result: [[0, 9], [10, 19], [20, 29], ..., [90, 99]]

// Use with parallel processing
await iterateParallel(ranges, async ([start, end]) => {
	return await processRange(start, end);
});

📝 TypeScript Support

Full TypeScript support with advanced type inference:

// Type inference works automatically
const numbers: number[] = [1, 2, 3];
const doubled = iterateSync(numbers, (x) => x * 2, []); // Type: number[]

// Custom types
interface User {
	id: number;
	name: string;
}

const users: User[] = [{id: 1, name: 'John'}];
const userNames = iterateSync(users, (user) => user.name, []); // Type: string[]

⚡ Performance

• Synchronous operations: Optimized for minimal overhead
• Parallel processing: Efficient batching and concurrency control
• Memory efficient: Streaming-style processing for large datasets
• Type safety: Zero runtime type checking overhead

🧪 Testing

The library has extensive test coverage (99.24%) with 331+ tests covering:

• All data types and edge cases
• Async/sync operations
• Parallel processing
• Error handling
• Type system validation
• Performance scenarios

Run tests:

npm test

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

📞 Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Made with ❤️ by Vasiliy Isaichkin