@hybrid-compute/worker 0.37.3 → 0.38.1
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 +24 -0
- package/README.md +30 -8
- package/dist/errors.d.ts +38 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +37 -0
- package/dist/errors.js.map +1 -0
- package/dist/expose.d.ts +39 -0
- package/dist/expose.d.ts.map +1 -0
- package/dist/expose.js +111 -0
- package/dist/expose.js.map +1 -0
- package/dist/index.d.ts +115 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +276 -0
- package/dist/index.js.map +1 -0
- package/dist/types.d.ts +93 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +2 -0
- package/dist/types.js.map +1 -0
- package/dist/utils.d.ts +6 -0
- package/dist/utils.d.ts.map +1 -0
- package/dist/utils.js +26 -0
- package/dist/utils.js.map +1 -0
- package/package.json +5 -1
- package/.release-it.json +0 -83
- package/eslint.config.mjs +0 -3
- package/src/__tests__/worker.spec.ts +0 -139
- package/src/index.ts +0 -118
- package/src/types.ts +0 -53
- package/tsconfig.build.json +0 -13
- package/tsconfig.json +0 -13
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,29 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [0.38.1](https://github.com/phun-ky/hybrid-compute/compare/%40hybrid-compute%2Fworker%400.38.0...%40hybrid-compute%2Fworker%400.38.1) (2026-10-20)
|
|
4
|
+
|
|
5
|
+
### Bug
|
|
6
|
+
|
|
7
|
+
* 🐛 publish the built files: add files to every package.json ([6cb3c1a](https://github.com/phun-ky/hybrid-compute/commit/6cb3c1a91bd0cefd9eb12e0718b183a47f68181c))
|
|
8
|
+
|
|
9
|
+
## [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)
|
|
10
|
+
|
|
11
|
+
### ⚠ BREAKING CHANGES
|
|
12
|
+
|
|
13
|
+
* createThreadedCompute and the ThreadedCompute constructor
|
|
14
|
+
take an options object: createThreadedCompute({ url, canRunTasks }) instead
|
|
15
|
+
of createThreadedCompute(url, taskNames). Error replies reject with a
|
|
16
|
+
WorkerTaskError instead of the raw error value. A task that isn't in
|
|
17
|
+
canRunTasks rejects with NoBackendError instead of being sent.
|
|
18
|
+
|
|
19
|
+
### Documentation
|
|
20
|
+
|
|
21
|
+
* ✏️ 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)
|
|
22
|
+
|
|
23
|
+
### Feature
|
|
24
|
+
|
|
25
|
+
* 🎸 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)
|
|
26
|
+
|
|
3
27
|
## [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)
|
|
4
28
|
|
|
5
29
|
### Tasks
|
package/README.md
CHANGED
|
@@ -22,30 +22,52 @@ monorepo.
|
|
|
22
22
|
## API Docs
|
|
23
23
|
|
|
24
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/dist/errors.d.ts
ADDED
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Why a worker task failed: the worker script replied with an `error`, the
|
|
3
|
+
* reply was unusable, the worker crashed or couldn't start, the input couldn't
|
|
4
|
+
* be sent, the timeout passed, or the backend was closed.
|
|
5
|
+
*
|
|
6
|
+
* A task cancelled with an `AbortSignal` rejects with the signal's reason
|
|
7
|
+
* instead, so a `WorkerTaskError` always means something went wrong.
|
|
8
|
+
*
|
|
9
|
+
* @example
|
|
10
|
+
* ```ts
|
|
11
|
+
* try {
|
|
12
|
+
* await threaded.runTask('resizeImage', blob);
|
|
13
|
+
* } catch (error) {
|
|
14
|
+
* if (error instanceof WorkerTaskError) {
|
|
15
|
+
* console.warn(`${error.taskName} failed`, error.detail);
|
|
16
|
+
* }
|
|
17
|
+
* }
|
|
18
|
+
* ```
|
|
19
|
+
*/
|
|
20
|
+
export declare class WorkerTaskError extends Error {
|
|
21
|
+
/** The name of the task that failed. */
|
|
22
|
+
readonly taskName: string;
|
|
23
|
+
/** The worker script's `error` value as it was sent, if it sent one. */
|
|
24
|
+
readonly detail?: unknown;
|
|
25
|
+
/** The underlying error or event, such as a worker crash, if there is one. */
|
|
26
|
+
readonly cause?: unknown;
|
|
27
|
+
/**
|
|
28
|
+
* @param taskName - The name of the task that failed.
|
|
29
|
+
* @param message - What went wrong.
|
|
30
|
+
* @param details - The worker script's error value and the underlying
|
|
31
|
+
* error, where there is one.
|
|
32
|
+
*/
|
|
33
|
+
constructor(taskName: string, message: string, details?: {
|
|
34
|
+
detail?: unknown;
|
|
35
|
+
cause?: unknown;
|
|
36
|
+
});
|
|
37
|
+
}
|
|
38
|
+
//# sourceMappingURL=errors.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,wEAAwE;IACxE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAE1B,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAEzB;;;;;OAKG;gBAED,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAUtD"}
|
package/dist/errors.js
ADDED
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Why a worker task failed: the worker script replied with an `error`, the
|
|
3
|
+
* reply was unusable, the worker crashed or couldn't start, the input couldn't
|
|
4
|
+
* be sent, the timeout passed, or the backend was closed.
|
|
5
|
+
*
|
|
6
|
+
* A task cancelled with an `AbortSignal` rejects with the signal's reason
|
|
7
|
+
* instead, so a `WorkerTaskError` always means something went wrong.
|
|
8
|
+
*
|
|
9
|
+
* @example
|
|
10
|
+
* ```ts
|
|
11
|
+
* try {
|
|
12
|
+
* await threaded.runTask('resizeImage', blob);
|
|
13
|
+
* } catch (error) {
|
|
14
|
+
* if (error instanceof WorkerTaskError) {
|
|
15
|
+
* console.warn(`${error.taskName} failed`, error.detail);
|
|
16
|
+
* }
|
|
17
|
+
* }
|
|
18
|
+
* ```
|
|
19
|
+
*/
|
|
20
|
+
export class WorkerTaskError extends Error {
|
|
21
|
+
/**
|
|
22
|
+
* @param taskName - The name of the task that failed.
|
|
23
|
+
* @param message - What went wrong.
|
|
24
|
+
* @param details - The worker script's error value and the underlying
|
|
25
|
+
* error, where there is one.
|
|
26
|
+
*/
|
|
27
|
+
constructor(taskName, message, details = {}) {
|
|
28
|
+
super(message);
|
|
29
|
+
this.name = 'WorkerTaskError';
|
|
30
|
+
this.taskName = taskName;
|
|
31
|
+
if (details.cause !== undefined)
|
|
32
|
+
this.cause = details.cause;
|
|
33
|
+
if ('detail' in details)
|
|
34
|
+
this.detail = details.detail;
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
//# sourceMappingURL=errors.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAUxC;;;;;OAKG;IACH,YACE,QAAgB,EAChB,OAAe,EACf,UAAiD,EAAE;QAEnD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QAEzB,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAE5D,IAAI,QAAQ,IAAI,OAAO;YAAE,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IACxD,CAAC;CACF"}
|
package/dist/expose.d.ts
ADDED
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
import type { WorkerScopeInterface, WorkerTaskType } from './types.js';
|
|
2
|
+
/**
|
|
3
|
+
* Answers tasks from {@link ThreadedCompute} in a worker script: it listens
|
|
4
|
+
* for task messages, runs the task with that name, and replies with its
|
|
5
|
+
* result, or with an error if the task throws, rejects or doesn't exist.
|
|
6
|
+
*
|
|
7
|
+
* Each task gets the input and a context with a `signal`, which aborts when
|
|
8
|
+
* the caller cancels the task or its timeout passes. A task that checks the
|
|
9
|
+
* signal can stop early; its reply is then not sent.
|
|
10
|
+
*
|
|
11
|
+
* @param tasks - The tasks, by name. List the same names in `canRunTasks`.
|
|
12
|
+
* @param scope - Where to listen and reply. Defaults to the worker's global
|
|
13
|
+
* scope.
|
|
14
|
+
*
|
|
15
|
+
* @throws {TypeError} If `tasks` isn't an object of functions, or if it's
|
|
16
|
+
* called outside a worker without a `scope`.
|
|
17
|
+
*
|
|
18
|
+
* @example
|
|
19
|
+
* ```ts
|
|
20
|
+
* // worker.js
|
|
21
|
+
* import { exposeTasks } from '@hybrid-compute/worker';
|
|
22
|
+
*
|
|
23
|
+
* exposeTasks({
|
|
24
|
+
* double: (n: number) => n * 2,
|
|
25
|
+
* slowSum: async (numbers: number[], { signal }) => {
|
|
26
|
+
* let sum = 0;
|
|
27
|
+
*
|
|
28
|
+
* for (const n of numbers) {
|
|
29
|
+
* signal.throwIfAborted();
|
|
30
|
+
* sum += n;
|
|
31
|
+
* }
|
|
32
|
+
*
|
|
33
|
+
* return sum;
|
|
34
|
+
* }
|
|
35
|
+
* });
|
|
36
|
+
* ```
|
|
37
|
+
*/
|
|
38
|
+
export declare function exposeTasks(tasks: Readonly<Record<string, WorkerTaskType>>, scope?: WorkerScopeInterface): void;
|
|
39
|
+
//# sourceMappingURL=expose.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"expose.d.ts","sourceRoot":"","sources":["../src/expose.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AA6BvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,EAC/C,KAAK,CAAC,EAAE,oBAAoB,GAC3B,IAAI,CA6DN"}
|
package/dist/expose.js
ADDED
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
import { describeValue, isPlainObject } from './utils.js';
|
|
2
|
+
/** An error as a value the structured clone algorithm can copy. */
|
|
3
|
+
const toErrorValue = (error) => {
|
|
4
|
+
if (error instanceof Error)
|
|
5
|
+
return { name: error.name, message: error.message };
|
|
6
|
+
if (typeof error === 'string')
|
|
7
|
+
return error;
|
|
8
|
+
return { message: String(error) };
|
|
9
|
+
};
|
|
10
|
+
/** The worker's global scope, or a TypeError outside a worker. */
|
|
11
|
+
const workerScope = () => {
|
|
12
|
+
const scope = globalThis;
|
|
13
|
+
if (!('WorkerGlobalScope' in globalThis) ||
|
|
14
|
+
typeof scope.addEventListener !== 'function' ||
|
|
15
|
+
typeof scope.postMessage !== 'function') {
|
|
16
|
+
throw new TypeError('exposeTasks must be called in a worker script, or be given a scope to listen on');
|
|
17
|
+
}
|
|
18
|
+
return scope;
|
|
19
|
+
};
|
|
20
|
+
/**
|
|
21
|
+
* Answers tasks from {@link ThreadedCompute} in a worker script: it listens
|
|
22
|
+
* for task messages, runs the task with that name, and replies with its
|
|
23
|
+
* result, or with an error if the task throws, rejects or doesn't exist.
|
|
24
|
+
*
|
|
25
|
+
* Each task gets the input and a context with a `signal`, which aborts when
|
|
26
|
+
* the caller cancels the task or its timeout passes. A task that checks the
|
|
27
|
+
* signal can stop early; its reply is then not sent.
|
|
28
|
+
*
|
|
29
|
+
* @param tasks - The tasks, by name. List the same names in `canRunTasks`.
|
|
30
|
+
* @param scope - Where to listen and reply. Defaults to the worker's global
|
|
31
|
+
* scope.
|
|
32
|
+
*
|
|
33
|
+
* @throws {TypeError} If `tasks` isn't an object of functions, or if it's
|
|
34
|
+
* called outside a worker without a `scope`.
|
|
35
|
+
*
|
|
36
|
+
* @example
|
|
37
|
+
* ```ts
|
|
38
|
+
* // worker.js
|
|
39
|
+
* import { exposeTasks } from '@hybrid-compute/worker';
|
|
40
|
+
*
|
|
41
|
+
* exposeTasks({
|
|
42
|
+
* double: (n: number) => n * 2,
|
|
43
|
+
* slowSum: async (numbers: number[], { signal }) => {
|
|
44
|
+
* let sum = 0;
|
|
45
|
+
*
|
|
46
|
+
* for (const n of numbers) {
|
|
47
|
+
* signal.throwIfAborted();
|
|
48
|
+
* sum += n;
|
|
49
|
+
* }
|
|
50
|
+
*
|
|
51
|
+
* return sum;
|
|
52
|
+
* }
|
|
53
|
+
* });
|
|
54
|
+
* ```
|
|
55
|
+
*/
|
|
56
|
+
export function exposeTasks(tasks, scope) {
|
|
57
|
+
if (!isPlainObject(tasks) ||
|
|
58
|
+
!Object.values(tasks).every((task) => typeof task === 'function')) {
|
|
59
|
+
throw new TypeError(`exposeTasks expects an object of task functions, got ${describeValue(tasks)}`);
|
|
60
|
+
}
|
|
61
|
+
const target = scope ?? workerScope();
|
|
62
|
+
const running = new Map();
|
|
63
|
+
const reply = (message) => {
|
|
64
|
+
try {
|
|
65
|
+
target.postMessage(message);
|
|
66
|
+
}
|
|
67
|
+
catch (error) {
|
|
68
|
+
// A result the structured clone algorithm can't copy
|
|
69
|
+
target.postMessage({
|
|
70
|
+
id: message.id,
|
|
71
|
+
error: {
|
|
72
|
+
name: 'DataCloneError',
|
|
73
|
+
message: `the result couldn't be sent: ${error instanceof Error ? error.message : String(error)}`
|
|
74
|
+
}
|
|
75
|
+
});
|
|
76
|
+
}
|
|
77
|
+
};
|
|
78
|
+
const run = async (id, name, input) => {
|
|
79
|
+
const controller = new AbortController();
|
|
80
|
+
running.set(id, controller);
|
|
81
|
+
try {
|
|
82
|
+
if (!Object.prototype.hasOwnProperty.call(tasks, name)) {
|
|
83
|
+
throw new Error(`No task '${name}' in this worker`);
|
|
84
|
+
}
|
|
85
|
+
const result = await tasks[name](input, {
|
|
86
|
+
signal: controller.signal
|
|
87
|
+
});
|
|
88
|
+
if (!controller.signal.aborted)
|
|
89
|
+
reply({ id, result });
|
|
90
|
+
}
|
|
91
|
+
catch (error) {
|
|
92
|
+
if (!controller.signal.aborted)
|
|
93
|
+
reply({ id, error: toErrorValue(error) });
|
|
94
|
+
}
|
|
95
|
+
finally {
|
|
96
|
+
running.delete(id);
|
|
97
|
+
}
|
|
98
|
+
};
|
|
99
|
+
target.addEventListener('message', ({ data }) => {
|
|
100
|
+
if (!isPlainObject(data) || typeof data.id !== 'number')
|
|
101
|
+
return;
|
|
102
|
+
if (data.cancel === true) {
|
|
103
|
+
running.get(data.id)?.abort();
|
|
104
|
+
return;
|
|
105
|
+
}
|
|
106
|
+
if (typeof data.task !== 'string')
|
|
107
|
+
return;
|
|
108
|
+
void run(data.id, data.task, data.input);
|
|
109
|
+
});
|
|
110
|
+
}
|
|
111
|
+
//# sourceMappingURL=expose.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"expose.js","sourceRoot":"","sources":["../src/expose.ts"],"names":[],"mappings":"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"}
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
import { type ComputeBackendInterface, type RunTaskOptionsInterface } from '@hybrid-compute/core';
|
|
2
|
+
import type { ThreadedComputeOptionsInterface } from './types.js';
|
|
3
|
+
export * from './errors.js';
|
|
4
|
+
export * from './expose.js';
|
|
5
|
+
export * from './types.js';
|
|
6
|
+
/**
|
|
7
|
+
* ThreadedCompute is a backend that runs tasks in a dedicated module Web
|
|
8
|
+
* Worker, so heavy work doesn't block the main thread.
|
|
9
|
+
*
|
|
10
|
+
* It starts the worker on the first task, not when it's created, sends each
|
|
11
|
+
* task with an id and matches the replies by id. Write the worker script with
|
|
12
|
+
* {@link exposeTasks}, or by hand following {@link WorkerTaskMessageInterface}
|
|
13
|
+
* and {@link WorkerResultMessageInterface}.
|
|
14
|
+
*
|
|
15
|
+
* Every failure (an `error` in the reply, a crash, the timeout) rejects with a
|
|
16
|
+
* {@link WorkerTaskError}. If the worker crashes, a new one starts on the next
|
|
17
|
+
* task. Call {@link ThreadedCompute.close} when you're done with it.
|
|
18
|
+
*
|
|
19
|
+
* Web Workers only exist in browsers (and Deno and Bun): where there is no
|
|
20
|
+
* global `Worker`, `canRun` returns `false`, so the `auto` strategy uses
|
|
21
|
+
* another backend.
|
|
22
|
+
*
|
|
23
|
+
* @example
|
|
24
|
+
* ```ts
|
|
25
|
+
* const threaded = createThreadedCompute({
|
|
26
|
+
* url: new URL('./worker.js', import.meta.url),
|
|
27
|
+
* canRunTasks: ['add']
|
|
28
|
+
* });
|
|
29
|
+
*
|
|
30
|
+
* const result = await threaded.runTask<number, number>('add', 5);
|
|
31
|
+
* ```
|
|
32
|
+
*
|
|
33
|
+
* @see https://developer.mozilla.org/en-US/docs/Web/API/Worker
|
|
34
|
+
*/
|
|
35
|
+
export declare class ThreadedCompute implements ComputeBackendInterface {
|
|
36
|
+
private readonly settings;
|
|
37
|
+
private worker?;
|
|
38
|
+
private readonly pending;
|
|
39
|
+
private nextId;
|
|
40
|
+
/**
|
|
41
|
+
* Creates the backend. It checks the options, and starts no worker until
|
|
42
|
+
* the first task.
|
|
43
|
+
*
|
|
44
|
+
* @param options - The worker script, the tasks it can run and,
|
|
45
|
+
* optionally, a timeout.
|
|
46
|
+
*
|
|
47
|
+
* @throws {TypeError} For a missing or wrongly typed option.
|
|
48
|
+
* @throws {RangeError} For a negative timeout.
|
|
49
|
+
*/
|
|
50
|
+
constructor(options: ThreadedComputeOptionsInterface);
|
|
51
|
+
/**
|
|
52
|
+
* Determines if this backend can run the given task.
|
|
53
|
+
*
|
|
54
|
+
* @param taskName - Name of the task.
|
|
55
|
+
* @returns `true` if the task is in `canRunTasks` and this runtime has Web
|
|
56
|
+
* Workers.
|
|
57
|
+
*/
|
|
58
|
+
canRun(taskName: string): boolean;
|
|
59
|
+
/**
|
|
60
|
+
* Runs a task in the worker and waits for its reply.
|
|
61
|
+
*
|
|
62
|
+
* @typeParam Input - The input type of the task.
|
|
63
|
+
* @typeParam Output - The output type of the task.
|
|
64
|
+
*
|
|
65
|
+
* @param taskName - The name of the task to run.
|
|
66
|
+
* @param input - The input for the task. It's copied with the structured
|
|
67
|
+
* clone algorithm, so it can't hold functions or DOM nodes.
|
|
68
|
+
* @param options - Options for this call. With a `signal`, `runTask`
|
|
69
|
+
* rejects with the signal's reason as soon as it aborts, and the worker is
|
|
70
|
+
* told to cancel the task.
|
|
71
|
+
* @returns A Promise resolving to the reply's `result`. It rejects with a
|
|
72
|
+
* `NoBackendError` (from `@hybrid-compute/core`) if the task isn't in
|
|
73
|
+
* `canRunTasks`, a `TypeError` if this runtime has no Web Workers, a
|
|
74
|
+
* {@link WorkerTaskError} if the task fails, and with the signal's reason
|
|
75
|
+
* if the call is cancelled.
|
|
76
|
+
*
|
|
77
|
+
* @example
|
|
78
|
+
* ```ts
|
|
79
|
+
* const result = await threaded.runTask('square', 9); // 81
|
|
80
|
+
* ```
|
|
81
|
+
*/
|
|
82
|
+
runTask<Input, Output>(taskName: string, input: Input, options?: RunTaskOptionsInterface): Promise<Output>;
|
|
83
|
+
/**
|
|
84
|
+
* Terminates the worker, if one is running. Tasks still waiting for a
|
|
85
|
+
* reply reject with a {@link WorkerTaskError}. The next task starts a new
|
|
86
|
+
* worker.
|
|
87
|
+
*/
|
|
88
|
+
close(): void;
|
|
89
|
+
/** The running worker, starting one first if needed. */
|
|
90
|
+
private start;
|
|
91
|
+
/** Match a reply to its task by id; ignore anything that can't be matched. */
|
|
92
|
+
private onMessage;
|
|
93
|
+
/** Reject every task still waiting for a reply. */
|
|
94
|
+
private rejectPending;
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* Creates a ThreadedCompute backend.
|
|
98
|
+
*
|
|
99
|
+
* @param options - The worker script, the tasks it can run and,
|
|
100
|
+
* optionally, a timeout.
|
|
101
|
+
* @returns A new `ThreadedCompute` instance.
|
|
102
|
+
*
|
|
103
|
+
* @throws {TypeError} For a missing or wrongly typed option.
|
|
104
|
+
* @throws {RangeError} For a negative timeout.
|
|
105
|
+
*
|
|
106
|
+
* @example
|
|
107
|
+
* ```ts
|
|
108
|
+
* const backend = createThreadedCompute({
|
|
109
|
+
* url: new URL('./worker.js', import.meta.url),
|
|
110
|
+
* canRunTasks: ['resizeImage']
|
|
111
|
+
* });
|
|
112
|
+
* ```
|
|
113
|
+
*/
|
|
114
|
+
export declare function createThreadedCompute(options: ThreadedComputeOptionsInterface): ThreadedCompute;
|
|
115
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,uBAAuB,EAC7B,MAAM,sBAAsB,CAAC;AAG9B,OAAO,KAAK,EACV,+BAA+B,EAGhC,MAAM,YAAY,CAAC;AAGpB,cAAc,aAAa,CAAC;AAE5B,cAAc,aAAa,CAAC;AAE5B,cAAc,YAAY,CAAC;AA+D3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,eAAgB,YAAW,uBAAuB;IAC7D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgC;IACzD,OAAO,CAAC,MAAM,CAAC,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;IAC9D,OAAO,CAAC,MAAM,CAAK;IAEnB;;;;;;;;;OASG;gBACS,OAAO,EAAE,+BAA+B;IAIpD;;;;;;OAMG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAIjC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,OAAO,CAAC,KAAK,EAAE,MAAM,EACzB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,KAAK,EACZ,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,MAAM,CAAC;IA2FlB;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAQb,wDAAwD;IACxD,OAAO,CAAC,KAAK;IA4Cb,8EAA8E;IAC9E,OAAO,CAAC,SAAS;IAkCjB,mDAAmD;IACnD,OAAO,CAAC,aAAa;CAWtB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,+BAA+B,mBAGzC"}
|