Announcing NGXS 3.7

markwhitfeld — Wed, 09 Sep 2020 07:06:35 +0000

2020 has definitely been a year of ups and downs! As open source maintainers, the shock out of normality has definitely brought its challenges... with work invading the home, family invading work, and every last drop of our day being caught up in the chaos.

This update has been a long time in the making, with lengthy discussions around each new feature, and great efforts to ensure the stability and backward compatibility of the library and API, following the big changes in Angular and in TypeScript this year.

Thank you to our incredible community for your ongoing contributions, enthusiasm, and support!

Now, let's get to the release...

Overview

🚀 Official Angular 10 Support
🛑 Improved Error Messages
🐛 Bug Fixes
🔌 Plugin Improvements and Fixes

Official Angular 10 Support

Angular 10 brought many behind the scenes improvements to the library we all know and love. Updates to the underlying tooling, upgrades to versions of library dependencies (TypeScript, etc.), and further improvements to Ivy and bundle sizes.

The day that Angular 10 was released, we were ready to announce to the world that we fully supported the new version... but alas we discovered that Angular 10 had issues with HMR.

The @ngxs/store library and all of the other plugins supported Angular 10 out of the box, but the HMR plugin was not so lucky. Our commitment to the stability of the library extends to all of the core plugins, including the HMR plugin.

We tried to work around the issue, but unfortunately, there was nothing we could do and the issue wasn't receiving much attention from the Angular team. As a result, we have decided to deprecate the HRM plugin. More on this later...

Improved Error Messages

Sometimes a developer can miss something small in their app that can result in obtuse and hard to debug issues. We have improved some of our error detection and messaging in order to give better feedback to the developer about where they may have gone wrong.

Here are some of the scenarios that we covered:

