[RFC] Possible model deprecation

[Andarist]

Model

Let's start by listing what is the responsibility of the model today and what can be done with it.

1. It accepts an "initial context"
2. It accepts a map of event factories (it also accepts action factories but that is something that is probably rarely used)
3. It returns a "prebound" assign (it's bound to TEvent type)
4. It returns a "prebound" createMachine
5. It provides a reset action that allows one to assign the initial context from point 1

Features recap/purpose

Event factories

We came to the conclusion that event factories can be somewhat cumbersome to work with. The TEvent type that is produced based on them (through TS inference) is very verbose and, at times, very hard to read. TS is somewhat known for very hard-to-read errors and this TEvent can compound this problem. The types machinery used to infer this type is very clever but it's also very hard to debug and modify. One of the main problems here is that the whole TEvent becomes "anonymous" (this also applies to every member of its union) and we can't assign any helpful labels/aliases that would be used by TS-based IDE tooltips etc.

In addition to that, we've found out that it can lead to inconsistencies in the codebase because there is no way to restrict people to only using this way of sending events. This could potentially be solved with a linter.

On top of that, declaring send actions utilizing the model for the parent-child communication can lead to module cycles and even runtime errors as it's possible to call a model's event factory during importing module initialization before the imported module, containing the model, has a chance to be initialized (hi @erikras 👋).

All in all, this doesn't quite "fit" that well with JavaScript language. Note that such event factories are common in, for example, Scala and the Akka framework. The important distinction though is that the language design there is different and the critique outlined here doesn't quite apply to its context.

Initial context

Because TS doesn't allow for "partial inference" and model is often used with event factories that require us to stay in the inference bounds, we end up declaring context type using unsafe assertions.

Type assertions are a very useful language/compiler feature. However, they are not meant for type declarations, and using them like that can lead to an increased number of runtime errors. I think that our job is to promote type-safety in the design of our API and having to rely on type assertions is hurting that goal.

Prebound functions

This is somewhat a nice feature of the model but its main appeal is that it enables us to workaround the mentioned partial inference limitation of TypeScript.

We are working hard on improving the TS story with an additional typegen tool and, with that in place, the main appeal of this "feature" might become redundant. This is especially true for the model.assign because we plan to precompute possible event types and encourage the use of the second argument of the createMachine to provide implementations for actions used in the machine config object using "string references" (aka "named actions").

Context reset

I believe that this is useful at times but it can also be misunderstood by users. The problem, and important realization about the model's API, is that the whole thing is unrelated to the final machine. It's just a container for some initially-defined & static values. This means that it can only reset to the model's initial context but it can't quite reset to the "true" initial context with which the machine has been started.

Possible deprecation

We are considering deprecating the model. It's important for us to hear out the community feedback before going with this further.

Note that for those who like what the model currently has to offer we could move it to a separate package that could still be used by your codebases. It just wouldn't be the "default" way of interacting with the running machines etc.

We could also consider only deprecating the model factories but:

• if we remove them in the future then not that much would be left in the model API, posing a question if the stuff left in it deserves a dedicated API or if maybe we should restructure it somehow
• it makes it hard to move the whole thing to a separate package

Also note that it's pretty easy to declare event factories with vanilla TypeScript/JavaScript:

const greet = (msg: string) => ({ type: 'greet', msg });

type MyEvent = 
  | { type: 'something' }
  | ReturnType<typeof greet>

One additional argument for deprecating the model API is that it makes it harder to sync event schemas between the code and the visual editor that we are working on.

[wKovacs64]

I used to use createModel for the perceived TS benefits, but have since migrated everything to typegen and would not go back. So here's a vote for "would not miss it."

[horacioh]

sounds like I need to refactor all my model-based machines then?

[Andarist]

Note that you don't have to do this right away - the decision about deprecating createModel API is not even final yet. However, if we don't face a considerate backlash from the community then it's very likely to happen.

Also, if you like this pattern then you can continue to use it. We might hand out this API to the hands of the community so you could just swap import statements concerned with it, or we might publish it as a separate package (although I would prefer the former solution).

In other words - don't panic yet. If you like this pattern let us know what do you like about it and let us know how do you feel about this possible deprecation.

[horacioh]

personally I like that there's a way I can import all the possible events a machine can receive. I like working with the event creators and not deal with explicitly pass an event object. It's true that when I want to type some actions or something else that accepts the machine itself, it can get a little convoluted. but nothing that bothers me a lot.

To be fair, I haven't played too much with typegen since most of the machines I use on my app are model-based. I miss the fact that I can get helpers with configuring machines (when you start typing actions and services names).

I will play more with typegen before I can commit my opinon to "please don't deprecate model-based machines" 😜

[horacioh]

actually, there's one issue that I don't like about it: I need to implement actions either outside the whole machine or inside the machine definition to get no complains from TS. I suppose this is also fixed with typegen right?

this could be the reason why I should change to typegen maybe?

[codingedgar]

actually, there's one issue that I don't like about it: I need to implement actions either outside the whole machine or inside the machine definition to get no complains from TS. I suppose this is also fixed with typegen right?

this could be the reason why I should change to typegen maybe?

Yep, this seems to be solved by typegen.

[mdpratt]

Typing is probably the biggest pain point when using XState. This is a combination of of the terrible error messages and complex typing under the hood for XState. Models make some things easier at runtime such as handling generics - though they make it harder to extract those types later.

I feel that the TS documentation should be flushed out more with richer examples and list well known pain points. Even an extra page for "Here are dozens of examples of how to do typing" could help alleviate a lot of developer stress from having to piecemeal it themselves. Some of it is Googling and understanding core TypeScript would help, but parts of it are also understanding when the type errors are an artifact of XState or TypeScript (again, see bad error messages).

Here is a naïve example using the example factories above:

const SEND_REQUEST = <TRequest>(request: TRequest) => ({ type: 'SEND_REQUEST', request });
const PAGE = () => ({ type: 'PAGE' });

type MachineEvents<TRequest> =
  | ReturnType<typeof SEND_REQUEST>
  | ReturnType<typeof PAGE>

// TypeScript shows type:
// type MachineEvents = {
//    type: string;
//    request: unknown;
// } | {
//    type: string;
// }

[mdpratt]

Property '...' does not exist on type 'never' is the bane of getting strong typing to work, for me.

[Andarist]

I feel that the TS documentation should be flushed out more with richer examples and list well known pain points. Even an extra page for "Here are dozens of examples of how to do typing" could help alleviate a lot of developer stress from having to piecemeal it themselves.

This is a fair critique - we are still somewhat solidifying best practices but it's definitely a guide that we should put together.

Some of it is Googling and understanding core TypeScript would help, but parts of it are also understanding when the type errors are an artifact of XState or TypeScript (again, see bad error messages).

Ye, unfortunately, there are limits to what we can do at a type-level to improve the experience. For some things it feels like our best shot is to embed more helpful diagnostics in the IDE extension.

Here is a naïve example using the example factories above:

Right, those should be sprinkled with as const. I'll update the example. As to how TS shows this type - this is exactly part of the reason why I'd like to migrate away from the model. The model creates anonymous types for events etc and those will always be really verbose (as we can't give them any meaningful aliases at the type-level) and this makes the error messages even harder to read.

[codingedgar]

I agree with deprecating it. Never fully adopted it, because it never fully solved the TS problems I have. Typegen is closer to be type perfect.

[esemczak]

This worries me a bit. Judging from recent releases and now this message, it looks like maintainers of this project put a lot of their focus on external gadgets, like VSC plugins, rather than extending and refactoring the library itself. If true, the direction of creating a tight dependency between one specific IDE and the library, renders, in my opinion, the latter unusable, or at least not trustworthy. One could ask a question whether xstate is an open and independent library or part of the VS Code ecosystem?

Automation introduced by typegen looks cool on paper, but developers should be able to achieve the same outcome without being forced to use it. Have you considered releasing a cli for example?

I have started using "createModel" approach because it solved several problems with TS, and one big one among others - verbosity. Although not ideal, this solution allows to, well, nomen omen, model a state machine with its context and events rather quickly, without having to write a tonne of unnecessary code. Personally, I would welcome expansion of in-code solutions (factories/helpers/etc) to solve common Typescript related problems more, than having to rely on my IDE to do it for me. Mainly, because I write in VIM...

While on it, I have recently noticed an influx of compatibility breaking changes in minor (!!!) releases and even patches (the last one with version 4.30.2.). These releases predominantly address bugs in relation to typegen, inadvertently breaking otherwise production ready solutions where typegen is not being used... At this point our team had hardcoded working version of the package, because we can't trust even the slightest updates. It's not a good look for otherwise brilliant library, to be honest.

[Andarist]

Like already mentioned - we've only chosen the integration with VSCode as being first because it allowed us to deliver the best experience out of the box. I don't think that CLI can have the same capabilities as an IDE integration and an IDE integration will always be able to do more (like opening webviews, displaying hints/lints in the IDE, working on still unsaved content of a file etc). This is us hashing out ideas and targeting a big group of users at the same time. I believe it's a safe bet to say that by far the most people using XState are working with VScode.

That being said - we won't ever limit ourselves to integration only with a single IDE. Hopefully, more will come and the mentioned CLI is already on its way. This is just a matter of prioritization.

I have started using "createModel" approach because it solved several problems with TS, and one big one among others - verbosity. Although not ideal, this solution allows to, well, nomen omen, model a state machine with its context and events rather quickly, without having to write a tonne of unnecessary code

Could you prepare an example of what do you consider to be unnecessary code? It's an honest question from my side - I just would like to understand your perspective better.

While on it, I have recently noticed an influx of compatibility breaking changes in minor (!!!) releases and even patches (the last one with version 4.30.2.).

We always try to minimize the breaking changes that we introduce and we try to minimize them as much as possible. If we wouldn't care about this the shape of the types would now be completely different. While working on this feature I've always had backward compatibility in mind.

However, keep in mind that I also believe that the only way not to make any breaking changes is to stop development altogether. We are humans and we make mistakes. On top of that, XState is a complicated beast that is being used by many and it's nearly impossible to not introduce some kind of a breaking change for somebody out there, even while introducing a seemingly innocent change.

While indeed we had some issues after the release related to types - I think we've handled it quite well. The issues were often diagnosed rapidly and we've fixed all/most of them by now.

After upgrading any piece of software testing is advised and if any issue comes up - we, maintainers, always appreciate a good bug report. This is why the community has settled on using lock files, right? We can't expect every update to be completely seamless. If you don't want to experience 0-day hiccups then you can always just wait a couple of days until things stabilize themselves.

You can also read more about how we treat semver here

---

I also want to emphasize what David has already said - we are planning for the next major version of XState, we want to make this piece of software as good as it can be and I really hope that you will enjoy it and the growing ecosystem around it.

[codingedgar]

Thanks a lot for your views on those matters, I pretty much had the same concerns but assumed part of what has been said here, now I have the confidence it is.

I think from the beginning TypeScript + XState has been quite a challenge, so I've treated every minor update as a major update (meaning I do not use ^ and spare time for an upgrade), but this is also true for most of the libs I use, so it's fine.

Thank you for your super hard work, the improvements have been noticeable, it is perceivable how XState is only starting 🚀

[esemczak]

Like already mentioned - we've only chosen the integration with VSCode as being first because it allowed us to deliver the best experience out of the box. I don't think that CLI can have the same capabilities as an IDE integration and an IDE integration will always be able to do more (like opening webviews, displaying hints/lints in the IDE, working on still unsaved content of a file etc). This is us hashing out ideas and targeting a big group of users at the same time. I believe it's a safe bet to say that by far the most people using XState are working with VScode.

My complaint isn’t about building tools which, by definition, are meant to make developers life easier. What worries me is perceived focus of maintainers being concentrated on said tools instead of the core functionality of the library. Look, by the end of the day I am not emotionally attached to the model approach. I am off opinion though, that a library should be self-sustained. If you need to use a specific plugin for a specific IDE to achieve an outcome of properly typed code, something seems to be wrong. At least to me, and my team. CLI is different story, especially if you can bundle it up in a package.

Onboarding of a new developer is that much harder, when you have to tell them: here’s the repository and a documentation of the project, and btw, you need to download VSC, and this plugin, and write the code in a very specific way for sake of this plugin, and… you get the picture.

Could you prepare an example of what do you consider to be unnecessary code? It's an honest question from my side - I just would like to understand your perspective better.

By unnecessary I meant verbose. Hard to produce examples from the top of my head since I’m using model for so long, but things like narrowing event types from model.assign, or having all events defined neatly in one, predictable place are very nice. Something I would have called unnecessarily verbose would be Typestates from your own docs. My eyes bled when I saw an example…

We always try to minimize the breaking changes that we introduce and we try to minimize them as much as possible.

I have no doubts that you do, don’t we all as developers? Priorities matter though. I feel like typegens of this world deserve separate projects, not affecting already established APIs etc. Definitely not in minor bumps.

I had written my original feedback literally after having a call from one of my tech leads who had a session with a new developer. They called me, because the production ready piece of code the young one was using to immerse himself did not work as expected, and it was related to states. Without even looking at the code, my reaction was: check if there’s a new minor version of xstate released, and if so, nuke modules, lock to previous version and continue. This is what is called being jaded, I suppose…

I don’t want this to be seen as a rant. I wanted to express slowly growing trepidation about the future of the library I personally love and fiercely promote within my organisation. I will leave you with this:

"^" - this little symbol is a badge of trust. It comes free once, but lost, is very hard to regain.

[Andarist]

Look, by the end of the day I am not emotionally attached to the model approach. I am off opinion though, that a library should be self-sustained. If you need to use a specific plugin for a specific IDE to achieve an outcome of properly typed code, something seems to be wrong. At least to me, and my team.

Define "properly typed" though. For full transparency - I think that current XState types often allow too much, since some any-like types might sneak to your code. So if you are for complete safety then you should look forward to the upcoming changes and not blame us for tightening type declarations. And if every change in types is considered a breaking change then we are just in a big trouble because we can't release any improvements. Note that I'm not referring to the typegen situation at all - I'm purely speaking about typegenless definitions now.

What we want is to revamp types completely in the upcoming major version to provide strictness by default (within reason). However, without using a typegen such types won't be overly pleasant to use. They will require boilerplate, type guards etc. It's just almost impossible for us to deliver maintainable relations between particular actions, actor creators etc and the events that can lead to them. So our "best shot" is to just assume that everything can be called with every possible event that a machine accepts. Limiting event types to types that can actually be received by those "implementations" at runtime would require us to analyze the state machine graph on the type level and this is super hard to do.

The typegen stuff will always be optional but I think that it should just be a preferred way of interacting with XState because it can cut a lot of boilerplate from your code and deliver much better developer experience in this regard. That being said - it won't be required and the library will always be runnable on its own.

Coming back a little bit to "properly typed". I think that in the vast majority of languages the typegenless types are how things would look like in those languages. It's only TypeScript that provides us crazy tools like conditional types and mapped types that make it even possible to deliver typegen stuff. Whereas in other languages to get a similar effect we'd have to reach for full codegen.

Onboarding of a new developer is that much harder, when you have to tell them: here’s the repository and a documentation of the project, and btw, you need to download VSC, and this plugin, and write the code in a very specific way for sake of this plugin, and… you get the picture.

I agree. It is some kind of a barrier and onboarding problem - but I think that RoI is high here so it's worth it. The same argument goes for CLI too, right? So it's not specific to a VSCode extension - and I got a feeling that you are on board with the CLI's idea.

things like narrowing event types from model.assign

I somewhat doubt though that this does increase type safety in any meaningful way. It's just some kind of a sugar but doesn't change assignability rules for TS.

having all events defined neatly in one, predictable place are very nice

I very much value traits like colocation, searchability (being able to grep for occurences of smth in the project) and common patterns that help you to create similar modules with ease. So I think that I hear you here but I'm unsure how exactly this would be deteriorated if we remove model. Unions feel like an idiomatic way of doing such things in TS.

Something I would have called unnecessarily verbose would be Typestates from your own docs. My eyes bled when I saw an example…

You might be happy then that we are planning to remove this "feature" too. In fact, IIRC, this has already been done on the next branch.

I have no doubts that you do, don’t we all as developers? Priorities matter though. I feel like typegens of this world deserve separate projects, not affecting already established APIs etc. Definitely not in minor bumps.

I don't agree with this - mainly because the goal here was to avoid breaking changes. It was supposed to be additive change. We've faced some unintended backlash and had to fix some bugs (I'm still aware of one bug that needs to be fixed), but overall I think this could have gone worse. Note that this feature was in development for months (you can check out when the initial PR was created and how many commits there are, going back and forth between different approaches, just to ensure that we maintain compatibility) and we've tested it in a few codebases. It's not like we have thrown a Hail Mary with that and just hoped for the best.

Without even looking at the code, my reaction was: check if there’s a new minor version of xstate released, and if so, nuke modules, lock to previous version and continue.

I'm trying to understand the context here, not trying to attack you/your project/anything like that. Don't you use lockfiles? Those should mitigate issues like this, right? There is always an explicit time when we update our dependencies and after that potential post-upgrade issues are often discovered.

I don’t want this to be seen as a rant. I wanted to express slowly growing trepidation about the future of the library I personally love and fiercely promote within my organisation.

I hope that with everything that is to come, we will regain your trust and that you will be able to confidently say that you are glad about sticking to XState.

[esemczak]

Define "properly typed" though. For full transparency - I think that current XState types often allow too much, since some any-like types might sneak to your code. So if you are for complete safety then you should look forward to the upcoming changes and not blame us for tightening type declarations.

I am for safety within the reason, where reason comprises cost and efficiency of development. I welcome solutions which help developers achieve one without sacrificing too much of the other. I thought the model-like enhancements to the lib is a step towards that. Hence, we are having this discussion - I was wrong.

And if every change in types is considered a breaking change then we are just in a big trouble because we can't release any improvements. Note that I'm not referring to the typegen situation at all - I'm purely speaking about typegenless definitions now.

Yes you can, in major releases (or, better yet, external projects).

The typegen stuff will always be optional but I think that it should just be a preferred way of interacting with XState because it can cut a lot of boilerplate from your code and deliver much better developer experience in this regard. That being said - it won't be required and the library will always be runnable on its own.

I understand the problem, I’m debating proposed solution. Personally, I’m OK with CLI, because it becomes a part of the project, like for example aws amplify or nx would. VSC’s plugin simply does not fit in this category in my opinion.

things like narrowing event types from model.assign

I somewhat doubt though that this does increase type safety in any meaningful way. It's just some kind of a sugar but doesn't change assignability rules for TS.

That's the thing. Keep the sugar coating for quick and not-so-dirty development, where being a bit looser with types is acceptable, and add a codegen cli to help with boilerplates. Perfect. But then please don’t break sugars with minor bumps of codegens. I think I can’t be clearer with my position.

It's not like we have thrown a Hail Mary with that and just hoped for the best.

Well, I trust your word on that.

I'm trying to understand the context here, not trying to attack you/your project/anything like that. Don't you use lockfiles?

Yes, we do. For a small number of libraries. Now that small number got a bit larger.

I hope that with everything that is to come, we will regain your trust and that you will be able to confidently say that you are glad about sticking to XState.

Same. And honestly, without a drop of sarcasm - good luck.

[huan]

@Andarist thanks for pointing this thread to me.

When I have just started using XState, I think the model API is what I need to declare all my types/events, but soon I switched back to the Redux style because I think the classic style is better.

Currently, I'm using the typesafe-actions with my ducks for managing all my events/types and it is quite clear, easy to use, and straightforward. I'm very happy with them. (here's my WIP PR in case anyone interested)

So I will vote for deprecation because this feature is not the core feature of XState.