Merge pull request #248 from audionerd/api-docs-fromCallback-promises-and-error-handling

Actors: add Promise example to `fromCallback`

Author: davidkpiano

docs/actors.mdx

@@ -410,6 +410,40 @@ Callback actors are a bit different from other actors in that they do not do the
 - Do not emit values when used with `.subscribe()`
 - Can not be stopped with `.stop()`
 
+You may choose to use `sendBack` to report caught errors to the parent actor. This is especially helpful for handling promise rejections within a callback function, which will not be caught by [`onError`](invoke.mdx#onerror).
+
+Callback functions cannot be `async` functions. But it is possible to execute a Promise within a callback function.
+
+```ts
+const machine = createMachine({
+  initial: 'running',
+  states: {
+    running: {
+      invoke: {
+        src: fromCallback(({ sendBack }) => {
+          // highlight-start
+          somePromise()
+            .then((data) => sendBack({ type: 'done', data }))
+            .catch((error) => sendBack({ type: 'error', data: error }));
+          // highlight-end
+
+          return () => {
+            /* cleanup function */
+          };
+        })
+      },
+      // highlight-start
+      on: {
+        error: {
+          actions: ({ event }) => console.error(event.data)
+        }
+      }
+      // highlight-end
+    }
+  }
+});
+```
+
 ## Higher-level actor logic
 
 Higher-level actor logic enhances existing actor logic with additional functionality. For example, you can create actor logic that logs or persists actor state: