@nadrif/thread 0.1.0

package/src/env.js

@@ -0,0 +1,361 @@
+/**
+ * @file Environment detection for the thread library.
+ *
+ * Detects the current JavaScript runtime and exposes flags for
+ * conditional code paths.  Used internally by Thread, GPUCompute,
+ * and the config loader to pick the right APIs.
+ *
+ * Supported environments:
+ * - **Browser** — Web Workers, Blob URLs, `navigator.gpu`
+ * - **Node.js** — `worker_threads`, `node:worker_threads`
+ * - **Bun** — `bun:ffi`, `node:worker_threads` (Bun's built-in)
+ * - **Deno** — `Deno.Worker`, `Deno.openKv`, `navigator.gpu`
+ * - **Cloudflare Workers** — `workers-runtime` (no `Worker` constructor)
+ * - **Edge runtimes** — Vercel Edge, Netlify Edge, Deno Deploy
+ *
+ * @example
+ * ```js
+ * import { env } from './env.js';
+ *
+ * if (env.isNode) {
+ *   const { Worker } = await import('node:worker_threads');
+ * } else if (env.isBrowser) {
+ *   const worker = new Worker(url);
+ * }
+ * ```
+ *
+ * @module env
+ */
+
+// ---------------------------------------------------------------------------
+// Runtime detection
+// ---------------------------------------------------------------------------
+
+/**
+ * @type {'browser'|'node'|'bun'|'deno'|'edge'|'unknown'}
+ * Detected runtime identifier.
+ */
+const runtime = (() => {
+  // Bun — check first because Bun also satisfies Node checks
+  if (typeof globalThis.Bun !== 'undefined') return 'bun';
+  // Deno
+  if (typeof globalThis.Deno !== 'undefined') return 'deno';
+  // Node.js
+  if (typeof globalThis.process !== 'undefined' && typeof globalThis.process.versions?.node !== 'undefined') return 'node';
+  // Browser (including Web Workers, Service Workers)
+  if (typeof globalThis.navigator !== 'undefined' || typeof globalThis.self !== 'undefined') {
+    // Cloudflare Workers / Vercel Edge — no full `Worker` constructor
+    if (typeof globalThis.caches !== 'undefined' && typeof globalThis.XMLHttpRequest === 'undefined') return 'edge';
+    return 'browser';
+  }
+  // Edge runtime fallback
+  if (typeof globalThis.EdgeRuntime !== 'undefined') return 'edge';
+  return 'unknown';
+})();
+
+/**
+ * @type {'main'|'worker'|'service-worker'|'unknown'}
+ * Current execution context.
+ */
+const context = (() => {
+  // Service Worker
+  if (typeof ServiceWorkerGlobalScope !== 'undefined' && globalThis instanceof ServiceWorkerGlobalScope) return 'service-worker';
+  // Web Worker / Deno Worker / Node worker_threads
+  if (typeof DedicatedWorkerGlobalScope !== 'undefined' && globalThis instanceof DedicatedWorkerGlobalScope) return 'worker';
+  if (typeof SharedWorkerGlobalScope !== 'undefined' && globalThis instanceof SharedWorkerGlobalScope) return 'worker';
+  // Node.js worker_threads
+  if (typeof globalThis.process !== 'undefined' && globalThis.process.env?.IS_WORKER_THREAD === '1') return 'worker';
+  // Bun worker_threads
+  if (typeof globalThis.Bun !== 'undefined' && typeof globalThis.Bun?.sleep === 'function' && typeof globalThis.self === 'undefined') return 'worker';
+  // Main thread
+  if (typeof window !== 'undefined' || typeof globalThis.window !== 'undefined') return 'main';
+  if (typeof globalThis.process !== 'undefined' && typeof globalThis.process.argv !== 'undefined') return 'main';
+  if (typeof globalThis.Deno !== 'undefined') return 'main';
+  return 'unknown';
+})();
+
+// ---------------------------------------------------------------------------
+// Feature detection (cached)
+// ---------------------------------------------------------------------------
+
+/** @type {boolean} `true` if the native `Worker` constructor is available. */
+const hasWorker = (() => {
+  if (typeof Worker !== 'undefined') return true;
+  // Node.js worker_threads has Worker in newer versions
+  try {
+    if (typeof globalThis.require === 'function') {
+      const wt = globalThis.require('node:worker_threads');
+      return typeof wt.Worker === 'function';
+    }
+  } catch { /* ignore */ }
+  return false;
+})();
+
+/** @type {boolean} `true` if WebGPU (`navigator.gpu`) is available. */
+const hasGPU = (() => {
+  if (typeof navigator !== 'undefined' && navigator.gpu) return true;
+  // Deno
+  if (typeof globalThis.Deno !== 'undefined' && globalThis.Deno?.gpu) return true;
+  // Bun — check built-in gpu API
+  if (typeof globalThis.Bun !== 'undefined' && globalThis.Bun?.gpu) return true;
+  return false;
+})();
+
+/** @type {boolean} `true` if `fs` module is available (Node/Bun). */
+const hasFS = (() => {
+  if (typeof globalThis.require === 'function') {
+    try { globalThis.require('node:fs'); return true; } catch { return false; }
+  }
+  if (typeof globalThis.Bun !== 'undefined') return true;
+  return false;
+})();
+
+/** @type {boolean} `true` if `path` module is available (Node/Bun). */
+const hasPath = (() => {
+  if (typeof globalThis.require === 'function') {
+    try { globalThis.require('node:path'); return true; } catch { return false; }
+  }
+  return false;
+})();
+
+/** @type {boolean} `true` if `performance.memory` is available (Chrome). */
+const hasMemoryAPI = (() => {
+  return typeof performance !== 'undefined' && typeof performance.memory !== 'undefined';
+})();
+
+/** @type {boolean} `true` if Blob and URL.createObjectURL are available. */
+const hasBlob = (() => {
+  return typeof Blob !== 'undefined' && typeof URL !== 'undefined' && typeof URL.createObjectURL === 'function';
+})();
+
+/** @type {boolean} `true` if dynamic `import()` is available. */
+const hasDynamicImport = (() => {
+  try {
+    return typeof globalThis.import === 'function' || typeof Function('return import') === 'function';
+  } catch { return false; }
+})();
+
+/** @type {boolean} `true` if the runtime is Bun. */
+const isBun = runtime === 'bun';
+
+/** @type {boolean} `true` if the runtime is Node.js. */
+const isNode = runtime === 'node';
+
+/** @type {boolean} `true` if the runtime is Deno. */
+const isDeno = runtime === 'deno';
+
+/** @type {boolean} `true` if the runtime is a browser (including Web Workers). */
+const isBrowser = runtime === 'browser';
+
+/** @type {boolean} `true` if the runtime is an edge function. */
+const isEdge = runtime === 'edge';
+
+/** @type {boolean} `true` if running in a worker context (not main thread). */
+const isWorker = context === 'worker';
+
+/** @type {boolean} `true` if running on the main thread. */
+const isMainThread = context === 'main';
+
+// ---------------------------------------------------------------------------
+// Platform-specific require/import helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Safely require a Node.js built-in module.
+ *
+ * Returns the module if available, `null` otherwise.  Works in Node.js,
+ * Bun, and environments where `globalThis.require` is defined.
+ *
+ * @param {string} moduleId - Module name (e.g. `'node:fs'`, `'node:path'`).
+ * @returns {any|null} The required module, or `null`.
+ *
+ * @example
+ * ```js
+ * const fs = requireModule('node:fs');
+ * if (fs) {
+ *   const data = fs.readFileSync('config.json', 'utf-8');
+ * }
+ * ```
+ */
+function requireModule(moduleId) {
+  try {
+    if (typeof globalThis.require === 'function') {
+      return globalThis.require(moduleId);
+    }
+  } catch { /* ignore */ }
+  return null;
+}
+
+/**
+ * Get the current working directory.
+ *
+ * Works across Node.js, Bun, Deno, and browser environments.
+ *
+ * @returns {string} The best-effort working directory.
+ *
+ * @example
+ * ```js
+ * const cwd = getCwd();
+ * console.log('Working from:', cwd);
+ * ```
+ */
+function getCwd() {
+  // Node.js / Bun
+  if (typeof process !== 'undefined' && typeof process.cwd === 'function') {
+    return process.cwd();
+  }
+  // Deno
+  if (typeof globalThis.Deno !== 'undefined' && typeof globalThis.Deno.cwd === 'function') {
+    return globalThis.Deno.cwd();
+  }
+  // Browser — use document.baseURI or location
+  if (typeof document !== 'undefined' && document.baseURI) {
+    try { return new URL(document.baseURI).pathname; } catch { /* ignore */ }
+  }
+  if (typeof location !== 'undefined' && location.href) {
+    try { return new URL(location.href).pathname; } catch { /* ignore */ }
+  }
+  return '.';
+}
+
+/**
+ * Read a file synchronously.
+ *
+ * Uses `fs.readFileSync` in Node/Bun, `Deno.readTextFileSync` in Deno,
+ * or returns `null` in browser environments.
+ *
+ * @param {string} filePath - Absolute or relative file path.
+ * @returns {string|null} File contents, or `null` if not readable.
+ *
+ * @example
+ * ```js
+ * const content = readFileSync('./config.json');
+ * if (content) {
+ *   const config = JSON.parse(content);
+ * }
+ * ```
+ */
+function readFileSync(filePath) {
+  // Node.js / Bun
+  const fs = requireModule('node:fs');
+  if (fs && typeof fs.readFileSync === 'function') {
+    return fs.readFileSync(filePath, 'utf-8');
+  }
+  // Deno
+  if (typeof globalThis.Deno !== 'undefined' && typeof globalThis.Deno.readTextFileSync === 'function') {
+    try { return globalThis.Deno.readTextFileSync(filePath); } catch { return null; }
+  }
+  return null;
+}
+
+/**
+ * Check if a file exists.
+ *
+ * @param {string} filePath - Path to check.
+ * @returns {boolean} `true` if the file exists and is accessible.
+ *
+ * @example
+ * ```js
+ * if (fileExists('./thread.config.js')) {
+ *   loadConfig();
+ * }
+ * ```
+ */
+function fileExists(filePath) {
+  // Node.js / Bun
+  const fs = requireModule('node:fs');
+  if (fs && typeof fs.existsSync === 'function') {
+    return fs.existsSync(filePath);
+  }
+  // Deno
+  if (typeof globalThis.Deno !== 'undefined' && typeof globalThis.Deno.statSync === 'function') {
+    try { globalThis.Deno.statSync(filePath); return true; } catch { return false; }
+  }
+  return false;
+}
+
+/**
+ * Resolve a file path relative to the current working directory.
+ *
+ * @param {string} ...segments - Path segments to join.
+ * @returns {string} Resolved absolute path.
+ *
+ * @example
+ * ```js
+ * const configPath = resolvePath('thread.config.js');
+ * const fullPath = resolvePath('src', 'config', 'index.js');
+ * ```
+ */
+function resolvePath(...segments) {
+  // Node.js / Bun
+  const path = requireModule('node:path');
+  if (path) {
+    return path.resolve(getCwd(), ...segments);
+  }
+  // Deno
+  if (typeof globalThis.Deno !== 'undefined' && typeof globalThis.Deno.resolve === 'function') {
+    return globalThis.Deno.resolve(...segments);
+  }
+  // Fallback — simple join
+  return [getCwd(), ...segments].join('/').replace(/\/+/g, '/');
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+/**
+ * Comprehensive environment information for the thread library.
+ *
+ * Provides runtime detection, feature flags, and platform-specific
+ * helpers for cross-environment compatibility.
+ *
+ * @type {{
+ *   runtime: 'browser'|'node'|'bun'|'deno'|'edge'|'unknown',
+ *   context: 'main'|'worker'|'service-worker'|'unknown',
+ *   isBrowser: boolean,
+ *   isNode: boolean,
+ *   isBun: boolean,
+ *   isDeno: boolean,
+ *   isEdge: boolean,
+ *   isWorker: boolean,
+ *   isMainThread: boolean,
+ *   hasWorker: boolean,
+ *   hasGPU: boolean,
+ *   hasFS: boolean,
+ *   hasPath: boolean,
+ *   hasMemoryAPI: boolean,
+ *   hasBlob: boolean,
+ *   hasDynamicImport: boolean,
+ *   requireModule: function(string): any|null,
+ *   getCwd: function(): string,
+ *   readFileSync: function(string): string|null,
+ *   fileExists: function(string): boolean,
+ *   resolvePath: function(...string): string
+ * }}
+ */
+export const env = Object.freeze({
+  runtime,
+  context,
+  isBrowser,
+  isNode,
+  isBun,
+  isDeno,
+  isEdge,
+  isWorker,
+  isMainThread,
+  hasWorker,
+  hasGPU,
+  hasFS,
+  hasPath,
+  hasMemoryAPI,
+  hasBlob,
+  hasDynamicImport,
+  requireModule,
+  getCwd,
+  readFileSync,
+  fileExists,
+  resolvePath,
+});
+
+export default env;

package/src/error.js

@@ -0,0 +1,340 @@
+/**
+ * @file Error hierarchy for the thread module.
+ *
+ * Every error in the thread system extends {@link ThreadError}, so a single
+ * `catch (e) { if (e instanceof ThreadError) }` block handles them all.
+ * Use the more specific subclasses to differentiate timeout, abort,
+ * termination, health, and dependency failures.
+ *
+ * @example
+ * ```js
+ * import {
+ *   ThreadError,
+ *   ThreadTimeoutError,
+ *   ThreadAbortError,
+ *   ThreadTerminatedError,
+ *   ThreadHealthError,
+ *   ThreadDependencyError,
+ * } from './error.js';
+ *
+ * try {
+ *   await thread.run(hugeDataset, { timeout: 5000 });
+ * } catch (err) {
+ *   if (err instanceof ThreadTimeoutError) {
+ *     console.warn('Task took too long – retrying with more time');
+ *   } else if (err instanceof ThreadAbortError) {
+ *     console.log('User cancelled – cleaning up');
+ *   } else if (err instanceof ThreadTerminatedError) {
+ *     console.error('Thread was killed');
+ *   } else if (err instanceof ThreadError) {
+ *     console.error('Worker error:', err.message);
+ *   } else {
+ *     throw err; // re-throw non-thread errors
+ *   }
+ * }
+ * ```
+ *
+ * @module error
+ */
+
+// ---------------------------------------------------------------------------
+// ThreadError – base class
+// ---------------------------------------------------------------------------
+
+/**
+ * Base error class for all thread-related issues.
+ *
+ * This is the **parent** of every error the thread module can throw.
+ * Catching `ThreadError` lets you handle any thread-specific failure in
+ * one place; catching the subclasses lets you respond to specific failure
+ * modes.
+ *
+ * @example
+ * ```js
+ * import { ThreadError } from './error.js';
+ *
+ * // Generic catch-all
+ * try {
+ *   await thread.run(data);
+ * } catch (err) {
+ *   if (err instanceof ThreadError) {
+ *     // any thread error – safe to handle generically
+ *     console.error(`[thread] ${err.name}: ${err.message}`);
+ *   }
+ * }
+ * ```
+ */
+export class ThreadError extends Error {
+  /**
+   * @param {string} message - Human-readable description of the error.
+   */
+  constructor(message) {
+    super(message);
+    /** @readonly @type {'ThreadError'} */
+    this.name = 'ThreadError';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ThreadTimeoutError
+// ---------------------------------------------------------------------------
+
+/**
+ * Thrown when a task exceeds its allowed execution time.
+ *
+ * Every `thread.run()` and `pool.run()` accepts a `timeout` option (in ms).
+ * If the worker does not respond within that window the task promise is
+ * rejected with this error.
+ *
+ * **Common causes:**
+ * - The worker function has an infinite loop or is blocking on I/O.
+ * - The task is genuinely slow and needs a longer timeout.
+ * - The worker crashed before it could respond (the error message will
+ *   include the timeout value).
+ *
+ * @example
+ * ```js
+ * import { createThread, ThreadTimeoutError } from './index.js';
+ *
+ * const t = createThread((n) => {
+ *   // Simulate a slow task
+ *   const end = Date.now() + n;
+ *   while (Date.now() < end) { busy_wait }
+ *   return 'done';
+ * });
+ *
+ * try {
+ *   const result = await t.run(60_000, { timeout: 5000 });
+ * } catch (err) {
+ *   if (err instanceof ThreadTimeoutError) {
+ *     console.error('Task exceeded 5s timeout:', err.message);
+ *     // "Timed out after 5000ms"
+ *   }
+ * }
+ * ```
+ */
+export class ThreadTimeoutError extends ThreadError {
+  /**
+   * @param {string} message - Timeout description (usually includes ms).
+   */
+  constructor(message) {
+    super(message);
+    /** @readonly @type {'ThreadTimeoutError'} */
+    this.name = 'ThreadTimeoutError';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ThreadAbortError
+// ---------------------------------------------------------------------------
+
+/**
+ * Thrown when a task is cancelled via an `AbortController` or the pool's
+ * `cancel()` method.
+ *
+ * There are two ways to abort a task:
+ * 1. **AbortController** – pass `signal` in run options.
+ * 2. **Pool cancel** – call `pool.cancel(taskId)`.
+ *
+ * In both cases the task promise rejects with this error.
+ *
+ * @example
+ * ```js
+ * import { createThread, ThreadAbortError } from './index.js';
+ *
+ * const t = createThread((data) => process(data));
+ * const controller = new AbortController();
+ *
+ * // Start a long-running task
+ * const promise = t.run(hugeData, { signal: controller.signal });
+ *
+ * // User clicks "Cancel"
+ * document.getElementById('cancel').onclick = () => controller.abort();
+ *
+ * try {
+ *   await promise;
+ * } catch (err) {
+ *   if (err instanceof ThreadAbortError) {
+ *     console.log('Task was cancelled by user');
+ *   }
+ * }
+ * ```
+ */
+export class ThreadAbortError extends ThreadError {
+  /**
+   * @param {string} message - Abort description.
+   */
+  constructor(message) {
+    super(message);
+    /** @readonly @type {'ThreadAbortError'} */
+    this.name = 'ThreadAbortError';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ThreadTerminatedError
+// ---------------------------------------------------------------------------
+
+/**
+ * Thrown when you try to use a thread that has been terminated, or when
+ * the pool shuts down while tasks are still queued.
+ *
+ * Once `thread.terminate()` or `pool.terminateAll()` is called, every
+ * pending and future task promise rejects with this error.
+ *
+ * @example
+ * ```js
+ * import { createThread, ThreadTerminatedError } from './index.js';
+ *
+ * const t = createThread((x) => x * 2);
+ * t.terminate();
+ *
+ * try {
+ *   await t.run(5);
+ * } catch (err) {
+ *   if (err instanceof ThreadTerminatedError) {
+ *     console.error('Cannot use a terminated thread');
+ *   }
+ * }
+ * ```
+ */
+export class ThreadTerminatedError extends ThreadError {
+  /**
+   * @param {string} message - Termination description.
+   */
+  constructor(message) {
+    super(message);
+    /** @readonly @type {'ThreadTerminatedError'} */
+    this.name = 'ThreadTerminatedError';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ThreadHealthError
+// ---------------------------------------------------------------------------
+
+/**
+ * Thrown when a health check fails.
+ *
+ * When `healthCheckInterval` is set, the thread periodically pings the
+ * worker.  If the worker does not respond within `healthCheckTimeout`,
+ * or if the ping throws, the thread considers the worker dead and emits
+ * this error.
+ *
+ * In practice this error is **not** thrown to your task promises.  Instead
+ * it is logged internally and triggers an automatic restart.  You will
+ * see it if you listen to the `error` event:
+ *
+ * @example
+ * ```js
+ * import { createThread, ThreadHealthError } from './index.js';
+ *
+ * const t = createThread((x) => x, {
+ *   healthCheckInterval: 5000,
+ *   healthCheckTimeout: 2000,
+ * });
+ *
+ * t.on('error', (info) => {
+ *   if (info.error instanceof ThreadHealthError) {
+ *     console.warn('Worker is unhealthy, restarting...');
+ *   }
+ * });
+ * ```
+ */
+export class ThreadHealthError extends ThreadError {
+  /**
+   * @param {string} message - Health check failure description.
+   */
+  constructor(message) {
+    super(message);
+    /** @readonly @type {'ThreadHealthError'} */
+    this.name = 'ThreadHealthError';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ThreadDependencyError
+// ---------------------------------------------------------------------------
+
+/**
+ * Thrown when a pool task's dependency fails.
+ *
+ * When you submit a task with `dependsOn: [taskId]` and the dependency
+ * task fails (for any reason), the dependent task is automatically
+ * rejected with this error instead of running.
+ *
+ * The error message includes the failed dependency's ID and the original
+ * error message so you can trace the failure chain.
+ *
+ * @example
+ * ```js
+ * import { createPool, ThreadDependencyError } from './index.js';
+ *
+ * const pool = createPool(2, (x) => {
+ *   if (x < 0) throw new Error('Negative input');
+ *   return x * 2;
+ * });
+ *
+ * const a = pool.run(-1);           // will fail: "Negative input"
+ * const b = pool.run(10, {
+ *   dependsOn: [a.id],              // depends on 'a'
+ * });
+ *
+ * try {
+ *   await b.promise;
+ * } catch (err) {
+ *   if (err instanceof ThreadDependencyError) {
+ *     // "Dependency task 0 failed: Negative input"
+ *     console.error(err.message);
+ *   }
+ * }
+ * ```
+ */
+export class ThreadDependencyError extends ThreadError {
+  /**
+   * @param {string} message - Dependency failure description.
+   */
+  constructor(message) {
+    super(message);
+    /** @readonly @type {'ThreadDependencyError'} */
+    this.name = 'ThreadDependencyError';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// GPUComputeError
+// ---------------------------------------------------------------------------
+
+/**
+ * Thrown when a GPU compute operation fails.
+ *
+ * Covers all GPU-specific failures: shader compilation errors, buffer
+ * size violations, device loss, and dispatch failures.  The error's
+ * `cause` property contains the original WebGPU error when available.
+ *
+ * @example
+ * ```js
+ * import { GPUComputeError } from './error.js';
+ *
+ * try {
+ *   await gpu.compute({ inputs: {}, outputBuffers: {} });
+ * } catch (err) {
+ *   if (err instanceof GPUComputeError) {
+ *     console.error(`GPU failed: ${err.message}`);
+ *     if (err.cause) console.error('Original:', err.cause);
+ *   }
+ * }
+ * ```
+ */
+export class GPUComputeError extends ThreadError {
+  /**
+   * @param {string} message - Human-readable GPU error description.
+   * @param {Error} [cause] - Original WebGPU error (if any).
+   */
+  constructor(message, cause = undefined) {
+    super(message);
+    /** @readonly @type {'GPUComputeError'} */
+    this.name = 'GPUComputeError';
+    if (cause !== undefined) this.cause = cause;
+  }
+}