🧵 Thready

A lightweight, type-safe thread pool implementation for JavaScript and TypeScript that enables true multithreading using Web Workers.

Note: Thready is a worker pool manager only. You provide your own worker script with your custom logic.

Features

• ✨ Simple API - Easy to use singleton pattern for quick integration
• 🔄 Worker Pooling - Efficiently reuses worker threads instead of creating new ones
• 📦 Zero Dependencies - No external dependencies, just pure JavaScript
• 💪 TypeScript Support - Full type definitions included
• ⚡ Performance - Supports transferable objects for zero-copy data transfer
• 🎯 Smart Queue Management - Automatically manages task queuing and load balancing
• 🔍 Statistics - Built-in monitoring of pool state and performance
• 🎨 Bring Your Own Worker - You write the worker logic, we handle the pooling

Installation

npm install thready-js

or with yarn:

yarn add thready-js

Quick Start

1. Initialize Thready in Your Project

Run the following command to generate configuration and worker template files:

npx thready init

This creates a thready-js/ folder with:

• thready.config.js - Pre-configured thready instance
• thready.worker.mjs - Node.js worker template
• thready.worker.js - Browser worker template

2. Customize Your Worker

Edit thready-js/thready.worker.mjs (or .js for browser) to add your custom task handlers:

// thready-js/thready.worker.mjs
import { parentPort } from 'worker_threads';

if (!parentPort) {
  throw new Error('This script must be run as a worker thread');
}

