gonex - v1.5.8

High-Performance Go-Inspired Concurrency with True Parallelism for Node.js

A comprehensive TypeScript library that brings Go's powerful concurrency primitives to Node.js with true parallelism using Worker Threads, enabling robust, scalable concurrent programming patterns with multi-core performance.

Features

Core Concurrency Primitives

Goroutines - Lightweight concurrent functions with automatic scheduling
Channels - Typed communication between goroutines (buffered/unbuffered)
Select - Non-blocking channel operations with multiple cases
WaitGroup - Synchronization for multiple goroutines
Mutex - Mutual exclusion locks for shared resources
RWMutex - Read-write mutex for concurrent read access
Once - One-time initialization guarantees
Cond - Condition variables for signaling
Semaphore - Resource limiting and access control
Context - Cancellation, deadlines, and request-scoped values

True Parallelism with Worker Threads

Multi-Core Execution - Utilize all CPU cores for CPU-intensive tasks
Automatic Load Balancing - Round-robin distribution across worker threads
Performance Optimized - Minimal overhead with direct function execution
Smart Fallback - Automatic fallback to event-loop for I/O-bound tasks
Execution Mode Tracking - Clear logging of event-loop vs worker-thread execution
External Imports - Support for Node.js built-in modules and third-party packages in worker threads

Timing and Scheduling

Ticker - Periodic events with configurable intervals
Timer - One-time delayed events
Sleep - Cooperative yielding and delays

Advanced Patterns

Worker Pool - Managed goroutine pools for controlled concurrency
Pipeline - Chained processing with backpressure
Fan-out/Fan-in - Parallel processing patterns
Rate Limiter - Request throttling and rate control
Circuit Breaker - Fault tolerance and failure handling
Retry - Automatic retry mechanisms with exponential backoff

Installation

npm install gonex

📦 NPM Package

This package is available on npm as gonex.

Install with:

npm install gonex
# or
yarn add gonex
# or
pnpm add gonex

🚀 Quick Start

import { go, channel, select, waitGroup } from 'gonex';

// Simple goroutine (event-loop)
go(async () => {
  console.log('Hello from goroutine!');
});

// Channel communication
const ch = channel<string>();
go(async () => {
  await ch.send('Hello from sender!');
});

go(async () => {
  const msg = await ch.receive();
  console.log(msg); // "Hello from sender!"
});

// WaitGroup synchronization
const wg = waitGroup();
for (let i = 0; i < 3; i++) {
  wg.add(1);
  go(async () => {
    await sleep(1000);
    console.log('Worker completed');
    wg.done();
  });
}
await wg.wait();
console.log('All workers completed');

await shutdownParallelScheduler();

🚀 External imports in worker threads

import { initializeParallelScheduler, shutdownParallelScheduler } from 'gonex';

await initializeParallelScheduler({ useWorkerThreads: true });

const result = await go(
  async () => {
    const fs = require('node:fs');
    const crypto = require('node:crypto');
    const moment = (await import('moment')).default;

    const moment_res = {
      version: moment.version,
      now: moment().format(),
      isValid: moment().isValid(),
    };

    return {
      fileExists: fs.existsSync('/tmp/test'),
      randomBytes: crypto.randomBytes(4).toString('hex'),
      ...moment_res,
    };
  },
  [],
  { useWorkerThreads: true }
);

🚀 Parallelism Examples

CPU-Intensive Tasks with True Parallelism

import { go, goAll } from 'gonex';

// CPU-intensive tasks run in parallel across multiple cores
const heavyTasks = [
  () => {
    let result = 0;
    for (let i = 0; i < 1000000000; i++) {
      result += Math.sqrt(i);
    }
    return result;
  },
  () => {
    let result = 0;
    for (let i = 0; i < 1000000000; i++) {
      result += Math.pow(i, 2);
    }
    return result;
  },
];

// Execute in parallel using worker threads
const results = await goAll(heavyTasks, [], { useWorkerThreads: true });
console.log('All tasks completed in parallel!');

Performance Comparison

import { go, goAll } from 'gonex';

// Event-loop execution (single-threaded)
const eventLoopResults = await goAll(tasks, [], { useWorkerThreads: false });
// Execution time: ~16 seconds

// Worker thread execution (multi-core)
const parallelResults = await goAll(tasks, [], { useWorkerThreads: true });
// Execution time: ~6 seconds (2.6x faster!)