RFC - Standalone API

[markwhitfeld]

A few ideas are being bounced around on what this could look like.
We are seeking proposals of ideas from the community.
Please create an 'Answer' to this discussion with your proposal which can then be discussed in the thread for it.

Please ensure that it clearly states the following aspects of your proposal:

• What are the changes to the public API?
• What are the advantages?
• What are the potential drawbacks?
• How would backwards compatibility be considered (and if it introduces a breaking change)?

Please also take the time to look at other proposals and engage in respectful discussion.
We will consider every proposal. Please do not be offended if yours is not accepted.
We want to keep the core of NGXS as simple and maintainable as possible, and sometimes bigger ideas are better as plugins.

[arturovt]

I suggest using the same methods in other 3rd party libraries (such as NgRx). Our users can register states via NgxsModule.forRoot() and NgxsModule.forFeature(); we need to change the implementation to register states via functions. The function signature will return EnvironmentProviders:

bootstrapApplication(AppComponent, {
  providers: [
    // might be named whatever we want
    provideNgxs(states)
  ]
})

I haven't thought about the function names; let's assume that they can be called anything for the time being.

The same with feature states:

const routes = [
  {
    path: 'blog',
    loadComponent: () => import('....'),
    providers: [
      // might be named whatever we want
      provideNgxsFeatureStates([BlogState]),
    ],
  },
];

Our users are able to provide configuration through NgxsModule.forRoot(states, CONFIG); we may have a separate function in standalone implementation for this purpose:

bootstrapApplication(AppComponent, {
  providers: [
    provideNgxs(
      states,
      withNgxsConfig({
        developmentMode: !environment.product,
      })
    ),
  ],
});

What about NGXS_PLUGINS:

import { withNgxsLoggerPlugin } from '@ngxs/logger-plugin';
import { provideNgxs, withNgxsConfig, withNgxsPlugin } from '@ngxs/store';

bootstrapApplication(AppComponent, {
  providers: [
    provideNgxs(
      states,
      withNgxsConfig({
        developmentMode: !environment.product,
      }),
      withNgxsLoggerPlugin(),
      withNgxsPlugin(MyCustomPlugin)
    ),
  ],
});

