--- id: "apps-script-async-await" title: "Promises, async and await in Google Apps Script" description: "Understand async/await and Promises in Google Apps Script. Learn why most APIs remain synchronous and how WebAssembly is the exception." pubDate: "2024-02-07T00:00:00.000Z" tags: - "code" - "google" - "google workspace" - "apps script" - "async" - "es6" - "wasm" - "webassembly" syndicate: false faq: - question: "Does Google Apps Script support async/await and Promises?" answer: "Yes, Apps Script's V8 runtime supports async/await and Promises, just like other V8-based environments." - question: "Are there any asynchronous APIs in Apps Script?" answer: "You'll find very few native asynchronous APIs in Apps Script. The key exception I've found is the WebAssembly API (WebAssembly.instantiate()), which genuinely works with async/await." - question: "Is top-level `await` supported in Apps Script?" answer: "No, top-level `await` isn't supported. I can only use `await` inside an `async` function." - question: "What happens with unhandled promise rejections in Apps Script?" answer: "Apps Script currently lacks unhandledRejection errors for Promises." - question: "Can I use `setTimeout` or `setInterval` in Apps Script?" answer: "No, `setTimeout` and `setInterval` aren't available." - question: "Is `Utilities.sleep()` a good alternative for `setTimeout`?" answer: "Definitely not. `Utilities.sleep()` blocks script execution, which is completely different from `setTimeout`'s asynchronous behavior." canonicalURL: "https://justin.poehnelt.com/posts/apps-script-async-await/" relativeURL: "/posts/apps-script-async-await/" markdownURL: "/posts/apps-script-async-await.md" --- Google Apps Script is based on the V8 engine and supports the use of Promises, async and await. However, there are almost no APIs available that are asynchronous except for the WebAssembly API. The [WebAssembly](https://developer.mozilla.org/en-US/docs/WebAssembly) API is used to run compiled code binaries. This is a very niche use case and not something that is commonly used in Apps Script, but WebAssembly is explicitly called out for in the [V8 engine](https://v8.dev/): > v8 is Google’s open source high-performance JavaScript and WebAssembly engine, written in C++. It is used in Chrome and in Node.js, among others. It implements ECMAScript and WebAssembly… I’m not going to get into the specifics of WebAssembly in this post, but I wanted to identify it as the only place I’ve seen async and await actually useful in Apps Script. ## Syntax of Promises, async and await in Apps Script[](#syntax-of-promises-async-and-await-in-apps-script) The syntax for Promises, async and await in Apps Script is the same as you would expect in modern JavaScript. Here is a simple example of a Promise: ```javascript function main() { const promise = new Promise((resolve, reject) => { resolve("hello world"); }); console.log(promise.constructor.name); promise.then(console.log); } ``` As expected in JavaScript, this outputs the following: ```sh 11:11:50 AM Notice Execution started 11:11:50 AM Info Promise 11:11:50 AM Info hello world 11:11:50 AM Notice Execution completed ``` But, as I mentioned, this is not actually asynchronous. The `Promise` is resolved immediately and the `then` is called immediately. So there is no actual asynchronous behavior here. I haven’t dug deep into the underlying event loop and tasks here. Might be worth a future post to dig deeper. Here is an example of using async and await: ```javascript async function main() { const promise = new Promise((resolve, reject) => { resolve("hello world"); }); console.log(promise.constructor.name); console.log(await promise); } ``` This leads to an interesting discovery, the entry function can be `async` and the `await` keyword can be used. But can I use a top-level await? ```javascript const promise = new Promise((resolve, reject) => { resolve("hello world"); }); await promise; // doesn't work function main() { console.log(promise.constructor.name); } ``` No, top-level await is not supported in Apps Script and returns the following error when trying to save the script: ```sh Syntax error: SyntaxError: await is only valid in async functions and the top-level bodies of modules line: 5 file: Code.gs ``` There is no `unhandledRejection` error for promises in Apps Script. Combined with an async function, this can lead to silent errors. ## WebAssembly in Apps Script[](#webassembly-in-apps-script) As mentioned earlier, the only place I’ve seen async and await actually useful in Apps Script is with the WebAssembly API. Here is a simple example of using async and await with WebAssembly: ```javascript async function main() { let bytes = new Uint8Array( Utilities.base64Decode( "AGFzbQEAAAABBwFgAn9/AX8DAgEAB" + "wcBA2FkZAAACgkBBwAgACABagsAHA" + "RuYW1lAQYBAANhZGQCDQEAAgADbGh" + "zAQNyaHM=", ), ); let { instance: { exports: { add }, }, } = await WebAssembly.instantiate(bytes); console.log(add(1, 2)); } ``` This output works as expected: ```sh 11:44:38 AM Notice Execution started 11:44:38 AM Info 3 11:44:38 AM Notice Execution completed ``` However, to verify that the code is running asynchronously, I removed the `await` from the `await WebAssembly.instantiate` which resulted in: ```javascript 11:45:57 AM Notice Execution started 11:45:58 AM Error TypeError: Cannot read properties of undefined (reading 'exports') main @ Code.gs:6 ``` So, it is clear that the WebAssembly API is running asynchronously and populating the `instance.exports` object asynchronously after the `instantiate` method is called. ## Addendum: `setTimeout` and `Utilities.sleep`[](#addendum-settimeout-and-utilitiessleep) The functions `setTimeout` and `setInterval` are typically used to create asynchronous behavior in JavaScript. However, in Apps Script, these functions are not defined and will result in `ReferenceError: setTimeout is not defined`. It may be tempting to use `Utilities.sleep()` to recreate `setTimeout`, but this function is synchronous and will block the task queue. ```javascript new Promise((resolve, reject) => { console.log("start"); Utilities.sleep(2000); console.log("end"); resolve(); }).then(() => console.log("done")); console.log("next"); ``` This will output the following: ```bash 3:20:21 PM Notice Execution started 3:20:22 PM Info start 3:20:24 PM Info end 3:20:24 PM Info next < this is printed after the sleep!!! 3:20:24 PM Info done 3:20:24 PM Notice Execution completed ``` If this was asynchronous, the `next` would be printed before the `end`. Interestingly, if you use `async`/`await`, the output changes to: ```bash 3:22:37 PM Notice Execution started 3:22:38 PM Info start 3:22:40 PM Info end 3:22:40 PM Info done 3:22:40 PM Info next < this is printed after the sleep!!! 3:22:40 PM Notice Execution completed ``` ## Conclusion[](#conclusion) The topic here is a bit esoteric, but as you attempt to push the limits of what is possible in Apps Script, it is good to know that you can use Promises, async and await in your code. I hope to share much more in the future on WebAssembly and other advanced topics in Apps Script! [Promises, async and await in Google Apps Script](https://justin.poehnelt.com/posts/apps-script-async-await/) © 2024 by [Justin Poehnelt](https://justin.poehnelt.com/) is licensed under CC BY-SA 4.0