redux-react-local

redux-react-local
---

npm install redux-react-local --save

warning: the api's in a state of flux right now

(badum-tsh)

tl;dr

``jsx
import { local } from 'redux-react-local'

// connect your components
@local({
ident: 'app',
initial: { count: 0 },
// optionally -
reducer(state, action) {
if(action.me) { // happened 'locally'
switch(action.meta.type) {
// case: increment decrement etc
}
}
// reduce on other global dispatches here
return state
}
})
class App extends React.Component {
render() {
let { state, dispatch, $ } = this.props
return (

Add the supplied reducer to a key local on your redux store.
`jsx
// ...
combineReducers({
// your other reducers
local: reducer
})
// ...
`

and wrap your app with the Root component
`jsx
// ...





// ...
`

local
---

decorator for a react component

- ident - a 'unique' string that corresponds to the component. eg - 'app', 'inbox', 'messages:341', etc
- ident (props) - a function that returns the above
- initial - initial local state
- initial (props) - a function that returns the above
- reducer (state, {type, payload, meta, me}) - a local reducer on every action on the store, me will be true for actions dispatched locally, and meta.type will not have the ${ident}: prefix
- persist - a boolean on whether the state should persist in the store on unmount, defaults to true


passed props
---

- ident - as above
- dispatch(action) - via redux
- $ - helper to locally scope an action
- state - current local state
- setState(state)


rationale
---

(This assumes some familiarity with React and redux)

So, React's 'components' are awesome, and lets us describe our UIs as trees/hierarchies. Lovely. I'm a big fan of architectures that are 'fractal' - where the 'big' elements are 'composed' of similar looking smaller ones, and React's components fit the bill. (Other examples - functions, observables, channels, js objects(!), etc) 1

However, because 'views' don't have global references / identities ala Backbone etc, communicating between these components can get cumbersome 2; we then resort to building some form of messaging system external to these components - callbacks, pubsub channels, flux stores, observable event chains, etc. The smart ones use context to expose these systems to a particular render tree, avoiding 'global' state, but still getting a similar model.

Redux is a popular implementation of the flux pattern - all application state is held in one js object, where the value of each of its keys correspond to a 'reducer' function that gets called on every 'action' that's 'dispatched'. Components / external sources can then dispatch actions to 'effect' state in a controlled manner. Very nice.

Redux expects you to declare all your reducers outright at the beginning of the app's lifecycle. This is great for state that -

- will exist through the lifecycle of the app
- makes sense 'across' the app. eg - currently logged in user details, databases/caches, mouse/touch positions, etc.
- isn't usually associated with a specific component on the page (unless that component is alive for the life of the app)


However, this approach doesn't work well for 'dynamic' components that might pop in and out of existence. eg - imagine a dynamically fetched list of tweets (length unknown till after fetch), each with buttons to like/retweet etc. When hovering/clicking these buttons, we'd need to store this state somewhere. Options -

1. We use this.setState(), but then that state is opaque to the rest of the app. We'd have to dispatch actions on every setState, and then have extra logic to differentiate based on type and some form of id, and this is already getting out of hand...
2. We store an array of components states, indexed by some key/id, and update that as and when. However, this collection's 'information' was already available in the react tree itself, and it's a shame we don't use it.
3. This is complicated by the fact that each of these elements might have an initial state that's based on its props. This leads to boilerplate on mount/unmount to prime/remove this state, and we end up jumping too many files for something that's really local to just one component.
4. Actions are differentiated (dynamic dispatch?) based on their string 'type', which implies a global 'namespace' of sorts for these action types. This is usually fine, but leads to ickiness in the above situation. ie - should one dispatch 'hover', {id} or '${id}:hover'?, etc

With the above issues, we lose the fractal nature of our architecture. which makes me a sad puppy. Sad puppies are officially considered an animal rights violation, so we have to do something about it.

What I'd really like to do is -

- define a reducer for a component's local 'state'
- that's called for all actions across the app
- that activates/deactivates with the component's mount/unmount lifecycle
- this state should correspond to a key/ ident on the redux store
- this ident could be dynamically generated as a ƒ(props)
- dispatch 'locally scoped' actions - ie - where the action type is a ƒ(ident)
- would be nice if the local reducer could 'recognize' actions that originated from 'itself'

[drum roll...]

redux-react-local to the rescue! At its simplest, it looks like this -

`jsx
@local({
ident: 'app',
initial: 0,
reducer(state, {type}){
if (type === 'increment'){
return state + 1;
}
return state;
}
})
class App extends Component{
render(){
return

`

We annotate our components with a @local decorator declaring -

- ident - short for 'identity', we use this value as a key on our internal store, among other things. This is either a string ('app', 'inbox', etc), or a function that receives this component's props and returns a string.
- initial - initial state for this component. Can also be a function that receives props and returns the initial state.
- reducer - a reducer for local state; recieves all actions that flow through the redux store.
- persist - a boolean indicating whether to 'keep' the state after the component has unmounted

The wrapped component will then recieve these props -

- dispatch - same as redux's dispatch
- state - current local state
- ident - as above
- $ - a helper function to 'localize' actions.
- setState - a helper to set a value directly to the local store. Unlike react's setState, this does not merge values.

'local' actions
---

We need a way to generate actions that are 'local' to the component that's dispatching them. We can use $ which accepts a type and a payload, and generates an action that's associated with the current component. It looks like this -
`jsx
$({
type: 'someAction',
payload: {some: 'payload'},
...moreStuff
})

// generates -

{
type: ${ident}:someAction,
payload: {some: 'payload'},
...moreStuff,
meta: {
ident: ident,
type: 'someAction'
}
}
`

Further, when reducing these actions, we can 'recognize' these actions.

`jsx
reducer(state, {me, meta, payload}){
if(me){ // happened locally!
switch(meta.type){
case 'someAction': //...
}
}
// you could 'listen' to all other global dispatches here
return state;
}
`

Convenient!

spiel
---

Fractal architectures are very nice to grok and work on, because it means you 'think' about your app the same way no matter what level of abstraction you're working on.

But also, there's value in being able to describe your system at very low levels, and have your software treat it as a global concern and optimize accordingly.

An example is the way React does event handling - when we first learn about front end web development, we attach event handlers directly on elements (