@dmop/puru 0.1.4 → 0.1.5

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);
@@ -418,9 +418,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 +471,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) {
@@ -662,14 +666,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 +699,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 +775,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 +809,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 +920,19 @@ 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);
     }
   }
   // --- Cancellation ---
@@ -965,14 +972,14 @@ 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] = [];
     }
@@ -999,10 +1006,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,12 +1029,12 @@ 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);
@@ -1142,6 +1149,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;
@@ -1167,7 +1180,7 @@ function spawn(fn, opts) {
       channelMap[name] = impl._id;
     }
   }
-  const task = {
+  const task2 = {
     id: taskId,
     fnStr,
     priority: opts?.priority ?? "normal",
@@ -1190,7 +1203,7 @@ function spawn(fn, opts) {
       }
     }
   };
-  getPool().submit(task);
+  getPool().submit(task2);
   const cancel = () => {
     if (settled) return;
     settled = true;
@@ -1204,9 +1217,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 +1236,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();
     }
   }
 };
@@ -1263,8 +1297,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 +1443,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 +1451,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 +1467,7 @@ var Ticker = class {
     if (this.resolve) {
       const r = this.resolve;
       this.resolve = null;
-      r();
+      r(false);
     }
   }
   async *[Symbol.asyncIterator]() {
@@ -1443,54 +1481,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 +1533,12 @@ function run(name, ...args) {
   configure,
   detectCapability,
   detectRuntime,
-  register,
   resize,
-  run,
   select,
+  shutdown,
   spawn,
   stats,
+  task,
   ticker
 });
 //# sourceMappingURL=index.cjs.map