Lazy Promises in Node.js

Why?

Let us consider a database connection.

const connection = new Promise(someHeavyConnectionStuff);
// ......
(await connection).query("SELECT ...");

Ideally, we don’t want to connect to the database until it's necessary. However, in the snippet above we will, because promise will start executing as soon as it is declared. This way, we will initiate the DB connection long before the actual call is made.

While it makes perfect sense in terms of Promises, that’s not something we are going for, so it would be great to be able to use lazy promises when we need them.

How?

In the ECMAScript, there is a concept of a “thenable“. It is an interface with a .then() method, which accepts a callback as an argument. Because of a diverse Node.js ecosystem, there is more than one Promise or promise-like class, so ECMAScript treats them all as equal. Despite their internal workings, as soon as they are complete (e.g. api call or db query return results) - .then() callback is called. await keyword is just a syntax sugar that covers this .then() call. So, these two ways to handle promise are virtually the same:

async const processAsyncCall = (filters) => {

  myAsyncCall().then(result => console.log(result));
  
  const result = await myAsyncCall();
  
}

This drives us to a conclusion: we can implement a “thenable“ by ourselves, and it will work both with .then() and await as long as we implement .then() function.

How is this different from a regular Node.js Promise? Let us see this usage example. P-lazy has been utilized for lazy promises in this example since this is a production-ready library:

const timeConsumingCode = resolve => {
    // some time-consuming code
  }

async const processAsyncCall = (filters) => {
  // myRegularPromise runs code as soon as new Promise constructor is called
  const regularPromise = new Promise(timeConsumingCode);
  
  // here we ensure the result is completed. We can also use .then()
  const regularPromiseResult = await regularPromise;
  
  // timeConsumingCode has not been called so far
  const lazyPromise = new PLazy(timeConsumingCode);
  
  // timeConsumingCode is run when awaited
  const lazyPromiseResult = await lazyPromise;
  
}

This way, we can call async code only if it is awaited.

As already mentioned, you can use p-lazy to get up and running with lazy promises. But if you want to know how it works, let us have a look at the implementation:

export default class PLazy extends Promise {
    #executor;
    #promise;

    constructor(executor) {
        super(resolve => {
            resolve();
        });

        this.#executor = executor;
    }

    // ...
    // some methods to support all Promise interfaces
    // ...

    then(onFulfilled, onRejected) {
        // TODO: Use `??=` when targeting Node.js 16.
        this.#promise = this.#promise || new Promise(this.#executor);
        return this.#promise.then(onFulfilled, onRejected);
    }
}

As you can see, the constructor does not really do anything. It only stores the executor, which is a function to be called when awaited. At this point, a regular promise would already start executing it, but we don’t need to unless the promise is awaited. And to actually resolve the lazy promise, .then() method is described. Under the hood, it creates a promise and resolves it.

So, long story short, a lazy promise in Node.js is a class that perfectly mimics the Promise interface (or at least Thenable), and creates the actual promise only when awaited.

And, coming back to our initial example, the lazy Promise for DB connection would look like this:

const connection = new PLazy.from(someHeavyConnectionStuff);

// ......
(await connection).query("SELECT ...");

I hope this article helped you to learn something new about promises and how to cook them. Happy coding!