Best practice for extending withEntities with more reuseable array features (e.g. building a generic filter feature?)

[Donnerstagnacht]

Does a best practice exist how to extend the withEntities store?

I would like to build a generic feature/custom feature/withFeature which I can use to filter the entites stored in a named withEntities store.

The requirements would be similiar to:

1. access the stored withEntities
2. filter the entites of the withEntites store by a specified property (for example I have a entities of type user including a property name and I would like to filter by that name/string)
3. provide the filtered entities as a signal

I am not sure if extension is the correct phrase. Probably it is more an extension. In a best case scenario, I would wish that, the consuming store would look like this:

import { computed } from '@angular/core';
import { signalStore } from '@ngrx/signals';
import { withEntities } from '@ngrx/signals/entities';
import {withFilterByString} from '<local_path>';

type User= {
  id: number;
  name: string;
};

export const UsersStore= signalStore(
  withEntities<User>(),
  withFilterByString<'name'>(),
);

Since I believe processing entities is a common use case, I wanted to ask if someone can provide a related example, a guide, documentation or code snippet?

---

My approach so far is (and I think it works for EntityStores)

Use entittyMap in the featureStore():

export type Todo = {
  id: number;
  text: string;
  completed: boolean;
};

export type StoreState = {
  state: boolean;
};

export const initialState: StoreState = {
  state: false,
};

export const TodosStore = signalStore(
  withEntities<Todo>(),
  withState<StoreState>(initialState),
  withStateExtension(),
  withEntityExtension(),
  withMethods((store) => ({
    test(): void {
      const todos = store.entities();
      const storeState = store.state();

      const todosExtended = store.extendEntities();
      const storeStateExtended = store.extendState();
      store.logAllTodosFromMap();
    },
  }))
);

export function withEntityExtension() {
  return signalStoreFeature(
    {
      //state: type<{ entities: Todo[] }>(),
      state: type<{ entityMap: EntityMap<Todo> }>(),
    },
    withMethods((store) => ({
      extendEntities(): void {
        // const entities_extended = store.entities();
        const entityMap_extended = store.entityMap();
      },
      logAllTodosFromMap(): void {
        const entityMap = store.entityMap();
        Object.values(entityMap).forEach((todo) => {
          console.log(`Todo ID: ${todo.id}, Text: ${todo.text}`);
        });
      },
    }))
  );
}

export function withStateExtension() {
  return signalStoreFeature(
    {
      state: type<{ state: boolean }>(),
    },
    withMethods((store) => ({
      extendState(): void {
        const state_extended = store.state();
      },
    }))
  );
}

But if I want to use a named store, it does not work anymore. Are the named signals state properties or computed?

export type TodoNamed = {
  todo_id: number;
  text: string;
  completed: boolean;
};

const todoConfig = entityConfig({
  entity: type<TodoNamed>(),
  collection: 'todos',
  selectId: (todo) => todo.todo_id,
});

export const NamedTodosStore = signalStore(
  withEntities(todoConfig),
  withState<StoreState>(initialState),
  withStateExtension(),
  withEntityExtension2(),
  withMethods((store) => ({
    test(): void {
      const todos = store.todosEntities();
      const storeState = store.state();

      const todosExtended = store.extendEntities();
      const storeStateExtended = store.extendState();
    },
  }))
);

export function withEntityExtension2() {
  return signalStoreFeature(
    {
      //state: type<{ entities: TodoNamed[] }>(), //type error
      //state: type<{ todosEntityMap: EntityMap<TodoNamed> }>(), //type error
      state: type<{ todosEntityMap: NamedEntityState<TodoNamed, 'todos'> }>(), //type error
    },
    withMethods((store) => ({
      extendEntities(): void {
        // const entities_extended = store.entities();
        const entityMap_extended = store.todosEntityMap();
      },
    }))
  );
}

