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.
Files changed (3) hide show
  1. package/README.md +101 -102
  2. package/README.ru.md +311 -0
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -9,79 +9,81 @@
9
9
  [![Bundle Size](https://img.shields.io/badge/bundle%20size-9.3kB-brightgreen)](https://www.npmjs.com/package/stardust-parallel-js)
10
10
  [![GitHub stars](https://img.shields.io/github/stars/b1411/stardust-parallel-js.svg?style=social)](https://github.com/b1411/stardust-parallel-js)
11
11
 
12
- **Ускорьте свои Node.js приложения до 3x** с помощью простого API для параллельного выполнения задач!
12
+ > 📖 **Other languages:** [Русский](./README.ru.md)
13
13
 
14
- Библиотека для параллельного выполнения JavaScript/TypeScript функций с использованием Worker Threads в Node.js.
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
- Реальные бенчмарки на 4-ядерном CPU:
18
+ ## 🚀 Performance
19
19
 
20
- | Задача | Последовательно | Параллельно (4 потока) | Ускорение |
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
- > 💡 **Результат**: до **63% улучшения** производительности на CPU-интенсивных задачах!
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
- - 🚀 **До 3x быстрее** - реальное ускорение на многоядерных процессорах
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
- **За 30 секунд** вы можете ускорить обработку массивов в 2-3 раза:
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
- // С stardust-parallel-js - быстро!
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
- Используйте `ThreadPool` для обработки множества задач с максимальной эффективностью:
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
- // Создаем пул из 4 потоков (по числу ядер CPU)
78
+ // Create a pool of 4 threads (matching CPU cores)
77
79
  const pool = new ThreadPool(4);
78
80
 
79
- // 🎯 Обработка массива - как обычный map(), но параллельно!
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
- Используйте `Thread` для разовых операций:
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
- // Обрабатываем 100 изображений параллельно
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
- - 🔒 Функции выполняются в изолированном контексте (отдельный Worker Thread)
240
- - 📦 Аргументы и результаты должны быть сериализуемыми
241
- - 🚫 Замыкания не работают - функции не имеют доступа к внешним переменным
242
- - ✅ Поддерживаются обычные и стрелочные функции
243
- - ✅ `require()` доступен внутри функций для использования Node.js модулей
244
- - ⚡ Лучше всего подходит для CPU-интенсивных задач (вычисления, обработка данных)
245
- - 💡 Для I/O операций (чтение файлов, сеть) используйте async/await вместо потоков
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
- **✅ Используйте stardust-parallel-js когда:**
250
- - Обрабатываете большие массивы данных
251
- - Выполняете сложные вычисления
252
- - Парсите или трансформируете данные
253
- - Обрабатываете изображения/видео
254
- - Нужно использовать все ядра CPU
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
- - Работаете с DOM (только в Node.js)
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
- // Оптимально: количество CPU ядер
265
+ // Optimal: number of CPU cores
267
266
  const pool = new ThreadPool(os.cpus().length);
268
267
 
269
- // Для CPU-интенсивных задач
270
- const pool = new ThreadPool(os.cpus().length - 1); // оставить 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
- | Решение | Простота | Производительность | TypeScript | Размер |
279
- |---------|----------|-------------------|------------|--------|
280
- | **stardust-parallel-js** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ✅ Полная | 9.3kB |
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
- - [ ] Поддержка transferable objects для больших данных
288
- - [ ] Автоматический выбор оптимального размера пула
289
- - [ ] Приоритизация задач
290
- - [ ] Мониторинг и статистика
291
- - [ ] Поддержка async функций в потоках
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
- Нашли баг? Есть идея? [Создайте issue](https://github.com/b1411/stardust-parallel-js/issues)!
294
+ Found a bug? Have an idea? [Create an issue](https://github.com/b1411/stardust-parallel-js/issues)!
296
295
 
297
- Если библиотека помогла вам - поставьте звезду на [GitHub](https://github.com/b1411/stardust-parallel-js)!
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 (с поддержкой Worker Threads)
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
- Сделано с ❤️ для Node.js сообщества
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
+ [![npm version](https://img.shields.io/npm/v/stardust-parallel-js.svg)](https://www.npmjs.com/package/stardust-parallel-js)
4
+ [![npm downloads](https://img.shields.io/npm/dm/stardust-parallel-js.svg)](https://www.npmjs.com/package/stardust-parallel-js)
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
6
+ [![Coverage](https://img.shields.io/badge/coverage-77%25-yellowgreen.svg)](https://github.com/b1411/stardust-parallel-js)
7
+ [![Node.js Version](https://img.shields.io/node/v/stardust-parallel-js.svg)](https://nodejs.org)
8
+ [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
9
+ [![Bundle Size](https://img.shields.io/badge/bundle%20size-9.3kB-brightgreen)](https://www.npmjs.com/package/stardust-parallel-js)
10
+ [![GitHub stars](https://img.shields.io/github/stars/b1411/stardust-parallel-js.svg?style=social)](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.4",
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",