@angular-architects/ngrx-toolkit 20.0.1 → 20.0.2

package/eslint.config.cjs

@@ -0,0 +1,43 @@
+const nx = require('@nx/eslint-plugin');
+const baseConfig = require('../../eslint.config.cjs');
+
+module.exports = [
+  ...baseConfig,
+  {
+    files: ['**/*.json'],
+    rules: {
+      '@nx/dependency-checks': [
+        'error',
+        {
+          ignoredFiles: ['{projectRoot}/eslint.config.{js,cjs,mjs}'],
+        },
+      ],
+    },
+    languageOptions: {
+      parser: require('jsonc-eslint-parser'),
+    },
+  },
+  ...nx.configs['flat/angular'],
+  ...nx.configs['flat/angular-template'],
+  {
+    files: ['**/*.ts'],
+    rules: {
+      '@angular-eslint/directive-selector': [
+        'error',
+        {
+          type: 'attribute',
+          prefix: 'lib',
+          style: 'camelCase',
+        },
+      ],
+      '@angular-eslint/component-selector': [
+        'error',
+        {
+          type: 'element',
+          prefix: 'lib',
+          style: 'kebab-case',
+        },
+      ],
+    },
+  }
+];

package/jest.config.ts

@@ -0,0 +1,22 @@
+export default {
+  displayName: 'ngrx-toolkit',
+  setupFiles: ['core-js'],
+  preset: '../../jest.preset.js',
+  setupFilesAfterEnv: ['<rootDir>/src/test-setup.ts'],
+  coverageDirectory: '../../coverage/libs/ngrx-toolkit',
+  transform: {
+    '^.+\\.(ts|mjs|js|html)$': [
+      'jest-preset-angular',
+      {
+        tsconfig: '<rootDir>/tsconfig.spec.json',
+        stringifyContentPathRegex: '\\.(html|svg)$',
+      },
+    ],
+  },
+  transformIgnorePatterns: ['node_modules/(?!.*\\.mjs$)'],
+  snapshotSerializers: [
+    'jest-preset-angular/build/serializers/no-ng-attributes',
+    'jest-preset-angular/build/serializers/ng-snapshot',
+    'jest-preset-angular/build/serializers/html-comment',
+  ],
+};

package/ng-package.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "../../node_modules/ng-packagr/ng-package.schema.json",
+  "dest": "../../dist/libs/ngrx-toolkit",
+  "lib": {
+    "entryFile": "src/index.ts"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@angular-architects/ngrx-toolkit",
-  "version": "20.0.1",
+  "version": "20.0.2",
   "license": "MIT",
   "repository": {
     "type": "GitHub",
@@ -18,23 +18,6 @@
       "optional": true
     }
   },
-  "dependencies": {
-    "tslib": "^2.3.0"
-  },
-  "sideEffects": false,
-  "module": "fesm2022/angular-architects-ngrx-toolkit.mjs",
-  "typings": "index.d.ts",
-  "exports": {
-    "./package.json": {
-      "default": "./package.json"
-    },
-    ".": {
-      "types": "./index.d.ts",
-      "default": "./fesm2022/angular-architects-ngrx-toolkit.mjs"
-    },
-    "./redux-connector": {
-      "types": "./redux-connector/index.d.ts",
-      "default": "./fesm2022/angular-architects-ngrx-toolkit-redux-connector.mjs"
-    }
-  }
-}
+  "dependencies": {},
+  "sideEffects": false
+}

package/project.json

