> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Working with Promises

## Article: Working with Promises

## Article Link: https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/java-script-velo/working-with-promises.md

## Article Content:

# About Promises

> **Note:** This article is intended for coders with limited JavaScript experience, and serves as an introduction to this basic JavaScript content.

Some of the code your write when developing your site is asynchronous code.

Asynchronous code doesn't execute in the order it's written, unlike synchronous code.  Instead, it returns a promise. A [promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises) is an object that represents the eventual completion (or failure) of an asynchronous operation and its resulting value. While the promise is pending, synchronous code continues to run.

When developing your website, there are some cases where you need to work with promises. For example:
- [Calling backend functions](https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/backend-code/web-modules/call-backend-code-from-a-jsw-web-module.md) from your page code.
- Calling certain [APIs](https://dev.wix.com/docs/velo.md).

Promises are a regular JavaScript concept, so it's easy to use AI chatbots or search engines to troubleshoot.


## Supported IDEs

You can handle promises using:

- The editor (Wix Studio and Wix Editor)
- The Wix IDE (Wix Studio)
- You local IDE (Wix Studio and Wix Editor)

## Handle a promise
Handling a promise means telling your code to read and use the value of the promise only once its resolved value is known. This means the asynchronous code has finished running. At any given time, a promise has one of the following statuses:
- **Pending**: The asynchronous code is still running.
- **Fulfilled**/**resolved**: The asynchronous code has finished running and has successfully returned a value.
- **Rejected**: The asynchronous code has finished running and has thrown an error.

You can tell your code to expect a promise and to wait for the asynchronous code to finish running in the following ways:
- [`async`/`await`](#asyncawait): Allows you to treat asynchronous code as if it's synchronous, meaning the next line of code won't run until the promise is resolved.
- [`then()`](#then): Allows you to run other synchronous code while your asynchronous code is running. You have more control over when your code runs, but it's less readable.

## `async`/`await`
The `async`/`await` syntax allows you to handle promises in a way that makes your asynchronous code appear synchronous. This can make your code more readable, as the next line of code won't run until the promise is resolved.


### Define asynchronous functions
Asynchronous functions are functions that contain asynchronous code. An asynchronous function's return value is always a promise.

To define a function as asynchronous, add `async` before the function declaration. For example:
```js
async function myFunction () {}

const myFunction = async () => {}
```

> **Note:** This method is not supported at the top level, because top level code is synchronous.

Add `await` before the call to an asynchronous function to make your code wait for the function to resolve before moving on to the next line. For example:
```js
const myPromiseValue = await myAsyncFunction();
```

Then you can use the value of the resolved promise on the next line. For example:

```js
async function myFunction () {
  const myPromiseValue = await myAsyncFunction();
  console.log(myPromiseValue);
}
```

### Handle errors with `async`/`await`
If your promise is rejected, something has gone wrong in the asynchronous code and you need to handle the error. Use the [`try...catch` block](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/try...catch) to handle errors. For example:
```js
async function myFunction () {
  try {
    const myPromiseValue = await myAsyncFunction();
    console.log(myPromiseValue);
  } catch (error) {
    console.log(error);
  }
}
```

## `then()`
With the `then()` syntax, you can instruct your code to handle promises by running a function once the promise is resolved. For example:
```js
asyncFunc().then((resolvedPromiseValue) => {
  // Do something with resolvedPromiseValue.
  console.log(resolvedPromiseValue);
})
```

### Handle `then()` return value
If you return a value in the function passed to `then()`, that value is always a promise. For example:
```js
const returnValue = asyncFunc().then((resolvedPromiseValue) => {
  return 'The value of the resolved promise is: ' + resolvedPromiseValue;
})
// returnValue is a promise.
```

You can handle this promise in the same way as any other promise:
- Use `async`/`await` to use the value synchronously in your code. For example:
    ```js
    async function myFunction () {
      const secondPromiseValue = await firstAsyncFunc()
        .then((firstPromiseValue) => {
          return secondAsyncFunc(firstPromiseValue);
        })
      console.log(secondPromiseValue);
    }
    ```
- Chain `then()` methods. For example:
    ```js
    firstAsyncFunc()
      .then((firstPromiseValue) => {
          return secondAsyncFunc(firstPromiseValue);
        })
      .then((secondPromiseValue) => {
        console.log(secondPromiseValue)
      })
    ```

Both of the above examples log the same value to the console.

### Handle errors with `then()`
If your promise is rejected, then something has gone wrong in the asynchronous code and you need to handle the error. Use the [`catch()` method](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/catch) to handle errors:
```js
myAsyncFunction()
  .then((myPromiseValue) => {
    console.log(myPromiseValue);
  }).catch((error) => {
    console.log(error);
  })
```

## Handle multiple promises simultaneously
Waiting for multiple promises to be fulfilled before the execution of some code is supported.

You can run multiple asynchronous functions and wait for their promises simultaneously using the [`Promise.all()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all) method. It accepts multiple promises in an array, and returns an array of resolved values. If any of the promises are rejected, the method throws an error.

For example:
```js
Promise.all([promise1, promise2, promise3]).then((values) => {
  console.log(values);
  // Expected output: [
  //   promise1ResolvedValue, 
  //   promise2ResolvedValue,
  //   promise3ResolvedValue
  // ]
});
```