runtime:workers

Durable workers: state that outlives the process, in esrun's own SQLite, with no service to run beside it.

A durable worker is addressed, not spawned. You name one; the runtime opens it on demand, runs one call at a time against it, and closes it when it has been idle. Its state is still there for the next process to name it.

Import

import { DurableWorker, configure, startAlarms, shutdown } from "runtime:workers";

// workers.js
import { DurableWorker } from "runtime:workers";

export class Cart extends DurableWorker {
  async add(item) {
    const items = this.state.get("items") ?? [];
    items.push(item);
    this.state.set("items", items);
    return items.length;             // held back until that write commits
  }
  async items() {
    return this.state.get("items") ?? [];
  }
}

// server.js
import { serve } from "runtime:http";
import { Cart } from "./workers.js";

serve(async (request) => {
  const cart = Cart.get(new URL(request.url).pathname.slice(1)); // no I/O yet
  return Response.json(await cart.items());
});

What it guarantees

Exports

The class

new Cart() throws — a durable worker is addressed, because which state an instance holds is the runtime's to decide. A minified build needs static durableName: a mangled class name would address a different file.

Arguments and results cross by structured clone, so what may be passed is the same rule it will be when a worker runs on a shard of its own. Lifecycle hooks are not callable through a reference, and neither is anything the class does not have — a TypeError from the call, not a promise that never settles.

state

Anything structuredClone carries can be stored — Date, Map, Set, typed arrays, BigInt, cycles — not only what JSON survives.

Mutating what get returns changes nothing on disk — a value is stored by set, not by being touched.

State is resident, so its ceiling is real: 1 MiB a worker, 128 KiB a value, refused at the write with ERR_DURABLE_STATE_TOO_LARGE. What grows without bound belongs in a database of its own — runtime:db is right there.

Collections

The keys are for the small, hot thing a request needs. Collections are for what grows: documents in a table of their own, queried rather than held, and not measured against the resident ceiling.

export class Room extends DurableWorker {
  static schema = {
    collections: { messages: { index: ["ts", "author"], unique: ["clientId"] } },
  };

  async post(message) { return this.state.collection("messages").insert(message); }

  async recent(n = 20) {
    return this.state.collection("messages")
      .find({ ts: { gte: Date.now() - 86_400_000 } })
      .sort({ ts: "desc" })
      .limit(n)
      .toArray();
  }
}

A document is stored the way a key is — structured clone — so a Date comes back a Date. What the class declares is copied into a real indexed column beside it, and that is what can be matched and sorted.

A bare value is equality; eq, ne, gt, gte, lt, lte and in are the comparisons.

state.transaction(fn) covers both halves: it commits when fn returns and rolls back when it throws. Schema changes apply on the first wake after a deploy — a newly declared field gets its column and is filled in from the documents already there. Nothing is ever dropped.

Alarms

A durable worker can ask to be woken. The time is stored beside its state, so it survives a restart — and the worker is woken whether or not anyone addresses it.

export class Reminder extends DurableWorker {
  async schedule(at, message) {
    this.state.set("message", message);
    await this.state.alarm.set(at);          // a Date, or ms since the epoch
  }
  async alarm() {
    await deliver(this.state.get("message"));
    // setting the next one here is how a worker repeats
  }
}

The alarm is cleared before the handler runs, so a handler that sets nothing is not woken again. alarm() goes through the same mailbox a call does, so it never interleaves with one. Setting an alarm on a class with no alarm() is a TypeError at the set.

A failing alarm() is retried — 1s, 2s, 4s, doubling to a five-minute cap — alarmRetries times (default 5), with the count stored so a restart does not reset it. After the last attempt it is cleared and reported.

startAlarms({ classes, onError, batch })

Nothing fires until a process says it is the one running alarms:

import { startAlarms } from "runtime:workers";
import { Reminder } from "./workers.js";

const alarms = startAlarms({ classes: [Reminder] });
await alarms.stop();

While it is running the process stays alive — which is why it is not started for you: a script that set an alarm for tomorrow should not sit there until tomorrow. stop() drops the timer and resolves once the sweep in flight has finished; shutdown() calls it.

configure(options)

Optional. With no call the defaults apply; it must come before the first worker is used, since these decide where state lives.

shutdown()

Closes every open worker — flushing, running stop() — and releases the directory. Results are gated on their writes, so an abrupt exit loses nothing that was acknowledged; shutdown() is how a process asks to stop, which is what gives stop() a chance to run.

It installs no signal handler, because doing that switches off esrun's own HTTP drain. An application that wants both wires them together:

import { exit, onSignal } from "runtime:process";
import { shutdown } from "runtime:workers";

onSignal("SIGTERM", async () => {
  await server.stop();
  await shutdown();
  exit(143);
});

Errors

Not yet

Shards: a worker on a Worker of its own, with a watchdog and a memory ceiling. It arrives with its own phase rather than as an option that does nothing today.