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>

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,
            runtimeChecks: { 
                // Auto-Entity includes classes in its actions:
                strictActionSerializability: false
            }
        }),
        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.

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.

As with any NgRX application, we need to create a new app.state.ts file. We recommend creating is 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 AppState {
  // todo: add each entity state interface to our application state interface
}

Define the AppState 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 AppState {
  // todo: add each entity state interface to our application state interface
}

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

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

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.

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

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

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

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

Angular 10 Support *

A quick note about Angular 10. While NgRx Auto-Entity has been tested with Angular 10, not every use case exhibited flawless support. There have been use cases where some uses of Auto-Entity with Angular 10 have worked just fine, and others that seemed to have issues. So we tentatively support Angular 10, but official guaranteed support is still pending. As such, we do not recommend you use Auto-Entity with Angular 10 in production environments at this time.

Further testing of Auto-Entity with Angular 10 is ongoing, and outstanding issues will be resolved as they are discovered. One of our key goals with Auto-Entity is to remain backwards compatible with prior versions of Angular as best we can. Due to certain TypeScript requirements, our minimum supported versions are Angular 8 and NgRx 8. We hope this will expand Auto-Entity viability to the broadest range of enterprise customers with established Angular projects, as well as cutting edge projects on the bleeding edge. Our compatibility goals may require more complex build, packaging and deployment in the future, and there may come a time when our minimum versions must change to keep abreast of the Angular platform.

For now, Angular 10 support is tentatively there. If you run into issues, let us know by opening a ticket in our GitHub repo:

https://github.com/briebug/ngrx-auto-entity/issues

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.

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 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 initialCustomerState, and the action.

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

Next we need to import the Key and Entity decorators. The Key decorator 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.

The Entity decorator is used to attach metadata to your entity model that the NgRx Auto-Entity library can use to perform many of its automated tasks. In version 0.5 of the library, only the modelName must be specified. Read more about the entity decorator in the advanced documentation.

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

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

provide: Model, useClass: EntityService

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

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

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

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

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

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

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

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!

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

Update the import of the StoreModule. In the forRoot() static method, specify the appReducer and (if necessary) 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.

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.

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.

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.

High Performance and Efficiency

Auto-Entity has been implemented with high performance in mind, and is capable of reducing very large data sets. We have tested NgRx Auto-Entity with up to millions of records in state, while adding millions more, with reduction times in the fractions of a second. We do not generally recommend loading such significant volumes of data into your Angular applications, and for more common usage at much lower volumes, you should encounter no performance limitations with Auto-Entity.

Should your application need to work with millions of entities in state in the browser, NgRx Auto-Entity has been tested under high entity volumes. With tens to hundreds of thousands of entities, reduction times should be sub-second, although subject to memory limitations. For millions of entities, performance may vary with memory, and under limited memory situations reductions of very large volumes of entities may require more time. Tests with MacBook Pros with 16 gigabytes of ram, reduction of 2 million entities takes 0.5 to 2 seconds under normal usage.

Compatibility with @ngrx/entity

While it is not required and Auto-Entity is an entirely independent library that solely depends on Angular 8/9/10 and NgRX 8/9/10, 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 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, originalEntity?: TModel): Observable<TModel>;
  createMany?(entityInfo: IEntityInfo, entities: TModel[], criteria?: any, originalEntities?: TModel[]): Observable<TModel[]>;

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

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

  delete?(entityInfo: IEntityInfo, entity: TModel, criteria?: any, originalEntity?: TModel): Observable<TModel>;
  deleteMany?(entityInfo: IEntityInfo, entities: TModel[], criteria?: any, originalEntities?: TModel[]): Observable<TModel[]>;
  
  deleteByKey?(entityInfo: IEntityInfo, key: EntityIdentity, criteria?: any): Observable<EntityIdentity>;
  deleteManyByKeys?(entityInfo: IEntityInfo, keys: EntityIdentity[], criteria?: any): Observable<EntityIdentity[]>;
}

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.

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 {Entity, Key} from '@briebug/ngrx-auto-entity';

