Many things that we do in JavaScript are asynchronous. We initiate a process, but it finishes later.

The most obvious example is `setTimeout`, but there are others, like making network requests, performing animations and so on.

Let's see a couple of examples, so that we can discover a problem, and then solve it using "promises".

[cut]

Remember resource load/error events? They are covered in the chapter <info:onload-onerror>.

Let's say we want to create a function `loadScript` that loads a script and executes our code afterwards.

It can look like this:

function loadScript(src, callback) {

let script = document.createElement('script');

script.src = src;

script.onload = () => callback(script);

document.head.append(script);

}

Now when we want to load a script and then do something, we can call:

loadScript('/my/script.js', function(script) {

alert(`Cool, the ${script.src} is loaded, let's use it`);

});

...And it works, shows `alert` after the script is loaded.

That is called "a callback API". Our function `loadScript` performs an asynchronous task and we can hook on its completion using the callback function.

What if we need to load two scripts: one more after the first one?

We can put another `loadScript` inside the callback, like this:

loadScript('/my/script.js', function(script) {

alert(`Cool, the ${script.src} is loaded, let's load one more`);

loadScript('/my/script2.js', function(script) {

alert(`Cool, the second script is loaded`);

});

});

Now after the outer `loadScript` is complete, the callback initiates the inner one.

...What if we want one more script?

loadScript('/my/script.js', function(script) {

loadScript('/my/script2.js', function(script) {

if (something) {

loadScript('/my/script3.js', function(script) {

// ...continue after all scripts are loaded

});

}

})

});

As you can see, a new asynchronous action means one more nesting level.

In this example we didn't consider errors. What if a script loading failed with an error? Our callback should be able to react on that.

Here's an improved version of `loadScript` that can handle errors:

```js run

function loadScript(src, callback) {

let script = document.createElement('script');

script.src = src;

script.onload = () => callback(null, script);

script.onerror = () => callback(new Error(`Script load error ` + src));

document.head.append(script);

}

It calls `callback(null, script)` for successful load and `callback(error)` otherwise.

Usage:

loadScript('/my/script.js', function(error, script) {

if (error) {

// handle error

} else {

// script loaded, go on

}

});

The first argument of `callback` is reserved for errors and the second argument for the successful result. That allows to use a single function to pass both success and failure.

From the first look it's a viable code. And indeed it is. For one or maybe two nested calls it looks fine.

But for multiple asynchronous actions that follow one after another...

loadScript('/my/script1.js', function(error, script) {

if (error) {

handleError(error);

} else {

// ...

loadScript('/my/script2.js', function(error, script) {

if (error) {

handleError(error);

} else {

// ...

loadScript('/my/script3.js', function(error, script) {

if (error) {

handleError(error);

} else {

*!*

// ...continue after all scripts are loaded (*)

*/!*

}

});

}

})

}

});

In the code above:

1. we load `/my/script1.js`, then if there's no error

2. we load `/my/script2.js`, then if there's no error

3. we load `/my/script3.js`, then if there's no error -- do something else `(*)`.

The nested calls become increasingly more difficult to manage, especially if we add real code instead of `...`, that may include more loops, conditional statements and other usage of loaded scripts.

That's sometimes called "callback hell" or "pyramid of doom".

See? It grows right with every asynchronous action.

Compare that with a "regular" synchronous code.

Just *if* `loadScript` were a regular synchronous function:

try {

// assume we get the result in a synchronous manner, without callbacks

let script = loadScript('/my/script.js');

// ...

let script2 = loadScript('/my/script2.js');

// ...

let script3 = loadScript('/my/script3.js');

} catch(err) {

handleError(err);

}

How much cleaner and simpler it is!

Promises allow to write asynchronous code in a similar way. They are really great at that. Let's study them in the next chapter.

There are many ways to explain promises. Here we'll follow the [specification](https://tc39.github.io/ecma262/#sec-promise-objects), because gives real understanding how things work. Besides, you'll become familiar with the terms.

First, what a promise is, and then usage patterns.

[cut]

A promise is an object of the built-in `Promise` class. It has the meaning of the "delayed result".

The constructor syntax is:

let promise = new Promise(function(resolve, reject) {

// ...

});

The function is called *executor*. It is called automatically when the promise is created and can do an asynchronous job, like loading a script, but can be something else.

At the end, it should call one of:

- `resolve(result)` -- to indicate that the job finished successfully with the `result`.

- `reject(error)` -- to indicate that an error occured, and `error` should be the `Error` object (technically can be any value).

For instance:

let promise = new Promise(function(*!*resolve*/!*, reject) {

// this function is executed automatically when the promise is constructed

setTimeout(() => *!*resolve("done!")*/!*, 1000);

});

Or, in case of an error:

let promise = new Promise(function(resolve, *!*reject*/!*) {

setTimeout(() => *!*reject(new Error("Woops!"))*/!*, 1000);

});

Initially, the promise is said to have a "pending" state. Then it has two ways. When `resolve` is called, the state becomes "fulfilled". When `reject` is called, the state becomes "rejected":

The idea of promises is that an external code may react on the state change.

The `promise` object provides the method `promise.then(onResolve, onReject)`.

Both its arguments are functions:

- `onResolve` is called when the state becomes "fulfilled" and gets the result.

- `onReject` is called when the state becomes "rejected" and gets the error.

For instance, here `promise.then` outputs the result when it comes:

```js run

