Support async functions

In practice, most long-running operations in Node.js applications
take place as a sequence of `await` operations on functions that
return promises, within an `async` function that itself returns
a promise.

As such, in order for AppSignal to be able to track the duration
of the heartbeat, when the return value is a promise, AppSignal
should send the heartbeat when the promise is resolved, and not when
the function that returns the promise finishes.

Author: unflxw

.changesets/add-heartbeats-support.md

@@ -32,3 +32,21 @@ function sendInvoices() {
 If an exception is raised within the function, the finish event will not be
 reported to AppSignal, triggering a notification about the missing heartbeat.
 The exception will bubble outside of the heartbeat function.
+
+If the function passed to `heartbeat` returns a promise, the finish event will
+be reported to AppSignal if the promise resolves, and a wrapped promise will
+be returned, which can be awaited. This means that you can use heartbeats to
+track the duration of async functions:
+
+```javascript
+import { heartbeat } from "@appsignal/nodejs"
+
+async function sendInvoices() {
+  await heartbeat("send_invoices", async () => {
+    // ... your async code here ...
+  })
+}
+```
+
+If the promise is rejected, or if it never resolves, the finish event will
+not be reported to AppSignal.

src/heartbeat.ts

@@ -97,6 +97,14 @@ export function heartbeat<T>(name: string, fn?: () => T): T | undefined {
     output = fn()
   }
 
-  heartbeat.finish()
+  if (output instanceof Promise) {
+    output = output.then(result => {
+      heartbeat.finish()
+      return result
+    }) as typeof output
+  } else {
+    heartbeat.finish()
+  }
+
   return output
 }