parentPort.on('message', (message) => {
  const { id, taskType, payload } = message;
  
  try {
    let result;
    
    // Add your custom task handlers here
    switch (taskType) {
      case 'fibonacci':
        result = fibonacci(payload);
        break;
      case 'processData':
        result = processData(payload);
        break;
      default:
        throw new Error(\`Unknown task type: \${taskType}\`);
    }
    
    parentPort.postMessage({ id, type: 'result', payload: result });
  } catch (error) {
    parentPort.postMessage({ id, type: 'error', payload: error.message });
  }
});

function fibonacci(n) {
  if (n <= 1) return n;
  return fibonacci(n - 1) + fibonacci(n - 2);
}

function processData(data) {
  // Your heavy computation here
  return data.map(x => x * 2);
}

3. Use Thready in Your Application

Simply import the pre-configured instance and start executing tasks:

import thready from './thready-js/thready.config.js';

// Execute tasks - thready is already initialized!
async function calculate() {
  try {
    const result = await thready.execute('fibonacci', 40);
    console.log('Result:', result);
  } catch (error) {
    console.error('Task failed:', error);
  }
}

// Cleanup on shutdown
process.on('SIGINT', () => {
  thready.shutdown();
  process.exit(0);
});

That's it! No manual initialization needed - just import and use.

Advanced Usage

Customizing Configuration

Edit thready-js/thready.config.js to customize worker count or worker path:

// thready-js/thready.config.js
import thready from 'thready-js';
import { Worker } from 'worker_threads';
import { join, dirname } from 'path';
import { fileURLToPath } from 'url';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

// Initialize with custom settings
thready.init({
  maxWorkers: 8, // Increase worker count
  worker: () => new Worker(join(__dirname, './thready.worker.mjs'), { type: 'module' }),
});

export default thready;

Using with Vite or Webpack

For browser environments, update the config to use Web Workers:

// thready-js/thready.config.js
import thready from 'thready-js';

// Vite/Webpack
thready.init({
  maxWorkers: 4,
  worker: () => new Worker(new URL('./thready.worker.js', import.meta.url), { type: 'module' })
});

export default thready;

Transferable Objects (Zero-Copy)

For better performance with large data, use transferables:

import thready from './thready-js/thready.config.js';

async function processImage(imageData) {
  const buffer = imageData.buffer;
  
  // Transfer ownership of the buffer (zero-copy)
  const result = await thready.execute(
    'processImage',
    buffer,
    [buffer] // Transferables array
  );
  
  return result;
}

Direct API Usage (Advanced)

If you prefer manual control, you can import threadPool directly:

import { threadPool } from 'thready-js';
import { Worker } from 'worker_threads';

// Manual initialization
threadPool.init({
  maxWorkers: 4,
  worker: () => new Worker('./custom-worker.mjs')
});

const result = await threadPool.execute('taskType', payload);

import { WorkerPool } from 'thready';
### Using WorkerPool Directly

For even more control, use the `WorkerPool` class:

```javascript
import { WorkerPool } from 'thready-js';
import { Worker } from 'worker_threads';

const pool = new WorkerPool({
  maxWorkers: 8,
  worker: () => new Worker('./worker.mjs')
});

const result = await pool.run('taskType', payload);

// Get statistics
const stats = pool.getStats();
console.log(stats);
// {
//   totalWorkers: 8,
//   availableWorkers: 6,
//   activeTasks: 2,
//   queuedTasks: 0
// }

// Cleanup
pool.terminate();

Monitoring Pool Statistics

import thready from './thready-js/thready.config.js';

const stats = thready.getStats();
console.log('Pool status:', stats);
// {
//   totalWorkers: 4,
//   availableWorkers: 2,
//   activeTasks: 2,
//   queuedTasks: 5
// }

Framework Examples

React

import thready from './thready-js/thready.config.js';
import { useEffect, useState } from 'react';

function App() {
  const [result, setResult] = useState(null);
  const [loading, setLoading] = useState(false);

  useEffect(() => {
    // Cleanup on unmount
    return () => thready.shutdown();
  }, []);

  const handleCalculate = async () => {
    setLoading(true);
    try {
      const res = await thready.execute('fibonacci', 40);
      setResult(res);
    } catch (error) {
      console.error(error);
    } finally {
      setLoading(false);
    }
  };

  return (
    <div>
      <button onClick={handleCalculate} disabled={loading}>
        {loading ? 'Calculating...' : 'Calculate Fibonacci'}
      </button>
      {result && <p>Result: {result}</p>}
    </div>
  );
}

Node.js with Worker Threads

The generated thready-js/thready.worker.mjs is already set up for Node.js worker_threads. Just add your task handlers and use it:

// index.js
import thready from './thready-js/thready.config.js';

async function main() {
  const result = await thready.execute('fibonacci', 35);
  console.log('Result:', result);
  
  thready.shutdown();
}

main();

API Reference

CLI Commands

• npx thready init - Generate configuration and worker template files in thready-js/ folder

thready (Default Export)

The pre-configured singleton instance from thready-js/thready.config.js.

Methods

• execute<T>(taskType: string, payload: any, transferables?: Transferable[]): Promise<T>

  Executes a task on the thread pool.

  • taskType: Identifier for the type of work
  • payload: Data to be processed
  • transferables (optional): Array of transferable objects
  • Returns: Promise resolving to the result

• getStats(): object | null

  Returns current pool statistics.

• shutdown(): void

  Terminates all workers and releases resources.

threadPool (Named Export - Advanced)

The singleton instance for manual initialization.

Methods

• init(config: WorkerPoolConfig): void

  Initializes the thread pool with your worker implementation.

  • config.maxWorkers (optional): Maximum number of workers (defaults to CPU cores)
  • config.worker: Path to worker script or factory function that returns a Worker

• execute<T>(taskType: string, payload: any, transferables?: Transferable[]): Promise<T>

• getStats(): object | null

• shutdown(): void

WorkerPool

The underlying pool implementation for direct usage.

Constructor

new WorkerPool(config: WorkerPoolConfig)

Methods

• run<T>(taskType: string, payload: any, transferables?: Transferable[]): Promise<T>
• getStats(): object
• terminate(): void

TypeScript

Full TypeScript support with exported types:

import thready from './thready-js/thready.config.js';
import type { 
  WorkerPoolConfig,
  WorkerMessage,
  WorkerResponse,
  Task
} from 'thready-js';

// Custom typed execution
interface CalculationResult {
  value: number;
  duration: number;
}

const result = await thready.execute<CalculationResult>('calculate', { n: 100 });

Best Practices

1. Run npx thready init: Start with generated templates for quick setup
2. Customize Workers: Edit thready-js/thready.worker.mjs (or .js) with your task handlers
3. Import Config: Use import thready from './thready-js/thready.config.js' - already initialized
4. Cleanup: Always call thready.shutdown() when your application closes
5. Transferables: Use transferables for large data (ArrayBuffers, ImageData) to avoid copying
6. Error Handling: Always wrap execute() calls in try-catch blocks
7. Task Granularity: Break large tasks into smaller chunks for better load balancing

Performance Tips

• Use transferables for data > 1MB
• Adjust maxWorkers in thready-js/thready.config.js to match your workload
• Monitor stats with thready.getStats() to tune pool size
• Reuse the same worker script for multiple task types
• Keep worker scripts focused and pure

Browser Support

Works in all modern browsers that support Web Workers:

• Chrome 4+
• Firefox 3.5+
• Safari 4+
• Edge (all versions)

License

ISC © Ram Krishna Yadav

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Issues

Found a bug or have a feature request? Open an issue

Links

• GitHub Repository
• npm Package