Merge pull request #170 from statelyai/davidkpiano/update-migration-guide-callbacks

Add changes to `fromCallback`

Author: davidkpiano

blog/2023-05-25-announcing-xstate-v5-beta/index.mdx

@@ -33,10 +33,10 @@ One of the biggest items of feedback we’ve received about XState is that altho
 - **From zero to “hello world” as quickly as possible**. Our goal with XState v5 and the [updated documentation (work in progress)](https://stately.ai/docs/xstate-v5) is to make developers productive with XState quickly. A simple, complete counter example in XState looks like this:
 
 ```ts
-import { createMachine, interpret, assign } from "xstate";
+import { createMachine, interpret, assign } from 'xstate';
 
 const counterMachine = createMachine({
-  id: "counter",
+  id: 'counter',
   context: {
     count: 0,
   },
@@ -54,9 +54,9 @@ const counterActor = interpret(counterMachine);
 counterActor.subscribe((state) => console.log(state.context.count));
 counterActor.start();
 
-counterActor.send({ type: "increment" }); // logs 1
-counterActor.send({ type: "increment" }); // logs 2
-counterActor.send({ type: "decrement" }); // logs 1
+counterActor.send({ type: 'increment' }); // logs 1
+counterActor.send({ type: 'increment' }); // logs 2
+counterActor.send({ type: 'decrement' }); // logs 1
 ```
 
 This functionality is already capable of meeting the majority of state management needs for most applications. If you require more advanced use cases, have no fear - XState v5 beta has got you covered.
@@ -74,44 +74,44 @@ import {
   fromEventObservable,
   fromCallback,
   createMachine,
-} from "xstate";
-import { interval, fromEvent } from "rxjs";
+} from 'xstate';
+import { interval, fromEvent } from 'rxjs';
 
 // Promise logic
