isFailure

Function, in @jr2/orchestrator/src/fail.ts. It is an export of @jr2/orchestrator, on the Authoring surface page, in Failure.

function isFailure(error: unknown): error is Failure

Is this error a Failure, which a state invoked fail to make? A defect — any other error — is not. Use it in the guard of an onError to catch a Failure and let a defect go up, and read the Failure's reason and detail from the error it narrows.

Parameters

• error: The error of an error event: event.error in an onError.

Returns: True for a Failure, with error narrowed to { reason, detail? }.

Example

import { z } from "zod";
import { defineEvent, fail, isFailure, jr2Setup } from "@jr2/orchestrator";

const retry = defineEvent({ name: "retry", description: "Try the plan again.", input: z.object({}) });

const attempt = jr2Setup({ actors: { fail: fail() } }).createMachine({
  id: "attempt",
  initial: "stuck",
  states: { stuck: { invoke: { src: "fail", input: { reason: "no plan fits the ticket" } } } },
});

export const machine = jr2Setup({ events: [retry], actors: { attempt } }).createMachine({
  id: "planner",
  initial: "planning",
  states: {
    planning: {
      invoke: {
        src: "attempt",
        onDone: "planned",
        // A Failure waits for a person; a defect has no route, so it goes up and the run ends `error`.
        onError: { guard: ({ event }) => isFailure(event.error), target: "asking" },
      },
    },
    asking: { invoke: { src: "gate" }, on: { retry: "planning" } },
    planned: { type: "final" },
  },
});

See also

• ADR-0073: A Machine fails a run with fail(), and an uncaught Failure ends it failed