[v5] Input

[davidkpiano]

This PR adds input to the second argument of the interpret(...) function. This passes input data in the "xstate.init" event:

const greetMachine = createMachine({
  context: ({ input }) => ({
    greeting: `Hello ${input.name}!`
  })
  // ...
});

const actor = interpret(greetMachine, {
  // Pass input data to the machine
  input: { name: 'David' }
}).start();

Addresses STA-3438

[changeset-bot]

🦋 Changeset detected

Latest commit: 718da10

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

This PR includes changesets to release 1 package

Name	Type
xstate	Major

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

[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 718da10:

Sandbox	Source
XState Example Template	Configuration
XState React Template	Configuration

[ghost]

👇 Click on the image for a new way to code review

Legend

[Andarist]

we should add the same test to all other integration packages

[davidkpiano]

https://linear.app/statelyai/issue/STA-3445

[with-heart]

Are you thinking of adding a way to get/set the type of input for a machine?

[Andarist]

As in with something like withInput? I think that's not necessary. A machine is like a class and input is information specific to its instance.

[with-heart]

More in the sense of making it part of a machine's public api so you can expect a certain type of input data that's consumed

[Andarist]

Ah, ye - the types for this will come in a followup PR

[Andarist]

thoughts about removing this getter altogether?

[davidkpiano]

I'm okay with it as long as we can make all the tests pass still 😅

[Andarist]

let's do this in a follow up work as this is just a symptom of a bigger story

[Andarist]

As we might see in the diff here - now actors won't have access to TContext and TEvent. So it's not possible to "configure" their dynamic part (input) in the implementations object. That's only possible within the config itself, through the invoke.input property. However, at the moment, we are not able to provide typegen-based information there so this might get annoying to people.

WDYT about allowing this to be:

// it's not a complete final type, just an illustration for this accepting `{ src, input }` 
actors: Record<string, AnyActorBehavior | { src: AnyActorBehavior, input: InputCreator<TContext, TEvent> }>; 

[davidkpiano]

The problem is that input might be different depending on where you come from:

state1: {
  invoke: {
    src: 'something',
    input: (ctx) => /* get from context */
  }
}

state2: {
  invoke: {
    src: 'something',
    input: (_ctx, ev) => /* get from event */
  }
}

I don't understand the typegen information; invoke.input is only relevant to the invoked actor, not to the machine (which is the scope of typegen); can you clarify?

[Andarist]

The conceptual TInput always comes from a given actor type and is the same regardless of where and how it is instantiated. What might be different between instantiation sites, are the "arguments" used to resolve that same type. But that's exactly the same as with any other implementation type:

state1: {
  entry: 'something'
}

state2: {
  entry: 'something'
}

The final implementation of something just has to deal with all possible argument types. It's free to ignore context completely, and it's free to ignore event - but when it starts using the event, it just has to assume that it's a union of all possible event types that can lead to triggering this specific action.

[davidkpiano]

What should be the resolution for this?

[Andarist]

I propose this: #3897