[core] Modeling events with createModel()

[davidkpiano]

Making this PR to discuss and see how we can improve this. This PR provides type inference for events in createModel() that are specified as "event creators":

const userModel = createModel(
  {
    name: 'David',
    age: 30
  },
  {
    updateName: (value: string) => ({ value }),
    updateAge: (value: number) => ({ value }),
    anotherEvent: () => ({})
  }
);

// Example of an externally-defined assign action
const assignName = userModel.assign(
  {
    name: (_, event) => {
      return event.value;
    }
  },
  'updateName'
);

const machine = createMachine<
  typeof userModel['types']['context'],
  typeof userModel['types']['events']
>({
  context: userModel.initialContext,
  initial: 'active',
  states: {
    active: {
      on: {
        updateName: {
          actions: assignName
        },
        updateAge: {
          actions: userModel.assign((_, e) => {
            return {
              age: e.value
            };
          })
        }
      }
    }
  }
});

let updatedState = machine.transition(
  undefined,
  userModel.events.updateName('Anyone')
);

expect(updatedState.context.name).toEqual('Anyone');

updatedState = machine.transition(
  updatedState,
  userModel.events.updateAge(42)
);

expect(updatedState.context.age).toEqual(42);

This is a little awkward, sure:

const machine = createMachine<
  typeof userModel['types']['context'],
  typeof userModel['types']['events']
>({/* ... */})

But the important part is this:

let updatedState = machine.transition(
  undefined,
  userModel.events.updateName('Anyone')
);

updatedState = machine.transition(
  updatedState,
  userModel.events.updateAge(42)
);

The second argument to createModel(initialCtx, eventCreators) enables two things:

• Events to be easily created and strongly typed using these convenient event creators, and...
• Event types to be inferred automatically from these event creators! 🎉

Let me know your thoughts!

[changeset-bot]

🦋 Changeset detected

Latest commit: 5febfe8

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

This PR includes changesets to release 3 packages

Name	Type
xstate	Minor

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

[HipsterBrown]

Instead of needing to do:

const machine = createMachine<typeof myModel['types']['context'], typeof myModel['types']['events']>({});

Could there be a function definition for createMachine to accept a ContextModel type argument that uses those types fields?

export function createMachine<ContextModel, TTypeStates>(config: MachineConfig): StateMachine<ContextModel['types']['context'], any, ContextModel['types']['events'], TTypeStates>;

[davidkpiano]

Instead of needing to do:

const machine = createMachine<typeof myModel['types']['context'], typeof myModel['types']['events']>({});

Could there be a function definition for createMachine to accept a ContextModel type argument that uses those types fields?

export function createMachine<ContextModel, TTypeStates>(config: MachineConfig): StateMachine<ContextModel['types']['context'], any, ContextModel['types']['events'], TTypeStates>;

Ideally yes, but I don't know if it's possible to have function overloading with different generic types... @Andarist @mattpocock ?

[HipsterBrown]

I don't know if it's possible to have function overloading with different generic types

It looks like the Machine function does this currently: https://github.com/davidkpiano/xstate/blob/master/packages/core/src/Machine.ts#L13-L29

[Andarist]

Ideally yes, but I don't know if it's possible to have function overloading with different generic types... @Andarist @mattpocock ?

Yep, totally possible.

[eddiewang]

looks great! I have been using createModel in my machines lately to make typing more consistent and it's been working well. would this be compatible with the createUpdater fns from Immer?

[davidkpiano]

looks great! I have been using createModel in my machines lately to make typing more consistent and it's been working well. would this be compatible with the createUpdater fns from Immer?

It should be! I haven't tested it out, might need to update the types or create an Immer-specific createModel.

[cbmd]

@davidkpiano how about to implement an array of events acceptable?
Something like....

import isType from '@sindresorhus/is';
import type { EventObject } from 'xstate';
import type { AssertedTypesUnion } from './types';

export function assertEventType<
  TEvent extends EventObject,
  TExpectedType extends TEventTypeArray | TEventType,
  TEventType extends TEvent['type'],
  TEventTypeArray extends TEventType[]
>(
  event: TEvent,
  expected: TExpectedType,
): asserts event is TEvent & {
  type: AssertedTypesUnion<TExpectedType>;
} {
  const events = isType.array<TExpectedType>(expected) ? expected : [expected];
  const { type } = event;
  if (!events.includes(type as TExpectedType)) {
    throw new Error(
      `Invalid event: expected one of "${events.join(
        ',',
      )}" but got "${type}" instead.`,
    );
  }
}

wherever isType from @sindresorhus/is surely could be eliminated, just copy/pasted from existing project to make it simple...
Any objections against adding that @davidkpiano / @Andarist?