0
# Run Parallel
1

2
Run Parallel is a lightweight utility that executes an array or object of asynchronous functions in parallel without waiting for each function to complete before starting the next. It serves as a modular alternative to `async.parallel`, focusing on a single core functionality to reduce bundle size for browser applications.
3

4
## Package Information
5

6
- **Package Name**: run-parallel
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install run-parallel`
10

11
## Core Imports
12

13
```javascript
14
const parallel = require('run-parallel');
15
```
16

17
or
18

19
```javascript
20
const runParallel = require('run-parallel');
21
```
22

23
## Basic Usage
24

25
```javascript
26
const parallel = require('run-parallel');
27

28
// Array of tasks - results returned as array
29
parallel([
30
  function (callback) {
31
    setTimeout(() => callback(null, 'task1'), 100);
32
  },
33
  function (callback) {
34
    setTimeout(() => callback(null, 'task2'), 50);
35
  }
36
], function (err, results) {
37
  if (err) throw err;
38
  console.log(results); // ['task1', 'task2'] - order preserved
39
});
40

41
// Object of tasks - results returned as object
42
parallel({
43
  users: function (callback) {
44
    // Fetch users
45
    callback(null, ['alice', 'bob']);
46
  },
47
  posts: function (callback) {
48
    // Fetch posts  
49
    callback(null, ['post1', 'post2']);
50
  }
51
}, function (err, results) {
52
  if (err) throw err;
53
  console.log(results); // { users: ['alice', 'bob'], posts: ['post1', 'post2'] }
54
});
55
```
56

57
## Capabilities
58

59
### Parallel Execution
60

61
Executes an array or object of asynchronous functions in parallel and collects their results.
62

63
```javascript { .api }
64
/**
65
 * Run an array or object of functions in parallel
66
 * @param {Array|Object} tasks - Collection of functions to execute in parallel
67
 * @param {Function} [callback] - Optional completion callback
68
 * @returns {undefined} - Does not return a value; results are provided via callback
69
 */
70
function runParallel(tasks, callback);
71
```
72

73
#### Parameters
74

75
- **tasks** (Array|Object): Collection of functions to execute in parallel
76
  - If Array: Functions are executed in parallel, results returned as array preserving order
77
  - If Object: Functions are executed in parallel, results returned as object with same keys
78
  - Each task function receives a callback with signature `callback(err, result)`
79
- **callback** (Function, optional): Completion callback with signature `callback(err, results)`
80
  - Called when all tasks complete successfully or when first error occurs
81
  - `err`: Error from first failed task, or null if all succeeded
82
  - `results`: Array or Object matching input type containing all results
83

84
#### Behavior
85

86
- **Parallel Execution**: All tasks start immediately, don't wait for previous tasks
87
- **Order Preservation**: For arrays, results maintain the same order as input tasks
88
- **Error Handling**: Stops on first error and calls main callback immediately
89
- **Empty Input**: Calls callback immediately with empty results for empty arrays/objects
90
- **Async Consistency**: Uses microtask queuing for consistent asynchronous behavior
91
- **Optional Callback**: Tasks still execute even if no callback is provided
92

93
#### Usage Examples
94

95
**Array of Tasks:**
96
```javascript
97
const parallel = require('run-parallel');
98

99
parallel([
100
  function (callback) {
101
    fs.readFile('file1.txt', callback);
102
  },
103
  function (callback) {
104
    fs.readFile('file2.txt', callback);
105
  },
106
  function (callback) {
107
    fs.readFile('file3.txt', callback);
108
  }
109
], function (err, results) {
110
  if (err) {
111
    console.error('Error reading files:', err);
112
    return;
113
  }
114
  // results[0] = contents of file1.txt
115
  // results[1] = contents of file2.txt  
116
  // results[2] = contents of file3.txt
117
  console.log('All files read successfully');
118
});
119
```
120

121
**Object of Tasks:**
122
```javascript
123
const parallel = require('run-parallel');
124

125
parallel({
126
  weather: function (callback) {
127
    fetchWeather((err, data) => callback(err, data));
128
  },
129
  news: function (callback) {
130
    fetchNews((err, data) => callback(err, data));
131
  },
132
  stocks: function (callback) {
133
    fetchStocks((err, data) => callback(err, data));
134
  }
135
}, function (err, results) {
136
  if (err) {
137
    console.error('Error fetching data:', err);
138
    return;
139
  }
140
  // results.weather = weather data
141
  // results.news = news data
142
  // results.stocks = stock data
143
  console.log('All data fetched:', results);
144
});
145
```
146

147
**Error Handling:**
148
```javascript
149
const parallel = require('run-parallel');
150

151
parallel([
152
  function (callback) {
153
    callback(null, 'success');
154
  },
155
  function (callback) {
156
    callback(new Error('Something went wrong'));
157
  },
158
  function (callback) {
159
    // This might not complete if error occurs first
160
    setTimeout(() => callback(null, 'delayed'), 1000);
161
  }
162
], function (err, results) {
163
  if (err) {
164
    console.error('Task failed:', err.message); // "Something went wrong"
165
    // results may contain partial data: ['success', undefined, undefined]
166
    return;
167
  }
168
  console.log('All tasks completed:', results);
169
});
170
```
171

172
**Without Callback:**
173
```javascript
174
const parallel = require('run-parallel');
175

176
// Tasks still execute, results are discarded
177
parallel([
178
  function (callback) {
179
    console.log('Task 1 executing');
180
    callback(null, 'done');
181
  },
182
  function (callback) {
183
    console.log('Task 2 executing');
184
    callback(null, 'done');
185
  }
186
]);
187
// Output: "Task 1 executing" and "Task 2 executing"
188
```
189

190
## Browser Compatibility
191

192
This package works in browsers when bundled with browserify or similar tools. It uses the `queue-microtask` dependency to ensure consistent asynchronous behavior across different JavaScript environments.
193

194
## Dependencies
195

196
- **queue-microtask**: ^1.2.2 - Provides consistent microtask scheduling across environments