Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/evanpipta/rad-flux
Minimalist library for flux architecture with no production dependencies
https://github.com/evanpipta/rad-flux
es6 flux flux-architecture node-module npm-module
Last synced: about 1 month ago
JSON representation
Minimalist library for flux architecture with no production dependencies
- Host: GitHub
- URL: https://github.com/evanpipta/rad-flux
- Owner: evanpipta
- Created: 2017-04-22T15:26:14.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2017-08-25T17:11:28.000Z (over 7 years ago)
- Last Synced: 2024-10-29T05:38:37.230Z (about 2 months ago)
- Topics: es6, flux, flux-architecture, node-module, npm-module
- Language: JavaScript
- Homepage:
- Size: 33.2 KB
- Stars: 4
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# rad-flux
Minimalist library for flux architecture with no production dependencies
### Installation
`npm install --save rad-flux`
### Contents:
- [Concepts](#concepts)
- [Usage Guide](#usage-guide)
- [Development](#development)
----------------
## Concepts
`rad-flux` takes a few key concepts from flux architecture, Actions and Data Stores, and cuts out everything else. It provides a simple, unopinionated, and non-magical interface to implement a simple form of flux architecture. The goal of `rad-flux` is to be intuitive, easy, and fast to start using.
The only pieces of `rad-flux` are two constructors: `DataStore` and `Actions`.
A DataStore represents a piece of application state. `rad-flux` doesn't dictate how these pieces are split up; a `rad-flux` DataStore can be used to store the entire state of an application, or of a single component. The important thing is that a `rad-flux` DataStore has a non-destructive `setState()` method that publishes change events to subscribers.
An instance of Actions in `rad-flux` represents one group of actions that can be done within an application. Actions are source agnostic, i.e. can be used for actions initiated by the user, or by the program. `rad-flux` provides an interface to call actions and subscribe to action calls from anywhere. It supports synchronous and asynchronous actions, and does not dictate whether or not actions should have built-in side effects.
`rad-flux` has no reducers, dispatchers, or other concepts found in other flux implementations. It really boils down to two simple "flows":
- You create a store, listen to changes to that store's state from anywhere (and change it from anywhere), and then decide what to do next.
- You create actions, listen for when they happen from anywhere (and make them happen from anywhere), and then decide what to do next.
Where you go from there is up to you.
----------------
## Usage guide
### Using DataStore
**Creating a new DataStore:**
```javascript
const { DataStore } = require('rad-flux');
const initialState = {};
const myDataStore = new DataStore(initialState);
// I recommend exporting your DataStore instances to share across the app
```
**Changing the DataStore's state:**
```javascript
console.log(myDataStore.state); // {}
myDataStore.setState({
hello: 'world'
});
console.log(myDataStore.state); // { hello: 'world' }
```
**Removing existing values:**
```javascript
console.log(myDataStore.state); // { hello: 'world' }
myDataStore.setState({ hello: null });
console.log(myDataStore.state); // {}
```
**Changing/removing existing values within nested objects:**
```javascript
myDataStore.setState({
nested: {
foo: 1,
bar: 2
}
});
console.log(myDataStore.state.nested); // { foo: 1, bar: 2 }
myDataStore.setState({
nested: { foo: 10 }
});
console.log(myDataStore.state.nested); // { foo: 10, bar: 2 }
myDataStore.setState({
nested: { foo: null }
});
console.log(myDataStore.state.nested); // { bar: 2 }
```
**Subscribing to state changes**
```javascript
myDataStore.onStateChanged(() => {
console.log(myDataStore.state); // { something: 'else' }
});
myDataStore.setState({
something: 'else'
});
```
**Unsubscribing from state changes:**
```javascript
// onStateChanged returns a reference to the callback
const ref = myDataStore.onStateChanged(() => {
// ...
});
// Pass it to unsubscribe to remove the callback
myDataStore.unsubscribe(ref);
```
**Replacing the state entirely:**
```javascript
myDataStore.setState({
loggedIn: true,
userData: {
name: 'you',
superSecretInfo: 'you don\'t want to know'
}
});
console.log(myDataStore.state); // that whole object up there ^
myDataStore.replaceState({
loggedIn: false
});
console.log(myDataStore.state); // { loggedIn: false }
```
### Using Actions
**Creating a new set of actions:**
```javascript
const { Actions } = require('rad-flux');
// Add your action names as keys (the values don't matter)
const myActions = new Actions({
'doStuff': null,
'doMoreStuff': null
});
// I recommend exporting your Actions instances to share across the app
```
(Note: the reason we pass in an object here instead of an array is to avoid generating a bunch of "hidden classes" when iterating over the actions to create the internal action objects)
**Subscribing to an action:**
```javascript
myActions.on('doStuff', () => {
console.log('yo');
});
// Make the action happen
myActions.call('doStuff');
```
**Doing stuff inside of an action:**
```javascript
// To do stuff inside of an action use .registerAsync()
myActions.registerAsync('doStuff', (done) => {
doSomeAsyncStuff()
.then(() => {
done(); // call done() whenever the stuff the action was doing is complete
// there's no distinction between synchronous and asynchronous here, you must always call done()
});
});
myActions.on('doStuff', () => {
// Won't reach this point until doSomeAsyncStuff() is complete.
});
myActions.call('doStuff');
```
Note: you can only call .registerAsync() once per action, it permanently sets the registered function for that action.
The idea here is to make sure actions themselves only do one thing, from one place. If you want your actions to indirectly cause other "effects", subscribe to them externally and do stuff after they complete.
**Actions that take data and do stuff with it:**
```javascript
// If we want to do something like call an API, and we need to take arguments, we can do this:
myActions.registerAsync('callAnApi', (done, args) => {
console.log(args); // { foo: 'bar' }
someApiCallThatTakesArguments(args)
.then(() => {
done();
});
});
myActions.call('callAnApi', { foo: 'bar' });
```
**Actions that do stuff and then pass data to their subscribers:**
```javascript
myActions.registerAsync('callAnApi', (done, args) => {
someApiCallThatTakesArguments(args)
.then((response) => {
done(response);
});
});
myActions.on('callAnApi', (response) => {
console.log(response); // the results of the action, whatever that may be
});
myActions.call('callAnApi', {
foo: 'bar'
});
```
**Unsubscribing:**
```javascript
// myActions.on returns a ref to the subscriber function, just like DataStore:
const ref = myActions.on('someAction', () => {
// ...
});
myActions.unsubscribe('someAction', ref);
// ------- Alternatively ----------
function callback() {
// ...
}
myActions.on('someAction', callback);
myActions.unsubscribe('someAction', callback);
```
### Putting together the DataStore and Actions (one possible way to do it):
```javascript
// data-stores/my-data-store.js
const { DataStore } = require('rad-flux');
const myActions = require('./actions/my-actions');
const myDataStore = module.exports = new DataStore({});
myActions.on('submitTheAwesomeForm', (response) => {
myDataStore.setState(response.data || response.error);
});
```
```javascript
// actions/my-actions.js
const { Actions } = require('rad-flux');
const myActions = module.exports = new Actions({
'submitTheAwesomeForm': null
});
myActions.registerAsync('submitTheAwesomeForm', (done, formData) => {
callTheApi(formData)
.then((response) => {
done(response);
})
.catch((error) => {
done({ error });
});
});
```
```javascript
// app.js
const myActions = require('./actions/my-actions');
const myDataStore = require('./data-stores/my-data-store');
console.log(myDataStore.state); // Does not contain anything
myDataStore.onStateChanged(() => {
console.log(myDataStore.state); // Now it contains the data that resulted from the user's action
});
function userSubmittedAwesomeForm(formData) {
myActions.call('submitTheAwesomeForm', formData);
}
```
### Further examples
Coming later
----------------
## Development
- `git clone https://github.com/747823/rad-flux.git` to get repo
- `npm install` to get developer dependencies
- `npm run build` to build distribution files
- `npm run test` to run unit tests