[V5] Event Schemas

[davidkpiano]

Event schemas are an important feature for event-driven systems, and XState should provide the ability to define event schemas in the machine so that they can be declaratively read and used (within and outside of a TypeScript context).

Some prior art:

• Amazon EventBridge Schema Registry
• Azure Event Grid Schemas

Proposed Plan:

• Add an events (name TBD) property to the machine to represent all of the events that the machine accepts as a subset of JSON Schema:

const machine = createMachine({
  // ...
  events: {
    change: {
      // type: 'object', // assumed
      properties: {
        value: { type: 'string' },
        key: { type: 'string' },
        timestamp: { type: 'number' } // optional
      },
      required: ['value', 'key']
    },
    submit: {} // no extra properties 
  }
});

• Add optional helpers in xstate/schema (name TBD):

import { eventSchema, types } from 'xstate/schema';

const machine = createMachine({
  // ...
  events: {
    change: eventSchema({
      value: types.string, // required by default
      key: types.string,
      timestamp: types.number.optional
    }),
    submit: eventSchema()
  }
});

• Change machine.events so that it returns a mapping of those event schema objects:

machine.events;
// { change: { ... }, submit: { ... } }

---

One of the biggest benefits of this will be in the visualizer (xstate.js.org/viz), since clicking an event can make a popover appear that will present a small form to fill in the required values for the given event type, or even generate sample events automatically!

Any thoughts on this are welcome, feel free to share.

EDIT: Changed eventSchema to events since machine.events already returns an array of accepted events and can be repurposed to return the event schemas for those events, which is more useful.

[caqu]

This looks amazing and a great addition for complex systems. Anything that improves the visualizer is a huge win.

[CodingDive]

Looks great! How does it compare to the event "schema" we define in TypeScript with the discriminatory type. Will they be used together or will the JSON-based event schema replace the need to define distinct types in TypeScript? Alternatively, could the visualizer not read a TypeScript-based event schema which most of us are already defining?

Posting multiple comments so we have an easy time replying.

[davidkpiano]

Good question - there's some TypeScript gymnastics that we can do to partially infer events from the event schemas, but ultimately, you'll want both, since the event schemas will represent more than what TypeScript can represent, and are useful in a non-TypeScript context (think cloud-based machines).

Alternatively, could the visualizer not read a TypeScript-based event schema which most of us are already defining?

It can't, at least not without a lot of effort.

[danielkcz]

Well, that's going to be quite a hurdle to maintain the same thing twice and with a different syntax (mindset switching). I cannot yet imagine the use cases for eventSchema, but I hope it's going to be opt-in. If TS won't be able to catch up desynchronization with eventSchema it might be a source of surprising bugs imo.

I wonder if that schema could be somehow "generated" based on TS, eg. with Babel macros.

[Andarist]

I wonder if that schema could be somehow "generated" based on TS, eg. with Babel macros.

That's the overall plan - to provide a compiler-enhanced workflow, we've just talked about it yesterday and I think we might have figured out how the user would interact with it. Need to further explore this idea and build some POC, it will definitely take some time though

[CodingDive]

What happens when the machine receives an event not defined in the schema. Should it log a warning, ignore the event silently or throw an error as would be the case with strictMode: true? Possibly an important question to answer before moving forward with the strictMode depreciation which I personally have never used and would almost consider an anti-pattern for creating reusable machines.

[davidkpiano]

Events not defined should be ignored silently.

Events that don't adhere to the schema, if you add some sort of validation, should raise an error.

[davidkpiano]

EDIT: validation per schema would be opt-in as well, and not the default.

[CodingDive]

Tangible related and very interesting to me would be to define a schema for other machines.

Essentially when spawning or invoking a machine, I'd love to be able to force the machine who is spawning a child to implement an arbitrary number of events that will be emitted from child to parent (using sendParent) and require additional actions. That's usually the case with reusable machines for searching, selecting a user, toggling a switch or whatever.

Just to give an example, I may have a UserPickerDropdownMachine and component. It may fetch users, display them and allow to select one or multiple users. As it doesn't perform any additional business logic when users are picked, it always wants to send an update to its parent machine once a user has been selected. I'm looking for something like a contract that enforces the USER_SELECTED event to be implemented by any parent that invokes said machine.

[davidkpiano]

That might be difficult to enforce - remember, machines are their own entities, and they can't be "forced" to do stuff from the machines that spawned them.

With that said, an "adapter pattern" would be better suited for the use-cases where the events don't match up exactly. When you move into cloud-based or 3rd-party machine scenarios, this will be more useful, since you can't exactly force a 3rd-party machine to send back specific events.

You can do something like this:

on: {
  'CUSTOM_USER_SELECTED': {
    // adapter
    actions: send(e => ({ ...e, type: 'USER_SELECTED' }))
  }
}

And maybe we can even introduce an event adapter helper:

on: {
  'CUSTOM_USER_SELECTED': {
    actions: adapt('USER_SELECTED')
  }
}

[danielkcz]

Personally, I started using strict mode recently and I like it. There is nothing worse than a typo in the event name, especially across different machines. When it stays completely silent and I have no idea what's the problem. Those are the moments when I kinda hate XState.

What surprised me the most that strict is actually fine when event is handled at least once in the whole machine, not for the current state only: https://codesandbox.io/s/wizardly-wilbur-b19nj?file=/src/index.js (notice that "OK" doesn't cause an error).

This is a really handy tool for typos. (Please, don't deprecate it)

Now imagine I would have to instead define eventSchema which can have a different typo. I would have 3 places where to look to find a problem. I can already imagine the desperation I am going to feel in those moments :/

[Andarist]

I don't feel like this would be that much helpful feature - probably only used by a super small fraction of users.

1. as @FredyC has mentioned - this is yet another thing to author and actually make mistakes while doing so
2. it's not a super common format (JSON schema) and it's super verbose (so not friendly for authoring).
3. it imposes a runtime cost (and bundlesize cost) if we'd like to actually validate events based on this

That being said there are of course benefits for being able to consume such a schema in a nice way - like the enhanced visualizer.

The majority of XState audience are JS developers and I feel like all of the mentioned drawbacks of the JSON schema approach are actually solved by TypeScript. If we can easily convert TS type to a JSON schema is another problem but actually it might not be that hard - I would expect that a simple VScode plugin could be implemented to add a context menu item like "Copy as JSON schema" if only the given type is not using crazy stuff like mapped typed etc the conversion should be fairly trivial. Sure - it wouldn't work for other IDEs out of the box, but one could always also write this manually (which is actually the only way to do it proposed in the original post).

One could paste in such a generated schema into a dedicated input in the visualizer. We could also add a new API that could be used for those that want a runtime validation - something like validatedMachine(config, schema).

Alternatively, in the future, the visualizer could be enhanced with TS support and could potentially be able to convert types from the source code into such schema so one would only have to paste-in their machine code (which would be better as would only require a single action from a user). Even though this would not be a lightweight solution I don't think this is a particular problem - we can expand visualizer with complex capabilities and treat it like a full-blown app. With apps like CodeSandbox, Excalidraw, TS & Babel REPLs etc I wouldn't be worried about bundlesize/startup times.

[davidkpiano]

It would be optional, so I don't expect the majority of users to use it. It would also not validate events by default - it would simply exist as a property.

[Andarist]

If it would be just an additional property then I'm fine with it - but also question the usefulness of it 😉

If one has to write this manually what are actual advantages of having this as an additional property over defining such a schema separately, above the machine definition or anywhere else?