{ "componentChunkName": "component---src-templates-post-js", "path": "/understanding-promise-objects/", "result": {"data":{"markdownRemark":{"html":"

Note: This post assumes familiarity with JavaScript in general. You might want to refresh your memory on objects in particular.

\n

Table of contents:

\n\n

\n

How to create a promise?

\n

We can create a promise with the Promise constructor:

\n
// example 1\n\nfunction foo() {} // We can rename \"foo\"  however we like.\n\nconst myPromise = new Promise(foo) // Creates a promise.
\n

The constructor expects one argument in the form of a function to initialize a promise. The specification gave this function the name \"executor\".

\n

In example 1, we have passed an executor that does nothing (the function's body is empty), still, the constructor successfully creates a promise.

\n

If nothing, or anything other than a function is passed, we get a type error:

\n
// example 2\n\nconst myPromise = new Promise() // Type error since nothing is passed.
\n

However, to create a useful promise, we probably want to pass an executor to the constructor that does something useful. We will do just that at the end of this post, but first, let's develop a better sense for what a promise actually is.

\n

\n

What is actually a promise?

\n

According to the ECMAScript Language Specification:

\n
\n

A Promise is an object that is used as a placeholder for the eventual results of a deferred (and possibly asynchronous) computation.

\n
\n

Do not let the language specification's use of \"Promise\", with a capital letter \"P\", confuse you. It does not refer to the Promise constructor (constructors are usually capitalized), it refers to an instance (which we normally do not capitalize). Think of \"Promise\" in the quote from the specification as \"myPromise\" in example 1.

\n

So a promise is an object.

\n

More specifically, it is an instance of the Promise constructor or Promise type, if you will.

\n

It has properties and methods like any other object.

\n

If we console.log a promise, we can take a look at the anatomy of the object:

\n
// example 3\n\nconst myPromise = new Promise(() => {})\n\nconsole.log(myPromise)
\n

We see 3 properties live directly on each instance of a Promise. In chrome, they are called Prototype (we will get to this later), PromiseState and PromiseResult.

\n

We can think of the PromiseState and PromiseResult properties as the actual \"placeholders\" the specification is referring to in a more abstract manner. Both properties are internal, i.e. inaccessible or not meant to be accessed by us directly.

\n

Their initial values are \"pending\" and \"undefined\", respectively.

\n

Now take a look at this example:

\n
// example 4\n\nfunction executor() {\n  /**\n   * We may do some \"computation\".\n   *\n   * ...\n   *\n   * Once we are finished,\n   * we may mutate the properties of the promise object\n   * to reflect the result of the computation.\n   **/\n}\n\nconst myPromise = new Promise(executor)
\n

The \"computation\" the language specification refers to is the code we write in our executor (see example 4).

\n

And basically, the purpose of each promise object is to:

\n
    \n
  1. Allow us to reflect the result of our computation in its properties (PromiseState and PromiseResult).
    2. \n
  2. Provide methods to schedule function calls (\"callbacks\") for the time after a change in its state.
    3. \n
\n

We will discuss the second point and how to use the methods (Promise.prototype.then, Promise.prototype.catch, Promise.prototype.finally) very soon, but only after looking at some examples of how the properties (state and result) of a promise can be mutated.

\n

\n

Changing the state and result of promises

\n

The executor is actually a higher order function. It takes two functions as arguments. To mutate the properties of a promise, we just have to call either the first or the second.

\n

Let's see the examples!

\n

Without having called anything, state and result are populated with their initial values:

\n
// example 5\n\nfunction executor(fufill, reject) {\n  /**\n   * We are still computing...\n   *\n   * Our program has yet to reach our call to fulfill or reject.\n   **/\n}\n\nconst myPromise = new Promise(executor)\n\nconsole.log(myPromise)\n\n// state: \"pending\", result: undefined\n\n// These are the initial values.
\n

Call the first function (without an argument):

\n
// example 6\n\nfunction executor(fulfill) {\n  // Finished computing.\n\n  fulfill() // Our program finally reached this call\n}\n\nconst myPromise = new Promise(executor)\n\nconsole.log(myPromise)\n// state: \"fulfilled\", result: undefined
\n

Call it with a number:

\n
// example 7\n\nfunction executor(fulfill) {\n  // Finished computing.\n\n  fulfill(9) // Our program finally reached this call\n}\n\nconst myPromise = new Promise(executor)\n\nconsole.log(myPromise)\n// state: \"fulfilled\", result: 9
\n

The result could be an object:

\n
// example 8\n\nfunction executor(fulfill) {\n  // Finished computing.\n\n  // We could pass an object:\n  fulfill({word: 'discombobulate', frequency: 'rare'})\n}\n\nconst myPromise = new Promise(executor)\n\nconsole.log(myPromise)\n// state: \"fulfilled\", result: {word: 'discombobulate', frequency: 'rare'}
\n

Call our reject function without an argument:

\n
// example 9\n\nfunction executor(fulfill, reject) {\n  // Finished computing, but something went wrong.\n\n  reject()\n}\n\nconst myPromise = new Promise(executor)\n\nconsole.log(myPromise)\n// state: \"rejected\", result: undefined
\n

Call our reject function with a number:

\n
// example 10\n\nfunction executor(fulfill, reject) {\n  // Finished computing, but something went wrong.\n\n  // We could pass a number (if we wanted):\n  reject(11)\n}\n\nconst myPromise = new Promise(executor)\n\nconsole.log(myPromise)\n// state: \"rejected\", result: 11
\n

Usually we call our reject function with an Error object:

\n
// example 11\n\nfunction executor(fulfill, reject) {\n  // Finished computing, but something went wrong.\n\n  // Usually an Error object is passed:\n  reject(new Error('My error message.'))\n}\n\nconst myPromise = new Promise(executor)\n\nconsole.log(myPromise)\n// state: \"rejected\", result: error object
\n

Note: we may replace \"fulfill\" and \"reject\" with any name we want.

\n

\n

How to use promises

\n

If you recall from earlier, all instances of Promise also have a Prototype property. This is where the methods shared by all instances live. We are interested in Promise.prototype.then, Promise.prototype.catch and Promise.prototype.finally.

\n

Take a look at this example:

\n
// example 12\n\nfunction executor(fulfill, reject) {\n  setTimeout(() => {\n    const computation = 'apple' === 'apple'\n\n    if (computation) {\n      fulfill('Successful')\n    } else {\n      reject('Failed')\n    }\n  }, 3000)\n}\n\nconst myPromise = new Promise(executor)\n\nsetTimeout(() => {\n  console.log('Our promise after 1s: ', myPromise)\n  // state: \"pending\", result: undefined\n}, 1000)\n\nsetTimeout(() => {\n  console.log('Our promise after 5s: ', myPromise)\n  // state: \"fulfilled\", result: \"Successful\"\n}, 5000)
\n

Here we use setTimeout to pretend doing some computation for 3 seconds, and then, the function passed to setTimeout is run. For this example, the result is always true, which always satisfies our condition, therefore we always call fulfill with the string \"Successful\".

\n

What is interesting about the above, is how we log myPromise twice (after 1 second and after 5 seconds).

\n

Look at the state and the result: they change (as we might expect, since after 3 seconds, we call fulfill with a string, to change the state and the result).

\n

However, it would be tedious and inefficient to make guesses how long the computation will take. Wouldn't it be convenient, if we could just tell what to do if it's finished? Also, how do we use something like the result of the computation?

\n

Luckily, promise objects have methods to come to our rescue!

\n

Let's see how they work.

\n
// example 13\n\nfunction executor(fulfill, reject) {\n  setTimeout(() => {\n    const computation = 'apple' === 'apple'\n\n    if (computation) { // Satisfies the condition\n      fulfill('Successful') // Do this.\n    } else {\n      reject('Failed')\n    }\n  }, 3000)\n}\n\nconst myPromise = new Promise(executor)\n\nmyPromise.then(\n  (result) => console.log(result),\n  (error) => console.log(error)\n)
\n

And with a slight modification, to always call the second argument of the executor:

\n
// example 14\n\nfunction executor(fulfill, reject) {\n  setTimeout(() => {\n    const computation = 'apple' === 'orange'\n\n    if (computation) { // Fails to satisfy the condition.\n      fulfill('Successful')\n    } else {\n      reject('Failed') // Do this.\n    }\n  }, 3000)\n}\n\nconst myPromise = new Promise(executor)\n\nmyPromise.then(\n  (result) => console.log(result),\n  (error) => console.log(error)\n)
\n

With the Promise.prototype.then method, we can schedule function calls (\"callbacks\") for the time after the promise's state changes.\nNot only that, it allows us to use the value of the object's result property via the optional parameter of the callback.

\n

In more detail:

\n

Promise.prototype.then can take two callback functions.

\n

Depending on which state the promise ends up in, either the first or the second callback is run.

\n\n

Now take a look at this example:

\n
// example 15\n\nfunction executor(fulfill, reject) {\n  setTimeout(() => {\n    const computation = 'apple' === 'orange'\n\n    if (computation) { // Fails to satisfy the condition.\n      fulfill('Successful')\n    } else {\n      reject('Failed') // Do this.\n    }\n  }, 3000)\n}\n\nconst myPromise = new Promise(executor)\n\nmyPromise.then(\n  (result) => console.log(result),\n).catch((error) => console.log(error))
\n

This does something similar to the previous example.

\n

Promise.prototype.catch gives us an opportunity to handle or \"catch\" any problematic promises (i.e. promises with a \"rejected\" state).

\n

In case you are wondering, here is some further reading about how catch compares to handling errors with then:

\n

In a Promise, what's the difference between using catch and the 2nd argument of then?

\n

It is important to note here, that all 3 methods (then, catch, finally) return a promise, which makes it possible to chain them. This concept is called \"method chaining\".

\n

Now take a look at this example:

\n
// example 16\n\nfunction executor(fulfill, reject) {\n  setTimeout(() => {\n    const computation = 'apple' === 'orange'\n\n    if (computation) { // Fails to satisfy the condition.\n      fulfill('Successful')\n    } else {\n      reject('Failed') // Do this.\n    }\n  }, 3000)\n}\n\nconst myPromise = new Promise(executor)\n\nmyPromise.then(\n  (result) => console.log(result)\n).catch(\n  (error) => console.log(error)\n).finally(\n  () => console.log('Clean things up.')\n)
\n

Promise.prototype.finally allows us to schedule a callback that always runs if the promise is settled, meaning, if its state becomes \"fulfilled\" or \"rejected\".

\n

\n

A more realistic example

\n

As MDN points out:

\n
\n

The Promise constructor is primarily used to wrap functions that do not already support promises.

\n
\n

MDN documentation of the Promise() constructor

\n

The article also gives this example:

\n
// example 17\n\nfunction myAsyncFunction(url) {\n  return new Promise((resolve, reject) => {\n    const xhr = new XMLHttpRequest()\n    xhr.open('GET', url)\n    xhr.onload = () => resolve(xhr.responseText)\n    xhr.onerror = () => reject(xhr.statusText)\n    xhr.send()\n  });\n}
\n

And this is how we might use this function (with Promise.prototype.then):

\n
// example 18\n\nfunction myAsyncFunction(url) {\n  return new Promise((resolve, reject) => {\n    const xhr = new XMLHttpRequest()\n    xhr.open('GET', url)\n    xhr.onload = () => resolve(xhr.responseText)\n    xhr.onerror = () => reject(xhr.statusText)\n    xhr.send()\n  });\n}\n\nconst myPromise = myAsyncFunction('https://catfact.ninja/fact')\n\nmyPromise.then(\n  (result) => console.log(result),\n  (error) => console.log(error)\n)
\n

Based on what we have learned so far, what does this code do? We don't have to understand each bit, but in essence:

\n
    \n
  1. myAsyncFunction is a function that uses a Promise constructor to create an instance of a promise.\n
      \n
    1. The constructor takes an executor function (with parameters called \"resolve\" and \"reject\" in this case).
      2. \n
    2. In the executor's body, we do our \"computation\":\n
        \n
      1. We create an XHR object and prepare a GET request.
        2. \n
      2. We get ready to call resolve with the response text, in case the request is successful.
        3. \n
      3. We get ready to call reject with the status text, in case the request encounters an error.
        4. \n
      4. We dispatch the request to the server.
        5. \n
      \n
      3. \n
    \n
    2. \n
  2. We call myAsyncFunction to create a promise (\"myPromise\").
    3. \n
  3. We call the promise's then method, to schedule our callbacks.
    4. \n
\n

\n

A few words about promise asynchronicity

\n

Much of this section is based on a presentation by Philip Roberts.

\n

One thing that might be confusing is what setTimeout has to do with asynchronicity.

\n

setTimeout sets a timer and schedules a function call (callback) for the time after the timer has expired. However we do not have to wait for the timer to expire, we can continue running other code.

\n

How can the JS runtime keep track of a countdown and also continue running other code?

\n

It can't, it only has a single thread, it can do one thing at a time.

\n

However, browsers can also access Web APIs, which you can think of as other threads, which is how concurrent computations are possible.

\n

To my best understanding, asynchronicity in JavaScript means some computation (like the countdown) is handed over to a Web API and is then able to run concurrently, and that we can schedule callbacks for the time after the computation has finished.

\n

How callbacks are handled

\n

Even if a promise is fulfilled immediately, its callbacks have to be scheduled first:

\n
// example 19\n\nfunction executor(fulfill) {\n  fulfill('Success')\n}\n\nconst myPromise = new Promise(executor)\n\nmyPromise.then(data => console.log(data)) // The callback is scheduled but not executed\n\nconsole.log('I will run before the callback.') // We Continue running other code\n\n// I will run before the callback. \n// Success
\n

Almost as though we were using setTimout with a 0 delay, to defer running our code. In reality, promise callbacks are added to the \"microtask queue\", whereas setTimout callbacks are added to the \"task queue\".

\n

In case you want to get a picture of how tasks and microtasks are handled, I have found this presentation by Jake Archibald very interesting.

\n

Blocking executors

\n

The code of an executor could produce blocking behavior, since it is run synchronously. For this reason, if you were wondering, if we could wrap a synchronous computation in a promise, to make it asynchronous, we can not.

\n

Further discussion:\nCorrect way to write a non-blocking function in Node.js

\n

\n

How to use promises with async and await?

\n

Promise methods are not the only way we can use promises.

\n

We could similarly schedule operations for the time after a promise's state changes with async and await.

\n

Let's see an example!

\n
// example 20\n\nconst url = 'https://catfact.ninja/fact'\n\nfunction fetchCatFactOne(url) {\n  return fetch(url)\n    .then(response => response.json())\n    .then(obj => obj.fact)\n}\n\nasync function fetchCatFactTwo(url) {\n  const response = await fetch(url)\n  const obj = await response.json()\n  return obj.fact\n}\n\nfetchCatFactOne(url).then(a => console.log(a))\n\nfetchCatFactTwo(url).then(a => console.log(a))
\n

Both functions do the same thing, only the syntax is different.

\n

They fetch data from an API and return a promise that is fulfilled with a text about cats.

\n

We can observe how in the first function, the first argument to then will be the promise's fulfillment value.

\n

Whereas in our async function, we have access to the same fulfillment value by preceding a function - that returns a promise - with the await keyword.

\n

\n

Further reading

\n

We've arrived at the end of this post, I will finish with some additional reading material:

\n\n

\n

Feedback

\n

There is more to promises, but I didn't want to make this post longer.

\n

In my opinion, the terminology around promises can be a bit confusing - I hope I did not add more to it.

\n

I don't have a comments section, but to ask questions, suggest changes and what have you, you can open an issue on github, or you can send me an email.

","id":"f2d8b18b-65e5-5b02-87c1-83d49a58be55","frontmatter":{"title":"Understanding promise objects","date":"December 12, 2021"}}},"pageContext":{"id":"f2d8b18b-65e5-5b02-87c1-83d49a58be55","previousPostId":null,"nextPostId":null}}, "staticQueryHashes": []}