SetlistJS
Setlist will sequential-ish your asynchronous code with ES6 Generator Function and Promise - Say goodbye to indentation hell.
TOC
- Setup
- Getting Started
- Setlist Chain
- Wrapping Callback Function
- Transform Generator Function Class with Promise
- Create Callback Handler with Generator Function
- Testing
- Bugs
- License
Setup
Install it with npm
.
npm install --save setlist
Then use them in your project by requiring setlist
.
const run = ;
Getting Started
This topics requires you to understand the basics of Promise https://www.promisejs.org
This is an example of function using Promises to handle some asynchronous operation.
// Suppose that getDataFromDb is returning promises ;
Meh. Let's write that again in Setlist.
{ // Get the data from Db (promise function) let data = ; // Get people with callback function // Setlist only accepts Promises, so we should promisify it with // List.async() function let people = Listdata; // Lets decide if 'good' in people // Yeay it's good return 'yeay'; // You should cleaned up first else ; // Now it is okay to return return 'yeay after clean'; }
RULE OF THUMB
There is always ayield
keyword before calling asynchronous function and generator function.
Do not useyield
when working with synchronous function.
Then, run the yeayFunction()
with the run()
function.
;
Done. No more indentation hell, and of course, no callback hells.
Setlist Chain
You can chain multiple generator function execution with run(...).next()
.
// Chain multiple execution with .next() next next;
Or, if you prefer creating new generator function, you can also call them with yield keyword. The yield keyword also pass the return value of child generator function to the parent.
// Or collect them in new generator function { let status = ; ; ;}// Execute the parent generator function;
Wrapping Callback Functions with Promise
Setlist does not work with callback functions. So, in order to use your
callback functions from the past, you can wrap them with run.promisify()
.
For example, the setlist
promisify will wrap the file system fs.readFile()
function so it can be chained in our generator function.
// Import fs libraryconst fs = ; // Create generator function { // Get file content let content = runfilename; // Do something with it return ;} // Or do with promise stylerunfilename ;
Wrapping Class or Object with Promise
If you are planning to write down classes or objects with generator function,
you can transform them into Promise on runtime by calling run.proxify()
and pass in your class or object after the class definition.
For class object,it will also automatically transform the prototype object.
Note that you should convert extended class with the proxify
if you define
new generator function in the extended class.
* { ... } static * { ... } // Convert base classrun; * { ... } // Convert extended classrun; // No need to convert because there is no generator functions { ... } // But this calls will return promise because we already// transform the base classanotherClass;
Create Callback Handler using Generator Function
Some function that require callback handler, such as REPL eval function, are more reliably written with generator function, at least in my opinion.
To wrap the generator function so it can be used with the callback handler
you can use run.callbackify()
function.
// Import REPL libraryconst repl = ; // Create repl eval callback handler { // Get result from evaluated code let result; try let result = ; catcherror // Get recoverable status (See REPL documentation from Node.js) if return REPL; else // You can just throw error here and the callbackify will properly // pass the error to the callback throw error; // Return result to the callback if the eval suceeds return result;} // Start repl sessionreplstart eval: run ;
Testing
You can test the package by
npm test
It may not the best testing in the world as this is my first project that using a real proper test.
Bugs
If you encounter any issues related to the Setlist library, please report them at https://github.com/withmandala/setlist/issues
License
Copyright (c) 2016 Fadhli Dzil Ikram. SetlistJS is MIT licensed.