[v5] setup() API

[davidkpiano]

const getChatCompletion = fromPromise(async () => { ... });
const processResult = fromPromise(async () => { ... });
const sendToDiscord = fromPromise(async () => { ... });

const machine = setup({
  actors: {
    getChatCompletion,
    processResult,
    sendToDiscord
  }
}).createMachine({
  // ...
  states: {
    thinking: {
      invoke: { src: 'getChatCompletion', onDone: 'processing' }
    },
    processing: {
      invoke: { src: 'processResult', onDone: 'sending' }
    },
    sending: {
      invoke: { src: 'sendToDiscord', onDone: 'done' }
    },
    done: { type: 'final' }
  }
});

[changeset-bot]

🦋 Changeset detected

Latest commit: 3bd3767

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
xstate	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[davidkpiano]

This fails without setup()

[davidkpiano]

types: {
  children: {} as {
    [key: `todo-${number}`]: 'todo';
    ['my-notifier']: 'notifierSrc';
  }
}

Or:

types: {
  childrenIds: {} as {
    todo: `todo-${number}`,
    notifierSrc: 'my-notifier',
  }
}

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 3bd3767:

Sandbox	Source
XState Example Template	Configuration
XState React Template	Configuration

[nstadigs]

Big fan of this change! Would it be weird to also support setting the event type in setup()? A framework could then use setup to export a fully preconfigured createMachine function where all the possible events and side effects are provided beforehand without using type hacks, no? See this discussion for context: #4315

[Andarist]

Big fan of this change! Would it be weird to also support setting the event type in setup()?

That's the current plan.

A framework could then use setup to export a fully preconfigured createMachine function where all the possible events and side effects are provided beforehand without using type hacks, no? See this discussion for context: #4315

I'm not sure if that would solve this particular issue though. The event type could be "preconfigured" here but other than that it would be set in stone. IIRC, you wanted to extend it with more event types.

[with-heart]

Don't forget to add setup to the core exports 😆

[with-heart]

Hey @davidkpiano, could you expand the example in the PR description to show envisioned usage for the other keys of the setup object param?

I really like the idea of defining the implementations up front and deriving types from them as much as possible but I'm struggling with thinking through how this could work with built-in actions like assign.

[davidkpiano]

Hey @davidkpiano, could you expand the example in the PR description to show envisioned usage for the other keys of the setup object param?

I really like the idea of defining the implementations up front and deriving types from them as much as possible but I'm struggling with thinking through how this could work with built-in actions like assign.

Hey sure!

So, you can always inline assign(...). But if you want to "serialize" them:

const machine = setup({
  actions: {
    setToZero: assign({ 
      count: 0
    })
  }
}).createMachine({
  entry: 'setToZero'
});

Not sure how context typings will work, or if/how parameters will work with this yet (cc. @Andarist)

[Andarist]

This one works just fine with what I will be pushing out soon:

setup({
  types: {} as {
    context: {
      count: number;
    };
  },
  actions: {
    resetTo: assign((_, params: number) => ({
      count: params
    }))
  }
})

[nstadigs]

Big fan of this change! Would it be weird to also support setting the event type in setup()?

That's the current plan.

A framework could then use setup to export a fully preconfigured createMachine function where all the possible events and side effects are provided beforehand without using type hacks, no? See this discussion for context: #4315

I'm not sure if that would solve this particular issue though. The event type could be "preconfigured" here but other than that it would be set in stone. IIRC, you wanted to extend it with more event types.

In my case the file providing the preconfigured 'createMachine' (using setup) would be generated, so extra event types can be specified before generating the code.

[Necmttn]

THANK YOU for this! This cleared up quite a bit type inference I was doing.

[joernroeder]

I'm just stumbling upon this from within the changelog. can someone give more context what this replaces or what the benefits of writing it that way are? is it just the call signature of createMachine? is it Typescript? what's the difference to myMachine.provide({ actors: { myActor } }}

thanks in advance

[davidkpiano]

I'm just stumbling upon this from within the changelog. can someone give more context what this replaces or what the benefits of writing it that way are? is it just the call signature of createMachine? is it Typescript? what's the difference to myMachine.provide({ actors: { myActor } }}

thanks in advance

By setting up the types in advance, not only is it much less boilerplate, but with how TypeScript works, we're able to more strongly infer typing throughout the machine. So instead of e.g.:

createMachine({
  types: {
    actors: {} as {
      logic: typeof someLogic;
    }
  }
}).provide({
  actors: { someLogic }
})

You can write:

setup({
  actors: { someLogic }
}).createMachine({/* ... */});

Both setup() and .provide() can be used together; they're for different use-cases:

• setup() is for setting up the known implementations (or stubs) in advance
• .provide() is for providing implementations to override the existing ones.

[joernroeder]

Thanks @davidkpiano for the swift response and clarification, love it!