@angular-architects/ngrx-toolkit 20.0.1 → 20.0.2

package/src/lib/with-data-service.ts

@@ -0,0 +1,433 @@
+import { ProviderToken, Signal, computed, inject } from '@angular/core';
+import {
+  EmptyFeatureResult,
+  SignalStoreFeature,
+  WritableStateSource,
+  patchState,
+  signalStoreFeature,
+  withComputed,
+  withMethods,
+  withState,
+} from '@ngrx/signals';
+import {
+  EntityId,
+  NamedEntityState,
+  addEntity,
+  removeEntity,
+  setAllEntities,
+  updateEntity,
+} from '@ngrx/signals/entities';
+import { EntityState } from './shared/signal-store-models';
+import {
+  CallState,
+  NamedCallStateSlice,
+  getCallStateKeys,
+  setError,
+  setLoaded,
+  setLoading,
+} from './with-call-state';
+
+export type Filter = Record<string, unknown>;
+export type Entity = { id: EntityId };
+
+export interface DataService<E extends Entity, F extends Filter> {
+  load(filter: F): Promise<E[]>;
+
+  loadById(id: EntityId): Promise<E>;
+
+  create(entity: E): Promise<E>;
+
+  update(entity: E): Promise<E>;
+
+  updateAll(entity: E[]): Promise<E[]>;
+
+  delete(entity: E): Promise<void>;
+}
+
+export function capitalize(str: string): string {
+  return str ? str[0].toUpperCase() + str.substring(1) : str;
+}
+
+export function getDataServiceKeys(options: { collection?: string }) {
+  const filterKey = options.collection
+    ? `${options.collection}Filter`
+    : 'filter';
+  const selectedIdsKey = options.collection
+    ? `selected${capitalize(options.collection)}Ids`
+    : 'selectedIds';
+  const selectedEntitiesKey = options.collection
+    ? `selected${capitalize(options.collection)}Entities`
+    : 'selectedEntities';
+
+  const updateFilterKey = options.collection
+    ? `update${capitalize(options.collection)}Filter`
+    : 'updateFilter';
+  const updateSelectedKey = options.collection
+    ? `updateSelected${capitalize(options.collection)}Entities`
+    : 'updateSelected';
+  const loadKey = options.collection
+    ? `load${capitalize(options.collection)}Entities`
+    : 'load';
+
+  const currentKey = options.collection
+    ? `current${capitalize(options.collection)}`
+    : 'current';
+  const loadByIdKey = options.collection
+    ? `load${capitalize(options.collection)}ById`
+    : 'loadById';
+  const setCurrentKey = options.collection
+    ? `setCurrent${capitalize(options.collection)}`
+    : 'setCurrent';
+  const createKey = options.collection
+    ? `create${capitalize(options.collection)}`
+    : 'create';
+  const updateKey = options.collection
+    ? `update${capitalize(options.collection)}`
+    : 'update';
+  const updateAllKey = options.collection
+    ? `updateAll${capitalize(options.collection)}`
+    : 'updateAll';
+  const deleteKey = options.collection
+    ? `delete${capitalize(options.collection)}`
+    : 'delete';
+
+  // TODO: Take these from @ngrx/signals/entities, when they are exported
+  const entitiesKey = options.collection
+    ? `${options.collection}Entities`
+    : 'entities';
+  const entityMapKey = options.collection
+    ? `${options.collection}EntityMap`
+    : 'entityMap';
+  const idsKey = options.collection ? `${options.collection}Ids` : 'ids';
+
+  return {
+    filterKey,
+    selectedIdsKey,
+    selectedEntitiesKey,
+    updateFilterKey,
+    updateSelectedKey,
+    loadKey,
+    entitiesKey,
+    entityMapKey,
+    idsKey,
+
+    currentKey,
+    loadByIdKey,
+    setCurrentKey,
+    createKey,
+    updateKey,
+    updateAllKey,
+    deleteKey,
+  };
+}
+
+export type NamedDataServiceState<
+  E extends Entity,
+  F extends Filter,
+  Collection extends string,
+> = {
+  [K in Collection as `${K}Filter`]: F;
+} & {
+  [K in Collection as `selected${Capitalize<K>}Ids`]: Record<EntityId, boolean>;
+} & {
+  [K in Collection as `current${Capitalize<K>}`]: E;
+};
+
+export type DataServiceState<E extends Entity, F extends Filter> = {
+  filter: F;
+  selectedIds: Record<EntityId, boolean>;
+  current: E;
+};
+
+export type DataServiceComputed<E extends Entity> = {
+  selectedEntities: Signal<E[]>;
+};
+
+export type NamedDataServiceComputed<
+  E extends Entity,
+  Collection extends string,
+> = {
+  [K in Collection as `selected${Capitalize<K>}Entities`]: Signal<E[]>;
+};
+
+export type NamedDataServiceMethods<
+  E extends Entity,
+  F extends Filter,
+  Collection extends string,
+> = {
+  [K in Collection as `update${Capitalize<K>}Filter`]: (filter: F) => void;
+} & {
+  [K in Collection as `updateSelected${Capitalize<K>}Entities`]: (
+    id: EntityId,
+    selected: boolean,
+  ) => void;
+} & {
+  [K in Collection as `load${Capitalize<K>}Entities`]: () => Promise<void>;
+} & {
+  [K in Collection as `setCurrent${Capitalize<K>}`]: (entity: E) => void;
+} & {
+  [K in Collection as `load${Capitalize<K>}ById`]: (
+    id: EntityId,
+  ) => Promise<void>;
+} & {
+  [K in Collection as `create${Capitalize<K>}`]: (entity: E) => Promise<void>;
+} & {
+  [K in Collection as `update${Capitalize<K>}`]: (entity: E) => Promise<void>;
+} & {
+  [K in Collection as `updateAll${Capitalize<K>}`]: (
+    entity: E[],
+  ) => Promise<void>;
+} & {
+  [K in Collection as `delete${Capitalize<K>}`]: (entity: E) => Promise<void>;
+};
+
+export type DataServiceMethods<E extends Entity, F extends Filter> = {
+  updateFilter: (filter: F) => void;
+  updateSelected: (id: EntityId, selected: boolean) => void;
+  load: () => Promise<void>;
+
+  setCurrent(entity: E): void;
+  loadById(id: EntityId): Promise<void>;
+  create(entity: E): Promise<void>;
+  update(entity: E): Promise<void>;
+  updateAll(entities: E[]): Promise<void>;
+  delete(entity: E): Promise<void>;
+};
+
+export function withDataService<
+  E extends Entity,
+  F extends Filter,
+  Collection extends string,
+>(options: {
+  dataServiceType: ProviderToken<DataService<E, F>>;
+  filter: F;
+  collection: Collection;
+}): SignalStoreFeature<
+  EmptyFeatureResult & {
+    state: NamedCallStateSlice<Collection> & NamedEntityState<E, Collection>;
+  },
+  {
+    state: NamedDataServiceState<E, F, Collection>;
+    props: NamedDataServiceComputed<E, Collection>;
+    methods: NamedDataServiceMethods<E, F, Collection>;
+  }
+>;
+export function withDataService<E extends Entity, F extends Filter>(options: {
+  dataServiceType: ProviderToken<DataService<E, F>>;
+  filter: F;
+}): SignalStoreFeature<
+  EmptyFeatureResult & { state: { callState: CallState } & EntityState<E> },
+  {
+    state: DataServiceState<E, F>;
+    props: DataServiceComputed<E>;
+    methods: DataServiceMethods<E, F>;
+  }
+>;
+
+export function withDataService<
+  E extends Entity,
+  F extends Filter,
+  Collection extends string,
+>(options: {
+  dataServiceType: ProviderToken<DataService<E, F>>;
+  filter: F;
+  collection?: Collection;
+}): /* eslint-disable @typescript-eslint/no-explicit-any */
+SignalStoreFeature<any, any> {
+  const { dataServiceType, filter, collection: prefix } = options;
+  const {
+    entitiesKey,
+    filterKey,
+    loadKey,
+    selectedEntitiesKey,
+    selectedIdsKey,
+    updateFilterKey,
+    updateSelectedKey,
+
+    currentKey,
+    createKey,
+    updateKey,
+    updateAllKey,
+    deleteKey,
+    loadByIdKey,
+    setCurrentKey,
+  } = getDataServiceKeys(options);
+
+  const { callStateKey } = getCallStateKeys({ collection: prefix });
+
+  return signalStoreFeature(
+    withState(() => ({
+      [filterKey]: filter,
+      [selectedIdsKey]: {} as Record<EntityId, boolean>,
+      [currentKey]: undefined as E | undefined,
+    })),
+    withComputed((store: Record<string, unknown>) => {
+      const entities = store[entitiesKey] as Signal<E[]>;
+      const selectedIds = store[selectedIdsKey] as Signal<
+        Record<EntityId, boolean>
+      >;
+
+      return {
+        [selectedEntitiesKey]: computed(() =>
+          entities().filter((e) => selectedIds()[e.id]),
+        ),
+      };
+    }),
+    withMethods(
+      (store: Record<string, unknown> & WritableStateSource<object>) => {
+        const dataService = inject(dataServiceType);
+        return {
+          [updateFilterKey]: (filter: F): void => {
+            patchState(store, { [filterKey]: filter });
+          },
+          [updateSelectedKey]: (id: EntityId, selected: boolean): void => {
+            patchState(store, (state: Record<string, unknown>) => ({
+              [selectedIdsKey]: {
+                ...(state[selectedIdsKey] as Record<EntityId, boolean>),
+                [id]: selected,
+              },
+            }));
+          },
+          [loadKey]: async (): Promise<void> => {
+            const filter = store[filterKey] as Signal<F>;
+            (() =>
+              store[callStateKey] && patchState(store, setLoading(prefix)))();
+
+            try {
+              const result = await dataService.load(filter());
+              patchState(
+                store,
+                prefix
+                  ? setAllEntities(result, { collection: prefix })
+                  : setAllEntities(result),
+              );
+              (() =>
+                store[callStateKey] && patchState(store, setLoaded(prefix)))();
+            } catch (e) {
+              (() =>
+                store[callStateKey] &&
+                patchState(store, setError(e, prefix)))();
+              throw e;
+            }
+          },
+          [loadByIdKey]: async (id: EntityId): Promise<void> => {
+            (() =>
+              store[callStateKey] && patchState(store, setLoading(prefix)))();
+
+            try {
+              const current = await dataService.loadById(id);
+              (() =>
+                store[callStateKey] && patchState(store, setLoaded(prefix)))();
+              patchState(store, { [currentKey]: current });
+            } catch (e) {
+              (() =>
+                store[callStateKey] &&
+                patchState(store, setError(e, prefix)))();
+              throw e;
+            }
+          },
+          [setCurrentKey]: (current: E): void => {
+            patchState(store, { [currentKey]: current });
+          },
+          [createKey]: async (entity: E): Promise<void> => {
+            patchState(store, { [currentKey]: entity });
+            (() =>
+              store[callStateKey] && patchState(store, setLoading(prefix)))();
+
+            try {
+              const created = await dataService.create(entity);
+              patchState(store, { [currentKey]: created });
+              patchState(
+                store,
+                prefix
+                  ? addEntity(created, { collection: prefix })
+                  : addEntity(created),
+              );
+              (() =>
+                store[callStateKey] && patchState(store, setLoaded(prefix)))();
+            } catch (e) {
+              (() =>
+                store[callStateKey] &&
+                patchState(store, setError(e, prefix)))();
+              throw e;
+            }
+          },
+          [updateKey]: async (entity: E): Promise<void> => {
+            patchState(store, { [currentKey]: entity });
+            (() =>
+              store[callStateKey] && patchState(store, setLoading(prefix)))();
+
+            try {
+              const updated = await dataService.update(entity);
+              patchState(store, { [currentKey]: updated });
+
+              const updateArg = {
+                id: updated.id,
+                changes: updated,
+              };
+
+              const updater = (collection: string) =>
+                updateEntity(updateArg, { collection });
+
+              patchState(
+                store,
+                prefix ? updater(prefix) : updateEntity(updateArg),
+              );
+              (() =>
+                store[callStateKey] && patchState(store, setLoaded(prefix)))();
+            } catch (e) {
+              (() =>
+                store[callStateKey] &&
+                patchState(store, setError(e, prefix)))();
+              throw e;
+            }
+          },
+          [updateAllKey]: async (entities: E[]): Promise<void> => {
+            (() =>
+              store[callStateKey] && patchState(store, setLoading(prefix)))();
+
+            try {
+              const result = await dataService.updateAll(entities);
+              patchState(
+                store,
+                prefix
+                  ? setAllEntities(result, { collection: prefix })
+                  : setAllEntities(result),
+              );
+              (() =>
+                store[callStateKey] && patchState(store, setLoaded(prefix)))();
+            } catch (e) {
+              (() =>
+                store[callStateKey] &&
+                patchState(store, setError(e, prefix)))();
+              throw e;
+            }
+          },
+          [deleteKey]: async (entity: E): Promise<void> => {
+            patchState(store, { [currentKey]: entity });
+            (() =>
+              store[callStateKey] && patchState(store, setLoading(prefix)))();
+
+            try {
+              await dataService.delete(entity);
+              patchState(store, { [currentKey]: undefined });
+              patchState(
+                store,
+                prefix
+                  ? removeEntity(entity.id, { collection: prefix })
+                  : removeEntity(entity.id),
+              );
+              (() =>
+                store[callStateKey] && patchState(store, setLoaded(prefix)))();
+            } catch (e) {
+              (() =>
+                store[callStateKey] &&
+                patchState(store, setError(e, prefix)))();
+              throw e;
+            }
+          },
+        };
+      },
+    ),
+  );
+}

