@angular-architects/ngrx-toolkit 20.0.0 → 20.0.2

package/src/lib/with-pagination.ts

@@ -0,0 +1,373 @@
+/** With pagination comes in two flavors the first one is local pagination or in memory pagination. For example we have 2000 items which we want
+ * to display in a table and the response payload is small enough to be stored in the memory. But we can not display all 2000 items at once
+ * so we need to paginate the data. The second flavor is server side pagination where the response payload is too large to be stored in the memory
+ * and we need to fetch the data from the server in chunks. In the second case we 'could' also cache the data in the memory but that could lead to
+ * other problems like memory leaks and stale data. So we will not cache the data in the memory in the second case.
+ * This feature implements the local pagination.
+ */
+
+import { Signal, computed } from '@angular/core';
+import {
+  EmptyFeatureResult,
+  SignalStoreFeature,
+  signalStoreFeature,
+  withComputed,
+  withState,
+} from '@ngrx/signals';
+import { capitalize } from './with-data-service';
+
+// This is a virtual page which is can be used to create a pagination control
+export type Page = { label: string | number; value: number };
+
+export type NamedPaginationServiceState<E, Collection extends string> = {
+  [K in Collection as `selectedPage${Capitalize<K>}Entities`]: Array<E>;
+} & {
+  [K in Collection as `${Lowercase<K>}CurrentPage`]: number;
+} & {
+  [K in Collection as `${Lowercase<K>}PageSize`]: number;
+} & {
+  [K in Collection as `${Lowercase<K>}TotalCount`]: number;
+} & {
+  [K in Collection as `${Lowercase<K>}PageCount`]: number;
+} & {
+  [K in Collection as `${Lowercase<K>}PageNavigationArray`]: number;
+} & {
+  [K in Collection as `${Lowercase<K>}PageNavigationArrayMax`]: number;
+};
+
+export type NamedPaginationServiceSignals<E, Collection extends string> = {
+  [K in Collection as `selectedPage${Capitalize<K>}Entities`]: Signal<E[]>;
+} & {
+  [K in Collection as `${Lowercase<K>}CurrentPage`]: Signal<number>;
+} & {
+  [K in Collection as `${Lowercase<K>}PageSize`]: Signal<number>;
+} & {
+  [K in Collection as `${Lowercase<K>}TotalCount`]: Signal<number>;
+} & {
+  [K in Collection as `${Lowercase<K>}PageCount`]: Signal<number>;
+} & {
+  [K in Collection as `${Lowercase<K>}PageNavigationArray`]: Signal<Page[]>;
+} & {
+  [K in Collection as `${Lowercase<K>}PageNavigationArrayMax`]: Signal<number>;
+} & {
+  [K in Collection as `hasNext${Capitalize<K>}Page`]: Signal<boolean>;
+} & {
+  [K in Collection as `hasPrevious${Capitalize<K>}Page`]: Signal<boolean>;
+};
+
+export type PaginationServiceState<E> = {
+  selectedPageEntities: Array<E>;
+  currentPage: number;
+  pageSize: number;
+  totalCount: number;
+  pageCount: number;
+  pageNavigationArray: Page[];
+  pageNavigationArrayMax: number;
+};
+
+export type PaginationServiceSignals<E> = {
+  selectedPageEntities: Signal<E[]>;
+  currentPage: Signal<number>;
+  pageSize: Signal<number>;
+  totalCount: Signal<number>;
+  pageCount: Signal<number>;
+  pageNavigationArray: Signal<Page[]>;
+  pageNavigationArrayMax: Signal<number>;
+  hasNextPage: Signal<boolean>;
+  hasPreviousPage: Signal<boolean>;
+};
+
+type PageState<Collection extends string | undefined> =
+  Collection extends string
+    ? {
+        [K in Collection as `${Lowercase<K>}CurrentPage`]: number;
+      }
+    : { currentPage: number };
+
+type PageSizeState<Collection extends string | undefined> =
+  Collection extends string
+    ? {
+        [K in Collection as `${Lowercase<K>}PageSize`]: number;
+      }
+    : { pageSize: number };
+
+export type SetPaginationState<
+  E,
+  Collection extends string | undefined,
+> = Collection extends string
+  ? NamedPaginationServiceState<E, Collection>
+  : PaginationServiceState<E>;
+
+export function withPagination<E, Collection extends string>(options: {
+  entity: E;
+  collection: Collection;
+}): SignalStoreFeature<
+  EmptyFeatureResult,
+  EmptyFeatureResult & {
+    state: NamedPaginationServiceState<E, Collection>;
+    props: NamedPaginationServiceSignals<E, Collection>;
+  }
+>;
+
+export function withPagination<E>(): SignalStoreFeature<
+  EmptyFeatureResult,
+  EmptyFeatureResult & {
+    state: PaginationServiceState<E>;
+    props: PaginationServiceSignals<E>;
+  }
+>;
+
+export function withPagination<E, Collection extends string>(options?: {
+  entity: E;
+  collection: Collection;
+}): SignalStoreFeature {
+  const {
+    pageKey,
+    pageSizeKey,
+    entitiesKey,
+    selectedPageEntitiesKey,
+    totalCountKey,
+    pageCountKey,
+    pageNavigationArrayMaxKey,
+    pageNavigationArrayKey,
+    hasNextPageKey,
+    hasPreviousPageKey,
+  } = createPaginationKeys<Collection>(options);
+
+  return signalStoreFeature(
+    withState({
+      [pageKey]: 0,
+      [pageSizeKey]: 10,
+      [pageNavigationArrayMaxKey]: 7,
+    }),
+    withComputed((store: Record<string, unknown>) => {
+      const entities = store[entitiesKey] as Signal<E[]>;
+      const page = store[pageKey] as Signal<number>;
+      const pageSize = store[pageSizeKey] as Signal<number>;
+      const pageNavigationArrayMax = store[
+        pageNavigationArrayMaxKey
+      ] as Signal<number>;
+
+      return {
+        // The derived enitites which are displayed on the current page
+        [selectedPageEntitiesKey]: computed<E[]>(() => {
+          const pageSizeValue = pageSize();
+          const pageValue = page();
+
+          return entities().slice(
+            pageValue * pageSizeValue,
+            (pageValue + 1) * pageSizeValue,
+          ) as E[];
+        }),
+        [totalCountKey]: computed(() => entities().length),
+        [pageCountKey]: computed(() => {
+          const totalCountValue = entities().length;
+          const pageSizeValue = pageSize();
+
+          if (totalCountValue === 0) {
+            return 0;
+          }
+
+          return Math.ceil(totalCountValue / pageSizeValue);
+        }),
+        [pageNavigationArrayKey]: computed(() =>
+          createPageArray(
+            page(),
+            pageSize(),
+            entities().length,
+            pageNavigationArrayMax(),
+          ),
+        ),
+
+        [hasNextPageKey]: computed(() => {
+          return page() < pageSize();
+        }),
+
+        [hasPreviousPageKey]: computed(() => {
+          return page() > 1;
+        }),
+      };
+    }),
+  );
+}
+
+export function gotoPage<Collection extends string>(
+  page: number,
+  options?: {
+    collection: Collection;
+  },
+): PageState<Collection> {
+  const { pageKey } = createPaginationKeys<Collection>(options);
+
+  return {
+    [pageKey]: page,
+  } as PageState<Collection>;
+}
+
+export function setPageSize<Collection extends string>(
+  pageSize: number,
+  options?: {
+    collection: Collection;
+  },
+) {
+  const { pageSizeKey } = createPaginationKeys<Collection>(options);
+
+  return {
+    [pageSizeKey]: pageSize,
+  } as PageSizeState<Collection>;
+}
+
+type SetPageState<Collection extends string | undefined> = (
+  state: PageState<Collection>,
+) => PageState<Collection>;
+
+export function nextPage<Collection extends string>(options?: {
+  collection: Collection;
+}): SetPageState<Collection> {
+  const { pageKey } = createPaginationKeys<Collection>(options);
+
+  return (state: Record<string, number>) => {
+    const currentPage = state[pageKey];
+
+    return { [pageKey]: currentPage + 1 } as PageState<Collection>;
+  };
+}
+
+export function previousPage<Collection extends string>(options?: {
+  collection: Collection;
+}): SetPageState<Collection> {
+  const { pageKey } = createPaginationKeys<Collection>(options);
+
+  return (state: Record<string, number>) => {
+    const currentPage = state[pageKey];
+
+    return { [pageKey]: currentPage - 1 } as PageState<Collection>;
+  };
+}
+
+export function firstPage<Collection extends string>(options?: {
+  collection: Collection;
+}) {
+  const { pageKey } = createPaginationKeys<Collection>(options);
+
+  return { [pageKey]: 0 } as PageState<Collection>;
+}
+
+export function setMaxPageNavigationArrayItems<E, Collection extends string>(
+  maxPageNavigationArrayItems: number,
+  options?: {
+    collection: Collection;
+  },
+): Partial<SetPaginationState<E, Collection>> {
+  const { pageNavigationArrayMaxKey } =
+    createPaginationKeys<Collection>(options);
+
+  return {
+    [pageNavigationArrayMaxKey]: maxPageNavigationArrayItems,
+  } as Partial<SetPaginationState<E, Collection>>;
+}
+
+function createPaginationKeys<Collection extends string>(
+  options: { collection: Collection } | undefined,
+) {
+  const entitiesKey = options?.collection
+    ? `${options.collection}Entities`
+    : 'entities';
+
+  const selectedPageEntitiesKey = options?.collection
+    ? `selectedPage${capitalize(options?.collection)}Entities`
+    : 'selectedPageEntities';
+
+  const pageKey = options?.collection
+    ? `${options.collection}CurrentPage`
+    : 'currentPage';
+
+  const pageSizeKey = options?.collection
+    ? `${options.collection}PageSize`
+    : 'pageSize';
+
+  const totalCountKey = options?.collection
+    ? `${options.collection}TotalCount`
+    : 'totalCount';
+
+  const pageCountKey = options?.collection
+    ? `${options.collection}PageCount`
+    : 'pageCount';
+
+  const pageNavigationArrayMaxKey = options?.collection
+    ? `${options.collection}PageNavigationArrayMax`
+    : 'pageNavigationArrayMax';
+
+  const pageNavigationArrayKey = options?.collection
+    ? `${options.collection}PageNavigationArray`
+    : 'pageNavigationArray';
+
+  const hasNextPageKey = options?.collection
+    ? `hasNext${capitalize(options.collection)}Page`
+    : 'hasNextPage';
+
+  const hasPreviousPageKey = options?.collection
+    ? `hasPrevious${capitalize(options.collection)}Page`
+    : 'hasPreviousPage';
+
+  return {
+    pageKey,
+    pageSizeKey,
+    entitiesKey,
+    selectedPageEntitiesKey,
+    totalCountKey,
+    pageCountKey,
+    pageNavigationArrayKey,
+    pageNavigationArrayMaxKey,
+    hasNextPageKey,
+    hasPreviousPageKey,
+  };
+}
+
+export function createPageArray(
+  currentPage: number,
+  itemsPerPage: number,
+  totalItems: number,
+  paginationRange: number,
+): Page[] {
+  // Convert paginationRange to number in case it's a string
+  paginationRange = +paginationRange;
+
+  // Calculate total number of pages
+  const totalPages = Math.max(Math.ceil(totalItems / itemsPerPage), 1);
+  const halfWay = Math.ceil(paginationRange / 2);
+
+  const isStart = currentPage <= halfWay;
+  const isEnd = totalPages - halfWay < currentPage;
+  const isMiddle = !isStart && !isEnd;
+
+  const ellipsesNeeded = paginationRange < totalPages;
+  const pages: Page[] = [];
+
+  for (let i = 1; i <= totalPages && i <= paginationRange; i++) {
+    let pageNumber = i;
+
+    if (i === paginationRange) {
+      pageNumber = totalPages;
+    } else if (ellipsesNeeded) {
+      if (isEnd) {
+        pageNumber = totalPages - paginationRange + i;
+      } else if (isMiddle) {
+        pageNumber = currentPage - halfWay + i;
+      }
+    }
+
+    const openingEllipsesNeeded = i === 2 && (isMiddle || isEnd);
+    const closingEllipsesNeeded =
+      i === paginationRange - 1 && (isMiddle || isStart);
+
+    const label =
+      ellipsesNeeded && (openingEllipsesNeeded || closingEllipsesNeeded)
+        ? '...'
+        : pageNumber;
+
+    pages.push({ label, value: pageNumber });
+  }
+
+  return pages;
+}

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

