Feature: createModel()

[davidkpiano]

This PR adds support for an opt-in helper function called createModel(), which is meant to assist in creating the datamodel (SCXML) for the machine:

import { createMachine } from 'xstate';
import { createModel } from 'xstate/lib/model'; // opt-in, not part of main build

interface UserContext {
  name: string;
  age: number;
}

type UserEvents =
  | { type: 'updateName'; value: string }
  | { type: 'updateAge'; value: number }

const userModel = createModel<UserContext, UserEvents>({
  name: 'David',
  age: 30
});

const assignName = userModel.assign({
  name: (_, e) => e.value // correctly typed to `string`
}, 'updateName'); // restrict to 'updateName' event

const machine = createMachine<UserContext, UserEvents>({
  context: userModel.context,
  initial: 'active',
  states: {
    active: {
      on: {
        updateName: {
          actions: assignName
        }
      }
    }
  }
});

[changeset-bot]

🦋 Changeset detected

Latest commit: a4e129c

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

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit b04f5c8:

Sandbox	Source
XState Example Template	Configuration
XState React Template	Configuration

[johnyanarella]

I was just thinking about how the current uncertainty around #989 and #1367 confounds this effort. The API surface area gets less elegant when once you have to require the developer to differentiate between assign and reset.

But that begs the question... does it even make sense for the entire model shape to change (as in the reset option)? Isn't that an entirely different animal--a union type where each variant might expose different available updaters...

[davidkpiano]

But that begs the question... does it even make sense for the entire model shape to change (as in the reset option)? Isn't that an entirely different animal--a union type where each variant might expose different available updaters...

Most of the time it doesn't, but there are usecases highlighted in those issues that demonstrate the need.

[johnyanarella]

Oh, for sure - definitely didn't mean to come across as dismissive of those needs at all.

Just thinking aloud today as the 💡 slowly flickered on in my head, realizing that those concerns were really about the friction of representing a union type using a key/value store. (And the SCXML spec has essentially mandated a key/value store as the root data model type.) The imperfect emulation of that, and all the effort to emulate it, falls away when storing that union type as keyed value instead. Bonus: language support starts to come into play (both in TypeScript and Swift--which has enums with associated values). Obvious in retrospect, but I was just not seeing it clearly before.

I think that means this cool new createModel() effort gets to similarly side-step those worries, too? i.e. you could have a property of the model that is a union type, and any related constraints become internal updater details rather than the responsibility of this new feature.

[Andarist]

I kinda feel like it would be more appropriate to name this a PropertyAssigner and the other one a PartialAssigner 😅

[davidkpiano]

I know... we can change this for v5

[Andarist]

is this used anywhere? cant find any reference to this 🤔

[Andarist]

q: is this here just to validate types?

[davidkpiano]

Yep!

[Andarist]

This version feels better than some previous iterations with withAssigners etc 👍 Good job.

[Andarist]

Please just remember about adding the appropriate changeset so the changelog entry gets correct attribution to PR etc :)

[Andarist]

Any particular reason behind this change? 🤔 seems a little bit stranger to pass TEvent and K around and compute at the end rather than pass a computed TEvent from here

is it about TransitionConfigTarget including a StateNode target? wouldn't it be better to allow there any at the TEvent position as we should be able to target any state node in the given machine config? As this is going to be removed in v5 anyway (targeting with getters etc) I'm not sure if it's worth complicating the codebase for its sake

[davidkpiano]

I think this is an accidental commit, thanks for catching.

[davidkpiano]

Oh, I just discovered one of the reasons for this change: the raise() event needs to be able to infer all possible events.

[Andarist]

Hm, I've wanted to look into it and I've checked out your branch locally but after removing those casts and comments I couldn't see any TS errors. Could you recheck on your machine? That being said - inferred generics are off and I don't understand why the inferred type is assignable here to the expected one 😭

[davidkpiano]

Hm, I'll keep the comment in here for now.