1 of 9

From Scratch

Adding NgRx & Auto-Entity to an App

If you have not used NgRx before, and need to start from scratch, this guide should get you going. Let's start by creating a state module. We recommend creating this module in a root state directory, located at src/app/state. In this directory, create a new state.module.ts file:

state.module.ts

import { NgModule } from '@angular/core';
import { EffectsModule } from '@ngrx/effects';
import { StoreModule } from '@ngrx/store';
import { EntityOperators } from '@briebug/ngrx-auto-entity';

@NgModule({
  imports: [
    StoreModule.forRoot()
    EffectsModule.forRoot([]),
    NgrxAutoEntityModule.forRoot()
  ]
})
export class StateModule {}

Import the NgRx StoreModule and EffectsModule as well as the Auto-Entity NgrxAutoEntityModule. Make sure you call the .forRoot() initializer on each of them to ensure they are properly imported. It is important that the NgrxAutoEntityModule be brought in after the EffectsModule, as this ensures all automatic effects will be properly registered.

The NgRx Auto Entity module is now imported in your application, giving you access to ready-made generic actions, automatic effects, pre-defined reducers and prefabricated facade classes to handle the bulk of your CRUD meeds.

Next, we need to set up the state of our application.

App Interfaces

Create application state interface.

As with any NgRX application, we need to create a new app.state.ts file. We recommend creating this file in a root state directory, located at src/app/state. Import the IEntityState interface from @briebug/ngrx-auto-entity as well, as we will be using it later.

app.state.ts

import { IEntityState } from '@briebug/ngrx-auto-entity';

export interface IAppState {
  // todo: add each entity state interface to our application state interface
}

export type AppState = IAppState;

Define the IAppState interface as normal. We will eventually define each entity state property here. For now, we've left it blank, and will fill it in later on in this quick start.

Remember to export the AppState type so that it may be used throughout the rest of your app.

App Reducer

Create application reducer and meta reducer.

Also like normal NgRX apps, add a reducer map to your app.state.ts file. We recommend creating this file in a root state directory, located at src/app/state.

app.state.ts

import { ActionReducerMap, MetaReducer } from '@ngrx/store';
import { IEntityState } from '@briebug/ngrx-auto-entity';
import { environment } from '../../environments/environment';

export interface IAppState {
  // todo: add each entity state interface to our application state interface
}
export type AppState = IAppState;

export const appReducer: ActionReducerMap<AppState> = {
  // todo: add each entity reducer
};

In versions of NgRx Auto-Entity prior to v0.2, the developer was also responsible for including the autoEntityMetaReducer in the app meta reducers collection. As of version 0.2 of the library, import of the NgrxAutoEntityModule with the .forRoot() call is all that is necessary to include the meta reducer.

If you are upgrading from a version prior to v0.2, you should remove the autoEntityMetaReducer from your app meta reducers!

With NgRx 8, runtime checks have replaced the need to use the storeFreeze meta reducer. As such, a standard state configuration no longer requires any meta reducers.

App State Module

Create application state module.

Now that we have implemented our root state interface & reducer map, we need to update the state module we created in the first step:

state.module.ts

import { NgModule } from '@angular/core';
import { NgrxAutoEntityModule } from '@briebug/ngrx-auto-entity';
import { EffectsModule } from '@ngrx/effects';
import { StoreModule } from '@ngrx/store';

import { appMetaReducers, appReducer } from './app.state';

@NgModule({
  imports: [
    StoreModule.forRoot(appReducer, { metaReducers: appMetaReducers }),
    EffectsModule.forRoot([]),
    NgrxAutoEntityModule.forRoot()
  ]
})
export class StateModule {}

Update the import of the StoreModule. In the forRoot() static method, specify the appReducer and appMetaReducers from your previously created app.reducer as with any normal NgRX app.

If you have any custom effects you may have implemented, include those classes in the EffectsModule import's forRoot() call. Effects are optional with NgRx Auto-Entity, so if you have no effects just pass an empty array.

Entity Model

Create your entity models.

In a departure from classic @ngrx/entity models, each model in your application should be defined as a class (see note below). Here is an example of a Customer model:

