🚀 taz-js

Efficiently execute asynchronous functions on array elements in parallel with a configurable concurrency limit.

📦 Installation

Install via npm:

npm install taz-js

Then, import it into your project:

require("taz-js");

or

import "taz-js";

⚡ Usage

Basic Example

The parallel method runs an async function on array elements with a concurrency limit.

require("taz-js");

const arr = [1, 2, 3, 4, 5];

arr.parallel(async (num) => {
  console.log(`Processing ${num}`);
  await new Promise((resolve) => setTimeout(resolve, 1000)); // Simulate async task
  console.log(`Finished ${num}`);
}, 2);

Example Output

Processing 1
Processing 2
Finished 1
Finished 2
Processing 3
Processing 4
Finished 3
Finished 4
Processing 5
Finished 5

(Only 2 tasks run concurrently at a time.)

🌟 Advanced Methods

1️⃣ $parallel: Ignore Failures

The $parallel method works like parallel, but it doesn't stop execution if an error occurs.

require("taz-js");

const arr = [1, 2, 3, 4, 5];

arr.$parallel(async (num) => {
  if (num === 3) throw new Error("Error on 3");
  console.log(`Processing ${num}`);
  await new Promise((resolve) => setTimeout(resolve, 1000));
  console.log(`Finished ${num}`);
}, 2);

2️⃣ $map: Collect Results

The $map method collects results and errors.

require("taz-js");

const arr = [1, 2, 3, 4, 5];

const results = await arr.$map(async (num) => {
  if (num === 3) throw new Error("Error on 3");
  return num * 2;
}, 2);

console.log(results); // Output: [2, 4, Error: Error on 3, 8, 10]

3️⃣ Fetching API Data in Parallel

require("taz-js");

const users = ["Alice", "Bob", "Charlie", "David", "Eve"];

async function fetchUserData(user) {
  console.log(`Fetching data for ${user}`);
  await new Promise((resolve) => setTimeout(resolve, 2000)); // Simulated API delay
  console.log(`Data fetched for ${user}`);
}

users.parallel(fetchUserData, 3); // Runs 3 API calls at a time

4️⃣ Processing Files in Parallel

require("taz-js");
const fs = require("fs/promises");

const files = ["file1.txt", "file2.txt", "file3.txt"];

files.parallel(async (file) => {
  const data = await fs.readFile(file, "utf8");
  console.log(`Read ${file}: ${data.length} characters`);
}, 2);

🔧 API Reference

Array.prototype.parallel(
  func: (element, index, array) => Promise<void>, 
  concurrency?: number
) => Promise<void>

Array.prototype.$parallel(
  func: (element, index, array) => Promise<void>, 
  concurrency?: number
) => Promise<void>

Array.prototype.$map(
  func: (element, index, array) => Promise<any>, 
  concurrency?: number
) => Promise<any[]>

Methods:

• parallel(func, concurrency?) - Executes tasks in parallel with a concurrency limit.
• $parallel(func, concurrency?) - Runs tasks in parallel, but doesn't stop on errors.
• $map(func, concurrency?) - Runs tasks in parallel and returns results/errors.

Parameters:

• func (async function) - Function to execute on each array element.
• concurrency (number, default = 10) - Max number of parallel executions.

Returns:

• parallel & $parallel return a Promise<void>.
• $map returns a Promise resolving to an array of results/errors.

📌 Notes

✔️ Works with any array of data.
✔️ Defaults to 10 concurrent executions if no limit is set.
✔️ Useful for API calls, file processing, and async tasks.
✔️ $parallel prevents failures from stopping execution.
✔️ $map allows result collection even if some fail.

📜 License

MIT