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.

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.

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.

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:

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.

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.

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.

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.

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)))
                )
            )
        ),
        { resubscribeOnError: false }
    );
    
    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.

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:

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

@Entity('Customer')
@Entity({ modelName: 'Customer' })
@Entity('Customer', { pluralName: 'Customers' })
@Entity({ 
  modelName: 'Customer',
  pluralName: 'Customers',
  uriName: 'customers'
})
export class Customer {}

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

@Entity({ modelName: 'LineItem' })
@Entity('LineItem', { pluralName: 'LineItems' })
@Entity({ 
  modelName: 'LineItem',
  pluralName: 'LineItems',
  uriName: 'line-item'
})
export class LineItem {}

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

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.

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

@Entity('Customer')
export class Customer {
  @Key id: string;
  name: string;
  // ...
}

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

@Entity('LineItem')
export class LineItem {
    @Key orderId: string;
    @Key productId: string;
    quantity: number;
}

Entity keys may be retrieved with one of many key getter utility functions. Check the Utility Functions 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!)

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:

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:

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:

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 . This interface is much like the EntityState<T> interface from @ngrx/entity, although more complex as Auto-Entity manages more state for you.

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

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:

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:

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.

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.

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

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.

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',
    LOAD_ALL_CUSTOMERS = '[Customer] Load: All',
    // ... 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 | any) {}
}

export class LoadAllCustomers implements Action {
    readonly type = CustomerActionTypes.LOAD_ALL_CUSTOMERS;
}

// ... additional actions ...

export union CustomerActions = 
      CreateCustomer
    | CreateCustomerSuccess
    | CreateCustomerFailure 
    | LoadAllCustomers
     // ... 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.

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:

export const createCustomer = createAction(
    '[Customer] Create',
    props<{customer: Customer}>()
);

export const createCustomerSuccess = createAction(
    '[Customer] Create: Success',
    props<{customer: Customer}>()
); 

export const createCustomerFailure = createAction(
    '[Customer] Create: Failure',
    props<{error: Error | any}>()
);

export const loadAllCustomers = createAction(
    '[Customer] Load: All'
);

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:

import {Customer} from 'models';
import {createCustomer, loadAllCustomers} 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(createCustomer({customer}));
    }
    
    refresh() {
        this.store.dispatch(loadAllCustomers());
    }
    
    // ...
}

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.

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.

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.

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:

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:

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:

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

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:

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

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.

Since Auto-Entity is a complete solution that manages your entities for you, including calling entity services and handling their results, your own code is a bit "out of the loop" when it comes to handling results that correlate directly to some particular initiating action.

For example, if you create an entity, you dispatch an action. When that entity has been created, another action, a success or failure result action, will be dispatched. Since these two events are now disjoint and decoupled from each other, handling a particular result for a particular initiation requires some means of correlating the two.

The Correlation Id

Auto-Entity provides a built-in mechanism for handling correlation. Every action is equipped with a correlationId that allows result actions to be associated back to the action that initiated them. Every initiating action created by auto-entity will have a correlationId generated for it automatically, however manually providing the correlationId is also an option.

Auto-Entity will also ensure that whenever a result action, success or failure, is created that the correlationId of those actions will match the correlationId of the initiating action that started the process. This is true whether the correlationId is created automatically or provided manually.

Patterns for Correlating Actions

There are some basic patterns for correlating Auto-Entity actions using the correlationId. The most basic is The Leap, where a custom action is used to make the little "leap" from the effect that is dispatching the initiating action, say Create, to the effect(s) that will handle the result actions, CreateSuccess or CreateFailure. This action will contain at the very least, the correlationId of the initiating action.

Implementing The Leap

Correlation itself simply requires checking if the correlationId of the leap action matches the correlationId of the result action. First, set up an effect to handle initiation:

This is really all there is to it at a basic level. There are other ways to handle this as well...you could create the correlationId yourself and avoid having to pre-create the action. Note that the switchMap part here, which could be exhaustMap or concatMap or mergeMap as appropriate for the use case, will automatically convert the returned array into a stream, one that emits twice, first the initiating action and second the leap action.

Once you have set up your leap action, you can correlate the result action in another effect or effects. To handle success and failure separately, two effects can be created to handle the different paths. Perhaps customer creation is performed within a modal popup that must be closed on successful completion, whereas only an alert toast should be shown on failure.

The basic pattern here uses a filter operator to ensure only the matching result for the initiation captured by the leap action is handled. If the filter passes, then whatever remaining work may be performed with the appropriate result action.