If you are already familiar with NgRx, then adding Auto-Entity to your Angular application is very easy. There are four major steps required to add the module, create new entity state, and provide your entity services.

Step 1: Importing the Module

First things first, you must bring in the NgrxAutoEntityModule into your app module and call the forRoot() method to configure the library.

import { NgrxAutoEntityModule } from '@briebug/ngrx-auto-entity';
// ... other imports ...

@NgModule({
    imports: [
        BrowserModule,
        StoreModule.forRoot(appReducer, { metaReducers: appMetaReducers }),
        EffectsModule.forRoot([]),
        NgrxAutoEntityModule.forRoot() // Add this!
    ]
})
export class AppModule {}

Step 2: Creating your Model and Entity Service

Entity Models

Before you can actually create your state, you will need to create your entity models, as you would normally do. Auto-Entity requires two small changes to how you create models for NgRx.

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

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

First, your models must be classes rather than interfaces (see advanced documentation for more info.) Second, your entity identity must be decorated with the @Key directive. For entities with composite keys, simply decorate each property that is part of the key.

Entity Services

You will also need to create an entity service to handle CRUD behavior for each entity. Entity services may be shared if your API uses a common pattern. Otherwise you may need to implement a service for each entity as you usually do with NgRx.

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));
  }
}

In the example above we have a simple shared entity service that supports a basic REST API where each entity conforms to a simple pattern:

/<rootUrl>/<entityName>[/<key>]

Auto-Entity provides basic entity metadata, such as the model name, in the entityInfo parameter of each entity service method.

Step 3: Providing your Services

Once you have created an entity service or services, you will need to provide them in your app module. With Auto-Entity, services must be provided in a slightly different manner than normal, to ensure that Auto-Entity is able to find entity services dynamically.

import { NgrxAutoEntityModule } from '@briebug/ngrx-auto-entity';
import { Customer, Order } from './models';
import { EntityService } from './services';
// ... other imports ...

@NgModule({
  imports: [
    BrowserModule,
    StoreModule.forRoot(...),
    EffectsModule.forRoot(...),
    NgrxAutoEntityModule.forRoot()
  ],
  // Add a provider for each model, mapping to the relevant entity service:
  providers: [
    { provide: Customer, useClass: EntityService },
    { provide: Order, useClass: EntityService }
  ]
})
export class AppModule {}

In our example here, we are sharing a single entity service, EntityService, for all entities. We must provide each model and useClass to specify the service class to use.

Step 4: Adding your States

Finally, now that you have your models and have provided your entity services, you need to build your state for each model. Add a new state file for each model following the pattern depicted here:

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

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

// A "stub" reducer is required to support AOT
export function customerReducer(state = initialState): IEntityState<Customer> {
  return state;
}

Finally, include your entity states in the AppState interface, and your stub reducers in the action reducer map:

import { IEntityState } from '@briebug/ngrx-auto-entity';
import { Customer, Order } from 'models';
import { customerReducer } from './customer.state.ts'
import { orderReducer } from './order.state.ts'

export interface IAppState {
  // ... other states ...
  customer: IEntityState<Customer>;
  order: IEntityState<Order>;
}
export type AppState = IAppState;

export const appReducer: ActionReducerMap<AppState> = {
  // ... other reducers ...
  customer: customerReducer
  order: orderReducer
};

With that, you are ready to start using your automatic entity state! Continue on to the next section to learn how.

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.

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
};

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

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.

In our CustomerComponent, there are a few methods that exhibit "class envy" which is a kind of anti-pattern. For those not familiar with the concept, class envy occurs when methods of one class are more dependent on functionality within another class. It then becomes prudent to move the method into the class of envy, and if necessary parameterize any input required from the method's previous home.

Our CustomerComponent has two potential candidates for encapsulation within our CustomerFacade class: hasCustomer and onSave. We can easily move this functionality into our facade class and make these behaviors reusable in any component that may require interaction with customer entity state:

export class CustomerFacade extends CustomerFacadeBase {
    constructor(store: Store<AppState>) {
        super(Customer, store);
    }

    hasCustomer(id: number): Observable<boolean> {
        return this.ids$.pipe(
          map((ids: number[]) => ids.indexOf(id) > -1)
        );
    }

    loadIfMissing(id: number): void {
        this.hasCustomer(id)
            .pipe(first())
            .subscribe(exists =>
                exists ? this.load(id) : false
            );
    }

    save(customer: Customer): void {
        if (updatedCustomer.id == null) {
          this.customerFacade.create(customer); // Facades FTW!
        } else {
          this.customerFacade.update(customer); // Facades FTW!
        }
    }
}

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.

Once you have enhanced your facade with functionality that belongs in the facade and not the component, it's time to clean up your component. Using the new functionality we have implemented in our customer facade, our component can become reduced to a simpler form:

@Component({
  selector: 'app-customer',
  templateUrl: './customer.component.html',
  styleUrls: ['./customer.component.scss']
})
export class CustomerComponent implements OnInit {
  constructor(
    private activatedRoute: ActivatedRoute, 
    public customerFacade: CustomerFacade // No store, no selectors!
  ) {}

  ngOnInit() {
    this.activatedRoute.paramMap.pipe(
      filter(params => params.has('id')),
      map(params => +params.get('id'))
    ).subscribe(id => {
        this.customerFacade.selectByKey(id); // Facades FTW!
        this.customerFacade.loadIfMissing(id); // Facades FTW!
    });
  }
}

<div class="customers">
  <div>
    <h2>Customer</h2>
    <app-customer-form 
      #customerForm
      [customer]="customerFacade.current$ | async" 
      (saved)="customerFacade.save($event)">
    </app-customer-form>
    <div>
      <button routerLink="/customers">Cancel</button>
      <button (click)="customerForm.save()" [disabled]="!customerForm.valid">
        Save
      </button>
    </div>
  </div>
</div>

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.

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));
  }
}

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.

For NgRX Auto-Entity to function properly, some minor changes will be required in the way you implement a couple standard bits of code. This includes service implementations and model implementations. These changes are not particularly significant, and for services we provide a lot of meta information to assist you in achieving whatever is necessary for your applications.

As models and services are standard elements of any Angular application, there should be no additional boilerplate code to implement here. These would be implemented regardless. However, be aware of the nuanced changes in how the model and service are used, and the explicit interface requirement for the service.

More significant changes occur when utilizing facades to interact with state. Facades encapsulate the complexities of @ngrx, presenting you with a simplified, logical and more standard API into working with your stateful data.

Now that you have set up state for an entity, it is time to start using it. With NgRx Auto-Entity, if you leverage our pre-fabricated facades, we have made using state about as easy as it can get. Start by creating a facade class that derives from the facade base class generated by your call to buildState:

import { Injectable } from '@angular/core';
import { Store } from '@ngrx/store';
import { AppState } from 'state/app.state';
import { CustomerFacadeBase } from '../state/customer.state';
import { Customer } from '../models';

@Injectable({ providedIn: 'root' })
export class CustomerFacade extends CustomerFacadeBase {
    constructor(store: Store<AppState>) {
        super(Customer, store);
    }

    // TODO: Extend your facade's functionality here!
}

With your facade in hand, inject it into your component and use the facade to interact with your entities:

import { ActivatedRoute } from '@angular/router';
// ... other imports ...
import { CustomerFacade } from '../facades';
import { Customer } from '../models';

@Component({
  selector: 'app-customer',
  templateUrl: './customer.component.html',
  styleUrls: ['./customer.component.scss']
})
export class CustomerComponent implements OnInit {
  customer$: Observable<Customer>;

  constructor(
    private activatedRoute: ActivatedRoute,
    private customerFacade: CustomerFacade // No store, no selectors!
  ) {}

  ngOnInit() {
    this.customer$ = this.activatedRoute.paramMap.pipe(
      filter(params => params.has('id')),
      map(params => +params.get('id')),
      tap(id => {
        this.customerFacade.selectByKey(id); // Facades FTW!
        this.hasCustomer(id)
          .pipe(first())
          .subscribe(exists => {
            if (!exists) {
              this.customerFacade.load(id); // Facades FTW!
            }
          });
      }),
      switchMap(() => this.customerFacade.current$) // Facades FTW!
    );
  }

  hasCustomer(id: number): Observable<boolean> {
    return this.customerFacade.ids$.pipe( // Facades FTW!
      map((ids: number[]) => ids.indexOf(id) > -1)
    );
  }

  onSave(customer: Customer): void {
    if (customer.id == null) {
      this.customerFacade.create(customer); // Facades FTW!
    } else {
      this.customerFacade.update(customer); // Facades FTW!
    }
  }
}

<div class="customers">
  <div>
    <h2>Customer</h2>
    <app-customer-form
      #customerForm
      [customer]="customer$ | async"
      (saved)="onSave($event)">
    </app-customer-form>
    <div>
      <button routerLink="/customers">Cancel</button>
      <button (click)="customerForm.save()" [disabled]="!customerForm.valid">
        Save
      </button>
    </div>
  </div>
</div>

Note the changes here. We imported only the activated route and a facade into our component. Our component does not import any state-related types at all. No actions, no store, no app state interface, none of the usual suspects. All state interactions occur through the facade.

To get started, install the package using npm or yarn:

npm i @briebug/ngrx-auto-entity@~0.2

yarn add @briebug/ngrx-auto-entity@~0.2

Requirements

The following peer requirements must also be installed when using NgRx Auto Entity:

npm i @angular/{common,core}@^8.0 @ngrx/{effects,store}@^8.0 rxjs@^6

yarn add @angular/{common,core}@^8.0 @ngrx/{effects,store}@^8.0 rxjs@^6

NgRx Auto-Entity is a library that simplifies reactive state in @ngrx with reusable generic actions, automated effects & reducers and prefabricated facades.

What is NgRx Auto-Entity?

NgRX Auto-Entity is an add-on library for @ngrx that aims to greatly simplify use of @ngrx and reduce the implementation load of adding @ngrx to your application. We provide a set of ready-made, generic actions that cover most of the common use cases such as loading entities and sets of entities as well as creating, updating or replacing, and deleting entities.

Auto-Entity wires in ready-made effects to handle standard behaviors, as well as provides a core meta reducer that reduces all entity state managed by this library. For most use cases, the implementation burden for you the developer will be limited to basic initial @ngrx setup, creation of models for each entity & creation of services for each entity. This is functionality that would need to be implemented by you the developer regardless.

Where we save you time is by eliminating the need to implement unique sets of CRUD actions for each and every entity, as well as the side effects that handle standard CRUD behavior for each and every entity. This can be a significant amount of development effort for each @ngrx application, and we hope the savings we offer will allow you to focus on solving the critical business needs of your customers.

Further, Auto-Entity generates pre-fabricated Facades around your entity state, allowing you to extract all @ngrx and other state related code from your components, encapsulate them in a facade layer that presents a much simpler, more logical and easier to comprehend and use API for your entities.