package/src/lib/with-feature-factory.spec.ts

@@ -0,0 +1,69 @@
+import { computed, Signal } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import {
+  getState,
+  patchState,
+  signalStore,
+  signalStoreFeature,
+  withComputed,
+  withMethods,
+  withState,
+} from '@ngrx/signals';
+import { lastValueFrom, of } from 'rxjs';
+import { withFeatureFactory } from './with-feature-factory';
+
+type User = {
+  id: number;
+  name: string;
+};
+
+function withMyEntity<Entity>(loadMethod: (id: number) => Promise<Entity>) {
+  return signalStoreFeature(
+    withState({
+      currentId: 1 as number | undefined,
+      entity: undefined as undefined | Entity,
+    }),
+    withMethods((store) => ({
+      async load(id: number) {
+        const entity = await loadMethod(1);
+        patchState(store, { entity, currentId: id });
+      },
+    })),
+  );
+}
+
+describe('withFeatureFactory', () => {
+  it('should allow a sum feature', () => {
+    function withSum(a: Signal<number>, b: Signal<number>) {
+      return signalStoreFeature(
+        withComputed(() => ({ sum: computed(() => a() + b()) })),
+      );
+    }
+    signalStore(
+      withState({ a: 1, b: 2 }),
+      withFeatureFactory((store) => withSum(store.a, store.b)),
+    );
+  });
+
+  it('should allow to pass elements from a SignalStore to a feature', async () => {
+    const UserStore = signalStore(
+      { providedIn: 'root' },
+      withMethods(() => ({
+        findById(id: number) {
+          return of({ id: 1, name: 'Konrad' });
+        },
+      })),
+      withFeatureFactory((store) => {
+        const loader = (id: number) => lastValueFrom(store.findById(id));
+        return withMyEntity<User>(loader);
+      }),
+    );
+
+    const userStore = TestBed.inject(UserStore);
+    await userStore.load(1);
+    expect(getState(userStore)).toEqual({
+      currentId: 1,
+      entity: { id: 1, name: 'Konrad' },
+    });
+  });
+});

