feat(component-store): add OnStoreInit and OnStateInit lifecycle hooks

[brandonroberts]

PR Checklist

Please check if your PR fulfills the following requirements:

• The commit message follows our guidelines: https://github.com/ngrx/platform/blob/master/CONTRIBUTING.md#commit
• Tests for the changes have been added (for bug fixes / features)
• Documentation has been added / updated (for bug fixes / features)

PR Type

What kind of change does this PR introduce?

[ ] Bugfix
[x] Feature
[ ] Code style update (formatting, local variables)
[ ] Refactoring (no functional changes, no api changes)
[ ] Build related changes
[ ] CI related changes
[ ] Documentation content changes
[ ] Other... Please describe:

What is the current behavior?

Closes #3335

What is the new behavior?

Adds two new lifecycle hooks to ComponentStore along with their respective interfaces

• OnStoreInit - is called after the store is created
  • This method throws an error when trying to access the .get() method because the state hasn't been set, even if done eagerly.
• OnStateInit - is called after the state is initialized

Adds a new exported function provideComponentStore(ComponentStore) that is used to provide the ComponentStore, instantiate it, and run the lifecycle hooks if defined

import { Injectable } from '@angular/core';
import {
  ComponentStore,
  OnStateInit,
  OnStoreInit,
} from '@ngrx/component-store';

@Injectable()
export class LoginPageStore
  extends ComponentStore<{ test: boolean }>
  implements OnStoreInit, OnStateInit
{
  constructor() {
    super({ test: false });
  }

  ngrxOnStoreInit() {
    console.log('store init');
  }

  ngrxOnStateInit() {
    console.log('state init', this.get());
  }
}

Does this PR introduce a breaking change?

[ ] Yes
[x] No

Other information

• Example App changes are only used for reference and will be reverted

[netlify]

✅ Deploy Preview for ngrx-io ready!

Name	Link
🔨 Latest commit	e7ac13e
🔍 Latest deploy log	https://app.netlify.com/sites/ngrx-io/deploys/626ee527d9c09a000960db7f
😎 Deploy Preview	https://deploy-preview-3368--ngrx-io.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[LayZeeDK]

suggestion: consider a different name:

• triggerInitStoreEvent
• callInitStoreHook

[brandonroberts]

Good suggestions

[LayZeeDK]

issue: cover OnStateInit and OnStoreInit hooks with tests

[brandonroberts]

Agreed. This was for testing example code

[brandonroberts]

Code is refactored, tests are updated and green. I do have some concerns about the feature in general though. Because we are chaining off the constructor of the ComponentStore, it forces us or the developer to consider workarounds to use it effectively.

Consider the example below:

import { Injectable } from '@angular/core';
import {
  ComponentStore,
  OnStateInit,
  OnStoreInit,
} from '@ngrx/component-store';
import { delay, of, tap } from 'rxjs';

@Injectable()
export class LoginPageStore
  extends ComponentStore<{ test: boolean }>
  implements OnStoreInit, OnStateInit
{
  props = [];
  constructor() {
    super();
  }

  logEffect = this.effect(
    tap<void>(() => {
      console.log('effect');
    })
  );

  ngrxOnStoreInit() {
    this.logEffect(); // doesn't work because constructor isn't done
    console.log(this.props); // undefined
  }

  ngrxOnStateInit() {
    console.log('state init', this.get()); // works
    this.logEffect(); // blows up
  }
}

The examples below work

import { Injectable } from '@angular/core';
import {
  ComponentStore,
  OnStateInit,
  OnStoreInit,
} from '@ngrx/component-store';
import { delay, of, tap } from 'rxjs';

@Injectable()
export class LoginPageStore
  extends ComponentStore<{ test: boolean }>
  implements OnStoreInit, OnStateInit
{
props = []
  constructor() {
    super();
  }

  logEffect = this.effect(
    tap<void>(() => {
      console.log('effect');
    })
  );

  ngrxOnStoreInit() {
    of(null)
      .pipe(delay(0))
      .subscribe(() => {
        console.log('store init');
        console.log(this.props); // empty array
        this.logEffect(); // works
      });
  }

  ngrxOnStateInit() {
    setTimeout(() => {
      console.log('state init', this.get()); // works
      this.logEffect();
    });
  }
}

