Skip to content

Commit 51ff86a

Browse files
authored
docs: Update README about NodeJS support (#31)
1 parent 6e1c85a commit 51ff86a

File tree

1 file changed

+23
-17
lines changed

1 file changed

+23
-17
lines changed

README.md

Lines changed: 23 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,9 @@
44
55
[Live Demo](https://wjsoftware.github.io/wjfe-async-workers)
66

7-
> **⚠️ Caution!**
8-
> This NPM package has had minimal testing under NodeJS + web-worker.
7+
> **⚠️ Important**
8+
>
9+
> This package may not yet be production-ready. It does work in the browser and in NodeJS using a polyfill like the `web-worker` NPM package. Unit testing coverage currently covers synchronization objects, but not the asynchronous features. It is getting there, though.
910
1011
## Objectives
1112

@@ -20,7 +21,7 @@ These are the recommended steps to get things going:
2021
to incoming messages.
2122
2. Export the tasks worker object.
2223
3. Create a new instance of `Worker` the way is recommended by your bundler, usually with the syntax
23-
`new Worker("./myworker.js", impot.meta.url)`. However, this forces you to write the worker in JavaScript, at least
24+
`new Worker("./my-worker.js", import.meta.url)`. However, this forces you to write the worker in JavaScript, at least
2425
in Vite-powered projects.
2526
4. Create a new instance of `AsyncWorker` (from this package) by passing the worker object and the tasks object from
2627
the previous points.
@@ -81,6 +82,7 @@ This is a 3-step worker. The worker simply waits to be informed which step to r
8182
This is what needs to be done in order to obtain an object that commands the worker:
8283

8384
> **⚡ Important**
85+
>
8486
> This example is using TypeScript and the following assumes a Vite-powered project. We are deviating from the
8587
> recommended way of obtaining a worker because the recommended way requires the worker to be written in JavaScript
8688
> while in serve mode (`npm run dev`).
@@ -144,17 +146,18 @@ self.onconnect = (ev) => {
144146
## Bi-Directional Communication
145147

146148
> **🕓 TL;DR**
149+
>
147150
> It's OK for workers to transmit intermediate results like progress reports and partial results. It is not recommended for the main thread to have to send data to a paused task. Promises in work item objects resolve once the `QueueingOptions.processMessage()` function returns `true`.
148151
149152
The default functionality is fine for many cases: A worker task is started, the user interface waits for its
150153
completion and when the task finishes, the work item's `promise` property spits out the resultant object when awaited.
151154

152-
There are also many cases where "interim" communcation between the worker and the UI thread is desired, most commonly:
155+
There are also many cases where "interim" communication between the worker and the UI thread is desired, most commonly:
153156

154157
1. Progress reports
155158
2. Partial results
156159

157-
How can a worker send data while the task is still in progress? By using the provied `post()` function.
160+
How can a worker send data while the task is still in progress? By using the provided `post()` function.
158161

159162
In reality, the functions of the worker's tasks object in the quickstart are simplified. In reality we can re-write
160163
the tasks object like this:
@@ -282,9 +285,10 @@ To learn about the implementation in the worker side, keep reading.
282285

283286
This package provides synchronization objects that use `Atomics` to cross the thread boundary safely.
284287

285-
> [!IMPORTANT]
288+
> **⚡ Important**
289+
>
286290
> This implementation uses `Atomics` on `SharedArrayBuffer` objects which demands certain
287-
[security requirements](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer#security_requirements).
291+
[security requirements](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer#security_requirements) in browser environments.
288292

289293
### CancellationSource
290294

@@ -299,7 +303,7 @@ import { CancellationSource, type Token } from '@wjfe/async-workers';
299303

300304
function computeSomeStuff(cancelToken?: Token) {
301305
for (let i = 0; i < Number.MAX_SAFE_INTEGER; ++i) {
302-
// No thowing will be done if cancelToken is undefined.
306+
// No throwing will be done if cancelToken is undefined.
303307
CancellationSource.throwIfSignaled(cancelToken);
304308
...
305309
}
@@ -409,17 +413,19 @@ Generally speaking, terminated workers should be disposed. Do so as fast as pos
409413

410414
## Usage in Node.Js
411415

412-
This package, by design, is for use in the browser. However, there is this NPM package called [web-worker](https://www.npmjs.com/package/web-worker)
413-
that claims to bring the browser API into Node. If this is indeed the case, using these 2 packages together should
414-
work properly in Node.
416+
> Since **v0.2.3**
417+
418+
This package, by design, is for use in the browser. However, there is this NPM package called [web-worker](https://www.npmjs.com/package/web-worker) that brings the browser API into Node. This collaboration works OK and enables the use of `@wjfe/async-workers` in Node.
419+
420+
Generally speaking, `AsyncWorker`, upon construction will duck-type test the provided worker. If it looks like a shared worker, it will initialize as a controller for a shared worker; otherwise, it will initialize as a controller for a dedicated worker. This should enable any `Worker` polyfill, not just `web-worker`.
415421

416422
## Roadmap
417423

418424
| Synchronization Objects | Dedicated Worker | Shared Worker |
419425
| - | - | - |
420-
| [x] ManualResetEvent | [x] Simple request/response scenario | [x] Simple request/response scenario |
421-
| [x] AutoResetEvent | [x] Request/multiple response scenario | [x] Request/multiple response scenario |
422-
| [x] Semaphore | [x] Strongly-typed tasks | [x] Strongly-typed tasks |
423-
| [x] CancellationSource | [x] Worker termination | |
424-
| [x] Mutex | [x] Out-of-order work items | [x] Out-of-order work items |
425-
| | [x] Task cancellation | [x] Task cancellation|
426+
| ManualResetEvent | Simple request/response scenario | Simple request/response scenario |
427+
| AutoResetEvent | Request/multiple response scenario | Request/multiple response scenario |
428+
| Semaphore | Strongly-typed tasks | Strongly-typed tasks |
429+
| CancellationSource | Worker termination | |
430+
| Mutex | Out-of-order work items | Out-of-order work items |
431+
| | Task cancellation | Task cancellation|

0 commit comments

Comments
 (0)