stardust-parallel-js 1.0.0 → 1.0.2

package/README.md

@@ -1,42 +1,89 @@
-# parallel.js
+# ⚡ stardust-parallel-js
+
+[![npm version](https://img.shields.io/npm/v/stardust-parallel-js.svg)](https://www.npmjs.com/package/stardust-parallel-js)
+[![npm downloads](https://img.shields.io/npm/dm/stardust-parallel-js.svg)](https://www.npmjs.com/package/stardust-parallel-js)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Coverage](https://img.shields.io/badge/coverage-77%25-yellowgreen.svg)](https://github.com/b1411/stardust-parallel-js)
+[![Node.js Version](https://img.shields.io/node/v/stardust-parallel-js.svg)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
+[![Bundle Size](https://img.shields.io/badge/bundle%20size-9.3kB-brightgreen)](https://www.npmjs.com/package/stardust-parallel-js)
+[![GitHub stars](https://img.shields.io/github/stars/b1411/stardust-parallel-js.svg?style=social)](https://github.com/b1411/stardust-parallel-js)
+
+**Ускорьте свои Node.js приложения до 3x** с помощью простого API для параллельного выполнения задач!
 
 Библиотека для параллельного выполнения JavaScript/TypeScript функций с использованием Worker Threads в Node.js.
 
-## Возможности
+## 🚀 Производительность
+
+Реальные бенчмарки на 4-ядерном CPU:
+
+| Задача | Последовательно | Параллельно (4 потока) | Ускорение |
+|--------|----------------|------------------------|-----------|
+| **Вычисление Fibonacci(35-42)** | 5113 мс | 2606 мс | **1.96x** 🔥 |
+| **Обработка 50 элементов** | 936 мс | 344 мс | **2.72x** ⚡ |
+
+> 💡 **Результат**: до **63% улучшения** производительности на CPU-интенсивных задачах!
+
+## ✨ Возможности
 
-- ✨ Простой API для параллельного выполнения функций
-- 🔄 Пул потоков для эффективного управления ресурсами
-- 🚀 Отдельные потоки для разовых задач
-- 📦 TypeScript поддержка из коробки
-- 🛡️ Автоматическое восстановление упавших потоков
-- ⚡ Асинхронная обработка задач с очередью
+- 🚀 **До 3x быстрее** - реальное ускорение на многоядерных процессорах
+- 💡 **Простой API** - начните использовать за 2 минуты
+- 🔄 **Пул потоков** - эффективное управление ресурсами
+- ⚡ **Отдельные потоки** - для разовых задач
+- 📦 **TypeScript** - полная поддержка из коробки
+- 🛡️ **Надежность** - автоматическое восстановление упавших потоков
+- 🎯 **Простота** - работает как обычный `map()`, но параллельно
 
-## Установка
+## 📦 Установка
 
 ```bash
-npm install parallel.js
+npm install stardust-parallel-js
 # или
-pnpm install parallel.js
+pnpm install stardust-parallel-js
 # или
-yarn add parallel.js
+yarn add stardust-parallel-js
+```
+
+## 🎯 Быстрый старт
+
+**За 30 секунд** вы можете ускорить обработку массивов в 2-3 раза:
+
+```typescript
+import { ThreadPool } from 'stardust-parallel-js';
+
+const pool = new ThreadPool(4);
+
+// Обычный код - медленно 🐌
+const results = data.map(item => heavyComputation(item));
+
+// С stardust-parallel-js - быстро! ⚡
+const results = await pool.map(data, item => heavyComputation(item));
+
+await pool.terminate();
 ```
 
-## Использование
+**Вот и всё!** Ваш код теперь работает параллельно на всех ядрах процессора.
+
+## 📚 Использование
 
-### ThreadPool - Пул потоков
+### ThreadPool - Пул потоков (рекомендуется)
 
-Используйте `ThreadPool` для выполнения множества задач с ограниченным количеством потоков:
+Используйте `ThreadPool` для обработки множества задач с максимальной эффективностью:
 
 ```typescript
-import { ThreadPool } from 'parallel.js';
+import { ThreadPool } from 'stardust-parallel-js';
 
-// Создаем пул из 4 потоков
+// Создаем пул из 4 потоков (по числу ядер CPU)
 const pool = new ThreadPool(4);
 
-// Выполнение одной задачи
+// 🎯 Обработка массива - как обычный map(), но параллельно!
+const numbers = [1, 2, 3, 4, 5, 6, 7, 8];
+const squares = await pool.map(numbers, (n: number) => n * n);
+console.log(squares); // [1, 4, 9, 16, 25, 36, 49, 64]
+
+// 💪 CPU-интенсивные вычисления
 const result = await pool.execute(
   (n: number) => {
-    // Тяжелые вычисления
     let sum = 0;
     for (let i = 0; i < n; i++) {
       sum += Math.sqrt(i);
@@ -46,43 +93,93 @@ const result = await pool.execute(
   [1000000]
 );
 
-console.log(result);
-
-// Параллельная обработка массива
-const numbers = [1, 2, 3, 4, 5, 6, 7, 8];
-const squares = await pool.map(numbers, (n: number) => n * n);
-console.log(squares); // [1, 4, 9, 16, 25, 36, 49, 64]
-
-// Не забудьте остановить пул
+// Освобождаем ресурсы
 await pool.terminate();
 ```
 
-### Thread - Отдельный поток
+### Thread - Отдельный поток (для простых задач)
 
-Используйте `Thread` для разовых задач:
+Используйте `Thread` для разовых операций:
 
 ```typescript
-import { Thread } from 'parallel.js';
+import { Thread } from 'stardust-parallel-js';
 
-// Создаем поток для выполнения функции
+// Запустить и дождаться результата
 const thread = new Thread(
-  (text: string) => {
-    return text.toUpperCase();
-  },
+  (text: string) => text.toUpperCase(),
   ['hello world']
 );
 
-// Ждем результат
 const result = await thread.join();
 console.log(result); // "HELLO WORLD"
 
-// Стрелочные функции также поддерживаются
+// Стрелочные функции работают!
 const thread2 = new Thread(x => x * 2, [21]);
-const result2 = await thread2.join();
-console.log(result2); // 42
+console.log(await thread2.join()); // 42
 ```
 
-## API
+## 💡 Примеры из реальной жизни
+
+### Обработка изображений
+
+```typescript
+import { ThreadPool } from 'stardust-parallel-js';
+
+const pool = new ThreadPool(8);
+const images = ['img1.jpg', 'img2.jpg', /* ... */ 'img100.jpg'];
+
+// Обрабатываем 100 изображений параллельно
+const processed = await pool.map(images, (path: string) => {
+  const fs = require('fs');
+  const sharp = require('sharp');
+  // Сложная обработка изображения
+  return processImage(path);
+});
+
+await pool.terminate();
+```
+
+### Парсинг больших данных
+
+```typescript
+const pool = new ThreadPool(4);
+const chunks = splitDataIntoChunks(bigData, 1000);
+
+// Парсим каждый чунк параллельно
+const parsed = await pool.map(chunks, (chunk: any[]) => {
+  return chunk.map(item => parseComplexData(item));
+});
+
+await pool.terminate();
+```
+
+### Вычисления и аналитика
+
+```typescript
+const pool = new ThreadPool(4);
+
+const results = await pool.map([35, 36, 37, 38, 39, 40], n => {
+  function fibonacci(num: number): number {
+    if (num <= 1) return num;
+    return fibonacci(num - 1) + fibonacci(num - 2);
+  }
+  return fibonacci(n);
+});
+
+await pool.terminate();
+```
+
+## 📊 Бенчмарки
+
+Запустите сами и убедитесь в производительности:
+
+```bash
+npm run build
+npx tsx benchmarks/cpu-intensive.ts
+npx tsx benchmarks/data-processing.ts
+```
+
+## 🎓 API Reference
 
 ### ThreadPool
 
@@ -137,92 +234,78 @@ const thread = new Thread((x: number) => x * x, [5]);
 const result = await thread.join();
 ```
 
-## Примеры
+## ⚠️ Важные замечания
 
-### Обработка больших данных
+- 🔒 Функции выполняются в изолированном контексте (отдельный Worker Thread)
+- 📦 Аргументы и результаты должны быть сериализуемыми
+- 🚫 Замыкания не работают - функции не имеют доступа к внешним переменным
+- ✅ Поддерживаются обычные и стрелочные функции
+- ✅ `require()` доступен внутри функций для использования Node.js модулей
+- ⚡ Лучше всего подходит для CPU-интенсивных задач (вычисления, обработка данных)
+- 💡 Для I/O операций (чтение файлов, сеть) используйте async/await вместо потоков
 
-```typescript
-import { ThreadPool } from 'parallel.js';
+## 🎯 Когда использовать?
 
-const pool = new ThreadPool(8);
+**✅ Используйте stardust-parallel-js когда:**
+- Обрабатываете большие массивы данных
+- Выполняете сложные вычисления
+- Парсите или трансформируете данные
+- Обрабатываете изображения/видео
+- Нужно использовать все ядра CPU
 
-const data = Array.from({ length: 10000 }, (_, i) => i);
+**❌ Не используйте когда:**
+- Простые операции (быстрее выполнить последовательно)
+- I/O операции (файлы, сеть, БД) - они уже асинхронные
+- Работаете с DOM (только в Node.js)
 
-const processed = await pool.map(data, (item: number) => {
-  // Сложная обработка каждого элемента
-  return Math.sin(item) * Math.cos(item);
-});
-### Вычисление чисел Фибоначчи
+## 📈 Как выбрать размер пула?
 
 ```typescript
-import { ThreadPool } from 'parallel.js';
+import os from 'os';
 
-const pool = new ThreadPool(4);
-
-const numbers = [35, 36, 37, 38, 39, 40];
-
-const results = await pool.map(numbers, n => {
-  function fibonacci(num) {
-    if (num <= 1) return num;
-    return fibonacci(num - 1) + fibonacci(num - 2);
-  }
-  return fibonacci(n);
-});
+// Оптимально: количество CPU ядер
+const pool = new ThreadPool(os.cpus().length);
 
-console.log(results); // [9227465, 14930352, 24157817, ...]
+// Для CPU-интенсивных задач
+const pool = new ThreadPool(os.cpus().length - 1); // оставить 1 ядро для системы
 
-await pool.terminate();
+// Для смешанной нагрузки
+const pool = new ThreadPool(os.cpus().length * 2);
 ```
 
-### Использование встроенных модулей Node.js
+## 🤝 Сравнение с альтернативами
 
-```typescript
-import { ThreadPool } from 'parallel.js';
+| Решение | Простота | Производительность | TypeScript | Размер |
+|---------|----------|-------------------|------------|--------|
+| **stardust-parallel-js** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ✅ Полная | 9.3kB |
+| worker_threads | ⭐⭐ | ⭐⭐⭐⭐⭐ | ⚠️ Частичная | Встроено |
+| cluster | ⭐⭐ | ⭐⭐⭐ | ⚠️ Частичная | Встроено |
+| child_process | ⭐ | ⭐⭐ | ❌ Нет | Встроено |
 
-const pool = new ThreadPool(4);
+## 🚀 Roadmap
 
-// require() доступен внутри функций
-const result = await pool.execute(() => {
-  const fs = require('fs');
-  const path = require('path');
-  return path.join('folder', 'file.txt');
-});
-
-console.log(result); // 'folder/file.txt' или 'folder\\file.txt'
+- [ ] Поддержка transferable objects для больших данных
+- [ ] Автоматический выбор оптимального размера пула
+- [ ] Приоритизация задач
+- [ ] Мониторинг и статистика
+- [ ] Поддержка async функций в потоках
 
-await pool.terminate();
-```eturn response.json();
-});
+## 💬 Обратная связь
 
-await pool.terminate();
-```
+Нашли баг? Есть идея? [Создайте issue](https://github.com/b1411/stardust-parallel-js/issues)!
 
-## Важные замечания
+⭐ Если библиотека помогла вам - поставьте звезду на [GitHub](https://github.com/b1411/stardust-parallel-js)!
 
-- 🔒 Функции, передаваемые в потоки, выполняются в изолированном контексте
-- 📦 Все аргументы и результаты должны быть сериализуемыми (передаются через структурированное клонирование)
-- 🚫 Нельзя использовать замыкания - функции не имеют доступа к внешним переменным из основного потока
-- ✅ Поддерживаются как обычные функции (`function`), так и стрелочные (`=>`)
-- ✅ `require()` и встроенные модули Node.js доступны внутри функций
-- ⚡ Worker Threads лучше всего подходят для CPU-интенсивных задач
-
-## Требования
+## 📦 Требования
 
 - Node.js >= 14.0.0 (с поддержкой Worker Threads)
 
-## Лицензия
-
-ISC
+## 📄 Лицензия
 
-## Разработка
+MIT © [b1411](https://github.com/b1411)
 
-```bash
-# Установка зависимостей
-pnpm install
+---
 
-# Запуск тестов
-pnpm test
-
-# Сборка
-pnpm build
-```
+<p align="center">
+  Сделано с ❤️ для Node.js сообщества
+</p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stardust-parallel-js",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "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.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,9 +12,13 @@
     "type": "git",
     "url": "git+https://github.com/b1411/parallel.js.git"
   },
+  "engines": {
+    "node": ">=14.0.0"
+  },
   "type": "module",
   "scripts": {
     "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "test:coverage": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage",
     "build": "tsc -p ."
   },
   "keywords": [
@@ -48,4 +52,4 @@
   "dependencies": {
     "@datastructures-js/queue": "^4.3.0"
   }
-}
+}