NgRx Toolkit

A bundle containing NgRx Helper classes and functions to simplify the coding experience

Installation

Requires Angular 12.1+ with Ivy enabled and TypeScript 4.3+

npm install @ngrx/{store,effects,entity} @tomtomb/ngrx-toolkit
# or
yarn add @ngrx/{store,effects,entity} @tomtomb/ngrx-toolkit

You probably want to install the store devtools as well

npm install -D @ngrx/store-devtools
# or
yarn add -D @ngrx/store-devtools

Getting started

For a full example have a look at the sandbox application. The toolkit can easily be integrated into an existing NgRx store.

API

These docs are based on version prior to 2.x. The new version included many breaking changes, so please refer to the sandbox app for now!

createActionGroup<Arguments, ResponseData, ErrorResponse>({method, name, scope, isUnique})

Creates an action group containing a call, success and failure action.

Generics

| Generic | Extends | Description | Default | | ------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------- | | Arguments | ArgumentsBase / null | Arguments needed to perform the action | | | ResponseData | | The response if the call was successfully performed | | | ErrorResponse | | Additional error data returned by the HttpErrorResponse error property | unknown |

IMPORTANT: The structure of the Arguments type must be based on the ArgumentsBase type.

export interface ArgumentsBase {
  queryParams?: Record<string | number, unknown>;
  params?: Record<string | number, unknown>;
  body?: unknown;
  sideUpdates?: Record<string, ArgumentsBase>;
}

Arguments

| Argument | Type | Description | Default | | -------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | method | 'GET' / 'POST' / 'PUT' / 'PATCH' / 'DELETE' | HTTP verb of the action | | | name | string | The actions name | | | scope | string | The actions scope | | | isUnique | boolean / undefined | By default all action calls will be stored inside the store. If true, only one action call will be stored. This is useful for things like login actions | false |

Returns

TypedActionObject<Arguments, ResponseData, ErrorResponse>

Example

export const getFoo = createActionGroup<
  { queryParams: { id: string } }, // This object must follow the ArgumentsBase type
  { value: boolean },
  { additionalErrorData: string }
>({
  method: 'GET',
  name: 'Foo',
  scope: 'Sandbox',
});

View the sandbox code

createStoreSlice({actions})

Creates an reducer based on provided TypedActionObjects.

WIP

View the sandbox code

createEntitySelectors({getState, storeSlice})

Creates selector functions to be used by FacadeBase

WIP

View the sandbox code

EffectBase (class)

A abstract class for handling ngrx effects with ActionGroups

constructor(actions, featureService)

Arguments

| Argument | Type | Description | Default | | -------------- | --------- | ------------------------------------------------------------------ | ------- | | actions | Actions | The NgRx Actions Observable | | | featureService | class | The class where the actual http calls are located | |

onActionSwitchMap(action, serviceCall, sideUpdates)

onActionMergeMap(action, serviceCall, sideUpdates)

onActionExhaustMap(action, serviceCall, sideUpdates)

onActionConcatMap(action, serviceCall, sideUpdates)

These methods are all doing the same except for the used observable flattening operator.

RxJS Docs: switchMap, mergeMap, exhaustMap, concatMap

Generics

Generics should NOT be provided by the user. They are filled automatically.

Arguments

| Argument | Type | Description | Default | | ----------- | -------------------- | -------------------------------------------------------------------------------------------------------------- | --------- | | action | TypedActionObject | The action group created via createActionGroup() | | | serviceCall | method | A reference to the actual http call | | | sideUpdates | object / undefined | Additional user defined side effects. These actions will be called after the parent success action gets called | undefined |

Example

@Injectable()
export class SandboxEffects extends EffectBase {
  getFoo$ = this.onActionSwitchMap({
    action: SandboxActions.getFoo,
    serviceCall: this.featureService.getFoo,
  });

  constructor(
    private actions$: Actions,
    private featureService: SandboxService
  ) {
    super(actions$, featureService);
  }
}

View the sandbox code

FacadeBase (class)

A abstract class for dispatching actions and retrieving data from the store

WIP

View the sandbox code

ServiceBase (class)

A abstract class for making http calls with caching built-in

WIP

View the sandbox code