RFC: Add createComponentStore Function

[markostanimirovic]

The createComponentStore function will provide the ability to create a custom ComponentStore without using a "class-based" approach. Its usage would look like this:

// users.store.ts

import { createComponentStore } from '@ngrx/component-store';

interface State {
  users: User[];
  query: string;
}

const initialState: State = {
  users: [],
  query: '',
};

export const UsersStore = createComponentStore({
  initialState,
  factory({ select, effect, patchState, onInit }) {
    const usersService = inject(UsersService);

    // selectors
    const users$ = select((s) => s.users);
    const query$ = select((s) => s.query);
    const filteredUsers$ = select(
      users$,
      query$,
      (users, query) =>
        users.filter((user) => user.name.includes(query))
    );

    // effects
    const loadUsers = effect<string>(
      switchMap((query) => {
        return usersService.getByQuery(query).pipe(
          tapResponse({
            next: (users) => patchState({ users }),
            error: console.error,
          })
        );
      })
    );

    onInit(() => loadUsers(query$));

    return { filteredUsers$ };
  }
});

The created ComponentStore can be used in the same way as before:

// users.component.ts

import { UsersStore } from './users.store';

@Component({
  /* ... */
  providers: [UsersStore],
})
export class UsersComponent {
  private readonly usersStore = inject(UsersStore);
  readonly filteredUsers$ = this.usersStore.filteredUsers$;

  onQueryChange(query: string): void {
    this.usersStore.patchState({ query });
  }
}

Providing at the root level

With createComponentStore, providing at the root level can be done as follows:

export const UsersStore = createComponentStore({
  initialState,
  providedIn: 'root',
  factory() {
    /* ... */
  }
});

Scaling

If needed, we can split ComponentStore selectors, effects, and/or updaters into separate functions, so we can avoid huge ComponentStore factories:

export const UsersStore = createComponentStore({
  initialState,
  factory(helpers) {
    const { onInit } = helpers;
    const { query$, filteredUsers$ } = injectUsersSelectors(helpers);
    const { loadUsers } = injectUsersEffects(helpers);

    onInit(() => loadUsers(query$));

    return { filteredUsers$ };
  }
});

// selectors
function injectUsersSelectors({ select }: ComponentStoreHelpers<State>) {
  const users$ = select((s) => s.users);
  const query$ = select((s) => s.query);
  const filteredUsers$ = select(
    users$,
    query$,
    (users, query) =>
      users.filter((user) => user.name.includes(query))
  );

  return { users$, query$, filteredUsers$ };   
}

// effects
function injectUsersEffects({ effect, patchState }: ComponentStoreHelpers<State>) {
  const usersService = inject(UsersService);

  const loadUsers = effect<string>(
    switchMap((query) => {
      return usersService.getByQuery(query).pipe(
        tapResponse({
          next: (users) => patchState({ users }),
          error: console.error,
        })
      );
    })
  );

  return { loadUsers };
}

Benefits

• There are several community ComponentStore plugins - ImmerComponentStore, EntityComponentStore, etc. However, in JS/TS, a class can only extend one class by default and without additional hacks. What if we want to create a ComponentStore that reuses entity features but also has immer updaters? 🤔 With the createComponentStore function, I see the possibility of combining reusable features in a more flexible way.
• Easier scaling into multiple functions if needed. (See the "Scaling" section above)
• With the "class-based" approach, ComponentStores that use onStoreInit and/or onStateInit hooks must be provided by using the provideComponentStore function. This won't be necessary with the createComponentStore function.

Alternative createComponentStore signature

There is another createComponentStore signature worth considering:

const [provideUsersStore, injectUsersStore] = createComponentStore({
  initialState,
  factory() {
    /* ... */
  },
});

@Component({
  providers: [provideUsersStore()],
})
export class UsersComponent {
  readonly usersStore = injectUsersStore();
}

[e-oz]

What are the benefits in comparison to a class-based approach?

[markostanimirovic]

Good point! I updated RFC description:

• There are several community ComponentStore plugins - ImmerComponentStore, EntityComponentStore, etc. However, in JS/TS, a class can only extend one class by default and without additional hacks. What if we want to create a ComponentStore that reuses entity features but also has immer updaters? 🤔 With the createComponentStore function, I see the possibility of combining reusable features in a more flexible way.
• Easier scaling into multiple functions if needed. (See the section above)
• With the "class-based" approach, ComponentStores that use onStoreInit and/or onStateInit hooks must be provided by using the provideComponentStore function. This won't be necessary with the createComponentStore function.

I'd also like to hear your thoughts. 👀 What advantages/disadvantages do you see?

[e-oz]

1. If stores have methods/fields with the same name, they can not be merged anyway;

2. It's interesting. To be fair, it is possible to declare effects in separate files already, to handle huge monolith component stores (same way, by exporting functions). But it is a legit point, and maybe right now I just don't see the full potential, but I admit it might exist.

3. the same question as for (1), but if resolved - it is a good feature.

Sorry, I don't want to be skeptical, and in no way do I want to stop any of your contributions. Maybe in process of implementation, you’ll find easy solutions for the points I mentioned.

[markostanimirovic]

Thank you so much for your feedback @e-oz! Much appreciated.

This is far away from the final decision. I just wanted to share my idea publicly and get some feedback.

[tomalaforge]

Hi @markostanimirovic,