customer.model.ts

import { Key } from '@briebug/ngrx-auto-entity';

export class Customer {
  @Key id: number;
  name: string;
  catchPhrase: string;
}

Next we need to import the Key decorator. This is used to specify the property in your model that is the unique identifier. Decorate the id property, which is the unique identifier for Customer model. Read more about entity keys in the advanced documentation.

Note that the model must be a class and not an interface. This is because interfaces are a compile-time only feature of TypeScript, while classes are a native runtime construct in JavaScript.

Entity State

Define the initial entity state

In our example we are building the state for the Customer entity. As such, we've created a new customer.state.ts file located at src/app/state/customer.state.ts.

customer.state.ts

import { Action } from '@ngrx/store';
import { buildState, IEntityState } from '@briebug/ngrx-auto-entity';
import { Customer } from '../models/customer.model';

export const { initialState, selectors, facade: CustomerFacadeBase } = buildState(Customer);

export const {
  selectAll: allCustomers
} = selectors;

export function customerReducer(state = initialState): IEntityState<Customer> {
  return state;
}

Import the buildState function from the ngrx-auto-entity module. This function builds the initial state and selectors for each entity. Call the function by passing in the Customer entity class (note, the class must be passed in!) We use object destructuring on the return type access the initialState , selectors and facade base class from the result of buildState.

We can now further destructure the selectors object to map each type of standard selector to model-specific names for import into other modules:

selectAll selects the Array of entities
selectEntities selects the Dictionary of entities
selectIds selects the Array of entity identifiers (keys)
selectTotal selects the number of entities

Note that retrieving and exporting the selectors are optional if you extract the facade. The facade base class generated by buildState fully encapsulates all of the functionality you will need to interact with your entity state, and we generally recommend only using the facade. Demonstration of how to access selectors directly, such as in the event that you may need to create your own custom selectors, is simply for completeness here.

There are additional selectors bundled as part of each custom entity state built by buildState that may be mapped to state-specific names. Read more in the advanced documentation.

When the selectors object is destructured we alias the selectors with entity-friendly names to avoid naming conflicts.

Finally, we define the customerReducer function. The reducer function accepts two arguments: state, which defaults to the initialState, and the action.

A reducer function is necessary to configure the NgRX standard actionsReducer we defined earlier. For most entities, you will not need to do anything other than return the state passed in, as the autoEntityMetaReducer will handle reduction for you. If custom reduction is required for your apps, it may be handled in these reducers.

Update App State

Update the application state interface.

Now that we have the standard initial implementation for NgRX and Auto-Entity in place, we need to wire our models into our state.

app.state.ts

// ... imports ...
import { Customer } from '../models';
import { customerReducer } from './customer.state.ts'

export interface IAppState {
  customer: IEntityState<Customer>;
}
export type AppState = IAppState;

export const appReducer: ActionReducerMap<AppState> = {
  customer: customerReducer
};

Note that we have added a new customer property to the IAppState interface of type IEntityState<Customer>, which we imported from @briebug/ngrx-auto-entity at the top of the file.

For most basic CRUD states, you will not need to implement any custom state interfaces, effects or reducers. This is the simplicity that NgRX Auto-Entity brings to the table!

After we create the entity reducer, we'll also need to update the appReducer constant to include the customer property (with the customer reducer function as the value). It's important that both properties have the same name.

Entity Service

Create service for handling data interactions with server

In our example we are creating a service for persisting entities via a simple REST API. As such, we've created a new entity.service.ts file and defined an injectable EntityService class.

services/entity.service.ts

import { HttpClient } from '@angular/common/http';
import { Injectable } from '@angular/core';
import { Observable } from 'rxjs';
import { map } from 'rxjs/operators';

import { IAutoEntityService, IEntityInfo } from '@briebug/ngrx-auto-entity';
import { environment } from '../../environments/environment';

@Injectable()
export class EntityService implements IAutoEntityService<any> {
  constructor(private http: HttpClient) {
  }

