@actualwave/worker-dispatcher

Named-event communication layer for Dedicated Workers, Shared Workers, and Service Workers. Built on top of @actualwave/messageport-dispatcher, it replaces raw postMessage/message boilerplate with typed named events on both sides of every worker channel.

Installation

npm install @actualwave/worker-dispatcher
# or
yarn add @actualwave/worker-dispatcher

Core concepts

• DedicatedWorkerDispatcher — wraps a Worker on the main thread (or self inside the worker).
• SharedWorkerDispatcher — wraps a SharedWorker on the main thread; handles the MessagePort internally.
• ServiceWorkerDispatcher — wraps a MessageChannel to the active Service Worker; auto-recovers when the worker restarts.
• Server dispatchers (SharedServerDispatcher, ServiceServerDispatcher) — used inside the worker script to receive connections and events.
• Client dispatchers (SharedClientDispatcher, ServiceClientDispatcher) — one instance per connected client, created automatically on each new connection.
• WorkerEvent — extends Event; carries nativeEvent, client, type, and data.
• WorkerType — string enum of all dispatcher type identifiers.

Usage

1. Dedicated Worker

Main thread:

import { DedicatedWorkerDispatcher } from '@actualwave/worker-dispatcher';

const dispatcher = new DedicatedWorkerDispatcher('/workers/worker.js');

dispatcher.addEventListener('result', (event) => {
  console.log('Worker result:', event.data);
});

dispatcher.dispatchEvent('compute', { input: [1, 2, 3] });

Inside the worker (worker.js):

import { createForSelf } from '@actualwave/worker-dispatcher';

const dispatcher = createForSelf();

dispatcher.addEventListener('compute', (event) => {
  dispatcher.dispatchEvent('result', { output: (event.data as any).input.map(Number) });
});

2. Shared Worker

Main thread:

import { SharedWorkerDispatcher } from '@actualwave/worker-dispatcher';

const dispatcher = new SharedWorkerDispatcher('/workers/shared.js');
// start() is called automatically in the constructor

dispatcher.addEventListener('broadcast', (event) => {
  console.log('Broadcast from worker:', event.data);
});

dispatcher.dispatchEvent('subscribe', { topic: 'news' });

Inside the shared worker (shared.js):

import { createForSelf } from '@actualwave/worker-dispatcher';
import WorkerEvent from '@actualwave/worker-dispatcher/WorkerEvent';

const server = createForSelf(); // returns SharedServerDispatcher

server.addEventListener(WorkerEvent.CONNECT, (event) => {
  const client = event.client; // SharedClientDispatcher
  client.start();

  client.addEventListener('subscribe', (e) => {
    console.log('Client subscribed to', (e.data as any).topic);
    client.dispatchEvent('broadcast', { message: 'Welcome!' });
  });
});

Close a client when done:

client.close();

3. Service Worker

Main thread (registers and communicates with a Service Worker):

import { ServiceWorkerDispatcher } from '@actualwave/worker-dispatcher';

const dispatcher = new ServiceWorkerDispatcher();

dispatcher.onReady((registration) => {
  console.log('Service worker ready');
  dispatcher.dispatchEvent('init', { config: { offline: true } });
});

dispatcher.addEventListener('push-received', (event) => {
  console.log('Push data:', event.data);
});

Inside the service worker (sw.js):

import { ServiceServerDispatcher } from '@actualwave/worker-dispatcher';
import WorkerEvent from '@actualwave/worker-dispatcher/WorkerEvent';

const server = new ServiceServerDispatcher();

server.addEventListener('init', (event) => {
  console.log('Config received:', event.data);
  const client = event.client; // ServiceClientDispatcher
  if (client) {
    client.dispatchEvent('ack', { ok: true });
  }
});

// Lifecycle events are wired automatically
server.addEventListener(WorkerEvent.INSTALL, (e) => {
  (e.nativeEvent as ExtendableEvent).waitUntil(caches.open('v1'));
});

4. Factory functions

