@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/src/types.ts
CHANGED
|
@@ -1,53 +1,102 @@
|
|
|
1
|
+
import type { TaskContextInterface } from '@hybrid-compute/core';
|
|
2
|
+
|
|
1
3
|
/**
|
|
2
|
-
*
|
|
3
|
-
*
|
|
4
|
-
* This message includes a task name, its input payload, and a unique ID used to match
|
|
5
|
-
* the response from the worker.
|
|
4
|
+
* Options for {@link createThreadedCompute}.
|
|
6
5
|
*
|
|
7
|
-
* @property
|
|
8
|
-
*
|
|
9
|
-
* @property
|
|
6
|
+
* @property url - The worker script, started as a module worker. Usually
|
|
7
|
+
* `new URL('./worker.js', import.meta.url)`, so bundlers find it.
|
|
8
|
+
* @property canRunTasks - The tasks the worker script can run. Only these are
|
|
9
|
+
* sent to it.
|
|
10
|
+
* @property timeout - How long to wait for a reply, in milliseconds, before
|
|
11
|
+
* rejecting with a `WorkerTaskError`. Defaults to `0`: no timeout, since
|
|
12
|
+
* workers are for long running work.
|
|
10
13
|
*
|
|
11
14
|
* @example
|
|
12
15
|
* ```ts
|
|
13
|
-
* const
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
*
|
|
16
|
+
* const options: ThreadedComputeOptionsInterface = {
|
|
17
|
+
* url: new URL('./worker.js', import.meta.url),
|
|
18
|
+
* canRunTasks: ['resizeImage'],
|
|
19
|
+
* timeout: 10_000
|
|
17
20
|
* };
|
|
18
|
-
* worker.postMessage(message);
|
|
19
21
|
* ```
|
|
20
22
|
*/
|
|
21
|
-
export interface
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
id: number;
|
|
23
|
+
export interface ThreadedComputeOptionsInterface {
|
|
24
|
+
url: string | URL;
|
|
25
|
+
canRunTasks: readonly string[];
|
|
26
|
+
timeout?: number;
|
|
26
27
|
}
|
|
27
28
|
|
|
28
29
|
/**
|
|
29
|
-
*
|
|
30
|
+
* What the worker script receives for each task: the task name, its input
|
|
31
|
+
* and an `id`, which the reply must repeat. The input is copied with the
|
|
32
|
+
* structured clone algorithm, so it can't hold functions or DOM nodes.
|
|
30
33
|
*
|
|
31
|
-
*
|
|
34
|
+
* @example
|
|
35
|
+
* ```ts
|
|
36
|
+
* const message: WorkerTaskMessageInterface = { id: 1, task: 'double', input: 21 };
|
|
37
|
+
* ```
|
|
32
38
|
*
|
|
33
|
-
* @
|
|
34
|
-
|
|
35
|
-
|
|
39
|
+
* @see https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm
|
|
40
|
+
*/
|
|
41
|
+
export interface WorkerTaskMessageInterface<Input = unknown> {
|
|
42
|
+
id: number;
|
|
43
|
+
task: string;
|
|
44
|
+
input: Input;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* What the worker script receives when a task is cancelled or times out:
|
|
49
|
+
* the task's `id` and `cancel: true`. {@link exposeTasks} aborts the task's
|
|
50
|
+
* signal; a hand written worker script can ignore it.
|
|
36
51
|
*
|
|
37
52
|
* @example
|
|
38
53
|
* ```ts
|
|
39
|
-
* const
|
|
40
|
-
* id: 1,
|
|
41
|
-
* result: 42
|
|
42
|
-
* };
|
|
43
|
-
* postMessage(response);
|
|
54
|
+
* const message: WorkerCancelMessageInterface = { id: 1, cancel: true };
|
|
44
55
|
* ```
|
|
56
|
+
*/
|
|
57
|
+
export interface WorkerCancelMessageInterface {
|
|
58
|
+
id: number;
|
|
59
|
+
cancel: true;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* What the worker script sends back: the task's `id` with either a `result`
|
|
64
|
+
* or an `error`. An `error` (a message string, or an object with a `message`)
|
|
65
|
+
* rejects the task with a `WorkerTaskError`.
|
|
45
66
|
*
|
|
46
|
-
* @
|
|
67
|
+
* @example
|
|
68
|
+
* ```ts
|
|
69
|
+
* self.postMessage({ id: 1, result: 42 } satisfies WorkerResultMessageInterface);
|
|
70
|
+
* ```
|
|
47
71
|
*/
|
|
48
|
-
export interface WorkerResultMessageInterface {
|
|
72
|
+
export interface WorkerResultMessageInterface<Output = unknown> {
|
|
49
73
|
id: number;
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
74
|
+
result?: Output;
|
|
75
|
+
error?: unknown;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/**
|
|
79
|
+
* A task in the worker script, for {@link exposeTasks}. It gets the input and
|
|
80
|
+
* a context with a `signal`, which aborts when the caller cancels the task or
|
|
81
|
+
* its timeout passes.
|
|
82
|
+
*
|
|
83
|
+
* @typeParam Input - The input type of the task.
|
|
84
|
+
* @typeParam Output - The output type of the task.
|
|
85
|
+
*/
|
|
86
|
+
export type WorkerTaskType<Input = never, Output = unknown> = (
|
|
87
|
+
input: Input,
|
|
88
|
+
context: Required<TaskContextInterface>
|
|
89
|
+
) => Output | Promise<Output>;
|
|
90
|
+
|
|
91
|
+
/**
|
|
92
|
+
* Where {@link exposeTasks} listens and replies. Defaults to the worker's
|
|
93
|
+
* global scope (`self`); pass another one to adapt it, for example to a
|
|
94
|
+
* `MessagePort`.
|
|
95
|
+
*/
|
|
96
|
+
export interface WorkerScopeInterface {
|
|
97
|
+
addEventListener(
|
|
98
|
+
type: 'message',
|
|
99
|
+
listener: (event: { data: unknown }) => void
|
|
100
|
+
): void;
|
|
101
|
+
postMessage(message: unknown): void;
|
|
53
102
|
}
|
package/src/utils.ts
ADDED
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
/** What a value is, for error messages: null, an array, or its typeof. */
|
|
2
|
+
export const describeValue = (value: unknown) => {
|
|
3
|
+
if (value === null) return 'null';
|
|
4
|
+
|
|
5
|
+
if (Array.isArray(value)) return 'an array';
|
|
6
|
+
|
|
7
|
+
if (value === '') return 'an empty string';
|
|
8
|
+
|
|
9
|
+
return typeof value;
|
|
10
|
+
};
|
|
11
|
+
|
|
12
|
+
export const isPlainObject = (
|
|
13
|
+
value: unknown
|
|
14
|
+
): value is Record<string, unknown> =>
|
|
15
|
+
typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
16
|
+
|
|
17
|
+
/** The message for an `error` value: a string, or an object's message. */
|
|
18
|
+
export const messageOf = (error: unknown) => {
|
|
19
|
+
if (typeof error === 'string') return error;
|
|
20
|
+
|
|
21
|
+
if (isPlainObject(error) && typeof error.message === 'string') {
|
|
22
|
+
return error.message;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
try {
|
|
26
|
+
return JSON.stringify(error);
|
|
27
|
+
} catch {
|
|
28
|
+
return String(error);
|
|
29
|
+
}
|
|
30
|
+
};
|