Offload functions to worker threads with shared memory primitives for Node.js.
1# moroutine
2
3## 1.0.0
4
5### Major Changes
6
7- e46aca0: Unify Task and StreamTask under a single `Task<T>` type
8 - `Task<T>` is `PromiseLike<T>` for value tasks, `AsyncIterable<T>` for streaming tasks, or just the base dispatch shape when unparameterized
9 - `Balancer.select()` receives `Task` instead of `Task<any> | StreamTask<any>`
10 - `Arg<T>` simplifies to `T | Task<T>`
11 - Classes renamed to `PromiseLikeTask<T>` and `AsyncIterableTask<T>` (internal, prefer `Task<T>` in type annotations)
12
13### Minor Changes
14
15- 9ab6016: Graceful async worker pool shutdown
16 - `await using run = workers(4)` waits for in-flight tasks to settle before terminating workers
17 - `run.signal` is an `AbortSignal` that fires when the pool starts disposing — thread it into tasks for cooperative cancellation
18 - `workers(size, { shutdownTimeout: ms })` force-terminates workers if graceful shutdown exceeds the timeout
19 - Existing `using run` (sync dispose) still terminates immediately
20
21- 3612d52: Include main-thread call site in error stack traces
22
23 Errors thrown during task dispatch now have stack traces that show where `run()`, `exec()`, or `await task` was called. The original worker-side error is preserved as `err.cause` with its own stack pointing to the moroutine source.
24
25 ```
26 Error: boom
27 at trackValue (worker-pool.ts:52:15)
28 at async loadUser (user-code.ts:7:3)
29 at async main (user-code.ts:11:3) {
30 [cause]: Error: boom
31 at fixtures/math.ts:6:9 // original throw site on the worker
32 at MessagePort.<anonymous> (worker-entry.ts:173:25)
33 }
34 ```
35
36 Built-in error subclass identity (`TypeError`, `RangeError`, etc.) is preserved on the outer wrapper.
37
38- 5137201: Preserve error details across worker boundary
39
40 Errors thrown in moroutines now transfer with `message`, `stack`, `cause`, and built-in subclass identity (`TypeError`, `RangeError`, etc.) preserved via structured clone. Previously only the message string was kept.
41
42- d13cd40: Configurable load balancing for worker pools
43 - `workers(size, { balance: leastBusy() })` routes tasks to the worker with the fewest in-flight tasks
44 - `roundRobin()` cycles through workers in order (default, same as before)
45 - Custom balancers implement `Balancer.select(workers, task)` for full control over scheduling
46
47- cdccfdb: Per-worker dispatch with `assign()` and `run.workers`
48 - `run.workers` exposes a read-only array of `WorkerHandle`s, one per pool worker
49 - `assign(worker, task)` returns a copy of the task pinned to a specific worker
50 - `worker.exec(task)` dispatches directly to a specific worker
51 - Channel fan-out no longer requires knowing the worker count
52
53### Patch Changes
54
55- e2dabc1: Fix pool workers exiting early with top-level await
56
57 Pool workers are now ref'd for the lifetime of the pool, preventing the Node.js event loop from exiting prematurely when using `using run = workers()` with top-level `await`. Dedicated workers continue to ref only while tasks are in-flight.
58
59## 0.1.1
60
61### Patch Changes
62
63- 5068c96: Auto-detect and transfer AbortSignal arguments to workers
64
65 AbortSignal args are automatically detected, marked transferable via `util.transferableAbortSignal()`, and transferred to the worker. Works with regular tasks, streaming moroutines, and dedicated workers.
66
67## 0.1.0
68
69### Minor Changes
70
71- b6d4275: Initial version of moroutine: offload functions to worker threads with shared memory primitives for Node.js.