@xstate/react 7.0.0-alpha.2 → 7.0.0-alpha.4

package/README.md

@@ -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 the hook replaces the actor (after an external stop, or a Fast Refresh that cannot keep it), 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/useActor.d.ts

@@ -1,6 +1,4 @@
-import { Actor, ActorOptions, AnyActorLogic, SnapshotFrom, type ConditionalRequired, type IsNotNever, type RequiredActorOptionsKeys } from 'xstate';
+import { Actor, ActorOptions, AnyActorLogic, SnapshotFrom, type ConditionalRequired, type IsNotNever, type RequiredActorOptionsKeys, type RequiredActorOptionsFor } from 'xstate';
 export declare function useActor<TLogic extends AnyActorLogic>(logic: TLogic, ...[options]: ConditionalRequired<[
-    options?: ActorOptions<TLogic> & {
-        [K in RequiredActorOptionsKeys<TLogic>]: unknown;
-    }
+    options?: ActorOptions<TLogic> & RequiredActorOptionsFor<TLogic>
 ], IsNotNever<RequiredActorOptionsKeys<TLogic>>>): [SnapshotFrom<TLogic>, Actor<TLogic>['send'], Actor<TLogic>];

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

@@ -1,14 +1,10 @@
-import { Actor, ActorOptions, AnyActorLogic, Observer, SnapshotFrom, type ConditionalRequired, type IsNotNever, type RequiredActorOptionsKeys } from 'xstate';
+import { Actor, ActorOptions, AnyActorLogic, Observer, SnapshotFrom, type ConditionalRequired, type IsNotNever, type RequiredActorOptionsKeys, type RequiredActorOptionsFor } from 'xstate';
 export declare function useIdleActorRef<TLogic extends AnyActorLogic>(logic: TLogic, ...[options]: ConditionalRequired<[
-    options?: ActorOptions<TLogic> & {
-        [K in RequiredActorOptionsKeys<TLogic>]: unknown;
-    }
+    options?: ActorOptions<TLogic> & RequiredActorOptionsFor<TLogic>
 ], 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;
-    },
+    options: ActorOptions<TLogic> & RequiredActorOptionsFor<TLogic>,
     observerOrListener?: Observer<SnapshotFrom<TLogic>> | ((value: SnapshotFrom<TLogic>) => void)
 ] : [
     options?: ActorOptions<TLogic>,

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

@@ -1,7 +1,5 @@
-import { Actor, ActorOptions, AnyStateMachine, StateFrom, type ConditionalRequired, type IsNotNever, type RequiredActorOptionsKeys } from 'xstate';
+import { Actor, ActorOptions, AnyStateMachine, StateFrom, type ConditionalRequired, type IsNotNever, type RequiredActorOptionsKeys, type RequiredActorOptionsFor } from 'xstate';
 /** @alias useActor */
 export declare function useMachine<TMachine extends AnyStateMachine>(machine: TMachine, ...[options]: ConditionalRequired<[
-    options?: ActorOptions<TMachine> & {
-        [K in RequiredActorOptionsKeys<TMachine>]: unknown;
-    }
+    options?: ActorOptions<TMachine> & RequiredActorOptionsFor<TMachine>
 ], IsNotNever<RequiredActorOptionsKeys<TMachine>>>): [StateFrom<TMachine>, Actor<TMachine>['send'], Actor<TMachine>];

package/dist/xstate-react.cjs.js

@@ -32,23 +32,28 @@ var React__namespace = /*#__PURE__*/_interopNamespace(React);
 var useIsomorphicLayoutEffect__default = /*#__PURE__*/_interopDefault(useIsomorphicLayoutEffect);
 
 function useIdleActorRef(logic, ...[options]) {
-  let [actorRef, setActorRef] = React.useState(() => {
+  const [actorRef, setActorRef] = React.useState(() => {
     return xstate.createActor(logic, options);
   });
-  if (logic.config !== actorRef.logic.config) {
-    const newActorRef = xstate.createActor(logic, {
-      ...options,
-      snapshot: actorRef.getPersistedSnapshot({
-        __unsafeAllowInlineActors: true
-      })
-    });
-    setActorRef(newActorRef);
-    actorRef = newActorRef;
-  }
+  // An object whose identity changes only when React Fast Refresh re-renders
+  // this component. Fast Refresh ignores dependency lists while it applies an
+  // update, so a `useMemo` with no dependencies recomputes during a refresh
+  // and at no other time.
+  const refreshSignal = React.useMemo(() => ({}), []);
+  const refreshSignalRef = React.useRef(refreshSignal);
 
+  // The logic passed on the first render is used for the hook's lifetime.
+  // Later renders only contribute implementations provided with
+  // `machine.provide()` for the same machine config.
   // TODO: consider using `useAsapEffect` that would do this in `useInsertionEffect` is that's available
   useIsomorphicLayoutEffect__default["default"](() => {
-    actorRef.logic.sources = logic.sources;
+    const currentLogic = actorRef.logic;
+    refreshSignalRef.current !== refreshSignal;
+    refreshSignalRef.current = refreshSignal;
+    if (logic.config === currentLogic.config) {
+      currentLogic.sources = logic.sources;
+      return;
+    }
   });
   return [actorRef, setActorRef];
 }
@@ -65,7 +70,6 @@ function useActorLifecycle(actorRef, setActorRef, createReplacement) {
     // actor. A stopped actor cannot be restarted.
     if (actorRef._processingStatus === 2 /* ProcessingStatus.Stopped */ && actorRef.getSnapshot()?.status === 'stopped') {
       const newActor = createReplacement();
-      newActor.start();
       setActorRef(newActor);
       return;
     }
@@ -97,8 +101,8 @@ function useActorRef(machine, ...[options, observerOrListener]) {
     return () => {
       sub.unsubscribe();
     };
-  }, [observerOrListener]);
-  useActorLifecycle(actorRef, setActorRef, () => xstate.createActor(machine, actorRef.options));
+  }, [actorRef, observerOrListener]);
+  useActorLifecycle(actorRef, setActorRef, () => xstate.createActor(actorRef.logic, actorRef.options));
   return actorRef;
 }
 
