@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/expose.ts ADDED
@@ -0,0 +1,130 @@
1
+ import type { WorkerScopeInterface, WorkerTaskType } from './types.js';
2
+ import { describeValue, isPlainObject } from './utils.js';
3
+
4
+ /** An error as a value the structured clone algorithm can copy. */
5
+ const toErrorValue = (error: unknown) => {
6
+ if (error instanceof Error)
7
+ return { name: error.name, message: error.message };
8
+
9
+ if (typeof error === 'string') return error;
10
+
11
+ return { message: String(error) };
12
+ };
13
+ /** The worker's global scope, or a TypeError outside a worker. */
14
+ const workerScope = (): WorkerScopeInterface => {
15
+ const scope = globalThis as unknown as Partial<WorkerScopeInterface>;
16
+
17
+ if (
18
+ !('WorkerGlobalScope' in globalThis) ||
19
+ typeof scope.addEventListener !== 'function' ||
20
+ typeof scope.postMessage !== 'function'
21
+ ) {
22
+ throw new TypeError(
23
+ 'exposeTasks must be called in a worker script, or be given a scope to listen on'
24
+ );
25
+ }
26
+
27
+ return scope as WorkerScopeInterface;
28
+ };
29
+
30
+ /**
31
+ * Answers tasks from {@link ThreadedCompute} in a worker script: it listens
32
+ * for task messages, runs the task with that name, and replies with its
33
+ * result, or with an error if the task throws, rejects or doesn't exist.
34
+ *
35
+ * Each task gets the input and a context with a `signal`, which aborts when
36
+ * the caller cancels the task or its timeout passes. A task that checks the
37
+ * signal can stop early; its reply is then not sent.
38
+ *
39
+ * @param tasks - The tasks, by name. List the same names in `canRunTasks`.
40
+ * @param scope - Where to listen and reply. Defaults to the worker's global
41
+ * scope.
42
+ *
43
+ * @throws {TypeError} If `tasks` isn't an object of functions, or if it's
44
+ * called outside a worker without a `scope`.
45
+ *
46
+ * @example
47
+ * ```ts
48
+ * // worker.js
49
+ * import { exposeTasks } from '@hybrid-compute/worker';
50
+ *
51
+ * exposeTasks({
52
+ * double: (n: number) => n * 2,
53
+ * slowSum: async (numbers: number[], { signal }) => {
54
+ * let sum = 0;
55
+ *
56
+ * for (const n of numbers) {
57
+ * signal.throwIfAborted();
58
+ * sum += n;
59
+ * }
60
+ *
61
+ * return sum;
62
+ * }
63
+ * });
64
+ * ```
65
+ */
66
+ export function exposeTasks(
67
+ tasks: Readonly<Record<string, WorkerTaskType>>,
68
+ scope?: WorkerScopeInterface
69
+ ): void {
70
+ if (
71
+ !isPlainObject(tasks) ||
72
+ !Object.values(tasks).every((task) => typeof task === 'function')
73
+ ) {
74
+ throw new TypeError(
75
+ `exposeTasks expects an object of task functions, got ${describeValue(tasks)}`
76
+ );
77
+ }
78
+
79
+ const target = scope ?? workerScope();
80
+ const running = new Map<number, AbortController>();
81
+ const reply = (message: Record<string, unknown>) => {
82
+ try {
83
+ target.postMessage(message);
84
+ } catch (error) {
85
+ // A result the structured clone algorithm can't copy
86
+ target.postMessage({
87
+ id: message.id,
88
+ error: {
89
+ name: 'DataCloneError',
90
+ message: `the result couldn't be sent: ${error instanceof Error ? error.message : String(error)}`
91
+ }
92
+ });
93
+ }
94
+ };
95
+ const run = async (id: number, name: string, input: unknown) => {
96
+ const controller = new AbortController();
97
+
98
+ running.set(id, controller);
99
+
100
+ try {
101
+ if (!Object.prototype.hasOwnProperty.call(tasks, name)) {
102
+ throw new Error(`No task '${name}' in this worker`);
103
+ }
104
+
105
+ const result = await tasks[name](input as never, {
106
+ signal: controller.signal
107
+ });
108
+
109
+ if (!controller.signal.aborted) reply({ id, result });
110
+ } catch (error) {
111
+ if (!controller.signal.aborted) reply({ id, error: toErrorValue(error) });
112
+ } finally {
113
+ running.delete(id);
114
+ }
115
+ };
116
+
117
+ target.addEventListener('message', ({ data }) => {
118
+ if (!isPlainObject(data) || typeof data.id !== 'number') return;
119
+
120
+ if (data.cancel === true) {
121
+ running.get(data.id)?.abort();
122
+
123
+ return;
124
+ }
125
+
126
+ if (typeof data.task !== 'string') return;
127
+
128
+ void run(data.id, data.task, data.input);
129
+ });
130
+ }
package/src/index.ts CHANGED
@@ -1,118 +1,389 @@
1
- import { ComputeBackendInterface } from '@hybrid-compute/core';
2
-
3
1
  import {
4
- WorkerResultMessageInterface,
2
+ NoBackendError,
3
+ type ComputeBackendInterface,
4
+ type RunTaskOptionsInterface
5
+ } from '@hybrid-compute/core';
6
+
7
+ import { WorkerTaskError } from './errors.js';
8
+ import type {
9
+ ThreadedComputeOptionsInterface,
10
+ WorkerCancelMessageInterface,
5
11
  WorkerTaskMessageInterface
6
12
  } from './types.js';
