Lesson 21: Asynchronous JavaScript

21.1 Two Ways to Get Live Data

Maya would like the club's home page to show the rain forecast. You fetched a forecast in Lesson 17. Talking to Web Services, with Apps Script's UrlFetchApp. So ask how to do it in a web page, in a new chat with your learner profile from Lesson 20. Events and Interactivity:

This is a thoughtful answer. The assistant explained that fetching data in a browser works differently, in a way your profile doesn't cover yet, and instead of using it anyway, it found a route with what you know: let Apps Script fetch the forecast and build the page, as a web app. You can read every line of it: it's Lesson 18. A Web App with Apps Script and Lesson 17. Talking to Web Services put together.

It's also a real design choice, not just a workaround. Doing the work on a server, then sending a finished page, is how much of the web works, and it has advantages: the visitor's browser does less, and secrets can stay on the server. But the club's home page is an ordinary web page, not an Apps Script web app, and the browser can fetch the data itself. That needs the "different way" the assistant mentioned, which is this lesson's subject.

21.2 Why the Browser Waits Differently

In Apps Script, UrlFetchApp.fetch(url) stopped your script until the reply arrived, and then the next line ran. That's called synchronous code: each line finishes before the next one starts. It was fine, because nobody was looking at your script while it waited.

A web page is different. Someone is looking at it, scrolling, clicking and typing. If the page stopped everything while waiting a second or two for a reply from another computer, it would freeze: buttons wouldn't respond, and nothing would scroll. So in the browser, a request for data is asynchronous: your code asks for the data, carries on, and handles the reply when it arrives.

21.2.1 Promises

The browser's version of UrlFetchApp.fetch is called fetch, and it can't give you the reply right away, because the reply hasn't arrived. Instead it gives you a promise: an object that stands for a result that will be available later. The promise is pending at first, and later it's either fulfilled, with the result, or rejected, with an error.

21.2.2 async and await

To use the result, you await the promise. await pauses the function until the promise is fulfilled, then gives you its result. And await can only be used inside a function marked async:

<p id="status">Waiting...</p>

<script>
  async function loadForecast() {
    const url = "https://api.open-meteo.com/v1/forecast?latitude=40.25&longitude=-111.65&daily=precipitation_sum&timezone=auto&forecast_days=3"
    console.log("1. Asking for the forecast")
    const response = await fetch(url)
    const data = await response.json()
    console.log("3. The forecast arrived")
    const status = document.querySelector("#status")
    status.textContent = `Rain in the next three days: ${data.daily.precipitation_sum}`
  }

  loadForecast()
  console.log("2. The page carries on")
</script>

Run it, and look at the order of the messages: 1, 2, 3. When loadForecast reaches the first await, it pauses, and the rest of the page's code carries on, which is why message 2 appears before message 3. When the reply arrives, loadForecast picks up where it left off. Inside the function, await makes the code read top to bottom, like the synchronous code you're used to. Outside it, nothing waits.

Two awaits are needed. fetch gives a promise of a response, which holds the reply's status and headers, but not yet all of its content. response.json() gives a second promise, for the content read and parsed as JSON, which does the job of getContentText() and JSON.parse together.

21.3 Fetching the Forecast in the Page

Back to the chat, now that you know async and await:

Read.

• loadForecast is async, and it's called once at the end of the script.
• await fetch(url) and await response.json() are the two waits you just learned.
• response.ok is a property that's true when the server replied successfully. Unlike UrlFetchApp, fetch doesn't treat an error reply, such as "404 Not Found," as a failure; it only fails when there's no reply at all. So checking ok is how you notice that the server said no. When it's false, the code throws an error of its own, with new Error(...), which creates an error object with a message.
• document.createElement("li") creates a new list item, and appendChild adds it to the end of the list. It's a way to build a page without writing HTML in a string, which also means the text goes in through textContent, so it can never be read as HTML. Neither method was on your list, and the reply didn't mention that; you can read them from their names, but it's worth noticing.
• try and catch put a message on the page if anything fails, instead of leaving a blank list. Unlike the Apps Script trigger in Lesson 17. Talking to Web Services, where catching an error hid it, here a person is looking at the page, so showing the message is exactly right.

Run it:

<!DOCTYPE html>
<html>
<head>
  <title>Club Rain Forecast</title>
  <style>
    body {
      font-family: Arial;
      margin: 20px;
    }
    .error {
      color: red;
    }
  </style>
