redux-entity-routines
Store domain objects in one place and operate on it. Originally inspired by redux-form, redux-routines and normalizr. The entity store is agnostic to the technology you use to get the data, it can be redux saga, ngrx, or even plain promises. It react to redux actions.
Usage
// Let's call this "store.js" // 1. Create asynchronous entity routinesconst soundRoutines = // 2. Create store and bind routinesconst soundStore = // 3. Use as a classic reducerconst appReducer =
In component
// Define component { return <div> <div> sounds </div> <button onClick=onClick> Load sounds </button> </div> } // Read sounds from store as usual { return sounds: soundStore } // Dispatch action as usualconst mapDispatchToProps = onClick: soundStoreloadAll // Create container as usualconst SoundList = SoundListComponent
Actions
All action creators produce Flux compatible actions with just two props: type
and payload
. At the moment, we do not implement meta because there was no use for it yet.
Sync routines
Sync routines are just a simple routine creators. They are used just as a shortcut when you need a group of routines related to an entity.
const dialogRoutines = dialogRoutines// { type: 'DIALOG/OPEN' }
First argument to the routine is always translated as a payload. The payload can be anything.
const dialogRoutines = dialogRoutines// { type: 'DIALOG/OPEN', payload: 'LOGIN_DIALOG' }
Async routines
Async routine is a series of actions that represent checkpoints in asynchronous processes or asynchronous communication. They are used everywhere you communicate with remote sources.
Trigger stage
The routine transaction has been triggered from the UI or some side effect. Next stage is request, but practically it is possible that the routine will not proceed to the next step if you choose to filter it in side effects.
routineroutineroutine
Trigger is the most used routine action, so it has a shortcut for your convenience
Request stage
In this stage, the routine transaction has been requested on the remote source. If you track the transaction status, it can be marked as "loading". Next stage is either success of failure.
routine
Success stage
In this stage, we've got the response from the remote source and entity reducers process it. Also it says our request to remote source was successful. Next stage is always fulfill.
routineroutine
Failure stage
In this stage, we either have the response from the remote source telling us that it failed to fulfill our request or no response in case the remote source could not be reached. The received payload is the error we met on the way.
routineroutine
Fulfill stage
In this stage, the routine transaction has been finished. If you track the transaction status, it can be marked as "not loading anymore". This is the final stage.
routineroutine
Operations
TBD
Entity store
The store is a reducer and a set of selectors that gets wired into your redux store. The main idea is to keep your entities in one place and keep the logic readable. However, we do not care about all the attributes, in other words, we trust your API and side effects to provide the entities in good shape.
Very basic store
The store reducer is autowired to respond to async routines success stage. You only need to specify routines that provide entity objects. Any routine that brings new pieces of entity objects is considered a provider and will be UPSERTed.
const userRoutines = const userStore =
Successful reponse
With this example. You can just dispatch loadAll success and the entities will immediately appear in the state.
userRoutinesloadAll
Multiple items
You get array processing for free, so you can put multiple objects to one action.
userRoutinesloadAll
Identifiers
Entity store requires single value unique identifier for all entities. You can either specify the identifier attribute name or identifier resolver. Default identifier is uuid
IDs example
const userStore = // { id: 1, name: 'Luke Skywalker' },
HATEOAS example
If you use HATEOAS based communication, you can simply leverage hateoas-hal-link-resolver as ident resolver. It supports multiple HAL link standards and it will automagically translate them.
const userStore = // { name: 'Luke Skywalker', _links: { self: '/users/1' } },
Delete entities
Easy, just use a routine. To prevent collisions with JavaScript reserved words, try using 'drop' or 'remove' instead of 'delete'.
const userRoutines = const userStore = // { name: 'Luke Skywalker', _links: { self: '/users/1' } },
Entity initial state
You can specify the initial state, for example when you create just a partial entity. It will be used as an overlay for all incoming entities.
const userStore = userRoutinesloadAll /*{ email: '', id: 5, name: '', phone: ''}*/
Clear entity store
The entity store autogenerates clear routine used to simply erase the entity store. If you need more of these, you can just create another routine.
const userRoutines = const userStore = // Synchronous clear // Clears on SUCCESS
Modifier reducers
In case you have specific needs to reduce entity objects, you can use modifiers. A modifier reducer always receives single item state and single item payload.
const userRoutines = const userStore =
Be careful about naming collisions. If you use action type as a provider, you cannot use it as a modifier, therefore loadAll.SUCCESS
could not be used here in this example.
Collection reducers
In case you have very very specific needs to reduce the whole entity collection, you can use collection reducers. A collection reducer always receives whole collection state and whole payload.
const userRoutines = const userStore =
Relations
In case you expect to receive nested entity objects, it is useful to define relations between object entities. All entity stores are automagically connected in a way that it will distribute entities to their stores and reference them as in relational database.
Many To Many
const groupRoutines = const userStore = const groupStore =
Consider following action being dispatched:
Entity store will distribute and reference the state.
belongsTo, hasMany
To be done. These were not needed yet.
Relation naming
To be done. At this moment, the relation naming must be 1:1 with entity store naming.
Selectors
Get all
Just returns all objects in the collection.
const userStore = { return users: userStore }
Get specific object
Returns and memoizes single entity object.
const userStore = { return user: userStore }
Get specific object based on state
Returns and memoizes single entity object.
const userStore = const getSelectedUser = userStore { return user: }
Given following state, it would return object representing Commander Data.
Get object property
Returns and memoizes single object property
const userStore = { return userName: userStore }
Get object flag
Returns and memoizes single object property, assuming it is a boolean
const userStore = { return hasName: userStore // returns true or false }