[v5] Rename external transitions to reentering ones (#3900)

* Rename external transitions to reentering ones and adjust semantics slightly * fixed the missed spot * tweak tests * bring back the inability to use reenter:false on parallel states transitions * add a changeset * fixed leftover instances of external property
statelyai · Apr 9, 2023 · 7d1a8ff · 7d1a8ff
1 parent 0b38a64
commit 7d1a8ff
Show file tree

Hide file tree

Showing 18 changed files with 98 additions and 43 deletions.
diff --git a/.changeset/cool-hairs-build.md b/.changeset/cool-hairs-build.md
@@ -0,0 +1,5 @@
+---
+'xstate': major
+---
+
+`external` property on transitions has been renamed to `reenter`
diff --git a/packages/core/src/StateNode.ts b/packages/core/src/StateNode.ts
@@ -220,7 +220,7 @@ export class StateNode<
             source: this,
             actions: this.initial.actions,
             eventType: null as any,
-            external: false,
+            reenter: false,
             toJSON: () => ({
               target: this.initial!.target!.map((t) => `#${t.id}`),
               source: `#${this.id}`,
@@ -451,7 +451,7 @@ export class StateNode<
           return !(
             !transition.target &&
             !transition.actions.length &&
-            !transition.external
+            !transition.reenter
           );
         })
         .map((transition) => transition.eventType)

diff --git a/packages/core/src/scxml.ts b/packages/core/src/scxml.ts
@@ -416,7 +416,7 @@ function toConfig(
           target: getTargets(targets),
           ...(value.elements ? executableContent(value.elements) : undefined),
           ...guardObject,
-          external: !internal
+          ...(!internal && { reenter: true })
         };
 
         if (eventType === NULL_EVENT) {

diff --git a/packages/core/src/stateUtils.ts b/packages/core/src/stateUtils.ts
@@ -360,7 +360,7 @@ export function formatTransition<
   }
 ): AnyTransitionDefinition {
   const normalizedTarget = normalizeTarget(transitionConfig.target);
-  const external = transitionConfig.external ?? false;
+  const reenter = transitionConfig.reenter ?? false;
   const { guards } = stateNode.machine.options;
   const target = resolveTarget(stateNode, normalizedTarget);
 
@@ -381,7 +381,7 @@ export function formatTransition<
       : undefined,
     target,
     source: stateNode,
-    external,
+    reenter,
     eventType: transitionConfig.event,
     toJSON: () => ({
       ...transition,
@@ -524,7 +524,7 @@ export function formatInitialTransition<
       source: stateNode,
       actions: [],
       eventType: null as any,
-      external: false,
+      reenter: false,
       target: resolvedTarget!,
       toJSON: () => ({
         ...transition,
@@ -990,8 +990,8 @@ function getTransitionDomain(
   }
 
   if (
-    !transition.external &&
-    transition.source.type === 'compound' &&
+    !transition.reenter &&
+    transition.source.type !== 'parallel' &&
     targetStates.every((targetStateNode) =>
       isDescendant(targetStateNode, transition.source)
     )
@@ -1069,7 +1069,7 @@ export function microstep<
           {
             target: [...currentState.configuration].filter(isAtomicStateNode),
             source: machine.root,
-            external: true,
+            reenter: true,
             actions: [],
             eventType: null as any,
             toJSON: null as any // TODO: fix

diff --git a/packages/core/src/types.ts b/packages/core/src/types.ts
@@ -319,7 +319,7 @@ export interface TransitionConfig<
 > {
   guard?: GuardConfig<TContext, TExpressionEvent>;
   actions?: BaseActions<TContext, TExpressionEvent, TEvent, TAction>;
-  external?: boolean;
+  reenter?: boolean;
   target?: TransitionTarget | undefined;
   meta?: Record<string, any>;
   description?: string;
@@ -1437,7 +1437,7 @@ export interface TransitionDefinition<
   target: Array<StateNode<TContext, TEvent>> | undefined;
   source: StateNode<TContext, TEvent>;
   actions: BaseActionObject[];
-  external: boolean;
+  reenter: boolean;
   guard?: GuardDefinition<TContext, TEvent>;
   eventType: TEvent['type'] | '*';
   toJSON: () => {

diff --git a/packages/core/test/actions.test.ts b/packages/core/test/actions.test.ts
@@ -231,7 +231,7 @@ describe('entry/exit actions', () => {
             on: {
               RESTART: {
                 target: 'green',
-                external: true
+                reenter: true
               }
             }
           }
@@ -256,7 +256,7 @@ describe('entry/exit actions', () => {
             on: {
               RESTART: {
                 target: 'green',
-                external: true
+                reenter: true
               }
             },
             initial: 'walk',
@@ -599,7 +599,7 @@ describe('entry/exit actions', () => {
       expect(called).toBe(true);
     });
 
-    it('root entry/exit actions should be called on root external transitions', () => {
+    it('root entry/exit actions should be called on root reentering transitions', () => {
       let entrySpy = jest.fn();
       let exitSpy = jest.fn();
 
@@ -610,7 +610,7 @@ describe('entry/exit actions', () => {
         on: {
           EVENT: {
             target: '#two',
-            external: true
+            reenter: true
           }
         },
         initial: 'one',
@@ -858,7 +858,7 @@ describe('entry/exit actions', () => {
             on: {
               RESTART: {
                 target: 'green',
-                external: true
+                reenter: true
               }
             },
             initial: 'walk',
@@ -966,15 +966,15 @@ describe('entry/exit actions', () => {
       ]);
     });
 
-    it('should enter all descendents when target is a descendent of the source when using an external transition', () => {
+    it('should enter all descendents when target is a descendent of the source when using an reentering transition', () => {
       const machine = createMachine({
         initial: 'A',
         states: {
           A: {
             initial: 'A1',
             on: {
               NEXT: {
-                external: true,
+                reenter: true,
                 target: '.A2'
               }
             },
@@ -1194,7 +1194,57 @@ describe('entry/exit actions', () => {
           ready: {
             type: 'parallel',
             on: {
-              FOO: '#cameraOff'
+              FOO: {
+                target: '#cameraOff',
+                reenter: true
+              }
+            },
+            states: {
+              devicesInfo: {},
+              camera: {
+                initial: 'on',
+                states: {
+                  on: {},
+                  off: {
+                    id: 'cameraOff'
+                  }
+                }
+              }
+            }
+          }
+        }
+      });
+
+      const flushTracked = trackEntries(machine);
+
+      const service = interpret(machine).start();
+
+      flushTracked();
+      service.send({ type: 'FOO' });
+
+      expect(flushTracked()).toEqual([
+        'exit: ready.camera.on',
+        'exit: ready.camera',
+        'exit: ready.devicesInfo',
+        'exit: ready',
+        'enter: ready',
+        'enter: ready.devicesInfo',
+        'enter: ready.camera',
+        'enter: ready.camera.off'
+      ]);
+    });
+
+    it('should reenter parallel region when a parallel state is reentered while targeting another region', () => {
+      const machine = createMachine({
+        initial: 'ready',
+        states: {
+          ready: {
+            type: 'parallel',
+            on: {
+              FOO: {
+                target: '#cameraOff',
+                reenter: true
+              }
             },
             states: {
               devicesInfo: {},

diff --git a/packages/core/test/activities.test.ts b/packages/core/test/activities.test.ts
@@ -357,7 +357,7 @@ describe('invocations (activities)', () => {
     expect(actual).toEqual(['start 0', 'stop 0', 'start 1']);
   });
 
-  it('should start a new actor when reentering the invoking state during an external self transition', () => {
+  it('should start a new actor when reentering the invoking state during a reentering self transition', () => {
     let counter = 0;
     const actual: string[] = [];
     const machine = createMachine(
@@ -371,7 +371,7 @@ describe('invocations (activities)', () => {
             on: {
               NEXT: {
                 target: 'a',
-                external: true
+                reenter: true
               }
             }
           }

diff --git a/packages/core/test/history.test.ts b/packages/core/test/history.test.ts
@@ -122,7 +122,7 @@ describe('history states', () => {
     expect(service.getSnapshot().value).toEqual({ idle: 'absent' });
   });
 
-  it('should reenter persisted state during external transition targeting a history state', () => {
+  it('should reenter persisted state during reentering transition targeting a history state', () => {
     const actual: string[] = [];
 
     const machine = createMachine({
@@ -132,7 +132,7 @@ describe('history states', () => {
           on: {
             REENTER: {
               target: '#b_hist',
-              external: true
+              reenter: true
             }
           },
           initial: 'a1',

diff --git a/packages/core/test/internalTransitions.test.ts b/packages/core/test/internalTransitions.test.ts
@@ -44,7 +44,7 @@ describe('internal transitions', () => {
           on: {
             NEXT: {
               target: '.right',
-              external: true
+              reenter: true
             }
           }
         }
@@ -85,7 +85,7 @@ describe('internal transitions', () => {
           on: {
             RESET: {
               target: 'foo',
-              external: true
+              reenter: true
             }
           }
         }
@@ -125,7 +125,7 @@ describe('internal transitions', () => {
           on: {
             RESET_TO_B: {
               target: 'foo.b',
-              external: true
+              reenter: true
             }
           }
         }

diff --git a/packages/core/test/invoke.test.ts b/packages/core/test/invoke.test.ts
@@ -3053,7 +3053,7 @@ describe('invoke', () => {
     expect(disposed).toBe(true);
   });
 
-  it('root invocations should restart on root external transitions', () => {
+  it('root invocations should restart on root reentering transitions', () => {
     let count = 0;
 
     const machine = createMachine({
@@ -3067,7 +3067,7 @@ describe('invoke', () => {
       on: {
         EVENT: {
           target: '#two',
-          external: true
+          reenter: true
         }
       },
       initial: 'one',

diff --git a/packages/core/test/json.test.ts b/packages/core/test/json.test.ts
@@ -145,8 +145,8 @@ describe('json', () => {
           "actions": [],
           "event": "done.invoke.active:invocation[0]",
           "eventType": "done.invoke.active:invocation[0]",
-          "external": false,
           "guard": undefined,
+          "reenter": false,
           "source": "#active",
           "target": [
             "#(machine).foo",
@@ -157,8 +157,8 @@ describe('json', () => {
           "actions": [],
           "event": "error.platform.active:invocation[0]",
           "eventType": "error.platform.active:invocation[0]",
-          "external": false,
           "guard": undefined,
+          "reenter": false,
           "source": "#active",
           "target": [
             "#(machine).bar",
@@ -169,8 +169,8 @@ describe('json', () => {
           "actions": [],
           "event": "EVENT",
           "eventType": "EVENT",
-          "external": false,
           "guard": undefined,
+          "reenter": false,
           "source": "#active",
           "target": [
             "#(machine).foo",

diff --git a/packages/core/test/parallel.test.ts b/packages/core/test/parallel.test.ts
@@ -893,7 +893,7 @@ describe('parallel states', () => {
     });
 
     // https://github.com/statelyai/xstate/issues/531
-    it('should calculate the entry set for external transitions in parallel states', () => {
+    it('should calculate the entry set for reentering transitions in parallel states', () => {
       const testMachine = createMachine<{ log: string[] }>({
         id: 'test',
         context: { log: [] },

diff --git a/packages/core/test/predictableExec.test.ts b/packages/core/test/predictableExec.test.ts
@@ -515,7 +515,7 @@ describe('predictableExec', () => {
           on: {
             REENTER: {
               target: 'active',
-              external: true
+              reenter: true
             }
           }
         }

diff --git a/packages/core/test/scxml.test.ts b/packages/core/test/scxml.test.ts
@@ -306,7 +306,7 @@ const testGroups: Record<string, string[]> = {
     // 'test530.txml', // https://github.com/davidkpiano/xstate/pull/1811#discussion_r551897693
     // 'test531.txml', // Basic HTTP Event I/O processor not implemented
     // 'test532.txml', // Basic HTTP Event I/O processor not implemented
-    'test533.txml',
+    // 'test533.txml', // we allow `reenter: false` to not leave the source state even if that source state is not compound
     // 'test534.txml', // Basic HTTP Event I/O processor not implemented
     // 'test550.txml', // non-root datamodel with early binding not implemented yet
     // 'test551.txml', // non-root datamodel with early binding not implemented yet