bun-supervise-worker

Tiny restart supervision for Bun Workers.

import { supervise } from "bun-supervise-worker";

const worker = supervise(() => new Worker("./worker.ts"));

worker.onmessage = (event) => {
  console.log("message", event.data);
};

worker.onrestart = (event) => {
  console.log("restarted", event.detail);
};

worker.postMessage({ type: "ping" });

Install

bun add bun-supervise-worker

What it does

• wraps new Worker(...)
• forwards message, messageerror, and error
• restarts crashed workers with backoff
• reattaches listeners across restarts
• queues postMessage(...) calls while the worker is offline by default

What it does not do

• no retries for messages already sent to a worker
• no delivery guarantees
• no RPC layer

If a worker crashes after a message was sent, that message is considered unknown and is not replayed.

API

supervise(factory, options?)

Creates a restartable worker wrapper.

const worker = supervise(() => new Worker(url, { type: "module" }));

Options

{
  queueWhileOffline?: boolean;
  restart?: false | {
    maxAttempts?: number;
    minDelayMs?: number;
    maxDelayMs?: number;
    factor?: number;
    jitter?: boolean;
  };
}

Defaults:

{
  queueWhileOffline: true,
  restart: {
    maxAttempts: Infinity,
    minDelayMs: 100,
    maxDelayMs: 5000,
    factor: 2,
    jitter: true,
  },
}

Returned worker

The returned object behaves like a small Worker facade:

• postMessage(message, transferOrOptions?)
• terminate()
• addEventListener(...)
• removeEventListener(...)
• onmessage
• onmessageerror
• onerror
• onrestart
• running
• generation
• restartCount

restart event

worker.onrestart = (event) => {
  event.detail.delayMs;
  event.detail.generation;
  event.detail.reason;
  event.detail.restartCount;
};