@mika/polite-worker (1.1.0)
Installation
@mika:registry=npm install @mika/polite-worker@1.1.0"@mika/polite-worker": "1.1.0"About this package
@mika/polite-worker
PoliteWorker gives browser tabs SharedWorker-shaped behavior using a normal module Worker, BroadcastChannel RPC, and Web Locks. Exactly one tab hosts the active Worker for an origin, while every tab can call the configured target through the same dynamic async-iterator API.
Usage
import { PoliteWorker } from "@mika/polite-worker"
const worker = PoliteWorker({
version: "1.0.0",
targetUrl: new URL("./target.js", import.meta.url),
targetArgs: [{ databaseName: "app-db" }],
})
const [value] = await Array.fromAsync(worker.someMethod("arg"))
The target module must default-export a factory. The Worker imports it, calls
it with ...targetArgs, and exposes the returned object's methods over RPC.
targetArgs defaults to [] and must be structured-cloneable.
version must be a stable SemVer-compatible string for the exact target
runtime, including targetArgs. Coordinators with the same SemVer precedence
are assumed to create equivalent targets. Build metadata after + is ignored
for takeover ordering. If targetArgs includes a database migration list, for
example, increase version every time that migration list changes.
Pass-Through Mode
Node runtimes can use the same public shape without starting browser workers:
import { PoliteWorker } from "@mika/polite-worker"
const worker = PoliteWorker({
mode: "passthrough",
version: "1.0.0",
targetUrl: new URL("./target.js", import.meta.url),
targetArgs: [{ databaseName: "test-db" }],
})
const [value] = await Array.fromAsync(worker.someMethod("arg"))
Pass-through mode still imports targetUrl, calls the default factory with
...targetArgs, and exposes dynamic async-iterator methods. It bypasses
Worker, BroadcastChannel, Web Locks, version takeover, and worker restart
behavior. Each PoliteWorker instance creates its own target instance.
To stay close to the browser transport contract, pass-through mode uses
structuredClone for targetArgs, method arguments, cancellation values,
yielded values, and final return values. Target method errors are serialized
and reconstructed like worker RPC errors.
Offline Worker Assets
PoliteWorker can recover when the active Worker owner tab closes only if a
remaining tab can start a replacement Worker. That requires the browser to load
the Worker entry, targetUrl, and every module the target imports.
When those assets are unavailable, for example because the origin is fully offline and the assets were not cached, PoliteWorker backs off restart attempts so the page does not spin at high CPU. It cannot keep an active Worker alive or accept new target calls without the replacement Worker code.
Applications that need offline handoff across owner-tab closure should cache
the full Worker module graph themselves, usually with an app Service Worker or a
single bundled Worker asset. Include workerUrl if you override it, targetUrl,
and all static or dynamic imports used by the target. Treat changes to that
graph as runtime changes and update version when compatibility changes.
Further Reading
Notes
- The package is plain ESM. There is no build step.
PoliteWorker({ version, targetUrl, targetArgs })requires a SemVer-compatible runtime version.
Dependencies
Development dependencies
| ID | Version |
|---|---|
| @playwright/test | ^1.59.1 |