NgRx Auto-Entity: Simplifying Reactive State
Updated state builders to build all state functionality "on-demand" to limit memory footprint when
lots of entities are used. This aligns selectors, facades, etc. with the way actions were implemented
when they were introduced to the state builder. Selectors for any given entity are only created
if they are accessed (i.e. destructured from the object returned by buildState), and the same goes
for facades.
Performed a major internal refactor of the auto-entity reducer in order to break down the single monolithic reducer into a more modular design. Each set of related actions, such as loadAll, create, editing, selections, etc. have their own corresponding reducer. Actions are now mapped to the appropriate reducer through a centralized mapping for action-to-reducer routing.
These changes are internal, and should not present any breaking changes to the public API. That said, the changes are fairly extensive, and care should be used until 0.8 is officially released.
pipe function to compose
Resolved a discrepancy in optional loading, where if the entity were a part of feature state, and its state properties were nested underneath a feature state property on root state, the correct entity state property could not be found.
Resolve license field issues in package.json. Update packages based on security alerts. No other or breaking changes in this release.
Added two new loading related selectors: hasBeenLoaded and loadWasAttempted. These selectors allow end developers to determine if a load has ever been attempted before, which is sometimes necessary to display the correct information in a UI component. Until a load has at least been attempted, it would generally be inappropriate to display to the user that there are no Entities X, however as the current state of each entity currently stands, there is no way to determine that particular state of an entity. You can determine if an entity is loading or not, which is useful for displaying a spinner, but other messaging requires more information.
This release officially adds support for Angular 12 and NgRx 12! With the advent of Ivy, and its
continued progress towards replacing View Engine, supporting Angular 12 required a bit more active
work to support. Currently, the library is built with enableIvy set to false, which allows the
library to be built with support for View Engine versions of Angular.
Research and planning has begun on supporting Angular 13, however this will be a more challenging task than supporting Angular 12 due to the fact that View Engine will be dropped entirely from Ng 13, which will affect our ability to build a library that supports older versions of Angular. We hope to have a plan in place for this scenario soon.
This release also updates some internal usage of NgRx to drop use of legacy or fully deprecated
features, such as the @Entity decorator.
@Effect() decorator, and are now using
the current and recommended createEffect() function. This is to ensure support with NgRx 12+.Auto-Entity version 0.6 introduces NgRx 8+ compatible action factory functions. Similar to the
kind of actions (technically factory functions that create actions!) you get when using the
createAction factory function from NgRx itself. This change is NON-Breaking, as all legacy
actions remain in place and fully usable, allowing migration to the new actions to be done
progressively if necessary.
New actions may be destructured from the object returend by calling buildState and buildFeatureState,
as with all other auto-entity state functionality. Simply destructure the new actions property:
export const {
actions: {
loadAll: loadAllCustomers,
create: createCustomer,
update: updateCustomer,
delete: deleteCustomer,
select: selectCustomer,
deselect: deselectCustomer,
// ... many more!
}
} = buildState(Customer);
Actions introduce a new mechanism for building auto-entity state. Only the actions that are actually used (i.e. destructured) are actually created for the specified entity. This should limit the amount of memory used for auto-entity related functionality. This mechanism will be expanded to the rest of the state related functionality that can be generated by the build state calls in the future.
The breaking changes this release should be minimally breaking, and mostly backwards compatible except in fringe cases covering more unusual use cases. Conversion of selection properties from read only getters to simple fields should improve the unit testability of facades by allowing simpler mocks, stubs, and fakes, easier spying, etc. This may also improve support for more custom use cases and extensions in concrete facade classes.
EditNew action (#161)editNew activity method (#161)selectHasEntities and selectHasNoEntities selectors (#149)hasEntities$ and hasNoEntities$ selections to facades (#149)updatedAt and replacedAt timestamps in state for each entityAuto-Entity version 0.5 introduces several major enhancements over version 0.4. These features include the addition of several new actions, including support for Upsert-style changes & optional loading. Result actions (success/failure) have been enhanced with additional data, providing all original params and criteria passed to their corresponding initiating actions.
Optional loading, or "if necessary" actions, have been added to support more efficient loading of entities by skipping the actual load, if the data has already been loaded and is in state. These actions require access to entity state, which necessitated the addition of a new configuration provider injection token, NGRX_AUTO_ENTITY_APP_STORE, that must be configured by the app to allow auto-entity to check state in *IfNecessary effects. Without proper configuration of the app store injection token, the *IfNecessary effects will fail to function properly. Graceful fallback to descriptive errors will occur if the necessary config has not been performed by the developer.
A range of new utility functions have been added to support the developer's utilization of entity meta-
data that is configured via the @Entity and @Key directives. This includes functions to retrieve the
various entity names, comparers, transformers, and other metadata.
Several enhancements to the internal reducer have been made to improve reliability, enhance performance, and
provide richer error messaging to the developer. When the reducer cannot perform its job due to mis-configuration
of any automatic entity, additional errors will be reported to the browser console. These enhancements extend
to additional error reporting by the buildState functions as well, in an attempt to identify mis-configuration
as early as possible. Any misconfiguration that can be detected will now be reported to the browser console,
along with instructions to fix (with example code) whenever possible.
Internal code cleanup and restructuring has been performed to achieve better organization and support long-term maintenance of the project as well. Internal re-org breaks previously very large code files into much smaller files, such as actions, operators, decorators and support code, utility functions, etc.
NOTE: Internal restructuring may potentially be breaking to consumers of NgRx Auto-Entity if they are by chance importing anything from internal (non public-api) paths in the library!
NgRx Auto-Entity has been verified to work with Angular 8 and 9. Angular 10 may work, depending on the use cases and exact configuration of Angular. Further testing will be performed for Angular 10 support, and updates may be forthcoming to add deeper support for Angular 10.
NgRx Auto-Entity is now properly licensed under the MIT Open Source License!
Upsert/UpsertMany actions to support upsert style changes (#109)upsert/upsertMany handlers to entity service (#109)upsert/upsertMany (#109)key params for load actions (#99)key params for load methods on facades (#99)@Entity decorator (#107)makeEntity utility function for converting POJOs to prototyped entity objects (#139)EditByKey action to support initiating edits by entity key, if entity is in state (#145)editByKey method to support initiating editd by entity key (#145)defaultMaxAge to @Entity decorator for "if necessary" support (#144)EntityAge enum with set of predefined common ages for use with "if necessary" ages (#144)@Entity decorator usage of passing model name as string only (#141)criteria as optional parameter to all data transformers (#93)null was a possibility for stronger typing../.. referencenumber) to resolve serialization issues (#98)Date to maintain public API (#98)all and sorted selectors to be based off other selectors to avoid unnecessary re-emissions (#113)buildState functions to log console errors and throw if entities are mis-configuredIntroduces the ability to delete entities just by their key, or many entities by their keys. This allows the deletion of entities without actually having the entity objects on hand.
Also resolves an issue with clearing state, which would also clear custom developer-defined extra state included alongside auto-entity managed state.
DeleteByKey, DeleteManyByKeys and related result actions (#85)deleteByKey and deleteManyByKeys methods in entity services (#85)@Entity decorator (#85)deleteByKey and deleteManyByKeys methods to generated facades (#85)Clear action (#86)buildState and buildFeatureState and related types to support custom properties in extra state under TS 3.x (#88)Introducing the @Entity decorator for model classes. This decorator provides custom naming capabilities,
the ability to filter which auto-entity pre-fab effects handle each model, as well as define a default
comparer for sorting entities retrieved with a new .sorted$ stream on pre-fab facades.
@Entity decorator for models with modelName, pluralName, uriName properties (#70)excludeEffects functionality to @Entity decorator for filtering which effects handle entitycomparer property to @Entity decorator to support selecting sorted entities (#58)selectAllSorted selector that uses entity comparer to sort on selection (#58)sorted$ stream to return all entities in sorted order from selectAllSorted selector (#58)modelName to @Entity decorator to allow explicit definition of model name immune to mangling by code minifiers (#81)