Update background tasks guide (supabase#30814)

* fix wording

* chore: update background tasks guide

* Apply suggestions from code review

Co-authored-by: Charis <[email protected]>

---------

Co-authored-by: Charis <[email protected]>

Author: laktek

apps/docs/content/guides/functions/background-tasks.mdx

@@ -3,39 +3,59 @@ id: 'function-background-tasks'
 title: 'Background Tasks'
 description: 'How to run background tasks in an Edge Function outside of the request handler'
 subtitle: 'How to run background tasks in an Edge Function outside of the request handler'
-tocVideo: 'rSKBTJxG9VA'
 ---
 
 Edge Function instances can process background tasks outside of the request handler. Background tasks are useful for asynchronous operations like uploading a file to Storage, updating a database, or sending events to a logging service. You can respond to the request immediately and leave the task running in the background.
 
-### How long a background task can run
+### How it works
 
-A background task can run until the Edge Function instance hits its wall-clock limit or reaches CPU/Memory limit. Check [limits](/docs/guides/functions/limits) for current caps.
+You can use `EdgeRuntime.waitUntil(promise)` to explicitly mark background tasks. The Function instance continues to run until the promise provided to `waitUntil` completes.
+
+The maximum duration is capped based on the wall-clock, CPU, and memory limits. The Function will shutdown when it reaches one of these [limits](/docs/guides/functions/limits).
+
+You can listen to the `beforeunload` event handler to be notified when Function invocation is about to be shut down.
 
 ### Example
 
-Here's an example of defining a background task using a custom event.
+Here's an example of using `EdgeRuntime.waitUntil` to run a background task and using `beforeunload` event to be notified when the instance is about to be shut down.
 
 ```ts
-// Define a custom event type for the background task.
-class MyBackgroundTaskEvent extends Event {
-  readonly taskPromise: Promise<Response>
-
-  constructor(taskPromise: Promise<Response>) {
-    super('myBackgroundTask')
-    this.taskPromise = taskPromise
-  }
+async function longRunningTask() {
+  // do work here
 }
 
-globalThis.addEventListener('myBackgroundTask', async (event) => {
-  const res = await (event as MyBackgroundTaskEvent).taskPromise
-  console.log(await res.json())
+// Mark the longRunningTask's returned promise as a background task.
+// note: we are not using await because we don't want it to block.
+EdgeRuntime.waitUntil(longRunningTask())
+
+// Use beforeunload event handler to be notified when function is about to shutdown
+addEventListener('beforeunload', (ev) => {
+  console.log('Function will be shutdown due to', ev.detail?.reason)
+
+  // save state or log the current progress
+})
+
+// Invoke the function using a HTTP request.
+// This will start the background task
+Deno.serve(async (req) => {
+  return new Response('ok')
 })
+```
+
+### Starting a background task in the request handler
+
+You can call `EdgeRuntime.waitUntil` in the request handler too. This will not block the request.
+
+```ts
+async function fetchAndLog(url: string) {
+  const response = await fetch('https://httpbin.org/json')
+  console.log(response)
+}
 
 Deno.serve(async (req) => {
-  const fetchPromise = fetch('https://httpbin.org/json')
-  const event = new MyBackgroundTaskEvent(fetchPromise)
-  globalThis.dispatchEvent(event)
+  // this will not block the request,
+  // instead it will run in the background
+  EdgeRuntime.waitUntil(fetchAndLog('https://httpbin.org/json'))
 
   return new Response('ok')
 })

apps/docs/content/guides/functions/ephemeral-storage.mdx

@@ -24,7 +24,7 @@ You can use [Deno File System APIs](https://docs.deno.com/api/deno/file-system)
 
 ### Example
 
-Here is an example of how to write a user-uploaded zip file into a temporary file for further processing.
+Here is an example of how to write a user-uploaded zip file into temporary storage for further processing.
 
 ```js
 Deno.serve(async (req) => {