iterational

Rational, semantic functions for common Node.js iteration patterns.

This package explores a structured approach to iteration, aiming to express intent clearly and to reduce refactoring friction.

Reasoning

This stems from a philosophical perspective on Node.js iteration patterns: different styles often lead to inconsistent bracket nesting, making refactoring require structural changes. Additionally, the intended iteration behavior is not always immediately clear.

iterational solves this by:

• Making iteration intent explicit – Sync, sequential async, or parallel async.
• Allowing easy experimentation – Swap iteration modes just by changing the function name.
• Reducing syntax friction – Avoid deep nesting when working with async loops.

🔍 Standard vs. iterational Approach

Example of Standard Iterations Patterns

// Original (Sync)
items.forEach((item) => {
    //Process item here;
});

// Refactor to Sequential Async
for (const item of items) {
    await //Process item here;
}

// Refactor to Parallel Async
await Promise.all(items.map(async (item) => {
    await //Process item here;
}));

Iterationals Patterns

import { sync, seq, parallel } from 'iterational';

// Sync
sync(items, (item) => {
    //Process item here.
});

// Sequential Async
await seq(items, async (item) => {
    //Process item here.
});

// Parallel Async
await parallel(items, async (item) => {
    //Process item here.
});

Developer intent is clear from the function name, and switching between modes requires only changing the function—no structural refactoring needed.

Install

npm install iterational

API

sync( array, ( item ) => {...} )

Equivalent to .forEach().

seq( items, async ( item ) => {...})

Awaits each callback in order.

parallel(array, async ( item ) => {...})

Executes all async operations concurrently

Links

Development Homepage:

https://github.com/alexstevovich/iterational

This link might become iterational-node in the future if conflicts arise.

License

Licensed under the Apache License 2.0.