@hybrid-compute/worker 0.37.2 → 0.38.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,37 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.38.0](https://github.com/phun-ky/hybrid-compute/compare/%40hybrid-compute%2Fworker%400.37.3...%40hybrid-compute%2Fworker%400.38.0) (2026-10-20)
4
+
5
+ ### ⚠ BREAKING CHANGES
6
+
7
+ * createThreadedCompute and the ThreadedCompute constructor
8
+ take an options object: createThreadedCompute({ url, canRunTasks }) instead
9
+ of createThreadedCompute(url, taskNames). Error replies reject with a
10
+ WorkerTaskError instead of the raw error value. A task that isn't in
11
+ canRunTasks rejects with NoBackendError instead of being sent.
12
+
13
+ ### Documentation
14
+
15
+ * ✏️ document worker's options, errors, cancelling, exposeTasks and message format ([e375d0b](https://github.com/phun-ky/hybrid-compute/commit/e375d0ba93711201daabd7442d7f1ad80a6903c2)), references [#127](https://github.com/phun-ky/hybrid-compute/issues/127) [#127](https://github.com/phun-ky/hybrid-compute/issues/127) [#85](https://github.com/phun-ky/hybrid-compute/issues/85)
16
+
17
+ ### Feature
18
+
19
+ * 🎸 worker API review: options object, WorkerTaskError, exposeTasks, timeouts, cancellation ([f7f3d6f](https://github.com/phun-ky/hybrid-compute/commit/f7f3d6f2ecec6bc84ceec3034833f135b06080b4)), references [#85](https://github.com/phun-ky/hybrid-compute/issues/85)
20
+
21
+ ## [0.37.3](https://github.com/phun-ky/hybrid-compute/compare/%40hybrid-compute%2Fworker%400.37.2...%40hybrid-compute%2Fworker%400.37.3) (2026-10-20)
22
+
23
+ ### Tasks
24
+
25
+ * 🤖 @hybrid-compute/core@0.39.0 ([410c7a0](https://github.com/phun-ky/hybrid-compute/commit/410c7a00cfa43524449e6ea5ab5661208af76126))
26
+
27
+ ### Documentation
28
+
29
+ * ✏️ document local's task rules and fix the package README links ([f8de45d](https://github.com/phun-ky/hybrid-compute/commit/f8de45dc5d7e55763132278c9ec39f171b5f588a)), closes [#83](https://github.com/phun-ky/hybrid-compute/issues/83)
30
+
31
+ ### Adding missing tests
32
+
33
+ * 💍 measure coverage on each package's own source ([4720e44](https://github.com/phun-ky/hybrid-compute/commit/4720e443b2a1d7c5a17536258c29da730f1a0b42)), references [#88](https://github.com/phun-ky/hybrid-compute/issues/88)
34
+
3
35
  ## [0.37.2](https://github.com/phun-ky/hybrid-compute/compare/%40hybrid-compute%2Fworker%400.37.1...%40hybrid-compute%2Fworker%400.37.2) (2026-10-20)
4
36
 
5
37
  ### Tasks
package/README.md CHANGED
@@ -21,31 +21,53 @@ monorepo.
21
21
 
22
22
  ## API Docs
23
23
 
24
- [ThreadedCompute API Documentation](https://github.com/phun-ky/hybrid-compute/blob/main/docs/api/worker/src/classes/ThreadedCompute.md)
24
+ [ThreadedCompute API Documentation](https://phun-ky.net/hybrid-compute/api/@hybrid-compute/worker/classes/ThreadedCompute)
25
+ and
26
+ [exposeTasks](https://phun-ky.net/hybrid-compute/api/@hybrid-compute/worker/functions/exposeTasks)
25
27
 
26
28
  ## 📦 Package Info
27
29
 
28
30
  This package provides:
29
31
 
30
- - A compute backend that runs tasks in a dedicated Web Worker
31
- - Asynchronous task messaging via `postMessage`
32
- - Useful for offloading CPU-intensive work from the main thread
32
+ - A compute backend that runs tasks in a dedicated module Web Worker, so heavy
33
+ work doesn't block the main thread
34
+ - `exposeTasks`, which turns an object of functions into a worker script
35
+ - Timeouts, cancellation with an `AbortSignal`, and one error type,
36
+ `WorkerTaskError`, for every failure
33
37
 
34
38
  ## Usage
35
39
 
36
40
  ```bash
37
- npm install @hybrid-compute/worker
41
+ npm install @hybrid-compute/core @hybrid-compute/worker
38
42
  ```
39
43
 
44
+ In the worker script, `worker.ts`:
45
+
46
+ ```ts
47
+ import { exposeTasks } from '@hybrid-compute/worker';
48
+
49
+ exposeTasks({
50
+ add: ([a, b]: [number, number]) => a + b
51
+ });
52
+ ```
53
+
54
+ On the main thread:
55
+
40
56
  ```ts
41
57
  import { createThreadedCompute } from '@hybrid-compute/worker';
42
58
 
43
- const threaded = createThreadedCompute(
44
- new URL('./worker.js', import.meta.url),
45
- ['add']
46
- );
59
+ const threaded = createThreadedCompute({
60
+ url: new URL('./worker.ts', import.meta.url),
61
+ canRunTasks: ['add']
62
+ });
63
+
64
+ await threaded.runTask('add', [2, 3]); // 5
47
65
  ```
48
66
 
67
+ The worker starts on the first task. Options, errors, cancelling and the message
68
+ format are in the
69
+ [worker guide](https://phun-ky.net/hybrid-compute/guide/usage/worker).
70
+
49
71
  ---
50
72
 
51
73
  ## Contributing
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hybrid-compute/worker",
3
- "version": "0.37.2",
3
+ "version": "0.38.0",
4
4
  "description": "Threaded compute backend for executing tasks in Web Workers.",
5
5
  "keywords": [
6
6
  "web-worker",
@@ -33,10 +33,10 @@
33
33
  "release": "release-it",
34
34
  "test": "tsx --test **/__tests__/**/*.spec.ts",
35
35
  "pretest:ci": "rm -rf coverage && mkdir -p coverage",
36
- "test:ci": "glob-bin -c \"node --import tsx --test --no-warnings --experimental-test-coverage --test-reporter=cobertura --test-reporter-destination=coverage/cobertura-coverage.xml --test-reporter=spec --test-reporter-destination=stdout\" \"**/__tests__/**/*.spec.ts\""
36
+ "test:ci": "glob-bin -c \"node --import tsx --test --no-warnings --experimental-test-coverage --test-coverage-include='src/**/*.ts' --test-coverage-exclude='src/**/__tests__/**' --test-coverage-exclude='src/types.ts' --test-reporter=cobertura --test-reporter-destination=coverage/cobertura-coverage.xml --test-reporter=spec --test-reporter-destination=stdout\" \"**/__tests__/**/*.spec.ts\""
37
37
  },
38
38
  "dependencies": {
39
- "@hybrid-compute/core": "^0.38.0"
39
+ "@hybrid-compute/core": "^0.39.0"
40
40
  },
41
41
  "devDependencies": {
42
42
  "eslint": "^9.27.0",
@@ -0,0 +1,175 @@
1
+ import assert from 'node:assert/strict';
2
+ import test, { describe } from 'node:test';
3
+
4
+ import { exposeTasks, WorkerScopeInterface, WorkerTaskType } from '..';
5
+
6
+ /** A scope that records replies, and sends messages to the listener. */
7
+ const createScope = (postMessage?: (message: unknown) => void) => {
8
+ const replies: unknown[] = [];
9
+ let listener: (event: { data: unknown }) => void = () => {};
10
+ const scope: WorkerScopeInterface = {
11
+ addEventListener: (_type, fn) => {
12
+ listener = fn;
13
+ },
14
+ postMessage: postMessage ?? ((message) => replies.push(message))
15
+ };
16
+
17
+ return {
18
+ scope,
19
+ replies,
20
+ send: (data: unknown) => listener({ data }),
21
+ settled: () => new Promise((resolve) => setTimeout(resolve, 10))
22
+ };
23
+ };
24
+ const tasks = (value: unknown) =>
25
+ value as unknown as Record<string, WorkerTaskType>;
26
+
27
+ describe('exposeTasks', () => {
28
+ test('throws a TypeError for something that is not an object of functions', () => {
29
+ for (const value of [undefined, null, [], { add: 1 }]) {
30
+ assert.throws(
31
+ () => exposeTasks(tasks(value), createScope().scope),
32
+ TypeError
33
+ );
34
+ }
35
+ });
36
+
37
+ test('throws a TypeError outside a worker without a scope', () => {
38
+ assert.throws(() => exposeTasks({}), {
39
+ name: 'TypeError',
40
+ message: /must be called in a worker script/
41
+ });
42
+ });
43
+
44
+ test('listens on the global scope in a worker', async () => {
45
+ const global = globalThis as Record<string, unknown>;
46
+ const { scope, replies, send, settled } = createScope();
47
+
48
+ Object.assign(global, {
49
+ WorkerGlobalScope: class {},
50
+ addEventListener: scope.addEventListener,
51
+ postMessage: scope.postMessage
52
+ });
53
+
54
+ try {
55
+ exposeTasks({ double: (n: number) => n * 2 });
56
+ send({ id: 1, task: 'double', input: 4 });
57
+ await settled();
58
+ } finally {
59
+ delete global.WorkerGlobalScope;
60
+ delete global.addEventListener;
61
+ delete global.postMessage;
62
+ }
63
+
64
+ assert.deepEqual(replies, [{ id: 1, result: 8 }]);
65
+ });
66
+
67
+ test('replies with the result, or with the error the task throws', async () => {
68
+ const { scope, replies, send, settled } = createScope();
69
+
70
+ exposeTasks(
71
+ {
72
+ sum: async (numbers: number[]) => numbers.reduce((a, b) => a + b, 0),
73
+ error: () => {
74
+ throw new RangeError('out of range');
75
+ },
76
+ string: () => Promise.reject('just a string'),
77
+ other: () => {
78
+ throw 42;
79
+ }
80
+ },
81
+ scope
82
+ );
83
+ send({ id: 1, task: 'sum', input: [1, 2, 3] });
84
+ send({ id: 2, task: 'error', input: null });
85
+ send({ id: 3, task: 'string', input: null });
86
+ send({ id: 4, task: 'other', input: null });
87
+ send({ id: 5, task: 'toString', input: null });
88
+ await settled();
89
+ // Async tasks finish in their own time, so compare in id order
90
+ replies.sort((a, b) => (a as { id: number }).id - (b as { id: number }).id);
91
+ assert.deepEqual(replies, [
92
+ { id: 1, result: 6 },
93
+ { id: 2, error: { name: 'RangeError', message: 'out of range' } },
94
+ { id: 3, error: 'just a string' },
95
+ { id: 4, error: { message: '42' } },
96
+ {
97
+ id: 5,
98
+ error: { name: 'Error', message: "No task 'toString' in this worker" }
99
+ }
100
+ ]);
101
+ });
102
+
103
+ test('ignores messages it cannot use', async () => {
104
+ const { scope, replies, send, settled } = createScope();
105
+
106
+ exposeTasks({ echo: (input: unknown) => input }, scope);
107
+
108
+ for (const data of [
109
+ null,
110
+ 'echo',
111
+ [],
112
+ { task: 'echo' },
113
+ { id: 1 },
114
+ { id: 2, cancel: true }
115
+ ]) {
116
+ send(data);
117
+ }
118
+
119
+ await settled();
120
+ assert.deepEqual(replies, []);
121
+ });
122
+
123
+ test('aborts the signal on cancel, and sends no reply', async () => {
124
+ const { scope, replies, send, settled } = createScope();
125
+ const seen: string[] = [];
126
+
127
+ exposeTasks(
128
+ {
129
+ wait: (_input: unknown, { signal }) =>
130
+ new Promise((resolve, reject) =>
131
+ signal.addEventListener('abort', () => {
132
+ seen.push('aborted');
133
+ reject(signal.reason);
134
+ })
135
+ ),
136
+ resolveAnyway: (_input: unknown, { signal }) =>
137
+ new Promise((resolve) =>
138
+ signal.addEventListener('abort', () => resolve('done'))
139
+ )
140
+ },
141
+ scope
142
+ );
143
+ send({ id: 1, task: 'wait', input: null });
144
+ send({ id: 2, task: 'resolveAnyway', input: null });
145
+ send({ id: 1, cancel: true });
146
+ send({ id: 2, cancel: true });
147
+ await settled();
148
+ assert.deepEqual(seen, ['aborted']);
149
+ assert.deepEqual(replies, []);
150
+ });
151
+
152
+ test('replies with an error when the result cannot be sent', async () => {
153
+ const replies: unknown[] = [];
154
+ const { scope, send, settled } = createScope((message) => {
155
+ if (typeof (message as { result?: unknown }).result === 'function') {
156
+ throw new Error('() => 1 could not be cloned');
157
+ }
158
+
159
+ replies.push(message);
160
+ });
161
+
162
+ exposeTasks({ fn: () => () => 1 }, scope);
163
+ send({ id: 1, task: 'fn', input: null });
164
+ await settled();
165
+ assert.deepEqual(replies, [
166
+ {
167
+ id: 1,
168
+ error: {
169
+ name: 'DataCloneError',
170
+ message: "the result couldn't be sent: () => 1 could not be cloned"
171
+ }
172
+ }
173
+ ]);
174
+ });
175
+ });
@@ -0,0 +1,30 @@
1
+ // A worker script written with exposeTasks, adapted to worker_threads
2
+ import { parentPort } from 'node:worker_threads';
3
+
4
+ import { exposeTasks } from '../../expose.js';
5
+
6
+ let aborted = 0;
7
+
8
+ exposeTasks(
9
+ {
10
+ echo: (input: unknown) => input,
11
+ double: async (n: number) => n * 2,
12
+ fail: () => {
13
+ throw new Error('boom');
14
+ },
15
+ unclonable: () => () => 1,
16
+ waitForAbort: (_input: unknown, { signal }) =>
17
+ new Promise((resolve) =>
18
+ signal.addEventListener('abort', () => {
19
+ aborted++;
20
+ resolve('aborted');
21
+ })
22
+ ),
23
+ abortedCount: () => aborted
24
+ },
25
+ {
26
+ addEventListener: (_type, listener) =>
27
+ parentPort?.on('message', (data) => listener({ data })),
28
+ postMessage: (message) => parentPort?.postMessage(message)
29
+ }
30
+ );
@@ -0,0 +1,21 @@
1
+ // A hand written worker script, answering by task name, with the replies a
2
+ // worker script can get wrong
3
+ import { parentPort } from 'node:worker_threads';
4
+
5
+ parentPort?.on('message', ({ id, task, input }) => {
6
+ const reply = (message: unknown) => parentPort?.postMessage(message);
7
+
8
+ if (task === 'echo') reply({ id, result: input });
9
+ else if (task === 'errorString') reply({ id, error: 'task failed' });
10
+ else if (task === 'errorObject')
11
+ reply({ id, error: { code: 'E_TASK', message: 'bad input' } });
12
+ else if (task === 'errorEmpty') reply({ id, error: '' });
13
+ else if (task === 'errorOther') reply({ id, error: 42 });
14
+ // JSON can't hold a BigInt, so the message falls back to String()
15
+ else if (task === 'errorBigInt') reply({ id, error: 10n });
16
+ else if (task === 'noResult') reply({ id });
17
+ else if (task === 'null') reply(null);
18
+ else if (task === 'stranger') reply({ id: 9999, result: 'not yours' });
19
+ else if (task === 'throw') throw new Error('thrown inside the worker');
20
+ // 'hang', and anything else: never answer
21
+ });
@@ -0,0 +1,69 @@
1
+ // A small Web Worker on top of node:worker_threads, so the tests run tasks in
2
+ // real threads instead of mocks. Node has no global Worker of its own.
3
+ import { Worker as Thread } from 'node:worker_threads';
4
+
5
+ export class ThreadWorker extends EventTarget {
6
+ /** Workers started so far. */
7
+ static started = 0;
8
+ /** The last worker started, to send it events in tests. */
9
+ static last?: ThreadWorker;
10
+ private readonly thread: Thread;
11
+
12
+ constructor(url: string | URL) {
13
+ super();
14
+
15
+ if (String(url).includes('constructor-throws')) {
16
+ throw new TypeError(`Failed to construct 'Worker': bad URL ${url}`);
17
+ }
18
+
19
+ ThreadWorker.started++;
20
+ ThreadWorker.last = this;
21
+ this.thread = new Thread(new URL(url));
22
+ this.thread.on('message', (data) =>
23
+ this.dispatchEvent(new MessageEvent('message', { data }))
24
+ );
25
+ this.thread.on('error', (error: Error & { code?: string }) => {
26
+ const event = new Event('error');
27
+
28
+ // Browsers give no message when the script fails to load
29
+ if (error.code !== 'ERR_MODULE_NOT_FOUND') {
30
+ Object.assign(event, { message: error.message, error });
31
+ }
32
+
33
+ this.dispatchEvent(event);
34
+ });
35
+ }
36
+
37
+ postMessage(message: unknown) {
38
+ this.thread.postMessage(message);
39
+ }
40
+
41
+ terminate() {
42
+ void this.thread.terminate();
43
+ }
44
+ }
45
+
46
+ /** Run fn with the global Worker set to worker. */
47
+ const withGlobalWorker = async <T>(
48
+ worker: unknown,
49
+ fn: () => T | Promise<T>
50
+ ) => {
51
+ const global = globalThis as { Worker?: unknown };
52
+ const original = global.Worker;
53
+
54
+ global.Worker = worker;
55
+
56
+ try {
57
+ return await fn();
58
+ } finally {
59
+ global.Worker = original;
60
+ }
61
+ };
62
+
63
+ /** Run fn with ThreadWorker as the global Worker. */
64
+ export const withWorker = <T>(fn: () => T | Promise<T>) =>
65
+ withGlobalWorker(ThreadWorker, fn);
66
+
67
+ /** Run fn with no global Worker, as in Node. */
68
+ export const withoutWorker = <T>(fn: () => T | Promise<T>) =>
69
+ withGlobalWorker(undefined, fn);