From Callbacks to Promises

You wrap the call in a promise executor and resolve or reject inside the callback. The executor function receives the two functions that control the promise, so the callback API's result becomes the promise's result.

// Wrap a callback-style function in a promise.
function delay(ms, value) {
  return new Promise((resolve) => {
    setTimeout(() => resolve(value), ms);
  });
}

delay(50, "done").then((value) => console.log(value));

// The same thing written with the callback API.
function delayCallback(ms, value, callback) {
  setTimeout(() => callback(null, value), ms);
}

delayCallback(50, "done too", (err, value) => {
  if (err) {
    console.log("failed:", err.message);
    return;
  }
  console.log(value);
});

Notice the shape of the error-first callback. The error is the first argument and the value is the second, and a null error means the operation succeeded. The promise wrapper inverts that: you call resolve with the value on success and reject with an error on failure. That inversion is what makes promises read better, because a successful path has to be stated explicitly rather than being implied by an absent error.

There is a generic version of this that is worth writing once and reusing. The promisify helper takes a function that follows the error-first convention and returns a function that returns a promise. It works for any number of arguments because the extra arguments are spread before the callback.

Two cautions. The callback must be called exactly once, because a promise settles only the first time. And if the underlying API can throw synchronously, wrap the call in a try and catch inside the executor and reject from there, otherwise the promise will hang rather than rejecting.

Because a promise is a value you can pass around and compose, while a callback is a function you have to nest. Three specific problems go away when you switch.

First, nesting. With callbacks, each step that depends on the previous one has to be written inside the previous one's callback, so a sequence of five steps becomes five levels of indentation and the shape of the code no longer matches the shape of the process. With promises, the steps sit next to each other in a chain, and the indentation stays flat.

Second, error handling. In the callback style, the error check has to be repeated in every callback, and forgetting one means the failure is swallowed silently. With promises, one catch handler at the end of the chain handles every failure in it, and because the chain short-circuits on a rejection, the steps after the failure never run.

Third, combining. There is no way to say wait for two of these at once with plain callbacks without building the coordination yourself. The promise combinators do it in one line, and they give you the all-or-nothing behaviour, the first-wins behaviour or the report-everything behaviour depending on which one you pick.

There is a fair caveat to add. Promises are not always the better choice. For a single asynchronous step with no follow-up, a callback is simpler and there is nothing to compose. And the promise version introduces a scheduling rule of its own, because handlers run in a microtask rather than immediately, which changes the order of some output.