@dmop/puru 0.1.4 → 0.1.10

package/dist/index.cjs

@@ -30,12 +30,12 @@ __export(index_exports, {
   configure: () => configure,
   detectCapability: () => detectCapability,
   detectRuntime: () => detectRuntime,
-  register: () => register,
   resize: () => resize,
-  run: () => run,
   select: () => select,
+  shutdown: () => shutdown,
   spawn: () => spawn,
   stats: () => stats,
+  task: () => task,
   ticker: () => ticker
 });
 module.exports = __toCommonJS(index_exports);
@@ -98,16 +98,15 @@ function getConfig() {
 
 // src/runtime.ts
 function detectRuntime() {
-  if (typeof globalThis.Bun !== "undefined") return "bun";
-  if (typeof globalThis.Deno !== "undefined") return "deno";
-  if (typeof globalThis.process !== "undefined" && globalThis.process.versions?.node)
-    return "node";
+  if ("Bun" in globalThis) return "bun";
+  if ("Deno" in globalThis) return "deno";
+  if (typeof globalThis.process !== "undefined" && globalThis.process.versions?.node) return "node";
   return "browser";
 }
 function detectCapability() {
   const runtime = detectRuntime();
   if (runtime === "node" || runtime === "bun") return "full-threads";
-  if (typeof globalThis.Worker !== "undefined") return "full-threads";
+  if ("Worker" in globalThis) return "full-threads";
   return "single-thread";
 }
 
@@ -374,7 +373,11 @@ var BunManagedWorker = class {
   id;
   constructor() {
     this.id = ++workerIdCounter;
-    this.worker = new Worker(getBootstrapFile());
+    const WorkerConstructor = globalThis.Worker;
+    if (!WorkerConstructor) {
+      throw new Error("Bun Worker constructor is not available in this runtime");
+    }
+    this.worker = new WorkerConstructor(getBootstrapFile());
   }
   postMessage(data) {
     this.worker.postMessage(data);
@@ -386,27 +389,28 @@ var BunManagedWorker = class {
   on(event, handler) {
     if (event === "message") {
       this.worker.addEventListener("message", (e) => {
+        ;
         handler(e.data);
       });
     } else if (event === "error") {
       this.worker.addEventListener("error", (e) => {
+        ;
         handler(e.error ?? new Error(e.message));
       });
     } else if (event === "exit") {
       this.worker.addEventListener("close", (e) => {
+        ;
         handler(e.code ?? 0);
       });
     }
   }
   unref() {
     if ("unref" in this.worker && typeof this.worker.unref === "function") {
-      ;
       this.worker.unref();
     }
   }
   ref() {
     if ("ref" in this.worker && typeof this.worker.ref === "function") {
-      ;
       this.worker.ref();
     }
   }
@@ -418,9 +422,11 @@ var BunWorkerAdapter = class {
 };
 
 // src/channel.ts
+var CLOSED = /* @__PURE__ */ Symbol("puru.channel.closed");
 var channelIdCounter = 0;
 var channelRegistry = /* @__PURE__ */ new Map();
 var ChannelImpl = class {
+  // constraint: can't create channels of nullable type
   /** @internal */
   _id;
   buffer = [];
@@ -469,14 +475,16 @@ var ChannelImpl = class {
       return Promise.resolve(null);
     }
     return new Promise((resolve) => {
-      this.recvQueue.push({ resolve });
+      this.recvQueue.push({
+        resolve: (v) => resolve(v === CLOSED ? null : v)
+      });
     });
   }
   close() {
     if (this.closed) return;
     this.closed = true;
     for (const receiver of this.recvQueue) {
-      receiver.resolve(null);
+      receiver.resolve(CLOSED);
     }
     this.recvQueue = [];
     for (const sender of this.sendQueue) {
@@ -501,6 +509,9 @@ function chan(capacity = 0) {
 function getChannelById(id) {
   return channelRegistry.get(id);
 }
+function getChannelId(channel) {
+  return channel._id;
+}
 
 // src/adapters/inline.ts
 var inlineIdCounter = 0;
@@ -517,15 +528,14 @@ var InlineManagedWorker = class {
       this.emit("message", { type: "ready" });
     });
   }
-  postMessage(data) {
+  postMessage(msg) {
     if (this.terminated) return;
-    const msg = data;
     if (msg.type === "execute") {
-      this.executeTask(msg.taskId, msg.fnStr, msg.concurrent ?? false, msg.channels);
+      this.executeTask(msg.taskId, msg.fnStr, msg.concurrent, msg.channels);
     } else if (msg.type === "cancel") {
       this.cancelledTasks.add(msg.taskId);
     } else if (msg.type === "channel-result") {
-      this.emit("message", msg);
+      return;
     } else if (msg.type === "shutdown") {
       this.terminated = true;
       this.emit("exit", 0);
@@ -555,7 +565,6 @@ var InlineManagedWorker = class {
     }
   }
   buildChannelProxies(channels) {
-    const self = this;
     const proxies = {};
     for (const [name, channelId] of Object.entries(channels)) {
       proxies[name] = {
@@ -577,13 +586,7 @@ var InlineManagedWorker = class {
         [Symbol.asyncIterator]() {
           const ch = getChannelById(channelId);
           if (!ch) throw new Error(`Channel ${channelId} not found`);
-          return {
-            async next() {
-              const value = await ch.recv();
-              if (value === null) return { done: true, value: void 0 };
-              return { done: false, value };
-            }
-          };
+          return ch[Symbol.asyncIterator]();
         }
       };
     }
@@ -662,14 +665,14 @@ var WorkerPool = class {
     this.adapter = adapter;
   }
   // --- Queue helpers ---
-  enqueue(task) {
-    this.queues[task.priority].push(task);
+  enqueue(task2) {
+    this.queues[task2.priority].push(task2);
   }
   dequeue() {
     return this.queues.high.shift() ?? this.queues.normal.shift() ?? this.queues.low.shift();
   }
-  enqueueConcurrent(task) {
-    this.concurrentQueues[task.priority].push(task);
+  enqueueConcurrent(task2) {
+    this.concurrentQueues[task2.priority].push(task2);
   }
   dequeueConcurrent() {
     return this.concurrentQueues.high.shift() ?? this.concurrentQueues.normal.shift() ?? this.concurrentQueues.low.shift();
@@ -695,73 +698,73 @@ var WorkerPool = class {
     return void 0;
   }
   // --- Submit ---
-  submit(task) {
+  submit(task2) {
     if (this.draining) {
-      task.reject(new Error("Pool is shutting down"));
+      task2.reject(new Error("Pool is shutting down"));
       return;
     }
-    if (task.concurrent) {
-      this.submitConcurrent(task);
+    if (task2.concurrent) {
+      this.submitConcurrent(task2);
     } else {
-      this.submitExclusive(task);
+      this.submitExclusive(task2);
     }
   }
-  submitExclusive(task) {
+  submitExclusive(task2) {
     const worker = this.idleWorkers.pop();
     if (worker) {
-      this.dispatch(worker, task);
+      this.dispatch(worker, task2);
       return;
     }
     const totalWorkers = this.allWorkers.size + this.pendingWorkerCount;
     if (totalWorkers < this.config.maxThreads) {
       this.pendingWorkerCount++;
-      this.pendingTasksForWorkers.push(task);
+      this.pendingTasksForWorkers.push(task2);
       this.createAndReadyWorker();
       return;
     }
-    this.enqueue(task);
+    this.enqueue(task2);
   }
-  submitConcurrent(task) {
+  submitConcurrent(task2) {
     for (const [worker, tasks] of this.sharedWorkers) {
       if (tasks.size < this.config.concurrency) {
-        this.dispatchConcurrent(worker, task);
+        this.dispatchConcurrent(worker, task2);
         return;
       }
     }
     const idleWorker = this.idleWorkers.pop();
     if (idleWorker) {
-      this.dispatchConcurrent(idleWorker, task);
+      this.dispatchConcurrent(idleWorker, task2);
       return;
     }
     const totalWorkers = this.allWorkers.size + this.pendingWorkerCount;
     if (totalWorkers < this.config.maxThreads) {
       this.pendingWorkerCount++;
-      this.pendingTasksForWorkers.push(task);
+      this.pendingTasksForWorkers.push(task2);
       this.createAndReadyWorker();
       return;
     }
-    this.enqueueConcurrent(task);
+    this.enqueueConcurrent(task2);
   }
   // --- Dispatch ---
-  dispatch(worker, task) {
+  dispatch(worker, task2) {
     const timer = this.idleTimers.get(worker);
     if (timer) {
       clearTimeout(timer);
       this.idleTimers.delete(worker);
     }
     worker.ref();
-    this.exclusiveWorkers.set(task.id, worker);
-    this.taskMap.set(task.id, task);
+    this.exclusiveWorkers.set(task2.id, worker);
+    this.taskMap.set(task2.id, task2);
     const msg = {
       type: "execute",
-      taskId: task.id,
-      fnStr: task.fnStr,
+      taskId: task2.id,
+      fnStr: task2.fnStr,
       concurrent: false,
-      channels: task.channels
+      channels: task2.channels
     };
     worker.postMessage(msg);
   }
-  dispatchConcurrent(worker, task) {
+  dispatchConcurrent(worker, task2) {
     const timer = this.idleTimers.get(worker);
     if (timer) {
       clearTimeout(timer);
@@ -771,14 +774,14 @@ var WorkerPool = class {
     if (!this.sharedWorkers.has(worker)) {
       this.sharedWorkers.set(worker, /* @__PURE__ */ new Set());
     }
-    this.sharedWorkers.get(worker).add(task.id);
-    this.taskMap.set(task.id, task);
+    this.sharedWorkers.get(worker).add(task2.id);
+    this.taskMap.set(task2.id, task2);
     const msg = {
       type: "execute",
-      taskId: task.id,
-      fnStr: task.fnStr,
+      taskId: task2.id,
+      fnStr: task2.fnStr,
       concurrent: true,
-      channels: task.channels
+      channels: task2.channels
     };
     worker.postMessage(msg);
   }
@@ -805,6 +808,9 @@ var WorkerPool = class {
       const taskId = response.taskId;
       const err = new Error(response.message);
       if (response.stack) err.stack = response.stack;
+      if (response.message.match(/^ReferenceError:/) || response.message.match(/ is not defined$/)) {
+        err.message += "\n  Hint: functions passed to spawn() cannot access variables from the enclosing scope. Inline all required values directly in the function body, or pass them via the channels option.";
+      }
       this.rejectTask(taskId, err);
       if (this.exclusiveWorkers.has(taskId)) {
         this.exclusiveWorkers.delete(taskId);
@@ -913,19 +919,28 @@ var WorkerPool = class {
   }
   // --- Task resolution ---
   resolveTask(taskId, value) {
-    const task = this.taskMap.get(taskId);
-    if (task) {
+    const task2 = this.taskMap.get(taskId);
+    if (task2) {
       this.taskMap.delete(taskId);
       this.totalCompleted++;
-      task.resolve(value);
+      task2.resolve(value);
     }
   }
   rejectTask(taskId, reason) {
-    const task = this.taskMap.get(taskId);
-    if (task) {
+    const task2 = this.taskMap.get(taskId);
+    if (task2) {
       this.taskMap.delete(taskId);
       this.totalFailed++;
-      task.reject(reason);
+      task2.reject(reason);
+    }
+  }
+  rejectExclusiveTaskForWorker(worker, reason) {
+    for (const [taskId, assignedWorker] of this.exclusiveWorkers) {
+      if (assignedWorker === worker) {
+        this.exclusiveWorkers.delete(taskId);
+        this.rejectTask(taskId, reason);
+        break;
+      }
     }
   }
   // --- Cancellation ---
@@ -965,17 +980,21 @@ var WorkerPool = class {
   async drain() {
     this.draining = true;
     for (const priority of ["high", "normal", "low"]) {
-      for (const task of this.queues[priority]) {
-        task.reject(new Error("Pool is shutting down"));
+      for (const task2 of this.queues[priority]) {
+        task2.reject(new Error("Pool is shutting down"));
       }
       this.queues[priority] = [];
     }
     for (const priority of ["high", "normal", "low"]) {
-      for (const task of this.concurrentQueues[priority]) {
-        task.reject(new Error("Pool is shutting down"));
+      for (const task2 of this.concurrentQueues[priority]) {
+        task2.reject(new Error("Pool is shutting down"));
       }
       this.concurrentQueues[priority] = [];
     }
+    for (const [taskId] of this.exclusiveWorkers) {
+      this.taskMap.delete(taskId);
+    }
+    this.exclusiveWorkers.clear();
     for (const [, taskSet] of this.sharedWorkers) {
       for (const taskId of taskSet) {
         this.taskMap.delete(taskId);
@@ -999,10 +1018,10 @@ var WorkerPool = class {
     while (true) {
       const totalWorkers = this.allWorkers.size + this.pendingWorkerCount;
       if (totalWorkers >= maxThreads) break;
-      const task = this.dequeue() ?? this.dequeueConcurrent();
-      if (!task) break;
+      const task2 = this.dequeue() ?? this.dequeueConcurrent();
+      if (!task2) break;
       this.pendingWorkerCount++;
-      this.pendingTasksForWorkers.push(task);
+      this.pendingTasksForWorkers.push(task2);
       this.createAndReadyWorker();
     }
     while (this.allWorkers.size > maxThreads && this.idleWorkers.length > 0) {
@@ -1022,19 +1041,18 @@ var WorkerPool = class {
     const onReady = () => {
       this.pendingWorkerCount--;
       this.allWorkers.add(worker);
-      const task = this.pendingTasksForWorkers.shift();
-      if (task) {
-        if (task.concurrent) {
-          this.dispatchConcurrent(worker, task);
+      const task2 = this.pendingTasksForWorkers.shift();
+      if (task2) {
+        if (task2.concurrent) {
+          this.dispatchConcurrent(worker, task2);
         } else {
-          this.dispatch(worker, task);
+          this.dispatch(worker, task2);
         }
       } else {
         this.makeIdle(worker);
       }
     };
-    worker.on("message", (msg) => {
-      const response = msg;
+    worker.on("message", (response) => {
       if (response.type === "ready") {
         onReady();
         return;
@@ -1042,12 +1060,7 @@ var WorkerPool = class {
       this.handleWorkerMessage(worker, response);
     });
     worker.on("error", (err) => {
-      for (const [taskId, w] of this.exclusiveWorkers) {
-        if (w === worker) {
-          this.exclusiveWorkers.delete(taskId);
-          break;
-        }
-      }
+      this.rejectExclusiveTaskForWorker(worker, err);
       const taskSet = this.sharedWorkers.get(worker);
       if (taskSet) {
         for (const taskId of taskSet) {
@@ -1067,12 +1080,7 @@ var WorkerPool = class {
       if (idleIdx !== -1) {
         this.idleWorkers.splice(idleIdx, 1);
       }
-      for (const [taskId, w] of this.exclusiveWorkers) {
-        if (w === worker) {
-          this.exclusiveWorkers.delete(taskId);
-          break;
-        }
-      }
+      this.rejectExclusiveTaskForWorker(worker, new Error("Worker exited unexpectedly"));
       const taskSet = this.sharedWorkers.get(worker);
       if (taskSet) {
         for (const taskId of taskSet) {
@@ -1142,6 +1150,12 @@ function stats() {
 function resize(maxThreads) {
   getPool().resize(maxThreads);
 }
+async function shutdown() {
+  if (poolInstance) {
+    await poolInstance.drain();
+    poolInstance = null;
+  }
+}
 
 // src/spawn.ts
 var taskCounter = 0;
@@ -1160,14 +1174,10 @@ function spawn(fn, opts) {
   if (opts?.channels) {
     channelMap = {};
     for (const [name, ch] of Object.entries(opts.channels)) {
-      const impl = ch;
-      if (!impl._id) {
-        throw new Error(`Channel "${name}" is not a valid puru channel`);
-      }
-      channelMap[name] = impl._id;
+      channelMap[name] = getChannelId(ch);
     }
   }
-  const task = {
+  const task2 = {
     id: taskId,
     fnStr,
     priority: opts?.priority ?? "normal",
@@ -1190,7 +1200,7 @@ function spawn(fn, opts) {
       }
     }
   };
-  getPool().submit(task);
+  getPool().submit(task2);
   const cancel = () => {
     if (settled) return;
     settled = true;
@@ -1204,9 +1214,18 @@ function spawn(fn, opts) {
 var WaitGroup = class {
   tasks = [];
   controller = new AbortController();
+  /**
+   * An `AbortSignal` shared across all tasks in this group.
+   * Pass it into spawned functions so they can stop early when `cancel()` is called.
+   */
   get signal() {
     return this.controller.signal;
   }
+  /**
+   * Spawns a function on a worker thread and adds it to the group.
+   *
+   * @throws If the group has already been cancelled.
+   */
   spawn(fn, opts) {
     if (this.controller.signal.aborted) {
       throw new Error("WaitGroup has been cancelled");
@@ -1214,16 +1233,28 @@ var WaitGroup = class {
     const handle = spawn(fn, opts);
     this.tasks.push(handle);
   }
+  /**
+   * Waits for all tasks to complete successfully.
+   * Rejects as soon as any task throws.
+   */
   async wait() {
     return Promise.all(this.tasks.map((t) => t.result));
   }
+  /**
+   * Waits for all tasks to settle (fulfilled or rejected) and returns each outcome.
+   * Never rejects — inspect each `PromiseSettledResult` to handle failures individually.
+   */
   async waitSettled() {
     return Promise.allSettled(this.tasks.map((t) => t.result));
   }
+  /**
+   * Cancels all tasks in the group and signals the shared `AbortSignal`.
+   * Already-settled tasks are unaffected.
+   */
   cancel() {
     this.controller.abort();
-    for (const task of this.tasks) {
-      task.cancel();
+    for (const task2 of this.tasks) {
+      task2.cancel();
     }
   }
 };
@@ -1232,7 +1263,7 @@ var WaitGroup = class {
 var ErrGroup = class {
   tasks = [];
   controller = new AbortController();
-  firstError = void 0;
+  firstError = null;
   hasError = false;
   get signal() {
     return this.controller.signal;
@@ -1253,7 +1284,7 @@ var ErrGroup = class {
   }
   async wait() {
     const settled = await Promise.allSettled(this.tasks.map((t) => t.result));
-    if (this.hasError) {
+    if (this.hasError && this.firstError) {
       throw this.firstError;
     }
     return settled.map((r) => {
@@ -1263,8 +1294,8 @@ var ErrGroup = class {
   }
   cancel() {
     this.controller.abort();
-    for (const task of this.tasks) {
-      task.cancel();
+    for (const task2 of this.tasks) {
+      task2.cancel();
     }
   }
 };
@@ -1409,7 +1440,7 @@ var Ticker = class {
       if (this.resolve) {
         const r = this.resolve;
         this.resolve = null;
-        r();
+        r(true);
       }
     }, ms);
     if (this.interval.unref) this.interval.unref();
@@ -1417,7 +1448,11 @@ var Ticker = class {
   async tick() {
     if (this.stopped) return false;
     return new Promise((resolve) => {
-      this.resolve = () => resolve(true);
+      this.resolve = resolve;
+      if (this.stopped) {
+        this.resolve = null;
+        resolve(false);
+      }
     });
   }
   stop() {
@@ -1429,7 +1464,7 @@ var Ticker = class {
     if (this.resolve) {
       const r = this.resolve;
       this.resolve = null;
-      r();
+      r(false);
     }
   }
   async *[Symbol.asyncIterator]() {
@@ -1443,54 +1478,45 @@ function ticker(ms) {
 }
 
 // src/registry.ts
-var registry = /* @__PURE__ */ new Map();
 var taskCounter2 = 0;
-function register(name, fn) {
-  if (registry.has(name)) {
-    throw new Error(`Task "${name}" is already registered`);
-  }
-  registry.set(name, fn);
-}
-function run(name, ...args) {
-  const fn = registry.get(name);
-  if (!fn) {
-    throw new Error(`Task "${name}" is not registered. Call register() first.`);
-  }
-  const fnStr = serializeFunction(fn);
-  const serializedArgs = args.map((a) => {
-    const json = JSON.stringify(a);
-    if (json === void 0) {
-      throw new TypeError(
-        `Argument of type ${typeof a} is not JSON-serializable. run() args must be JSON-serializable (no undefined, functions, symbols, or BigInt).`
-      );
-    }
-    return json;
-  });
-  const wrapperStr = `() => (${fnStr})(${serializedArgs.join(", ")})`;
-  const taskId = `reg_${++taskCounter2}`;
-  const spawnStack = new Error().stack;
-  let resolveFn;
-  let rejectFn;
-  const result = new Promise((resolve, reject) => {
-    resolveFn = resolve;
-    rejectFn = reject;
-  });
-  const task = {
-    id: taskId,
-    fnStr: wrapperStr,
-    priority: "normal",
-    concurrent: false,
-    resolve: (value) => resolveFn(value),
-    reject: (reason) => {
-      if (reason instanceof Error && spawnStack) {
-        const callerLine = spawnStack.split("\n").slice(2).join("\n");
-        reason.stack = (reason.stack ?? reason.message) + "\n    --- spawned at ---\n" + callerLine;
+function task(fn) {
+  return (...args) => {
+    const fnStr = serializeFunction(fn);
+    const serializedArgs = args.map((a) => {
+      const json = JSON.stringify(a);
+      if (json === void 0) {
+        throw new TypeError(
+          `Argument of type ${typeof a} is not JSON-serializable. task() args must be JSON-serializable (no undefined, functions, symbols, or BigInt).`
+        );
       }
-      rejectFn(reason);
-    }
+      return json;
+    });
+    const wrapperStr = `() => (${fnStr})(${serializedArgs.join(", ")})`;
+    const taskId = `task_${++taskCounter2}`;
+    const spawnStack = new Error().stack;
+    let resolveFn;
+    let rejectFn;
+    const result = new Promise((resolve, reject) => {
+      resolveFn = resolve;
+      rejectFn = reject;
+    });
+    const taskObj = {
+      id: taskId,
+      fnStr: wrapperStr,
+      priority: "normal",
+      concurrent: false,
+      resolve: (value) => resolveFn(value),
+      reject: (reason) => {
+        if (reason instanceof Error && spawnStack) {
+          const callerLine = spawnStack.split("\n").slice(2).join("\n");
+          reason.stack = (reason.stack ?? reason.message) + "\n    --- spawned at ---\n" + callerLine;
+        }
+        rejectFn(reason);
+      }
+    };
+    getPool().submit(taskObj);
+    return result;
   };
-  getPool().submit(task);
-  return result;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -1504,12 +1530,12 @@ function run(name, ...args) {
   configure,
   detectCapability,
   detectRuntime,
-  register,
   resize,
-  run,
   select,
+  shutdown,
   spawn,
   stats,
+  task,
   ticker
 });
 //# sourceMappingURL=index.cjs.map