TypeScript event typing best practices

[Cheerazar]

Hi there 👋 I'm looking for some best practices for typing my events in TypeScript. Right now if I don't add the value key to the LOGOUT and AUTHENTICATE events in the code sample below, I get the following error in setClaims:

Property ‘value’ does not exist on type ‘GlobalEvent’.
Property ‘value’ does not exist on type ‘{ type: “LOGOUT”; }’.ts(2339)

I couldn't find anything in the docs or the examples that covered this. Are there best practices for typing your events or some examples that anyone can share that cover this? Thanks!

Edit: here's a sandbox.

import { memoize } from 'lodash';
import { assign, createMachine } from 'xstate';
import { UserClaims } from '@okta/okta-auth-js';
​
export const AUTHENTICATE = 'AUTHENTICATE';
export const LOGIN = 'LOGIN';
export const LOGOUT = 'LOGOUT';
​
export type GlobalContext = {
  claims: UserClaims | null;
  error?: string;
};
​
export type GlobalEvent =
  | { type: 'LOGOUT'; value: null }
  | { type: 'AUTHENTICATE'; value: null }
  | { type: 'LOGIN'; value: UserClaims };
​
export type GlobalState =
  | {
      value: 'authenticating';
      context: GlobalContext & {
        error: undefined;
      };
    }
  | {
      value: 'loggedIn';
      context: GlobalContext & {
        error: undefined;
      };
    }
  | {
      value: 'loggedOut';
      context: GlobalContext & {
        error: undefined;
      };
    };
​
export default memoize(function createGlobalMachine(initialState) {
  return createMachine<GlobalContext, GlobalEvent, GlobalState>(
    {
      id: 'global',
      initial: initialState,
      context: {
        claims: null,
        error: undefined,
      },
      states: {
        authenticating: {
          on: {
            LOGIN: {
              target: 'loggedIn',
              actions: 'setClaims',
            },
          },
        },
        loggedIn: {
          on: {
            LOGOUT: {
              target: 'loggedOut',
              actions: 'clearClaims',
            },
          },
        },
        loggedOut: {
          on: {
            AUTHENTICATE: {
              target: 'authenticating',
            },
          },
        },
      },
    },
    {
      actions: {
        clearClaims: assign({
          claims: (_ctx, _evt) => null,
        }),
        setClaims: assign({
          claims: (_ctx, evt) => evt.value,
        }),
      },
    }
  );
});

[davidkpiano]

✏️ Please create a CodeSandbox (XState TypeScript template) reproduction of this. Thanks!

[Cheerazar]

@davidkpiano here's the sandbox you asked for and I added it to the original question as well.

[Andarist]

This is currently not possible (or not in an easy way) to type properly using pure TS. The second argument passed to the createMachine is somewhat contextless - in a sense that it doesn't know where in the schema those actions are used and thus it cannot limit your GlobalEvent union to only truly relevant events.

We are working on fixing this problem with a typegen tool that actually has more knowledge about XState and can use it to create more full and stricter types than we can do without it. It's beta and thus how it works in details is subject to change, but it's worth trying out already as it can already provide good value: https://github.com/mattpocock/xstate-codegen

[davidkpiano]

Here's an idea: since any action in actions assume (rightfully) that any event can be sent to it, you have to explicitly guard against unwanted events. One way to do this with TypeScript is to use an assertion function:

function assertEventType<TE extends EventObject, TType extends TE["type"]>(
  event: TE,
  eventType: TType
): asserts event is TE & { type: TType } {
  if (event.type !== eventType) {
    throw new Error(
      `Invalid event: expected "${eventType}", got "${event.type}"`
    );
  }
}

And that way, all you'll need to do is add that function:

        setClaims: assign({
          claims: (_ctx, evt) => {
+           assertEventType(evt, "LOGIN");
            return evt.value;
          }
        })

And it will be typed correctly! Check it out: https://codesandbox.io/s/xstate-typescript-template-forked-b19c4?file=/src/index.ts

[Cheerazar]

@davidkpiano that worked like a charm! I wasn't familiar with TypeScript assertion functions until now, but that was just what was needed. Thanks!

[pke]

maybe this assert should be made part of the library @davidkpiano?

Or maybe a templated version of assignEvent<LoginEvent> could be used as typesafe assign replacement?
It could also allow multiple events to be described assignEvent<"LOGIN|"LOGOUT">.
Signature would be the same as assign.

[pke]

I wonder how one would write a test to trigger the assert? By just calling the services actions manually with a different event type?

[Andarist]

maybe this assert should be made part of the library @davidkpiano?

We are working on the typegen approach that should make things like this obsolete - if you are only willing to install our VScode extension or use some kind of a CLI that we are going to publish.

[pke]

OK waiting for what you have cooking there ;)
Any thoughts on how to get coverage for the asserts "throw" line with a unit test?

[karfau]

For our own event types, we know what the type should be, so the above approach works.
But what if we have a DoneInvokeEvent as part of our Events, it's type property has the type string.
Can we reliably assume the value of the type property for such an event?
(With the newest typescript versions template literals are type checked, so maybe it can become more narrow by providing another generic that defaults to string?)

And could assertEventType become part of the libary?

[Andarist]

We are going to be rethinking a lot of TS-related stuff in the upcoming months so stay tuned. We plan to deliver the best-in-class TS experience but it might take some time before we deliver that.

[karfau]

Thx for the reply, looking forward to it.
It's really a pity that it currently seem to require triple the code to properly type every possible aspect of a machine.

On a side note:
I have nothing to prove it but I had the impression that recent changes in the types have a tendency to break the build, at least with regards to "the types that worked before no longer work".
Maybe you can try to consider this as part of the upcoming journey.

It's also quite hard to find documentation regarding some special cases, of how to do it with ts.
Maybe it would be nice to have "all"/more and more examples js and ts side by side?

If the examples would also be tested as part of ci, it could be a way to make sure they don't break.

Just some ideas.

[karfau]

And I have another question:
What happens to the machine when an action throws?
If somebody prefers to handle the case without adding a try/catch-block, here is an alternative:

export function isEventType<TE extends EventObject, TType extends TE["type"]>(
  event: TE,
  eventType: TType
): event is TE & { type: TType } {
  return event.type === eventType;
}

wo using the example above it can be a noop:

    setClaims: assign({
      claims: (_ctx, evt) => isEventType(evt, "LOGIN") ? evt.value : _ctx.claims
    })

(Does this make sense?)

[Andarist]

What happens to the machine when an action throws?

That is not super well-defined right now - it also might depend on the action type. For example custom actions (basically functions like actions: () => {}) do this:

xstate/packages/core/src/interpreter.ts

Lines 782 to 799 in fb3cdfa

	if (exec) {
	try {
	return exec(context, _event.data, {
	action,
	state: this.state,
	_event
	});
	} catch (err) {
	if (this.parent) {
	this.parent.send({
	type: 'xstate.error',
	data: err
	} as EventObject);
	}
	throw err;
	}
	}

But builtin actions just throw (without sending an event to the parent). I would expect that this might always lead to some kind of inconsistent state and that having errors thrown should be avoided (your logic should be tested and thrown errors should just not happen).

This feels inconsistent and we plan to refine this and document this stuff so users would know exactly how this stuff behaves and how to deal with errors.