I think it would be helpful for most developers to extend the input docs with a section how to access withEntity properties (e.g. use them as input in feature stores) or extend the entity docs with a guide how to extend named entities. I think it would be good to add more documentation about the difference between maps and computed signals (thats a big difference here, isn't it?) in this context.

[rainerhahnekamp]

If I would write an extension, then the extension would also call withEntities and not depend on it.

I hope that I didn't miss it, but in your example I didn't see a single one where you called withEntities in signalStoreFeature. Is there a reason for that?

[Donnerstagnacht]

I thought I would keep it "modular" - but not sure if there is a better way - that is why I was asking for "best practices".

I thought, if I would add withEntitites to the featureStore, I would have to add all features to that one featureStore (else wise I need to access withEntities of that feature store). Over time, this could become very massive but there might be use cases in which I only require a set features.

I guess my idea is to have generic features that receive an array store, e.g. withEntities(), and then add other array features like filterByString, select, insert... If I would phrase it, I would even write "the feature store depends on an array, e.g. withEntities".

As far as I undertstand the design of including withEntities to the featureStore, it would require to create one massive extendedWithEntitiesStore which holds all features and this store must be used everywhere, even in most cases I only need a set of methods from this store. Second, if I understand it correct, it may require identical property names.

For example:

type User= {
  id: number;
  name: string;
};

type Concert= {
  id: number;
  name: string;
  price: number
};

export const UsersStore= signalStore(
  withEntitiesExtended<User>(), // is this even possible because users does not hold property price?
);

export const ConcertsStore= signalStore(
  withEntitiesExtended<Concert>>(),
);

export const UsersStore= signalStore(
  withEntities<User>(),
  withEntitiesFilterByString<'name'>(),
);

export const ConcertsStore= signalStore(
  withEntities<Concert>(),
  withEntitySelected<'id'>(),
  withEntitiesSortByNumber<'price')>()
);

Probably, my question was to narrow. What would be the best way to add additional and reuseable array features based on the exisiting withEntities? Is there a better concept? Isn't trying to combine the input feature with withEntities a valid approach?

[Donnerstagnacht]

So this is my best result until now.
As far as I can say, I can

1. reuse it flexible
2. chain it with other filters that overwrite the entities computed signal
3. have full type support

What do you think @rainerhahnekamp ?

I was not able to make it work for

1. named entities
2. the entityConfig object (not sure what happens with custom identifiers)

Is it save to "overwrite" the computed entities signal like this? What I like about this approach is, that the store consuming ui-components would not even notify that a filter was plugged out or in (at least if I refactor the updateFilterString method to its own feature store).

export type FilterState = {
  filterString: string | undefined;
};

export const initialFilterState: FilterState = {
  filterString: undefined,
};

export function withFilterByString<
  T extends Record<string, any>,
  K extends keyof T & string
>(filterKeys: K[]) {
  return signalStoreFeature(
    {
      state: type<{ entityMap: EntityMap<T> }>(),
    },

    withState<FilterState>(initialFilterState),

    withComputed((store) => ({
      entities: computed(() => {
        const entityMap = store.entityMap();
        const entities = Object.values(entityMap);
        const filterString = store.filterString();

        if (!entities || entities.length === 0 || !filterString) {
          return entities;
        }

        return entities.filter((entity) => {
          const searchableTextFields = filterKeys
            .map((key) => String(entity[key]))
            .join(' ')
            .toLowerCase();
          const filterResults = searchableTextFields.includes(
            filterString.toLowerCase()
          );
          console.log(filterResults);
          return filterResults;
        });
      }),
    })),

    withMethods((store) => ({
      updateFilterString(filterString: string) {
        patchState(store, { filterString: filterString });
        console.log(store.filterString());
      },
      clearFilter() {
        patchState(store, { filterString: undefined });
      },
    }))
  );
}

Then I can use it flexible and can even chain it with other featureFilters which overwrite entities. The filter keys are fully typed.

export const ProfileFollowerStore = signalStore(
  {
    providedIn: 'root',
  },
  withLoadingStore(),
  withAlertStore(),
  withEntities<Follower>(),
  withFilterByString<Follower, 'first_name' | 'last_name'>([
    'first_name',
    'last_name',
  ]),

  withMethods(
  // ...
  )
)