@Entity({
    modelName: 'Customer',
    uriName: 'customers'
})
export class Customer {
    @Key id: string;
    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';

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

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

Entity Metadata

You should also notice that we have decorated our entity with the Entity decorator, imported from @briebug/ngrx-auto-entity. This decorator allows us to associate important metadata with each of our entities. Currently, the only required metadata is the modelName which allows us to define a minification/uglification-safe identifier for our entity models.

The Entity decorator allows the definition of other metadata for our entities, including alternative names for specific use cases, a sort comparer, data transformations, and other things. For more detail about entity metadata, read the advanced usage documentation on models.

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.

Efficiency with Service Mappings

Auto-Entity makes it possible to reuse a single smart entity service with multiple entities. This approach allows another reduction in developer effort, requiring an initial effort up front to implement the entity service, however over the lifetime of the application that single service may be used countless times for countless entities.

Mapping each entity to a service may not be the most efficient approach. Each provider will be a new instance of the entity service. In order to supply a single service instance you can use a factory with another provider.

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 { Product } from 'models';
import { Order } from 'models';
import { LineItem } from 'models';
import { EntityService } from 'services/entity.service';

export function provideEntityService(service: EntityService) {
  return service;
}

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule, NgrxAutoEntityModule],
  providers: [
    EntityService,
    { provide: Customer, useFactory: provideEntityService, deps: [EntityService] },
    { provide: Product, useFactory: provideEntityService, deps: [EntityService] },
    { provide: Order, useFactory: provideEntityService, deps: [EntityService] },
    { provide: LineItem, useFactory: provideEntityService, deps: [EntityService] },    
  ],
  bootstrap: [AppComponent]
})
export class AppModule {}

Minification and Service Lookup

To ensure that auto-entity's service lookup for a given identifier of application state will work even when your code has been minified/uglified, run through AoT, optimized, etc. we require that a string name for each model be defined with the Entity decorator. This name is used instead of the actual runtime class name, thus guaranteeing that even if the class name (and therefor constructor.name) is changed during minification, auto-entity will still function properly.

Entity models are central to Auto-Entity. These describe your data, not just in terms of the data itself, but how Auto-Entity interacts with each entity. The @Entity decorator allows you to configure each entity, including specifying non-minifiable entity names, comparers for sorting purposes, transforms for converting data to and from server formats, and more. The @Key decorator allow you to mark which properties of your entities comprise the unique identifier of each.

The @Entity Decorator

A range of metadata may be used to configure your entities using the @Entity decorator. This decorator is intended to decorate the classes you use to define your entity models. The only required property is the modelName, which provides auto-entity with a non-minifiable name that uniquely describes the identifier of your model. A non-minifiable name (i.e. vs. constructor.name) is critical, as auto-entity relies on this name to find the slice of state for your entity and perform other internal operations.

In addition to the model name, the @Entity decorator allows you to describe a default sort comparer as well as named sort comparers, compose pipelines of data transforms, define a default maximum age for entities for use with optional loading, and finally exclude the entity from certain automatic effects handling (for very advanced use cases).

The @Key Decorator

For any entity to be managed by auto-entity, it must have an identity. A unique identity. Auto-entity supports entity keys that are single-property, or multi-property. A multi-property or composite key will be handled automatically by auto-entity. There is an internal format for these that ensures they are strings that can be used as keys in the ngrx state.

Entity keys may be retrieved with one of many key getter utility functions. Check the documentation for more information.

At the core of NgRx Auto-Entity is the buildState function. This utility function encapsulates the creation and management of all the "boilerplate" that you would normally implement yourself when building up state for a new entity. 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:

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:

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!)

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.

Custom Effect

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

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:

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.

In addition to the modelName, the @Entity decorator supports other names. These include the pluralName which can be useful for dynamically describing entities in plurality in log messages, messages displayed in the ui, etc. Additionally a uriName may be specified that can be used when building API endpoint urls in your entity services.