let promise = new Promise(function(resolve, reject) {

setTimeout(() => resolve("done!"), 1000);

});

promise.then(result => alert(result));

...And here it shows the error message:

```js run

let promise = new Promise(function(resolve, reject) {

setTimeout(() => reject(new Error("Woops!")), 1000);

});

promise.then(null, error => alert(error.message));

- To handle only a result, we can use single argument: `promise.then(onResolve)`

- To handle only an error, we can use a shorthand method `promise.catch(onReject)` -- it's the same as `promise.then(null, onReject)`.

Here's the example rewritten with `promise.catch`:

```js run

let promise = new Promise(function(resolve, reject) {

setTimeout(() => reject(new Error("Woops!")), 1000);

});

promise.catch(error => alert(error.message));

"What's the benefit?" -- one might ask, "How do we use it?" Let's see an example.

We have the `loadScript` function for loading a script from the previous chapter, here's the callback-based variant:

function loadScript(src, callback) {

let script = document.createElement('script');

script.src = src;

script.onload = () => callback(null, script);

script.onerror = () => callback(new Error(`Script load error ` + src));

document.head.append(script);

}

Let's rewrite it using promises.

The call to `loadScript(src)` below returns a promise that settles when the loading is complete:

```js run

function loadScript(src) {

return new Promise(function(resolve, reject) {

let script = document.createElement('script');

script.src = src;

script.onload = () => resolve(script);

script.onerror = () => reject(new Error("Script load error: " + src));

document.head.append(script);

});

}

let promise = loadScript("https://cdnjs.cloudflare.com/ajax/libs/lodash.js/3.2.0/lodash.js");

promise.then(

script => alert(`${script.src} is loaded!`),

error => alert(`Error: ${error.message}`);

);

The benefits compared to the callback syntax:

- We can add as many `.then` as we want and when we want. Maybe later.

- Also we can pass a promise object somewhere else, and new handlers can be added there, so that's extensible.

So promises already give us flexibility. But there's more. We can chain promises, see the next chapter.

````warn header="Once a promise settles, it can't be changed"

```smart header="On settled promises `then` runs immediately"

As we've seen from the example above, a promise may call resolve/reject without delay. That happens sometimes, if it turns out that there's no asynchronous things to be done.

When the promise is settled (resolved or rejected), subsequent `promise.then` callbacks are executed immediately.

...But if we pass more arguments: `resolve(1, 2, 3)`, then all arguments after the first one are ignored. A promise may have only one value as a result/error.

Use objects and destructuring if you need to pass many values, like this:

```js run

let promise = new Promise(function(resolve, reject) {

resolve({name: "John", age: 25}); // two values packed in an object

});

promise.then(function({name, age}) {

alert(`${name} ${age}`); // John 25

})