stardust-parallel-js 1.0.4 → 1.0.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +101 -102
- package/README.ru.md +311 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -9,79 +9,81 @@
|
|
|
9
9
|
[](https://www.npmjs.com/package/stardust-parallel-js)
|
|
10
10
|
[](https://github.com/b1411/stardust-parallel-js)
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
> 📖 **Other languages:** [Русский](./README.ru.md)
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
**Speed up your Node.js applications up to 3x** with a simple API for parallel task execution!
|
|
15
15
|
|
|
16
|
-
|
|
16
|
+
A library for parallel execution of JavaScript/TypeScript functions using Worker Threads in Node.js.
|
|
17
17
|
|
|
18
|
-
|
|
18
|
+
## 🚀 Performance
|
|
19
19
|
|
|
20
|
-
|
|
21
|
-
|--------|----------------|------------------------|-----------|
|
|
22
|
-
| **Вычисление Fibonacci(35-42)** | 5113 мс | 2606 мс | **1.96x** 🔥 |
|
|
23
|
-
| **Обработка 50 элементов** | 936 мс | 344 мс | **2.72x** ⚡ |
|
|
20
|
+
Real benchmarks on 4-core CPU:
|
|
24
21
|
|
|
25
|
-
|
|
22
|
+
| Task | Sequential | Parallel (4 workers) | Speedup |
|
|
23
|
+
|------|-----------|---------------------|---------|
|
|
24
|
+
| **Fibonacci(35-42) computation** | 5113 ms | 2606 ms | **1.96x** 🔥 |
|
|
25
|
+
| **Processing 50 items** | 936 ms | 344 ms | **2.72x** ⚡ |
|
|
26
26
|
|
|
27
|
-
|
|
27
|
+
> 💡 **Result**: up to **63% performance improvement** on CPU-intensive tasks!
|
|
28
28
|
|
|
29
|
-
|
|
30
|
-
- 💡 **Простой API** - начните использовать за 2 минуты
|
|
31
|
-
- 🔄 **Пул потоков** - эффективное управление ресурсами
|
|
32
|
-
- ⚡ **Отдельные потоки** - для разовых задач
|
|
33
|
-
- 📦 **TypeScript** - полная поддержка из коробки
|
|
34
|
-
- 🛡️ **Надежность** - автоматическое восстановление упавших потоков
|
|
35
|
-
- 🎯 **Простота** - работает как обычный `map()`, но параллельно
|
|
29
|
+
## ✨ Features
|
|
36
30
|
|
|
37
|
-
|
|
31
|
+
- 🚀 **Up to 3x faster** - real speedup on multi-core processors
|
|
32
|
+
- 💡 **Simple API** - start using in 2 minutes
|
|
33
|
+
- 🔄 **Thread pool** - efficient resource management
|
|
34
|
+
- ⚡ **Single threads** - for one-off tasks
|
|
35
|
+
- 📦 **TypeScript** - full support out of the box
|
|
36
|
+
- 🛡️ **Reliability** - automatic recovery of crashed threads
|
|
37
|
+
- 🎯 **Simplicity** - works like regular `map()`, but parallel
|
|
38
|
+
|
|
39
|
+
## 📦 Installation
|
|
38
40
|
|
|
39
41
|
```bash
|
|
40
42
|
npm install stardust-parallel-js
|
|
41
|
-
#
|
|
43
|
+
# or
|
|
42
44
|
pnpm install stardust-parallel-js
|
|
43
|
-
#
|
|
45
|
+
# or
|
|
44
46
|
yarn add stardust-parallel-js
|
|
45
47
|
```
|
|
46
48
|
|
|
47
|
-
## 🎯
|
|
49
|
+
## 🎯 Quick Start
|
|
48
50
|
|
|
49
|
-
|
|
51
|
+
**In 30 seconds** you can speed up array processing by 2-3x:
|
|
50
52
|
|
|
51
53
|
```typescript
|
|
52
54
|
import { ThreadPool } from 'stardust-parallel-js';
|
|
53
55
|
|
|
54
56
|
const pool = new ThreadPool(4);
|
|
55
57
|
|
|
56
|
-
//
|
|
58
|
+
// Regular code - slow 🐌
|
|
57
59
|
const results = data.map(item => heavyComputation(item));
|
|
58
60
|
|
|
59
|
-
//
|
|
61
|
+
// With stardust-parallel-js - fast! ⚡
|
|
60
62
|
const results = await pool.map(data, item => heavyComputation(item));
|
|
61
63
|
|
|
62
64
|
await pool.terminate();
|
|
63
65
|
```
|
|
64
66
|
|
|
65
|
-
|
|
67
|
+
**That's it!** Your code now runs in parallel on all CPU cores.
|
|
66
68
|
|
|
67
|
-
## 📚
|
|
69
|
+
## 📚 Usage
|
|
68
70
|
|
|
69
|
-
### ThreadPool -
|
|
71
|
+
### ThreadPool - Thread pool (recommended)
|
|
70
72
|
|
|
71
|
-
|
|
73
|
+
Use `ThreadPool` to process multiple tasks with maximum efficiency:
|
|
72
74
|
|
|
73
75
|
```typescript
|
|
74
76
|
import { ThreadPool } from 'stardust-parallel-js';
|
|
75
77
|
|
|
76
|
-
//
|
|
78
|
+
// Create a pool of 4 threads (matching CPU cores)
|
|
77
79
|
const pool = new ThreadPool(4);
|
|
78
80
|
|
|
79
|
-
// 🎯
|
|
81
|
+
// 🎯 Process array - like regular map(), but parallel!
|
|
80
82
|
const numbers = [1, 2, 3, 4, 5, 6, 7, 8];
|
|
81
83
|
const squares = await pool.map(numbers, (n: number) => n * n);
|
|
82
84
|
console.log(squares); // [1, 4, 9, 16, 25, 36, 49, 64]
|
|
83
85
|
|
|
84
|
-
// 💪 CPU
|
|
86
|
+
// 💪 CPU-intensive computations
|
|
85
87
|
const result = await pool.execute(
|
|
86
88
|
(n: number) => {
|
|
87
89
|
let sum = 0;
|
|
@@ -93,18 +95,18 @@ const result = await pool.execute(
|
|
|
93
95
|
[1000000]
|
|
94
96
|
);
|
|
95
97
|
|
|
96
|
-
//
|
|
98
|
+
// Release resources
|
|
97
99
|
await pool.terminate();
|
|
98
100
|
```
|
|
99
101
|
|
|
100
|
-
### Thread -
|
|
102
|
+
### Thread - Single thread (for simple tasks)
|
|
101
103
|
|
|
102
|
-
|
|
104
|
+
Use `Thread` for one-off operations:
|
|
103
105
|
|
|
104
106
|
```typescript
|
|
105
107
|
import { Thread } from 'stardust-parallel-js';
|
|
106
108
|
|
|
107
|
-
//
|
|
109
|
+
// Start and wait for result
|
|
108
110
|
const thread = new Thread(
|
|
109
111
|
(text: string) => text.toUpperCase(),
|
|
110
112
|
['hello world']
|
|
@@ -113,14 +115,14 @@ const thread = new Thread(
|
|
|
113
115
|
const result = await thread.join();
|
|
114
116
|
console.log(result); // "HELLO WORLD"
|
|
115
117
|
|
|
116
|
-
//
|
|
118
|
+
// Arrow functions work!
|
|
117
119
|
const thread2 = new Thread(x => x * 2, [21]);
|
|
118
120
|
console.log(await thread2.join()); // 42
|
|
119
121
|
```
|
|
120
122
|
|
|
121
|
-
## 💡
|
|
123
|
+
## 💡 Real-World Examples
|
|
122
124
|
|
|
123
|
-
###
|
|
125
|
+
### Image Processing
|
|
124
126
|
|
|
125
127
|
```typescript
|
|
126
128
|
import { ThreadPool } from 'stardust-parallel-js';
|
|
@@ -128,24 +130,24 @@ import { ThreadPool } from 'stardust-parallel-js';
|
|
|
128
130
|
const pool = new ThreadPool(8);
|
|
129
131
|
const images = ['img1.jpg', 'img2.jpg', /* ... */ 'img100.jpg'];
|
|
130
132
|
|
|
131
|
-
//
|
|
133
|
+
// Process 100 images in parallel
|
|
132
134
|
const processed = await pool.map(images, (path: string) => {
|
|
133
135
|
const fs = require('fs');
|
|
134
136
|
const sharp = require('sharp');
|
|
135
|
-
//
|
|
137
|
+
// Complex image processing
|
|
136
138
|
return processImage(path);
|
|
137
139
|
});
|
|
138
140
|
|
|
139
141
|
await pool.terminate();
|
|
140
142
|
```
|
|
141
143
|
|
|
142
|
-
###
|
|
144
|
+
### Parsing Large Data
|
|
143
145
|
|
|
144
146
|
```typescript
|
|
145
147
|
const pool = new ThreadPool(4);
|
|
146
148
|
const chunks = splitDataIntoChunks(bigData, 1000);
|
|
147
149
|
|
|
148
|
-
//
|
|
150
|
+
// Parse each chunk in parallel
|
|
149
151
|
const parsed = await pool.map(chunks, (chunk: any[]) => {
|
|
150
152
|
return chunk.map(item => parseComplexData(item));
|
|
151
153
|
});
|
|
@@ -153,7 +155,7 @@ const parsed = await pool.map(chunks, (chunk: any[]) => {
|
|
|
153
155
|
await pool.terminate();
|
|
154
156
|
```
|
|
155
157
|
|
|
156
|
-
###
|
|
158
|
+
### Calculations and Analytics
|
|
157
159
|
|
|
158
160
|
```typescript
|
|
159
161
|
const pool = new ThreadPool(4);
|
|
@@ -169,9 +171,9 @@ const results = await pool.map([35, 36, 37, 38, 39, 40], n => {
|
|
|
169
171
|
await pool.terminate();
|
|
170
172
|
```
|
|
171
173
|
|
|
172
|
-
## 📊
|
|
174
|
+
## 📊 Benchmarks
|
|
173
175
|
|
|
174
|
-
|
|
176
|
+
Run yourself and see the performance:
|
|
175
177
|
|
|
176
178
|
```bash
|
|
177
179
|
npm run build
|
|
@@ -184,35 +186,32 @@ npx tsx benchmarks/data-processing.ts
|
|
|
184
186
|
### ThreadPool
|
|
185
187
|
|
|
186
188
|
#### `constructor(size: number)`
|
|
187
|
-
|
|
189
|
+
Creates a thread pool of the specified size.
|
|
188
190
|
|
|
189
191
|
```typescript
|
|
190
192
|
const pool = new ThreadPool(4);
|
|
191
193
|
```
|
|
192
194
|
|
|
193
195
|
#### `execute<TArgs, TResult>(fn: (...args: TArgs) => TResult, args?: TArgs): Promise<TResult>`
|
|
194
|
-
|
|
196
|
+
Executes a function in an available thread from the pool.
|
|
195
197
|
|
|
196
198
|
```typescript
|
|
197
|
-
const result = await pool.execute(
|
|
199
|
+
const result = await pool.execute((x: number) => x * x, [5]);
|
|
200
|
+
```
|
|
201
|
+
|
|
198
202
|
#### `map<T, R>(items: T[], fn: (item: T) => R): Promise<R[]>`
|
|
199
|
-
|
|
203
|
+
Applies a function to each array element in parallel.
|
|
200
204
|
|
|
201
205
|
```typescript
|
|
202
|
-
//
|
|
206
|
+
// Arrow function
|
|
203
207
|
const results = await pool.map([1, 2, 3], n => n * 2);
|
|
204
208
|
|
|
205
|
-
//
|
|
209
|
+
// Regular function
|
|
206
210
|
const results2 = await pool.map([1, 2, 3], function(n) { return n * 2; });
|
|
207
|
-
```# `map<T, R>(items: T[], fn: (item: T) => R): Promise<R[]>`
|
|
208
|
-
Применяет функцию к каждому элементу массива параллельно.
|
|
209
|
-
|
|
210
|
-
```typescript
|
|
211
|
-
const results = await pool.map([1, 2, 3], (n) => n * 2);
|
|
212
211
|
```
|
|
213
212
|
|
|
214
213
|
#### `terminate(): Promise<void>`
|
|
215
|
-
|
|
214
|
+
Stops all threads and releases resources.
|
|
216
215
|
|
|
217
216
|
```typescript
|
|
218
217
|
await pool.terminate();
|
|
@@ -221,91 +220,91 @@ await pool.terminate();
|
|
|
221
220
|
### Thread
|
|
222
221
|
|
|
223
222
|
#### `constructor<T, TArgs>(fn: (...args: TArgs) => T, args?: TArgs)`
|
|
224
|
-
|
|
223
|
+
Creates a new thread to execute a function.
|
|
225
224
|
|
|
226
225
|
```typescript
|
|
227
226
|
const thread = new Thread((x: number) => x * x, [5]);
|
|
228
227
|
```
|
|
229
228
|
|
|
230
229
|
#### `join(): Promise<T>`
|
|
231
|
-
|
|
230
|
+
Waits for execution to complete and returns the result. Automatically terminates the thread.
|
|
232
231
|
|
|
233
232
|
```typescript
|
|
234
233
|
const result = await thread.join();
|
|
235
234
|
```
|
|
236
235
|
|
|
237
|
-
## ⚠️
|
|
236
|
+
## ⚠️ Important Notes
|
|
238
237
|
|
|
239
|
-
- 🔒
|
|
240
|
-
- 📦
|
|
241
|
-
- 🚫
|
|
242
|
-
- ✅
|
|
243
|
-
- ✅ `require()`
|
|
244
|
-
- ⚡
|
|
245
|
-
- 💡
|
|
238
|
+
- 🔒 Functions execute in an isolated context (separate Worker Thread)
|
|
239
|
+
- 📦 Arguments and results must be serializable
|
|
240
|
+
- 🚫 Closures don't work - functions have no access to external variables
|
|
241
|
+
- ✅ Regular and arrow functions are supported
|
|
242
|
+
- ✅ `require()` is available inside functions for using Node.js modules
|
|
243
|
+
- ⚡ Best suited for CPU-intensive tasks (calculations, data processing)
|
|
244
|
+
- 💡 For I/O operations (reading files, network) use async/await instead of threads
|
|
246
245
|
|
|
247
|
-
## 🎯
|
|
246
|
+
## 🎯 When to Use?
|
|
248
247
|
|
|
249
|
-
**✅
|
|
250
|
-
-
|
|
251
|
-
-
|
|
252
|
-
-
|
|
253
|
-
-
|
|
254
|
-
-
|
|
248
|
+
**✅ Use stardust-parallel-js when:**
|
|
249
|
+
- Processing large data arrays
|
|
250
|
+
- Performing complex calculations
|
|
251
|
+
- Parsing or transforming data
|
|
252
|
+
- Processing images/video
|
|
253
|
+
- Need to utilize all CPU cores
|
|
255
254
|
|
|
256
|
-
**❌
|
|
257
|
-
-
|
|
258
|
-
- I/O
|
|
259
|
-
-
|
|
255
|
+
**❌ Don't use when:**
|
|
256
|
+
- Simple operations (faster to execute sequentially)
|
|
257
|
+
- I/O operations (files, network, DB) - they're already asynchronous
|
|
258
|
+
- Working with DOM (Node.js only)
|
|
260
259
|
|
|
261
|
-
## 📈
|
|
260
|
+
## 📈 How to Choose Pool Size?
|
|
262
261
|
|
|
263
262
|
```typescript
|
|
264
263
|
import os from 'os';
|
|
265
264
|
|
|
266
|
-
//
|
|
265
|
+
// Optimal: number of CPU cores
|
|
267
266
|
const pool = new ThreadPool(os.cpus().length);
|
|
268
267
|
|
|
269
|
-
//
|
|
270
|
-
const pool = new ThreadPool(os.cpus().length - 1); //
|
|
268
|
+
// For CPU-intensive tasks
|
|
269
|
+
const pool = new ThreadPool(os.cpus().length - 1); // leave 1 core for system
|
|
271
270
|
|
|
272
|
-
//
|
|
271
|
+
// For mixed workload
|
|
273
272
|
const pool = new ThreadPool(os.cpus().length * 2);
|
|
274
273
|
```
|
|
275
274
|
|
|
276
|
-
## 🤝
|
|
275
|
+
## 🤝 Comparison with Alternatives
|
|
277
276
|
|
|
278
|
-
|
|
|
279
|
-
|
|
280
|
-
| **stardust-parallel-js** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ✅
|
|
281
|
-
| worker_threads | ⭐⭐ | ⭐⭐⭐⭐⭐ | ⚠️
|
|
282
|
-
| cluster | ⭐⭐ | ⭐⭐⭐ | ⚠️
|
|
283
|
-
| child_process | ⭐ | ⭐⭐ | ❌
|
|
277
|
+
| Solution | Simplicity | Performance | TypeScript | Size |
|
|
278
|
+
|----------|-----------|-------------|------------|------|
|
|
279
|
+
| **stardust-parallel-js** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ✅ Full | 9.3kB |
|
|
280
|
+
| worker_threads | ⭐⭐ | ⭐⭐⭐⭐⭐ | ⚠️ Partial | Built-in |
|
|
281
|
+
| cluster | ⭐⭐ | ⭐⭐⭐ | ⚠️ Partial | Built-in |
|
|
282
|
+
| child_process | ⭐ | ⭐⭐ | ❌ No | Built-in |
|
|
284
283
|
|
|
285
284
|
## 🚀 Roadmap
|
|
286
285
|
|
|
287
|
-
- [ ]
|
|
288
|
-
- [ ]
|
|
289
|
-
- [ ]
|
|
290
|
-
- [ ]
|
|
291
|
-
- [ ]
|
|
286
|
+
- [ ] Support for transferable objects for large data
|
|
287
|
+
- [ ] Automatic selection of optimal pool size
|
|
288
|
+
- [ ] Task prioritization
|
|
289
|
+
- [ ] Monitoring and statistics
|
|
290
|
+
- [ ] Support for async functions in threads
|
|
292
291
|
|
|
293
|
-
## 💬
|
|
292
|
+
## 💬 Feedback
|
|
294
293
|
|
|
295
|
-
|
|
294
|
+
Found a bug? Have an idea? [Create an issue](https://github.com/b1411/stardust-parallel-js/issues)!
|
|
296
295
|
|
|
297
|
-
⭐
|
|
296
|
+
⭐ If the library helped you - give it a star on [GitHub](https://github.com/b1411/stardust-parallel-js)!
|
|
298
297
|
|
|
299
|
-
## 📦
|
|
298
|
+
## 📦 Requirements
|
|
300
299
|
|
|
301
|
-
- Node.js >= 14.0.0 (
|
|
300
|
+
- Node.js >= 14.0.0 (with Worker Threads support)
|
|
302
301
|
|
|
303
|
-
## 📄
|
|
302
|
+
## 📄 License
|
|
304
303
|
|
|
305
304
|
MIT © [b1411](https://github.com/b1411)
|
|
306
305
|
|
|
307
306
|
---
|
|
308
307
|
|
|
309
308
|
<p align="center">
|
|
310
|
-
|
|
309
|
+
Made with ❤️ for the Node.js community
|
|
311
310
|
</p>
|
package/README.ru.md
ADDED
|
@@ -0,0 +1,311 @@
|
|
|
1
|
+
# ⚡ stardust-parallel-js
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/stardust-parallel-js)
|
|
4
|
+
[](https://www.npmjs.com/package/stardust-parallel-js)
|
|
5
|
+
[](https://opensource.org/licenses/MIT)
|
|
6
|
+
[](https://github.com/b1411/stardust-parallel-js)
|
|
7
|
+
[](https://nodejs.org)
|
|
8
|
+
[](https://www.typescriptlang.org/)
|
|
9
|
+
[](https://www.npmjs.com/package/stardust-parallel-js)
|
|
10
|
+
[](https://github.com/b1411/stardust-parallel-js)
|
|
11
|
+
|
|
12
|
+
> 📖 **Другие языки:** [English](./README.md)
|
|
13
|
+
|
|
14
|
+
**Ускорьте свои Node.js приложения до 3x** с помощью простого API для параллельного выполнения задач!
|
|
15
|
+
|
|
16
|
+
## 🚀 Производительность
|
|
17
|
+
|
|
18
|
+
Реальные бенчмарки на 4-ядерном CPU:
|
|
19
|
+
|
|
20
|
+
| Задача | Последовательно | Параллельно (4 потока) | Ускорение |
|
|
21
|
+
|--------|----------------|------------------------|-----------|
|
|
22
|
+
| **Вычисление Fibonacci(35-42)** | 5113 мс | 2606 мс | **1.96x** 🔥 |
|
|
23
|
+
| **Обработка 50 элементов** | 936 мс | 344 мс | **2.72x** ⚡ |
|
|
24
|
+
|
|
25
|
+
> 💡 **Результат**: до **63% улучшения** производительности на CPU-интенсивных задачах!
|
|
26
|
+
|
|
27
|
+
## ✨ Возможности
|
|
28
|
+
|
|
29
|
+
- 🚀 **До 3x быстрее** - реальное ускорение на многоядерных процессорах
|
|
30
|
+
- 💡 **Простой API** - начните использовать за 2 минуты
|
|
31
|
+
- 🔄 **Пул потоков** - эффективное управление ресурсами
|
|
32
|
+
- ⚡ **Отдельные потоки** - для разовых задач
|
|
33
|
+
- 📦 **TypeScript** - полная поддержка из коробки
|
|
34
|
+
- 🛡️ **Надежность** - автоматическое восстановление упавших потоков
|
|
35
|
+
- 🎯 **Простота** - работает как обычный `map()`, но параллельно
|
|
36
|
+
|
|
37
|
+
## 📦 Установка
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
npm install stardust-parallel-js
|
|
41
|
+
# или
|
|
42
|
+
pnpm install stardust-parallel-js
|
|
43
|
+
# или
|
|
44
|
+
yarn add stardust-parallel-js
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## 🎯 Быстрый старт
|
|
48
|
+
|
|
49
|
+
**За 30 секунд** вы можете ускорить обработку массивов в 2-3 раза:
|
|
50
|
+
|
|
51
|
+
```typescript
|
|
52
|
+
import { ThreadPool } from 'stardust-parallel-js';
|
|
53
|
+
|
|
54
|
+
const pool = new ThreadPool(4);
|
|
55
|
+
|
|
56
|
+
// Обычный код - медленно 🐌
|
|
57
|
+
const results = data.map(item => heavyComputation(item));
|
|
58
|
+
|
|
59
|
+
// С stardust-parallel-js - быстро! ⚡
|
|
60
|
+
const results = await pool.map(data, item => heavyComputation(item));
|
|
61
|
+
|
|
62
|
+
await pool.terminate();
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
**Вот и всё!** Ваш код теперь работает параллельно на всех ядрах процессора.
|
|
66
|
+
|
|
67
|
+
## 📚 Использование
|
|
68
|
+
|
|
69
|
+
### ThreadPool - Пул потоков (рекомендуется)
|
|
70
|
+
|
|
71
|
+
Используйте `ThreadPool` для обработки множества задач с максимальной эффективностью:
|
|
72
|
+
|
|
73
|
+
```typescript
|
|
74
|
+
import { ThreadPool } from 'stardust-parallel-js';
|
|
75
|
+
|
|
76
|
+
// Создаем пул из 4 потоков (по числу ядер CPU)
|
|
77
|
+
const pool = new ThreadPool(4);
|
|
78
|
+
|
|
79
|
+
// 🎯 Обработка массива - как обычный map(), но параллельно!
|
|
80
|
+
const numbers = [1, 2, 3, 4, 5, 6, 7, 8];
|
|
81
|
+
const squares = await pool.map(numbers, (n: number) => n * n);
|
|
82
|
+
console.log(squares); // [1, 4, 9, 16, 25, 36, 49, 64]
|
|
83
|
+
|
|
84
|
+
// 💪 CPU-интенсивные вычисления
|
|
85
|
+
const result = await pool.execute(
|
|
86
|
+
(n: number) => {
|
|
87
|
+
let sum = 0;
|
|
88
|
+
for (let i = 0; i < n; i++) {
|
|
89
|
+
sum += Math.sqrt(i);
|
|
90
|
+
}
|
|
91
|
+
return sum;
|
|
92
|
+
},
|
|
93
|
+
[1000000]
|
|
94
|
+
);
|
|
95
|
+
|
|
96
|
+
// Освобождаем ресурсы
|
|
97
|
+
await pool.terminate();
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
### Thread - Отдельный поток (для простых задач)
|
|
101
|
+
|
|
102
|
+
Используйте `Thread` для разовых операций:
|
|
103
|
+
|
|
104
|
+
```typescript
|
|
105
|
+
import { Thread } from 'stardust-parallel-js';
|
|
106
|
+
|
|
107
|
+
// Запустить и дождаться результата
|
|
108
|
+
const thread = new Thread(
|
|
109
|
+
(text: string) => text.toUpperCase(),
|
|
110
|
+
['hello world']
|
|
111
|
+
);
|
|
112
|
+
|
|
113
|
+
const result = await thread.join();
|
|
114
|
+
console.log(result); // "HELLO WORLD"
|
|
115
|
+
|
|
116
|
+
// Стрелочные функции работают!
|
|
117
|
+
const thread2 = new Thread(x => x * 2, [21]);
|
|
118
|
+
console.log(await thread2.join()); // 42
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
## 💡 Примеры из реальной жизни
|
|
122
|
+
|
|
123
|
+
### Обработка изображений
|
|
124
|
+
|
|
125
|
+
```typescript
|
|
126
|
+
import { ThreadPool } from 'stardust-parallel-js';
|
|
127
|
+
|
|
128
|
+
const pool = new ThreadPool(8);
|
|
129
|
+
const images = ['img1.jpg', 'img2.jpg', /* ... */ 'img100.jpg'];
|
|
130
|
+
|
|
131
|
+
// Обрабатываем 100 изображений параллельно
|
|
132
|
+
const processed = await pool.map(images, (path: string) => {
|
|
133
|
+
const fs = require('fs');
|
|
134
|
+
const sharp = require('sharp');
|
|
135
|
+
// Сложная обработка изображения
|
|
136
|
+
return processImage(path);
|
|
137
|
+
});
|
|
138
|
+
|
|
139
|
+
await pool.terminate();
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
### Парсинг больших данных
|
|
143
|
+
|
|
144
|
+
```typescript
|
|
145
|
+
const pool = new ThreadPool(4);
|
|
146
|
+
const chunks = splitDataIntoChunks(bigData, 1000);
|
|
147
|
+
|
|
148
|
+
// Парсим каждый чунк параллельно
|
|
149
|
+
const parsed = await pool.map(chunks, (chunk: any[]) => {
|
|
150
|
+
return chunk.map(item => parseComplexData(item));
|
|
151
|
+
});
|
|
152
|
+
|
|
153
|
+
await pool.terminate();
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
### Вычисления и аналитика
|
|
157
|
+
|
|
158
|
+
```typescript
|
|
159
|
+
const pool = new ThreadPool(4);
|
|
160
|
+
|
|
161
|
+
const results = await pool.map([35, 36, 37, 38, 39, 40], n => {
|
|
162
|
+
function fibonacci(num: number): number {
|
|
163
|
+
if (num <= 1) return num;
|
|
164
|
+
return fibonacci(num - 1) + fibonacci(num - 2);
|
|
165
|
+
}
|
|
166
|
+
return fibonacci(n);
|
|
167
|
+
});
|
|
168
|
+
|
|
169
|
+
await pool.terminate();
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
## 📊 Бенчмарки
|
|
173
|
+
|
|
174
|
+
Запустите сами и убедитесь в производительности:
|
|
175
|
+
|
|
176
|
+
```bash
|
|
177
|
+
npm run build
|
|
178
|
+
npx tsx benchmarks/cpu-intensive.ts
|
|
179
|
+
npx tsx benchmarks/data-processing.ts
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
## 🎓 API Reference
|
|
183
|
+
|
|
184
|
+
### ThreadPool
|
|
185
|
+
|
|
186
|
+
#### `constructor(size: number)`
|
|
187
|
+
Создает пул потоков заданного размера.
|
|
188
|
+
|
|
189
|
+
```typescript
|
|
190
|
+
const pool = new ThreadPool(4);
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
#### `execute<TArgs, TResult>(fn: (...args: TArgs) => TResult, args?: TArgs): Promise<TResult>`
|
|
194
|
+
Выполняет функцию в доступном потоке из пула.
|
|
195
|
+
|
|
196
|
+
```typescript
|
|
197
|
+
const result = await pool.execute(
|
|
198
|
+
#### `map<T, R>(items: T[], fn: (item: T) => R): Promise<R[]>`
|
|
199
|
+
Применяет функцию к каждому элементу массива параллельно.
|
|
200
|
+
|
|
201
|
+
```typescript
|
|
202
|
+
// Стрелочная функция
|
|
203
|
+
const results = await pool.map([1, 2, 3], n => n * 2);
|
|
204
|
+
|
|
205
|
+
// Обычная функция
|
|
206
|
+
const results2 = await pool.map([1, 2, 3], function(n) { return n * 2; });
|
|
207
|
+
```# `map<T, R>(items: T[], fn: (item: T) => R): Promise<R[]>`
|
|
208
|
+
Применяет функцию к каждому элементу массива параллельно.
|
|
209
|
+
|
|
210
|
+
```typescript
|
|
211
|
+
const results = await pool.map([1, 2, 3], (n) => n * 2);
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
#### `terminate(): Promise<void>`
|
|
215
|
+
Останавливает все потоки и освобождает ресурсы.
|
|
216
|
+
|
|
217
|
+
```typescript
|
|
218
|
+
await pool.terminate();
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
### Thread
|
|
222
|
+
|
|
223
|
+
#### `constructor<T, TArgs>(fn: (...args: TArgs) => T, args?: TArgs)`
|
|
224
|
+
Создает новый поток для выполнения функции.
|
|
225
|
+
|
|
226
|
+
```typescript
|
|
227
|
+
const thread = new Thread((x: number) => x * x, [5]);
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
#### `join(): Promise<T>`
|
|
231
|
+
Ожидает завершения выполнения и возвращает результат. Автоматически завершает поток.
|
|
232
|
+
|
|
233
|
+
```typescript
|
|
234
|
+
const result = await thread.join();
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
## ⚠️ Важные замечания
|
|
238
|
+
|
|
239
|
+
- 🔒 Функции выполняются в изолированном контексте (отдельный Worker Thread)
|
|
240
|
+
- 📦 Аргументы и результаты должны быть сериализуемыми
|
|
241
|
+
- 🚫 Замыкания не работают - функции не имеют доступа к внешним переменным
|
|
242
|
+
- ✅ Поддерживаются обычные и стрелочные функции
|
|
243
|
+
- ✅ `require()` доступен внутри функций для использования Node.js модулей
|
|
244
|
+
- ⚡ Лучше всего подходит для CPU-интенсивных задач (вычисления, обработка данных)
|
|
245
|
+
- 💡 Для I/O операций (чтение файлов, сеть) используйте async/await вместо потоков
|
|
246
|
+
|
|
247
|
+
## 🎯 Когда использовать?
|
|
248
|
+
|
|
249
|
+
**✅ Используйте stardust-parallel-js когда:**
|
|
250
|
+
- Обрабатываете большие массивы данных
|
|
251
|
+
- Выполняете сложные вычисления
|
|
252
|
+
- Парсите или трансформируете данные
|
|
253
|
+
- Обрабатываете изображения/видео
|
|
254
|
+
- Нужно использовать все ядра CPU
|
|
255
|
+
|
|
256
|
+
**❌ Не используйте когда:**
|
|
257
|
+
- Простые операции (быстрее выполнить последовательно)
|
|
258
|
+
- I/O операции (файлы, сеть, БД) - они уже асинхронные
|
|
259
|
+
- Работаете с DOM (только в Node.js)
|
|
260
|
+
|
|
261
|
+
## 📈 Как выбрать размер пула?
|
|
262
|
+
|
|
263
|
+
```typescript
|
|
264
|
+
import os from 'os';
|
|
265
|
+
|
|
266
|
+
// Оптимально: количество CPU ядер
|
|
267
|
+
const pool = new ThreadPool(os.cpus().length);
|
|
268
|
+
|
|
269
|
+
// Для CPU-интенсивных задач
|
|
270
|
+
const pool = new ThreadPool(os.cpus().length - 1); // оставить 1 ядро для системы
|
|
271
|
+
|
|
272
|
+
// Для смешанной нагрузки
|
|
273
|
+
const pool = new ThreadPool(os.cpus().length * 2);
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
## 🤝 Сравнение с альтернативами
|
|
277
|
+
|
|
278
|
+
| Решение | Простота | Производительность | TypeScript | Размер |
|
|
279
|
+
|---------|----------|-------------------|------------|--------|
|
|
280
|
+
| **stardust-parallel-js** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ✅ Полная | 9.3kB |
|
|
281
|
+
| worker_threads | ⭐⭐ | ⭐⭐⭐⭐⭐ | ⚠️ Частичная | Встроено |
|
|
282
|
+
| cluster | ⭐⭐ | ⭐⭐⭐ | ⚠️ Частичная | Встроено |
|
|
283
|
+
| child_process | ⭐ | ⭐⭐ | ❌ Нет | Встроено |
|
|
284
|
+
|
|
285
|
+
## 🚀 Roadmap
|
|
286
|
+
|
|
287
|
+
- [ ] Поддержка transferable objects для больших данных
|
|
288
|
+
- [ ] Автоматический выбор оптимального размера пула
|
|
289
|
+
- [ ] Приоритизация задач
|
|
290
|
+
- [ ] Мониторинг и статистика
|
|
291
|
+
- [ ] Поддержка async функций в потоках
|
|
292
|
+
|
|
293
|
+
## 💬 Обратная связь
|
|
294
|
+
|
|
295
|
+
Нашли баг? Есть идея? [Создайте issue](https://github.com/b1411/stardust-parallel-js/issues)!
|
|
296
|
+
|
|
297
|
+
⭐ Если библиотека помогла вам - поставьте звезду на [GitHub](https://github.com/b1411/stardust-parallel-js)!
|
|
298
|
+
|
|
299
|
+
## 📦 Требования
|
|
300
|
+
|
|
301
|
+
- Node.js >= 14.0.0 (с поддержкой Worker Threads)
|
|
302
|
+
|
|
303
|
+
## 📄 Лицензия
|
|
304
|
+
|
|
305
|
+
MIT © [b1411](https://github.com/b1411)
|
|
306
|
+
|
|
307
|
+
---
|
|
308
|
+
|
|
309
|
+
<p align="center">
|
|
310
|
+
Сделано с ❤️ для Node.js сообщества
|
|
311
|
+
</p>
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "stardust-parallel-js",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.5",
|
|
4
4
|
"description": "Simple parallel execution library for Node.js using Worker Threads. Execute CPU-intensive tasks with thread pools and isolated workers. Supports both regular and arrow functions.",
|
|
5
5
|
"main": "dist/index.js",
|
|
6
6
|
"types": "dist/index.d.ts",
|