13
+ import { describeValue, isPlainObject, messageOf } from './utils.js';
14
+
15
+ export * from './errors.js';
16
+
17
+ export * from './expose.js';
7
18
 
8
19
  export * from './types.js';
9
20
 
21
+ /** A task waiting for its reply from the worker. */
22
+ type PendingTaskType = {
23
+ taskName: string;
24
+ resolve: (value: unknown) => void;
25
+ reject: (reason: unknown) => void;
26
+ };
27
+
28
+ /** Whether this runtime has Web Workers. */
29
+ const hasWorkers = () => typeof Worker === 'function';
10
30
  /**
11
- * `ThreadedCompute` is a compute backend that runs tasks in a dedicated Web Worker.
31
+ * Check the options and return them normalised.
12
32
  *
13
- * It manages communication with the worker via `postMessage`, assigns unique task
14
- * request IDs, and resolves results asynchronously. Tasks are registered by name
15
- * during construction and mapped internally for availability checks.
33
+ * @throws {TypeError} For a missing or wrongly typed option.
34
+ * @throws {RangeError} For a negative timeout.
35
+ */
36
+ const toSettings = (options: unknown) => {
37
+ if (!isPlainObject(options)) {
38
+ throw new TypeError(
39
+ `createThreadedCompute expects an options object, got ${describeValue(options)}`
40
+ );
41
+ }
42
+
43
+ const { url, canRunTasks, timeout } = options;
44
+
45
+ if (!(url instanceof URL) && (typeof url !== 'string' || url === '')) {
46
+ throw new TypeError(
47
+ `url must be a URL or a non-empty string, got ${describeValue(url)}`
48
+ );
49
+ }
50
+
51
+ if (
52
+ !Array.isArray(canRunTasks) ||
53
+ !canRunTasks.every((name) => typeof name === 'string' && name !== '')
54
+ ) {
55
+ throw new TypeError(
56
+ `canRunTasks must be an array of task names, got ${describeValue(canRunTasks)}`
57
+ );
58
+ }
59
+
60
+ if (
61
+ timeout !== undefined &&
62
+ (typeof timeout !== 'number' || !Number.isFinite(timeout))
63
+ ) {
64
+ throw new TypeError(
65
+ `timeout must be a number of milliseconds, got ${describeValue(timeout)}`
66
+ );
67
+ }
68
+
69
+ if (typeof timeout === 'number' && timeout < 0) {
70
+ throw new RangeError(
71
+ `timeout must be 0 (no timeout) or more, got ${timeout}`
72
+ );
73
+ }
74
+
75
+ return {
76
+ url: url as string | URL,
77
+ tasks: new Set(canRunTasks as string[]) as ReadonlySet<string>,
78
+ timeout: (timeout as number | undefined) ?? 0
79
+ };
80
+ };
81
+
82
+ /**
83
+ * ThreadedCompute is a backend that runs tasks in a dedicated module Web
84
+ * Worker, so heavy work doesn't block the main thread.
85
+ *
86
+ * It starts the worker on the first task, not when it's created, sends each
87
+ * task with an id and matches the replies by id. Write the worker script with
88
+ * {@link exposeTasks}, or by hand following {@link WorkerTaskMessageInterface}
89
+ * and {@link WorkerResultMessageInterface}.
90
+ *
91
+ * Every failure (an `error` in the reply, a crash, the timeout) rejects with a
92
+ * {@link WorkerTaskError}. If the worker crashes, a new one starts on the next
93
+ * task. Call {@link ThreadedCompute.close} when you're done with it.
94
+ *
95
+ * Web Workers only exist in browsers (and Deno and Bun): where there is no
96
+ * global `Worker`, `canRun` returns `false`, so the `auto` strategy uses
97
+ * another backend.
16
98
  *
17
99
  * @example
18
100
  * ```ts
19
- * const threaded = new ThreadedCompute(new URL('./worker.js', import.meta.url), ['add']);
101
+ * const threaded = createThreadedCompute({
102
+ * url: new URL('./worker.js', import.meta.url),
103
+ * canRunTasks: ['add']
104
+ * });
20
105
  *
21
106
  * const result = await threaded.runTask<number, number>('add', 5);
22
- * console.log(result); // Output from worker
23
107
  * ```
24
108
  *
25
109
  * @see https://developer.mozilla.org/en-US/docs/Web/API/Worker
26
110
  */
