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:

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.

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

// ... 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!

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.

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 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.

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.

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

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.

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.

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:

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.

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

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.

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.

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.

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.

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.