Suggest an edit

Improve this article

Refine the answer for “What is a promise?”. Your changes go to moderation before they’re published.

Approval required

Content

What you’re changing

Title (EN)

Short answer (EN)

Shown above the full answer for quick recall.

Answer (EN)

## What **Promise** is

> **Promise** is a special object that represents the **result of an asynchronous operation**:
> - either a **successful result**,
> - or an **error**,
> which may occur **in the future**.

In other words:

> A promise is JavaScript's "promise" that "I will give you the result later".

## An example of a simple promise

```javascript
const promise = new Promise((resolve, reject) => {
  setTimeout(() => {
    resolve('Data received');
  }, 1000);
});

promise.then(result => {
  console.log(result); // 'Data received' (after 1 sec)
});
```

What happens:

1. `new Promise()` creates a promise.
2. The callback inside receives two parameters:
  - `resolve(value)` → the operation finished successfully
  - `reject(error)` → an error occurred
3. The `.then()` method fires when the promise resolves (`fulfilled`).

## Promise states

Every `Promise` can be in one of **three states**:

| State | Description |
| --- | --- |
| **pending** (waiting) | The promise is still running |
| **fulfilled** (resolved) | The operation finished successfully, `resolve()` was called |
| **rejected** (rejected) | An error occurred, `reject()` was called |

Once a promise moves into one of its final states (fulfilled/rejected), it **no longer changes**.

## An example with `resolve` and `reject`

```javascript
const promise = new Promise((resolve, reject) => {
  const success = Math.random() > 0.5;

if (success) {
    resolve('Success');
  } else {
    reject('Error');
  }
});

promise
  .then(result => console.log(result))   // if everything went well
  .catch(error => console.error(error)) // if there was an error
  .finally(() => console.log('Finished'));
```

`.then()` is called on success
`.catch()` is called on error
`.finally()` is called **always**, regardless of the outcome

## Promises are a way to "flatten" asynchronous code

### Before (callbacks):

```javascript
getUser(id, function (user) {
  getPosts(user.id, function (posts) {
    getComments(posts[0].id, function (comments) {
      console.log(comments);
    });
  });
});
```

### With promises:

```javascript
getUser(id)
  .then(user => getPosts(user.id))
  .then(posts => getComments(posts[0].id))
  .then(comments => console.log(comments))
  .catch(err => console.error(err));
```

Now the code reads **linearly**, top to bottom.

## Example: turning asynchronous code into a promise

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

delay(2000).then(() => console.log('2 seconds have passed'));
```

## Promise API methods

| Method | What it does |
| --- | --- |
| `Promise.resolve(value)` | Creates a resolved promise |
| `Promise.reject(error)` | Creates a rejected promise |
| `Promise.all([p1, p2])` | Waits for **all** promises to resolve |
| `Promise.race([p1, p2])` | Returns the result of the **first** promise to settle |
| `Promise.allSettled([p1, p2])` | Waits for all promises, even if some reject |
| `Promise.any([p1, p2])` | Returns the **first successful** promise |

## An example of `Promise.all`

```javascript
const p1 = Promise.resolve('A');
const p2 = Promise.resolve('B');
const p3 = Promise.resolve('C');

Promise.all([p1, p2, p3]).then(values => {
  console.log(values); // ['A', 'B', 'C']
});
```

## An example of `Promise.race`

```javascript
const slow = new Promise(resolve => setTimeout(() => resolve('slow'), 2000));
const fast = new Promise(resolve => setTimeout(() => resolve('fast'), 1000));

Promise.race([slow, fast]).then(result => console.log(result));
// fast
```

## Promises are the foundation for `async/await`

Later (in ES2017) a layer on top appeared, the `async/await` syntax,
which makes the code **even simpler**:

```javascript
const getData = () => new Promise(resolve => setTimeout(() => resolve('OK'), 1000));

async function main() {
  const res = await getData();
  console.log(res);
}
main(); // OK
```

> `await` is just "syntactic sugar" over `.then()`

## Key features

| Feature | Description |
| --- | --- |
| Asynchronous by nature | Processed through the microtask queue |
| Resolves only once | A promise can be "resolved" only once |
| Does not block the thread | JS continues running the rest of the code |
| Supports chaining | `.then()` and `.catch()` can be chained together |

## Summary

| What it is | In simple words |
| --- | --- |
| Promise | A "promise" that an asynchronous operation will return a result later |
| States | pending → fulfilled / rejected |
| then() | Run code on success |
| catch() | Run code on error |
| finally() | Run code no matter what |

Simply put:

> A **promise** is a container for the result of an operation that will finish in the future.
> It simplifies asynchronous code, making it linear, understandable, and predictable.

Markdown · drag & drop images · ⌘B / ⌘I shortcuts715 words

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.