session-typed-worker
v1.0.3
Published
A deadlock-free communication API for web workers based on (a subset of) session types.
Downloads
3
Maintainers
Readme
session-typed-worker
A deadlock-free communication API for web workers based on (a subset of) session types.
Features
- Type-safe & deadlock-free
- Zero-dependency
- Integration with webpack & parcel
Getting Started
Install
Also install worker-loader for importScripts()
.
You can use worker-plugin or parcel instead of worker-loader.
In this case, the following .d.ts
setting is unnecessary.
Complete examples is here.
$ npm i -D worker-loader session-typed-worker
Then, set worker-loader's integrating with TypeScript.
// typings/custom.d.ts
declare module "worker-loader!*";
Note: If "esModuleInterop": true
is not set, please write .d.ts
as follows.
// typings/custom.d.ts
declare module "worker-loader!*" {
const worker: any;
export default worker;
}
Writing a protocol
Write as a type a communication procedure and the kinds of values to handle.
Sending from the main script to the worker is C2W
, and the reverse is W2C
.
The following CheckNumbersEquality
protocol shows the operation of sending a numbers twice to the worker, receiving a boolean from the worker.
// protocols.d.ts
import { C2W, W2C, Fin } from "session-typed-worker";
type CheckNumbersEquality = C2W<number, C2W<number, W2C<boolean, Fin>>>;
export { CheckNumbersEquality };
Writing code
The type representing communication on the main script side is taken out by giving ["client"]
to the protocol.
// index.ts
import { send, recv } from "session-typed-worker";
import * as proto from "./protocols";
import Worker from "worker-loader!./worker";
const p: proto.CheckNumbersEquality["client"] = new Worker();
(async () => {
const p1 = send(p, 42);
const p2 = send(p1, 42);
const [v, _] = await recv(p2);
console.log(v); // true
})();
Here the type of p
is Send<number, Send<number, Recv<boolean, Close>>>
.
(If you are using VSCode, you can check this with a mouseover.)
This type means that you first need to send a value of type number
twice with send
and then receive a value of type boolean
with recv
.
If you actually do send
once, the type of the return value (i.e. p1
) changes to Send<number, Recv<boolean, Close>>
.
Even if you write recv
instead of send
or apply a value of type string
instead of a value of type number
, you can detect it by type checking.
In TypeScript, shadowing of local variables is not allowed.
Therefore, please note that it is necessary to change the variable name of the type value representing the communication operation like p1
and p2
.
Just like the main script side, the type representing communication on the worker side is taken out by giving ["worker"]
to the protocol.
// worker.ts
import { send, recv } from "session-typed-worker";
import * as proto from "./protocols";
const p: proto.CheckNumbersEquality["worker"] = self as any;
(async () => {
const [v1, p1] = await recv(p);
const [v2, p2] = await recv(p1);
send(p2, v1 === v2);
})();
At this time, the type of p
is Recv<number, Recv<number, Send<boolean, Close>>>
, which is opposite to the type of p
in the main script.
In other words, if you sending on one side, you can guarantee that the other side is sure to be receiving and you can write code that will not cause deadlock.
Complete examples including tsconfig.json and webpack.config.js are in the examples directory.