  load(entityInfo: IEntityInfo, id: any): Observable<any> {
    return this.http.get<any>(
      `${environment.rootUrl}/${entityInfo.modelName}/${id}`
    );
  }

  loadAll(entityInfo: IEntityInfo): Observable<any[]> {
    return this.http.get<any[]>(
      `${environment.rootUrl}/${entityInfo.modelName}`
    );
  }

  create(entityInfo: IEntityInfo, entity: any): Observable<any> {
    return this.http.post<any>(
      `${environment.rootUrl}/${entityInfo.modelName}`, 
      entity
    );
  }

  update(entityInfo: IEntityInfo, entity: any): Observable<any> {
    return this.http.patch<any>(
      `${environment.rootUrl}/${entityInfo.modelName}/${entity.id}`,
       entity
    );
  }

  delete(entityInfo: IEntityInfo, entity: any): Observable<any> {
    return this.http.delete<any>(
      `${environment.rootUrl}/${entityInfo.modelName}/${entity.id}`
    ).pipe(map(() => entity));
  }
}

It's important that each entity service implement the IAutoEntity interface. This interface supports the following methods:

load()
loadAll()
loadMany()
loadPage()
loadRange()
create()
createMany()
update()
updateMany()
replace()
replaceMany()
delete()
deleteMany()

These methods perform the CRUD operators for entity retrieval and persistence.

To create an entity service, we must import the IAutoEntityService and IEntityInfo interfaces. The entity service must implement the IAutoEntityService interface. The IEntityInfo object provides metadata about the entities, which can be used to help build urls if necessary.

Finally, we implement each of the necessary methods for retrieving and persisting an entities.

Your implementation may vary based on the method of persistence and the architecture of your API. Each method is optional, and may be implemented on an as-needed basis for each entity. We provide several options for loading data, as well as options for updating (PATCH) or replacing (PUT) entities. Implement what you need.

Update App Module

Finally, in order for NgRx Auto-Entity to find the entity service you just created, you must provide it in your application state. Providing entity services is slightly different than a normal provider, which simply provides itself as the service class.

app.module.ts

import { NgModule } from '@angular/core';
import { StateModule } from './state';
import { Customer } from './models';
import { EntityService } from './services';

@NgModule({
  imports: [BrowserModule, StateModule],
  providers: [
    { provide: Customer, useClass: EntityService }
  ]
})
export class AppModule {}

Here, we have provided the model type as the provider, and specified the EntityService class as the actual service class via useClass. This is the simplest model for using Auto-Entity, and for simple backend APIs that follow a common pattern, a single service like this may be reused for any number of entities.

provide: Entity, useClass: EntityService

In the event that you have a more complex backend API, or even must integrate with many backend APIs, you may create custom entity services for each entity if necessary, and provide each model with its own unique service class following the same pattern as above.

Finally, import the StateModule we created earlier into your root AppModule to bring in all of your root state, including NgRx Auto-Entity.

And, with that, you are done! You can now start using your entity in your app.

Entity State

Define the initial entity state

In our example we are building the state for the Customer entity. As such, we've created a new customer.state.ts file located at src/app/state/customer.state.ts.

customer.state.ts

import { Action } from '@ngrx/store';
import { buildState, IEntityState } from '@briebug/ngrx-auto-entity';
import { Customer } from '../models/customer.model';

export const { initialState, selectors, facade: CustomerFacadeBase } = buildState(Customer);

export const {
  selectAll: allCustomers
} = selectors;

export function customerReducer(state = initialState): IEntityState<Customer> {
  return state;
}

We can now further destructure the selectors object to map each type of standard selector to model-specific names for import into other modules:

selectAll selects the Array of entities
selectEntities selects the Dictionary of entities
selectIds selects the Array of entity identifiers (keys)
selectTotal selects the number of entities

There are additional selectors bundled as part of each custom entity state built by buildState that may be mapped to state-specific names. Read more in the advanced documentation.

When the selectors object is destructured we alias the selectors with entity-friendly names to avoid naming conflicts.

Finally, we define the customerReducer function. The reducer function accepts two arguments: state, which defaults to the initialState, and the action.