@@ -0,0 +1,258 @@
+import {
+  HttpClient,
+  HttpParams,
+  provideHttpClient,
+} from '@angular/common/http';
+import {
+  HttpTestingController,
+  provideHttpClientTesting,
+} from '@angular/common/http/testing';
+import { inject } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { patchState, signalStore, withMethods, withState } from '@ngrx/signals';
+import { map, switchMap } from 'rxjs';
+import {
+  createEffects,
+  createReducer,
+  noPayload,
+  payload,
+  withRedux,
+} from './with-redux';
+
+interface Flight {
+  id: number;
+  from: string;
+  to: string;
+  delayed: boolean;
+  date: Date;
+}
+
+let currentId = 1;
+
+const createFlight = (flight: Partial<Flight> = {}) => {
+  return {
+    ...{
+      id: currentId++,
+      from: 'Vienna',
+      to: 'London',
+      delayed: false,
+      date: new Date(2024, 0, 1),
+    },
+    ...flight,
+  };
+};
+
+describe('with redux', () => {
+  it('should load flights', () => {
+    TestBed.configureTestingModule({
+      providers: [provideHttpClient(), provideHttpClientTesting()],
+    });
+
+    TestBed.runInInjectionContext(() => {
+      const controller = TestBed.inject(HttpTestingController);
+      const FlightsStore = signalStore(
+        withState({ flights: [] as Flight[] }),
+        withRedux({
+          actions: {
+            public: {
+              loadFlights: payload<{ from: string; to: string }>(),
+              delayFirst: noPayload,
+            },
+            private: {
+              flightsLoaded: payload<{ flights: Flight[] }>(),
+            },
+          },
+
+          reducer: (actions, on) => {
+            on(actions.flightsLoaded, (state, { flights }) => {
+              patchState(state, { flights });
+            });
+          },
+
+          effects: (actions, create) => {
+            const httpClient = inject(HttpClient);
+
+            return {
+              loadFlights$: create(actions.loadFlights).pipe(
+                switchMap(({ from, to }) => {
+                  return httpClient.get<Flight[]>(
+                    'https://www.angulararchitects.io',
+                    {
+                      params: new HttpParams().set('from', from).set('to', to),
+                    },
+                  );
+                }),
+                map((flights) => actions.flightsLoaded({ flights })),
+              ),
+            };
+          },
+        }),
+      );
+
+      const flightsStore = new FlightsStore();
+      flightsStore.loadFlights({ from: 'Vienna', to: 'London' });
+      const flight = createFlight();
+      controller
+        .expectOne((req) =>
+          req.url.startsWith('https://www.angulararchitects.io'),
+        )
+        .flush([flight]);
+
+      expect(flightsStore.flights()).toEqual([flight]);
+
+      controller.verify();
+    });
+  });
+
+  it('should allow a noPayload action to call without parameters', () => {
+    const FlightsStore = signalStore(
+      withState({ flights: [] as Flight[] }),
+      withRedux({
+        actions: {
+          init: noPayload,
+        },
+        reducer() {
+          return {};
+        },
+        effects() {
+          return {};
+        },
+      }),
+    );
+
+    const flightStore = TestBed.configureTestingModule({
+      providers: [FlightsStore],
+    }).inject(FlightsStore);
+
+    flightStore.init();
+  });
+
+  it('should allow multiple effects listening to the same action', () => {
+    const FlightsStore = signalStore(
+      withState({ flights: [] as Flight[], effect1: false, effect2: false }),
+      withRedux({
+        actions: {
+          init: noPayload,
+          updateEffect1: payload<{ value: boolean }>(),
+          updateEffect2: payload<{ value: boolean }>(),
+        },
+        reducer(actions, on) {
+          on(actions.updateEffect1, (state, { value }) => {
+            patchState(state, { effect1: value });
+          });
+
+          on(actions.updateEffect2, (state, { value }) => {
+            patchState(state, { effect2: value });
+          });
+        },
+        effects(actions, create) {
+          return {
+            init1$: create(actions.init).pipe(
+              map(() => actions.updateEffect1({ value: true })),
+            ),
+            init2$: create(actions.init).pipe(
+              map(() => actions.updateEffect2({ value: true })),
+            ),
+          };
+        },
+      }),
+    );
+
+    const flightStore = TestBed.configureTestingModule({
+      providers: [FlightsStore],
+    }).inject(FlightsStore);
+
+    flightStore.init();
+
+    expect(flightStore.effect1()).toBe(true);
+    expect(flightStore.effect2()).toBe(true);
+  });
+
+  it('should be possible to separate actions, reducer and effects', () => {
+    interface FlightState {
+      flights: Flight[];
+      effect1: boolean;
+      effect2: boolean;
+    }
+
+    const initialState: FlightState = {
+      flights: [],
+      effect1: false,
+      effect2: false,
+    };
+
+    const actions = {
+      init: noPayload,
+      updateEffect1: payload<{ value: boolean }>(),
+      updateEffect2: payload<{ value: boolean }>(),
+    };
+
+    const effects = createEffects(actions, (actions, create) => {
+      return {
+        init1$: create(actions.init).pipe(
+          map(() => actions.updateEffect1({ value: true })),
+        ),
+        init2$: create(actions.init).pipe(
+          map(() => actions.updateEffect2({ value: true })),
+        ),
+      };
+    });
+
+    const reducer = createReducer<FlightState, typeof actions>(
+      (actions, on) => {
+        on(actions.updateEffect1, (state, { value }) => {
+          patchState(state, { effect1: value });
+        });
+
+        on(actions.updateEffect2, (state, { value }) => {
+          patchState(state, { effect2: value });
+        });
+      },
+    );
+
+    const FlightsStore = signalStore(
+      withState(initialState),
+      withRedux({
+        actions,
+        effects,
+        reducer,
+      }),
+    );
+
+    const flightStore = TestBed.configureTestingModule({
+      providers: [FlightsStore],
+    }).inject(FlightsStore);
+
+    flightStore.init();
+
+    expect(flightStore.effect1()).toBe(true);
+    expect(flightStore.effect2()).toBe(true);
+  });
+
+  it('should not override methods defined before', () => {
+    const FlightsStore = signalStore(
+      withMethods(() => ({
+        sayHi() {
+          return 'hi';
+        },
+      })),
+      withRedux({
+        actions: {
+          init: noPayload,
+        },
+        reducer() {
+          return {};
+        },
+        effects() {
+          return {};
+        },
+      }),
+    );
+
+    const flightStore = TestBed.configureTestingModule({
+      providers: [FlightsStore],
+    }).inject(FlightsStore);
+
+    expect(flightStore.sayHi()).toBe('hi');
+  });
+});