deasync

What is deasync?

The deasync npm package allows you to convert asynchronous functions into synchronous ones. This can be useful in scenarios where you need to perform asynchronous operations in a synchronous manner, such as during initialization or configuration phases.

What are deasync's main functionalities?

Convert Asynchronous Function to Synchronous

This feature allows you to convert an asynchronous function into a synchronous one. The code demonstrates how to use deasync to wait for an asynchronous function to complete before proceeding.

const deasync = require('deasync');
let done = false;
let result;
asyncFunction((err, res) => {
  if (err) throw err;
  result = res;
  done = true;
});
while (!done) {
  deasync.sleep(100);
}
console.log(result);

Sleep Function

The sleep function pauses the execution of code for a specified number of milliseconds. This can be useful for delaying operations or simulating long-running tasks.

const deasync = require('deasync');
console.log('Start');
deasync.sleep(2000);
console.log('End');

Synchronous Read File

This feature demonstrates how to read a file synchronously using deasync. The code waits for the asynchronous readFile operation to complete before proceeding.

const fs = require('fs');
const deasync = require('deasync');
let content;
fs.readFile('example.txt', 'utf8', (err, data) => {
  if (err) throw err;
  content = data;
  done = true;
});
while (!done) {
  deasync.sleep(100);
}
console.log(content);

Other packages similar to deasync

sync-request

The sync-request package allows you to make synchronous HTTP requests. Unlike deasync, which can convert any asynchronous function to synchronous, sync-request is specifically designed for HTTP requests.

wait-for-stuff

The wait-for-stuff package provides synchronous versions of common asynchronous operations like reading files and making HTTP requests. It offers a more limited scope compared to deasync, which can handle any asynchronous function.

fibers

The fibers package allows you to write asynchronous code in a synchronous style using fibers. It is more complex and powerful than deasync, offering more control over the execution flow but requiring a deeper understanding of fibers.

README

deasync

deasync turns async function into sync, implemented with a blocking mechanism by calling Node.js event loop at JavaScript layer. The core of deasync is writen in C++.

Motivation

Suppose you maintain a library that exposes a function getData. Your users call it to get actual data:
var output = getData();
Under the hood data is saved in a file so you implemented getData using Node.js built-in fs.readFileSync. It's obvious both getData and fs.readFileSync are sync functions. One day you were told to switch the underlying data source to a repo such as MongoDB which can only be accessed asynchronously. You were also told to avoid pissing off your users, getData API cannot be changed to return merely a promise or demand a callback parameter. How do you meet both requirements?

You may tempted to use node-fibers or a module derived from it, but node fibers can only wrap async function call into a sync function inside a fiber. In the case above you cannot assume all callers are inside fibers. On the other hand, if you start a fiber in getData then getData itself will still return immediately without waiting for the async call result. For similar reason ES6 generators introduced in Node v11 won't work either.

What really needed is a way to block subsequent JavaScript from running without blocking entire thread by yielding to allow other events in the event loop to be handled. Ideally the blockage is removed as soon as the result of async function is available. A less ideal but often acceptable alternative is a sleep function which you can use to implement the blockage like while(!done) sleep(100);. It is less ideal because sleep duration has to be guessed. It is important the sleep function not only shouldn't block entire thread, but also shouldn't incur busy wait that pegs the CPU to 100%.

deasync supports both alternatives.

Usages

• Generic wrapper of async function with standard API signature function(p1,...pn,function cb(err,res){})

var deasync = require('deasync');
var cp = require('child_process');
var exec = deasync(cp.exec);
// output result of ls -la
try{
  console.log(exec('ls -la'));
}
catch(err){
  console.log(err);
}
// done is printed last, as supposed, with cp.exec wrapped in deasync; first without.
console.log('done');

• For async function with non-standard API, for instance function asyncFunction(p1,function cb(res){}), use runLoopOnce

var done = false;
var data;
asyncFunction(p1,function cb(res){
  data = res;
  done = true;
});
while(!done) {
  require('deasync').runLoopOnce();
}
// data is now populated

• Sleep (a wrapper of setTimeout)

function SyncFunction(){
  var ret;
  setTimeout(function(){
      ret = "hello";
  },3000);
  while(ret === undefined) {
    require('deasync').sleep(100);
  }
  // returns hello with sleep; undefined without
  return ret;    
}

Installation

Prerequisites: Except on a few platform and Node version combinations where binary distribution is included, deasync uses node-gyp to compile C++ source code so you may need the compilers listed in node-gyp. You may also need to update npm's bundled node gyp.

To install, run npm install deasync