Skip to content

Implement asynchronous processing

This article gives an overview of asynchronous processing and explains how to implement it in Office Scripts, with sample code.

As the name suggests, asynchronous processing is processing that doesn’t run synchronously.

Before we explain how to implement it, take a look at the following code.

Type definition of the fetch function
function fetch(input: RequestInfo, init?: RequestInit): Promise<Response>;

This is the type definition of the fetch function, which retrieves data from an external service.

You can see that the function’s return value is wrapped in a Promise.

The result of asynchronous processing is wrapped in this Promise. A Promise is an object that represents “the future result of an operation that may not have finished yet.”

Sample using the fetch function
async function fetchGoogle() {
const response = await fetch('https://www.google.com');
console.log('Retrieved data from Google');
}
async function main(workbook: ExcelScript.Workbook) {
fetchGoogle();
console.log('This runs after retrieving data from Google');
}

The sample above defines an asynchronous function, fetchGoogle, and calls it from the main function.

For now, all you need to know about fetchGoogle is that it’s “a function that returns its result asynchronously (it returns a Promise).” What we want you to look at is how the main function behaves.

You’d probably expect the rest of the main function to run after fetchGoogle finishes, but the actual result is as follows.

Output
This runs after retrieving data from Google
Retrieved data from Google

(In Office Scripts, asynchronous operations that aren’t awaited may not finish before the script ends, so the second line may not be output at all.)

You can see that the rest of the main function ran first.

As this shows, if nothing tells the code to wait for asynchronous processing, the code that follows runs without waiting for the asynchronous processing to finish.

Waiting for the asynchronous function
async function fetchGoogle() {
const response = await fetch('https://www.google.com');
console.log('Retrieved data from Google');
}
async function main(workbook: ExcelScript.Workbook) {
await fetchGoogle();
console.log('This runs after retrieving data from Google');
}

We added await before fetchGoogle();.

Now you get the result you expected.

Output
Retrieved data from Google
This runs after retrieving data from Google

The most recommended way to write asynchronous processing in Office Scripts is to use async/await.

Add async before the function keyword of the function that calls the asynchronous code, and add await before each call that returns its result asynchronously. Processing then waits until the asynchronous function’s result is available.

Sample using async/await
async function main(workbook: ExcelScript.Workbook) {
/** Response from the Google website */
const google = await fetch('https://www.google.com');
console.log('Retrieved data from Google');
/** Response from the Yahoo website */
const yahoo = await fetch('https://www.yahoo.co.jp');
console.log('Retrieved data from Yahoo');
}

As mentioned earlier, the result of an asynchronous function is wrapped in a Promise object, so you can use methods of the Promise object, such as then.

In terms of JavaScript syntax, async isn’t required when you use then. However, when you make external calls in Office Scripts, you need to add async to the main function and use await to wait for the entire then chain so that processing finishes before the script ends.

Sample using Promise.then
async function main(workbook: ExcelScript.Workbook) {
await fetch('https://www.google.com')
.then((google) => {
console.log('Retrieved data from Google');
return fetch('https://www.yahoo.co.jp');
})
.then((yahoo) => {
console.log('Retrieved data from Yahoo');
});
}

If you compare it with the async/await pattern, you’ll see that this approach, which uses method chaining with Promise.then, looks very different from ordinary synchronous code, and it can make your code harder to read.

Unless it can’t be avoided, we recommend using async/await.