@@ -214,7 +218,7 @@ function useActor(logic, ...[options]) {
   if (snapshotWithStatus?.status === 'error') {
     throw snapshotWithStatus.error;
   }
-  useActorLifecycle(actorRef, setActorRef, () => xstate.createActor(logic, options));
+  useActorLifecycle(actorRef, setActorRef, () => xstate.createActor(actorRef.logic, options));
   return [actorSnapshot, actorRef.send, actorRef];
 }
 

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

@@ -32,23 +32,37 @@ var React__namespace = /*#__PURE__*/_interopNamespace(React);
 var useIsomorphicLayoutEffect__default = /*#__PURE__*/_interopDefault(useIsomorphicLayoutEffect);
 
 function useIdleActorRef(logic, ...[options]) {
-  let [actorRef, setActorRef] = React.useState(() => {
+  const [actorRef, setActorRef] = React.useState(() => {
     return xstate.createActor(logic, options);
   });
-  if (logic.config !== actorRef.logic.config) {
-    const newActorRef = xstate.createActor(logic, {
-      ...options,
-      snapshot: actorRef.getPersistedSnapshot({
-        __unsafeAllowInlineActors: true
-      })
-    });
-    setActorRef(newActorRef);
-    actorRef = newActorRef;
-  }
+  // An object whose identity changes only when React Fast Refresh re-renders
+  // this component. Fast Refresh ignores dependency lists while it applies an
+  // update, so a `useMemo` with no dependencies recomputes during a refresh
+  // and at no other time.
+  const refreshSignal = React.useMemo(() => ({}), []);
+  const refreshSignalRef = React.useRef(refreshSignal);
 
+  // The logic passed on the first render is used for the hook's lifetime.
+  // Later renders only contribute implementations provided with
+  // `machine.provide()` for the same machine config.
   // TODO: consider using `useAsapEffect` that would do this in `useInsertionEffect` is that's available
   useIsomorphicLayoutEffect__default["default"](() => {
-    actorRef.logic.sources = logic.sources;
+    const currentLogic = actorRef.logic;
+    const refreshed = refreshSignalRef.current !== refreshSignal;
+    refreshSignalRef.current = refreshSignal;
+    if (logic.config === currentLogic.config) {
+      currentLogic.sources = logic.sources;
+      return;
+    }
+
+    // Development hot reloading: Fast Refresh re-evaluated the module that
+    // defines the machine. Keep the running actor and carry its live snapshot
+    // over to the new machine; start a fresh actor if it cannot be carried.
+    if (refreshed) {
+      if (!xstate._hotSwapActorLogic(actorRef, logic)) {
+        setActorRef(xstate.createActor(logic, options));
+      }
+    }
   });
   return [actorRef, setActorRef];
 }
@@ -65,7 +79,6 @@ function useActorLifecycle(actorRef, setActorRef, createReplacement) {
     // actor. A stopped actor cannot be restarted.
     if (actorRef._processingStatus === 2 /* ProcessingStatus.Stopped */ && actorRef.getSnapshot()?.status === 'stopped') {
       const newActor = createReplacement();
-      newActor.start();
       setActorRef(newActor);
       return;
     }
@@ -97,8 +110,8 @@ function useActorRef(machine, ...[options, observerOrListener]) {
     return () => {
       sub.unsubscribe();
     };
-  }, [observerOrListener]);
-  useActorLifecycle(actorRef, setActorRef, () => xstate.createActor(machine, actorRef.options));
+  }, [actorRef, observerOrListener]);
+  useActorLifecycle(actorRef, setActorRef, () => xstate.createActor(actorRef.logic, actorRef.options));
   return actorRef;
 }
 
