Minimalist library for flux architecture with no production dependencies
npm install --save rad-flux
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.
Creating a new DataStore:
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:
console.log(myDataStore.state); // {}
myDataStore.setState({
hello: 'world'
});
console.log(myDataStore.state); // { hello: 'world' }
Removing existing values:
console.log(myDataStore.state); // { hello: 'world' }
myDataStore.setState({ hello: null });
console.log(myDataStore.state); // {}
Changing/removing existing values within nested objects:
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
myDataStore.onStateChanged(() => {
console.log(myDataStore.state); // { something: 'else' }
});
myDataStore.setState({
something: 'else'
});
Unsubscribing from state changes:
// 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:
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 }
Creating a new set of actions:
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:
myActions.on('doStuff', () => {
console.log('yo');
});
// Make the action happen
myActions.call('doStuff');
Doing stuff inside of an action:
// 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:
// 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:
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:
// 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);
// 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);
});
// 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 });
});
});
// 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);
}
Coming later
git clone https://github.com/747823/rad-flux.git
to get reponpm install
to get developer dependenciesnpm run build
to build distribution filesnpm run test
to run unit tests