</head>
<body>

  <h1>Rain Forecast</h1>

  <ul id="forecast-list"></ul>

  <p id="error-message" class="error"></p>

  <script>

    async function loadForecast() {
      // These hold the club's location
      const latitude = 40.25
      const longitude = -111.65

      // Build the web address for the Open-Meteo API
      const url = `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&daily=precipitation_sum&timezone=auto&forecast_days=3`

      // Find the elements on the page we'll fill in
      const list = document.querySelector("#forecast-list")
      const errorMessage = document.querySelector("#error-message")

      try {
        // Ask Open-Meteo for the forecast and wait for the reply
        const response = await fetch(url)

        // Check whether the server said something went wrong
        if (response.ok === false) {
          throw new Error(`Server responded with status ${response.status}`)
        }

        // Turn the reply into a JavaScript object
        const data = await response.json()

        // Pull out the parallel arrays of dates and rain amounts
        const dates = data.daily.time
        const rainAmounts = data.daily.precipitation_sum

        // Add one list item for each day
        for (let i = 0; i < dates.length; i++) {
          const date = dates[i]
          const rain = rainAmounts[i]
          const item = document.createElement("li")
          item.textContent = `${date}: ${rain} mm of rain`
          list.appendChild(item)
        }

      } catch (error) {
        // If anything above failed, show a message instead of a blank page
        errorMessage.textContent = `Could not load forecast: ${error.message}`
      }
    }

    loadForecast()

  </script>

</body>
</html>

21.4 A Missing await

One mistake with async code is so common that it's worth seeing on purpose. Here's what happens when await goes missing:

That's right. Without await, response holds the promise itself, not the response, and a promise has no json method. The error message is a symptom: it says json isn't a function, and doesn't mention await at all. (The reply says the message reported "the real underlying problem," but it didn't; you had to reason back from the symptom to the cause.)

There's a quieter problem hidden in that code, too. The check response.ok === false didn't catch anything, because a promise has no ok property, so response.ok was undefined, and undefined === false is false. The code sailed past the check to the next line.

Learn to recognize the signs of a missing await:

• "... is not a function" or undefined properties on something that came from fetch or another async function.
• [object Promise] appearing on the page, where text was expected.
• Promise { <pending> } in the Console where you expected data.

21.5 Showing the Forecast on the Home Page

Here's the forecast as part of the club's home page, in the book's style. It adds a day of the week to each date, using what you learned about Date objects in Lesson 14. Email, Calendar, and Dates. Adding T12:00 to the date text makes it noon in your time zone, which avoids the time-zone trap from that lesson:

<!doctype html>
<html>
  <head>
    <title>College Community Garden</title>
    <style>
      body {
        font-family: Arial, sans-serif;
        background-color: #f4f9f4;
        margin: 20px;
      }
      h1 {
        color: #2e7d32;
      }
      .error {
        color: darkred;
      }
    </style>
  </head>
  <body>
    <h1>College Community Garden</h1>
    <h2>Rain in the next three days</h2>
    <ul id="forecast">
      <li>Loading the forecast...</li>
    </ul>

    <script>
      const DAY_NAMES = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"]

      async function showForecast() {
        const url = "https://api.open-meteo.com/v1/forecast?latitude=40.25&longitude=-111.65&daily=precipitation_sum&timezone=auto&forecast_days=3"
        const list = document.querySelector("#forecast")
        try {
          const response = await fetch(url)
          if (response.ok === false) {
            throw new Error(`the weather service replied with status ${response.status}`)
          }
          const data = await response.json()
          const dates = data.daily.time
          const rainAmounts = data.daily.precipitation_sum

          // replace the "Loading" message with the forecast
          list.textContent = ""
          for (let i = 0; i < dates.length; i++) {
            // noon avoids the date shifting across time zones
            const date = new Date(`${dates[i]}T12:00`)
            const dayName = DAY_NAMES[date.getDay()]
            const item = document.createElement("li")
            item.textContent = `${dayName}: ${rainAmounts[i]} mm`
            list.appendChild(item)
          }
        } catch (error) {
          list.textContent = ""
          const item = document.createElement("li")
          item.className = "error"
          item.textContent = `The forecast isn't available right now (${error.message}).`
          list.appendChild(item)
        }
      }

      showForecast()
    </script>
  </body>
</html>

Two touches worth copying: the list says "Loading the forecast..." until the data arrives, so visitors know something is happening, and an error replaces it with a message a club member can understand. Try breaking the address, for example by changing open-meteo to open-meteor, to see the error message.

21.6 Your Learner Profile

21.7 Summary

A browser can't freeze a page while it waits for data, so a web request there is asynchronous: fetch returns a promise, a stand-in for a result that arrives later. Inside an async function, await pauses until a promise is fulfilled and gives you its result, so await fetch(url) gets a response and await response.json() gets its content as an object. Everything outside the function carries on meanwhile. fetch only fails when there's no reply, so check response.ok and throw an error when the server says no. A missing await shows up as strange symptoms, such as "is not a function," far from the real cause. Apps Script's UrlFetchApp was synchronous, which is why you didn't need any of this before; fetching on a server remains a good option, especially for APIs that don't allow CORS. Next, you'll use JavaScript on pages you don't own, to automate sites you use.