Some examples of using the @Entity decorator to name your entities:

Auto-entity provides a number of utility functions for retrieving the various names of entities. Refer to the documentation for more information.

Sorting is a core feature of most applications that use data. At one point or another, you will likely want to display your data sorted in one order or another. Auto-Entity provides built in functionality for sorting your entities. The most common use case would be to define a default comparer, however auto-entity also supports defining additional named comparers to sort your entities in any number of ways.

Default Comparer

To attach a default comparer to your entity, use the comparer property of the configuration object you pass to the @Entity decorator. This is a standard comparer function that you should be familiar with for standard JavaScript sort functionality.

Sort comparers may be defined directly within the @Entity decorator, or may be defined as a constant or function and passed in the decorator. This allows a single comparer to be used for multiple entities, as appropriate:

Named Comparers

If you find yourself in a situation where you need to sort entities in more than one way, then you can define named comparers. Named comparers are used with the the CustomSorted selector, which is a parameterized selector. Being parameterized, each time you use it with a different parameter, its memoized result is recomputed. This ensures that you don't use too much memory when sorting the same set of entities in different ways, however at greater compute cost.

To define named comparers, use the comparers property of the configuration object you pass to the @Entity decorator. This property expects an object, or an associative map, where the properties are the names of the comparers, and the value of each property is the comparer function.

Default Named Comparer

When defining named comparers, you may also define the default within the comparers property of the configuration object passed to @Entity. This is an alternative method of defining a default comparer.

Note that when defining default comparers, if you define both the comparer property as well as the default named comparer of the comparers property, the comparer defined on the comparer property will always take precedence. As such, this configuration will sort by name, not id:

One of the most powerful features that Auto-Entity provides is data transforms. The data transformation model in auto-entity allows simple types that expose two functions to be composed together in a simple manner to create rich, powerful transformations of entities as they arrive from the server, or are sent to the server. Transforms can solve a multitude of problems that can often be challenging to resolve in other ways.

Anatomy of a Transform

A transform in auto-entity is a simple object that contains two properties, fromServer and toServer. Each of these properties must return a function that can be used to apply the transform to data going in the specified direction. A simple example:

This simple object and its functions perform the very simple task of doubling a name when an entity is retrieved from a server, then un-doubling it when it is sent back to the server. The functions can be extremely basic, in this case they leverage a JavaScript comma expression to assign a property then return the updated object back without requiring any unnecessary verbosity.

"Non-Pure", yet Still Observationally Pure!

You may notice that the functions in the previous example do not appear to be pure. They are modifying the object passed in! That may seem as though it violates immutability, however it helps to understand the context within which these functions are called. Transformation occurs BETWEEN the entity services, and the effects that handle auto-entity actions. The transformation code will always clone your entity first before applying each configured transformation in-order.

This ensures that whenever an entity is transformed, the process IS immutable. Further, all the apparent non-purity is tightly contained within a specific function of the transformation process, and therefor no mutations are actually observable to anything other than the transformation process itself. Such "mutative contexts" are often allowed in functional languages that otherwise require immutability. If mutations cannot be observed, then they cannot incur unexpected side effects. No transformation mutation can ever be observed outside of the transformation process itself.

Designed for Performance

The key reason why mutations (of the clone of the entity provided by the internal transformation process) are allowed during transformations is to ensure they are performant. If every entity in a retrieved data set required the entity to be cloned in each and every transform, the performance of the transformation process would be rather miserable (a reality verified through testing!) By allowing mutations in a tightly controlled and non-observable process, transformation can in fact be extremely fast, even with complex transformation pipelines.

Composing Transforms

Transforms in auto-entity are intended to be composable. This allows discrete transforms of certain aspects of each entity to be encapsulated, often into generalized and reusable units, that can then be composed together as necessary for each entity that requires such transforms.

Converting Data

