@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 +32 -0
- package/README.md +31 -9
- package/package.json +3 -3
- package/src/__tests__/expose.spec.ts +175 -0
- package/src/__tests__/fixtures/exposed.ts +30 -0
- package/src/__tests__/fixtures/raw.ts +21 -0
- package/src/__tests__/thread-worker.ts +69 -0
- package/src/__tests__/worker.spec.ts +418 -108
- package/src/errors.ts +49 -0
- package/src/expose.ts +130 -0
- package/src/index.ts +332 -61
- package/src/types.ts +81 -32
- package/src/utils.ts +30 -0
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://
|
|
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
|
-
|
|
32
|
-
-
|
|
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.
|
|
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.
|
|
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.
|
|
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);
|