With a normal @ngrx application, you are free to implement services however you see fit. There are no explicit requirements by @ngrx, since you are also on the hook to implement the effects as well, and it is your own effects that call your services.

Dynamic Services

NgRX Auto-Entities dynamic nature requires that data services implement the IAutoEntityService<TModel> interface. This interface defines the contract by which Auto-Entity interacts with your services. This interface is described as follows:

export interface IAutoEntityService<TModel> {
  load?(entityInfo: IEntityInfo, keys: any, criteria?: any): Observable<TModel>;
  loadAll?(entityInfo: IEntityInfo, criteria?: any): Observable<TModel[]>;
  loadMany?(entityInfo: IEntityInfo, criteria?: any): Observable<TModel[]>;
  loadPage?(entityInfo: IEntityInfo, page: Page, criteria?: any): Observable<IEntityWithPageInfo<TModel>>;
  loadRange?(entityInfo: IEntityInfo, range: Range, criteria?: any): Observable<IEntityWithRangeInfo<TModel>>;

  create?(entityInfo: IEntityInfo, entity: TModel, criteria?: any): Observable<TModel>;
  createMany?(entityInfo: IEntityInfo, entities: TModel[], criteria?: any): Observable<TModel[]>;

  update?(entityInfo: IEntityInfo, entity: TModel, criteria?: any): Observable<TModel>;
  updateMany?(entityInfo: IEntityInfo, entities: TModel[], criteria?: any): Observable<TModel[]>;

  replace?(entityInfo: IEntityInfo, entity: TModel, criteria?: any): Observable<TModel>;
  replaceMany?(entityInfo: IEntityInfo, entities: TModel[], criteria?: any): Observable<TModel[]>;

  delete?(entityInfo: IEntityInfo, entity: TModel, criteria?: any): Observable<TModel>;
  deleteMany?(entityInfo: IEntityInfo, entities: TModel[], criteria?: any): Observable<TModel[]>;
}

This interface defines a different method that corresponds to each different kind of initiating generic action provided as a part of the NgRX Auto-Entity library. Every method provides entityInfo as the first parameter, which contains metadata about the entity, including its name (based on the class name you defined for the model) as well as its type (the class you defined for the model). Each method also accepts a variety of other parameters, whatever may be necessary to support the unique behavior of that method.

Bulk Operations

In addition to the basic CUD operations, we also support bulk versions of each CUD operation, as well as several options for loading entities. Each of the different load operations support different behavioral semantics, defined by the initiating actions and guiding how the meta reducer handles the data in state.

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.

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.

What is it?

NgRX Auto-Entity aims to provide a seamless means of utilizing a standard set entity actions and effects with minimal repetitive code requirements, while preserving the fundamental nature of NgRX itself. This library is not a replacement for or alternative to NgRX. It works within the standard paradigm that NgRX has set forth, making use of actions, reducers & effects like any other NgRX application.

Generic, reusable, flexible

What Auto-Entity does do is provide a set of ready-made, generic actions for handling all of the standard CRUD operations for entities, so you neither have to write nor generate any of that code yourself. Auto-Entity presents a flexible framework that you may use in its entirety for all of your entity needs, or use piecemeal as necessary in order to achieve your specific goals.

Compatibility with @ngrx/entity

While it is not required and Auto-Entity is an entirely independent library that solely depends on Angular 8 and NgRX 8, Auto-Entity manages state in a manner that is compatible with @ngrx/entity as well, in the event you wish to utilize some of the utilities from that library in your own custom reducers.

With NgRX Auto-Entity, a very small change must be made to how models are implemented. Standard @ngrx models are implemented as interfaces. A normal model used with @ngrx/entity may look like this:

export interface Customer {
    id: number;
    name: string;
}

This simple model would then be wired into @ngrx/entity using the adapter, with a selectId handler to allow entity framework to determine what the primary key of the entity is.

Dynamic Library

Due to the dynamic nature of how NgRX Auto-Entity works, interfaces are insufficient as they are compile-time only types in TypeScript. All of their information is ultimately stripped from the transpiled and optimized JavaScript code that you will ultimately release to a web server. To combat this issue, we must convert our entities to classes, which are a native runtime feature of JavaScript.

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

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

Identifying Keys

In addition to converting our model from an interface to a class, notice that we have also imported Key from @briebug/ngrx-auto-entity and decorated our id property with @Key. This is how the Auto-Entity framework is able to determine which property of the model represents the primary key. As with @ngrx/entity, this key is used to organize and look up entities stored in state.

Composite Keys

A simple but common example of a composite key might be something along the lines of an order line item, which references both an order and a product along with a quantity:

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

export class LineItem {
    @Key orderId: ObjectId;
    @Key productId: ObjectId;
    quantity: number;
}

For more detail about how composite keys work, read the advanced usage documentation on models and keys.

The buildState function has a fairly strait forward and simple signature that requires only two arguments: the model type of the entity you wish to build NgRx state for, and an optional object containing extra initial state:

function buildState<
    TState extends IEntityState<TModel>, 
    TParentState, 
    TModel
>(
    type: ITModelClass<TModel>, 
    extraInitialState?: any
): IModelState<TParentState, TState, TModel> 

You may have noticed that there is a fairly complex generic signature here. This function returns an object that contains all the necessary bits and pieces for you to export selectors, create your own customer selectors, provide initial state to your stub reducer, and of course the facade base class.

The first argument of the function is the model type. In this case, you actually pass in the class itself, not an instance of the class. The second argument is an object that contains any extra initial state you wish to include in addition to the initial state generated for you by the library. The signature for the model class is as follows:

type IModelClass<TModel> = new () => TModel;

As indicated by this interface, all model types must be newable, thus enforcing the class rather than interface requirement for all entity models. Also note that the constructor signature is empty...all models must have an parameterless constructor.

The object returned by buildState is defined by the IModelState interface. This interface encapsulates the initialState, selectors map, and facade, among other things:

export interface IModelState<TParentState, TState, TModel> {
  initialState: TState;
  selectors: ISelectorMap<TParentState, TModel>;
  reducer: (state: TState) => IEntityState<TModel>;
  facade: { new (type: { new (): TModel }, store: Store<any>): IEntityFacade<TModel> };
  entityState: ((state: TParentState) => TState) | (MemoizedSelector<object, any>);
}

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.

While we strive to provide as much commonly implemented functionality as we can, there can always be cases where you, the developer, must take control. Since this library is implemented much like any standard @ngrx application, it allows you to inject your own behavior whenever you need to.

Supporting Custom Behavior

If you require custom behavior for anything, you are always free to implement your own custom actions & custom effects. You are also free to hook into our library and framework by dispatching our actions from your own actions.

This could, for example, allow you to implement a custom search behavior with your own SearchEntityWhatever action and searchEntityWhatever$ effect, and dispatch the Auto-Entity relevant success and failure actions on response, which will be handled by our meta reducer. This would integrate a custom initiating action and data from a custom service call into Auto-Entity managed state.

It is possible to integrate custom actions and effects in a variety of ways, allowing you to leverage the lower level power of NgRx when necessary, while still leveraging the ease of use offered by NgRx Auto-Entity.

The primary interface for an application to interact with state in @ngrx is actions. Actions encapsulate intent, along with the information necessary to perform the requested intent. Actions are one of the key sources of "boilerplate" code with standard @ngrx, and one of the primary areas we aim to simplify with Auto-Entity.

With @ngrx, defining actions tends to require defining action types and action classes "in triplicate", as most actions, particularly entity actions, usually require an "initiator" paired with "result" actions. Initiators are dispatched to request that "some action be performed", while results are dispatched in order to denote that "a requested action completed" with success or failure. Actions, therefor, tend to trifurcate in their actual implementation.

For most Angular applications, services can be provided very simply, simply by including the class in the array of providers in your module. With NgRX Auto-Entity, due to its dynamic nature we must change how services for entities are provided a little bit.

Mapping Model to Service

Instead of registering the service itself directly, we must instead register the model class as the provider, and map it to an entity service via the useClass option. Like so:

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { NgrxAutoEntityModule } from '@briebug/ngrx-auto-entity';

import { AppComponent } from './app.component';

import { Customer } from 'models';
import { CustomerService } from 'services/customer.service';

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule, NgrxAutoEntityModule],
  providers: [
    { provide: Customer, useClass: CustomerService }
  ],
  bootstrap: [AppComponent]
})
export class AppModule {}

When dispatching an action, the model class is specified as the first parameter, and as such the model class is the only thing NgRX Auto-Entity can use to look up the necessary service provider. By mapping the model class to the service class, you are leveraging a standard Angular paradigm to support dynamic service lookup at runtime.

A standard approach to implementing actions with @ngrx requires defining an enumeration of action types, which map a code identifier to a string, implementation of an action class that derives from Action and the concatenation of each action type into an action union that allows proper implementation of a reducer function to reduce actions and the information they contain into your state.

export enum CustomerActionTypes {
    CREATE_CUSTOMER = '[Customer] Create',
    CREATE_CUSTOMER_SUCCESS = '[Customer] Create: Success',
    CREATE_CUSTOMER_FAILURE = '[Customer] Create: Failure',
    // ... additional types ...
}

export class CreateCustomer implements Action {
    readonly type = CustomerActionTypes.CREATE_CUSTOMER;
    
    constructor(public payload: Customer) {}
}

export class CreateCustomerSuccess implements Action {
    readonly type = CustomerActionTypes.CREATE_CUSTOMER_SUCCESS;
    
    constructor(public payload: Customer) {}
}

export class CreateCustomerFailure implements Action {
    readonly type = CustomerActionTypes.CREATE_CUSTOMER_FAILURE;
    
    constructor(public payload: Error) {}
}

// ... additional actions ...

export union CustomerActions = 
      CreateCustomer
    | CreateCustomerSuccess
    | CreateCustomerFailure 
     // ... additional actions to union ...;

Lot of work!

This is a lot of work required just to add the ability to create an entity. Not only do you need the ability to handle the initial create request, but also deal with the success or failure of that request, at the very least. So each "action" generally tends to trifurcate, and thus the action types and action union code trifurcates as well.

Dispatched from Components

Once actions are defined, one may then dispatch them using the @ngrx store. This is usually done within Angular container components:

import {Customer} from 'models';
import {CreateCustomer, LoadCustomers} from 'state/customer.actions';
import {allCustomers} from 'state/customer.selectors';

@Component(...)
export class CustomersComponent implements OnInit {
    customers$: Observable<Customer[]>;
    
    constructor(
        private activatedRoute: ActivatedRoute, 
        private store: Store<AppState>
    ) {}
    
    ngOnInit() {
        this.customer$ = this.store.pipe(select(allCustomers));
        this.refresh();
    }
    
    addCustomer(customer: Customer) {
        this.store.dispatch(new CreateCustomer(customer));
    }
    
