RootFinalStatesFrom and/or waitForFinalState

[maxfi]

When using waitFor on the backend, it would be great to be able to ensure that all final states are handled (possibly using something like https://github.com/gvergnaud/ts-pattern#exhaustive).

@mattpocock suggested in the discord that something like the following could be implemented in typegen:

type RootFinalStatesFrom<typeof machine> = ...

Perhaps a more specific waitFor could be implemented that waits for final states? For example,

const machine = ... // 2 final states: "User found" | "User not found"
const actor = interpret(machine).start();
const finalState = await waitForFinalState(actor)
finalState.value
//         ^ "User found" | "User not found"

Or maybe finalState.matches() needs to have its argument constrained to "User found" | "User not found" but I'm not sure how an exhaustive check would work then using either a switch statement or a pattern matching library like [ts-pattern](https://github.com/gvergnaud/ts-pattern#exhaustive). 🤔

[Andarist]

Isn't this already possible today with this:

await waitFor(actor, state => state.done)

[maxfi]

@Andarist Yup. It's already possible. 😀 But...

const finalState = await waitFor(actor, state => state.done)
// Enter the below into vscode
finalState.matches(" 
//                  ^ The states aren't constrained to only the final states

It would be awesome to use an exhaustive check, with either a switch statement and exhaustive check or https://github.com/gvergnaud/ts-pattern#exhaustive, to ensure that all final states are handled.

Using ts-pattern it could look something like this (with final states being "User found" | "User not found" :

match(finalState)
  .with({value: "User found"}, () => console.log("Yay! User found"))
  .exhaustive() // This would throw a ts error as not all final states are handled

match(finalState)
  .with({value: "User found"}, () => console.log("Yay! User found"))
  .with({value: "User not found"}, () => console.log("Oops! User not found"))
  .exhaustive() // This would be ok

Hope that makes sense! Thanks. 🙏

[Andarist]

The problem is that even if we'd expose smth like RootFinalStatesFrom based on the typegen data then you still wouldn't be able to do this with waitFor because we can't easily narrow down its return value based on the predicate that you provide to it (at least not in a completely type-safe way). So you would need a specialized API for that (it could exist in your codebase, and wouldn't have to be provided by us).

[maxfi]

@mattpocock Any thoughts/ideas on this? Perhaps if you have an idea for a solution and can point me in the right direction in the code I can have a crack at it? Thanks! 🙏

[Andarist]

The question still stands if this is something we'd like to include. Introducing this has some costs and I wonder how big an audience this would get among our users. Note that you can always assign stuff to context in your final states and use exhaustive based on that information. Maybe sometimes you'd have to write some extra code and "duplicate" stuff (in the given example of the user found/not found scenario you probably wouldn't have that problem though as most likely u have your user data assigned to context anyway) but at least that's a generic solution that can work with just anything you want. You can utilize it with any context-based predicate.

[maxfi]

xstate-tools repo is the place to go! The introspectMachine file is where we grab all the info.

Thanks! I'll check it out.

[maxfi]

The question still stands if this is something we'd like to include. Introducing this has some costs and I wonder how big an audience this would get among our users. Note that you can always assign stuff to context in your final states and use exhaustive based on that information. Maybe sometimes you'd have to write some extra code and "duplicate" stuff (in the given example of the user found/not found scenario you probably wouldn't have that problem though as most likely u have your user data assigned to context anyway) but at least that's a generic solution that can work with just anything you want. You can utilize it with any context-based predicate.

Thanks @Andarist. 🙏

I wonder how must people are using waitFor? Personally I plan to use it a lot, especially on the backend, or complex logic on the front end! 🎉 I suspect the two most common use cases of waitFor will be either waiting for a final state or a tag.

assigning to context could definitely be an option but I feel that a more intuitive approach would be to have different final states for all the cases that you want to handle.

As you mentioned, given RootFinalStatesFrom one could implement their own waitForFinalState function using waitFor and a type cast. So the usage would be const finalState = await waitForFinalState() - so no predicate function but possibly an options object.

[Andarist]

The additional (IMHO a big one) problem with the proposed waitForFinalState is that I'd expect that most of the time you actually need to read the context for a given final state and do something with the values there. We don't have any way to associate a particular state value with the context shape though (this was available previously as typestates but it was never type-safe), so I'd expect that this idea introduces either casting down the road or defensive checks and at that point you lose certain traits/guarantees for your app's logic. While we'd like to figure out in the future how to actually have type-safe typestates~ - we don't have a solution for this yet. I feel like the assign solution might be a little bit of a chore at the moment - but at least it doesn't lose you those guarantees because u match against what you usually need to read in the end anyway.

It's not that I don't see a value in exhaustive matching against each possible final state - it's just that it has some important drawbacks in the current shape of things and thus I, sort of, believe that it's not the time to follow up on this idea.

A separate thing though is that perhaps we could expose a simplified config on the typegen metadata and based on it you could compute what you want, it could also be used to compute things that we already precompute in the typegen - like state values for .matches().

[maxfi]

Thanks @Andarist. I wonder if perhaps a possible solution could be to generate the waitForFinalState function as part of the typegen process?