package/src/lib/with-feature-factory.ts

@@ -0,0 +1,56 @@
+import {
+  SignalStoreFeature,
+  SignalStoreFeatureResult,
+  StateSignals,
+} from '@ngrx/signals';
+
+type StoreForFactory<Input extends SignalStoreFeatureResult> = StateSignals<
+  Input['state']
+> &
+  Input['props'] &
+  Input['methods'];
+
+/**
+ * @deprecated Use `import { withFeature } from '@ngrx/signals'` instead, starting with `ngrx/signals` 19.1: https://ngrx.io/guide/signals/signal-store/custom-store-features#connecting-a-custom-feature-with-the-store
+ *
+ * Allows to pass properties, methods, or signals from a SignalStore
+ * to a feature.
+ *
+ * Typically, a `signalStoreFeature` can have input constraints on
+ *
+ * ```typescript
+ * function withSum(a: Signal<number>, b: Signal<number>) {
+ *   return signalStoreFeature(
+ *     withComputed(() => ({
+ *       sum: computed(() => a() + b())
+ *     }))
+ *   );
+ * }
+ *
+ * signalStore(
+ *   withState({ a: 1, b: 2 }),
+ *   withFeatureFactory((store) => withSum(store.a, store.b))
+ * );
+ * ```
+ * @param factoryFn
+ */
+export function withFeatureFactory<
+  Input extends SignalStoreFeatureResult,
+  Output extends SignalStoreFeatureResult,
+>(
+  factoryFn: (
+    store: StoreForFactory<Input>,
+  ) => SignalStoreFeature<Input, Output>,
+): SignalStoreFeature<Input, Output> {
+  return (store) => {
+    const storeForFactory = {
+      ...store['stateSignals'],
+      ...store['props'],
+      ...store['methods'],
+    } as StoreForFactory<Input>;
+
+    const feature = factoryFn(storeForFactory);
+
+    return feature(store);
+  };
+}