    refresh() {
        this.store.dispatch(new LoadCustomers();
    }
    
    // ...
}

For actions to actually do anything, however, you need more. Your work does not end here. You still need effects, and reducers, to make any of these dispatched actions actually perform useful work and update state.

At the core of NgRx Auto-Entity is the buildState function. This utility function encapsulates all the "boilerplate" that you would normally implement yourself when building up state for a new entity. Where in the past you may have manually created an @ngrx/entity adapter, built out your standardized reducer function, and exported a bunch of support elements like initial state, selectors, a key selection handler, etc.

Just "buildState()!"

Now you simply need to call buildState() like so:

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

const { initialState } = buildState(Model);
export function entityReducer(state = initialState): IEntityState<Model> {
    return state;
}

That is about as simple as it gets, unless you need to do anything custom, such as add your own additional support actions, use selectors, or retrieve the prefabricated facade base class so you can keep your state encapsulated.

Rich Functionality

The buildState function provides all of the functionality necessary to take control when you need to, without being complex, and all while still handling most of the work for you. The full expression of a buildState call would be as follows:

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

export const { 
    initialState, 
    selectors, 
    entityState, 
    facade: ModelBaseFacade,
    reducer: modelReducer // Sadly, this does not work with AOT! :'(
} = buildState(Model);

export const {
    selectAll: allModels,
    selectEntities: modelEntities,
    selectIds: modelIds,
    selectTotal: countOfModels,
    // Additional selectors...
} = selectors;

export const firstModel = createSelector(
    entityState,
    (state: IEntityState<Model>) => 
        (entityState.ids?.length && entityState.entities) ? 
            entityState.entities[entityState.ids[0]] : null
);

In addition to providing the initial state version for your stub reducer, the buildState() function also provides a selectors map, an entityState selector to support the creation of custom selectors, a base facade class (source of ultimate power and simplicity!), and finally a ready-made stub reducer (only works with non-AOT builds, sorry!)

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:

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.

When the need arises to create a custom action & custom effects, Auto-Entity can still help you reduce your workload. It may be that you can integrate your actions, effects and data with Auto-Entity managed state, so long as the data is compatible.

Custom Action

As a simple example, you may wish to create a custom action for handling type-ahead lookups that search a given entity.

export const SearchCustomers = createAction(
  '[Customer] Typeahead Search',
  props<{criteria: string }>()
);

Custom Effect

You could then implement your own effect for handling this action to ensure the proper implementation and behavior:

import {Actions, createEffect} from '@ngrx/effects';
import {LoadAllSuccess, LoadAllFailure} from '@briebug/ngrx-auto-entity';
import {SearchCustomers} from 'state/customer.actions';

export class CustomerEffects {
    searchCustomers$ = createEffect(() => this.actions$.pipe(
        ofType(SearchCustomers),
        map(action => action.criteria),
        switchMap(criteria => 
            this.customerService.search(criteria).pipe(
                map(result => new LoadAllSuccess(Customer, result)),
                catchError(err => of(new LoadAllFailure(Customer, err)))
            ))
    ));
    
    constructor(private actions$: Actions, private customerService: CustomerService) {}
}

In this case, we need switchMap semantics...that is, we wish to cancel any previous requests that may have stale information in order to utilize the most up to date search criteria the user may have entered.

Integrate into Auto-Entity Managed State

Take note, however, of the new actions returned by this effect:

this.customerService.search(criteria).pipe(
    map(result => new LoadAllSuccess(Customer, result)),
    catchError(err => of(new LoadAllFailure(Customer, err)))
))

We are returning generic actions! Since these are customers, as long as we have built auto-entity state for the Customer entity, you may combine custom actions you implement yourself with generic actions from the Auto-Entity library.

These actions will ultimately cause the returned customer search results to be reduced into state managed by Auto-Entity for you. You only have to create just one action. Just make sure the shape of the data returned by your custom service is compatible, or is otherwise transformed into a compatible shape.

The lazy loaded feature module counterpart to buildState is, of course, buildFeatureState. This function is similar to buildState, however it is not identical and has one nuanced change:

function buildFeatureState<
  TState extends IEntityState<TModel>, 
  TParentState, 
  TModel
>(
  type: ITModelClass<TModel>,
  featureStateName: string,
  selectParentState: MemoizedSelector<object, TParentState>,
  extraInitialState?: any
): IModelState<TParentState, TState, TModel>;

Two additional arguments must be passed. The second is the name of the feature state, the same name you specify in the createFeatureSelector call. The third argument that must be passed to buildFeatureState is the feature selector for the feature state. The use case would be as follows:

import { createFeatureSelector } from '@ngrx/store';
import { FeatureEntity } from '../models';

export interface IFeatureState {
    featureEntity: IEntityState<FeatureEntity>;
}

export const FEATURE_NAME = 'feature';
export const featureEntityState = createFeatureSelector<IFeatureState>(
    FEATURE_NAME
);

import { buildFeatureState } from '@briebug/ngrx-auto-entity';
import { featureEntityState, FEATURE_NAME } from './feature.state';
import { FeatureEntity } from '../models';

export const { initialState, selectors } = buildFeatureState(
    FeatureEntity,
    FEATURE_NAME,
    featureEntityState
);

Building feature state otherwise works the same as the standard buildState function does. It also provides the entityState for the feature entity, a stub reducer and a facade class.

Differences vs. Root State

When using feature state, there are some nuanced differences that must be taken into account. With NgRx feature state becomes a new state property on the root state, with the name given to the createFeatureState function. This new root state property then encapsulates all other state properties for that particular feature.

{
    routerState: { ... }, 
    customer: { ... }, // Auto-Entity in root state
    products: {
        product: { ... } // Auto-Entity in feature 'products'
    },
    orders: {
        order: { ... }, // Auto-Entity in feature 'orders'
        lineItem: { ... } // Auto-Entity in feature 'orders'
    }
}

Due to these differences, it becomes very important to specify the proper name for both the createFeatureState and the buildFeatureState function calls. Hence the use of a constant in the prior example.

In addition to this little nuance, there is another critical change that must be made. Where root state may easily share the state interface and reducer map in a single file, such as app.state.ts, due to the fact that buildFeatureState depends on the state created by createFeatureState, but the reducer map depends on the reducer that you create with the initialState returned by buildFeatureState, putting the state and the reducer in a single file results in a circular reference problem.

The solution is to simply put the feature state interface and createFeatureState call in one file, say feature.state.ts, and put the reducer map in another, say feature.reducer.ts. This breaks the chain and eliminates the cycle.

In addition to our "standard" loading actions for single, all and many entity retrievals, we also provide two additional loading actions: LoadPage and LoadRange. You may wonder why both, and again it boils down to semantics, behavior. Both are necessary to support different kinds of data loading behavior, as will become evident here.

Loading Ranges

Loading a "range" of data is similar in concept to loading a page of data, however it differs in semantics and actual behavior in the context of NgRx Auto-Entity and the way reduction of page loads are handled vs. the way reduction of ranged loads are handled.

The LoadRange generic action supports a more modern approach to handling very large, and more specifically arbitrarily sized datasets called "infinite scrolling." This technique is usually implemented on lists of items, such as products in a catalog, that may have relatively arbitrary and often-changing total entity counts. When a user scrolls to the bottom of the browser page, the next "range" of products, starting from the last+1 of the currently displayed range, is automatically retrieved from the server and displayed as a continuation of any previously displayed list.

Augmentation of Existing State

When loading a range, unlike loading a page, any newly loaded entities for this type will be merged into existing state, preserving any previously loaded entities and including any newly loaded entities. As with paged loads, this ensures that bandwidth is used efficiently, however keep in mind that for very large data sets, continuous loading of subsequent ranges could eventually require significant amounts of browser memory to store all the information in state. Further, due to the pure (side-effect free) nature by which new versions of state must be created with @ngrx, updating state with a large volume of previously loaded entities may start to become a lengthy operation.

Ranged Load Implementation

Loading ranges of data one at a time with NgRx Auto-Entity is also very easy. Simply use the LoadRange action, or the loadRange method on your entity facades, along with the Range parameter:

this.customerFacade.loadRange({ first: 26, last: 50 });

When implementing your entity service, you will have access to the Range object provided in the initial action, which may be leveraged in your API call:

loadRange(entityInfo: IEntityInfo, {first, last}: Range, criteria?: any)
    : Observable<IEntityWithRangeInfo<Customer>> {
        return this.http.get<Customer[]>(
            `${environment.apiBaseUrl}/api/v1/customers?first=${first}&last=${last}`
        ).pipe(
            map(customers => ({
                rangeInfo: {
                    range: {first, last},
                    totalCount: Infinity
                },
                entities: customers
            }))
        );
    }

Note the use of pipe() on the http call here, and the transformation of the response. Also not the return type of the loadRange method. NgRx Auto-Entity requires additional meta-data about what range was loaded as well as the total number of entities that may be ranged through, in order to store that information in state and make it available to components and your UI (for proper handling of infinite scrolling behavior, for example).

Entities with Range Info

It is important to understand the nature of the data that must be returned by the loadRange method in your entity services. The return type is IEntityWithRangeInfo<TModel> which is defined as so:

export interface IEntityWithRangeInfo<TModel> {
    entities: TModel[];
    rangeInfo: IRangeInfo;
}

The child type of the property rangeInfo, of type IRangeInfo is defined as so:

export declare type RangeValue = string | number | Date;

export interface IStartEndRange {
    start: RangeValue;
    end: RangeValue;
}
export interface IFirstLastRange {
    first: RangeValue;
    last: RangeValue;
}
export interface ISkipTakeRange {
    skip: number;
    take: number;
}
export declare type Range = IStartEndRange | IFirstLastRange | ISkipTakeRange;

export interface IRangeInfo {
    range: Range;
    totalCount: number;
}

Total Counts

Unlike with paged data, where a total count is essential in order to properly calculate how many pages of data there are, ranged data does not necessarily require an exact total count. For use cases where a total count is not required, you may simply specify Infinity or any other constant that allows you to implement your ranged loads and UI behavior properly.

In the event that you do require an actual total count, see the paged loads documentation for various ways to retrieve total counts from the server.

Core to NgRx Auto-Entity is it's internal state structure for each entity. You may have noticed the little IEntityState<TModel> interface floating around prior documentation, including the . This interface is much like the EntityState<T> interface from @ngrx/entity, although more complex as Auto-Entity manages more state for you.

export interface IEntityDictionary<TModel> {
  [key: string]: TModel;
}

export type EntityIdentity = string | number;

export interface IEntityState<TModel> {
  entities: IEntityDictionary<TModel>;
  ids: EntityIdentity[];
  currentEntityKey?: EntityIdentity;
  currentEntitiesKeys?: EntityIdentity[];
  currentPage?: Page;
  currentRange?: Range;
  totalPageableCount?: number;
  isLoading?: boolean;
  isSaving?: boolean;
  isDeleting?: boolean;
  loadedAt?: Date;
  savedAt?: Date;
  deletedAt?: Date;
}

