@xstate/react 7.0.0-alpha.1 → 7.0.0-alpha.3

package/README.md

@@ -24,10 +24,10 @@ const toggleMachine = createMachine({
   initial: 'inactive',
   states: {
     inactive: {
-      on: { TOGGLE: 'active' }
+      on: { TOGGLE: { target: 'active' } }
     },
     active: {
-      on: { TOGGLE: 'inactive' }
+      on: { TOGGLE: { target: 'inactive' } }
     }
   }
 });
@@ -44,3 +44,9 @@ export const Toggler = () => {
   );
 };
 ```
+
+## Observing an actor
+
+<!-- observer lifecycle from src/useActorRef.ts -->
+
+Pass a snapshot listener or observer as the third argument to `useActorRef(logic, options, observer)`. It subscribes before the actor starts. When changing the machine configuration replaces the actor, the observer follows the replacement, even when the callback identity stays the same. Unmounting unsubscribes the observer and stops the actor.

package/dist/declarations/src/useActorRef.d.ts

@@ -4,6 +4,7 @@ export declare function useIdleActorRef<TLogic extends AnyActorLogic>(logic: TLo
         [K in RequiredActorOptionsKeys<TLogic>]: unknown;
     }
 ], IsNotNever<RequiredActorOptionsKeys<TLogic>>>): [Actor<TLogic>, (actorRef: Actor<TLogic>) => void];
+export declare function useActorLifecycle<TLogic extends AnyActorLogic>(actorRef: Actor<TLogic>, setActorRef: (actorRef: Actor<TLogic>) => void, createReplacement: () => Actor<TLogic>): void;
 export declare function useActorRef<TLogic extends AnyActorLogic>(machine: TLogic, ...[options, observerOrListener]: IsNotNever<RequiredActorOptionsKeys<TLogic>> extends true ? [
     options: ActorOptions<TLogic> & {
         [K in RequiredActorOptionsKeys<TLogic>]: unknown;

package/dist/xstate-react.cjs.js

@@ -48,40 +48,56 @@ function useIdleActorRef(logic, ...[options]) {
 
   // TODO: consider using `useAsapEffect` that would do this in `useInsertionEffect` is that's available
   useIsomorphicLayoutEffect__default["default"](() => {
-    actorRef.logic.implementations = logic.implementations;
+    actorRef.logic.sources = logic.sources;
   });
   return [actorRef, setActorRef];
 }
-function useActorRef(machine, ...[options, observerOrListener]) {
-  const [actorRef, setActorRef] = useIdleActorRef(machine, options);
+function useActorLifecycle(actorRef, setActorRef, createReplacement) {
+  const pendingStopsRef = React.useRef(new Map());
   React.useEffect(() => {
-    if (!observerOrListener) {
-      return;
+    const cancelPendingStop = pendingStopsRef.current.get(actorRef);
+    if (cancelPendingStop) {
+      cancelPendingStop();
+      pendingStopsRef.current.delete(actorRef);
     }
-    const sub = actorRef.subscribe(xstate.toObserver(observerOrListener));
-    return () => {
-      sub.unsubscribe();
-    };
-  }, [observerOrListener]);
-  React.useEffect(() => {
-    // If the actor was stopped by a previous cleanup (e.g. strict mode),
-    // create a fresh actor. The setActorRef triggers a re-render so
-    // useSyncExternalStore re-subscribes to the new actor.
-    // Only recreate if externally stopped ('stopped' status from XSTATE_STOP),
-    // not if it completed naturally ('done'/'error' status).
+
+    // If the actor was stopped before this effect reconnected, create a fresh
+    // actor. A stopped actor cannot be restarted.
     if (actorRef._processingStatus === 2 /* ProcessingStatus.Stopped */ && actorRef.getSnapshot()?.status === 'stopped') {
-      const newActor = xstate.createActor(machine, actorRef.options);
-      newActor.start();
+      const newActor = createReplacement();
       setActorRef(newActor);
-      // No cleanup — the re-render will run this effect again with the
-      // new actorRef (which is Running), registering the stop cleanup then.
       return;
     }
     actorRef.start();
     return () => {
-      actorRef.stop();
+      let canceled = false;
+      const cancel = () => {
+        canceled = true;
+      };
+      pendingStopsRef.current.set(actorRef, cancel);
+      queueMicrotask(() => {
+        if (!canceled) {
+          actorRef.stop();
+        }
+        if (pendingStopsRef.current.get(actorRef) === cancel) {
+          pendingStopsRef.current.delete(actorRef);
+        }
+      });
     };
   }, [actorRef]);
+}
+function useActorRef(machine, ...[options, observerOrListener]) {
+  const [actorRef, setActorRef] = useIdleActorRef(machine, options);
+  React.useEffect(() => {
+    if (!observerOrListener) {
+      return;
+    }
+    const sub = actorRef.subscribe(xstate.toObserver(observerOrListener));
+    return () => {
+      sub.unsubscribe();
+    };
+  }, [actorRef, observerOrListener]);
+  useActorLifecycle(actorRef, setActorRef, () => xstate.createActor(machine, actorRef.options));
   return actorRef;
 }
 
@@ -197,18 +213,7 @@ function useActor(logic, ...[options]) {
   if (snapshotWithStatus?.status === 'error') {
     throw snapshotWithStatus.error;
   }
-  React.useEffect(() => {
-    if (actorRef._processingStatus === 2 /* ProcessingStatus.Stopped */ && actorRef.getSnapshot()?.status === 'stopped') {
-      const newActor = xstate.createActor(logic, options);
-      newActor.start();
-      setActorRef(newActor);
-      return;
-    }
-    actorRef.start();
-    return () => {
-      actorRef.stop();
-    };
-  }, [actorRef]);
+  useActorLifecycle(actorRef, setActorRef, () => xstate.createActor(logic, options));
   return [actorSnapshot, actorRef.send, actorRef];
 }
 

package/dist/xstate-react.development.cjs.js

@@ -48,40 +48,56 @@ function useIdleActorRef(logic, ...[options]) {
 
   // TODO: consider using `useAsapEffect` that would do this in `useInsertionEffect` is that's available
   useIsomorphicLayoutEffect__default["default"](() => {
-    actorRef.logic.implementations = logic.implementations;
+    actorRef.logic.sources = logic.sources;
   });
   return [actorRef, setActorRef];
 }
-function useActorRef(machine, ...[options, observerOrListener]) {
-  const [actorRef, setActorRef] = useIdleActorRef(machine, options);
+function useActorLifecycle(actorRef, setActorRef, createReplacement) {
+  const pendingStopsRef = React.useRef(new Map());
   React.useEffect(() => {
-    if (!observerOrListener) {
-      return;
+    const cancelPendingStop = pendingStopsRef.current.get(actorRef);
+    if (cancelPendingStop) {
+      cancelPendingStop();
+      pendingStopsRef.current.delete(actorRef);
     }
-    const sub = actorRef.subscribe(xstate.toObserver(observerOrListener));
-    return () => {
-      sub.unsubscribe();
-    };
-  }, [observerOrListener]);
-  React.useEffect(() => {
-    // If the actor was stopped by a previous cleanup (e.g. strict mode),
-    // create a fresh actor. The setActorRef triggers a re-render so
-    // useSyncExternalStore re-subscribes to the new actor.
-    // Only recreate if externally stopped ('stopped' status from XSTATE_STOP),
-    // not if it completed naturally ('done'/'error' status).
+
+    // If the actor was stopped before this effect reconnected, create a fresh
+    // actor. A stopped actor cannot be restarted.
     if (actorRef._processingStatus === 2 /* ProcessingStatus.Stopped */ && actorRef.getSnapshot()?.status === 'stopped') {
-      const newActor = xstate.createActor(machine, actorRef.options);
-      newActor.start();
+      const newActor = createReplacement();
       setActorRef(newActor);
-      // No cleanup — the re-render will run this effect again with the
-      // new actorRef (which is Running), registering the stop cleanup then.
       return;
     }
     actorRef.start();
     return () => {
-      actorRef.stop();
+      let canceled = false;
+      const cancel = () => {
+        canceled = true;
+      };
+      pendingStopsRef.current.set(actorRef, cancel);
+      queueMicrotask(() => {
+        if (!canceled) {
+          actorRef.stop();
+        }
+        if (pendingStopsRef.current.get(actorRef) === cancel) {
+          pendingStopsRef.current.delete(actorRef);
+        }
+      });
     };
   }, [actorRef]);
+}
+function useActorRef(machine, ...[options, observerOrListener]) {
+  const [actorRef, setActorRef] = useIdleActorRef(machine, options);
+  React.useEffect(() => {
+    if (!observerOrListener) {
+      return;
+    }
+    const sub = actorRef.subscribe(xstate.toObserver(observerOrListener));
+    return () => {
+      sub.unsubscribe();
+    };
+  }, [actorRef, observerOrListener]);
+  useActorLifecycle(actorRef, setActorRef, () => xstate.createActor(machine, actorRef.options));
   return actorRef;
 }
 
@@ -200,18 +216,7 @@ function useActor(logic, ...[options]) {
   if (snapshotWithStatus?.status === 'error') {
     throw snapshotWithStatus.error;
   }
-  React.useEffect(() => {
-    if (actorRef._processingStatus === 2 /* ProcessingStatus.Stopped */ && actorRef.getSnapshot()?.status === 'stopped') {
-      const newActor = xstate.createActor(logic, options);
-      newActor.start();
-      setActorRef(newActor);
-      return;
-    }
-    actorRef.start();
-    return () => {
-      actorRef.stop();
-    };
-  }, [actorRef]);
+  useActorLifecycle(actorRef, setActorRef, () => xstate.createActor(logic, options));
   return [actorSnapshot, actorRef.send, actorRef];
 }
 

package/dist/xstate-react.development.esm.js

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { useEffect, useState, useCallback } from 'react';
+import { useEffect, useState, useRef, useCallback } from 'react';
 import useIsomorphicLayoutEffect from 'use-isomorphic-layout-effect';
 import { toObserver, createActor } from 'xstate';
 import { useSyncExternalStoreWithSelector } from 'use-sync-external-store/shim/with-selector';
@@ -22,40 +22,56 @@ function useIdleActorRef(logic, ...[options]) {
 
   // TODO: consider using `useAsapEffect` that would do this in `useInsertionEffect` is that's available
   useIsomorphicLayoutEffect(() => {
-    actorRef.logic.implementations = logic.implementations;
+    actorRef.logic.sources = logic.sources;
   });
   return [actorRef, setActorRef];
 }
-function useActorRef(machine, ...[options, observerOrListener]) {
-  const [actorRef, setActorRef] = useIdleActorRef(machine, options);
+function useActorLifecycle(actorRef, setActorRef, createReplacement) {
+  const pendingStopsRef = useRef(new Map());
   useEffect(() => {
-    if (!observerOrListener) {
-      return;
+    const cancelPendingStop = pendingStopsRef.current.get(actorRef);
+    if (cancelPendingStop) {
+      cancelPendingStop();
+      pendingStopsRef.current.delete(actorRef);
     }
-    const sub = actorRef.subscribe(toObserver(observerOrListener));
-    return () => {
-      sub.unsubscribe();
-    };
-  }, [observerOrListener]);
-  useEffect(() => {
-    // If the actor was stopped by a previous cleanup (e.g. strict mode),
-    // create a fresh actor. The setActorRef triggers a re-render so
-    // useSyncExternalStore re-subscribes to the new actor.
-    // Only recreate if externally stopped ('stopped' status from XSTATE_STOP),
-    // not if it completed naturally ('done'/'error' status).
+
+    // If the actor was stopped before this effect reconnected, create a fresh
+    // actor. A stopped actor cannot be restarted.
     if (actorRef._processingStatus === 2 /* ProcessingStatus.Stopped */ && actorRef.getSnapshot()?.status === 'stopped') {
-      const newActor = createActor(machine, actorRef.options);
-      newActor.start();
+      const newActor = createReplacement();
       setActorRef(newActor);
-      // No cleanup — the re-render will run this effect again with the
-      // new actorRef (which is Running), registering the stop cleanup then.
       return;
     }
     actorRef.start();
     return () => {
-      actorRef.stop();
+      let canceled = false;
+      const cancel = () => {
+        canceled = true;
+      };
+      pendingStopsRef.current.set(actorRef, cancel);
+      queueMicrotask(() => {
+        if (!canceled) {
+          actorRef.stop();
+        }
+        if (pendingStopsRef.current.get(actorRef) === cancel) {
+          pendingStopsRef.current.delete(actorRef);
+        }
+      });
     };
   }, [actorRef]);
+}
+function useActorRef(machine, ...[options, observerOrListener]) {
+  const [actorRef, setActorRef] = useIdleActorRef(machine, options);
+  useEffect(() => {
+    if (!observerOrListener) {
+      return;
+    }
+    const sub = actorRef.subscribe(toObserver(observerOrListener));
+    return () => {
+      sub.unsubscribe();
+    };
+  }, [actorRef, observerOrListener]);
+  useActorLifecycle(actorRef, setActorRef, () => createActor(machine, actorRef.options));
   return actorRef;
 }
 
@@ -174,18 +190,7 @@ function useActor(logic, ...[options]) {
   if (snapshotWithStatus?.status === 'error') {
     throw snapshotWithStatus.error;
   }
-  useEffect(() => {
-    if (actorRef._processingStatus === 2 /* ProcessingStatus.Stopped */ && actorRef.getSnapshot()?.status === 'stopped') {
-      const newActor = createActor(logic, options);
-      newActor.start();
-      setActorRef(newActor);
-      return;
-    }
-    actorRef.start();
-    return () => {
-      actorRef.stop();
-    };
-  }, [actorRef]);
+  useActorLifecycle(actorRef, setActorRef, () => createActor(logic, options));
   return [actorSnapshot, actorRef.send, actorRef];
 }
 

package/dist/xstate-react.esm.js

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { useEffect, useState, useCallback } from 'react';
+import { useEffect, useState, useRef, useCallback } from 'react';
 import useIsomorphicLayoutEffect from 'use-isomorphic-layout-effect';
 import { toObserver, createActor } from 'xstate';
 import { useSyncExternalStoreWithSelector } from 'use-sync-external-store/shim/with-selector';
@@ -22,40 +22,56 @@ function useIdleActorRef(logic, ...[options]) {
 
   // TODO: consider using `useAsapEffect` that would do this in `useInsertionEffect` is that's available
   useIsomorphicLayoutEffect(() => {
-    actorRef.logic.implementations = logic.implementations;
+    actorRef.logic.sources = logic.sources;
   });
   return [actorRef, setActorRef];
 }
-function useActorRef(machine, ...[options, observerOrListener]) {
-  const [actorRef, setActorRef] = useIdleActorRef(machine, options);
+function useActorLifecycle(actorRef, setActorRef, createReplacement) {
+  const pendingStopsRef = useRef(new Map());
   useEffect(() => {
-    if (!observerOrListener) {
-      return;
+    const cancelPendingStop = pendingStopsRef.current.get(actorRef);
+    if (cancelPendingStop) {
+      cancelPendingStop();
+      pendingStopsRef.current.delete(actorRef);
     }
-    const sub = actorRef.subscribe(toObserver(observerOrListener));
-    return () => {
-      sub.unsubscribe();
-    };
-  }, [observerOrListener]);
-  useEffect(() => {
-    // If the actor was stopped by a previous cleanup (e.g. strict mode),
-    // create a fresh actor. The setActorRef triggers a re-render so
-    // useSyncExternalStore re-subscribes to the new actor.
-    // Only recreate if externally stopped ('stopped' status from XSTATE_STOP),
-    // not if it completed naturally ('done'/'error' status).
+
+    // If the actor was stopped before this effect reconnected, create a fresh
+    // actor. A stopped actor cannot be restarted.
     if (actorRef._processingStatus === 2 /* ProcessingStatus.Stopped */ && actorRef.getSnapshot()?.status === 'stopped') {
-      const newActor = createActor(machine, actorRef.options);
-      newActor.start();
+      const newActor = createReplacement();
       setActorRef(newActor);
-      // No cleanup — the re-render will run this effect again with the
-      // new actorRef (which is Running), registering the stop cleanup then.
       return;
     }
     actorRef.start();
     return () => {
-      actorRef.stop();
+      let canceled = false;
+      const cancel = () => {
+        canceled = true;
+      };
+      pendingStopsRef.current.set(actorRef, cancel);
+      queueMicrotask(() => {
+        if (!canceled) {
+          actorRef.stop();
+        }
+        if (pendingStopsRef.current.get(actorRef) === cancel) {
+          pendingStopsRef.current.delete(actorRef);
+        }
+      });
     };
   }, [actorRef]);
+}
+function useActorRef(machine, ...[options, observerOrListener]) {
+  const [actorRef, setActorRef] = useIdleActorRef(machine, options);
+  useEffect(() => {
+    if (!observerOrListener) {
+      return;
+    }
+    const sub = actorRef.subscribe(toObserver(observerOrListener));
+    return () => {
+      sub.unsubscribe();
+    };
+  }, [actorRef, observerOrListener]);
+  useActorLifecycle(actorRef, setActorRef, () => createActor(machine, actorRef.options));
   return actorRef;
 }
 
@@ -171,18 +187,7 @@ function useActor(logic, ...[options]) {
   if (snapshotWithStatus?.status === 'error') {
     throw snapshotWithStatus.error;
   }
-  useEffect(() => {
-    if (actorRef._processingStatus === 2 /* ProcessingStatus.Stopped */ && actorRef.getSnapshot()?.status === 'stopped') {
-      const newActor = createActor(logic, options);
-      newActor.start();
-      setActorRef(newActor);
-      return;
-    }
-    actorRef.start();
-    return () => {
-      actorRef.stop();
-    };
-  }, [actorRef]);
+  useActorLifecycle(actorRef, setActorRef, () => createActor(logic, options));
   return [actorSnapshot, actorRef.send, actorRef];
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xstate/react",
-  "version": "7.0.0-alpha.1",
+  "version": "7.0.0-alpha.3",
   "description": "XState tools for React",
   "keywords": [
     "state",
@@ -54,7 +54,7 @@
   },
   "peerDependencies": {
     "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
-    "xstate": "^6.0.0-alpha.1"
+    "xstate": "^6.0.0-alpha.59"
   },
   "peerDependenciesMeta": {
     "xstate": {
@@ -74,7 +74,7 @@
     "react-dom": "^19.0.0",
     "rxjs": "^7.8.1",
     "zod": "^3.25.51",
-    "xstate": "^6.0.0-alpha.1"
+    "xstate": "^6.0.0-alpha.59"
   },
   "scripts": {}
 }