feat: add ESM and CommonJS dual module support (v1.1.0)

Author: mdwekat

.changeset/major-v1.md

@@ -9,6 +9,9 @@ node_modules
 
 # Compiled Files
 dist
+dist/cjs
+dist/esm
+dist/types
 benchmark/dist
 
 # Logs and databases

.gitignore

@@ -1,5 +1,69 @@
 # Changelog
 
+## 2.0.0
+
+### Major Changes
+
+- ad1eede: Production-ready v1.0.0 release with enterprise features:
+  - Job timeout & cancellation with AbortController support
+  - Priority queue system (HIGH, NORMAL, LOW priorities)
+  - Worker health monitoring and automatic restart on failure
+  - Real-time metrics and performance monitoring
+  - Auto-scaling thread pool with configurable thresholds
+  - Strict mode security validation (enabled by default)
+  - Comprehensive benchmark suite vs competitors (Piscina, Workerpool, Tinypool)
+  - Full TypeScript strict mode with zero linter errors
+  - 20+ new comprehensive tests covering all features
+  - Complete documentation overhaul (README, SECURITY, CHANGELOG, CONTRIBUTING)
+  - Advanced examples for all features
+  - Event-driven pool closing (replaced inefficient polling)
+  - Enhanced error handling with full stack trace preservation
+
+### Minor Changes
+
+- Add full ESM (ES Modules) and CommonJS dual module support:
+  - Dual build system with separate CJS and ESM outputs
+  - Proper package.json exports field with conditional exports
+  - Module type hints in dist folders for better resolution
+  - Universal worker path resolution for both module systems
+  - Compatibility tests for both ESM and CJS
+  - Tree-shaking support in ESM builds
+  - Works seamlessly in modern bundlers (Vite, Rollup) and legacy tools (Webpack, Node CJS)
+  - Fully backward compatible - existing CommonJS users unaffected
+
+## 1.1.0
+
+### Minor Changes
+
+- **Full ESM (ES Modules) support**: Package now supports both ESM and CommonJS
+- **Dual build system**: Separate builds for CJS (`dist/cjs`) and ESM (`dist/esm`) with proper conditional exports
+- **Package.json exports field**: Proper conditional exports for modern tooling and tree-shaking
+- **Module type hints**: package.json files in dist folders for better module resolution
+- **Compatibility tests**: Dedicated ESM and CJS compatibility test suites
+- **Universal worker path resolution**: Works seamlessly in both ESM and CJS environments
+
+### Changed
+
+- Build system now outputs three separate builds: `dist/cjs`, `dist/esm`, `dist/types`
+- Worker path resolution improved to detect and handle both module systems automatically
+- Package exports configured for optimal tree-shaking in ESM
+- Documentation updated with both ESM and CJS usage examples
+
+### Technical Details
+
+- Main entry point (`require`): `./dist/cjs/index.js`
+- Module entry point (`import`): `./dist/esm/index.js`
+- TypeScript types: `./dist/types/index.d.ts`
+- Requires Node.js 12.20+ for conditional exports support
+
+### Benefits
+
+- ✅ Modern ESM support for Vite, Rollup, and modern bundlers
+- ✅ Tree-shaking support in ESM builds
+- ✅ Backward compatible with CommonJS projects
+- ✅ Future-proof module architecture
+- ✅ Works in both Next.js App Router (ESM) and Pages Router (CJS)
+
 ## 1.0.0
 
 ### Major Changes

CHANGELOG.md

@@ -12,6 +12,7 @@ NodeSwarm is a high-performance, feature-rich library for managing worker thread
 
 - **🚀 High Performance**: Optimized for throughput and latency
 - **⚡ Simple API**: Execute any function in a thread with one line
+- **📦 Dual Module Support**: Works with both ESM and CommonJS
 - **🎯 Priority Queue**: HIGH, NORMAL, LOW priority job scheduling
 - **⏱️ Timeout & Cancellation**: Built-in timeout and AbortController support
 - **📊 Metrics**: Real-time monitoring of pool performance
@@ -37,6 +38,8 @@ pnpm add nodeswarm
 
 ## Quick Start
 
+### ESM (Modern)
+
 ```typescript
 import { ThreadPool } from "nodeswarm";
 
@@ -49,6 +52,21 @@ console.log(result); // 15
 await pool.close();
 ```
 
+### CommonJS (Legacy)
+
+```javascript
+const { ThreadPool } = require("nodeswarm");
+
+(async () => {
+  const pool = new ThreadPool();
+
+  const result = await pool.thread((a, b) => a + b, 5, 10);
+  console.log(result); // 15
+
+  await pool.close();
+})();
+```
+
 ## Performance
 
 NodeSwarm delivers excellent performance across different workload types:

README.md