27
111
  export class ThreadedCompute implements ComputeBackendInterface {
28
- private worker: Worker;
29
- private taskMap = new Set<string>();
30
-
31
- // Map of task response IDs to success callbacks
32
- // eslint-disable-next-line @typescript-eslint/no-explicit-any
33
- private callbacks = new Map<number, (value: any) => void>();
34
-
35
- // Map of task response IDs to error callbacks
36
- // eslint-disable-next-line @typescript-eslint/no-explicit-any
37
- private errors = new Map<number, (err: any) => void>();
38
-
112
+ private readonly settings: ReturnType<typeof toSettings>;
113
+ private worker?: Worker;
114
+ private readonly pending = new Map<number, PendingTaskType>();
39
115
  private nextId = 1;
40
116
 
41
117
  /**
42
- * Constructs a new `ThreadedCompute` backend with a specified worker and list of available task names.
118
+ * Creates the backend. It checks the options, and starts no worker until
119
+ * the first task.
43
120
  *
44
- * @param workerPath - Path to the worker script (typically a URL via `import.meta.url`).
45
- * @param taskNames - A list of task identifiers this worker is capable of executing.
121
+ * @param options - The worker script, the tasks it can run and,
122
+ * optionally, a timeout.
123
+ *
124
+ * @throws {TypeError} For a missing or wrongly typed option.
125
+ * @throws {RangeError} For a negative timeout.
46
126
  */
47
- constructor(workerPath: string, taskNames: string[]) {
48
- this.worker = new Worker(workerPath, { type: 'module' });
49
- this.taskMap = new Set(taskNames);
50
-
51
- this.worker.onmessage = (e: MessageEvent<WorkerResultMessageInterface>) => {
52
- const { id, result, error } = e.data;
53
-
54
- if (error) this.errors.get(id)?.(error);
55
- else this.callbacks.get(id)?.(result);
56
-
57
- this.callbacks.delete(id);
58
- this.errors.delete(id);
59
- };
127
+ constructor(options: ThreadedComputeOptionsInterface) {
128
+ this.settings = toSettings(options);
60
129
  }
61
130
 
62
131
  /**
63
- * Checks whether the current worker is registered to handle a given task.
132
+ * Determines if this backend can run the given task.
64
133
  *
65
- * @param taskName - The name of the task to check.
66
- * @returns `true` if the task is supported, otherwise `false`.
134
+ * @param taskName - Name of the task.
135
+ * @returns `true` if the task is in `canRunTasks` and this runtime has Web
136
+ * Workers.
67
137
  */
68
138
  canRun(taskName: string): boolean {
69
- return this.taskMap.has(taskName);
139
+ return hasWorkers() && this.settings.tasks.has(taskName);
70
140
  }
71
141
 
72
142
  /**
73
- * Runs a task inside the Web Worker.
143
+ * Runs a task in the worker and waits for its reply.
74
144
  *
75
- * The task is assigned a unique ID and sent via `postMessage`. The result or error
76
- * is resolved asynchronously when the worker responds.
145
+ * @typeParam Input - The input type of the task.
146
+ * @typeParam Output - The output type of the task.
77
147
  *
78
- * @typeParam Input - The input type for the task.
79
- * @typeParam Output - The output type returned by the task.
80
- *
81
- * @param taskName - The name of the task to execute.
82
- * @param input - The input payload for the task.
83
- * @returns A Promise resolving to the task output.
148
+ * @param taskName - The name of the task to run.
149
+ * @param input - The input for the task. It's copied with the structured
150
+ * clone algorithm, so it can't hold functions or DOM nodes.
151
+ * @param options - Options for this call. With a `signal`, `runTask`
152
+ * rejects with the signal's reason as soon as it aborts, and the worker is
153
+ * told to cancel the task.
154
+ * @returns A Promise resolving to the reply's `result`. It rejects with a
155
+ * `NoBackendError` (from `@hybrid-compute/core`) if the task isn't in
156
+ * `canRunTasks`, a `TypeError` if this runtime has no Web Workers, a
157
+ * {@link WorkerTaskError} if the task fails, and with the signal's reason
158
+ * if the call is cancelled.
84
159
  *
85
160
  * @example
86
161
  * ```ts
87
162
  * const result = await threaded.runTask('square', 9); // 81
88
163
  * ```
89
164
  */
90
- runTask<Input, Output>(taskName: string, input: Input): Promise<Output> {
165
+ async runTask<Input, Output>(
166
+ taskName: string,
167
+ input: Input,
168
+ options?: RunTaskOptionsInterface
169
+ ): Promise<Output> {
170
+ if (!this.settings.tasks.has(taskName)) {
171
+ throw new NoBackendError(
172
+ taskName,
173
+ 'worker',
174
+ `The worker can't run task '${taskName}'; it isn't in canRunTasks`
175
+ );
176
+ }
177
+
178
+ if (!hasWorkers()) {
179
+ throw new TypeError(
180
+ 'Web Workers are not available in this runtime; @hybrid-compute/worker needs a global Worker'
181
+ );
182
+ }
183
+
184
+ const signal = options?.signal;
185
+
186
+ if (signal?.aborted) throw signal.reason;
187
+
188
+ const worker = this.start(taskName);
189
+ const { timeout } = this.settings;
190
+ const id = this.nextId++;
191
+
91
192
  return new Promise<Output>((resolve, reject) => {
92
- const id = this.nextId++;
193
+ let timer: ReturnType<typeof setTimeout> | undefined;
194
+
195
+ const finish = () => {
196
+ clearTimeout(timer);
197
+ signal?.removeEventListener('abort', onAbort);
198
+ this.pending.delete(id);
199
+ };
200
+ // Settled before the worker replied: tell the worker to stop
201
+ const cancel = () => {
202
+ const message: WorkerCancelMessageInterface = { id, cancel: true };
203
+
204
+ worker.postMessage(message);
205
+ };
206
+ const onAbort = () => {
207
+ finish();
208
+ cancel();
209
+ reject(signal?.reason);
210
+ };
211
+
212
+ if (timeout > 0) {
213
+ timer = setTimeout(() => {
214
+ finish();
215
+ cancel();
216
+ reject(
217
+ new WorkerTaskError(
218
+ taskName,
219
+ `Worker task '${taskName}' timed out after ${timeout} ms`
220
+ )
221
+ );
222
+ }, timeout);
223
+ }
224
+
225
+ signal?.addEventListener('abort', onAbort, { once: true });
226
+ this.pending.set(id, {
227
+ taskName,
228
+ resolve: (value) => {
229
+ finish();
230
+ resolve(value as Output);
231
+ },
232
+ reject: (reason) => {
233
+ finish();
234
+ reject(reason);
235
+ }
236
+ });
237
+
238
+ const message: WorkerTaskMessageInterface<Input> = {
239
+ id,
240
+ task: taskName,
241
+ input
242
+ };
243
+
244
+ try {
245
+ worker.postMessage(message);
246
+ } catch (error) {
247
+ this.pending
248
+ .get(id)
249
+ ?.reject(
250
+ new WorkerTaskError(
251
+ taskName,
252
+ `Worker task '${taskName}' couldn't send its input to the worker`,
253
+ { cause: error }
254
+ )
255
+ );
256
+ }
257
+ });
258
+ }
259
+
260
+ /**
261
+ * Terminates the worker, if one is running. Tasks still waiting for a
262
+ * reply reject with a {@link WorkerTaskError}. The next task starts a new
263
+ * worker.
264
+ */
265
+ close(): void {
266
+ const { worker } = this;
267
+
268
+ this.worker = undefined;
269
+ worker?.terminate();
270
+ this.rejectPending('the worker was closed');
271
+ }
272
+
273
+ /** The running worker, starting one first if needed. */
274
+ private start(taskName: string): Worker {
275
+ if (this.worker) return this.worker;
93
276
 
94
- this.callbacks.set(id, resolve);
95
- this.errors.set(id, reject);
277
+ let worker: Worker;
96
278
 
97
- const message: WorkerTaskMessageInterface = { task: taskName, input, id };
279
+ try {
280
+ worker = new Worker(this.settings.url, { type: 'module' });
281
+ } catch (error) {
282
+ throw new WorkerTaskError(
283
+ taskName,
284
+ `Worker task '${taskName}' couldn't start the worker ${String(this.settings.url)}`,
285
+ { cause: error }
286
+ );
287
+ }
98
288
 
99
- this.worker.postMessage(message);
289
+ worker.addEventListener('message', (event) => this.onMessage(event));
290
+ // An uncaught error, or a script that fails to load: the worker is in an
291
+ // unknown state, so reject what it was doing and start over next time
292
+ worker.addEventListener('error', (event) => {
293
+ if (this.worker !== worker) return;
294
+
295
+ const detail = (event as Partial<ErrorEvent>).message;
296
+
297
+ this.worker = undefined;
298
+ worker.terminate();
299
+ this.rejectPending(
300
+ detail
301
+ ? `the worker threw: ${detail}`
302
+ : 'the worker failed: its script did not load, or threw while starting',
303
+ event
304
+ );
305
+ });
306
+ // A reply that couldn't be deserialised: nothing tells which task it
307
+ // was for, so reject them all instead of letting one wait forever
308
+ worker.addEventListener('messageerror', (event) => {
309
+ if (this.worker !== worker) return;
310
+
311
+ this.rejectPending('a reply from the worker could not be read', event);
100
312
  });
313
+ this.worker = worker;
314
+
315
+ return worker;
316
+ }
317
+
318
+ /** Match a reply to its task by id; ignore anything that can't be matched. */
319
+ private onMessage(event: MessageEvent) {
320
+ const reply: unknown = event.data;
321
+
322
+ if (!isPlainObject(reply) || typeof reply.id !== 'number') return;
323
+
324
+ const task = this.pending.get(reply.id);
325
+
326
+ if (!task) return;
327
+
328
+ const { taskName } = task;
329
+ const { error } = reply;
330
+
331
+ if (error !== undefined && error !== null) {
332
+ const text = messageOf(error);
333
+
334
+ task.reject(
335
+ new WorkerTaskError(
336
+ taskName,
337
+ `Worker task '${taskName}' failed${text ? `: ${text}` : ''}`,
338
+ { detail: error }
339
+ )
340
+ );
341
+ } else if ('result' in reply) {
342
+ task.resolve(reply.result);
343
+ } else {
344
+ task.reject(
345
+ new WorkerTaskError(
346
+ taskName,
347
+ `Worker task '${taskName}' got a reply with neither a result nor an error`
348
+ )
349
+ );
350
+ }
351
+ }
352
+
353
+ /** Reject every task still waiting for a reply. */
354
+ private rejectPending(why: string, cause?: unknown) {
355
+ for (const task of [...this.pending.values()]) {
356
+ task.reject(
357
+ new WorkerTaskError(
358
+ task.taskName,
359
+ `Worker task '${task.taskName}' got no reply: ${why}`,
360
+ { cause }
361
+ )
362
+ );
363
+ }
101
364
  }
102
365
  }
103
366
 
104
367
  /**
105
- * Factory function to create a new `ThreadedCompute` backend.
368
+ * Creates a ThreadedCompute backend.
106
369
  *
107
- * @param workerPath - The module worker file path (e.g. `new URL('./worker.js', import.meta.url)`).
108
- * @param tasks - A list of supported task names this worker can execute.
370
+ * @param options - The worker script, the tasks it can run and,
371
+ * optionally, a timeout.
109
372
  * @returns A new `ThreadedCompute` instance.
110
373
  *
374
+ * @throws {TypeError} For a missing or wrongly typed option.
375
+ * @throws {RangeError} For a negative timeout.
376
+ *
111
377
  * @example
112
378
  * ```ts
113
- * const backend = createThreadedCompute(new URL('./worker.js', import.meta.url), ['resizeImage']);
379
+ * const backend = createThreadedCompute({
380
+ * url: new URL('./worker.js', import.meta.url),
381
+ * canRunTasks: ['resizeImage']
382
+ * });
114
383
  * ```
115
384
  */
116
- export function createThreadedCompute(workerPath: string, tasks: string[]) {
117
- return new ThreadedCompute(workerPath, tasks);
385
+ export function createThreadedCompute(
386
+ options: ThreadedComputeOptionsInterface
387
+ ) {
388
+ return new ThreadedCompute(options);
118
389
  }