Promisification & promise-based APIs

Why turn callbacks into promises?

Many older JavaScript functions were written before promises were common. They don't return their result. Instead, you give them a callback: a function they call later, with the result.

A promise is an object that stands for a result that isn't ready yet. Later, the promise is either fulfilled with a value, or rejected with an error.

Promisification means writing a new function around an old callback function. The new function is called a wrapper. It returns a promise, so you don't pass it a callback.

You met callbacks in the Callbacks lesson and promises in the Promises lesson. This lesson joins the two. The old function still does the same work. Only the way you get the result changes.

function getName(callback) {
  callback(null, "Asha");
}

function getNameAsync() {
  return new Promise((resolve, reject) => {
    getName((err, name) => err ? reject(err) : resolve(name));
  });
}

getNameAsync().then(name => console.log(name));

In plain words, line by line:

1. Lines 1 to 3: getName is the old function. It calls its callback with two values: null (meaning "no error") and "Asha".
2. Lines 5 to 9: getNameAsync is the wrapper. Line 6 makes a new promise and returns it. While making it, JavaScript hands you two functions: resolve fulfills the promise with a value, and reject rejects it with an error.
3. Line 7 calls getName and passes it a callback. The ? : picks one of two actions: if err holds an error, call reject(err); if not, call resolve(name).
4. Line 11 calls the wrapper and gets a promise. .then runs when the promise is fulfilled, so it prints Asha.

Many functions in Node.js (JavaScript that runs outside the browser) follow one rule for callbacks. It's called error-first. The callback gets two arguments, (err, result):

• If the work failed, err is an Error object.
• If the work worked, err is null and result holds the value.

Here is a wrapper for one error-first function, readConfig. It reads a settings object, called a config, by its name.

1function readConfigPromise(name) {2  return new Promise((resolve, reject) => {3    readConfig(name, (err, config) => {4      if (err) {5        reject(err);6        return;7      }8      resolve(config);9    });10  });11}

1. Line 2 makes a new promise and returns it.
2. Line 3 calls the old readConfig function. It adds a callback as the last argument.
3. Line 5 runs if err holds an error. It rejects the promise, and line 6 stops the callback there.
4. Line 8 runs if there was no error. It fulfills the promise with config.

A promisify helper does the same job for any error-first function, not just one. You give it the old function. It gives you back a new function that does four things:

1. It takes the same arguments as the old function.
2. It makes a new promise.
3. It calls the old function with those arguments, plus one callback at the end.
4. When that callback runs, it rejects or resolves the promise.

In the code below, ...args on line 13 collects all the arguments into one list. Line 15 calls the old function, fn, with those arguments, and adds the callback last.

1function readConfig(name, callback) {2  setTimeout(() => {3    if (name === "missing") {4      callback(new Error("No config named " + name));5      return;6    }7 8    callback(null, { name, theme: "dark" });9  }, 10);10}11 12function promisify(fn) {13  return function (...args) {14    return new Promise((resolve, reject) => {15      fn(...args, (err, value) => {16        if (err) reject(err);17        else resolve(value);18      });19    });20  };21}22 23const readConfigPromise = promisify(readConfig);Run24readConfigPromise("app")25  .then(config => console.log(config.theme))26  .catch(error => console.log(error.message));

A promisify helper that works for many functions is called generic. A generic helper expects two things from the old function:

• The callback is the last argument.
• The callback is error-first: it gets (err, value).

Many Node.js functions follow both rules. Some functions in browsers, libraries, and old code don't. In the playground below, pick a kind of old function and see if the generic wrapper fits.

1const fsLike = {2  prefix: "user:",3  readFile(name, cb) {4    cb(null, this.prefix + name.toUpperCase());5  }6};7 8function genericPromisify(fn) {9  return (...args) => new Promise((resolve, reject) => {10    fn(...args, (err, value) => err ? reject(err) : resolve(value));11  });12}

function readSize(callback) {
  callback(null, 640, 480);
}

function readSizeAsync() {
  return new Promise((resolve, reject) => {
    readSize((err, width, height) => {
      if (err) reject(err);
      else resolve({ width, height });
    });
  });
}

readSizeAsync().then(size => console.log(size.width, size.height));

On line 2, readSize calls back with two values: a width, 640, and a height, 480. A promise holds only one value, so a generic wrapper would keep just the width. This custom wrapper puts both into one object on line 9, { width, height }, and fulfills the promise with it. So line 14 prints 640 480.