import {
  create,
  createForSelf,
  createForDedicatedWorker,
  createForSharedWorker,
  createForServiceWorker,
  WorkerType,
} from '@actualwave/worker-dispatcher';

// auto-detect from a target object
const d1 = create(worker, WorkerType.DEDICATED_WORKER);
const d2 = create(sharedWorker, WorkerType.SHARED_WORKER);

// inside a worker script — auto-detects context
const dispatcher = createForSelf();

// explicit per-type helpers
const dw = createForDedicatedWorker('/worker.js');
const sw = createForSharedWorker('/shared.js');
const svc = createForServiceWorker();

5. Event preprocessors

Transform every incoming or outgoing event:

import type { EventProcessor } from '@actualwave/event-dispatcher';

const stamp: EventProcessor = (event) => ({
  ...event,
  data: { ...(event.data as object), ts: Date.now() },
});

const dispatcher = new DedicatedWorkerDispatcher(
  '/worker.js',
  stamp,   // receiverEventPreprocessor
  stamp,   // senderEventPreprocessor
);

API reference

DedicatedWorkerDispatcher

new DedicatedWorkerDispatcher(
  worker?: Worker | string,
  receiverEventPreprocessor?: EventProcessor | null,
  senderEventPreprocessor?: EventProcessor | null,
)

| Member | Description | |---|---| | addEventListener(type, listener, priority?) | Listen for events from the worker. | | hasEventListener(type) | Check if listener exists. | | removeEventListener(type, listener) | Remove a listener. | | removeAllEventListeners(type) | Remove all listeners for a type. | | dispatchEvent(type, data?, transferList?) | Send an event to the worker. | | receiver | IEventDispatcher for incoming events. | | sender | IEventDispatcher for outgoing echo. | | target | Underlying Worker or WorkerLike. | | terminate() | Terminate the worker and clean up listeners. |

SharedWorkerDispatcher

new SharedWorkerDispatcher(
  target: SharedWorker | string,
  name?: string,
  receiverEventPreprocessor?: EventProcessor | null,
  senderEventPreprocessor?: EventProcessor | null,
)

| Member | Description | |---|---| | start() | Start the port (called automatically). | | close() | Close the port and clean up listeners. | | worker | The underlying SharedWorker instance. | | (inherits all dispatcher methods) | |

ServiceWorkerDispatcher

new ServiceWorkerDispatcher(
  receiverEventPreprocessor?: EventProcessor | null,
  senderEventPreprocessor?: EventProcessor | null,
)

| Member | Description | |---|---| | start() | Start the internal MessageChannel port. | | close() | Close the port and remove error listeners. | | ready | Promise<ServiceWorkerRegistration> | | onReady(handler) | Calls handler when the SW registration resolves. Returns Promise<void>. | | (inherits all dispatcher methods) | |

Auto-recovers the MessageChannel when the active Service Worker changes (e.g., after an update).

SharedServerDispatcher (inside a Shared Worker)

new SharedServerDispatcher(
  target?: EventTarget,      // defaults to self
  receiverEventPreprocessor?: EventProcessor,
  clientReceiverEventPreprocessor?: EventProcessor,
  clientSenderEventPreprocessor?: EventProcessor,
)

| Member | Description | |---|---| | addEventListener(type, listener) | Listen for connect and worker-lifecycle events. | | destroy() | Remove all native listeners from the target. | | receiver | IEventDispatcher for dispatched events. |

Fires WorkerEvent.CONNECT whenever a new client connects. The event's .client is a SharedClientDispatcher.

ServiceServerDispatcher (inside a Service Worker)

new ServiceServerDispatcher(
  target?: EventTarget,      // defaults to self
  receiverEventPreprocessor?: EventProcessor,
  clientReceiverEventPreprocessor?: EventProcessor,
  clientSenderEventPreprocessor?: EventProcessor,
)

Automatically registers listeners for error, messageerror, install, activate, fetch, sync, and push on target. The event's .client is a ServiceClientDispatcher when a port was transferred.

