Side Effect JS
Easy to setup and use - 3 lines of configuration and you can test your single page application like it's really connected to an API / Writes to files etc.
Version:
- V2.1.0
How to use:
-
Install
side-effect-js
from npm :npm install side-effect-js --save
-
Create side effects file - the name is not important and export an array of side effects:
//side-effects-my-app.js;var newConsoleEffect = SideEffectJS;var fetchEffect = SideEffectJS;newConsoleEffect fetchEffect;Note: side effect is an object that must contain: id: string, run: func, simulate: func - id is unique, defining duplicate ids will throw an error
SideffectsJS load failed, Found duplicate id in effects:$id
on load. -
On the root of your app - load all side effects to SideEffectJS:
//App.js or index.js;SideEffectJS; -
When you want to use the
simulate
effect - just add afterSideEffectJS.Load
this line:SideEffectJS.UseSimulator();
Don't use
SideEffectJS.UseSimulator()
on production.
Better way to run in simulator mode without Changing the code (v2.0.0+)
Old way (changing code):
In versions previous to 2.0.0 when you wanted to use the mock side effects you should call SideEffectJS.UseSimulator();
in your code.
You can still do it - but then you need to change this line all the time.
New way (use process.env):
All you need to do is to initiate SIMULATE_SIDE_EFFECTS=1
and you will get the mock effects.
For example instead of using: node index.js
run: SIMULATE_SIDE_EFFECTS=1 node index.js
.
For react applications using CRA (create react app) - you can use REACT_APP_SIMULATE_SIDE_EFFECTS=1
in the .env
files.
Read more on Create React App .env:
https://create-react-app.dev/docs/adding-custom-environment-variables/
- Consume effects from SideEffectJS:;var effect = SideEffectJS;;
What do you need it for?
If you are developing single page application (Frontend) or Node.js apps (Backend) - most of the times you will have a server that returns responses to your client.
Almost any application has side effects:
- Using AJAX to call remote servers (Your REST API / Firebase or other serverless).
- Reading / Writing to files (on the server side)
In order to mock those I/O operations - you need to change your code frequently - means you should replace those I/O with some "stub" code.
So - what can we do better?
Use the side-effect method
Write all side effects in some aggregated place and load real / stub behaviour on run time.
Example:
Let's assume we are using redux-thunk or redux-saga and we need to fetch some data. What will we do with this data? save it to the state - and baiscally it will cause the UI to re-render and display something.
So instead of using this example thunk we will use the side-effects approach:
//some-redux-thunk-example const myThunk = { ; // I.O operation
This is how it will look when using Side Effect JS:
//some-redux-thunk-example ; const myThunk = { ; // I.O operation SideEffectJSusername password
What are the benefits of this approach?
- You are aware of IO - because you define side effect for each operation.
- You can mock and stub any i/o operation - and work on real app like it's consuming data from an API.
- You don't need to handle mock api and configure it all the time.
- You have one place that holds all the side effects of your app (in DDD terms it enfources infrastructure layer)
- You app will be easier to test
- By creating the side effects file you are creating documentations for you app's side effects.
What's next?
In the next versions there will be full support for:
- Display all the side effects that your application actually uses in real time.
- Better documentations & Examples.
- Support for middlewares - so you will be able implement anything you want.
Release notes:
V2.1.0: - 04/27/2020
Deprecated (ts only):
For TypeScript only - CreateEffect
is deprecated (backward compatible), instead use: CreateEffectTyped
.
Typescript usage example:
//T - The model that mock and real function gets//R - The result type of the mock and real function
//Example.ts; //Old way of creating effect; //New way of creating effect(V2.1.0+) - ensures real effect and mock effect has the same contract;
V2.0.0: - 04/26/2020
Instead of using SideEffectJS.UseSimulator()
- which forces you to change code -> use SIMULATE_SIDE_EFFECTS=1
or REACT_APP_SIMULATE_SIDE_EFFECTS=1
for CRA apps.
SideEffectJS.UseSimulator()
is still an option but it forces you to change code before merging.
Read more on Create React App .env:
https://create-react-app.dev/docs/adding-custom-environment-variables/