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.

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.

The createAction Factory

With the release of NgRx 8, several utility functions, factory functions, were introduced and can help reduce some of the "boilerplate" nature of implementing actions, effects and reducers. These new functions are a welcome improvement over prior versions of NgRx...however, we do believe they still fall short of providing the kind of simplified, rapid development experience Auto-Entity provides for entity use cases.

Using the createAction factory, we can reduce the previous boilerplate to the following:

A definite reduction in complexity, and a small reduction in overall code volume. However, actions must still be created in order to handle entity loading/success/failure in NgRx. And, similar sets of actions must be created for each and every entity you need to use in your app.

Dispatched from Components

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

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.

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.

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. Most action constructors are as follows:

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

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 next 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 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 are 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`, {
                params: { skip, 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 note 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`, {
                params: { skip, take }
            }
        ).pipe(
            withLatestFrom(
                this.http.get<{totalRecords: number}>(
                    `${environment.apiBaseUrl}/api/v1/customers`, {
                        params: { 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<Customer[]>(
            `${environment.apiBaseUrl}/api/v1/customers`, {
                params: { skip, take },
                observe: 'response'
            }
        ).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] 
                    : size // default to page size if no total returned
            }),
            map(({customers, total}) => ({
                pageInfo: {
                    page: { page, size },
                    totalCount: total
                },
                entities: customers
            }))
        );
    }

Beyond the core CUURDL 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. Added in v0.5 is the ability to track and update copies of entities for active editing.

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.

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

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

Upsert: Update or Insert

Some data stores support the concept of a sort of "merge" operation, where data may be updated, or inserted, as appropriate based on keys and what exists already vs. not. MongoDB is an example of one database that has first-class upsert support in many of its operations.

Auto-Entity provides first-class support for upsert operations. This means that when upsert responses are reduced, they will be properly merged into the existing state, updating existing keys or adding new keys as appropriate.

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.

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.

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', 
    wasFulfilled: true 
});

And our custom loadMany implementation in our entity service:

interface LoadCriteria {
    customerId: number;
    datePlaced?: string;
    dateFulfilled?: string;
    wasFulfilled?: boolean;
}

loadMany(entityInfo: IEntityInfo, criteria?: LoadCriteria): Observable<Order[]> {
    let url = `${environment.apiBaseUrl}/api/v1/customers/${criteria.customerId}/orders`;
    return this.http.get<Order[]>(url, {
        params: {
            ...criteria, // Provide the rest of the criteria as query parameters
            customerId: undefined // Strip the id, as it is in the 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 we will be going into more detail on in the next section.

New in version 0.5 is the ability to "optionally" load data. This functionality was added with the IfNecessary set of loading actions. These actions will perform some basic checks against the existing state in your application, which necessitates that you actually expose your state to the library (more on this in a moment.) In essence, if the entities are already in state, the actual load action will not be dispatched. Optionally, a maxAge may be specified in the IfNecessary actions, or a defaultMaxAge may be defined on the model with the @Entity decorator.

Providing Your Store

In order for optional loading actions to function, they must be able to access your state. This means you must expose your store to the auto-entity library. This is achieved by providing the NGRX_AUTO_ENTITY_APP_STORE injection token with a factory function that will return your Store instance.

There is not much to it, other than to create a factory function that depends on the NgRx Store, and to specify Store as a dependency of your provider. You should also provide this token in your root application module, to ensure it is within the root injection scope (otherwise Auto-Entity will be unable to find it, as it is unable to use child injection scopes defined by your own applications.)

Using Optional Loading

Once you have provided your store to Auto-Entity, you may use the optional loading actions. These actions are available for each of the different loading actions that already exist:

These actions will attempt to verify that the requested data already exists within state. For loading a single entity, it will look for that entity (its key) in state. For loading all or many entities, it will check if any entities are in state. (Note: Currently, we will not try to verify if custom criteria matches, as auto-entity currently does not store the previous criteria. This may change in a future version of auto-entity.) For loading a page or range, the current page/range criteria will be compared against existing state.

Optional loading is an additional "layer" on top of normal loading. When dispatching a LoadIfNecessary action, this action simply invokes an effect that performs the appropriate verification against state to determine if a Load action should be dispatched or not. If the entity or entities are found in state, then a Load action will NOT be dispatched. Otherwise, the Load action will be dispatched normally.

The *IfNecessary actions therefor only introduce new functionality, and otherwise do not change the existing load functionality. Any custom code that may rely on the existing loading mechanism in Auto-Entity to continue working the way it does will continue to work when using optional loading. You may also add effects that expect *Success or *Failure load result actions, as they will still be dispatched appropriately when using *IfNecessary actions.

Maximum Age

When performing an optional load, a maximum age, in seconds, may be specified. If the last loadedAt timestamp for the entity in question is older than the specified age, then entities will be loaded. A maximum age may be specified within the *IfNecessary action as a parameter, or a default max age may be specified on the entity model using the @Entity decorator:

If both a default maximum age is specified on the model, and a maximum age is passed in the action, the action age takes precedence. Auto-Entity provides an enumeration of pre-defined ages, for convenience:

The enum is numeric, and as such may be combined with basic math to produce N number of minutes, days, etc.:

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 concatenated 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:

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:

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:

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

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.