@@ -0,0 +1,37 @@
+{
+  "name": "ngrx-toolkit",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "libs/ngrx-toolkit/src",
+  "prefix": "ngrx-toolkit",
+  "projectType": "library",
+  "tags": [],
+  "targets": {
+    "build": {
+      "executor": "@nx/angular:package",
+      "outputs": ["{workspaceRoot}/dist/{projectRoot}"],
+      "options": {
+        "project": "libs/ngrx-toolkit/ng-package.json"
+      },
+      "configurations": {
+        "production": {
+          "tsConfig": "libs/ngrx-toolkit/tsconfig.lib.prod.json"
+        },
+        "development": {
+          "tsConfig": "libs/ngrx-toolkit/tsconfig.lib.json"
+        }
+      },
+      "defaultConfiguration": "production"
+    },
+    "test": {
+      "executor": "@nx/jest:jest",
+      "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
+      "options": {
+        "jestConfig": "libs/ngrx-toolkit/jest.config.ts"
+      }
+    },
+    "lint": {
+      "executor": "@nx/eslint:lint",
+      "outputs": ["{options.outputFile}"]
+    }
+  }
+}

package/redux-connector/docs/README.md

@@ -0,0 +1,131 @@
+# Redux Connector for the NgRx Signal Store `createReduxState()`
+
+The Redux Connector turns any `signalStore()` into a Global State Management Slice following the Redux pattern. It is available as secondary entry point, i.e. `import { createReduxState } from '@angular-architects/ngrx-toolkit/redux-connector'` and has a dependency to `@ngrx/store`.
+
+It supports:
+
+✅ Well-known NgRx Store Actions \
+✅ Global Action `dispatch()` \
+✅ Angular Lazy Loading \
+✅ Auto-generated `provideNamedStore()` & `injectNamedStore()` Functions \
+✅ Global Action to Store Method Mappers \
+
+- [Redux Connector for the NgRx Signal Store `createReduxState()`](#redux-connector-for-the-ngrx-signal-store-createreduxstate)
+  - [Use a present Signal Store](#use-a-present-signal-store)
+  - [Use well-known NgRx Store Actions](#use-well-known-ngrx-store-actions)
+  - [Map Actions to Methods](#map-actions-to-methods)
+  - [Register an Angular Dependency Injection Provider](#register-an-angular-dependency-injection-provider)
+  - [Use the Store in your Component](#use-the-store-in-your-component)
+
+## Use a present Signal Store
+
+```typescript
+export const FlightStore = signalStore(
+  // State
+  withEntities({ entity: type<Flight>(), collection: 'flight' }),
+  withEntities({ entity: type<number>(), collection: 'hide' }),
+  // Selectors
+  withComputed(({ flightEntities, hideEntities }) => ({
+    filteredFlights: computed(() => flightEntities().filter((flight) => !hideEntities().includes(flight.id))),
+    flightCount: computed(() => flightEntities().length),
+  })),
+  // Updater
+  withMethods((store) => ({
+    setFlights: (state: { flights: Flight[] }) => patchState(store, setAllEntities(state.flights, { collection: 'flight' })),
+    updateFlight: (state: { flight: Flight }) => patchState(store, updateEntity({ id: state.flight.id, changes: state.flight }, { collection: 'flight' })),
+    clearFlights: () => patchState(store, removeAllEntities({ collection: 'flight' })),
+  })),
+  // Effects
+  withMethods((store, flightService = inject(FlightService)) => ({
+    loadFlights: reduxMethod<FlightFilter, { flights: Flight[] }>(
+      pipe(
+        switchMap((filter) => from(flightService.load({ from: filter.from, to: filter.to }))),
+        map((flights) => ({ flights })),
+      ),
+      store.setFlights,
+    ),
+  })),
+);
+```
+
+## Use well-known NgRx Store Actions
+
+```typescript
+export const ticketActions = createActionGroup({
+  source: 'tickets',
+  events: {
+    'flights load': props<FlightFilter>(),
+    'flights loaded': props<{ flights: Flight[] }>(),
+    'flights loaded by passenger': props<{ flights: Flight[] }>(),
+    'flight update': props<{ flight: Flight }>(),
+    'flights clear': emptyProps(),
+  },
+});
+```
+
+## Map Actions to Methods
+
+```typescript
+export const { provideFlightStore, injectFlightStore } = createReduxState('flight', FlightStore, (store) =>
+  withActionMappers(
+    mapAction(
+      // Filtered Action
+      ticketActions.flightsLoad,
+      // Side-Effect
+      store.loadFlights,
+      // Result Action
+      ticketActions.flightsLoaded,
+    ),
+    mapAction(
+      // Filtered Actions
+      ticketActions.flightsLoaded,
+      ticketActions.flightsLoadedByPassenger,
+      // State Updater Method (like Reducers)
+      store.setFlights,
+    ),
+    mapAction(ticketActions.flightUpdate, store.updateFlight),
+    mapAction(ticketActions.flightsClear, store.clearFlights),
+  ),
+);
+```
+
+## Register an Angular Dependency Injection Provider
+
+```typescript
+export const appRoutes: Route[] = [
+  {
+    path: 'flight-search-redux-connector',
+    providers: [provideFlightStore()],
+    component: FlightSearchReducConnectorComponent,
+  },
+];
+```
+
+## Use the Store in your Component
+
+```typescript
+@Component({
+  standalone: true,
+  imports: [JsonPipe, RouterLink, FormsModule, FlightCardComponent],
+  selector: 'demo-flight-search-redux-connector',
+  templateUrl: './flight-search.component.html',
+})
+export class FlightSearchReducConnectorComponent {
+  private store = injectFlightStore();
+
+  protected flights = this.store.flightEntities;
+
+  protected search() {
+    this.store.dispatch(
+      ticketActions.flightsLoad({
+        from: this.localState.filter.from(),
+        to: this.localState.filter.to(),
+      }),
+    );
+  }
+
+  protected reset(): void {
+    this.store.dispatch(ticketActions.flightsClear());
+  }
+}
+```

package/redux-connector/index.ts

@@ -0,0 +1,6 @@
+export {
+  createReduxState,
+  mapAction,
+  withActionMappers,
+} from './src/lib/create-redux';
+export { reduxMethod } from './src/lib/rxjs-interop/redux-method';

package/redux-connector/ng-package.json

@@ -0,0 +1,5 @@
+{
+  "lib": {
+    "entryFile": "index.ts"
+  }
+}

package/redux-connector/src/lib/create-redux.ts

@@ -0,0 +1,102 @@
+import {
+  inject,
+  makeEnvironmentProviders,
+  provideEnvironmentInitializer,
+} from '@angular/core';
+import { ActionCreator, ActionType } from '@ngrx/store/src/models';
+import {
+  CreateReduxState,
+  ExtractActionTypes,
+  MapperTypes,
+  ServiceWithDecorator,
+  Store,
+} from './model';
+import { SignalReduxStore, injectReduxDispatch } from './signal-redux-store';
+import { capitalize, isActionCreator } from './util';
+
+export function mapAction<Creators extends readonly ActionCreator[]>(
+  ...args: [
+    ...creators: Creators,
+    storeMethod: (action: ActionType<Creators[number]>) => unknown,
+  ]
+): MapperTypes<Creators>;
+export function mapAction<Creators extends readonly ActionCreator[], T>(
+  ...args: [
+    ...creators: Creators,
+    storeMethod: (
+      action: ActionType<Creators[number]>,
+      resultMethod: (input: T) => unknown,
+    ) => unknown,
+    resultMethod: (input: T) => unknown,
+  ]
+): MapperTypes<Creators>;
+export function mapAction<Creators extends readonly ActionCreator[]>(
+  ...args: [
+    ...creators: Creators,
+    storeMethod: (action: ActionType<Creators[number]>) => unknown,
+    resultMethod?: (input: unknown) => unknown,
+  ]
+): MapperTypes<Creators> {
+  let resultMethod = args.pop() as unknown as
+    | ((input: unknown) => unknown)
+    | undefined;
+  let storeMethod = args.pop() as unknown as (
+    action: ActionType<Creators[number]>,
+  ) => unknown;
+
+  if (isActionCreator(storeMethod)) {
+    args.push(storeMethod);
+    storeMethod = resultMethod || storeMethod;
+    resultMethod = undefined;
+  }
+
+  const types = (args as unknown as Creators).map(
+    (creator) => creator.type,
+  ) as unknown as ExtractActionTypes<Creators>;
+
+  return {
+    types,
+    storeMethod,
+    resultMethod,
+  };
+}
+
+export function withActionMappers(
+  ...mappers: MapperTypes<ActionCreator[]>[]
+): MapperTypes<ActionCreator[]>[] {
+  return mappers;
+}
+
+export function createReduxState<StoreName extends string, STORE extends Store>(
+  storeName: StoreName,
+  signalStore: STORE,
+  withActionMappers: (
+    store: InstanceType<STORE>,
+  ) => MapperTypes<ActionCreator[]>[],
+): CreateReduxState<StoreName, STORE> {
+  const isRootProvider =
+    (signalStore as ServiceWithDecorator)?.ɵprov?.providedIn === 'root';
+  return {
+    [`provide${capitalize(storeName)}Store`]: (connectReduxDevtools = false) =>
+      makeEnvironmentProviders([
+        isRootProvider ? [] : signalStore,
+        provideEnvironmentInitializer(() => {
+          const initializerFn = (
+            (
+              signalReduxStore = inject(SignalReduxStore),
+              store = inject(signalStore),
+            ) =>
+            () => {
+              if (connectReduxDevtools) {
+                // addStoreToReduxDevtools(store, storeName, false);
+              }
+              signalReduxStore.connectFeatureStore(withActionMappers(store));
+            }
+          )();
+          return initializerFn();
+        }),
+      ]),
+    [`inject${capitalize(storeName)}Store`]: () =>
+      Object.assign(inject(signalStore), { dispatch: injectReduxDispatch() }),
+  } as CreateReduxState<StoreName, STORE>;
+}

package/redux-connector/src/lib/model.ts

@@ -0,0 +1,89 @@
+import { EnvironmentProviders, Signal, Type } from '@angular/core';
+import { DeepSignal } from '@ngrx/signals/src/deep-signal';
+import {
+  SignalStoreFeatureResult,
+  StateSignals,
+} from '@ngrx/signals/src/signal-store-models';
+import {
+  Action,
+  ActionCreator,
+  ActionType,
+  Prettify,
+} from '@ngrx/store/src/models';
+import { Observable, Unsubscribable } from 'rxjs';
+
+export type IncludePropType<
+  T,
+  V,
+  WithNevers = {
+    [K in keyof T]: Exclude<T[K], undefined> extends V
+      ? T[K] extends Record<string, unknown>
+        ? IncludePropType<T[K], V>
+        : T[K]
+      : never;
+  },
+> = Prettify<
+  Pick<
+    WithNevers,
+    {
+      [K in keyof WithNevers]: WithNevers[K] extends never
+        ? never
+        : K extends string
+          ? K
+          : never;
+    }[keyof WithNevers]
+  >
+>;
+
+export type Store = Type<
+  Record<string, unknown> & StateSignals<SignalStoreFeatureResult['state']>
+>;
+
+export type CreateReduxState<StoreName extends string, STORE extends Store> = {
+  [K in StoreName as `provide${Capitalize<K>}Store`]: (
+    connectReduxDevtools?: boolean,
+  ) => EnvironmentProviders;
+} & {
+  [K in StoreName as `inject${Capitalize<K>}Store`]: () => InjectableReduxSlice<STORE>;
+};
+
+export type Selectors<STORE extends Store> = IncludePropType<
+  InstanceType<STORE>,
+  Signal<unknown> | DeepSignal<unknown>
+>;
+export type Dispatch = {
+  dispatch: (
+    input: Action | Observable<Action> | Signal<Action>,
+  ) => Unsubscribable;
+};
+export type InjectableReduxSlice<STORE extends Store> = Selectors<STORE> &
+  Dispatch;
+
+export type ExtractActionTypes<Creators extends readonly ActionCreator[]> = {
+  [Key in keyof Creators]: Creators[Key] extends ActionCreator<infer T>
+    ? T
+    : never;
+};
+
+export interface ActionMethod<T, V extends Action = Action> {
+  (action: V): T;
+}
+
+export interface StoreMethod<
+  Creators extends readonly ActionCreator[],
+  ResultState = unknown,
+> {
+  (action: ActionType<Creators[number]>): ResultState;
+}
+
+export interface MapperTypes<Creators extends readonly ActionCreator[]> {
+  types: ExtractActionTypes<Creators>;
+  storeMethod: StoreMethod<Creators>;
+  resultMethod?: (...args: unknown[]) => unknown;
+}
+
+export type ServiceWithDecorator = {
+  ɵprov?: {
+    providedIn?: string;
+  };
+};

package/redux-connector/src/lib/rxjs-interop/redux-method.ts

@@ -0,0 +1,66 @@
+import { Injector, Signal, inject } from '@angular/core';
+import { rxMethod } from '@ngrx/signals/rxjs-interop';
+import { Observable, Unsubscribable, map, pipe } from 'rxjs';
+
+type RxMethodInput<Input> = Input | Observable<Input> | Signal<Input>;
+
+type RxMethodRef = {
+  destroy: () => void;
+};
+
+type RxMethod<Input, MethodInput = Input, MethodResult = unknown> = ((
+  input: RxMethodInput<Input>,
+  resultMethod: (input: MethodInput) => MethodResult,
+) => RxMethodRef) &
+  RxMethodRef;
+
+export function reduxMethod<Input, MethodInput = Input>(
+  generator: (source$: Observable<Input>) => Observable<MethodInput>,
+  config?: { injector?: Injector },
+): RxMethod<Input, MethodInput>;
+export function reduxMethod<Input, MethodInput = Input, MethodResult = unknown>(
+  generator: (source$: Observable<Input>) => Observable<MethodInput>,
+  resultMethod: (input: MethodInput) => MethodResult,
+  config?: {
+    injector?: Injector;
+  },
+): RxMethod<Input, MethodInput, MethodResult>;
+export function reduxMethod<Input, MethodInput = Input, MethodResult = unknown>(
+  generator: (source$: Observable<Input>) => Observable<MethodInput>,
+  resultMethodOrConfig?:
+    | ((input: MethodInput) => MethodResult)
+    | {
+        injector?: Injector;
+      },
+  config?: {
+    injector?: Injector;
+  },
+): RxMethod<Input, MethodInput, MethodResult> {
+  const injector = inject(Injector);
+
+  if (typeof resultMethodOrConfig === 'function') {
+    let unsubscribable: Unsubscribable;
+    const inputResultFn = ((
+      input: RxMethodInput<Input>,
+      resultMethod = resultMethodOrConfig,
+    ) => {
+      const rxMethodWithResult = rxMethod<Input>(
+        pipe(generator, map(resultMethod)),
+        {
+          ...(config || {}),
+          injector: config?.injector || injector,
+        },
+      );
+      const rxWithInput = rxMethodWithResult(input);
+      unsubscribable = { unsubscribe: rxWithInput.destroy.bind(rxWithInput) };
+
+      return rxWithInput;
+    }) as RxMethod<Input, MethodInput, MethodResult>;
+
+    inputResultFn.destroy = () => unsubscribable?.unsubscribe();
+
+    return inputResultFn;
+  }
+
+  return rxMethod<Input>(generator, resultMethodOrConfig);
+}

package/redux-connector/src/lib/signal-redux-store.ts

@@ -0,0 +1,59 @@
+import { Injectable, inject } from '@angular/core';
+import { rxMethod } from '@ngrx/signals/rxjs-interop';
+import { Action, ActionCreator } from '@ngrx/store';
+import { pipe, tap } from 'rxjs';
+import { MapperTypes } from './model';
+import { isUnsubscribable } from './util';
+
+@Injectable({
+  providedIn: 'root',
+})
+export class SignalReduxStore {
+  private mapperDict: Record<
+    string,
+    {
+      storeMethod: (...args: unknown[]) => unknown;
+      resultMethod?: (...args: unknown[]) => unknown;
+    }
+  > = {};
+
+  dispatch = rxMethod<Action>(
+    pipe(
+      tap((action: Action) => {
+        const callbacks = this.mapperDict[action.type];
+        if (callbacks?.storeMethod) {
+          if (
+            isUnsubscribable(callbacks.storeMethod) &&
+            callbacks.resultMethod
+          ) {
+            return callbacks.storeMethod(action, (a: Action) => {
+              const resultAction = callbacks.resultMethod?.(a) as Action;
+              this.dispatch(resultAction);
+            });
+          }
+
+          return callbacks?.storeMethod(action);
+        }
+
+        return;
+      }),
+    ),
+  );
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  connectFeatureStore(mappers: MapperTypes<ActionCreator<any, any>[]>[]): void {
+    mappers.forEach((mapper) =>
+      mapper.types.forEach(
+        (action) =>
+          (this.mapperDict[action] = {
+            storeMethod: mapper.storeMethod,
+            resultMethod: mapper.resultMethod,
+          }),
+      ),
+    );
+  }
+}
+
+export function injectReduxDispatch() {
+  return inject(SignalReduxStore).dispatch;
+}

package/redux-connector/src/lib/util.ts

@@ -0,0 +1,22 @@
+import { ActionCreator } from '@ngrx/store';
+import { Unsubscribable } from 'rxjs';
+
+export function isUnsubscribable<F extends (...args: unknown[]) => unknown>(
+  fn: F | (F & Unsubscribable),
+): fn is F & Unsubscribable {
+  return !!(fn as F & Unsubscribable)?.unsubscribe;
+}
+
+export function capitalize(str: string): string {
+  return str ? str[0].toUpperCase() + str.substring(1) : str;
+}
+
+export function isActionCreator(action: unknown): action is ActionCreator {
+  return Boolean(
+    typeof action === 'function' &&
+      action &&
+      'type' in action &&
+      action.type &&
+      typeof action.type === 'string',
+  );
+}

package/src/index.ts

@@ -0,0 +1,43 @@
+export { withDisabledNameIndices } from './lib/devtools/features/with-disabled-name-indicies';
+export { withGlitchTracking } from './lib/devtools/features/with-glitch-tracking';
+export { withMapper } from './lib/devtools/features/with-mapper';
+export {
+  ReduxDevtoolsConfig,
+  provideDevtoolsConfig,
+} from './lib/devtools/provide-devtools-config';
+export { renameDevtoolsName } from './lib/devtools/rename-devtools-name';
+export { patchState, updateState } from './lib/devtools/update-state';
+export { withDevToolsStub } from './lib/devtools/with-dev-tools-stub';
+export { withDevtools } from './lib/devtools/with-devtools';
+
+export {
+  createEffects,
+  createReducer,
+  noPayload,
+  payload,
+  withRedux,
+} from './lib/with-redux';
+
+export * from './lib/with-call-state';
+export * from './lib/with-data-service';
+export * from './lib/with-pagination';
+export { setResetState, withReset } from './lib/with-reset';
+export * from './lib/with-undo-redo';
+
+export { withImmutableState } from './lib/immutable-state/with-immutable-state';
+export { withIndexedDB } from './lib/storage-sync/features/with-indexed-db';
+
+/**
+ * @deprecated Use {@link withIndexedDB} instead.
+ */
+export { withIndexedDB as withIndexeddb } from './lib/storage-sync/features/with-indexed-db';
+export {
+  withLocalStorage,
+  withSessionStorage,
+} from './lib/storage-sync/features/with-local-storage';
+export {
+  SyncConfig,
+  withStorageSync,
+} from './lib/storage-sync/with-storage-sync';
+export { emptyFeature, withConditional } from './lib/with-conditional';
+export { withFeatureFactory } from './lib/with-feature-factory';

package/src/lib/assertions/assertions.ts

@@ -0,0 +1,9 @@
+import { ActionsFnSpecs } from '../with-redux';
+
+export function assertActionFnSpecs(
+  obj: unknown,
+): asserts obj is ActionsFnSpecs {
+  if (!obj || typeof obj !== 'object') {
+    throw new Error('%o is not an Action Specification');
+  }
+}