Velo Promises in Action: Key Tips to Call the Asynchronously-Run Functions

Asynchronous code is code that doesn't necessarily run line-by-line in the order you've written it. In Velo, you will often encounter asynchronous code when you call a function that cannot finish executing immediately and therefore returns a Promise. Also, when you call a backend function that you've written from your page code, you must call it asynchronously.

For example, if you run a query on one of your database collections using the

find()

Consider the following code snippet where the

find()

console.log("1")

wixData.query("myCollection")
  .find()
  .then( (results) => {
    console.log("2");
  } );

console.log("3");

The following will be logged to the console.

1
3
2

Notice that the 3 is logged before the

2

console.log()

2

In this article, we describe how to work with the functions in the Velo API that run asynchronously. We discuss different ways to call such functions and wait for them to finish executing. We do not present a general discussion of asynchronous programming in JavaScript. To learn more about using Promises in a general context, see Using Promises.

Promise

A Promise represents a value that is not necessarily known when the Promise is created because it depends on asynchronous communication. A
function that returns a promise is returning a contract to eventually produce a return value at some point in the future. A Promise is said to be fulfilled or resolved when its value is finally known.

There are two main ways to work with Promises that are returned from a function.

• then()

  - Using this approach your code is generally a little more difficult to read, but you have more control over when your code runs. For example, if your code does not need to wait for a Promise to resolve, you can have other code run in the meantime, thereby improving overall performance.

• async/await

  - Allows you to work with asynchronous code as if it was synchronous, making you code easier to read. However, you lose the option of running other code while waiting for a Promise to resolve.

Generally, using

async/await

then( )

You can use the

then()

then()

For example, let's say you want to retrieve some data from a collection and display it in a table. Since the data retrieval is an asynchronous operation, you have to wait until it is completed before using the query results to set the table's data. The

find()

then()

then()

import wixData from 'wix-data';

$w.onReady( function () {
  wixData.query("myCollection")
    .find()
    .then( (results) => {
      // this will only run once the query has returned results
      $w("#myTable").rows = results.items;
    } );
  // code here will run before the query has returned results
} );

Multiple .then( ) Calls

Sometimes, you will need to call another asynchronous function inside the

then()

For example, let's say you want to use the

fetch()

json()

You might think that you need to nest one

then()

fetch( url, {method: 'get'} )
  .then( (response) => {
    return response.json()
      .then( (json) => {
        // do something with the json response
      } );
  } );

But because

then()

then()

then()

That means the code above should be written like this:

fetch( url, {method: 'get'} )
  .then( response => response.json() )
  .then( (json) => {
    // do something with the json response
  } );

Here, the

then()

then()

fetch()

then()

then()

json()

then()

fetch()

then()

json()

Returning in a .then( )

Another common misconception is what happens when you use a return inside a

then()

then()

For example, let's say you have a page about cars. On that page you have a
dropdown that users use to select a car model. When a selection is made, you perform a query for a specific car model and populate a table with all the matching items.

You might write some code like this thinking that the

queryCars()

find()

import wixData from 'wix-data';

export function modelDropdown_change() {
  let model = $w("#modelDropdown").value;
  $w("#resultsTable").rows = queryCars(model);
}

// This will not work as expected
function queryCars(model) {
  wixData.query("cars")
    .eq("model", model)
    .find()
    .then( (results) => {
      return results.items;
    } );
}

However, the above code will not work as expected. Let's understand why it doesn't work and what we need to do to fix it.

When we return

results.items

queryCars()

then()

queryCars()

queryCars()

To remedy this situation, we need to return the result of the Promise's

then()

then()

return

So here our chain looks like this:

• .query()

  - Create a query - returns a WixDataQuery object

• .eq()

  - Modify the query - returns a WixDataQuery object

• .find()

  - Execute the query - returns a Promise

• .then()

  - Define what to do on resolution - returns a Promise

Adding a

return

then()

then()

queryCars()

That means our fixed up code should look like this:

import wixData from 'wix-data';

export function modelDropdown_change() {
  let model = $w("#modelDropdown").value;
  queryCars(model)
    .then( (items) => {
      $w("#resultsTable").rows = items;
    } );
}

// The added `return` on line 13 fixes the problem
function queryCars(model) {
  return wixData.query("cars")
    .eq("model", model)
    .find()
    .then( (results) => {
      return results.items;
    } );
}

Here the

queryCars()

queryCars()

then()

Debugging on the Backend

Calls to

console.log()

then()

For example, consider the following backend code:

export function usePromise() {
  return fetch('https://site.com/api?q=query', {method: 'get'})
    .then( (response) => {
      console.log(response.status);
  } );
}

As written, if you call

usePromise

usePromise

Note

You can use Site Monitoring to view the output of console messages in backend code.

Error Handling

An asynchronous process might fail for any number of reasons. For example if you call a function like

fetch()

catch()

then()

catch()

Let's return to the example of retrieving some data from a collection and
displaying it in a table. You can handle errors by adding a

catch()

import wixData from 'wix-data';

$w.onReady( function () {
  wixData.query("myCollection")
    .find()
    .then(results => $w("#myTable").rows = results.items)
    .catch(error => {
      // handle your error here
    } );
} );

async/await

Using a

then()

then()

async/await

You use

await

await

async

Once again, let's return to the example of retrieving some data from a
collection and displaying it in a table. But instead of using a

then()

async/await

find()

Remember, when using a

then()

import wixData from 'wix-data';

$w.onReady( function () {
  wixData.query("myCollection")
    .find()
    .then( (results) => {
      // this will only run once the query has returned results
      $w("#myTable").rows = results.items;
    } );
  // code here will run before the query has returned results
} );

Using

async/await

import wixData from 'wix-data';

$w.onReady( async function () { 
  const results = await wixData.query("myCollection").find(); 
  // the next line will run only after the query has finished
  $w("#table1").rows = results.items;
} );

Here, you can see on line 3 that the callback function passed to the

onReady()

async

find()

await

find()

Note, that when you create an async function, that function returns a Promise. So when you call that function you need to use one of the approaches discussed in this article to deal with the Promise it returns.

For example, here is an async function that queries a collection to find an item with a specified name.

import wixData from 'wix-data';

//...

async function findName(name) {
  const results = await wixData.query("myCollection")
    .eq("name", name)
    .find();
  return results.items[0];
}

You can call this function using a

then()

$w.onReady( function () {
  findName("Bob")
    .then(item => console.log(item));
} );

Or, you can call it using

async/await

$w.onReady( async function () {
  const item = await findName("Bob");
  console.log(item);
} );

Error Handling

When using

async/await

try/catch

import wixData from 'wix-data';

$w.onReady( async function () { 
  try {
    const results = await wixData.query("myCollection").find(); 
    $w("#table1").rows = results.items;
  }
  catch(error) {
    // handle the error here
  }
} );

Image Credit: https://pixahive.com/photo/promise-illustration/

Previously published at https://support.wix.com/en/article/velo-working-with-promises