nice RFC. I see that you are trying to move everything to functional programming. But for this use case, I'm not seeing the benefits. I find it harder to read. With injectable class, you stay in the "angular way" of doing thing.

It can be very confusing to inject a function. Will feel even more magic.

[markostanimirovic]

Hi @tomalaforge 👋

I see that you are trying to move everything to functional programming.

No, I'm trying to solve the limitations I've faced with the "class-based" ComponentStore approach. I described them in the "Benefits" section:

• There are several community ComponentStore plugins - ImmerComponentStore, EntityComponentStore, etc. However, in JS/TS, a class can only extend one class by default and without additional hacks. What if we want to create a ComponentStore that reuses entity features but also has immer updaters? 🤔 With the createComponentStore function, I see the possibility of combining reusable features in a more flexible way.
• Easier scaling into multiple functions if needed. (See the section above)
• With the "class-based" approach, ComponentStores that use onStoreInit and/or onStateInit hooks must be provided by using the provideComponentStore function. This won't be necessary with the createComponentStore function.

---

But for this use case, I'm not seeing the benefits. I find it harder to read.

It doesn't seem unreadable to me compared to the ComponentStore class, but that's probably a preference. Do you see any other drawbacks? 👀

With injectable class, you stay in the "angular way" of doing thing.

I'm wondering what will be the "Angular way" in upcoming versions. 🤔

It can be very confusing to inject a function. Will feel even more magic.

No, not a function. The createComponentStore result would be the ComponentStore class that contains the factory result. Take a look at the example above. The result could also be an InjectionToken.

I was also considering the following signature:

const [provideUsersStore, injectUsersStore] = createComponentStore({
  initialState,
  factory() {
    /* ... */
  },
});

@Component({
  providers: [provideUsersStore()],
})
export class UsersComponent {
  readonly usersStore = injectUsersStore();
}

[KevTale]

Looks very cool!

Could it be used like so as well?

@Component({...})
export class UsersComponent {

  readonly store = inject(createComponentStore({
    initialState,
    factory() {...},
  });

}

So we can have a single file feature similar to what other frameworks provide.

[markostanimirovic]

Hey @KevTale 👋

Component and ComponentStore can be created in the same file. However, I would still use createComponentStore outside the component class:

// file: users.component.ts

const UsersStore = createComponentStore({
  initialState,
  factory() { /* ... */ },
})

@Component({
  // 👇 note that created store needs to be provided
  // because it's not provided anywhere by default
  providers: [UsersStore],
})
export class UsersComponent {
  readonly store = inject(UsersStore);
}

[sg-gdarnell]

The class-based api allows for the initial state itself to be injected and/or instantiated lazily. This proposal requires the initial state as the first parameter, which seems to imply that it would have to be known statically, unless you called this function inside a provider factory of your own. I don't personally have a use case that requires this functionality, so that would be fine with me, but I noticed it. I assume it's structured this way so that the type can be inferred, which is nice.

Also, I'd prefer the first return type to the alternative that returns a tuple. Getting the class or injection token or whatever it is back is more flexible, and the helper functions could always be done in userland.

[markostanimirovic]

Thanks for the feedback @sg-gdarnell!

ComponentStore's state could be initialized lazily by excluding the initialState property:

export const FooStore = createComponentStore({
  providedIn: 'root',
  factory() { /* ... */ }
});

or we can add another signature that accepts a factory function like this:

export const FooStore = createComponentStore((/* ... */) => {
  /* ... */
});

---

We can also provide the ability to pass the InjectionToken reference for the initial state. However, I don't see any benefit from this feature. Do you have an example where using InjectionToken for the initial state could be useful?

For the ComponentStore class, InjectionToken is needed to avoid NullInjectorError when we want to inject ComponentStore directly:

import { ComponentStore } from '@ngrx/component-store';

@Component({
  providers: [ComponentStore],
})
export class MyComponent {
  readonly cs = inject(ComponentStore);
}

Without @Optional() @Inject(INITIAL_STATE_TOKEN) defaultState?: T in the ComponentStore constructor, Angular wouldn't know how to resolve the constructor param defaultState and would throw NullInjectorError.

[sg-gdarnell]

We can also provide the ability to pass the InjectionToken reference for the initial state. However, I don't see any benefit from this feature. Do you have an example where using InjectionToken for the initial state could be useful?

Thanks for your response! To be clear, I think this is a nice improvement to DX, and I could definitely use the improved composability to reduce code duplication in my code. I've got a handful of base classes that extend ComponentStore today and I can see how this API would simplify them.

That said, I misread the initial proposal and thought that the proposed syntax was createComponentStore(initialState, { factory: () => {...} }) instead of createComponentStore({ initialState, factory: () => {...} }), which made me think the initial state was a required parameter. If it was a required parameter, it would create the problems I described, but since it's not, I think you can ignore my feedback. With lazily-initialized state, you could initialize with DI if you wanted to, like this:

const MyComponentStore = createComponentStore<{ value: any }>({
  factory: ({ patchState }) => {
    // initialize from DI
    patchState({ value: inject(SOME_INJECTION_TOKEN) });

    // etc.
  }
});

I'm struggling to come up with a reasonable use case for wanting to do this, I was just kinda thinking out loud about parity between the class-based API and the functional API.

[timdeschryver]

I like it, the only nit I have is the onInit hook.
As we've discussed, perhaps it would be better to keep onStoreInit and onStateInit as we have now.
Or, to rename onInit to onStoreInit.