How do you create custom asynchronous functions in node.js?

Question

I was unsure how node.js was able to realize what functions where async and which were not and how to create a custom async function.

Say I wanted to create a custom asynchronous function. I would be surprised if just because I called my last argument to the async function callback or cb that it would just know its an async function:

function f(arg1, callback){
  //do stuff with arg1
  arg1.doStuff()
  //call callback
  callback(null, arg1.result());
}

I tried something like that and it did not work async. How do you tell node.js that f is actually async?

Answer 1

NOTE: this answer was written in 2014, before the existence of async function, and before Promises gaining popularity. While the same principles apply as well, I would recommend reading on Promises before trying to get your head around how they relate to "traditional" callback-driven async functions.

---

To create a function that calls its callback asynchronously, you have to use some platform-provided async primitive (typically IO-related) on it - timers, reading from the filesystem, making a request etc.

For example, this function takes a callback argument, and calls it 100ms after:

function asyncFn(callback) {
  setTimeout(() => {
    callback();
  }, 100);
}

A possible reason for making a function async when it doesn't need to be, is for API consistency. For example, suppose you have a function that makes a network request, and caches the result for later calls:

var cache = null;
function makeRequest(callback) {
  if (!cache) {
    makeAjax(result => {
      cache = result;
      callback(result);
    });
  } else {
    callback(cache);
  }
}

The problem is, this function is inconsistent: sometimes it is asynchronous, sometimes it isn't. Suppose you have a consumer like this:

makeRequest(result => doSomethingWithResult(result));
doSomethingElse();

The doSomethingElse function may run before or after the doSomethingWithResult function, depending on whether the result was cached or not. Now, if you use an async primitive on the makeRequest function, such as process.nextTick:

var cache = null;
function makeRequest(callback) {
  if(!cache) {
    makeAjax(result => {
      cache = result;
      callback(result);
    });
  } else {
    process.nextTick(() => callback(cache));
  }
}

The call is always async, and doSomethingElse always runs before doSomethingWithResult.

Answer 2

Only native functions (with access to the event loop) are asynchronous. You would need to call one of them to get asynchronity for your callback. See What is a simple example of an asynchronous javascript function?.

If you aren't using any, there's hardly a reason to make your function asynchronous.