RunGen
This library provides a generic runtime around async flow in javascript. This provides something like co with the ability to extend its behaviour. This is also largely inspired from redux-saga. It first started from the idea of decoupling redux-saga from redux.
API
If you're familiar with co, The API here is slitely different. Instead of taking a generator and returning a promise. We can take basically any value (pass in an iterator to have the same behavior as co for generators) and as a result uses callbacks instead of a promise.
const myGenerator* yield new Promise } const runtime = const onSuccess = consoleconst onError = console
If you want to have a similar API than co
, It's as easy as
const runtime = const co = co runtime
Generic ?
Co allows to you to wrap generators that yields automatically promises, iterators, arrays etc... The idea of genericity here is the ability to perform a custom process on any value depending on your needs. We call these custom processes : controls.
Built-in Controls
By default, you can yield generators, arrays, objects and errors : These are the base controls included in every runtime.
// Create a runtimeconst runtime = const myGenerator = { const value = input return value} // Run the generator
Instead of running your generator directly, you can also get a simple function from your generator and run it later
const myFunction = runtime // Run it later
Sub-generators
Nesting generators is allowed using the built-in generator control.
const increment = { input return input + 1}
Arrays
By using the all
helper, yield arrays will make the runtime resolve all the values of the array and get the result as an array.
Here is an example combining the array and the subgenerator control.
const increment = { input return input + 1}
Objects
By using the all
helper, in the same way as arrays, yielding javascript objets will resolve all the attributes of the objects
and return an object containing the resolved values.
const increment = { input return input + 1}
Async controls
RunGen offers you some async controls that allows you to write basically any async flow in a simple declarative way. These controls are opt-in, this means you can choose to use them or not in your runtime. Here is how to do that.
// creating a runtime with these controlsconst runtime =
Promise
Async controls allows you to yield promises, the runtime resolves the promise and returns the resolved value on success or trigger an error on failure.
fork/join
When dealing with async flows, we need a way to trigger non blocking calls, this can be done easily using the fork
helper.
const subGenerator = { console} // this will output 2 than 1
We can get the result of a forked generator using the join
helper (join raises an error if the forked task has already finished)
const subGenerator = { console return input+1} // this will output 2 than 1
race
Race is a special control that lets you deal with race conditions. For example : timeouts on API calls.
Race can also be used using arrays
Wrap controls
To ease testing generators without the need of mocks, we have to avoid triggering any side effect (api calls, timeouts...) in the generator. We use some of those effects in our previous example : calling fork, join or race helpers returs a simple javascript object and doest trigger any side effect. The wrap controls can be used to extend this mecanism to any function call.
invoke, call and apply
those are helpers used to tell the runtime to trigger a function call, but the function is not called directory in the generator.
runtime = { return } const myGenerator = return result}
testing this generator is now straighforward
// the generator to testconst gen = // Asserts
apply
and call
do the same thing as the invoke
helper with the ability to specify a context (the this
inside the function call)
cps
In nodejs, libraries often use cps (Continuation-passing style). functions expecting the last argument to be a callback with the following signature : (err, result) => void
RunGen provide a helper that wraps these kind of function calls.
{ }
Custom Controls
A control is an function with the following signature (value, next) => bool
- the function returns a boolean whether or not, it handles the yielded value passed as argument
- Once the value has been resolved, It should call the
next
callback with the result
Let's say we are going to create a control that allows us to get values from the localStorage
// pushing data testlocalStorage // Creating the custom controlmyCustomLocalStorageControl = value next if typeof value !== 'object' || valuetype !== 'localstorage' return false return true // Creating a runtime with this controlruntime =
While this should be fine for almost all custom controls use cases, there are some cases when you would need to call some specific callbacks.
The full signature of the control is : (value, next, runtime, yieldNext, yieldError) => bool
- the
next
callback : we call this with a resolved value, when we handled the current value and we have no idea about the result (like promises) - the
runtime
callback : the runtime itself, can be used to perform nesting - the
yieldNext
callback : is a shortcut to avoid infinite loops, it directly yields the resolved value without trying to resolve it as well. This can be usefull to avoid infinte loops, for example in an arrayControl takes an array and yields an array as a result - the
yieldError
callback : called to trigger an error (that can be catched using try/catch in the generator)