Some of the most common applications for data transformation is to convert data from a server or wire representation into a more useful representation in the application. A key example of this is dates, which are most often transferred over the wire as ISO8601 formatted strings, as JavaScript Date objects cannot be properly serialized and deserialized in JSON.

A date transform can make short work of keeping the data types and formats in line both for the app as well as for the wire:

This simple unit of code is a highly reusable transform. Unlike the simpler example before, this transform is actually a function that takes a property name as a parameter, and returns a transform that can transform that property on an entity. This allows the transform to be applied to many entities with different date properties, or even many date properties on a single entity:

Data conversions are likely to be the most common use case for using transforms, however they are not the only use case.

Distributing and Merging Data

Another potential use case for transforms could be the distribution of information from one particular property, into several others that only exist for UI purposes, then the aggregation of those properties back into a single property for transfer over the wire back to the server.

Sometimes rich information may be encoded in a single string. Such a string may represent numbers and names and other things. These aspects of the entity can be distributed out of the single string, into distinct properties of the entity making them easier to access and strongly typed.

Generating Data

Finally, transforms may be used to generate data. Perhaps from other data on the entity, perhaps from data produced by another transform, which in effect can chain transforms. In the event that transforms are chained together, the order in which they are specified in the transform property of the configuration passed to @Entity becomes important.

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[]>;
  selectAllSorted: MemoizedSelector<object | TParentState, TModel[]>;
  selectTotal: MemoizedSelector<object | TParentState, number>;
  selectCurrentEntity: MemoizedSelector<object | TParentState, TModel | null>;
  selectCurrentEntityKey: MemoizedSelector<object | TParentState, EntityIdentity | null>;
  selectCurrentEntities: MemoizedSelector<object | TParentState, TModel[]>;
  selectCurrentEntitiesKeys: MemoizedSelector<object | TParentState, EntityIdentity[]>;
  selectEditedEntity: MemoizedSelector<object | TParentState, Partial<TModel> | null>;
  selectIsDirty: MemoizedSelector<object | TParentState, boolean>;
  selectCurrentPage: MemoizedSelector<object | TParentState, Page | null>;
  selectCurrentRange: MemoizedSelector<object | TParentState, Range | null>;
  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 | null>;
  selectSavedAt: MemoizedSelector<object | TParentState, Date | null>;
  selectCreatedAt: MemoizedSelector<object | TParentState, Date | null>;
  selectDeletedAt: MemoizedSelector<object | TParentState, Date | null>;
}

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.

The buildState function has a fairly strait forward 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:

export const buildState = <
  TState extends IEntityState<TModel>, 
  TParentState, 
  TModel, 
  TExtra
>(
  type: IModelClass<TModel>,
  extraInitialState?: TExtra
): IModelState<TParentState, TState, TModel, TExtra>

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 (including extra custom state), 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, TExtra> {
  initialState: TState & TExtra;
  selectors: ISelectorMap<TParentState, TModel>;
  reducer: (state: TState & TExtra) => IEntityState<TModel> & TExtra;
  facade: new (type: new () => TModel, store: Store<any>) => IEntityFacade<TModel>;
  entityState: ((state: TParentState) => TState & TExtra) | (MemoizedSelector<object, any>);
}

Extra Custom State

If you examine the IModelState interface closely, including all of its generic types, you may notice the TExtra type. This represents extra, custom state properties you may add to your auto-entity state. This is provided as the second argument passed to buildState, and allows any additional state to be added.

Auto-entity aims to preserve the full typing of your entity states, and if extra state is provided, the type of your state will become TState & TExtra, or the intersection of the two types. This should ensure that when your state is used, in selectors for example, the full type information is available.

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 Quick Start. 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[];
  editedEntity?: Partial<TModel>;
  isDirty?: boolean;
  currentPage?: Page;
  currentRange?: Range;
  totalPageableCount?: number;
  isLoading?: boolean;
  isSaving?: boolean;
  isDeleting?: boolean;
  loadedAt?: number;
  savedAt?: number;
  createdAt?: number;
  deletedAt?: number;
}