@aurelienbbn/oxlint-plugin-xstate

17 oxlint rules for XState v5 and v6 alpha machines (with @xstate/effect), built with setup().createMachine(), the shape eslint-plugin-xstate can't see.

v6 support is checked against [email protected], @xstate/[email protected] and @xstate/[email protected]; alpha APIs can move between releases.

pnpm add -D @aurelienbbn/oxlint-plugin-xstate oxlint

{
  "jsPlugins": ["@aurelienbbn/oxlint-plugin-xstate"],
  "rules": {
    "xstate/require-setup-create-machine": "error",
    "xstate/no-context-mutation": "error",
    "xstate/require-effect-actor": "error",
    "xstate/no-deferred-enqueue": "error"
  }
}

No preset, no autofix: enable each rule by name.

13 solid, 2 MAYBE, 2 deprecated

solid       █████████████  13   error
MAYBE       ██              2   off or warn: no-unreachable-transition · promise-actor-abort-signal
deprecated  ██              2   v5 only: no-imperative-action-creator · prefer-send-to

no-imperative-action-creator and prefer-send-to are deprecated since 0.2.0. XState v6 removes the action creators and sendParent (importing one is a type error); both rules still work on v5 until you migrate.

no-direct-named-action contradicts the upstream v6 docs, which show direct actions.x(...) calls. It reports them anyway: in alpha.64 a direct call ran twice for one send, and also ran during pure transition() and snapshot.can().

What fires

setup({ types: {} }).createMachine({
  entry: ({ context }) => {
    assign({ count: context.count + 1 });
  }, // ❌ no-imperative-action-creator: builds an action, runs nothing
});
setup({ types: {} }).createMachine({
  entry: assign({ count: ({ context }) => context.count + 1 }), // ✅
});

actorRef.send({ type: "ADD_ITEM", id: "x" }); // ❌ require-event-satisfies
actorRef.send({ type: "ADD_ITEM" } satisfies CartEvent); // ✅

setup({}).createMachine({ id: "app.cart" });
// ❌ require-setup-create-machine: neither `types` (v5) nor `schemas` (v6)

// v6 alpha / @xstate/effect
createActor(setupEffect({ actors }).createMachine(config)); // ❌ require-effect-actor: status 'error', use createEffectActor
on: { SAVE: (_, enq) => { setTimeout(() => enq.raise({ type: "SAVED" }), 100); } } // ❌ no-deferred-enqueue
on: { SAVE: (_, enq) => { enq.raise({ type: "SAVED" }, { delay: 100 }); } } // ✅
after: { "5m": { target: "expired" } } // ❌ valid-duration: write "PT5M" or 300000

require-event-satisfies matters where types are erased

setup({ types }) machine  ──▶  TypeScript already checks the payload  → rule redundant
sendTo / sendParent targets,
AnyActorRef, untyped refs ──▶  event type erased                      → rule is the only check

Fully typed codebase? Narrow sendCalleeNames to the erased senders. satisfies unknown / any isn't evidence; the rule enforces syntax, not the intended event union.

Credit: no-imperative-action-creator and no-unreachable-transition re-implement eslint-plugin-xstate's no-imperative-action and no-infinite-loop ideas (Richard Laffers); no-discarded-effect re-implements the idea of statelyai/xstate's no-inline-effect (MIT). No code copied.

Registered contract inventory

Generated from package exports by pnpm catalog. Rule-specific options and limitations are described above and in the source tests.

Credited concepts

• ai-automation by Sandro Maglione (inspiration, independently re-implemented)
• eslint-plugin-xstate no-imperative-action by Richard Laffers (concept)
• eslint-plugin-xstate no-infinite-loop by Richard Laffers (concept)
• statelyai/xstate no-inline-effect (MIT; concept, independently implemented)