While our internal types are named slightly differently, the structure of our IEntityState interface is name-compatible with the structure @ngrx/entity expects. As such, with perhaps a little type coercion when necessary, it should be possible to utilize @ngrx/entity functionality such as its adapter to update Auto-Entity state...if the need ever arose.

Additional State

You may notice that we track a lot of additional but optional state as well. This includes the current entity, information about the current page or range loaded into state, as well as various flags and timestamps.

Learn this interface if you intend to leverage any of the lower level capabilities of NgRx Auto-Entity. In particular, if you ever provide extra initial state, make sure you know what properties are involved in the event you wish to ADD new state information, or SET existing state information with initial values.

NgRx Auto-Entity provides a relatively simple solution to the action triplet trifurcation conundrum. Make commonly-implemented actions reusable! If there ever was a use case for generics, CRUD entity actions would seem to be as sublimely perfect a case as ever possible. By making actions generic, this allows a simple library of standard CRUD actions to be implemented that could then be easily reused by any number of unique entities.

Actions Made For You

Generic actions are the primary interface with which an application interacts with NgRx Auto-Entity. No need to implement the same pattern of three actions again and again for each and every entity! We have provided all the necessary actions for you. You simply need to dispatch them!

import {Create, LoadAll} from '@briebug/ngrx-auto-entity';
import {Customer} from 'models';
import {allCustomers} from 'state/customer.state';

@Component(...)
export class CustomersComponent implements OnInit {
    customers$: Observable<Customer[]>;
    
    constructor(
        private activatedRoute: ActivatedRoute, 
        private store: Store<AppState>
    ) {}
    
    ngOnInit() {
        this.customer$ = this.store.pipe(select(allCustomers));
        this.refresh();
    }
    
    addCustomer(customer: Customer) {
        this.store.dispatch(new Create(Customer, customer));
    }
    
    refresh() {
        this.store.dispatch(new LoadAll(Customer));
    }
    
    // ...
}

Aside from no longer having to implement your own actions, everything else should be business as usual. Your controllers, when dispatching generic actions from Auto-Entity directly, should look quite familiar.

Standardized Properties

Each generic action's constructors require a standard set of parameters, and some actions may require unique parameters to perform the necessary function. Action constructors are as follows:

constructor(type: { new (): TModel }, public criteria?: any)
constructor(type: { new (): TModel }, public keys: any, public criteria?: any)
constructor(type: { new (): TModel }, public page: Page, public criteria?: any)
constructor(type: { new (): TModel }, public range: Range, public criteria?: any)
constructor(type: { new (): TModel }, public entity: TModel, public criteria?: any)
constructor(type: { new (): TModel }, public entities: TModel[], public criteria?: any)

Note that the first parameter for every action is the model type itself. Also take note that every action accepts optional custom criteria as the final parameter. This same criteria is later included in the arguments for each entity service method, and is transferred from the action to the entity service method exactly as provided when originally dispatching the action.

In addition to the "common" selectors that match @ngrx/entity selectors from the adaptor, NgRx Auto-Entity also provides selectors for accessing all of the extra state it also automatically tracks and manages for you. This includes loading/saving/deleting timestamps as well as flags, currently selected entities, etc.

As with common selectors, these are returned from our buildState utility function as part of the ISelectorMap<TParentState, TModel>. See the documentation on buildState for the full interface definition. You export these selectors the same as any other, via destructuring the selectors object returned by buildState.

Sparse State by Default

It should be noted that all state managed by Auto-Entity is "sparse" or lightly populated. This means that some state, say the current page or range, the total pageable count, even the current entity, may be null or undefined until such time as an action is dispatched that would result in that state becoming populated. As such, expect that depending on the actual state of the application, null or undefined may indeed be the result of using any of the above selectors.

NgRx Auto-Entity offers many ways to load data. The most common of these will usually be the single, all and many loads. A single entity load is pretty strait forward, requiring that you provide a model type and entity key to the Load action. This will retrieve the single entity uniquely identified by the specified key and merge it into the state for that entity.

Loading Everything

Loading all entities of a given type is even more strait forward, as you simply provide the model type to the LoadAll action. This will retrieve every entity of a given type and replace it in the state for that entity.

Loading Many Things

The third common way of loading entities is to load many entities. This is also strait forward and relies on providing at least a model type to the LoadMany action. This will retrieve entities and merge them into the state for that entity.

Custom Criteria

For many loads, you may need to specify criteria other than a primary or uniquely identifying key. All NgRx Auto-Entity actions support optional custom criteria that may be used for this purpose.

The generic actions in the NgRx Auto-Entity library cover all the CRUD bases, as well as a range of loading options, plus some extra useful "utility" actions to cover other common state-related entity tasks. First up, we provide several options for loading data:

Semantics & Behavior

Each load action is imbued with unique semantics and behavioral implications. For example, dispatching a LoadAll action implies that you wish to replace any previously existing entity state for the given model with whatever set of entities is retrieved by the entity service for that model.

Dispatching LoadMany on the other hand implies that you wish to keep any previously existing entity state for the given model, and merge in whatever set of entities is retrieved. Similarly, Load will also merge the retrieved entity into any previously existing state.

Pages vs. Ranges

Further, pages are semantically different than ranges. A page is a discrete slice of a set of entities with a distinct beginning and end. A range on the other hand is a sequential slice of a set of entities that ultimately form a continuous range. When dispatching LoadPage the implication is that you wish to replace any previously existing state for the given model.

The explicit use case here is when the entire set of all entities for a given model is simply too large to fit in memory in a browser (i.e. you may have tens of thousands...millions...billions of records in a database.) Standard case for tables with paging controls.

When dispatching LoadRange on the other hand, the implication is that you wish to join newly loaded ranges of entities onto existing state for the given model. The primary use case here is infinite scrolling, where additional entities are added to previously loaded entities in response to continued vertical scrolling or horizontal panning by a user.

First off, you may be wondering why I am trying to coin a new term here. CURD? "Ain't it supposed to be CRUD?!" you say? Just wait till you hear the full "new" acronym! CURDL! Ah, the cow jokes that could be made... Well, CURDL, because: Create, Update, Replace, Delete & Load! These are the core actions supported by Auto-Entity, and they span the range of common entity-related behaviors.

CURD, not CRUD??

CRUD in the past has stood for Create, Read, Update, Delete. This was a fairly standard term, however one of the goals of NgRx Auto-Entity is to fully support the entire range of HTTP/REST methods currently standardized. This includes both PUT and PATCH, which now have the semantics of "Replace in Whole" vs. "Update in Part." Auto-Entity provides actions to support both methods concurrently, required.

Bulk Actions Supported

Aside from supporting a full set of CURD actions for singular entities, we also support batch/bulk CURD actions allowing the creation, update/replacement and deletion of multiple entities at once.

Beyond the core CURDL actions, Auto-Entity also provides a few utility actions that cover other common entity-state related functionality. This includes an action to clear the state for a given model, as well as select and deselect a particular entity for a given model by reference or key.

Recently added in v0.2 is the ability to select and deselect a set of entities for a given model by references or keys.

Dealing with Entity Keys

For selecting entities by key, if an entity uses a composite key we provide some useful utility functions for retrieving an entities key. For more information about how composite keys are generated in Auto-Entity, read the advanced documentation on models and keys.

When developing complex applications, sometimes it may help to "bundle" multiple actions together or compose many individual actions into sort of a higher order action, an action of actions. Such actions may be handled by custom effects to enforce order-of-execution in a manner that may be much more challenging otherwise.

Use Case

A simple use case might be the creation of an Order that contains LineItems. Depending on the nature of the backend system you must work with, it may be that you must first create an empty order which returns its key, then populate that order, for which you now know the key, with items that relate back to the order. You may have certain timing issues here that are not necessarily easy to solve with the asynchronous nature of the web and NgRx.

Full Order Creation Action

Start by creating a custom action, createFullOrder. This action will require both an Order entity as well as an array of LineItem entities. We only need this one action, as we will ultimately leverage existing Auto-Entity actions down the line. Lets just put this new action in the state file for our order state:

// ... other order state config...

export const createFullOrder = createAction(
    '[Orders] Create Full Order',
    props<{ order: Readonly<Order>, lineItems: ReadonlyArray<LineItem> }>()
);

With this action now in hand, we want to update our Order facade to support creation of a full order with its line items. We can simple add a new method to our facade that will facilitate this new behavior:

import { createFullOrder, OrderFacadeBase } from '../state/order.state';

export class OrderFacade extendes OrderFacadeBase {
    constructor(store: Store<AppState>) {
        super(Order, store);
    }
    
    createOrderWithLineItems(
        order: Readonly<Order>, 
        lineItems: ReadonlyArray<LineItem>
    ): void {
        this.store.dispatch(createFullOrder({order, lineItems});
    }
}

Order Creation Custom Effect

In order to leverage NgRx Auto-Entity here, we will need to create some effects that decompose our createFullOrder action into a generic Create action for the Order, then upon the success of said order creation dispatch additional generic Create actions for each LineItem.

This order of execution is important as creation of a LineItem entity requires knowledge of the Order they belong to, and the key for this order is only known once it is created. Achieving it can be a little tricky, but it tends to be easier in an effect than elsewhere:

export class OrderEffects {
    constructor(private actions$: Actions, private store: Store<AppState>) {}
    