const reader = {
  prefix: "file:",
  read(name, callback) {
    callback(null, this.prefix + name);
  }
};

function promisifyOne(fn) {
  return (...args) => new Promise((resolve, reject) => {
    fn(...args, (err, value) => err ? reject(err) : resolve(value));
  });
}

const readAsync = promisifyOne(reader.read.bind(reader));
readAsync("notes.txt").then(console.log);

reader.read is a method: a function stored on the reader object. On line 4 it uses this.prefix, and this must be reader for that to work.

But promisifyOne(reader.read) would pass only the function, without reader. Then this would not be reader. On line 14, .bind(reader) makes a copy of the function where this is always reader. So line 15 prints file:notes.txt.

function watchOnce(callback) {
  callback(null, "first");
  callback(null, "second");
}

const promise = new Promise((resolve, reject) => {
  watchOnce((err, value) => err ? reject(err) : resolve(value));
});

promise.then(value => console.log(value));

watchOnce calls its callback twice: first with "first", then with "second". A promise can settle (become fulfilled or rejected) only once. The first resolve wins, and the second call is ignored. So line 10 prints only first.

Some things happen many times, like clicks, progress updates, or pieces of a download. Don't turn those into one promise. Keep the event listener, or use an async iterator: a loop that waits for each new value. You'll meet async iterators in a later lesson.

The table sums up this section. Each row is one kind of old function. Read across to see what a generic wrapper does with it, and what to use instead.

Node.js has a promisify helper built in: util.promisify, from the node:util module. It has been there since Node 8. It follows the same two rules: the callback comes last, and it is error-first. It gives back a new function that returns a promise.

Many Node modules now come with promise versions built in, too. For example, node:fs/promises reads files and node:timers/promises waits. When a promise version exists, use it. Then you don't need a wrapper at all.

1import { promisify } from "node:util";2import { readFile } from "node:fs";3import { readFile as readFilePromise } from "node:fs/promises";4import { setTimeout as sleep } from "node:timers/promises";5 6const readFileAsync = promisify(readFile);7const text = await readFileAsync("package.json", "utf8");8const sameText = await readFilePromise("package.json", "utf8");9await sleep(100);

1. Line 1 imports promisify. Line 2 imports the old callback version of readFile.
2. Line 6 wraps the old readFile. Line 7 calls the wrapper and waits for the file's text.
3. Line 3 imports the promise version of readFile. Line 8 uses it with no wrapper.
4. Line 4 imports a promise version of setTimeout, named sleep. Line 9 waits 100 milliseconds.

This example runs in Node, not in the editor on this page. It imports node: modules and reads a file from your computer, which a web page can't do.

Some callbacks get more than one result. A function like that can bring its own promise version. It stores it under a special key, util.promisify.custom. That key is a symbol: a unique value that can be used as a property name. When util.promisify finds a function under that key, it gives back that function instead of making its own wrapper.

1import { promisify } from "node:util";2 3function size(path, callback) {4  callback(null, 640, 480);5}6 7size[promisify.custom] = path =>8  Promise.resolve({ path, width: 640, height: 480 });9 10const sizeAsync = promisify(size);11console.log(await sizeAsync("hero.png"));

1. Line 4: size calls back with two results, 640 and 480.
2. Lines 7 and 8 store a promise version under promisify.custom. It fulfills with one object that holds both results.
3. Line 10: promisify(size) finds that stored function and gives it back.
4. Line 11 prints { path: 'hero.png', width: 640, height: 480 }.

Browser functions don't follow Node's error-first rule. You can still wrap them with new Promise. But each wrapper has to match the function it wraps:

• setTimeout calls one function when the time is up. It never fails.
• An image has two events: img.onload runs when it loads, and img.onerror runs when it fails.
• navigator.geolocation.getCurrentPosition finds where the device is. It takes a success callback and an error callback. It also asks the user for permission first.

1const sleep = ms => new Promise(resolve => {2  setTimeout(resolve, ms);3});4 5function loadImage(src) {6  return new Promise((resolve, reject) => {7    const img = new Image();8    img.onload = () => resolve(img);9    img.onerror = () => reject(new Error("Image failed to load"));10    img.src = src;11  });12}13 14function getPosition(options) {15  return new Promise((resolve, reject) => {16    if (!navigator.geolocation) {17      reject(new Error("Geolocation is not available"));18      return;19    }20    navigator.geolocation.getCurrentPosition(resolve, reject, options);21  });22}

