Vague sweeping question about TypeScript and XState

[HerbCaudill]

This is kind of a rephrasing of my question in #4783, and is related to several other TS questions (#4697 for example).

The TypeScript story in v5 is a big improvement in most respects. If you use the setup(...).createMachine(...) API, and you put every single bit of your code between those parens, you get strong typing everywhere without any hassle.

The tradeoff is that if everything has to be inline, you lose access to some of the language's fundamental tools for wrangling complexity - things like "assigning values to named constants" and "putting some of your code in other files".

This is not a criticism - I realize that getting type safety in this context is a hard problem, probably in ways that I only dimly understand; and I know you guys understand TypeScript better than pretty much anyone, and we're probably bumping up against the limitations of what TypeScript can do.

What I'm wondering is: Is there anything at all we can do to bridge the chasm that currently exists between easy setup(...) scenario, and any even-slightly-more-complex use case?

To make this a bit less abstract, here's an example of what I'm talking about (see StackBlitz or playground):

const config = {
  id: 'feedback',
  initial: 'prompt',
  context: { feedback: '' },
  states: {
    prompt: {
      on: {
        'feedback.good': 'thanks',
        'feedback.bad': 'form',
      },
    },
    form: {
      on: {
        'feedback.update': { actions: 'onSubmit' },
        back: { target: 'prompt' },
        submit: { guard: 'feedbackValid', target: 'thanks' },
      },
    },
    thanks: {},
    closed: {
      on: { restart: 'prompt' },
    },
  },
  on: {
    close: '.closed',
  },
} as const

const onSubmit = assign(({ event }: ActionParam) => {
  assertEvent(event, 'feedback.update')
  return { feedback: event.value }
})

const feedbackValid = ({ context }: ActionParam) => context.feedback.length > 0

export const feedbackMachine = setup({
  types: {
    context: {} as Context,
    events: {} as Event,
  },
  actions: { onSubmit },
  guards: { feedbackValid },
}).createMachine(config)

// TYPES

type Context = { feedback: string }

type Event = EventObject &
  (
    | { type: 'feedback.good' }
    | { type: 'feedback.bad' }
    | { type: 'feedback.update'; value: string }
    | { type: 'submit' }
    | { type: 'close' }
    | { type: 'back' }
    | { type: 'restart' }
  )

type ActionParam = { event: Event; context: Context }

Here I've almost succeeded at extracting some of the feedback machine's pieces - the config into a constant, and the action and the guard into standalone functions; but TypeScript is unhappy about actions: { onSubmit }:

Type 'ActionFunction<Context, Event, EventObject, NonReducibleUnknown, ProvidedActor, never, never, never, never>' is not assignable to type 'ActionFunction<Context, { type: "feedback.good"; } | { type: "feedback.bad"; } | { type: "feedback.update"; value: string; } | { type: "submit"; } | { type: "close"; } | { type: "back"; } | { type: "restart"; }, ... 6 more ..., EventObject>'.
  Types of property '_out_TEvent' are incompatible.
    Type 'EventObject | undefined' is not assignable to type '{ type: "feedback.good"; } | { type: "feedback.bad"; } | { type: "feedback.update"; value: string; } | { type: "submit"; } | { type: "close"; } | { type: "back"; } | { type: "restart"; } | undefined'.
      Type 'EventObject' is not assignable to type '{ type: "feedback.good"; } | { type: "feedback.bad"; } | { type: "feedback.update"; value: string; } | { type: "submit"; } | { type: "close"; } | { type: "back"; } | { type: "restart"; } | undefined'.
        Type 'EventObject' is not assignable to type '{ type: "feedback.good"; } | { type: "feedback.bad"; } | { type: "feedback.update"; value: string; } | { type: "submit"; } | { type: "close"; } | { type: "back"; } | { type: "restart"; }'.(2322)

So I go looking for the type signature of assign, and it's this:

export declare function assign<
  TContext extends MachineContext,
  TExpressionEvent extends AnyEventObject,
  TParams extends ParameterizedObject['params'] | undefined,
  TEvent extends EventObject,
  TActor extends ProvidedActor
>(
  assignment:
    | Assigner<LowInfer<TContext>, TExpressionEvent, TParams, TEvent, TActor>
    | PropertyAssigner<LowInfer<TContext>, TExpressionEvent, TParams, TEvent, TActor>
): ActionFunction<TContext, TExpressionEvent, TEvent, TParams, TActor, never, never, never, never>

...at which point I think most developers will do what I did, which is to throw up my hands and go back to putting everything inline.

• Maybe this is just a matter of adding a couple of more TS cookbook examples showing usage beyond the simple inline setup() use case?
• Maybe there are some helper types that we can expose?
• Maybe we just have to wait for the typegen tool to be available for v5?

Again I hope this doesn't read as criticism, and I don't mean to whinge - I'd be very happy to contribute to a solution if you can give me a sense of how you're thinking about this. Or maybe I'm just holding it wrong and there's a straightforward way to do this, in which case I'd be happy to contribute to the docs.

[christophe-g]

...at which point I think most developers will do what I did, which is to throw up my hands and go back to putting everything inline

Been there, done exactly that !
Thanks for this question.

[emmanuel]

I've landed on the other side of this (for now), with the result that I have somewhat less than the full type-safety that Xstate can provide, but I haven't relinquished the other benefits that you point to above (e.g., code organized in separate files: think actions.ts, context.ts, state and event names as exported constants safely re-usable outside the machine, etc).

I prefer the trade-off that I've made, though I'm relatively new to Xstate and I have little sense of the long-term implications of either direction. Please provide some guidance about what to consider when making these decisions, it would be very appreciated!

[boneskull]

A helper function may be able to solve this. Think a createAssignAction() that wraps assign() but accepts additional parameters (e.g., machine, event expression); it would infer the type arguments from those parameters.

Such a helper function may still be cumbersome--but that's the general solution I've seen to the problem of "omg too many type args".

[Szulerinio]

I am new to Xstate, so it might be obvious to others, but docs say, that one should not directly call assign inside custom action function
https://stately.ai/docs/actions#built-in-actions