From my understanding, setTimeout is a macrotask that gets pushed into the queue, running on the next "tick" which allows it to run successfully. It would put the responsibility on the developer to run the code inside the hooks in a way that doesn't break. I'm open to other suggestions also internally we could make to make it more predictable without introducing race conditions.

If Angular had some sort of ELEMENT_INITIALIZER token, similar to the INJECTOR_INITIALIZER being introduced with standalone components, we could hook into that to run the hooks after instantiation, but no such thing exists today.

@aokrushk @markostanimirovic @timdeschryver @nartc

[markostanimirovic]

Hoisting 😳 The behavior could be very confusing for users.

This will work for component stores that are explicitly provided in components, modules, or route config:

const WITH_HOOKS = new InjectionToken<ComponentStore<any>[]>(
  '@ngrx/component-store: ComponentStores with Hooks'
);

export function provideWithHooks(
  componentStoreClass: Type<ComponentStore<any>>
) {
  return [
    { provide: WITH_HOOKS, multi: true, useClass: componentStoreClass },
    {
      provide: componentStoreClass,
      useFactory: () => {
        const componentStore = inject(WITH_HOOKS).pop();

        if (isOnStoreInitDefined(componentStore)) {
          componentStore.ngrxOnStoreInit();
        }

        if (isOnStateInitDefined(componentStore)) {
          componentStore.state$
            .pipe(take(1), takeUntil(componentStore.destroy$))
            .subscribe(() => componentStore.ngrxOnStateInit());
        }

        return componentStore;
      },
    },
  ];
}

Example:

@Injectable()
class LifecycleStore
  extends ComponentStore<LifeCycle>
  implements OnStoreInit, OnStateInit
{
  constructor() {
    super({ init: true });

    console.log('constructor');
    this.logEffect('constructor effect');
  }

  logEffect = this.effect(
    tap<string>((message) => {
      console.log(message);
    })
  );

  ngrxOnStoreInit(): void {
    console.log('onStoreInit');
    this.logEffect('store init effect');
  };

  ngrxOnStateInit(): void {
    console.log('onStateInit');
    this.logEffect('state init effect');
  }
}

@Component({
  providers: [provideWithHooks(LifecycleStore)]
})
export class AppComponent {
  constructor(private readonly lifecycleStore: LifecycleStore) {}
}

// console:
// constructor
// constructor effect
// onStoreInit
// store init effect
// onStateInit
// state init effect

[brandonroberts]

Nice, I thought of adding a type of provideComponentStore function also, but didn't think about using inject. I think it works for the primary use case, and if you want to use the providedIn you understand that restriction.

[brandonroberts]

I refactored the logic for the init checks to run after the constructor is complete, so the additional token isn't required and it runs consistently whether it's in providers or uses providedIn.

[markostanimirovic]

LGTM 🎉 The only thing I would change is not to expose isStoreInitDefined and isStateInitDefined guards to the public API.

[alex-okrushko]

Suggested change

	const CS_WITH_HOOKS = new InjectionToken<ComponentStore<any>>(
	const CS_WITH_HOOKS = new InjectionToken<ComponentStore<unknown>>(

[nartc]

I think unknown will fail extends object constraint on ComponentStore generics. If we want to absolutely avoid any, I think {} would do it?

[alex-okrushko]

yeah, {} or <object>. Just not any :)

[brandonroberts]

👍

[timdeschryver]

LGTM (again 😅)
Should we document somewhere why it's done like this instead of "just" adding the hooks to the Store class? (or will this be a part of the docs?).

[brandonroberts]

@timdeschryver yes, I'm going to add a docs page in a follow-up PR. We're also looking at adding a warning if the lifecycle hooks are defined but it wasn't provided through the function.