Implement asynchronous processing
This article gives an overview of asynchronous processing and explains how to implement it in Office Scripts, with sample code.
About asynchronous processing
Section titled “About asynchronous processing”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.
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.”
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.
This runs after retrieving data from GoogleRetrieved 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.
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.
Retrieved data from GoogleThis runs after retrieving data from GoogleAsynchronous processing with async/await
Section titled “Asynchronous processing with async/await”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.
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');}Asynchronous processing with Promise
Section titled “Asynchronous processing with Promise”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.
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.