@@ -1,20 +1,49 @@
 {
   "name": "nodeswarm",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Lightweight library for managing worker threads and parallel execution of tasks in Node.js.",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "type": "commonjs",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "SECURITY.md"
+  ],
   "repository": "git@github.com:dwekat/nodeswarm.git",
   "bugs": {
     "url": "https://github.com/dwekat/nodeswarm/issues"
   },
   "homepage": "https://github.com/dwekat/nodeswarm#readme",
   "scripts": {
-    "build": "rimraf dist && tsc",
+    "build": "npm run build:clean && npm run build:cjs && npm run build:fix-cjs && npm run build:esm && npm run build:types && npm run build:hints",
+    "build:clean": "rimraf dist",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:fix-cjs": "node scripts/fix-cjs-imports.js",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:types": "tsc -p tsconfig.types.json",
+    "build:hints": "node scripts/create-package-hints.js",
     "build:benchmark": "tsc -p benchmark/tsconfig.json",
     "pretest": "rimraf test_tmp && tsc -p tsconfig.worker.json",
     "posttest": "rimraf test_tmp",
     "test": "jest",
+    "test:compat": "node test/cjs-compat.test.cjs && node test/esm-compat.test.mjs",
     "benchmark": "npm run build && npm run build:benchmark && node benchmark/dist/index.js",
     "benchmark:compare": "npm run build && npm run build:benchmark && node benchmark/dist/compare.js",
     "prepublishOnly": "npm run build",

package.json

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * Create package.json type hints in dist folders
+ */
+const fs = require('fs');
+const path = require('path');
+
+const cjsPackage = { type: 'commonjs' };
+const esmPackage = { type: 'module' };
+
+const cjsPath = path.join(__dirname, '../dist/cjs/package.json');
+const esmPath = path.join(__dirname, '../dist/esm/package.json');
+
+// Ensure directories exist
+fs.mkdirSync(path.dirname(cjsPath), { recursive: true });
+fs.mkdirSync(path.dirname(esmPath), { recursive: true });
+
+// Write package.json files
+fs.writeFileSync(cjsPath, JSON.stringify(cjsPackage, null, 2) + '\n');
+fs.writeFileSync(esmPath, JSON.stringify(esmPackage, null, 2) + '\n');
+
+console.log('✓ Created package.json type hints in dist folders');
+

scripts/create-package-hints.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * Fix import.meta references in CJS build
+ * Replaces the ESM path code with a throw statement since it's unreachable
+ */
+const fs = require('fs');
+const path = require('path');
+
+const threadPoolPath = path.join(__dirname, '../dist/cjs/ThreadPool.js');
+
+let content = fs.readFileSync(threadPoolPath, 'utf8');
+
+// Replace the import.meta.url line with a throw
+// This code is unreachable in CJS (guarded by __dirname check)
+// but Node still parses it and throws syntax error
+content = content.replace(
+  /const url = new URL\("\.\/worker\.js", import\.meta\.url\);/g,
+  'throw new Error("This code path should never execute in CommonJS");'
+);
+
+fs.writeFileSync(threadPoolPath, content, 'utf8');
+console.log('✓ Fixed import.meta references in CJS build');
+

scripts/fix-cjs-imports.js

@@ -1,9 +1,10 @@
 import os from "os";
-import { resolve } from "path";
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
 import { Worker } from "worker_threads";
-import { PriorityQueue } from "./priorityQueue";
-import { MetricsTracker } from "./metrics";
-import { validateFunction, validateArguments } from "./validation";
+import { PriorityQueue } from "./priorityQueue.js";
+import { MetricsTracker } from "./metrics.js";
+import { validateFunction, validateArguments } from "./validation.js";
 import {
   ThreadPoolConfig,
   ThreadOptions,
@@ -12,10 +13,38 @@ import {
   WorkerMessage,
   ThreadPoolMetrics,
   WorkerState,
-} from "./types";
+} from "./types.js";
 
 // Re-export WorkerMessage for worker.ts
-export type { WorkerMessage } from "./types";
+export type { WorkerMessage } from "./types.js";
+
+/**
+ * Get worker path - resolved at module load time
+ * In CJS: uses __dirname which is always defined
+ * In ESM: uses import.meta.url
+ * 
+ * Note: The __dirname check returns early in CJS builds, so the import.meta
+ * code is never executed in CJS (avoiding syntax errors).
+ */
+let cachedWorkerPath: string | null = null;
+
+function getWorkerPath(): string {
+  if (cachedWorkerPath) return cachedWorkerPath;
+  
+  // CommonJS: __dirname is defined
+  // This check succeeds and returns in CJS, so import.meta below never runs
+  if (typeof __dirname !== "undefined") {
+    cachedWorkerPath = resolve(__dirname, "./worker.js");
+    return cachedWorkerPath;
+  }
+  
+  // ESM: __dirname is not defined, use import.meta.url
+  // This code only executes in ESM builds where import.meta is available
+  // @ts-ignore - TypeScript may not recognize import.meta in all contexts
+  const url = new URL("./worker.js", import.meta.url);
+  cachedWorkerPath = fileURLToPath(url);
+  return cachedWorkerPath;
+}
 
 /**
  * ThreadPool class manages a pool of worker threads and schedules jobs
@@ -31,7 +60,7 @@ export class ThreadPool {
   private metrics: MetricsTracker;
   private healthCheckInterval?: NodeJS.Timeout;
 
-  private static readonly workerPath = resolve(__dirname, "./worker.js");
+  private static readonly workerPath = getWorkerPath();
   private readonly config: Required<ThreadPoolConfig>;
 
   /**

src/ThreadPool.ts

@@ -1,4 +1,4 @@
-export * from "./ThreadPool";
-export * from "./types";
-export { PriorityQueue } from "./priorityQueue";
-export { MetricsTracker } from "./metrics";
+export * from "./ThreadPool.js";
+export * from "./types.js";
+export { PriorityQueue } from "./priorityQueue.js";
+export { MetricsTracker } from "./metrics.js";

src/index.ts

@@ -1,4 +1,4 @@
-import { Job, Priority } from "./types";
+import { Job, Priority } from "./types.js";
 
 /**
  * Priority queue implementation for job scheduling