@@ -217,7 +230,7 @@ function useActor(logic, ...[options]) {
   if (snapshotWithStatus?.status === 'error') {
     throw snapshotWithStatus.error;
   }
-  useActorLifecycle(actorRef, setActorRef, () => xstate.createActor(logic, options));
+  useActorLifecycle(actorRef, setActorRef, () => xstate.createActor(actorRef.logic, options));
   return [actorSnapshot, actorRef.send, actorRef];
 }
 

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

@@ -1,28 +1,42 @@
 import * as React from 'react';
-import { useEffect, useState, useRef, useCallback } from 'react';
+import { useEffect, useState, useMemo, useRef, useCallback } from 'react';
 import useIsomorphicLayoutEffect from 'use-isomorphic-layout-effect';
-import { toObserver, createActor } from 'xstate';
+import { toObserver, createActor, _hotSwapActorLogic } from 'xstate';
 import { useSyncExternalStoreWithSelector } from 'use-sync-external-store/shim/with-selector';
 import { useSyncExternalStore } from 'use-sync-external-store/shim';
 
 function useIdleActorRef(logic, ...[options]) {
-  let [actorRef, setActorRef] = useState(() => {
+  const [actorRef, setActorRef] = useState(() => {
     return createActor(logic, options);
   });
-  if (logic.config !== actorRef.logic.config) {
-    const newActorRef = createActor(logic, {
-      ...options,
-      snapshot: actorRef.getPersistedSnapshot({
-        __unsafeAllowInlineActors: true
-      })
-    });
-    setActorRef(newActorRef);
-    actorRef = newActorRef;
-  }
+  // An object whose identity changes only when React Fast Refresh re-renders
+  // this component. Fast Refresh ignores dependency lists while it applies an
+  // update, so a `useMemo` with no dependencies recomputes during a refresh
+  // and at no other time.
+  const refreshSignal = useMemo(() => ({}), []);
+  const refreshSignalRef = useRef(refreshSignal);
 
+  // The logic passed on the first render is used for the hook's lifetime.
+  // Later renders only contribute implementations provided with
+  // `machine.provide()` for the same machine config.
   // TODO: consider using `useAsapEffect` that would do this in `useInsertionEffect` is that's available
   useIsomorphicLayoutEffect(() => {
-    actorRef.logic.sources = logic.sources;
+    const currentLogic = actorRef.logic;
+    const refreshed = refreshSignalRef.current !== refreshSignal;
+    refreshSignalRef.current = refreshSignal;
+    if (logic.config === currentLogic.config) {
+      currentLogic.sources = logic.sources;
+      return;
+    }
+
+    // Development hot reloading: Fast Refresh re-evaluated the module that
+    // defines the machine. Keep the running actor and carry its live snapshot
+    // over to the new machine; start a fresh actor if it cannot be carried.
+    if (refreshed) {
+      if (!_hotSwapActorLogic(actorRef, logic)) {
+        setActorRef(createActor(logic, options));
+      }
+    }
   });
   return [actorRef, setActorRef];
 }
@@ -39,7 +53,6 @@ function useActorLifecycle(actorRef, setActorRef, createReplacement) {
     // actor. A stopped actor cannot be restarted.
     if (actorRef._processingStatus === 2 /* ProcessingStatus.Stopped */ && actorRef.getSnapshot()?.status === 'stopped') {
       const newActor = createReplacement();
-      newActor.start();
       setActorRef(newActor);
       return;
     }
@@ -71,8 +84,8 @@ function useActorRef(machine, ...[options, observerOrListener]) {
     return () => {
       sub.unsubscribe();
     };
-  }, [observerOrListener]);
-  useActorLifecycle(actorRef, setActorRef, () => createActor(machine, actorRef.options));
+  }, [actorRef, observerOrListener]);
+  useActorLifecycle(actorRef, setActorRef, () => createActor(actorRef.logic, actorRef.options));
   return actorRef;
 }
 