function delay(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

delay(1).then(() => console.log("tea is ready"));

Line 2 makes a promise and starts a timer. When the timer fires, it calls resolve, which fulfills the promise with undefined. Line 5 waits 1 millisecond, then prints tea is ready.

Location needs extra care:

• It works only on a secure page: one served over HTTPS, or from localhost on your own computer.
• The user must give permission.
• When it fails, the error has a number in error.code: 1 is PERMISSION_DENIED (the user said no), 2 is POSITION_UNAVAILABLE (the device couldn't find its place), and 3 is TIMEOUT (it took too long).

Never ask for the location as soon as the page loads. Ask only after the user clicks a button that clearly needs it.

Once you can wrap other people's functions, you'll start writing your own functions that return promises. A few rules make them easy to use.

Here is a function that follows the rules. It loads a user's profile from a server.

1async function getUserProfile(id, { signal } = {}) {2  if (typeof id !== "string") {3    throw new TypeError("id must be a string");4  }5 6  const response = await fetch(`/api/users/${id}`, { signal });7  if (!response.ok) {8    throw new Error(`Profile request failed: ${response.status}`);9  }10 11  return response.json();12}

1. Line 1: async makes the function always return a promise. It also takes an optional signal. A signal (an AbortSignal) lets the caller cancel the request later.
2. Line 3: if id isn't a string, it throws a TypeError. Inside an async function, a throw doesn't escape right away. It rejects the returned promise.
3. Line 6: fetch asks the server for the profile. It passes the signal along.
4. Line 8: response.ok is false when the server answers with an error, like 404 "not found". Then it throws an Error, which also rejects the promise.
5. Line 11: on success, the promise is fulfilled with the profile data, read from the response as JSON.

So callers handle every problem in one place: a .catch, or a try/catch around await. Write down what the promise is fulfilled with. And don't let one function sometimes take a callback and sometimes return a promise.

Where you'll use this

You'll use promisification when you update older code a little at a time. For example:

• A library only has callback functions, but the rest of your app uses promises and await. Wrap the library's functions once, and use the wrappers everywhere.
• A browser feature uses events or callbacks. Wrap it, so it handles errors the same way as the rest of your promise code.

Common misconceptions

Some callback functions call back right away in one case and later in another. Programmers nicknamed this "releasing Zalgo", after a monster from internet jokes. Code that runs after the call can't know if the callback has run yet.

1// Avoid: sometimes callback now, sometimes later.2function getCached(key, callback) {3  if (cache.has(key)) callback(null, cache.get(key));4  else setTimeout(() => callback(null, load(key)), 0);5}6 7// Prefer: one promise-shaped result every time.8async function getCached(key) {9  if (cache.has(key)) return cache.get(key);10  return load(key);11}

1. Line 3: when the value is already saved in cache, the first version calls back right away.
2. Line 4: when it isn't saved, it calls back later, after a timer.
3. Line 8: the second version is an async function, so it always returns a promise. Your .then code always runs later, saved or not.

Here are some common wrong ideas about promisification, and what is true instead:

• "Promisify makes the work faster." No. It changes how you get the result. The timer, the file, the network, and the permission prompt take just as long.
• "Every callback should become a promise." No. Things that happen many times, like clicks, downloads in pieces, and progress updates, don't fit one promise.
• "A promise can be resolved many times." No. A promise settles once. Later resolve or reject calls are ignored.
• "A generic wrapper fits every callback." No. It expects the callback last and error-first. Other shapes need a custom wrapper.
• "Rejecting with a string is fine." Use an Error object. Then the catch gets a message, a name, and a record of where it happened.

The table compares the two styles. Each row asks one question. Read across to see how callbacks answer it, and how promises do.

Key takeaways

• Promisification wraps an old callback function so it returns a promise. The old function still does the same work.
• A generic wrapper expects the callback last and error-first: (err, value).
• util.promisify keeps only the first result after err, unless the function brings its own version under util.promisify.custom.
• A promise settles once. For things that happen many times, use events or async iterators.
• Good promise functions always return a promise, reject with an Error object, and say what the promise is fulfilled with.

Promisification turns "I'll call your callback later" into "here is a promise for the result".

Up next: async & await.