ForPromise-JS

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.

---

✨ Key Features:

• Works with arrays, objects, numbers, and custom while conditions.
• Supports fn() and fn_error() callbacks.
• Allows break, forceResult, dontSendResult, and even nested async loops.
• Simple await-based usage — no need for external async/await handling inside the loop.

Perfect for replacing async logic inside for/forEach/while scripts — but safer and smarter.

📘 Usage Examples

🔁 Basic Loop: Number as Loop Count

Execute a loop a fixed number of times (like a traditional for loop).

// Import the moduleimportforPromisefrom'for-promise';// Loop will run 10 timesconstdataCount=10;// Run the loopawaitforPromise({data: dataCount},(index,result)=>{// Display the current indexconsole.log(`The index value is '${index}'.`);// Call result() to mark this iteration as completeresult();});

🧾 Looping Through Arrays or Objects

You can also loop through an array or object and handle asynchronous logic inside.

// Import the moduleimportforPromisefrom'for-promise';importfsfrom'fs';// Sample arrayconstdata=[1,2,3,4,5];// Loop through each indexawaitforPromise({ data },(index,result,error)=>{// Print current index and valueconsole.log(`The index '${index}' has value '${data[index]}'.`);// Async operation: reading a directoryfs.readdir('/some/folder/path',(err,files)=>{if(!err){// Success: mark the iteration as completedresult();}else{// Error: interrupt the loop and reject the promiseerror(err);}});});

➕ Adding Extra Loops Dynamically

Use extra() to add another loop from inside your main loop — perfect for nested async iterations!

// Import the moduleimportforPromisefrom'for-promise';importfsfrom'fs';// First datasetconstdata1=[1,2,3];constdata2=[4,5,6];// Outer loopawaitforPromise({data: data1},(index,result,error,extra)=>{console.log(`Outer index '${index}' has value '${data1[index]}'.`);// Add a nested loop dynamicallyconstextraLoop=extra({data: data2});// Run the nested loopextraLoop.run((index2,result2,error2)=>{console.log(` Inner index '${index2}' has value '${data2[index2]}'.`);fs.readdir('/another/folder',(err,files)=>{if(!err)result2();elseerror2(err);});});// Continue outer loopresult();});

🔁 Execute a "Do While" Loop

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 moduleimportforPromisefrom'for-promise';// Data object to track the conditionconstwhileData={count: 0};// Run the "do while" loopawaitforPromise({// Set the loop typetype: 'while',while: whileData,// Condition checker (must return true or false)checker: ()=>{return(whileData.count<3);}},(done,error)=>{// Loop body: will execute at least onceconsole.log(`Do: ${whileData.count}`);// Update valuewhileData.count++;// Mark iteration as completedone();});

💡 This script will print:

Do: 0 Do: 1 Do: 2 

🛑 Execute a "For Script" with Break FN

Use fn(true) inside the loop callback to force a break, just like a break statement in traditional for loops.

// Import the moduleimportforPromisefrom'for-promise';// Start the loopawaitforPromise({data: [1,2,3]},(item,done)=>{// Show the current itemconsole.log(`Array with Force Break: ${item}`);// Break the loop immediatelydone(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.

🧠 Execute a "For Script" with forceResult, break, and dontSendResult

Use the fn() function with advanced options to control how the loop behaves and what result it returns.

// Import the moduleimportforPromisefrom'for-promise';// Example: Use filesystemimportfsfrom'fs';importpathfrom'path';// Start the loopawaitforPromise({data: [1,2,3]},(item,done,fail)=>{// Async example: read a folderfs.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 executiondone({forceResult: true});}else{// ❌ Stop execution and return the errorfail(err);}});// 🛑 Stop further execution without returning a resultdone({break: true,dontSendResult: true});});

---

🔍 Behavior Summary

• forceResult: true: Immediately ends the loop and returns this value as the final result.
• break: true: Stops the loop like a normal break.
• dontSendResult: true: Suppresses the current iteration result from being stored or returned.

💡 You can combine forceResult, break, and dontSendResult 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.