Easy CRUD actions for your
ngxs
state
This package is an entity adapter and simplifies CRUD behaviour with just a few lines of setup per state class!
Setup
npm i @ngxs-labs/entity-state
You do not have import any module, just extend your state class, make a super
call and you are good to go!
The first super
parameter is always the state class itself.
The second parameter is the key to identify your entities with.
The third is an implementation of an IdGenerator
(see below).
Example state
export interface ToDo {
title: string;
description: string;
done: boolean;
}
@State<EntityStateModel<ToDo>>({
name: 'todo',
defaults: defaultEntityState()
})
export class TodoState extends EntityState<ToDo> {
constructor() {
super(TodoState, 'title', IdStrategy.EntityIdGenerator);
}
}
Actions
There are ready to use Actions for entity-states. Just pass in the targeted state class as the first parameter and then your action's payload.
this.store.dispatch(new SetLoading(TodoState, this.loading));
this.store.dispatch(new UpdateActive(TodoState, { done: true }));
Action | Short description |
---|---|
Add |
Adds a new entity and cannot replace existing entities |
CreateOrReplace |
Gets the entity's ID and will replace entities with same id or else add a new one |
Update |
Updates one or more entities by partial value or function |
UpdateAll |
Update all entities by partial value or function |
Remove |
Removes entities from the state |
RemoveAll |
Removes all entities from the state |
---------- | ---------- |
SetActive |
Takes an ID and sets it as active |
ClearActive |
Clears the active ID |
UpdateActive |
Updates the currently active entity |
RemoveActive |
Removes the active entity and clears the ID |
---------- | ---------- |
SetError |
Sets the error (Error instance or undefined ) |
SetLoading |
Sets the loading state (true or false ) |
Reset |
Resets the state to default |
---------- | ---------- |
GoToPage |
Goes to specified page, via index, stepwise or first/last |
SetPageSize |
Sets the page size |
Actions that change the entities will update the internal timestamp lastUpdated
.
You can use one of the existing selectors to see the age of your data.
Selectors
Use predefined Selectors just like you would normally!
@Select(TodoState.entities) toDos$: Observable<ToDo[]>;
@Select(TodoState.active) active$: Observable<ToDo>;
Selector | Short description |
---|---|
entities |
All entities in an array |
keys |
All entity keys in an array |
entitiesMap |
All entities in a map |
size |
Entity count |
active |
the active entity |
activeId |
the active ID |
paginatedEntities |
Entities in an array defined by pagination values |
nthEntity |
the nthEntity by insertion order |
latestId |
the ID of the latest entity |
latest |
the latest entity |
loading |
the loading state |
error |
the current error |
lastUpdated |
the lastUpdated timestamp as Date
|
age |
difference between Date.now() and lastUpdated in ms |
IdStrategy
There are 3 different strategies in the IdStrategy
namespace available:
-
IncrementingIdGenerator
-> uses auto-incremeting IDs based on present entities -
UUIDGenerator
-> generatesUUID
s for new entities -
EntityIdGenerator
-> takes the id from the provided entity
The latter will cause errors if you try to add
an entity with the same ID.
The former two will always generate a new ID.
You can also implement your own strategy by extending IdGenerator
and then provide it in the super
call.
EntitySelector
The EntitySelector
type is used in Actions such as Update
or Remove
.
export type EntitySelector<T> = string | string[] | ((entity: T) => boolean);
-
string
-> one ID; selects one entity -
string[]
-> array of IDs; selects matching entities -
(entity: T) => boolean
-> predicate; selects entities that returntrue
when applied to this function