effed
v0.1.0
Published
Effects library for JavaScript
Downloads
3
Maintainers
Readme
effed
JavaScript library that elevates side-effects to the front line.
Inspired by project like redux
and redux-saga
effed proposes that idea that the code/business logic can be
expressed as a generator yielding effects (which are plain objects) and the run function that interprets those effects.
While inspired by redux
the proposed model of computation is generic enough to be used anywhere where generators
are supported, in the browser or in node.js environment.
Benefits
- Defer side-effect
- Synchronous testing
- Multiple interpretation of effects
- Effect composition, creating high-level DSL effects
Quick example
// inside fetch.js
import fetch from 'node-fetch'
// define middleware that will run fetch effects
export const fetchMiddleware = (run) => (next) => (effect) => {
if (effect.type === 'fetch') {
return fetch(effect.url, effect.options)
.then(response => response.json())
} else {
return next(effect)
}
}
// define effect creator function
export const fetch = (url, options = {}) => ({type: 'fetch', url, options})
// inside index.js
import {createRunner} from 'effed'
import {fetchMiddleware, fetch) from './fetch'
// create the run function that is capable of running generators yielding fetch effects
const run = createRunner(fetchMiddleware)
// run a generator function
run(function * () {
const content1 = yield fetch('http://url1')
const content2 = yield fetch('http://url2')
return [content1, content1]
}).then(console.log, console.error)
// => [{...}, {...}] contents of url2 and url2 are returned in a Promise
Concepts
Effect - a plain JavaScript object defining the side-effect requested. The "primitive" effects define some IO
operation, e.g. fetch a url, read a file, query database. The "primitive" effects can be combined into higher level
effects by either using combinators like parallel
, race
, sequence
, or defining a generator that combines
other effects and returns the result.
run - is a function that is able to drive passed in generator until it completes, using a chain of middleware. Generally on a project, there will be one module that export such function, already created with all middleware that a project uses.
run :: Effect -> Promise<any>
middleware - implements the logic of running an effect and returns a promise with the result of the effect.
Middlewares are passed to createRunner
function, where they are chained internally into a pipeline and used
to run each effect. To write a middleware one simply needs to define a function with the following signature:
middleware :: run -> next -> effect -> Promise<effect result>
// inside ./run.js
const myMiddleware = (config) => (run) => (next) => (effect) => {
if (effectIsForMe(effect)) {
// can use run function here to run a sub-effect if needed
return Promise.resolve(someResult)
} else {
// continue the chain of processing
return next(effect)
}
}
const importedMiddleware from 'importedMiddleware'
export default createRunner(myMiddleware({}), importedMiddleware({}))
Composition of effects
// How do we combine multiple effects? // Option 1: Create larger effects, with its own creators and runners // Option 2: Combine several low level effects using generators
Testing
The major benefit of expressing the logic as a generator emitting effects is the ease of testing.
The scripts themselves are synchronous generators, and the tests just need to verify that they emit correct sequence of effects when fed predefined results of previous effects.
FAQ
Questions
- how is stack handled? Free monad trampolines computation without using stack, will generators do that?
Write your program using exactly the language you need. Compose your language from smaller orthogonal languages, in a canonical way. Plug in interpreters that support the behavior you want.