package/src/lib/with-pagination.spec.ts

@@ -0,0 +1,135 @@
+import { patchState, signalStore, type } from '@ngrx/signals';
+import { setAllEntities, withEntities } from '@ngrx/signals/entities';
+import {
+  createPageArray,
+  firstPage,
+  gotoPage,
+  nextPage,
+  previousPage,
+  setPageSize,
+  withPagination,
+} from './with-pagination';
+
+type Book = { id: number; title: string; author: string };
+const generateBooks = (count = 10) => {
+  const books = [] as Book[];
+  for (let i = 1; i <= count; i++) {
+    books.push({ id: i, title: `Book ${i}`, author: `Author ${i}` });
+  }
+  return books;
+};
+
+describe('withPagination', () => {
+  it('should use and update a pagination', () => {
+    const Store = signalStore(
+      { protectedState: false },
+      withEntities({ entity: type<Book>() }),
+      withPagination(),
+    );
+
+    const store = new Store();
+
+    patchState(store, setAllEntities(generateBooks(55)));
+    expect(store.currentPage()).toBe(0);
+    expect(store.pageCount()).toBe(6);
+  });
+
+  it('should use and update a pagination with collection', () => {
+    const Store = signalStore(
+      { protectedState: false },
+      withEntities({ entity: type<Book>(), collection: 'books' }),
+      withPagination({ entity: type<Book>(), collection: 'books' }),
+    );
+
+    const store = new Store();
+
+    patchState(
+      store,
+      setAllEntities(generateBooks(55), { collection: 'books' }),
+    );
+
+    patchState(store, gotoPage(5, { collection: 'books' }));
+    expect(store.booksCurrentPage()).toBe(5);
+    expect(store.selectedPageBooksEntities().length).toBe(5);
+    expect(store.booksPageCount()).toBe(6);
+  });
+
+  it('should navigate through pages', () => {
+    const Store = signalStore(
+      { protectedState: false },
+      withEntities({ entity: type<Book>() }),
+      withPagination(),
+    );
+
+    const store = new Store();
+
+    patchState(store, setAllEntities(generateBooks(55)));
+    expect(store.currentPage()).toBe(0);
+
+    patchState(store, nextPage());
+    expect(store.currentPage()).toBe(1);
+
+    patchState(store, previousPage());
+    expect(store.currentPage()).toBe(0);
+
+    patchState(store, nextPage());
+    patchState(store, nextPage());
+    expect(store.currentPage()).toBe(2);
+
+    patchState(store, firstPage());
+    expect(store.currentPage()).toBe(0);
+  });
+
+  it('should set page size', () => {
+    const Store = signalStore(
+      { protectedState: false },
+      withEntities({ entity: type<Book>() }),
+      withPagination(),
+    );
+
+    const store = new Store();
+
+    patchState(store, setAllEntities(generateBooks(50)), setPageSize(10));
+    expect(store.pageCount()).toBe(5);
+
+    patchState(store, setPageSize(5));
+    expect(store.pageCount()).toBe(10);
+  });
+
+  it('should react on entity changes', () => {
+    const Store = signalStore(
+      { protectedState: false },
+      withEntities({ entity: type<Book>() }),
+      withPagination(),
+    );
+
+    const store = new Store();
+
+    patchState(store, setAllEntities(generateBooks(100)));
+
+    expect(store.pageCount()).toBe(10);
+
+    patchState(store, setAllEntities(generateBooks(20)));
+
+    expect(store.pageCount()).toBe(2);
+
+    patchState(store, setPageSize(5));
+
+    expect(store.pageCount()).toBe(4);
+  });
+
+  describe('internal pageNavigationArray', () => {
+    it('should return an array of page numbers', () => {
+      const pages = createPageArray(8, 10, 500, 7);
+      expect(pages).toEqual([
+        { label: 5, value: 5 },
+        { label: '...', value: 6 },
+        { label: 7, value: 7 },
+        { label: 8, value: 8 },
+        { label: 9, value: 9 },
+        { label: '...', value: 10 },
+        { label: 50, value: 50 },
+      ]);
+    });
+  });
+});