@hybrid-compute/worker 0.37.3 → 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/src/types.ts CHANGED
@@ -1,53 +1,102 @@
1
+ import type { TaskContextInterface } from '@hybrid-compute/core';
2
+
1
3
  /**
2
- * The message format sent from the main thread to a Web Worker when executing a task.
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 task - The name of the task to be executed in the worker.
8
- * @property input - The input data for the task. This can be any JSON-serializable value.
9
- * @property id - A unique identifier for correlating the response message.
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 message: WorkerTaskMessageInterface = {
14
- * task: 'double',
15
- * input: 21,
16
- * id: 1
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 WorkerTaskMessageInterface {
22
- task: string;
23
- // eslint-disable-next-line @typescript-eslint/no-explicit-any
24
- input: any;
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
- * The message format sent from a Web Worker back to the main thread upon task completion.
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
- * This message includes the result of the task execution or an error message if the task failed.
34
+ * @example
35
+ * ```ts
36
+ * const message: WorkerTaskMessageInterface = { id: 1, task: 'double', input: 21 };
37
+ * ```
32
38
  *
33
- * @property id - The unique identifier that matches a previously sent task message.
34
- * @property result - The result of the task execution (if successful).
35
- * @property error - An optional error message if the task failed.
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 response: WorkerResultMessageInterface = {
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
- * @see https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers
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
- // eslint-disable-next-line @typescript-eslint/no-explicit-any
51
- result: any;
52
- error?: string;
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
+ };