@@ -191,7 +204,7 @@ function useActor(logic, ...[options]) {
   if (snapshotWithStatus?.status === 'error') {
     throw snapshotWithStatus.error;
   }
-  useActorLifecycle(actorRef, setActorRef, () => createActor(logic, options));
+  useActorLifecycle(actorRef, setActorRef, () => createActor(actorRef.logic, options));
   return [actorSnapshot, actorRef.send, actorRef];
 }
 

package/dist/xstate-react.esm.js

@@ -1,28 +1,33 @@
 import * as React from 'react';
-import { useEffect, useState, useRef, useCallback } from 'react';
+import { useEffect, useState, useMemo, 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';
 import { useSyncExternalStore } from 'use-sync-external-store/shim';
 
 function useIdleActorRef(logic, ...[options]) {
-  let [actorRef, setActorRef] = useState(() => {
+  const [actorRef, setActorRef] = useState(() => {
     return createActor(logic, options);
   });
-  if (logic.config !== actorRef.logic.config) {
-    const newActorRef = createActor(logic, {
-      ...options,
-      snapshot: actorRef.getPersistedSnapshot({
-        __unsafeAllowInlineActors: true
-      })
-    });
-    setActorRef(newActorRef);
-    actorRef = newActorRef;
-  }
+  // An object whose identity changes only when React Fast Refresh re-renders
+  // this component. Fast Refresh ignores dependency lists while it applies an
+  // update, so a `useMemo` with no dependencies recomputes during a refresh
+  // and at no other time.
+  const refreshSignal = useMemo(() => ({}), []);
+  const refreshSignalRef = useRef(refreshSignal);
 
+  // The logic passed on the first render is used for the hook's lifetime.
+  // Later renders only contribute implementations provided with
+  // `machine.provide()` for the same machine config.
   // TODO: consider using `useAsapEffect` that would do this in `useInsertionEffect` is that's available
   useIsomorphicLayoutEffect(() => {
-    actorRef.logic.sources = logic.sources;
+    const currentLogic = actorRef.logic;
+    refreshSignalRef.current !== refreshSignal;
+    refreshSignalRef.current = refreshSignal;
+    if (logic.config === currentLogic.config) {
+      currentLogic.sources = logic.sources;
+      return;
+    }
   });
   return [actorRef, setActorRef];
 }
@@ -39,7 +44,6 @@ function useActorLifecycle(actorRef, setActorRef, createReplacement) {
     // actor. A stopped actor cannot be restarted.
     if (actorRef._processingStatus === 2 /* ProcessingStatus.Stopped */ && actorRef.getSnapshot()?.status === 'stopped') {
       const newActor = createReplacement();
-      newActor.start();
       setActorRef(newActor);
       return;
     }
@@ -71,8 +75,8 @@ function useActorRef(machine, ...[options, observerOrListener]) {
     return () => {
       sub.unsubscribe();
     };
-  }, [observerOrListener]);
-  useActorLifecycle(actorRef, setActorRef, () => createActor(machine, actorRef.options));
+  }, [actorRef, observerOrListener]);
+  useActorLifecycle(actorRef, setActorRef, () => createActor(actorRef.logic, actorRef.options));
   return actorRef;
 }
 
@@ -188,7 +192,7 @@ function useActor(logic, ...[options]) {
   if (snapshotWithStatus?.status === 'error') {
     throw snapshotWithStatus.error;
   }
-  useActorLifecycle(actorRef, setActorRef, () => createActor(logic, options));
+  useActorLifecycle(actorRef, setActorRef, () => createActor(actorRef.logic, options));
   return [actorSnapshot, actorRef.send, actorRef];
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xstate/react",
-  "version": "7.0.0-alpha.2",
+  "version": "7.0.0-alpha.4",
   "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.52"
+    "xstate": "^6.0.0-alpha.61"
   },
   "peerDependenciesMeta": {
     "xstate": {
@@ -74,7 +74,7 @@
     "react-dom": "^19.0.0",
     "rxjs": "^7.8.1",
     "zod": "^3.25.51",
-    "xstate": "^6.0.0-alpha.52"
+    "xstate": "^6.0.0-alpha.61"
   },
   "scripts": {}
 }