Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/limscoder/react-wrangler
A react component for simple declarative state management with "one way data flow" and side effects
https://github.com/limscoder/react-wrangler
data-flow persistent-data react redux rest
Last synced: 2 months ago
JSON representation
A react component for simple declarative state management with "one way data flow" and side effects
- Host: GitHub
- URL: https://github.com/limscoder/react-wrangler
- Owner: limscoder
- License: mit
- Created: 2016-12-18T14:35:59.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2017-02-10T16:31:14.000Z (almost 8 years ago)
- Last Synced: 2024-04-23T13:26:49.680Z (9 months ago)
- Topics: data-flow, persistent-data, react, redux, rest
- Language: JavaScript
- Homepage:
- Size: 325 KB
- Stars: 16
- Watchers: 4
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# react-wrangler
`react-wrangler` simplifies state management by using a declarative component
to implement "one way data flow" and side effects.
It's composable components all the way down:
no actions, reducers, selectors, generators, middleware, thunks, sagas, query fragments, or observeables required.
## Why?
One of the first things I learned when beginning react is that `props` serve as the public API for components.
It's a great concept because eliminating imperative function calls from the API makes components declarative and easily composable.
An entire react application is composed by defining a tree of react-elements and using event handlers to trigger state changes in response to user actions.
The `render->user action->update state->render` cycle is commonly referred to as "one way data flow".
This should be a very elegant solution to application development, but many state management frameworks force react developers to
struggle with imperative API calls invoked outside of the react-element render tree and allow side effects to be triggered from
anywhere in the application, making it difficult to reason about when and why side effects are triggered.
Does "one way data flow" need to be this complicated?
`react-wrangler` is an attempt to get back to basics and provide "one way data flow" with a simple, component based API.
## Example
Take a look at the [example counter application](https://limscoder.github.io/react-wrangler/pages/examples/counter/index.html) and the
[example application code](./examples/counter/App.js) for an idea of how `react-wrangler` works.
## Development
### Install
`react-wrangler` requires peer dependencies `immutable` and `react`.
```bash
> npm i immutable
> npm i react
> npm i react-wrangler
```
### Configure
The `Wrangle` component provides a single place to store your state, represented as an [immutable Map](https://facebook.github.io/immutable-js/docs/#/Map).
Pass the `initialState` prop to the `Wrangle` component to define the application's starting state.
It uses `context` to expose data to descendant components, so it should only be rendered once at the root of an application.
```javascript
import { fromJs } from 'immutable';
const initialState = fromJs({
user: {
id: '137af8eb-6baf-42a8-a38a-3df6fc36d562',
display: 'username999',
email: '[email protected]',
preferences: {
showFirstTimeHelp: true
}
},
});
ReactDOM.render(
);
```
### Paths
`paths` are strings used to reference nodes within `react-wrangler` state.
Using `initialState` from above:
```javascript
// path === 'user.id'
> '137af8eb-6baf-42a8-a38a-3df6fc36d562'
// path === 'user.preferences'
> Map({
showFirstTimeHelp: true
})
// path === 'user.preferences.showFirstTimeHelp'
> true
// paths that are not present in state are undefined
// path === 'user.missing'
> undefined
```
### Path component
Use the `Path` component to retrieve `path` values from state and map them to `props`:
```javascript
import { Path } from 'react-wrangler';
function Welcome(props) {
const { displayName, showFirstTimeHelp, onDismiss } = props;
const firstTimeHelp = showFirstTimeHelp ?
: null;
return (
Welcome { displayName }
{ firstTimeHelp }
);
}
function WrangledWelcome(props) {
// map path values to props
//
// key === prop to map path value to
// value === path
const mapPathsToProps = {
displayName: 'user.displayName',
showFirstTimeHelp: 'user.preferences.showFirstTimeHelp'
}
// the `component` prop contains the component to
// be rendered with paths mapped to props.
return ;
}
```
### Mutation
An application isn't very useful if it can't mutate it's state.
Here is the example from above with state mutation in response to a user action:
```javascript
function onDismiss(store, ...args) {
store.setPath('user.perferences.showFirstTimeHelp', false);
}
function WrangledWelcome(props) {
// map callbacks to props
//
// key === prop to map callback to
// value === callback function
const mapCallbacksToProps = { onDismiss };
const mapPathsToProps = { ... };
return ;
}
```
### Side effects
`react-wrangler` simplifies application logic by isolating all side effects into two callbacks.
`Wrangle.onMissingPaths` and `Wrangle.onStoreChange` are the only 2 functions that should invoke side effects within a `react-wrangler` application.
#### Fetching data
Use `Wrangle.onMissingPaths` to fetch data.
It's up to the implementer to determine how the missing path values are fetched:
[Falcor](https://netflix.github.io/falcor/),
[Graphql](http://graphql.org/),
[Rest](https://en.wikipedia.org/wiki/Representational_state_transfer),
[LocalStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage),
[AsyncStorage](https://facebook.github.io/react-native/docs/asyncstorage.html),
etc.
`onMissingPaths` is called once-per-frame with an array of de-duplicated paths that have been requested, but are not present in state.
```javascript
function onMissingPaths(store, missingPaths) {
fetchPathsFromServer(missingPaths).then((pathValues) => {
// call setPaths to update state and
// re-render the view after pathValues are fetched.
store.setPaths(pathValues);
});
}
ReactDOM.render(
);
```
#### Persisting data
Use `Wrangle.onStoreChange` to persist data.
`onStoreChange` is called whenever `path` values are changed.
It's up to the implementer to determine how the path values are persisted,
such as `LocalStorage` or an API call that makes a network request.
```javascript
function onStoreChange(store, changedPaths) {
updatePathsOnServer(changedPaths)
.then(() => {
store.setPath('showNotification': 'saved successfully');
})
.catch(() => {
store.setPath('showNotification': 'failed to save');
});
}
ReactDOM.render(
);
```
### Debugging
Set the `debug` prop to enable debugging messages in the console.
```javascript
```
Debugging messages include information about each state update.
```
> store changed (5): counter.current
> elapsed time: 0.08500000000094587ms
> changed paths: {counter.current: 92}
> new state: {counter: {current: 92}}
> type 'resetState(5)' in console to return to this state
```
Use the `resetState` function in the console to retreive any previous state for "time travel" debugging.
Use the `setPath` function in the console to manually update state
(object and array values are automatically converted to Immutable data structures).
### Optimization
#### Use immutable data structures
`path` values should *always* be immutable so `Path.shouldComponentUpdate` can avoid unnessecary vdom re-renders.
```javascript
// don't set plain JS objects or arrays into state
setPath('user.preferences', { showFirstTimeHelp: true });
// use Immutable data structures instead
setPath('user.preferences', Immutable.fromJS({ showFirstTimeHelp: true }));
```
#### Batch calls to `setPath`
Invoking `setPath` triggers all `` components to check their state and possibly re-render, so it should be called as infrequently as possible.
If multiple paths need to be set at the same time, it's more efficient to invoke `setPaths` once instead of calling `setPath` multiple times:
```javascript
// set multiple paths in one call
setPaths({
'user.preferences.showFirstTimeHelp': false,
'user.displayName': 'Kathy'
});
```
#### Avoid inline closures for callbacks
Dynamically defined functions in `mapCallbacksToProps` will cause unnessecary vdom re-renders.
Use statically defined functions whenever possible.
#### Batch requests in `onMissingPaths`
It's recommended to batch network requests triggered from within `onMissingPaths`
into the fewest number of requests possible.
It's also important to note that `onMissingPaths` can be called multiple times with the same paths.
Everytime the component re-renders, `onMissingPaths` will be called with all missing paths.
Implementers must be careful to avoid duplicate network requests by keeping track of in-flight requests.