xstate

Major Changes

• #4306 30e3cb216 Thanks @Andarist! - The final output of a state machine is now specified directly in the output property of the machine config:

  const machine = createMachine({
    initial: 'started',
    states: {
      started: {
        // ...
      },
      finished: {
        type: 'final'
        // moved to the top level
        //
        // output: {
        //   status: 200
        // }
      }
    },
    // This will be the final output of the machine
    // present on `snapshot.output` and in the done events received by the parent
    // when the machine reaches the top-level final state ("finished")
    output: {
      status: 200
    }
  });
  

Minor Changes

• #4172 aeef5e2d0 Thanks @davidkpiano! - The onSnapshot: { ... } transition object is now supported for invoked machines, observables, promises, and transition functions:

  const machine = createMachine({
    // ...
    invoke: [
      {
        src: createMachine({ ... }),
        onSnapshot: {
          actions: (context, event) => {
            event.snapshot; // machine state
          }
        }
      },
      {
        src: fromObservable(() => ...),
        onSnapshot: {
          actions: (context, event) => {
            event.snapshot; // observable value
          }
        }
      },
      {
        src: fromTransition((state, event) => { ... }, /* ... */),
        onSnapshot: {
          actions: (context, event) => {
            event.snapshot; // transition function return value
          }
        }
      }
    ]
  });
  

Patch Changes

• #4307 0c7b3aa3d Thanks @davidkpiano! - The input of a callback actor created with fromCallback(...) will now be properly restored when the actor is persisted.

Patch Changes

• Updated dependencies [af032db12]:
  • @xstate/[email protected]

Patch Changes

• #4308 af032db12 Thanks @davidkpiano! - Traversing state machines that have delayed transitions will now work as expected:

  const machine = createMachine({
    initial: 'a',
    states: {
      a: {
        after: {
          1000: 'b'
        }
      },
      b: {}
    }
  });
  
  const paths = getShortestPaths(machine); // works
  

Major Changes

• #4299 bd9a1a599 Thanks @Andarist! - All actor snapshots now have a consistent, predictable shape containing these common properties:

  • status: 'active' | 'done' | 'error' | 'stopped'
  • output: The output data of the actor when it has reached status: 'done'
  • error: The error thrown by the actor when it has reached status: 'error'
  • context: The context of the actor

  This makes it easier to work with actors in a consistent way, and to inspect their snapshots.

  const promiseActor = fromPromise(async () => {
    return 42;
  });
  
  // Previously number | undefined
  // Now a snapshot object with { status, output, error, context }
  const promiseActorSnapshot = promiseActor.getSnapshot();
  
  if (promiseActorSnapshot.status === 'done') {
    console.log(promiseActorSnapshot.output); // 42
  }
  

Minor Changes

• #4240 409552cf8 Thanks @davidkpiano! - The useMachine function is aliased to useActor and not shown as visually deprecated.

Major Changes

• #3282 6ff9fc242 Thanks @Andarist! - Returning promises when creating a callback actor doesn't work anymore. Only cleanup functions can be returned now (or undefined).

• #4281 52b26fd30 Thanks @Andarist! - Removed deferEvents from the actor options.

Minor Changes

• #4278 f2d5ac047 Thanks @Andarist! - self provided to actions should now receive correct types for the snapshot and events.

Major Changes

• #4265 1153b3f9a Thanks @davidkpiano! - FSM-related functions have been removed.

Major Changes

• #4265 1153b3f9a Thanks @davidkpiano! - FSM-related functions have been removed.

Major Changes

• #4270 c8de2ce65 Thanks @Andarist! - All events automatically generated by XState will now be prefixed by xstate.. Naming scheme changed slightly as well, for example done.invoke.* events became xstate.done.actor.* events.

Minor Changes

• #4269 2c916b835 Thanks @davidkpiano! - Actor types are now exported from xstate:

  import {
    type CallbackActorLogic,
    type ObservableActorLogic,
    type PromiseActorLogic,
    type TransitionActorLogic
  } from 'xstate';
  

• #4222 41822f05e Thanks @Andarist! - spawn can now benefit from the actor types. Its arguments are strongly-typed based on them.

Patch Changes

• #4271 b8118bf4c Thanks @Andarist! - Improved type safety of spawned inline actors when the actor types are not provided explicitly. It fixes an issue with an incompatible actor being assignable to a location accepting a different actor type (like a context property).

Major Changes

• #4248 d02226cd2 Thanks @Andarist! - Removed the ability to pass a string value directly to invoke. To migrate you should use the object version of invoke:

  -invoke: 'myActor'
  +invoke: { src: 'myActor' }
  

Minor Changes

• #4228 824bee882 Thanks @Andarist! - Params of actions and guards can now be resolved dynamically

  createMachine({
    types: {} as {
      actions:
        | { type: 'greet'; params: { surname: string } }
        | { type: 'poke' };
    },
    entry: {
      type: 'greet',
      params: ({ context }) => ({
        surname: 'Doe'
      })
    }
  });
  

Patch Changes

• Updated dependencies [b4f12a517]:
  • @xstate/[email protected]

Major Changes