| Member | Description | |---|---| | destroy() | Remove all native listeners from the target. |

SharedClientDispatcher / ServiceClientDispatcher

One instance per client connection. Returned via event.client on connect/message events.

| Member | Description | |---|---| | start() | Start the MessagePort. | | close() | Close the MessagePort. | | dispatchEvent(type, data?) | Send an event to this specific client. | | (inherits all dispatcher methods) | |

WorkerEvent

Static event type constants (all prefixed worker:):

| Constant | Value | When fired | |---|---|---| | WorkerEvent.CONNECT | 'worker:connect' | New client connected (Shared Worker) | | WorkerEvent.MESSAGE | 'worker:message' | Incoming message | | WorkerEvent.ERROR | 'worker:error' | Worker error | | WorkerEvent.MESSAGEERROR | 'worker:messageerror' | Message deserialization error | | WorkerEvent.LANGUAGECHANGE | 'worker:languagechange' | Language changed | | WorkerEvent.ONLINE | 'worker:online' | Network online | | WorkerEvent.OFFLINE | 'worker:offline' | Network offline | | WorkerEvent.INSTALL | 'worker:install' | SW install event | | WorkerEvent.ACTIVATE | 'worker:activate' | SW activate event | | WorkerEvent.FETCH | 'worker:fetch' | SW fetch event | | WorkerEvent.SYNC | 'worker:sync' | SW background sync | | WorkerEvent.PUSH | 'worker:push' | SW push notification |

Instance properties:

| Property | Type | Description | |---|---|---| | type | string | The worker-prefixed event type | | data | unknown | Event payload | | nativeEvent | unknown | The original native DOM event | | client | unknown | Client dispatcher, or null |

WorkerType

String constants used with create():

| Constant | Value | |---|---| | WorkerType.DEDICATED_WORKER | 'dedicated' | | WorkerType.SHARED_WORKER | 'shared' | | WorkerType.SERVICE_WORKER | 'service' |

NativeEventType

Raw DOM event type strings: 'connect', 'message', 'error', 'messageerror', 'install', 'activate', 'fetch', 'sync', 'push', 'languagechange', 'online', 'offline'.

Utility: dispatchWorkerEvent / dispatchWorkerEvents / dispatchWorkerErrorEvent

Lower-level helpers that register native event listeners on an EventTarget and forward translated WorkerEvents to an IEventDispatcher. Each returns a () => void cleanup function.

import { dispatchWorkerErrorEvent } from '@actualwave/worker-dispatcher/WorkerEvent';

const cleanup = dispatchWorkerErrorEvent(target, myDispatcher.receiver);
// later:
cleanup();

TypeScript types

import type { WorkerTypeValue } from '@actualwave/worker-dispatcher/WorkerType';
import type { NativeEventHandler } from '@actualwave/worker-dispatcher/WorkerEvent';
import type { WorkerLike } from '@actualwave/worker-dispatcher/AbstractDispatcher';

import type {
  EventObject,
  IEventDispatcher,
  EventProcessor,
  EventListener,
} from '@actualwave/event-dispatcher';

Common edge cases

• Service Worker recovery: ServiceWorkerDispatcher automatically recreates the MessageChannel and retransmits pending port2 when the active worker changes. The first dispatchEvent() after construction always transfers port2.
• destroy() on server dispatchers: Call destroy() when tearing down a SharedServerDispatcher or ServiceServerDispatcher to remove all native addEventListener registrations from self.
• start() on SharedWorkerDispatcher: start() is called automatically in the constructor; calling it again is a no-op in most environments but safe.
• WorkerEvent.MESSAGEERROR value: The correct value is 'worker:messageerror', not 'messageerror'. Use the constant, not the string literal.
• createForSelf() auto-detection: Checks typeof self.postMessage === 'function' (Dedicated Worker) then checks self.registration.scope (Service Worker), then falls back to SharedServerDispatcher.
• Preprocessors apply on both sides: Pass the same preprocessor to receiver and sender if you want symmetric transformation; they are independent by default.