https://github.com/gnapse/keflux
Flux workflow using Kefir's FRP streams
https://github.com/gnapse/keflux
Last synced: 12 days ago
JSON representation
Flux workflow using Kefir's FRP streams
- Host: GitHub
- URL: https://github.com/gnapse/keflux
- Owner: gnapse
- Created: 2015-07-02T20:54:01.000Z (almost 10 years ago)
- Default Branch: develop
- Last Pushed: 2015-07-02T21:40:03.000Z (almost 10 years ago)
- Last Synced: 2025-05-12T23:53:18.778Z (12 days ago)
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/keflux
- Size: 117 KB
- Stars: 5
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Keflux
**Keflux** is a library that allows to use [event streams][] to build a
[Flux][] architecture in a front-end [React][] app. It uses [Kefir][] for all
FRP-related code, and as part of the library name. It also embraces the use of
[immutable][] data structures, as an integral part of how it is designed, and
how it works.
[event streams]: https://en.wikipedia.org/wiki/Functional_reactive_programming
[Flux]: https://facebook.github.io/flux/
[React]: https://facebook.github.io/react/
[Kefir]: https://rpominov.github.io/kefir/
[immutable]: https://facebook.github.io/immutable-js/
## Stores
Keflux promotes the concept of self-contained stores, each defining its data
structure and the actions that are available to perform on it. Below is an
example store for a todo-list app:
```javascript
const TodoStore = Keflux.Store({
create(stream) {
return stream.
filter((text) => text.trim().length > 0).
map((text) => {
const todo = Immutable.OrderedMap({
id: uuid.v1(),
text: text,
completed: false,
});
return (data) => data.set(todo.get("id"), todo);
});
},
updateText(stream) {
return stream.
filter((params) => params.text.trim().length > 0).
map((params) => {
return (data) => data.setIn([params.id, "text"], params.text);
});
},
toggleComplete(stream) {
return stream.map((todo) => {
return (data) => data.setIn([todo.id, "completed"], !todo.completed);
});
},
destroy(stream) {
return stream.map((todo) => {
return (data) => data.remove(todo.id);
});
},
clearCompleted(stream) {
return stream.map(() => {
return (data) => data.filter((todo) => !todo.get('completed'));
});
},
toggleAll(stream) {
return stream.map((checked) => {
return (data) => data.map((todo) => todo.set('completed', checked));
});
},
});
```
Each action method receives a stream of events, each event being an invocation
by the app to trigger that particular action. These action methods can then
transform this stream using traditional FRP functions (filter, map, etc.)
The resulting stream should issue a series of functions, that when applied to
the underlying data structure, modifies it in a way consistent with the action
invoked.
For more real-world-like examples, take a look to a couple of stores in the
`examples/` directory. Those are todo-list stores but with persistend storage
(one to local storage, and the other to an ajax json api).
### Understanding how it works
To better understand this concept, let's look in detail at the `create` action
from the example above:
```javascript
create(stream) {
return stream.
filter((text) => text.trim().length > 0).
map((text) => {
const todo = Immutable.OrderedMap({
id: uuid.v1(),
text: text,
completed: false,
});
return (data) => data.set(todo.get("id"), todo);
});
}
```
The `stream` received as argument above will emit a new value each time the app
invokes this action on the store. The first thing the action does is filtering
out those invocations made with an empty text, since we do not want to-do items
whose text is an empty string.
Then the valid events (those with non-empty text) are mapped to a function that
receives the underlying data structure of the store (an [immutable map][]), and
returns a copy of it, but with the new todo-item added to it.
[immutable map]: facebook.github.io/immutable-js/docs/#/Map
The result is a new stream of functions, that when applied to the store's data
structure, each add a new todo item to it, as requested by the app using this
store. The store takes care of applying these functions to the underlying data
structure, on each iteration of the stream processing.
## Usage on a React.js app
Keflux stores expose a stream called `changes`, which emits a new value each
time the underlying data structure changes as a result of triggering one of its
actions.
So once stores are defined like it is described above, a React.js component can
subcribe to the `changes` on this store, and update its state to match the
store's data. This is shown in the following example:
```javascript
const TodoApp = React.createClass({
propTypes: {
store: React.PropTypes.object,
},
getInitialState() {
return {
data: this.props.store.data,
};
},
componentDidMount() {
this.props.store.changes.onValue((data) => this.setState({data}));
},
render() {
// ...
},
});
```
There are plans to provide a mixin for components to easily declare that its
state depends on one or more stores, as well as to take advantage of [React.js'
contexts][] to implicitly pass stores to child components.
## What's next
This is a list of features that have not been explored or implemented yet.
* Automated tests.
* How does error handling fits with this architecture.
* Mixin for easing the access to stores/actions in components via [React.js' contexts][].
* Registering callbacks to handle action completion.
[React.js' contexts]: https://blog.jscrambler.com/react-js-communication-between-components-with-contexts/