automatic transitions via _enter() return values

Author: morungos

index.js

@@ -1,4 +1,4 @@
-export default function (state, states = {}) {
+export default function (initialState, states = {}) {
   /*
    * Core Finite State Machine functionality
    * - adheres to Svelte store contract (https://svelte.dev/docs#Store_contract)
@@ -8,6 +8,7 @@ export default function (state, states = {}) {
    */
   const subscribers = new Set();
   let proxy;
+  let state = null;
 
   function subscribe(callback) {
     if (typeof callback !== 'function') {
@@ -18,12 +19,43 @@ export default function (state, states = {}) {
     return () => subscribers.delete(callback);
   }
 
+  /*
+   * API change: subscribers are notified after _enter, not before, because eventless transitions
+   * might mean we settle in a new state. We may well transit through several states during the
+   * _enter() call. 
+   * 
+   * The logic here is intricate. The protocol is that there is always, internally, calls to 
+   * _exit() followed by _enter(), with the same to and from arguments. The initial _exit()
+   * and the final _enter() will use the public event. All calls will have the original event
+   * and args -- since we never know in advance whether an event is a final one. If _enter()
+   * returns a new state, we then generate a new _exit() and _enter, moving from the previous
+   * state to the new one, and repeat. If it does not, then that _enter is the final call.
+   */
   function transition(newState, event, args) {
-    const metadata = { from: state, to: newState, event, args };
-    dispatch('_exit', metadata);
-    state = newState;
-    subscribers.forEach((callback) => callback(state));
-    dispatch('_enter', metadata);
+    let metadata = { from: state, to: newState, event, args };
+    let startState = state;
+
+    // Never exit the null state
+    if (state !== null) {
+      dispatch('_exit', metadata);
+    }
+
+    while(true) {
+      state = metadata.to;
+      const nextState = dispatch('_enter', metadata);
+      if (! nextState) {
+        break;
+      }
+
+      metadata = { from: metadata.to, to: nextState, event, args }
+      dispatch('_exit', metadata);
+    }
+
+    // If (and only if) the final state is not the same as the initial state, then we 
+    // inform the subscribers
+    if (state !== startState) {
+      subscribers.forEach((callback) => callback(state));
+    }
   }
 
   function dispatch(event, ...args) {
@@ -78,8 +110,10 @@ export default function (state, states = {}) {
   });
 
   /*
-   * `_enter` initial state and return the proxy object
+   * `_enter` initial state and return the proxy object. Note that this may also
+   * involve eventless transitions to other states. Note, interestingly, that 
+   * we are free to notify here, because there will never be subscribers.
    */
-  dispatch('_enter', { from: null, to: state, event: null, args: [] });
+  transition(initialState, null, []);
   return proxy;
 }

test/units.js

@@ -142,11 +142,13 @@ describe('a finite state machine', () => {
       assert.throws(machine.arrowFunction, TypeError);
     });
 
+    // API change here. The notification callback will be called after
+    // _enter, not before
     it('should call lifecycle actions in proper sequence', () => {
       machine.toggle();
       assert.isTrue(states.off._enter.calledBefore(states.off._exit));
       assert.isTrue(states.off._exit.calledBefore(callback));
-      assert.isTrue(callback.calledBefore(states.on._enter));
+      assert.isTrue(states.on._enter.calledBefore(callback));
     });
 
     it('should call _enter with appropirate metadata when fsm is created', () => {
@@ -250,4 +252,64 @@ describe('a finite state machine', () => {
       assert.equal('off', state);
     });
   });
+
+
+  describe('automatic transitions', () => {
+    let callback;
+    let unsubscribe;
+
+    beforeEach(() => {
+      callback = sinon.fake();
+      unsubscribe = machine.subscribe(callback);
+      callback.resetHistory();
+    });
+
+    afterEach(() => {
+      unsubscribe();
+    });
+
+    it('should perform an automatic transition once', () => {
+      const enterOn = sinon.fake.returns('off')
+      sinon.replace(states.on, '_enter', enterOn);
+      machine.toggle();
+
+      const expected = {
+        from: 'off',
+        to: 'on',
+        event: 'toggle',
+        args: []
+      };
+
+      assert.equal(states.on._enter.callCount, 1);
+      assert.calledWithExactly(states.on._enter, expected);
+      assert.equal(states.off._enter.callCount, 2);
+
+      assert.notCalled(callback);
+    });
+
+    it('should perform an automatic transition multiple times', () => {
+      const enterOn = sinon.fake.returns('off')
+      sinon.replace(states.on, '_enter', enterOn);
+
+      machine.toggle();
+      machine.toggle();
+      machine.toggle();
+      machine.toggle();
+
+      assert.equal(states.on._enter.callCount, 4);
+
+      const expected = {
+        from: 'off',
+        to: 'on',
+        event: 'toggle',
+        args: []
+      };
+
+      assert.equal(states.on._enter.callCount, 4);
+      assert.calledWithExactly(states.on._enter, expected);
+      assert.equal(states.off._enter.callCount, 5);
+
+      assert.notCalled(callback);
+    })
+  });
 });