@zajdasoft/grocery v1.0.4
grocery
Grocery JS / container for managing application state, designed to be used in modular applications. Combining power of flux-like store and messaging system.
About
Grocery is designed for typical portal web application. Modules can be loaded during application lifetime, providing many useful widgets for your dashboard, website builder, etc. In such scenario single store powering whole system gets complicated and low performant. This brings the idea to split the single store to multiple groceries.
Breaking a store to smaller entities might bring a need to communicate changes between groceries. Because of that Grocery comes with messaging system (publisher-subscriber pattern).
Installation
$ npm install @zajdasoft/grocery
or:
$ yarn add @zajdasoft/grocery
Usage
Basic usage
In your src
directory create new directory groceries
. In this directory create new file MyGrocery.js
like this:
import Grocery from '@zajdasoft/grocery';
export const ADD_TODO = 'ADD_TODO';
const MyGrocery = new Grocery({
initState: {
toDos: [],
},
});
MyGrocery.addReducer((state, { type, payload }) => {
switch (type) {
case ADD_TODO:
return {
...state,
toDos: [
...state.toDos,
payload
]
};
}
});
export default MyGrocery;
In your Application
component you need to bind the grocery to react:
import React from 'react';
import MyGrocery from './groceries/MyGrocery';
import MyComponent from './MyComponent';
const Application = () => (
<MyGrocery.Connector>
<MyComponent />
</MyGrocery.Connector>
)
export default Application;
In your component src/MyComponent.jsx
then:
import React from 'react';
import MyGrocery, { ADD_TODO } from './groceries/MyGrocery';
const MyComponent = () => {
const { toDos } = MyGrocery.useGroceryState();
const { dispatch } = MyGrocery.useGrocery();
const addTodo = () => {
const todo = confirm('Add a to-do.');
if (!todo) return;
dispatch({ type: ADD_TODO, payload: todo });
}
return (
<>
<ul>
{toDos.map(item => <li>{item}</li>)}
</ul>
<button type="button" onClick={addTodo}>Add Todo</button>
</>
);
}
Messaging system
Let's say that there is a module which is going to alert count of stored to-dos when a todo is added. Let it be in
src/CountModule.js
:
import MyGrocery, { ADD_TODO } from './groceries/MyGrocery';
MyGrocery.subscribe(ADD_TODO, ({ payload }) => {
alert(`There are ${payload} to-do(s).`);
});
Now, because reducers should not have any side-effects, we need to publish the message in our MyComponent
:
import React from 'react';
import MyGrocery, { ADD_TODO } from './groceries/MyGrocery';
const MyComponent = () => {
const { toDos } = MyGrocery.useGroceryState();
const { dispatch, publish } = MyGrocery.useGrocery();
const addTodo = () => {
const todo = confirm('Add a to-do.');
if (!todo) return;
dispatch({ type: ADD_TODO, payload: todo });
publish({ type: ADD_TODO, payload: toDos.length + 1 });
}
return (
<>
<ul>
{toDos.map(item => <li>{item}</li>)}
</ul>
<button type="button" onClick={addTodo}>Add Todo</button>
</>
);
}
Enhancing reducers
In some particular cases we might want to enhance a reducer from another module. To achieve that we need to name
the reducer which should be enhanced. This can be done by adding name to addReducer
call. Note that reducers
without a name can't be enhanced. Naming a reducer should make the reducer aware that it might be enhanced.
In src/MyGrocery.js
:
import Grocery from '@zajdasoft/grocery';
export const ADD_TODO = 'ADD_TODO';
export const REDUCER_BASE_TODO = 'REDUCER_BASE_TODO';
const MyGrocery = new Grocery({
initState: {
toDos: [],
},
});
MyGrocery.addReducer((state, { type, payload }) => {
switch (type) {
case ADD_TODO:
return {
...state,
toDos: [
...state.toDos,
payload
]
};
}
}, REDUCER_BASE_TODO);
export default MyGrocery;
Now we can enhance our reducer from src/AnotherModule.js
:
import MyGrocery, { REDUCER_BASE_TODO } from './groceries/MyGrocery';
MyGrocery.enhanceReducer(REDUCER_BASE_TODO, (state, action, next) => {
const newState = next();
console.log('New to-do list', newState.toDos);
return newState;
});
Enhancer takes another parameter next
which calls next enhancer in the chain or final reducer.
next
takes up to two parameters newState
and newAction
. These will be passed as state
or action
to the reducer or another enhancer.
From Grocery perspective, enhancer is another reducer, which makes possible to enhance even enhancers. First,
enhanceReducer
must take third argument as name for the enhancer. Then you can enhance the enhancer in another module.
This example shows how to use next
to change ADD_TODO
action when its payload is 'test'
:
import MyGrocery, { REDUCER_BASE_TODO } from './groceries/MyGrocery';
MyGrocery.enhanceReducer(REDUCER_BASE_TODO, (state, action, next) => {
const newState = next(state, action.payload === 'test'
? { ...action, payload: 'replaced' }
: action);
console.log('New to-do list', newState.toDos);
return newState;
});
Middlewares
Grocery supports usage of middlewares. Middlewares are called for all groceries in your application. This allows to handle development or error logging in one place.
import { addGroceryMiddleware, addGroceryLogger } from '@zajdasoft/grocery';
addGroceryLogger();
addGroceryMiddleware(grocery => next => action => {
console.log(grocery.getState());
return next(action);
});
License
Licensed under L-GPL v. 3.