    createFullOrder$ = createEffect(() => 
        this.actions$.pipe(
            ofType(createFullOrder.type),
            tap(({order}) => this.store.dispatch(new Create(Order, order))),
            mergeMap(({order, lineItems}) => 
                this.actions$.pipe(
                    ofEntityType(Order, EntityActionTypes.CreateSuccess),
                    filter(action => action.entity.poNumber === order.poNumber),
                    map(action => ({ order: action.entity, lineItems })),
                    tap(({order, lineItems}) => 
                        lineItems.reduce((_, item) => 
                            this.store.dispatch(new Create(LineItem, {
                                ...item,
                                orderId: order.id
                            }))
                        )
                    )
                )
            )
        )
    , {dispatch: false});
}

This new effect will now handle dispatching of Create generic actions for our new Order, then wait for a CreateSuccess generic action from Auto-Entity to be dispatched for the Order entity type, and upon said dispatch occurring will then dispatch additional Create generic actions for each of the LineItems for that order.

Best in an Effect

This careful timing of dispatches may be achieved elsewhere, such as a component or a facade, however the interactions will generally be more complex and disjoint than when handled in a cohesive effect. Leverage the full power of NgRx when you need to!

Much like @ngrx/entity, when you build state for a new entity with NgRx Auto-Entity we provide a set of ready-made common selectors. These selectors allow you to retrieve the state Auto-Entity manages for you.

These selectors are returned from our buildState utility function as a ISelectorMap<TParentState, TModel>. See the reference documentation for the full interface definition and the complete list of selectors.

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!

Selectors are generated for a given entity when you call buildState with a model class. The selectors may be initially destructured out of the object returned by buildState. From there, you may choose to simply export the entire selectors object, or further destructure the selectors and export only those you need to use:

import {buildState} from '@briebug/ngrx-auto-entity';
import {Customer} from 'models';

const { selectors } = buildState(Customer);

export const {
    selectAll: allCustomers,
    selectCurrentEntity: currentCustomer
} = selectors;

Selectivity with Selectors

It is not required to export all selectors. Through destructuring, it is recommended that you only export the selectors that you will actually use within your application. Further, we highly recommend renaming each selector to utilize the name of the model they relate to.

At BrieBug, we have moved away from naming selectors selectWhatever in an attempt to maintain DRY principal:

this.store.pipe(select(selectAllCustomers)); // Repetition of 'select' here. :(
this.store.pipe(select(allCustomers)); // No repetition, natural language flow! :)

While NgRx Auto-Entity provides quite a bit of ready-made functionality, tracking state for many of the most common elements of entity state including the usual "custom" aspects such as the currently selected entity, loading flags, etc. there may be cases where you still need to create a custom selector. Even when using prefabricated facades, once you get into extending those facades, custom selectors are not uncommon.

import { createSelector } from '@ngrx/store';
import { buildState } from '@briebug/ngrx-auto-entity';

const { 
    selectors: {
        selectIds,
        selectEntities
    }, 
    entityState
} = buildState(Customer);

export const firstCustomer = createSelector(
    selectIds,
    selectEntities,
    (ids, entities) => 
        ids?.length && entities ? entities[ids[0]] : null;
);

Nothing New Here

Custom selectors are implemented as you have always implemented them. Nothing new or special there. Parameterized selectors may also still be used. Make sure to extract the entityState property from the return value from buildState if you need to access the whole state (including all of the additional data tracked by Auto-Entity) for a given entity.

Parameterized Selectors Supported

Note that it is also possible to create parameterized selectors with @ngrx. You may still implement parameterized selectors with Auto-Entity as well:

export const customerByName = createSelector(
    selectIds,
    selectEntities,
    (ids, entities, props) => 
        ids.map(id => entities[id])
           .find(entity => entity.name === props.name);
);

Follow the necessary precautions and best practices outlined in the ngrx.io documentation when using parameterized selectors. There are some important caveats to be aware of with their use.

In addition to our "standard" loading actions for single, all and many entity retrievals, we also provide two additional loading actions: LoadPage and LoadRange. You may wonder why both, and again it boils down to semantics, behavior. Both are necessary to support different kinds of data loading behavior, as will become evident here.

Paged Data

Loading of paged data is a common practice that dates back many years, in fact decades. It is a fundamental kind of data load, and extensive research has been done as well as dedicated features to support paged data have been integrated into data storage solutions.

Loading pages of data, rather than loading complete sets of data, is often essential. This is especially true in the modern world where we frequently must acquire and work with immense datasets that can number in the millions, billions...even trillions of records. With such numbers, it should be obvious that loading all entities for such datasets would be problematic at best, assuming it was even possible in the first place. Large datasets will usually consume immense space, including immense bandwidth and immense amounts of memory in a browser.

Replacement of Existing State

When loading a page, any previously loaded entities for this type will be replaced in by the new page of entities retrieved. This ensures that bandwidth and browser memory space is used efficiently, and that memory is not wasted trying to store an ever-growing number of entities as a user cycles through pages in your UI.

Paged Load Implementation

Loading pages of data one at a time with NgRx Auto-Entity is quite easy. Simply use the LoadPage action, or the loadPage method on your entity facades, along with the Page parameter:

this.customerFacade.loadPage({ page: 2, size: 25 });
this.customerFacade.loadPage({ page: 2 }); // Size may be optional

When implementing your entity service, you will have access to the Page object provided in the initial action, which may be leveraged in your API call:

loadPage(entityInfo: IEntityInfo, {page=1, size=25}: Page, criteria?: any)
    : Observable<IEntityWithPageInfo<Customer>> {
        const skip = (page-1) * size;
        const take = size;
        
        return this.http.get<Customer[]>(
            `${environment.apiBaseUrl}/api/v1/customers?skip=${skip}&take=${take}`
        ).pipe(
            map(customersMeta => ({
                pageInfo: {
                    page: {
                        page: customersMeta.pageNo,
                        size
                    },
                    totalCount: customersMeta.totalRecordCount
                },
                entities: customersMeta.customers
            }))
        );
    }

Note the use of pipe() on the http call here, and the transformation of the response. Also not the return type of the loadPage method. NgRx Auto-Entity requires additional meta-data about which page was loaded as well as the total number of entities that may be paged through, in order to store that information in state and make it available to components and your UI (for proper rendering of paging controls, for example).

Entities with Page Info

It is important to understand the nature of the data that must be returned by the loadPage method in your entity services. The return type is IEntityWithPageInfo<TModel> which is defined as so:

export interface IEntityWithPageInfo<TModel> {
    entities: TModel[];
    pageInfo: IPageInfo;
}

The child type of the property pageInfo, of type IPageInfo is defined as so:

export interface IPage {
    page: number;
    size: number;
}
export declare type Page = IPage;

export interface IPageInfo {
    page: Page;
    totalCount: number;
}

Separate Total Count Call

One way or another, you must be able to provide the above information for each paged load. You may simply prefer to reflect back the original page information sent in for the IPageInfo page property, however usually the totalCount must be returned by the server in one way or another. It need not necessarily be on the same call, an additional call may be performed to retrieve the total count of entities:

loadPage(entityInfo: IEntityInfo, {page=1, size=25}: Page, criteria?: any)
    : Observable<IEntityWithPageInfo<Customer>> {
        const skip = (page-1) * size;
        const take = size;
        
        return this.http.get<Customer[]>(
            `${environment.apiBaseUrl}/api/v1/customers?skip=${skip}&take=${take}`
        ).pipe(
            withLatestFrom(
                this.http.get<{totalRecords: number}>(
                    `${environment.apiBaseUrl}/api/v1/customers?totalOnly=true`
                );
            )
            map(([customers, total]) => ({
                pageInfo: {
                    page: { page, size },
                    totalCount: total.totalRecords
                },
                entities: customers
            }))
        );
    }

Content-Range HTTP Header

Another possibility, although potentially not canonical standard depending on exactly how you implement it, might be to use the HTTP Content-Range header in your responses to support additional metadata about page info, without having to include it in the body of the response. This header is normally used with a unit of bytes, however technically speaking the units can be arbitrary (such as, say, records or entities):

loadPage(entityInfo: IEntityInfo, {page=1, size=25}: Page, criteria?: any)
    : Observable<IEntityWithPageInfo<Customer>> {
        const skip = (page-1) * size;
        const take = size;
        
        return this.http.get<HttpResponse<Customer[]>>(
            `${environment.apiBaseUrl}/api/v1/customers?skip=${skip}&take=${take}`
        ).pipe(
            map(response => ({
                customers: response.body,
                contentRange: response.headers.has('Content-Range') ? 
                    // <units> <start>-<end>/<size>
                    // entities 0-25/102942
                    // records 25-50/102942
                    response.headers.get('Content-Range').split('/')[1] : 0
            }),
            map(({customers, total}) => ({
                pageInfo: {
                    page: { page, size },
                    totalCount: +total
                },
                entities: customers
            }))
        );
    }

NgRx Auto-Entity will generate a new facade class for you dynamically whenever you call buildState. You may optionally destructure this facade class from the response, along with destructuring other core aspects of your new state:

export const { initialState, facade: CustomerFacadeBase } = buildState(Customer);
export function customerReducer(state = initialState): IEntityState<Customer> {
    return state;
}

The above is the recommended and most minimal use case for the building states with Auto-Entity. For most use cases, nothing beyond the initialState and facade class should be required.

We also recommend renaming for export the name facade into a more appropriate, unique name for a base facade class for your entity. In the example here, we have renamed the facade to CustomerFacadeBase.

Extending a Concrete Facade

Once you have your base facade class, you will need to extend the proper facade class from it. Extension is required in order to provide the facade base class with the necessary services. Since our facades are dynamically generated classes created by a simple function, we are unable to leverage the Angular Injector directly.

export class CustomerFacade extends CustomerFacadeBase {
    constructor(private store: Store<AppState>) {
        super(Customer, store);
    }
}

The above is the most minimal use case for a facade. The only requirement is to call super() from within your constructor, and pass in the entity model type as well as the store. From here, you may start using all of the ready-made functionality the base facade offers, without any additional work.

If you do encounter the need to implement custom selectors, it is highly recommended that you integrate them into your entity facades, rather than consume them directly from components. This does of course assume you are using entity facades, and if you have foregone the use of facades then you may use custom selectors as you normally do with @ngrx.

Property or Accessor Method

After creating a custom selector, you will need to determine whether a property or accessor method is appropriate for this new selector in your facade. For non-parameterized selectors, a property is usually most appropriate.

For parameterized selectors, an accessor method may be more appropriate. If however the possible range of input to your parameters is limited then multiple properties that each encompass a particular use case might still be the best option.

Adding a Custom Property

Continuing on with our firstCustomer selector from the previous section, adding this to a CustomerFacade should be very strait forward:

import {firstCustomer, CustomerFacadeBase} from 'state/customer.state';
import {Customer} from 'models';

export class CustomerFacade extends CustomerFacadeBase {
    constructor(store: Store<AppState>) {
        super(Customer, store);
    }
    
    get firstCustomer$(): Observable<Customer> {
        return this.store.pipe(select(firstCustomer));
    }
}

Adding a Custom Accessor Method

With a parameterized selector like our prior customerById example, we should use a method instead of a property to allow passing in the id of the customer to select:

import {firstCustomer, customerByName, CustomerFacadeBase} from 'state/customer.state';
import {Customer} from 'models';

export class CustomerFacade extends CustomerFacadeBase {
    constructor(store: Store<AppState>) {
        super(Customer, store);
    }
    
    get firstCustomer$(): Observable<Customer> {
        return this.store.pipe(select(firstCustomer));
    }
    
    customerByName$(name: string): Observable<Customer> {
        return this.store.pipe(select(customerByName, {name});
    }
}

Special attention should be called to the custom parameter of all NgRx Auto-Entity generic actions. This parameter is optional and is always the last parameter of any action constructors. The availability of custom criteria for all actions is critical to supporting more advanced use of Auto-Entity, more complex API calls, support for hierarchical API structures, etc.

Sending custom criteria is entirely optional, but is an option for every action. This includes not only loads, but also CURD actions as well. If the set of entities to be retrieved, updated, replaced or deleted must be restricted by criteria beyond simply a uniquely identifying key, then custom criteria should be used.

Hierarchical Queries

Custom criteria should also be used to identify parent keys or relation keys in hierarchical API paths. Many REST APIs often relate entities hierarchically by nesting child entities under the paths of parent entities:

Customer Orders

GET /api/v1/customers/:customerId/orders

Retrieves all the orders placed by the specified customer

Path Parameters

[{
    orderId: number;
    customerId: number;
    datePlaced: Date;
    dateFulfilled?: Date;
    dateShipped?: Date;
}]

In the case of the above example REST API, the customerId is not a unique identifying key of the entity Order. As such it would be inappropriate to specify the customerId as the key in a Load action. Instead, the customerId should be passed as part of custom criteria:

this.ordersFacade.loadAll({ customerId: 1 });

The custom criteria with customerId will be made available as the criteria parameter to the corresponding loadAll entity service method down the line, allowing you to make a proper call to the API:

loadAll(entityInfo: IEntityInfo, criteria?: { customerId: number }): Observable<Order[]> {
    return this.http.get<Order[]>(
        `${environment.apiBaseUrl}/api/v1/customers/${criteria.customerId}/orders`
    );
}

Partial Retrievals

Some times you may wish to retrieve restricted sets of entities based on criteria. Perhaps by date ranges. This is another use case for criteria, the fundamental case. If we expand our above API with additional custom query string parameters for the various order related dates:

Customer Orders w/ Criteria

GET /api/v1/customer/:customerId/orders?datePlaced&dateFulfilled&hasDateFullfilled

Retrieves all the orders placed by the specified customer, filtered by optional criteria

Path Parameters

Query Parameters

[{
    orderId: number;
    customerId: number;
    datePlaced: Date;
    dateFullfilled?: Date;
    dateShipped?: Date;
}]

We might handle these optional criteria with a more advanced implementation of our Entity service for Orders. First, our initial dispatch:

this.ordersFacade.loadMany({ 
    customerId: 1, 
    datePlaced: '2019-06-01', 
    wasFullfilled: true 
});

And our custom loadMany implementation in our entity service:

interface LoadCriteria {
    customerId: number;
    datePlaced?: string;
    dateFullfilled?: string;
    wasFullfilled?: boolean;
}

loadMany(entityInfo: IEntityInfo, criteria?: LoadCriteria): Observable<Order[]> {
    let url = `${environment.apiBaseUrl}/api/v1/customers/{criteria.customerId}/orders`;
    if (criteria.datePlaced || criteria.dateFullfilled || criteria.wasFullfilled) {
        url = `${url}?`;
        url = criteria.datePlaced ? `${url}datePlaced=${criteria.datePlaced}&` : url;
        url = criteria.dateFullfilled ? `${url}dateFullfilled=${criteria.dateFullfilled}&` : url;
        url = criteria.wasFullfilled ? `${url}wasFullfilled=${criteria.wasFullfilled}` : url;
    }
    return this.http.get<Order[]>(url);
}

With custom criteria, we can handle any kind of backend API, even complex ones with custom and dynamic parameters. Note the use of loadMany here instead of loadAll...this is an important distinction with partial data loads vs. full data loads, which I'll be going into more detail on in the next section.

While NgRx Auto-Entity can do a lot for you, there may be times when you need to perform more complex operations than are supported with the ready-made generic actions of Auto-Entity. In such situations, you can always fall back onto "classic" NgRx and leverage all the raw power it provides.

There are a few scenarios where you may need to fall back onto regular old NgRx. Purely custom functionality that doesn't fall into the "entity" mold may simply require a "full on NgRx." The top use case that comes to mind would be your average user login scenario, which often requires actions and server interactions that fall into more of a challenge/response sort of paradigm than an entity CRUD paradigm.

Purely Custom NgRx

In the auth case, aside from just Load(User, id) the actual act of Authentication will usually be a custom action, custom effect, probably a custom service method (although it is fine to add additional functionality to entity services if you so require! Entity services may be provided directly as well as via the model if necessary.)

Composition or Bundling

There are a couple other scenarios where you may need to implement some custom functionality, however you may also still be able to leverage Auto-Entity to one degree or another. Such cases may include say a bundling complex behaviors such as a multi-entity save into a single action, and leveraging a custom effect to ultimately dispatch the necessary generic actions to work on each individual entity behind the scenes.

Workflows

Another case may be when you need a workflow, where one action begets another action, and so on. In this case custom effects may be leveraged to watch for particular generic actions dispatched for particular entities, and in turn dispatch other generic or custom actions for other entities or behaviors. This is where the power of reactive programming really comes into play.

Prefabricated facades in NgRx Auto-Entity expose all the necessary properties and methods to allow you to fully leverage all of the state, actions and selectors Auto-Entity manages. Once you have extended a class from the base facade class, you may leverage all of this functionality without any additional effort.

Observable Data Properties

Each entity facade exposes a number of properties that wrap NgRx state selections, exposing the streaming data within. Each of these properties returns and Observable of the appropriate type based on the state Auto-Entity tracks. The available properties on every entity facade include the following:

Familiar Functionality

All of these properties are encapsulating functionality you may already be familiar with. In the past with plain old NgRx, you might have done something like the following:

this.customers$ = this.store.pipe(select(allCustomers));

This is in fact what all of the entity facade properties are doing for you. We simplify the above repetitive procedure so you may simply access a property rather than have to bring in the store, pipe and select yourself:

get all$(): Observable<TModel> {
    return this.store.pipe(select(selectAll));
}

Still Observable

Since all of our entity facade properties are observables, you are still free to use .pipe() on them as necessary, and leverage the full power of RxJs and reactive programming.

this.customers$ = this.customerFacade.all$.pipe(
    withLatestFrom(this.activatedRoute.paramMap),
    map(([customers, params]) => [customers, params.get('search')]),
    map(([customers, search]) => 
        customers.map(customer => customer.name.match(search))
    )
);

When it comes to using custom selectors, they are used the same as any prefabricated facade property or method. As a quick example, our prior two custom selections added to our CustomerFacade may be used as so:

@Component({
  selector: 'app-customer-by-name',
  templateUrl: './customer-by-name.component.html',
  styleUrls: ['./customer-by-name.component.scss']
})
export class CustomerByNameComponent implements OnInit {
  customer$: Observable<Customer>;

  constructor(
    private activatedRoute: ActivatedRoute, 
    private customerFacade: CustomerFacade
  ) {}

  ngOnInit() {
    this.customerFacade.loadAll(); // This may be called elsewhere instead of here
  
    this.customer$ = this.activatedRoute.paramMap.pipe(
      filter(params => params.has('name')),
      map(params => params.get('name')),
      switchMap(name => this.customerFacade.customerByName$(name))
    );
  }
}

Prefabricated facades in NgRx Auto-Entity expose all the necessary properties and methods to allow you to fully leverage all of the state, actions and selectors Auto-Entity manages. Once you have extended a class from the base facade class, you may leverage all of this functionality without any additional effort.

Action Dispatching Methods

In addition to properties for each selection, entity facades also expose a number of methods that wrap NgRx action dispatch calls. Each of these methods handles creation and subsequent dispatch of the appropriate generic action, including handling all the type information. The available methods on every facade include:

Familiar Functionality

All of these methods, as with the properties, are encapsulating functionality you may already be familiar with. In the past with plain old NgRx, you might have done something like the following:

this.store.dispatch(new LoadAll(Customer, { organizationId: orgId }));

This is in fact what all of the entity facade methods are doing for you. We simplify the above repetitive procedure so you may simply call a method with just the bare bones required arguments, rather than have to bring in the store, dispatch and construct new actions yourself:

loadAll(criteria?: any): void {
  this.store.dispatch(new LoadAll(this.modelType, criteria));
}

The model type is tracked when you extend the facade base class with your own concrete implementation:

export class CustomerFacade extends CustomerFacadeBase {
    constructor(private store: Store<AppState>) {
        super(Customer, store); // Passing Customer here sets this.modelType
    }
}

To use one of these properties in your component, simply inject your facade class and assign the property to a local observable:

export class CustomersComponent implements OnInit {
    customers$: Observable<Customer[]>;
    currentCustomer$: Observable<Customer>;
    isLoading$: Observable<boolean>;
    
    constructor(private customerFacade: CustomerFacade) {
    }
    
    ngOnInit(): void {
        this.customers$ = this.customerFacade.all$;
        this.customer$ = this.customerFacade.current$;
        this.isLoading$ = this.customerFacade.isLoading$;
        
        this.customerFacade.loadAll();
    }
    
    select(customer: Customer): void {
        this.customerFacade.select(customer);
    }
}

Use the Async Pipe

We highly recommend following NgRx best practices here to avoid subscribing directly to any observable on an entity facade. Instead, use the async pipe from Angular in your templates, and follow container/presenter model for your component architecture:

<div class="customers" *ngIf="isLoading$ | async; else #loading">
    <app-customer-list 
        [customers]="customers$ | async" 
        (selected)="select($event)">
    </app-customer-list>
    <app-customer-detail 
        *ngIf="(customer$ | async) as customer"
        [customer]="customer">
    </app-customer-detail>
</div>
<ng-template #loading>
Loading customers...
</ng-template>

In some cases, assigning facade properties to other properties on your component classes may itself be somewhat overly complex. There is not necessarily an explicit need to have observable properties on the component itself.

Light Weight Containers

For container components such as the above Customers component, there is nothing of particular note in the component itself that isn't simply replicating functionality we already have in the facade. We could simply expose the facade to the template by making it public in the constructor:

export class CustomersComponent {    
    constructor(public customers: CustomerFacade) {}
}

Facade in the Template

Then simply use the facade within the template, as it already provides all of the same exact functionality:

<div class="customers" *ngIf="customers.isLoading$ | async; else #loading">
    <app-customer-list 
        [customers]="customers.all$ | async" 
        (selected)="customers.select($event)">
    </app-customer-list>
    <app-customer-detail 
        *ngIf="(customers.current$ | async) as customer"
        [customer]="customer">
    </app-customer-detail>
</div>
<ng-template #loading>
    Loading customers...
</ng-template>

Note just how simple this container component is now that we have leveraged the full capabilities of a generated auto-entity facade! And note just how little code you really had to write.

An alternative use case to the bundling of actions or action composition, where related data must be handled with explicit order of execution, is workflows. A workflow is the use case where the result of one action may result in the dispatching of another, perhaps with derived data, perhaps with otherwise unrelated data.

Let's face it. Sometimes we have to work with odd data structures in order to make things work. One of the key tenants of NgRx is denormalization of data, so we may have multiple collections that contain entities related to each other.

Use Case

A potential example use case here, however contrived it may be (although not necessarily unheard of, especially for those who work with existing, well-established and particularly older backends), might be tracking the things a user favorites with joiner records in a many-to-many table. Lets say we have a single-user app that needs to easily display this information. We may want to track an isFavorite flag on our things, and update said flag whenever our joiner entities are created or deleted.

Chaining Actions

Unlike our full order creation example, where we needed to track a group of entities together and manage the order of execution for their creation, this use case requires that we chain one action off of the success of another.

We do not need any new custom actions for this use case, however we do need some effects. Let's say we have Posts that a user may Like. The actual likes are tracked as a join between the postId and the userId and are created and deleted as independent entities in the database. For simplicity of processing this data in our UI and UI performance, we track an wasLiked flag on our Post entities in state.

export class LikeEffects {
    constructor(private actions$: Actions, private store: Store<AppState>) {}
    
    createSuccess$ = createEffect(() => 
        this.actions$.pipe(
            ofEntityType(Like, CreateSuccess),
            map(action => action.entity),
            withLatestFrom(this.store.pipe(select(allPosts))),
            map(([like, allPosts]) => 
                allPosts.find(post => post.id === like.postId)
            ),
            filter(post => !!post),
            map(post => new LoadSuccess(Post, {...post, wasLiked: true}))
        )
    );
    
    deleteSuccess$ = createEffect(() => 
        this.actions$.pipe(
            ofEntityType(Like, DeleteSuccess),
            map(action => action.entity),
            withLatestFrom(this.store.pipe(select(allPosts))),
            map(([like, allPosts]) => 
                allPosts.find(post => post.id === like.postId)
            ),
            filter(post => !!post),
            map(post => new LoadSuccess(Post, {...post, wasLiked: false}))
        )
    );
}

Understanding Workflows

These two effects are fairly strait forward. They look for the success of prior Create or Delete actions dispatched for Like entities. They then grab all the posts currently loaded into state, find the post related to the like, and dispatch a LoadSuccess. This may seem odd, however we do not actually wish to load a Post from the database, we only wish to update the related Post in state...the goal is efficiency and performance.

The Auto-Entity meta reducer handles LoadSuccess in a specific way...it merges the specified entity into state. If it already exists, it is updated, if not it is added. Since creating a Like marks a post as liked for the specified user, we know we can set wasLiked to true when a Like is successfully created. Similarly, we know we can set wasLiked to false when a Like is successfully deleted.

Further, if either the Create or Delete of a Like fails, due to network connectivity issues, a server outage, etc. then we do not update the Post in state, which might incorrectly reflect to the user their status for the given post.

Higher Order Facade

Ok, now that we have the necessary effects to handle these state updates, let's update our facades to support the new behavior here. In fact...let's create a new facade of a special type, what we like to call a Manager, to handle the composition of information from multiple entities into another.

This is just a matter of code organization, and for simpler applications adding the necessary method to an existing facade, say the PostFacade. For larger applications, segregating out behavior that relies on multiple entities can help keep facades small and manageable.

@Injectable({providedIn: 'root'})
export class PostManager  {
    constructor(
        private store: Store<AppState>, 
        private likeFacade: LikeFacade
    ) {}
    
    likePost(post: readonly Post, user: readonly User): void {
        this.likeFacade.create({ postId: post.id, userId: user.id});
    }
}

We could try to simplify things here. We could, say, bring in the PostFacade here as well, and right after creating our like we update the Post and directly set the wasLiked flag to true. We could...

When we create something, such as our Like joiner entity here, that dispatches the request to create the entity. This request may be fulfilled at a later time, but it is not guaranteed to be fulfilled by the time we get to the next line of code. It may in fact never be fulfilled depending on network or server conditions.

By creating a simple workflow with effects and subsequent action dispatches, we are able to enforce and maintain the integrity of our data in our application. We only update the wasLiked flag once the CreateSuccess or DeleteSuccess actions for the liked Post have been dispatched, something much harder to do in a facade or component.

Customer & Address

import { Key } from '@briebug/ngrx-auto-entity';
import { Address } from './address.model';

export class Customer {
    @Key id?: number;
    name: string;
    title: string;
    email: string;
    handles?: {
        twitter?: string;
        facebook?: string;
    }
    addressId?: number;
}

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

export class Address {
    @Key id?: number;
    street1: string;
    street2: string;
    city: string;
    state: string;
    zip: string;
}

Order & Line Item

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

export type ISODate = string; // YYYY-MM-DDTHH:mm:ss-ZZ:zz
export type Never = 'never';

export enum OrderStatus {
    PENDING = 'pending',
    ONHOLD = 'on-hold',
    PARTIAL = 'partial-fill',
    FILLED = 'filled',
    PARTSHIP = 'partial-shipped',
    SHIPPED = 'shipped',
    CLOSED = 'closed'
}

export class Order {
    @Key id?: number;
    purchaseOrderNo: string;
    status: OrderStatus;
    dateCreated: ISODate;
    dateClosed: ISODate | Never;
    history: OrderHistory[];
}

export class OrderHistory {
    dateOfAction: ISODate;
    action: string;
    newStatus: OrderStatus;
}

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

export class LineItem {
    @Key orderId: number;
    @Key productId: number;
    quantity: number;
    isRush: boolean;
}

Barrel

export * from './address.model';
export * from './customer.model';
export * from './lineItem.model';
export * from './order.model';

Here is the full excerpt of code that you had to write to implement our customers container component from the facade examples. We are assuming code module imports are handled by the IDE and are not something you would necessarily "write" yourself. Standard Angular decorator content excluded as it is usually generated for you.

export const { initialState, facade: CustomerFacadeBase } = buildState(Customer);
export function customerReducer(state = initialState): IEntityState<Customer> {
    return state;
}

@Injectable({providedIn: 'root'})
export class CustomerFacade extends CustomerFacadeBase {
    constructor(private store: Store<AppState>) {
        super(Customer, store);
    }
}

@Component({...})
export class CustomersComponent {
    constructor(
        public customers: CustomerFacade, 
        public router: Router,
        public route: ActivatedRoute
    ) {
        customers.loadAll();
        
        this.route.paramMap.pipe(
            filter(params => params.has('id')),
            map(params => params.get('id'))
        ).subscribe(id => this.customers.selectByKey(id));
    }
    
    select(customer: Customer): void {
        this.router.navigate(['./', customer.id]);
    }
}

<div class="customers" *ngIf="customers.isLoading$ | async; else #loading">
    <app-customer-list 
        [customers]="customers.all$ | async" 
        (selected)="select($event)">
    </app-customer-list>
    <app-customer-detail 
        *ngIf="(customers.current$ | async) as customer"
        [customer]="customer">
    </app-customer-detail>
</div>
<ng-template #loading>
    Loading customers...
</ng-template>

There are also a couple additional lines of code you may need to add to your app.state.ts file for the app state interface and app reducer map, as well as a provider mapping between the model and the entity service. See quick start for more info.

States

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

import { Customer, Order } from '../models';
import { customerReducer } from './customer.state';
import { orderReducer } from './order.state';

export interface IAppState {
    customer: IEntityState<Customer>;
    order: IEntityState<Order>;
}

export type AppState = IAppState;

export function appReducer: ActionReducerMap<AppState> = {
    customer: customerReducer,
    order: orderReducer
};

import { buildState, IEntityState } from '@briebug/ngrx-auto-entity';
import { createReducer } from '@ngrx/store';
import { Customer } from 'models';

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

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

import { buildState, IEntityState } from '@briebug/ngrx-auto-entity';
import { createReducer } from '@ngrx/store';
import { Order } from 'models';

export const { initialState: orderInitialState, facade: OrderFacadeBase } = buildState(Order);

export function orderReducer(state = initialState): IEntityState<Order> {
  return state;
}

Module

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

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

@NgModule({
  imports: [
    StoreModule.forRoot(appReducer, {
      runtimeChecks: {
        strictStateImmutability: true,
        strictActionImmutability: true,
        strictStateSerializability: true,
        strictActionSerializability: true,
      },
    }),
    EffectsModule.forRoot([]),
    NgrxAutoEntityModule.forRoot()
  ]
})
export class StateModule {}

Barrel

export * from './app.state';
export * from './customer.state';
export * from './order.state';
export * from './state.module';

Another lower level element returned by buildState is the selector map. Much like @ngrx/entity, the selector map is a simple object (associative array) that maps common names to selector functions.

export interface ISelectorMap<TParentState, TModel> {
  selectIds: MemoizedSelector<object | TParentState, EntityIdentity[]>;
  selectEntities: MemoizedSelector<object | TParentState, IEntityDictionary<TModel>>;
  selectAll: MemoizedSelector<object | TParentState, TModel[]>;
  selectTotal: MemoizedSelector<object | TParentState, number>;
  selectCurrentEntity: MemoizedSelector<object | TParentState, TModel>;
  selectCurrentEntityKey: MemoizedSelector<object | TParentState, EntityIdentity>;
  selectCurrentEntities: MemoizedSelector<object | TParentState, TModel[]>;
  selectCurrentEntitiesKeys: MemoizedSelector<object | TParentState, EntityIdentity[]>;
  selectCurrentPage: MemoizedSelector<object | TParentState, Page>;
  selectCurrentRange: MemoizedSelector<object | TParentState, Range>;
  selectTotalPageable: MemoizedSelector<object | TParentState, number>;
  selectIsLoading: MemoizedSelector<object | TParentState, boolean>;
  selectIsSaving: MemoizedSelector<object | TParentState, boolean>;
  selectIsDeleting: MemoizedSelector<object | TParentState, boolean>;
  selectLoadedAt: MemoizedSelector<object | TParentState, Date>;
  selectSavedAt: MemoizedSelector<object | TParentState, Date>;
  selectDeletedAt: MemoizedSelector<object | TParentState, Date>;
}

As with the IEntityState interface, we have attempted to maintain naming compatibility with @ngrx/entity here, however also as with IEntityState we provide a lot more than @ngrx/entity does as well. Selectors are available for every state property managed by NgRx Auto-Entity.

To use one of these methods in your component, simply inject your facade class and call the method in the constructor, an ngOnInit or similar handler, or a custom handler:

export class CustomersComponent implements OnInit {    
    constructor(
        public customers: CustomerFacade, 
        public router: Router,
        public route: ActivatedRoute
    ) {
        this.customers.loadAll();
    }
    
    ngOnInit(): void {
        this.route.paramMap.pipe(
            filter(params => params.has('id')),
            map(params => params.get('id'))
        ).subscribe(id => this.customers.selectByKey(id));
    }
    
    select(customer: Customer): void {
        this.router.navigate(['./', customer.id]);
    }
}

Use the Async Pipe!

We highly recommend following NgRx best practices here to avoid subscribing directly to any observable on an entity facade. Instead, use the async pipe from Angular in your templates, and follow container/presenter model for your component architecture:

<div class="customers" *ngIf="customers.isLoading$ | async; else #loading">
    <app-customer-list 
        [customers]="customers.all$ | async" 
        (selected)="select($event)">
    </app-customer-list>
    <app-customer-detail 
        *ngIf="(customers.current$ | async) as customer"
        [customer]="customer">
    </app-customer-detail>
</div>
<ng-template #loading>
    Loading customers...
</ng-template>

Customers

import { Component } from '@angular/core';
import { CustomerFacade } from 'facades';
import { CustomerEditComponent } from 'components';

@Component({
  selector: 'app-customers',
  templateUrl: './customers.component.html',
  styleUrls: ['./customers.component.css']
})
export class CustomersComponent {
  constructor(public customers: CustomerFacade, public ui: CustomerUIFacade) {
    customers.loadAll();
  }
}

<div class="customers" *ngIf="customers.isLoading$ | async; else loading">
    <app-customer-list 
        [customers]="customers.all$ | async" 
        (deleted)="customers.delete($event)"
        (selected)="customers.select($event)">
    </app-customer-list>
    <app-customer-detail 
        *ngIf="(customers.currentOrFirst$ | async) as customer"
        [customer]="customer"
        (deleted)="customers.delete($event)"
        (edited)="ui.edit($event)">
    </app-customer-detail>
</div>
<ng-template #loading>
    Loading customers...
</ng-template>

Orders

import { Component } from '@angular/core';
import { Router } froj '@angular/router';
import { OrderFacade, LineItemFacade } from 'facades';

@Component({
  selector: 'app-orders',
  templateUrl: './orders.component.html',
  styleUrls: ['./orders.component.css']
})
export class CustomersComponent {
  constructor(
    public orders: OrderFacade, 
    public lineItems: LineItemFacade,
    public router: Router) {
    orders.loadAll();
  }
}

<div class="orders" *ngIf="orders.isLoading$ | async; else loading">
    <app-order-list 
        [orders]="orders.all$ | async" 
        (deleted)="orders.delete($event)"
        (selected)="orders.select($event)">
    </app-order-list>
    <app-order-detail 
        *ngIf="(orders.current$ | async) as order"
        [order]="order"
        [lineItems]="lineItems.byOrder$(order) | async"
        (deleted)="orders.delete($event); lineItems.deleteAllForOrder($event)"
        (edited)="router.navigate(['edit', $event.id])">
    </app-order-detail>
</div>
<ng-template #loading>
    Loading orders...
</ng-template>

Customer List

import { EventEmitter, Component, Input, Output } from '@angular/core';
import { Customer } from '../models';

@Component({
  selector: 'app-customers-list',
  templateUrl: './customers-list.component.html',
  styleUrls: ['./customers-list.component.scss']
})
export class CustomersListComponent {
  @Input() customers: Customer[];
  @Output() selected = new EventEmitter<Customer>();
  @Output() deleted = new EventEmitter<Customer>();
}

<div class="customer-list">
  <table>  
    <thead>
      <tr>
        <th><i class="fa fa-key"></i></th>
        <th>Name</th>
        <th><i class="fa fa-wrench"></i></th>
      </tr>
    </thead>  
    <tbody>
      <tr *ngFor="let customer of customers">
        <td>{{customer.id}}</td>
        <td>{{customer.name}}</td>
        <td>
          <i class="fa fa-edit" (click)="selected.emit(customer)"></i>
          <i class="fa fa-trash" (click)="deleted.emit(customer)"></i>
        </td>
      </tr>
    </tbody>
    <tfoot>
      <tr>
        <td class="text-right" colspan="3">
          Total Customers: {{customers.length}}
        </td>
      </tr>
    </tfoot>
  </table>
</div>

Customer Detail

import { EventEmitter, Component, Input, Output } from '@angular/core';
import { Customer } from '../models';

@Component({
  selector: 'app-customer-detail',
  templateUrl: './customer-detail.component.html',
  styleUrls: ['./customer-detail.component.scss']
})
export class CustomersListComponent {
  @Input() customer: Customer;
  @Output() saved = new EventEmitter<Customer>();
  @Output() deleted = new EventEmitter<Customer>();
}

<div class="customer-detail">
    <h2>{{customer.name}}</h2>
    <h3>{{customer.title}}</h3>
    <a href="mailto:{{customer.email}}">
        {{customer.email | prettyEmail}}
    </a>
    
    <a *ngIf="customer.handles?.twitter"
       href="https://www.twitter.com/{{customer.handles?.twitter}}">
        {{customer.handles?.twitter}}
    </a>
    <a *ngIf="customer.handles?.facebook"
       href="https://www.facebook.com/{{customer.handles?.facebook}}">
        {{customer.handles?.facebook}}
    </a>
    
    <button (click)="edited.emit(customer)">Edit</button>    
    <button (click)="deleted.emit(customer)">Delete</button>
</div>

Modal Container

import { Component } from '@angular/core';
import { CustomerFacade } from '../facades';

@Component({
  selector: 'app-customer-edit',
  templateUrl: './customer-edit.component.html',
  styleUrls: ['./customer-edit.component.css']
})
export class CustomerEditComponent {
  @ViewChild('form') form: CustomerEditFormComponent;
   
  canSave = false;
  constructor(public customers: CustomerFacade, public modal: ModalInstance) {
  }
}

<div class="customer-exit">
  <div>
    <h2>Edit Customer</h2>
    <app-customer-edit-form #form
      [customer]="customers.current$ | async"
      (submitted)="modal.dismiss($event)"
      (validated)="canSave = $event"
      >
    </app-customer-edit-form>
  </div>
  <div>
    <button [disabled]="canSave" click="form.submit()">Save</span>
    <button (click)="modal.dismiss()">Cancel</span>
  </div>
</div>

Modal Form

import { Component, Input, Output } from '@angular/core';
import { Customer } from '../models';

@Component({
  selector: 'app-customers-edit-form',
  templateUrl: './customers-edit-form.component.html',
  styleUrls: ['./customers-edit-form.component.scss']
})
export class CustomersEditFormComponent implements OnChanges, OnInit {
  @Input() customer: Customer;
  @Output() submitted = new EventEmitter<Customer>();
  @Output() validated = new EventEmitter<boolean>();
  
  form: FormGroup;
  
  constructor(private builder: FormBuilder) {}
  
  ngOnInit(): void {
    this.form = this.buildForm(this.builder);
    this.form.statusChanges.subscribe(() => this.validated.emit(form.valid));
  }
  
  ngOnChanges(): void {
    if (this.customer) {
      form.patchValue(customer);
    }
  }
  
  buildForm(builder: FormBuilder): FormGroup {
    return builder.group({
      name: [null, [Validators.required, Validators.maxLength(30)]],
      title: [null, [Validators.required, Validators.maxLength(60)]],
      email: [null, [Validators.required, Validators.maxLength(35)]],
      handles: builder.group({
        twitter: [null, Validators.maxLength(50)],
        facebook: [null, Validators.maxLenth(50)]
      }),
      address: builder.group({
        city: [null, Validators.maxLength(50)],
        state: [null, Validators.maxLength(2)],
        zip: [null, [Validators.minLength(5), Validators.maxLength(10)]]
      })
    });
  }
  
  submit() {
    if (this.form.valid) {
      this.submitted.emit({
        ...this.customer,
        ...this.form.value
      });
    }
  }
}

<form [formGroup]="form">
    <div>
      <label>Customer Name</label>
      <input id="name" formControlName="name">
      <i class="text-red" 
         *ngIf="name.invalid && (name.dirty || name.touched)">
         Please fill out this field.
      </i>
    </div>
    <div>
      <label>title</label>
      <input id="title" formControlName="title">
      <i class="text-red" 
         *ngIf="title.invalid && (title.dirty || title.touched)">
         Please fill out this field.
      </i>    
    </div>
    <div>
      <label>Email Address</label>
      <input id="email" formControlName="email" type="email">
      <i class="text-red" 
         *ngIf="email.invalid && (email.dirty || email.touched)">
         Please fill out this field.
      </i>    
    </div>
  </div>
  <div>
    <div>
      <label>City</label>
      <input id="city" formControlName="city">
    </div>
    <div>
      <label>State</label>
      <select id="state" formControlName="state">
        <option value="AZ">Arizona</option>
        <option value="CO">Colorado</option>
        <option value="NM">New Mexico</option>
        <option value="UT">Utah</option>
      </select>
    </div>
    <div>
      <label>Zip</label>
      <input id="zip" formControlName="zip">
    </div>
  </div>
</form>

Prefabricated facades are one of NgRx Auto-Entities most powerful offerings. Not only can they greatly simplify your code, facades offer a way of organizing and encapsulating core business logic. You can pull a lot of behavior out of your components and move it into your facades. This simplifies your components, and can potentially improve code reuse.

Generated for You

When preparing your state with a call to the buildState function, Auto-Entity will generate an entity facade class for you. These classes are best considered to be base classes, from which you should extend another class. See the instructions on how in the next section.

Rich Prefabricated Functionality

Prefabricated facades come complete with a core set of properties and methods that may be used "out of the box" without any additional work on your part beyond extending the base facade class. There is no explicit need to wrap every property or method provided by a facade base class in your own class in order to use it. You may, and are encouraged to, add your own custom properties and methods to encapsulate higher level behavior, though!

Customer Facade

import { Injectable } from '@angular/core';
import { store } from '@ngrx/store';

import { CustomerEditComponent } from 'components';
import { Customer } from 'models';
import { AppState, CustomerFacadeBase, firstCustomer } from 'state'

@Injectable({ providedIn: 'root' })
export class CustomerFacade extends CustomerFacadeBase {
    constructor(store: Store<AppState>, private modal: Modal) {
        super(Customer, store);
    }
    
    get first$(): Observable<Customer> {
        return this.store.pipe(select(firstCustomer));
    }
    
    get currentOrFirst$(): Observable<Customer> {
        return combineLatest(this.current$, this.first$).pipe(
            map(([current, first]) => current || first)
        );
    }
    
    save(customer: Customer): void {
        customer.id ? this.update(customer) : this.create(customer);
    }
}

import { Injectable } from '@angular/core';

import { CustomerEditComponent } from '../components';
import { Customer } from '../models';

@Injectable({ providedIn: 'root' })
export class CustomerUIFacade {
    constructor(private modal: Modal, private customerFacade: CustomerFacade) {
    }
    
    edit(customer: Customer): void {
        const reference = this.modal.show(CustomerEditComponent);
        reference.dismissed(editedCustomer => {
          this.customerFacade.save(editedCustomer);
        });
    }
}

import { Injectable } from '@angular/core';
import { store } from '@ngrx/store';

import { Order } from 'models';
import { AppState, OrderFacadeBase } from 'state'

@Injectable({ providedIn: 'root' })
export class OrderFacade extends OrderFacadeBase {
    constructor(store: Store<AppState>, private modal: Modal) {
        super(Order, store);
    }
    
    save(order: Order): void {
        order.id ? this.update(order) : this.create(order);
    }
}

import { Injectable } from '@angular/core';
import { store } from '@ngrx/store';

import { LineItem } from 'models';
import { AppState, LineItemFacadeBase } from 'state'

@Injectable({ providedIn: 'root' })
export class LineItemFacade extends LineItemFacadeBase {
    constructor(store: Store<AppState>, private modal: Modal) {
        super(LineItem, store);
    }
    
    byOrder$(order: Order): Observable<LineItem[]> {
        return this.all$.pipe(
            map(lineItems => 
                lineItems.filter(lineItem => lineItem.orderId === order.id)
            )
        );
    }
    
    deleteAllForOrder(order: Order): void {
        this.byOrder$(order).pipe(
            tap(lineItems => this.deleteMany(lineItems))
        );
    }
}

export * from './customer.facade';
export * from './customer-ui.facade';