Feature plugins (doesn't exist yet, under consideration):

import { provideNgxsStorageFeatureStates } from '@ngxs/storage-plugin';
import { provideNgxsFeatureStates } from '@ngxs/store';

const routes = [
  {
    path: 'blog',
    loadComponent: () => import('....'),
    providers: [
      // might be named whatever we want
      provideNgxsFeatureStates([BlogState, My_Other_Feature_State]),
      provideNgxsStorageFeatureStates([BlogState]),
    ],
  },
];

The new implementation is backwards compatible with the previous one.

TODO: this post may be updated later, I just drafted my thought aloud real quick...

[profanis]

Although the descriptive names are easy to follow, I would vote to have the provideNgxsFeatureStates as provideNgxsFeatures.
In the same way, the provideNgxsStorageFeatureStates could be something like provideNgxsStorage

const routes = [
  {
    path: 'blog',
    loadComponent: () => import('....'),
    providers: [
      // might be named whatever we want
      provideNgxsFeatures([BlogState, My_Other_Feature_State]),
      provideNgxsStorage([BlogState]),
    ],
  },
];

The fitst name that came to my mind was even shorter: provideFeatures. I like though to have the Ngxs into the function names as it is easier to differentiate between other function names that exist in an app from other libs. For example, whenever I see the TestbedHarnessEnvironment into an application I always need some time to check where is this referring to. In a way that it's easy to follow and understand what a function is doing is the RouterTestingHarness since the name contains the, let's say, context.

Hense 👍 for the overall suggestion!

[Carniatto]

Related PR: #1999

[markwhitfeld]

Following on from @arturovt's recommendations above, this is the API that I think makes sense:

• provideNgxs(states?: StateClass[], config?: NgxsConfig)
  • This is the root initialiser for NGXS and is the equivalent of the current NgxsModule.forRoot(...)
  • This is a singleton provider that is expected to be provided only once. An error should b thrown if it is provided multiple times
• provideNgxsStates(states: StateClass[])
  • This is a provider that adds states to the global NGXS state store, and they become available to the entire application.
  • This is the equivalent to the current NgxsModule.forFeature
  • It can be used as part of lazy, or eager providers for a route or just as part of a provider list specified somewhere in the application.
  • This provider can be called multiple times in the application. If the same state class is specified in multiple places then this state would only be added to the global state once, and the subsequent additions would be ignored.

Plugins could be left to define their own pattern for standalone API, but the following pattern could be recommended:

• provideNgxsFooPlugin(config: NgxsFooPluginConfig) (where Foo is the plugin name placeholder)
  • I don't think that we need to provide any library level plugin provider (like provideNgxsPlugin([...]))

Bringing this all together, it would appear in code as follows:

import { provideNgxsLoggerPlugin } from '@ngxs/logger-plugin';
import { provideNgxs } from '@ngxs/store';

bootstrapApplication(AppComponent, {
  providers: [
    provideNgxs( states, { developmentMode: !environment.production } ),
    provideNgxsLoggerPlugin(),
  ],
});

"Feature" states:

import { provideNgxsStates } from '@ngxs/store';

const routes = [
  {
    path: 'blog',
    loadComponent: () => import('....'),
    providers: [
      provideNgxsStates([BlogState, My_Other_Feature_State]),
    ],
  },
];

---

Just for testing out the APIs of other proposals I would also like to mention a potential local component state provider API (see RFC #1979 ):

• provideNgxsComponentState(states: StateClass[])
• This would be used to provide state that is scoped to the current component and its children.
• This state is not accessible to any selectors created by a parent or sibling component.
• If the same state is provided in another part of the application then these states would be independent and not have any affect on each other.
• If the same state is provided in a child component then the child component state would override this state for all selectors at the level of the child component and its decendants. The parent component state would still be accessible outside that child component.

[kondelik]

I'm sure I'll use provideNgxs() in lazy loaded feature a few times before I get used to it. provideNgxsStates() sounds like it should be called after provideNgxs() in main.ts -- Maybe provideNgxsForFeature (and provideNgxsForComponent*) would be better?

*: I am not an expert on providers on component, but isnt that the same as providers on lazy-loaded route? So it should be provideNgxsForFeature() in both? I can be wrong.

[Carniatto]

+1 for having the config as a second argument to provideNgxs.

If you are proposing to have all the states added as lazy based only in the fact of when the module/component is loaded in the application, then that could be an interesting option.

However, if I'm declaring a state that will live only while a module/component is loaded, I'd expect this state to be no longer available after this module/component is destroyed.

If this is the case, might be better to allow users to have a explicitly way to declare states that are potentially short lived.

[joaqcid]

i think im leaning towards the following naming:

provideNgxs (called once in app bootstrap)
provideNgxsFooPlugin (called once in app bootstrap)
provideNgxsStates (called n times in features/lazy loaded routes)

I will say tho, that i also like addNgxsStates for features/lazy loaded routes. These names will map to the current APIs we have in place.

for local-component states, what about:

provideNgxsLocalStates
provideNgxsComponentStates

my thinking is that the word Local/Component would indicate that the state will only live will the component is alive

[arturovt]

We had a discussion with Mark regarding signatures of these APIs:

provideNgxs(states: StateClass[] = [], config?: NgxsConfig);
provideNgxsStates(states: StateClass[]);
provideNgxsPlugin(plugin: NgxsPlugin);

We had a thought that provideNgxs may only be called with the config, and all of the states are registered using provideNgxsStates. Thus, provideNgxs is only responsible for setting the Store up. But this is not backward compatible with the current implementation because it breaks the order of the executed code.

NGXS has internal actions InitState and UpdateState. InitState is always dispatched once when the NgxsModule.forRoot registers root states provided in forRoot. UpdateState is dispatched whenever any state is registered later.

These technical constraints require keeping backward compatible signatures of the standalone API. So provideNgxs signature looks similar to forRoot().

Those APIs will never be provided on the component level, which is guaranteed by types being returned by those APIs (EnvironemntProviders, which is not assignable to @Component({ providers })). The EnvironmentProviders type secures us from those APIs being used in places they should never be called in. The provideNgxs would have a guard checking the function has already been called (the guard will function only in development mode wrapped with ngDevMode).

Our plugins will expose functions because plugins rely on user provided configurations. That's why the signature of core NGXS plugins will be:

export function provideNgxsLoggerPlugin(config) {
  return makeEnvironmentProviders([
    { provide: NGXS_LOGGER_PLUGIN_OPTIONS, ....},
    provideNgxsPlugin(NgxsLoggerPlugin)
  ]);
}

Note: the provideNgxsPlugin is still required to keep the provider "schema", this obviates developers from writing the same provider signature every time they want to provide their plugins:

bootstrapApplication(..., {
  providers: [
    {
      provide: NGXS_PLUGINS,
      useClass: PLUGIN,
      multi: true
    },
    {
      provide: NGXS_PLUGINS,
      useClass: PLUGIN,
      multi: true
    },
    {
      provide: NGXS_PLUGINS,
      useClass: PLUGIN,
      multi: true
    },
    {
      provide: NGXS_PLUGINS,
      useClass: PLUGIN,
      multi: true
    }
  ]
});

I think we should have a minimal handshake agreed on namings (even tho namings are hard). Note: please let's NOT discuss the component state in this discussion because I'm worried about the cognitive overload 😄

---

UPD (July 26)

We have agreed to use the following namings and signatures:

function provideStore(
  states?: StateClass[],
  ...features: EnvironmentProviders[]
): EnvironmentProviders;

function provideStore(
  states?: StateClass[],
  options?: NgxsModuleOptions,
  ...features: EnvironmentProviders[]
): EnvironmentProviders;

function provideStates(
  states: StateClass[],
  ...features: EnvironmentProviders[]
): EnvironmentProviders;

Example:

provideStore(
  [TodosState],
  { developmentMode: !environment.production, selectorOptions: {} },
  withNgxsFormPlugin(),
  withNgxsLoggerPlugin({ logger: console, collapsed: false, disabled: true }),
  withNgxsReduxDevtoolsPlugin({ disabled: environment.production }),
  withNgxsRouterPlugin(),
  withNgxsStoragePlugin({ key: [TODOS_STORAGE_KEY] })
)

[markwhitfeld]

@arturovt Maybe one small note, I think that the provideNgxsPlugin function should be in a @ngxs/store/plugin subpackage, just so that it is clearer that this is an API intended for use by plugins.
The other plugin interfaces should be moved there too, but, in order to maintain backwards compatibility, they will still need to be exported from the main package (potentially with a deprecation comment to promote moving the reference to the plugin subpackage (this is already on the list for v4 changes (see #827 ).

PS. The type signature of provideNgxsPlugin should also expect the class reference, as opposed to an instance.