Runner

Live machine

The shipped runMachine — the whole run lifecycle as state values: submitted, streaming, settled, cancelled, failed, and the action-required detour.

{
  "attempt": 0
}

Hello world

A settle-once request can report directly to a service. The runner owns cancellation and delivery; the machine receives ordinary events.

import { createService } from "@grassroot/statechart"
import { createRequestRunner } from "@grassroot/runner"

const runner = createRequestRunner({
  source: (signal) => fetch("/api/profile", { signal }).then((r) => r.json()),
  send: (event) => service.send(event), // { type: "RESULT", result } | { type: "FAILED", error }
})
await runner.start()

The command bridge keeps the same boundary when a machine initiates the work: the machine says what should happen and Runner handles how.

import { bindRunnerToService } from "@grassroot/runner"

const runCommand = bindRunnerToService({
  handlers: {
    OPTIONS_REQUEST: (request, { signal }) => fetchOptions(request.query, signal),
  },
})
const service = createService(comboboxMachine, { input, runCommand })

The command bridge

Combobox's optional loadOptions mode emits this keyed command after its debounce. A newer request for the same key supersedes the earlier one.

{ type: "OPTIONS_REQUEST", key: "combobox.options", request: { query: context.inputValue },
  onSettled: { type: "OPTIONS_LOADED", payloadKey: "options" },
  onFailed: { type: "OPTIONS_LOAD_FAILED", payloadKey: "error" } }

Wire that command to real work with bindRunnerToService. The signal aborts when the request is cancelled or superseded.

const runCommand = bindRunnerToService({
  handlers: { OPTIONS_REQUEST: (request, { signal }) => loadOptions(request.query, signal) },
})
const service = createService(comboboxMachine, { input: { options: [], loadOptions: true }, runCommand })

While loading, Combobox keeps its last-known options. A successful request replaces them; a failed request records the error without emptying the list. With loadOptions absent, the existing synchronous behaviour is unchanged.

Keyed staleness

createKeyedRunner allows one live run per key. These five scenarios define its same-key-replace contract.

Who consumes this

Runner is the shared async boundary for five named consumers. Combobox ships the integration here; the remaining product plans now point to the same public package instead of defining parallel actor seams.