• #4238 b4f12a517 Thanks @davidkpiano! - The steps in the paths returned from functions like getShortestPaths(...) and getSimplePaths(...) have the following changes:

  • The step.event property now represents the event object that resulted in the transition to the step.state, not the event that comes before the next step.
  • The path.steps array now includes the target path.state as the last step.
    • Note: this means that path.steps always has at least one step.
  • The first step now has the { type: 'xstate.init' } event

Patch Changes

• Updated dependencies [3d96d0f95]:
  • @xstate/[email protected]

Major Changes

• #4233 3d96d0f95 Thanks @davidkpiano! - Remove getMachineShortestPaths and getMachineSimplePaths

  import {
  - getMachineShortestPaths,
  + getShortestPaths,
  - getMachineSimplePaths,
  + getSimplePaths
  } from '@xstate/graph';
  
  -const paths = getMachineShortestPaths(machine);
  +const paths = getShortestPaths(machine);
  
  -const paths = getMachineSimplePaths(machine);
  +const paths = getSimplePaths(machine);
  

Minor Changes

• #4220 c67a3d3b0 Thanks @davidkpiano! - Partial event descriptors are now type-safe:

  createMachine({
    types: {} as {
      events:
        | { type: 'mouse.click.up'; direction: 'up' }
        | { type: 'mouse.click.down'; direction: 'down' }
        | { type: 'mouse.move' }
        | { type: 'keypress' };
    },
    on: {
      'mouse.click.*': {
        actions: ({ event }) => {
          event.type;
          // 'mouse.click.up' | 'mouse.click.down'
          event.direction;
          // 'up' | 'down'
        }
      },
      'mouse.*': {
        actions: ({ event }) => {
          event.type;
          // 'mouse.click.up' | 'mouse.click.down' | 'mouse.move'
        }
      }
    }
  });
  

Minor Changes

• #4213 243d36fa8 Thanks @Andarist! - You can now define strict tags for machines:

  createMachine({
    types: {} as {
      tags: 'pending' | 'success' | 'error';
    }
    // ...
  });
  

• #4209 e658a37f4 Thanks @Andarist! - Allow the TGuard type to flow into actions. Thanks to that choose can benefit from strongly-typed guards.

• #4182 d34f8b102 Thanks @davidkpiano! - You can now specify delay types for machines:

  createMachine({
    types: {} as {
      delays: 'one second' | 'one minute';
    }
    // ...
  });
  

Minor Changes

• #4181 70bd8d06f Thanks @davidkpiano! - You can now specify guard types for machines:

  createMachine({
    types: {} as {
      guards:
        | {
            type: 'isGreaterThan';
            params: {
              count: number;
            };
          }
        | { type: 'plainGuard' };
    }
    // ...
  });
  

Patch Changes

• #4206 e7b59493a Thanks @Andarist! - Fixed type-related issue that prevented guards not('checkFoo') from being used in machines.

• #4210 5d19c5a75 Thanks @Andarist! - Allow the types to flow from pure to raise that it returns. It now should properly raise errors on attempts to raise non-defined events and it should allow all defined events to be raised.

Minor Changes

• #4180 6b1646ba8 Thanks @davidkpiano! - You can now specify action types for machines:

  createMachine({
    types: {} as {
      actions: { type: 'greet'; params: { name: string } };
    },
    entry: [
      {
        type: 'greet',
        params: {
          name: 'David'
        }
      },
      // @ts-expect-error
      { type: 'greet' },
      // @ts-expect-error
      { type: 'unknownAction' }
    ]
    // ...
  });
  

• #4179 2b7548579 Thanks @davidkpiano! - Output types can now be specified in the machine:

  const machine = createMachine({
    types: {} as {
      output: {
        result: 'pass' | 'fail';
        score: number;
      };
    }
    // ...
  });
  
  const actor = createActor(machine);
  
  // ...
  
  const snapshot = actor.getSnapshot();
  
  if (snapshot.output) {
    snapshot.output.result;
    // strongly typed as 'pass' | 'fail'
    snapshot.output.score;
    // strongly typed as number
  }
  

Major Changes

• #4176 2e176b0b9 Thanks @davidkpiano! - The interpret(...) function has been deprecated and renamed to createActor(...):

  -import { interpret } from 'xstate';
  +import { createActor } from 'xstate';
  
  -const actor = interpret(machine);
  +const actor = createActor(machine);
  

Minor Changes

• #4145 5cc902531 Thanks @davidkpiano! - Significant improvements to error handling have been made:

  • Actors will no longer crash when an error is thrown in an observer (actor.subscribe(observer)).
  • Errors will be handled by observer's .error() handler:

    actor.subscribe({
      error: (error) => {
        // handle error
      }
    });
    

  • If an observer does not have an error handler, the error will be thrown in a clear stack so bug tracking services can collect it.

• #4054 a24711181 Thanks @davidkpiano! - Input types can now be specified for machines:

  const emailMachine = createMachine({
    types: {} as {
      input: {
        subject: string;
        message: string;
      };
    },
    context: ({ input }) => ({
      // Strongly-typed input!
      emailSubject: input.subject,
      emailBody: input.message.trim()
    })
  });
  
  const emailActor = interpret(emailMachine, {
    input: {
      // Strongly-typed input!
      subject: 'Hello, world!',
      message: 'This is a test.'
    }
  }).start();