ForPromise-JS is a lightweight utility for running asynchronous scripts in sequence — like a for
, forEach
, or while
loop — but fully promise-based and with complete control over each iteration.
This module helps you run multiple asynchronous operations (Promises or callbacks) in an ordered, controlled flow within a single await
call.
Instead of juggling multiple Promise
instances inside regular loop structures (which can get messy or execute out of order), ForPromise-JS executes them sequentially, instantly, and cleanly — all inside one master Promise
.
- Works with arrays, objects, numbers, and custom
while
conditions. - Supports
fn()
andfn_error()
callbacks. - Allows
break
,forceResult
,dontSendResult
, and even nested async loops. - Simple
await
-based usage — no need for externalasync/await
handling inside the loop.
Perfect for replacing async logic inside
for
/forEach
/while
scripts — but safer and smarter.
Execute a loop a fixed number of times (like a traditional for
loop).
// Import the module
import forPromise from 'for-promise';
// Loop will run 10 times
const dataCount = 10;
// Run the loop
await forPromise({ data: dataCount }, (index, result) => {
// Display the current index
console.log(`The index value is '${index}'.`);
// Call result() to mark this iteration as complete
result();
});
You can also loop through an array or object and handle asynchronous logic inside.
// Import the module
import forPromise from 'for-promise';
import fs from 'fs';
// Sample array
const data = [1, 2, 3, 4, 5];
// Loop through each index
await forPromise({ data }, (index, result, error) => {
// Print current index and value
console.log(`The index '${index}' has value '${data[index]}'.`);
// Async operation: reading a directory
fs.readdir('/some/folder/path', (err, files) => {
if (!err) {
// Success: mark the iteration as completed
result();
} else {
// Error: interrupt the loop and reject the promise
error(err);
}
});
});
Use extra()
to add another loop from inside your main loop — perfect for nested async iterations!
// Import the module
import forPromise from 'for-promise';
import fs from 'fs';
// First dataset
const data1 = [1, 2, 3];
const data2 = [4, 5, 6];
// Outer loop
await forPromise({ data: data1 }, (index, result, error, extra) => {
console.log(`Outer index '${index}' has value '${data1[index]}'.`);
// Add a nested loop dynamically
const extraLoop = extra({ data: data2 });
// Run the nested loop
extraLoop.run((index2, result2, error2) => {
console.log(` Inner index '${index2}' has value '${data2[index2]}'.`);
fs.readdir('/another/folder', (err, files) => {
if (!err) result2();
else error2(err);
});
});
// Continue outer loop
result();
});
Use the type: 'while'
option to run a loop that repeats while a condition remains true — similar to a classic do...while
structure.
// Import the module
import forPromise from 'for-promise';
// Data object to track the condition
const whileData = { count: 0 };
// Run the "do while" loop
await forPromise({
// Set the loop type
type: 'while',
while: whileData,
// Condition checker (must return true or false)
checker: () => {
return (whileData.count < 3);
}
}, (done, error) => {
// Loop body: will execute at least once
console.log(`Do: ${whileData.count}`);
// Update value
whileData.count++;
// Mark iteration as complete
done();
});
💡 This script will print:
Do: 0 Do: 1 Do: 2
Use fn(true)
inside the loop callback to force a break, just like a break
statement in traditional for
loops.
// Import the module
import forPromise from 'for-promise';
// Start the loop
await forPromise({
data: [1, 2, 3]
}, (item, done) => {
// Show the current item
console.log(`Array with Force Break: ${item}`);
// Break the loop immediately
done(true);
});
💡 This will only execute once and stop the entire loop.
Array with Force Break: 1
You can use this when you need to exit early based on a certain condition, just like break
in native loops.
Use the fn()
function with advanced options to control how the loop behaves and what result it returns.
// Import the module
import forPromise from 'for-promise';
// Example: Use filesystem
import fs from 'fs';
import path from 'path';
// Start the loop
await forPromise({
data: [1, 2, 3]
}, (item, done, fail) => {
// Async example: read a folder
fs.readdir(path.join(__dirname, './folder'), (err, files) => {
if (!err) {
console.log(`Force Break used to read this data: ${item}`);
console.log(files);
// ✅ Mark this result as the final result and end all execution
done({ forceResult: true });
} else {
// ❌ Stop execution and return the error
fail(err);
}
});
// 🛑 Stop further execution without returning a result
done({ break: true, dontSendResult: true });
});
-
forceResult: true
: Immediately ends the loop and returns this value as the final result. -
break: true
: Stops the loop like a normalbreak
. -
dontSendResult: true
: Suppresses the current iteration result from being stored or returned.
💡 You can combine
forceResult
,break
, anddontSendResult
as needed to fully control the loop's execution and return behavior.
🧠 This documentation was written with the help of AI assistance (ChatGPT by OpenAI) to ensure clarity, structure, and language accuracy.