Empty `type` Property on Action (PR #1625)

For example, if you define an action that has a type property but its value is not set, then typescript is happy and the app compiles, but the action handlers cannot correctly determine the type of action.

Now you will receive a convenient message notifying you of the action that has an empty type property.

Incorrect Arguments for `ofAction*` operator (PR #1616)

The ofAction* pipeable operators previously had a pretty open typings for the argument definition. We have improved this typing so that it only accepts valid action types.

Bug Fixes

Relax `@Select` type check (PR #1623)

In NGXS v3.6 we added a typescript trick that would show an error if the declared type of the variable decorated by the @Select decorator didn't match the type of the selector referenced by the decorator. Unfortunately, this prevented the use of this decorator with private or protected fields. Due to this being a regression over NGXS v3.5, we reverted this change.

Handle Empty Observables Correctly (PR #1615)

Previously, if an observable returned from an @Action function completed without emitting any values then this would be seen as a cancellation. This type of returned observable is entirely valid, and therefore we adjusted the internal processing of observables to accept an empty observable as a valid completion scenario.

Plugin Improvements

Logger Plugin

Feature: Action Filter in Logger Plugin (PR #1571)

The logger plugin did not have an option to ignore specific actions. It either logged every action or, when disabled, did not log any action at all. However, you may need logging actions conditionally because of several reasons like:

Some actions are not your focus and logging them as well makes it hard to find what you are actually working on.
Some actions are simply fired too often and the console becomes cumbersome.
You want to log an action only when there is a certain state.

With this version, the forRoot method of the NgxsLoggerPluginModule takes a filter option, which is a predicate that defines the actions to be logged. Here is a simple example:

import { NgxsModule, getActionTypeFromInstance } from '@ngxs/store';
import { NgxsLoggerPluginModule } from '@ngxs/logger-plugin';
import { SomeAction } from './path/to/some/action';

@NgModule({
  imports: [
    NgxsModule.forRoot([]),
    NgxsLoggerPluginModule.forRoot({
      filter: action => getActionTypeFromInstance(action) !== SomeAction.type
    })
  ]
})
export class AppModule {}

In this example, the SomeAction action will not be logged, because the predicate returns false for it. You may pass more complicated prediactes if you want and even make use of current state snapshot in your predicates:

import { NgxsModule, getActionTypeFromInstance } from '@ngxs/store';
import { NgxsLoggerPluginModule } from '@ngxs/logger-plugin';
import { SomeAction } from './path/to/some/action';

@NgModule({
  imports: [
    NgxsModule.forRoot([]),
    NgxsLoggerPluginModule.forRoot({
      filter: (action, state) =>
        getActionTypeFromInstance(action) === SomeAction.type && state.foo === 'bar'
    })
  ]
})
export class AppModule {}

The predicate given in this example lets you log only SomeAction and only when foo state is equal to 'bar'. This makes it easier to pinpoint a dispatched action while debugging it.

Important Note: The predicate will be called for every action. This may cause performance issues in development, especially when you are planning to keep the predicate after debugging. Therefore, please consider using a memoized function for filters more complicated than a simple action comparison. You may take advantage of memoization libraries for that.

Storage Plugin

Feature: Serialization Interceptors in Storage Plugin (PR #1513)

You can define your own logic before or after the state get serialized or deserialized.

beforeSerialize: Use this option to alter the state before it gets serialized.
afterSerialize: Use this option to alter the state after it gets deserialized. For instance, you can use it to instantiate a concrete class.

@NgModule({
  imports: [
    NgxsStoragePluginModule.forRoot({
      key: 'counter',
      beforeSerialize: (obj, key) => {
        if (key === 'counter') {
          return {
            count: obj.count < 10 ? obj.count : 10
          };
        }
        return obj;
      },
      afterDeserialize: (obj, key) => {
        if (key === 'counter') {
          return new CounterInfoStateModel(obj.count);
        }
        return obj;
      }
    })
  ]
})
export class AppModule {}

Form Plugin

Feature: Reset Form Action (PR #1604)

You can reset the form with the ResetForm action.

This action resets the form and related form state.
The form status, dirty, values, etc. will be reset by related form values after calling this action.

Example:

<form [formGroup]="form" ngxsForm="exampleState.form">
  <input formControlName="text" /> <button type="submit">Add todo</button>

  <button (click)="resetForm()">Reset Form</button>
  <button (click)="resetFormWithValue()">Reset Form With Value</button>
</form>

@Component({...})
class FormExampleComponent {
  public form = new FormGroup({
    text: new FormControl(),
  });

  constructor(private store: Store) {}

  resetForm() {
    this.store.dispatch(new ResetForm({ path: 'exampleState.form' }));
  }

  resetFormWithValue() {
    this.store.dispatch(
      new ResetForm({
        path: 'exampleState.form',
        value: {
          text: 'Default Text',
        },
      }),
    );
  }
}

Improvement: Simplify `ngxsFormClearOnDestroy` Attribute (PR #1662)

The ngxsFormClearOnDestroy attribute previously required its declaration on the form element to be exactly [ngxsFormClearOnDestroy]="true" to work.
Since this is a simple boolean attribute, the mere presence of the attribute on the form element should imply the behavior. We have improved this attribute to recognize all valid forms of specification.

For example, you can now just include the attribute like this:

<form [formGroup]="form" ngxsFormClearOnDestroy ngxsForm="exampleState.form">
  <input formControlName="text" />
</form>

@Component({...})
class FormExampleComponent {
  public form = new FormGroup({
    text: new FormControl(),
  });

  constructor(private store: Store) {}  
}

This form will be cleared once the component is destroyed. Win!

HMR Plugin

Deprecation

As mentioned above, Angular 10 has issues with HMR, and these issues prevented us from announcing official support from day 1.

After many attempts to get it working again, we admitted defeat and had to make some hard decisions. After consulting with the community, we have decided to deprecate the HMR plugin until there is official Angular support for the HMR paradigm again. This goes against some of our fundamental philosophies that make the NGXS ecosystem such a reliable choice for your application, but in this case, we are forced by things that are outside of our control.

Here is our poll to the community on our slack channel:

The results were the following:

💥 73% voted in favor of dropping the HMR plugin
🙏 2% voted to keep the plugin
🤷‍♀️ 25% didn't mind either way

Upon discussion with the 2%, they were not aware that the storage plugin could be used to gain an almost identical experience and then supported the deprecation too. We have included details about this workaround in our docs.

Some Useful Links

If you would like any further information on changes in this release please feel free to have a look at our changelog. The code for NGXS is all available at https://github.com/ngxs/store and our docs are available at http://ngxs.io/. We have a thriving community on our slack channel so come and join us to keep abreast of the latest developments. Here is the slack invitation link.

11 Reasons why you should use NGXS as State Management in your Angular apps

Lex Kuncevic — Sat, 01 Aug 2020 12:32:09 +0000

Developers tend to use state management solutions to solve some common problems developing modern single page applications. Building a modern web application using Angular you might not need to opt-in for a state management solution right away (it depends) but when the day comes NGXS is your best choice and here is why.

Why you should choose NGXS:

Bulletproofed: NGXS was built back in Feb 2018. Since then, for many years, it has been chosen by many dev teams and companies as a state management solution for their Angular apps. Now there are 3.4+ million npm downloads to date!
Backed by an awesome team: NGXS is an open source project maintained by a team of great software engineers from across the globe with a combined experience of 80+ years in software development.
Angular way: NGXS written by Angular devs and for Angular devs. As a result, your store-related code uses a more familiar Angular approach that leverages dependency injection, decorators, etc.
Great Features: There are many awesome features that NGXS offers: component communication, state operators, selectors and much more.
Plugins: NGXS has a plugin system built-in - it is similar to Redux's meta reducers. You can use existing plugins to extend the functionality on top of your store or you can build your own plugin. Plugins that NGXS offering you: Logger, Devtools, Storage, Forms, Web Socket, Router and more!
Less Boilerplate: NGXS was originally invented in response to the complexity and amount of boilerplate present in other state management solutions.
Backwards Compatibility: NGXS team very strongly stands for backwards compatibility so by migrating to a new version of NGXS you can be assured that your codebase won’t require significant changes as part of the upgrade.
Consistency and Maintainability: In practice it is much easier to maintain applications that build with the same fashion. When you use NGXS it gives your code a place to live and common patterns will emerge that will make for a much more maintainable codebase.
Documentation: NGXS has a great documentation at NGXS.io in addition to that you can find some blog posts about NGXS on medium blog.
Community: The NGXS community is strong, you can join NGXS slack channel if you have any questions or if you want to discuss anything or just to say hello.
NGXS labs: NGXS labs is an organization on github - the place to test out the new ideas and to play around and experiment with new cool features and new plugins that are not yet under the main NGXS organisation. Here is the list of the additional features and plugins currently available at NGXS labs:

      - Data - NGXS Persistence API
      - Emitter - provides the opportunity to feel free from actions
      - Immer adapter - declarative state mutations
      - Dispatch decorator - provide separation of concern between the state management and the view
      - Select snapshot - decorator that allows to get a snapshot of the state
      - Async storage plugin - async Storage Plugin
      - Entity state - entity adapter
      - Actions executing - notifies if action is being executed
      - Attach action - attaching independent, pure and easy to test Action Handlers to NGXS State
      - Firestore plugin - firestore plugin for NGXS

So as you can see there are lots of reasons why you may want to consider NGXS as a state management solution for your Angular applications. To get started check up the documentation at ngxs.io and if you have any questions you can join the slack channel to discuss or just comment below.

My name is Aliaksei Kuncevič. I am teaching Angular and Web Technology. Helping dev teams to adopt Angular in the most efficient way. GDE, member of the NGXS Core Team.

I hope you find this content helpful and if so, please help to spread this article so more people can benefit from it.

If you want to learn more Angular tips and tricks join my newsletter at kuncevic.dev

If you want to know more about Angular subscribe for Angular Rocks podcast 🎙

DEV Community: Ngxs