🚀 [FEATURE]: List of Breaking Changes planned for V4

[markwhitfeld]

NGXS follows semantic versioning. As a result we will change the major version number when breaking changes are introduced. Many developers seem to have the idea that upping the major version number is a good thing because it shows progress and is a bit of a marketing opportunity. When following a semantic versioning scheme increasing the version number means that breaking changes have happened, which is not such a positive thing.
Obviously making breaking changes for critical issues should not be avoided but when there are smaller annoyances that need to be remedied then they should be collected together and released together in a single major version update.
This is one such list:

• An @Selector with parameters in a state class should not receive a default first parameter of the enclosing class state
  • See: Discussion: Selector Composition and Query Classes #386 (comment)) (fix(store): do not inject container state by default #2117)
  • Related: 🐞[BUG]: Incorrect behavior when using @Selector #541 Problem with state composition #446
• The plugin interfaces should be part of a @ngxs/store/plugin sub-package
• Review plugin architecture, possibly include more extensibility points than just middleware
• NGXS internals currently exposed as part of the public api should be moved to the @ngxs/store/internals sub-package
• The StateContext.getState should return a DeepReadOnly<> interface (fix(store): ctx.getState should return DeepReadOnly<> #2110)
• The value passed in the observable returned from a dispatch call should be void, matching its interface (fix(store): dispatch return observable should be <void> #2109 )
• patchState and setState should both return void to match their interfaces (Harmonize return value of patchState, setState and getState #491) (fix(store): setState and patchState should both return <void> #2114)
• The web socket plugin should have consistent Title casing of the word WebSocket ( feat(websocket-plugin): add WebSocketDisconnected, WebsocketMessageError actions #825 WIP: feat(websocket-plugin): dispatch WebSocketDisconnected Action upon socket disconnect; dispatch WebsocketMessageError on received message error #820) (fix(websocket-plugin): WebSocket title casing should be consistent #2115)
• The web socket plugin should not expose NGXS_WEBSOCKET_OPTIONS in its public api (fix(websocket-plugin): WebSocket title casing should be consistent #2115)
• The storage plugin should not expose tokens in its public api
• Improve public interface type safety
• Disable suppress errors in selector (the default suppressErrors should be false) (fix(store): enable throwing errors from selectors by default #2111)
• Default the developmentMode setting to align with the angular dev mode.
  • Also see perf(store): tree-shake ConfigValidator, HostEnvironment and isAngularInTestMode #1741 (comment)
• The ofActionErrored pipe should return the error as well as the action (change return value to the same signature which is returned by ofActionCompleted. Where success and cancel should be false) (fix(store): ofActionErrored should return ActionCompletion #2112)
• The Actions stream has to have ActionContext signature except of any.
• Flatten the .d.ts file exports of the library (🚀 [FEATURE]: List of Breaking Changes planned for V4 #827 (comment)) (build: flatten .d.ts files #2131)
• Deprecation notice for @Select. We would need a migration page in the recipes sections of the docs for both of these.
• Deprecation notice for sub-states (the children property of @State). We would need migration pages in the recipes sections of the docs for both of these.
• Please add the motivation for the additional items you add on this list as a comment below
  --

... still going to add some more to this list, saving the issue for now.

Much of this list has been sitting in my head for months. It feels good to get it out! ;-)

Please raise additional proposals for breaking changes in the comments and I will add them to this list if they are something we would like to introduce for v4.

[markwhitfeld]

@eranshmil :

Every time I want to install the devtools plugin in a project, I write NgxsDevtoolsPluginModule, instead of NgxsReduxDevtoolsPluginModule.
I suggest that we create an alias right now and in version 4, deprecate the old symbol.

We will be releasing our own dev tool in time, so I'm quite glad that we did not use NgxsDevtoolsPluginModule 😉

[ahnpnl]

Hi, are there any chances that @Dispatch can be moved from ngxs-labs into this main repo ? Personally I find dispatch is a core functionality like @Select and @Selector so I think it deserves to be in together with @Select and other decorators here.

[splincode]

Latest doc here: https://gist.github.com/LayZeeDK/c822cc812f75bb07b7c55d07ba2719b3

[DaSchTour]

I would be great if typesafety would be improved.

• dispatch should not take any but there should be an interface defined for actions
• ngxsForms could provide an (generic) interface for state, that contains also the different states of status

That's the two things I recall now, but I general it feels like there is a lot of any inside NGXS.

[splincode]

@markwhitfeld @arturovt what do you think about skip VE? and older Angular versions?

[markwhitfeld]

In v4 we could compile for the new Ivy lib format (being introduced in v12) which will drop support for ViewEngine.
We could maintain ViewEngine and backwards compatible support by publishing a @ngxs/store/viewengine subpackage with the old library format.

[markwhitfeld]

We should also look at flattening the .d.ts files published by the lib so that deep imports are not allowed.
Before doing this we need to make sure that we are exporting all types that are typically used.
Doing this may break projects referencing internal types (hence this should be part of v4).
Here is a discussion, and a useful comment on how this can be achieved:
microsoft/TypeScript#4433 (comment)

[irowbin]

Almost after 2 years of this post, is it still on plan or already in dev? 🤔 Looks like it is on hold state. 😕

//cc @markwhitfeld @splincode

[markwhitfeld]

Hi @irowbin. Yes, and no😉.
A prerequisite for these changes is that we get schematics integrated into the @ngxs/store library so that it can facilitate a smooth transition to v4. This initiative has been kicked off about 4 times already, but due to all the disruptions of COVID, each time there has been something that has come up that with the primary contributor to the schematics initiative (such are the perils of Open Source and leveraging people's spare capacity). This initiative was kicked off again in December, I will follow up with the team to see where we are at with this. 👍
Once schematics is in, it will just be a few days of dev to get this all done.

[rbrzoska]

When can we expect v4 ?

[markwhitfeld]

Hi @rbrzoska
As mentioned in my comment above the prerequisite for this is to have schematics built into the lib to facilitate easier migration to v4. The contributors to this effort have not gotten far with this, so if you do know anyone that would love to help out in this regard, please let me know.

[zip-fa]

Hi. How about implementing newly arrived signals?

[destus90]

Seems like with Angular@16 we will not be able to use this library until v4 is released because of this https://github.com/angular/angular/releases/tag/16.0.0-next.0

Angular Compatibility Compiler (ngcc) has been removed and as a result Angular View Engine libraries will no longer work

[markwhitfeld]

@zip-fa Support for signals will be added before v4. There is no prerequisite of any breaking changes for this. 👍

@destus90 We will be compiling for the Ivy format in the next minor release (it does not require v4). This would have been released a while back, but is being blocked by a TypeScript bug. We are looking at ways to detect the scenarios that would cause a user to experience this bug because it is not receiving much attention from the TS team. See this comment for more details.