-const promiseLogic = fromPromise(() => fetch("https://api.example.com/users"));
+const promiseLogic = fromPromise(() => fetch('https://api.example.com/users'));
 
 // Transition logic
 const transitionLogic = fromTransition(
   (state, event) => {
-    if (event.type === "increment") {
+    if (event.type === 'increment') {
       return { ...state, count: state.count + 1 };
-    } else if (event.type === "decrement") {
+    } else if (event.type === 'decrement') {
       return { ...state, count: state.count - 1 };
     }
 
     return state;
   },
-  { count: 0 }
+  { count: 0 },
 );
 
 // Observable logic
 const observableLogic = fromObservable(() => interval(1000));
 
 // Event observable logic
 const eventObservableLogic = fromEventObservable(() =>
-  fromEvent(window, "resize")
+  fromEvent(window, 'resize'),
 );
 
 // Callback logic
-const callbackLogic = fromCallback((sendBack) => {
+const callbackLogic = fromCallback(({ sendBack }) => {
   const handler = (ev) => {
     sendBack(ev);
   };
 
-  window.addEventListener("resize", handler);
+  window.addEventListener('resize', handler);
 
   return () => {
-    window.removeEventListener("resize", handler);
+    window.removeEventListener('resize', handler);
   };
 });
 
@@ -154,8 +154,8 @@ In the following example, the state of the `mainActor` will be persisted, as wel
 ```ts
 const machine = createMachine({
   invoke: {
-    src: "counter",
-    id: "someCounter",
+    src: 'counter',
+    id: 'someCounter',
   },
   // ...
 });
@@ -187,13 +187,13 @@ In XState v5 beta, calling `interpret(...)` to create a root actor will also cre
 For example, let’s say you have a `checkoutMachine` that orchestrates the state of an online shop. If you want a notifier actor to be available to any machines spawned anywhere within the `checkoutMachine` system, you can register it by providing a `systemId`:
 
 ```ts
-import { notifierMachine } from "../notifierMachine";
-import { shippingMachine } from "../shippingMachine";
+import { notifierMachine } from '../notifierMachine';
+import { shippingMachine } from '../shippingMachine';
 
 const checkoutMachine = createMachine({
   invoke: {
     src: notifierMachine,
-    systemId: "notifier",
+    systemId: 'notifier',
   },
   // ...
   states: {
@@ -216,10 +216,10 @@ Now, any actor within the `checkoutActor` system can access the notifier actor b
 const shippingMachine = createMachine({
   // ...
   on: {
-    "address.updated": {
-      actions: sendTo(({ system }) => system.get("notifier"), {
-        type: "notify",
-        message: "Shipping address updated",
+    'address.updated': {
+      actions: sendTo(({ system }) => system.get('notifier'), {
+        type: 'notify',
+        message: 'Shipping address updated',
       }),
     },
   },
@@ -248,7 +248,7 @@ const greetingMachine = createMachine({
 
 const greetingActor = interpret(greetingMachine, {
   input: {
-    name: "David",
+    name: 'David',
   },
 });
 ```
@@ -257,7 +257,7 @@ Furthermore, this works for any actor logic, not just state machines:
 
 ```ts
 const promiseLogic = fromPromise(({ input }) =>
-  fetch(`https://api.example.com/users/${input.id}`).then((res) => res.json())
+  fetch(`https://api.example.com/users/${input.id}`).then((res) => res.json()),
 );
 
 const promiseActor = interpret(promiseLogic, {
@@ -300,12 +300,12 @@ In the unified argument object, there is a `self` property that references the a
 ```ts
 const pingMachine = createMachine({
   invoke: {
-    src: "pong",
-    id: "pong",
+    src: 'pong',
+    id: 'pong',
   },
   on: {
     ping: {
-      actions: sendTo("pong", ({ self }) => ({ type: "ping", sender: self })),
+      actions: sendTo('pong', ({ self }) => ({ type: 'ping', sender: self })),
     },
   },
 });
@@ -315,7 +315,7 @@ const pingMachine = createMachine({
 const pongMachine = createMachine({
   on: {
     ping: {
-      actions: sendTo(({ event }) => event.sender, { type: "pong" }),
+      actions: sendTo(({ event }) => event.sender, { type: 'pong' }),
     },
   },
 });
@@ -326,7 +326,7 @@ const pongMachine = createMachine({
 In XState v4, guards were simple functions on the `.cond` transition property that returned `true` or `false` to determine if a transition would be taken. To negate a guard or combine guards, you had to create a new guard, which resulted in duplication or redundant code. In XState v5 beta, you can now use higher-order guards, which are functions that take in guards (referenced and/or inline) and return a guard function. There are 3 built-in higher-order guard functions: `and([...guards])`, `or([...guards])`, and `not(guard)`:
 
 ```ts
-import { createMachine, and, not } from "xstate";
+import { createMachine, and, not } from 'xstate';
 
 const userMachine = createMachine(
   {
@@ -335,17 +335,17 @@ const userMachine = createMachine(
       doSomething: {
         // Higher-order guard
         // Renamed from "cond" (v4) -> "guard" (v5)
-        guard: and(["isAuthenticated", "isAdmin", not("isBanned")]),
+        guard: and(['isAuthenticated', 'isAdmin', not('isBanned')]),
       },
     },
   },
   {
     guards: {
       isAuthenticated: ({ context }) => context.user !== undefined,
-      isAdmin: ({ context }) => context.user.role === "admin",
-      isBanned: ({ context }) => context.user.status === "banned",
+      isAdmin: ({ context }) => context.user.role === 'admin',
+      isBanned: ({ context }) => context.user.status === 'banned',
     },
-  }
+  },
 );
 ```
 
@@ -373,8 +373,8 @@ const machine = createMachine({
   on: {
     // Will handle any event that starts with "pointer.":
     // "pointer.down", "pointer.up", "pointer.move", etc.
-    "pointer.*": {
-      actions: "logPointerEvent",
+    'pointer.*': {
+      actions: 'logPointerEvent',
     },
   },
 });

versioned_docs/version-5/actors.mdx

@@ -322,13 +322,13 @@ canvasActor.start();
 
 ## Callback actors
 
-Callback actor logic is described by a callback function that receives a `sendBack` function and a `receive` function. Actors created from callback logic (“callback actors”) can:
+Callback actor logic is described by a callback function that receives a single object argument that includes a `sendBack(event)` function and a `receive(event => ...)` function. Actors created from callback logic (“callback actors”) can:
 
 - Receive events via the `receive` function
 - Send events to the parent actor via the `sendBack` function
 
 ```ts
-const callbackLogic = fromCallback((sendBack, receive) => {
+const callbackLogic = fromCallback(({ sendBack, receive }) => {
   let lockStatus = 'unlocked';
 
   const handler = (event) => {

versioned_docs/version-5/migration.mdx

@@ -769,7 +769,7 @@ import { fromCallback, createMachine } from 'xstate';
 
 const machine = createMachine({
   invoke: {
-    src: fromCallback((sendBack, receive, { input }) => {
+    src: fromCallback(({ sendBack, receive, input }) => {
       // ...
     }),
     input: ({ context, event }) => ({