xstate 3.2.1 → 3.3.3

package/lib/StateNode.js

@@ -17,65 +17,15 @@ var HISTORY_KEY = '$history';
 var NULL_EVENT = '';
 var STATE_IDENTIFIER = '#';
 var isStateId = function (str) { return str[0] === STATE_IDENTIFIER; };
-var emptyActions = Object.freeze({
-    onEntry: [],
-    onExit: [],
-    actions: []
-});
-/**
- * Given a StateNode, walk up the parent chain until we find an
- * orthogonal region of a parallel state, or the top level machine
- * itself
- */
-var regionOf = function (node) {
-    // If we reach the top of the state machine, we're a "region".
-    // If our parent is a parallel state, we're a region.
-    while (node.parent && !node.parent.parallel) {
-        node = node.parent;
-    }
-    return node;
-};
-/**
- * Ensure that the passed in StateNode instance belongs to a region
- * that previously had not been used, or that matches the existing
- * StateNode for the orthogonal regions.  This function is used to
- * verify that a transition that has multiple targets ends doesn't try
- * to target several states in the same orthogonal region.  The passed
- * state is added to the regions data structure using the state's
- * _region_ (see regionOf), and the region's parent.  If there is
- * already an object in the structure which is not already the state
- * in question, an Error is thrown, otherwise the state is added to
- * the structure, and the _region_ is returned.
- *
- * @param sourceState the state in which the event was triggered (used
- * to report error messages)
- * @param event the event that triggered the transition (used to
- * report error messages)
- * @param regions A data structure that retains the current set of
- * orthogonal regions (their IDs), grouped by their parallel state
- * (their IDs), with the values being the chosen states
- * @param state A state to add to the structure if possible.
- * @returns The region of the state, in order for the caller to repeat the process for the parent.
- * @throws Error if the region found already exists in the regions
- */
-var ensureTargetStateIsInCorrectRegion = function (sourceState, event, regions, stateToCheck) {
-    var region = regionOf(stateToCheck);
-    var parent = region.parent;
-    var parentId = parent ? parent.id : ''; // '' == machine
-    regions[parentId] = regions[parentId] || {};
-    if (regions[parentId][region.id] &&
-        regions[parentId][region.id] !== stateToCheck) {
-        throw new Error("Event '" + event + "' on state '" + sourceState.id + "' leads to an invalid configuration: " +
-            ("Two or more states in the orthogonal region '" + region.id + "'."));
-    }
-    // Keep track of which state was chosen in a particular region.
-    regions[parentId][region.id] = stateToCheck;
-    return region;
+var defaultOptions = {
+    guards: {}
 };
 var StateNode = /** @class */ (function () {
-    function StateNode(config) {
+    function StateNode(config, options) {
+        if (options === void 0) { options = defaultOptions; }
         var _this = this;
         this.config = config;
+        this.options = options;
         this.__cache = {
             events: undefined,
             relativeValue: new Map(),
@@ -98,25 +48,31 @@ var StateNode = /** @class */ (function () {
         this.parallel = !!config.parallel;
         this.states = (config.states
             ? utils_1.mapValues(config.states, function (stateConfig, key) {
+                var _a;
                 var stateNode = new StateNode(__assign({}, stateConfig, { key: key, parent: _this }));
                 Object.assign(_this.idMap, __assign((_a = {}, _a[stateNode.id] = stateNode, _a), stateNode.idMap));
                 return stateNode;
-                var _a;
             })
             : {});
+        // History config
+        this.history =
+            config.history === true ? 'shallow' : config.history || false;
         this.on = config.on ? this.formatTransitions(config.on) : {};
+        this.transient = !!this.on[NULL_EVENT];
         this.strict = !!config.strict;
         this.onEntry = config.onEntry
             ? [].concat(config.onEntry)
-            : undefined;
-        this.onExit = config.onExit
-            ? [].concat(config.onExit)
-            : undefined;
+            : [];
+        this.onExit = config.onExit ? [].concat(config.onExit) : [];
         this.data = config.data;
         this.activities = config.activities;
     }
     StateNode.prototype.getStateNodes = function (state) {
         var _this = this;
+        var _a;
+        if (!state) {
+            return [];
+        }
         var stateValue = state instanceof State_1.State
             ? state.value
             : utils_1.toStateValue(state, this.delimiter);
@@ -134,86 +90,406 @@ var StateNode = /** @class */ (function () {
             var subStateNode = _this.getStateNode(subStateKey).getStateNodes(stateValue[subStateKey]);
             return allSubStateNodes.concat(subStateNode);
         }, []));
-        var _a;
     };
     StateNode.prototype.handles = function (event) {
         var eventType = utils_1.getEventType(event);
         return this.events.indexOf(eventType) !== -1;
     };
+    StateNode.prototype._transitionLeafNode = function (stateValue, state, event, extendedState) {
+        var stateNode = this.getStateNode(stateValue);
+        var next = stateNode._next(state, event, extendedState);
+        if (!next.value) {
+            var _a = this._next(state, event, extendedState), value = _a.value, entryExitStates = _a.entryExitStates, actions = _a.actions, paths = _a.paths;
+            return {
+                value: value,
+                entryExitStates: {
+                    entry: entryExitStates ? entryExitStates.entry : new Set(),
+                    exit: new Set([
+                        stateNode
+                    ].concat((entryExitStates
+                        ? Array.from(entryExitStates.exit)
+                        : [])))
+                },
+                actions: actions,
+                paths: paths
+            };
+        }
+        return next;
+    };
+    StateNode.prototype._transitionHierarchicalNode = function (stateValue, state, event, extendedState) {
+        var subStateKeys = Object.keys(stateValue);
+        var stateNode = this.getStateNode(subStateKeys[0]);
+        var next = stateNode._transition(stateValue[subStateKeys[0]], state, event, extendedState);
+        if (!next.value) {
+            var _a = this._next(state, event, extendedState), value = _a.value, entryExitStates = _a.entryExitStates, actions = _a.actions, paths = _a.paths;
+            return {
+                value: value,
+                entryExitStates: {
+                    entry: entryExitStates ? entryExitStates.entry : new Set(),
+                    exit: new Set((next.entryExitStates
+                        ? Array.from(next.entryExitStates.exit)
+                        : []).concat([
+                        stateNode
+                    ], (entryExitStates
+                        ? Array.from(entryExitStates.exit)
+                        : [])))
+                },
+                actions: actions,
+                paths: paths
+            };
+        }
+        return next;
+    };
+    StateNode.prototype._transitionOrthogonalNode = function (stateValue, state, event, extendedState) {
+        var _this = this;
+        var noTransitionKeys = [];
+        var transitionMap = {};
+        Object.keys(stateValue).forEach(function (subStateKey) {
+            var subStateValue = stateValue[subStateKey];
+            if (!subStateValue) {
+                return;
+            }
+            var next = _this.getStateNode(subStateKey)._transition(subStateValue, state, event, extendedState);
+            if (!next.value) {
+                noTransitionKeys.push(subStateKey);
+            }
+            transitionMap[subStateKey] = next;
+        });
+        var willTransition = Object.keys(transitionMap).some(function (key) { return transitionMap[key].value !== undefined; });
+        if (!willTransition) {
+            var _a = this._next(state, event, extendedState), value = _a.value, entryExitStates = _a.entryExitStates, actions = _a.actions, paths = _a.paths;
+            return {
+                value: value,
+                entryExitStates: {
+                    entry: entryExitStates ? entryExitStates.entry : new Set(),
+                    exit: new Set(Object.keys(this.states).map(function (key) { return _this.states[key]; }).concat((entryExitStates ? Array.from(entryExitStates.exit) : [])))
+                },
+                actions: actions,
+                paths: paths
+            };
+        }
+        var allPaths = utils_1.flatMap(Object.keys(transitionMap).map(function (key) { return transitionMap[key].paths; }));
+        // External transition that escapes orthogonal region
+        if (allPaths.length === 1 &&
+            !matchesState_1.matchesState(utils_1.pathToStateValue(this.path), utils_1.pathToStateValue(allPaths[0]))) {
+            return {
+                value: this.machine.resolve(utils_1.pathsToStateValue(allPaths)),
+                entryExitStates: Object.keys(transitionMap)
+                    .map(function (key) { return transitionMap[key].entryExitStates; })
+                    .reduce(function (allEntryExitStates, entryExitStates) {
+                    var _a = entryExitStates, entry = _a.entry, exit = _a.exit;
+                    return {
+                        entry: new Set(Array.from(allEntryExitStates.entry).concat(Array.from(entry))),
+                        exit: new Set(Array.from(allEntryExitStates.exit).concat(Array.from(exit)))
+                    };
+                }, { entry: new Set(), exit: new Set() }),
+                actions: utils_1.flatMap(Object.keys(transitionMap).map(function (key) {
+                    return transitionMap[key].actions;
+                })),
+                paths: allPaths
+            };
+        }
+        var allResolvedPaths = utils_1.flatMap(Object.keys(transitionMap).map(function (key) {
+            var transition = transitionMap[key];
+            var value = transition.value || state.value;
+            return utils_1.toStatePaths(utils_1.path(_this.path)(value)[key]).map(function (statePath) {
+                return _this.path.concat(key, statePath);
+            });
+        }));
+        var nextStateValue = this.machine.resolve(utils_1.pathsToStateValue(allResolvedPaths));
+        return {
+            value: nextStateValue,
+            entryExitStates: Object.keys(transitionMap).reduce(function (allEntryExitStates, key) {
+                var _a = transitionMap[key], subStateValue = _a.value, entryExitStates = _a.entryExitStates;
+                // If the event was not handled (no subStateValue),
+                // machine should still be in state without reentry/exit.
+                if (!subStateValue || !entryExitStates) {
+                    return allEntryExitStates;
+                }
+                var entry = entryExitStates.entry, exit = entryExitStates.exit;
+                return {
+                    entry: new Set(Array.from(allEntryExitStates.entry).concat(Array.from(entry))),
+                    exit: new Set(Array.from(allEntryExitStates.exit).concat(Array.from(exit)))
+                };
+            }, { entry: new Set(), exit: new Set() }),
+            actions: utils_1.flatMap(Object.keys(transitionMap).map(function (key) {
+                return transitionMap[key].actions;
+            })),
+            paths: utils_1.toStatePaths(nextStateValue)
+        };
+    };
+    StateNode.prototype._transition = function (stateValue, state, event, extendedState) {
+        // leaf node
+        if (typeof stateValue === 'string') {
+            return this._transitionLeafNode(stateValue, state, event, extendedState);
+        }
+        // hierarchical node
+        if (Object.keys(stateValue).length === 1) {
+            return this._transitionHierarchicalNode(stateValue, state, event, extendedState);
+        }
+        // orthogonal node
+        return this._transitionOrthogonalNode(stateValue, state, event, extendedState);
+    };
+    StateNode.prototype._next = function (state, event, extendedState) {
+        var _this = this;
+        var eventType = utils_1.getEventType(event);
+        var candidates = this.on[eventType];
+        var actions = this.transient
+            ? [{ type: actions_1.actionTypes.null }]
+            : [];
+        if (!candidates || !candidates.length) {
+            return {
+                value: undefined,
+                entryExitStates: undefined,
+                actions: actions,
+                paths: []
+            };
+        }
+        var nextStateStrings = [];
+        var selectedTransition;
+        for (var _i = 0, candidates_1 = candidates; _i < candidates_1.length; _i++) {
+            var candidate = candidates_1[_i];
+            var _a = candidate, cond = _a.cond, stateIn = _a.in
+            // actions: transitionActions
+            ;
+            var extendedStateObject = extendedState || {};
+            var eventObject = actions_1.toEventObject(event);
+            var isInState = stateIn
+                ? matchesState_1.matchesState(utils_1.toStateValue(stateIn, this.delimiter), utils_1.path(this.path.slice(0, -2))(state.value))
+                : true;
+            if ((!cond ||
+                this._evaluateCond(cond, extendedStateObject, eventObject, state.value)) &&
+                (!stateIn || isInState)) {
+                nextStateStrings = Array.isArray(candidate.target)
+                    ? candidate.target
+                    : [candidate.target];
+                actions.push.apply(actions, (candidate.actions ? candidate.actions : [])); // TODO: fixme;
+                selectedTransition = candidate;
+                break;
+            }
+        }
+        if (nextStateStrings.length === 0) {
+            return {
+                value: undefined,
+                entryExitStates: undefined,
+                actions: actions,
+                paths: []
+            };
+        }
+        var nextStateNodes = utils_1.flatMap(nextStateStrings.map(function (str) {
+            return _this.getRelativeStateNodes(str, state.historyValue);
+        }));
+        var nextStatePaths = nextStateNodes.map(function (stateNode) { return stateNode.path; });
+        var entryExitStates = nextStateNodes.reduce(function (allEntryExitStates, nextStateNode) {
+            var _a = _this._getEntryExitStates(nextStateNode, !!selectedTransition.internal), entry = _a.entry, exit = _a.exit;
+            return {
+                entry: new Set(Array.from(allEntryExitStates.entry).concat(Array.from(entry))),
+                exit: new Set(Array.from(allEntryExitStates.exit).concat(Array.from(exit)))
+            };
+        }, { entry: new Set(), exit: new Set() });
+        return {
+            value: this.machine.resolve(utils_1.pathsToStateValue(utils_1.flatMap(nextStateStrings.map(function (str) {
+                return _this.getRelativeStateNodes(str, state.historyValue).map(function (s) { return s.path; });
+            })))),
+            entryExitStates: entryExitStates,
+            actions: actions,
+            paths: nextStatePaths
+        };
+    };
+    StateNode.prototype._getEntryExitStates = function (nextStateNode, internal) {
+        var entryExitStates = {
+            entry: [],
+            exit: []
+        };
+        var fromPath = this.path;
+        var toPath = nextStateNode.path;
+        var parent = this.machine;
+        for (var i = 0; i < Math.min(fromPath.length, toPath.length); i++) {
+            var fromPathSegment = fromPath[i];
+            var toPathSegment = toPath[i];
+            if (fromPathSegment === toPathSegment) {
+                parent = parent.getStateNode(fromPathSegment);
+            }
+            else {
+                break;
+            }
+        }
+        var commonAncestorPath = parent.path;
+        var marker = parent;
+        for (var _i = 0, _a = fromPath.slice(commonAncestorPath.length); _i < _a.length; _i++) {
+            var segment = _a[_i];
+            marker = marker.getStateNode(segment);
+            entryExitStates.exit.unshift(marker);
+        }
+        // Child node
+        if (parent === this) {
+            if (!internal) {
+                entryExitStates.exit.push(this);
+                entryExitStates.entry.push(this);
+            }
+        }
+        marker = parent;
+        for (var _b = 0, _c = toPath.slice(commonAncestorPath.length); _b < _c.length; _b++) {
+            var segment = _c[_b];
+            marker = marker.getStateNode(segment);
+            entryExitStates.entry.push(marker);
+        }
+        return {
+            entry: new Set(entryExitStates.entry),
+            exit: new Set(entryExitStates.exit)
+        };
+    };
+    StateNode.prototype._evaluateCond = function (condition, extendedState, eventObject, interimState) {
+        var condFn;
+        if (typeof condition === 'string') {
+            if (!this.machine.options.guards[condition]) {
+                throw new Error("String condition '" + condition + "' is not defined on machine '" + this.machine.id + "'");
+            }
+            condFn = this.machine.options.guards[condition];
+        }
+        else {
+            condFn = condition;
+        }
+        return condFn(extendedState, eventObject, interimState);
+    };
+    StateNode.prototype._getActions = function (transition) {
+        var entryExitActions = {
+            entry: transition.entryExitStates
+                ? utils_1.flatMap(Array.from(transition.entryExitStates.entry).map(function (n) { return n.onEntry.concat((n.activities
+                    ? n.activities.map(function (activity) { return actions_1.start(activity); })
+                    : [])); }))
+                : [],
+            exit: transition.entryExitStates
+                ? utils_1.flatMap(Array.from(transition.entryExitStates.exit).map(function (n) { return n.onExit.concat((n.activities
+                    ? n.activities.map(function (activity) { return actions_1.stop(activity); })
+                    : [])); }))
+                : []
+        };
+        var actions = (entryExitActions.exit || [])
+            .concat(transition.actions || [])
+            .concat(entryExitActions.entry || []);
+        return actions;
+    };
+    StateNode.prototype._getActivities = function (state, transition) {
+        if (!transition.entryExitStates) {
+            return {};
+        }
+        var activityMap = __assign({}, state.activities);
+        Array.from(transition.entryExitStates.exit).forEach(function (stateNode) {
+            if (!stateNode.activities) {
+                return; // TODO: fixme
+            }
+            stateNode.activities.forEach(function (activity) {
+                activityMap[utils_1.getActionType(activity)] = false;
+            });
+        });
+        Array.from(transition.entryExitStates.entry).forEach(function (stateNode) {
+            if (!stateNode.activities) {
+                return; // TODO: fixme
+            }
+            stateNode.activities.forEach(function (activity) {
+                activityMap[utils_1.getActionType(activity)] = true;
+            });
+        });
+        return activityMap;
+    };
     StateNode.prototype.transition = function (state, event, extendedState) {
+        var _a;
         var resolvedStateValue = typeof state === 'string'
             ? this.resolve(utils_1.pathToStateValue(this.getResolvedPath(state)))
-            : state instanceof State_1.State ? state : this.resolve(state);
+            : state instanceof State_1.State
+                ? state
+                : this.resolve(state);
+        var eventType = utils_1.getEventType(event);
         if (this.strict) {
-            var eventType = utils_1.getEventType(event);
             if (this.events.indexOf(eventType) === -1) {
                 throw new Error("Machine '" + this.id + "' does not accept event '" + eventType + "'");
             }
         }
         var currentState = State_1.State.from(resolvedStateValue);
-        var stateTransition = this.transitionStateValue(currentState, event, currentState, extendedState);
-        var nextState = this.stateTransitionToState(stateTransition, currentState);
+        var historyValue = resolvedStateValue instanceof State_1.State
+            ? resolvedStateValue.historyValue
+                ? resolvedStateValue.historyValue
+                : this.machine.historyValue(resolvedStateValue.value)
+            : this.machine.historyValue(resolvedStateValue);
+        var stateTransition = this._transition(currentState.value, currentState, event, extendedState);
+        try {
+            this.ensureValidPaths(stateTransition.paths);
+        }
+        catch (e) {
+            throw new Error("Event '" + eventType + "' leads to an invalid configuration: " + e.message);
+        }
+        var actions = this._getActions(stateTransition);
+        var activities = this._getActivities(currentState, stateTransition);
+        var raisedEvents = actions.filter(function (action) {
+            return typeof action === 'object' &&
+                (action.type === actions_1.actionTypes.raise || action.type === actions_1.actionTypes.null);
+        });
+        var nonEventActions = actions.filter(function (action) {
+            return typeof action !== 'object' ||
+                (action.type !== actions_1.actionTypes.raise && action.type !== actions_1.actionTypes.null);
+        });
+        var stateNodes = stateTransition.value
+            ? this.getStateNodes(stateTransition.value)
+            : [];
+        var isTransient = stateNodes.some(function (stateNode) { return stateNode.transient; });
+        if (isTransient) {
+            raisedEvents.push({ type: actions_1.actionTypes.null });
+        }
+        var data = {};
+        stateNodes.forEach(function (stateNode) {
+            data[stateNode.id] = stateNode.data;
+        });
+        var nextState = stateTransition.value
+            ? new State_1.State(stateTransition.value, StateNode.updateHistoryValue(historyValue, stateTransition.value), currentState, nonEventActions, activities, data, raisedEvents)
+            : undefined;
         if (!nextState) {
+            // Unchanged state should be returned with no actions
             return State_1.State.inert(currentState);
         }
+        // Dispose of previous histories to prevent memory leaks
+        delete currentState.history;
         var maybeNextState = nextState;
-        var raisedEvents = nextState.actions.filter(function (action) { return typeof action === 'object' && action.type === actions_1.actionTypes.raise; });
-        if (raisedEvents.length) {
-            var raisedEvent = raisedEvents[0].event;
-            nextState = this.transition(nextState, raisedEvent, extendedState);
-            (_a = nextState.actions).unshift.apply(_a, nextState.actions);
-            return nextState;
-        }
-        if (stateTransition.events.length) {
-            var raised = stateTransition.events[0].type === actions_1.actionTypes.raise
-                ? stateTransition.events[0].event
-                : undefined;
-            var nullEvent = stateTransition.events[0].type === actions_1.actionTypes.null;
-            if (raised || nullEvent) {
-                maybeNextState = this.transition(nextState, nullEvent ? NULL_EVENT : raised, extendedState);
-                (_b = maybeNextState.actions).unshift.apply(_b, nextState.actions);
-                return maybeNextState;
-            }
+        while (raisedEvents.length) {
+            var currentActions = maybeNextState.actions;
+            var raisedEvent = raisedEvents.shift();
+            maybeNextState = this.transition(maybeNextState, raisedEvent.type === actions_1.actionTypes.null ? NULL_EVENT : raisedEvent.event, extendedState);
+            (_a = maybeNextState.actions).unshift.apply(_a, currentActions);
         }
-        return nextState;
-        var _a, _b;
+        return maybeNextState;
     };
-    StateNode.prototype.stateTransitionToState = function (stateTransition, prevState) {
-        var nextStatePaths = stateTransition.statePaths, nextActions = stateTransition.actions, nextActivities = stateTransition.activities, events = stateTransition.events;
-        if (!nextStatePaths.length) {
-            return undefined;
-        }
-        var prevActivities = prevState instanceof State_1.State ? prevState.activities : undefined;
-        var activities = __assign({}, prevActivities, nextActivities);
-        var nextStateValue = this.resolve(utils_1.pathsToStateValue(nextStatePaths));
-        return new State_1.State(
-        // next state value
-        nextStateValue, 
-        // history
-        State_1.State.from(prevState), 
-        // effects
-        nextActions
-            ? nextActions.onExit
-                .concat(nextActions.actions)
-                .concat(nextActions.onEntry)
-            : [], 
-        // activities
-        activities, 
-        // data
-        this.getStateNodes(nextStateValue).reduce(function (data, stateNode) {
-            if (stateNode.data !== undefined) {
-                data[stateNode.id] = stateNode.data;
+    StateNode.prototype.ensureValidPaths = function (paths) {
+        var _this = this;
+        var visitedParents = new Map();
+        var stateNodes = utils_1.flatMap(paths.map(function (_path) { return _this.getRelativeStateNodes(_path); }));
+        outer: for (var _i = 0, stateNodes_1 = stateNodes; _i < stateNodes_1.length; _i++) {
+            var stateNode = stateNodes_1[_i];
+            var marker = stateNode;
+            while (marker.parent) {
+                if (visitedParents.has(marker.parent)) {
+                    if (marker.parent.parallel) {
+                        continue outer;
+                    }
+                    throw new Error("State node '" + stateNode.id + "' shares parent '" + marker.parent.id + "' with state node '" + visitedParents
+                        .get(marker.parent)
+                        .map(function (a) { return a.id; }) + "'");
+                }
+                if (!visitedParents.get(marker.parent)) {
+                    visitedParents.set(marker.parent, [stateNode]);
+                }
+                else {
+                    visitedParents.get(marker.parent).push(stateNode);
+                }
+                marker = marker.parent;
             }
-            return data;
-        }, {}), events);
+        }
     };
     StateNode.prototype.getStateNode = function (stateKey) {
         if (isStateId(stateKey)) {
             return this.machine.getStateNodeById(stateKey);
         }
         if (!this.states) {
-            throw new Error("Unable to retrieve child state '" + stateKey + "' from '" + this
-                .id + "'; no child states exist.");
+            throw new Error("Unable to retrieve child state '" + stateKey + "' from '" + this.id + "'; no child states exist.");
         }
         var result = this.states[stateKey];
         if (!result) {
@@ -225,14 +501,24 @@ var StateNode = /** @class */ (function () {
         var resolvedStateId = isStateId(stateId)
             ? stateId.slice(STATE_IDENTIFIER.length)
             : stateId;
-        var stateNode = this.idMap[resolvedStateId];
+        var stateNode = this.machine.idMap[resolvedStateId];
         if (!stateNode) {
             throw new Error("Substate '#" + resolvedStateId + "' does not exist on '" + this.id + "'");
         }
         return stateNode;
     };
+    StateNode.prototype.getStateNodeByPath = function (statePath) {
+        var arrayStatePath = utils_1.toStatePath(statePath, this.delimiter);
+        var currentStateNode = this;
+        while (arrayStatePath.length) {
+            var key = arrayStatePath.shift();
+            currentStateNode = currentStateNode.getStateNode(key);
+        }
+        return currentStateNode;
+    };
     StateNode.prototype.resolve = function (stateValue) {
         var _this = this;
+        var _a;
         if (typeof stateValue === 'string') {
             var subStateNode = this.getStateNode(stateValue);
             return subStateNode.initial
@@ -240,290 +526,24 @@ var StateNode = /** @class */ (function () {
         }
         if (this.parallel) {
             return utils_1.mapValues(this.initialStateValue, function (subStateValue, subStateKey) {
-                return _this.getStateNode(subStateKey).resolve(stateValue[subStateKey] || subStateValue);
+                return subStateValue
+                    ? _this.getStateNode(subStateKey).resolve(stateValue[subStateKey] || subStateValue)
+                    : {};
             });
         }
         return utils_1.mapValues(stateValue, function (subStateValue, subStateKey) {
-            return _this.getStateNode(subStateKey).resolve(subStateValue);
-        });
-        var _a;
-    };
-    StateNode.prototype.transitionStateValue = function (state, event, fullState, extendedState) {
-        var _this = this;
-        var history = state.history;
-        var stateValue = state.value;
-        if (typeof stateValue === 'string') {
-            var subStateNode = this.getStateNode(stateValue);
-            var result = subStateNode.next(event, fullState, history ? history.value : undefined, extendedState);
-            // If a machine substate returns no potential transitions,
-            // check on the machine itself.
-            if (!result.statePaths.length && !this.parent) {
-                return this.next(event, fullState, history ? history.value : undefined, extendedState);
-            }
-            return result;
-        }
-        // Potential transition tuples from parent state nodes
-        var potentialStateTransitions = [];
-        var willTransition = false;
-        var nextStateTransitionMap = utils_1.mapValues(stateValue, function (subStateValue, subStateKey) {
-            var subStateNode = _this.getStateNode(subStateKey);
-            var subHistory = history ? history.value[subStateKey] : undefined;
-            var subState = new State_1.State(subStateValue, subHistory ? State_1.State.from(subHistory) : undefined);
-            var subStateTransition = subStateNode.transitionStateValue(subState, event, fullState, extendedState);
-            if (!subStateTransition.statePaths.length) {
-                potentialStateTransitions.push(subStateNode.next(event, fullState, history ? history.value : undefined, extendedState));
-            }
-            else {
-                willTransition = true;
-            }
-            return subStateTransition;
-        });
-        if (!willTransition) {
-            if (this.parallel) {
-                if (potentialStateTransitions.length) {
-                    // Select the first potential state transition to take
-                    return potentialStateTransitions[0];
-                }
-                return {
-                    statePaths: [],
-                    actions: emptyActions,
-                    activities: undefined,
-                    events: []
-                };
-            }
-            var subStateKey = Object.keys(nextStateTransitionMap)[0];
-            // try with parent
-            var _a = this.getStateNode(subStateKey).next(event, fullState, history ? history.value : undefined, extendedState), parentStatePaths = _a.statePaths, parentNextActions = _a.actions, parentActivities = _a.activities;
-            var nextActions = nextStateTransitionMap[subStateKey].actions;
-            var activities = nextStateTransitionMap[subStateKey].activities;
-            var allActivities = __assign({}, activities, parentActivities);
-            var allActions = parentNextActions
-                ? nextActions
-                    ? {
-                        onEntry: nextActions.onEntry.concat(parentNextActions.onEntry),
-                        actions: nextActions.actions.concat(parentNextActions.actions),
-                        onExit: nextActions.onExit.concat(parentNextActions.onExit)
-                    }
-                    : parentNextActions
-                : nextActions;
-            return {
-                statePaths: parentStatePaths,
-                actions: allActions,
-                activities: allActivities,
-                events: []
-            };
-        }
-        if (this.parallel) {
-            nextStateTransitionMap = __assign({}, utils_1.mapValues(this.initialState.value, function (subStateValue, key) {
-                var subStateTransition = nextStateTransitionMap[key];
-                return {
-                    statePaths: subStateTransition && subStateTransition.statePaths.length
-                        ? subStateTransition.statePaths
-                        : utils_1.toStatePaths(stateValue[key] || subStateValue).map(function (subPath) { return _this.getStateNode(key).path.concat(subPath); }),
-                    actions: subStateTransition && subStateTransition.actions
-                        ? subStateTransition.actions
-                        : {
-                            onEntry: [],
-                            onExit: [],
-                            actions: []
-                        },
-                    activities: undefined,
-                    events: []
-                };
-            }));
-        }
-        var finalActions = {
-            onEntry: [],
-            actions: [],
-            onExit: []
-        };
-        var finalActivities = {};
-        utils_1.mapValues(nextStateTransitionMap, function (subStateTransition) {
-            var 
-            // statePaths: nextSubStatePaths,
-            nextSubActions = subStateTransition.actions, nextSubActivities = subStateTransition.activities;
-            if (nextSubActions) {
-                if (nextSubActions.onEntry) {
-                    (_a = finalActions.onEntry).push.apply(_a, nextSubActions.onEntry);
-                }
-                if (nextSubActions.actions) {
-                    (_b = finalActions.actions).push.apply(_b, nextSubActions.actions);
-                }
-                if (nextSubActions.onExit) {
-                    (_c = finalActions.onExit).push.apply(_c, nextSubActions.onExit);
-                }
-            }
-            if (nextSubActivities) {
-                Object.assign(finalActivities, nextSubActivities);
-            }
-            var _a, _b, _c;
-        });
-        return {
-            statePaths: Object.keys(nextStateTransitionMap)
-                .map(function (stateKey) { return nextStateTransitionMap[stateKey].statePaths; })
-                .reduce(function (a, b) { return a.concat(b); }, []),
-            actions: finalActions,
-            activities: finalActivities,
-            events: []
-        };
-    };
-    StateNode.prototype.next = function (event, fullState, history, extendedState) {
-        var _this = this;
-        var eventType = utils_1.getEventType(event);
-        var actionMap = { onEntry: [], onExit: [], actions: [] };
-        var activityMap = {};
-        var candidates = this.on[eventType];
-        if (this.onExit) {
-            actionMap.onExit = this.onExit;
-        }
-        if (this.activities) {
-            this.activities.forEach(function (activity) {
-                activityMap[utils_1.getEventType(activity)] = false;
-                actionMap.onExit = actionMap.onExit.concat(actions_1.stop(activity));
-            });
-        }
-        if (!candidates) {
-            return {
-                statePaths: [],
-                actions: actionMap,
-                activities: activityMap,
-                events: []
-            };
-        }
-        var nextStateStrings = [];
-        for (var _i = 0, candidates_1 = candidates; _i < candidates_1.length; _i++) {
-            var candidate = candidates_1[_i];
-            var _a = candidate, cond = _a.cond, stateIn = _a.in, transitionActions = _a.actions;
-            var extendedStateObject = extendedState || {};
-            var eventObject = actions_1.toEventObject(event);
-            var isInState = stateIn
-                ? matchesState_1.matchesState(utils_1.toStateValue(stateIn, this.delimiter), utils_1.path(this.path.slice(0, -2))(fullState.value))
-                : true;
-            if ((!cond || cond(extendedStateObject, eventObject)) &&
-                (!stateIn || isInState)) {
-                nextStateStrings = Array.isArray(candidate.target)
-                    ? candidate.target
-                    : [candidate.target];
-                if (transitionActions) {
-                    actionMap.actions = actionMap.actions.concat(transitionActions);
-                }
-                break;
-            }
-        }
-        if (nextStateStrings.length === 0) {
-            return {
-                statePaths: [],
-                actions: actionMap,
-                activities: activityMap,
-                events: []
-            };
-        }
-        var finalPaths = [];
-        var raisedEvents = [];
-        var usedRegions = {};
-        nextStateStrings.forEach(function (nextStateString) {
-            var nextStatePath = _this.getResolvedPath(nextStateString);
-            var currentState = isStateId(nextStateString)
-                ? _this.machine
-                : _this.parent;
-            var currentHistory = history;
-            var currentPath = _this.key;
-            nextStatePath.forEach(function (subPath) {
-                if (subPath === '') {
-                    actionMap.onExit = [];
-                    currentState = _this;
-                    return;
-                }
-                if (!currentState || !currentState.states) {
-                    throw new Error("Unable to read '" + subPath + "' from '" + _this.id + "'");
-                }
-                if (subPath === HISTORY_KEY) {
-                    if (!Object.keys(currentState.states).length) {
-                        subPath = '';
-                    }
-                    else if (currentHistory) {
-                        subPath =
-                            typeof currentHistory === 'object'
-                                ? Object.keys(currentHistory)[0]
-                                : currentHistory;
-                    }
-                    else if (currentState.initial) {
-                        subPath = currentState.initial;
-                    }
-                    else {
-                        throw new Error("Cannot read '" + HISTORY_KEY + "' from state '" + currentState.id + "': missing 'initial'");
-                    }
-                }
-                try {
-                    if (subPath !== '') {
-                        currentState = currentState.getStateNode(subPath);
-                    }
-                }
-                catch (e) {
-                    throw new Error("Event '" + event + "' on state '" + currentPath + "' leads to undefined state '" + nextStatePath.join(_this.delimiter) + "'.");
-                }
-                if (currentState.onEntry) {
-                    actionMap.onEntry = actionMap.onEntry.concat(currentState.onEntry);
-                }
-                if (currentState.activities) {
-                    currentState.activities.forEach(function (activity) {
-                        activityMap[utils_1.getEventType(activity)] = true;
-                        actionMap.onEntry = actionMap.onEntry.concat(actions_1.start(activity));
-                    });
-                }
-                currentPath = subPath;
-                if (currentHistory) {
-                    currentHistory = currentHistory[subPath];
-                }
-            });
-            if (!currentState) {
-                throw new Error('no state');
-            }
-            var region = ensureTargetStateIsInCorrectRegion(_this, event, usedRegions, currentState);
-            while (region.parent) {
-                region = ensureTargetStateIsInCorrectRegion(_this, event, usedRegions, region.parent);
-            }
-            var paths = [currentState.path];
-            if (currentState.initial || currentState.parallel) {
-                var initialState = currentState.initialState;
-                actionMap.onEntry = actionMap.onEntry.concat(initialState.actions);
-                paths = utils_1.toStatePaths(initialState.value).map(function (subPath) {
-                    return currentState.path.concat(subPath);
-                });
-            }
-            finalPaths.push.apply(finalPaths, paths);
-            while (currentState.initial) {
-                if (!currentState || !currentState.states) {
-                    throw new Error("Invalid initial state");
-                }
-                currentState = currentState.states[currentState.initial];
-                if (currentState.activities) {
-                    currentState.activities.forEach(function (activity) {
-                        activityMap[utils_1.getEventType(activity)] = true;
-                        actionMap.onEntry = actionMap.onEntry.concat(actions_1.start(activity));
-                    });
-                }
-            }
-            var myActions = (currentState.onEntry
-                ? currentState.onEntry.filter(function (action) {
-                    return typeof action === 'object' && action.type === actions_1.actionTypes.raise;
-                })
-                : []).concat(currentState.on[NULL_EVENT] ? { type: actions_1.actionTypes.null } : []);
-            myActions.forEach(function (action) { return raisedEvents.push(action); });
+            return subStateValue
+                ? _this.getStateNode(subStateKey).resolve(subStateValue)
+                : {};
         });
-        return {
-            statePaths: finalPaths,
-            actions: actionMap,
-            activities: activityMap,
-            events: raisedEvents
-        };
     };
     Object.defineProperty(StateNode.prototype, "resolvedStateValue", {
         get: function () {
+            var _a, _b;
             var key = this.key;
             if (this.parallel) {
                 return _a = {},
-                    _a[key] = utils_1.mapValues(this.states, function (stateNode) { return stateNode.resolvedStateValue[stateNode.key]; }),
+                    _a[key] = utils_1.mapFilterValues(this.states, function (stateNode) { return stateNode.resolvedStateValue[stateNode.key]; }, function (stateNode) { return !stateNode.history; }),
                     _a;
             }
             if (!this.initial) {
@@ -533,7 +553,6 @@ var StateNode = /** @class */ (function () {
             return _b = {},
                 _b[key] = this.states[this.initial].resolvedStateValue,
                 _b;
-            var _a, _b;
         },
         enumerable: true,
         configurable: true
@@ -550,12 +569,14 @@ var StateNode = /** @class */ (function () {
     };
     Object.defineProperty(StateNode.prototype, "initialStateValue", {
         get: function () {
-            var initialStateValue = this.__cache.initialState ||
-                (this.parallel
-                    ? utils_1.mapValues(this.states, function (state) { return state.initialStateValue; })
-                    : typeof this.resolvedStateValue === 'string'
-                        ? undefined
-                        : this.resolvedStateValue[this.key]);
+            if (this.__cache.initialState) {
+                return this.__cache.initialState;
+            }
+            var initialStateValue = (this.parallel
+                ? utils_1.mapFilterValues(this.states, function (state) { return state.initialStateValue || {}; }, function (stateNode) { return !stateNode.history; })
+                : typeof this.resolvedStateValue === 'string'
+                    ? undefined
+                    : this.resolvedStateValue[this.key]);
             this.__cache.initialState = initialStateValue;
             return this.__cache.initialState;
         },
@@ -564,6 +585,7 @@ var StateNode = /** @class */ (function () {
     });
     Object.defineProperty(StateNode.prototype, "initialState", {
         get: function () {
+            var _a;
             var initialStateValue = this.initialStateValue;
             if (!initialStateValue) {
                 throw new Error("Cannot retrieve initial state from simple state '" + this.id + ".'");
@@ -581,7 +603,42 @@ var StateNode = /** @class */ (function () {
                     });
                 }
             });
-            return new State_1.State(initialStateValue, undefined, actions, activityMap);
+            // TODO: deduplicate - DRY (from this.transition())
+            var raisedEvents = actions.filter(function (action) {
+                return typeof action === 'object' &&
+                    (action.type === actions_1.actionTypes.raise || action.type === actions_1.actionTypes.null);
+            });
+            var initialState = new State_1.State(initialStateValue, undefined, undefined, actions, activityMap);
+            var maybeNextState = initialState;
+            while (raisedEvents.length) {
+                var currentActions = maybeNextState.actions;
+                var raisedEvent = raisedEvents.shift();
+                maybeNextState = this.transition(maybeNextState, raisedEvent.type === actions_1.actionTypes.null ? NULL_EVENT : raisedEvent.event, undefined // TODO: consider initial state given external state
+                );
+                (_a = maybeNextState.actions).unshift.apply(_a, currentActions);
+            }
+            return maybeNextState;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(StateNode.prototype, "target", {
+        get: function () {
+            var target;
+            if (this.history) {
+                var historyConfig = this.config;
+                if (historyConfig.target && typeof historyConfig.target === 'string') {
+                    target = isStateId(historyConfig.target)
+                        ? utils_1.pathToStateValue(this.machine
+                            .getStateNodeById(historyConfig.target)
+                            .path.slice(this.path.length - 1))
+                        : historyConfig.target;
+                }
+                else {
+                    target = historyConfig.target;
+                }
+            }
+            return target;
         },
         enumerable: true,
         configurable: true
@@ -597,22 +654,151 @@ var StateNode = /** @class */ (function () {
         });
         return stateNodes;
     };
-    StateNode.prototype.getState = function (relativeStateId) {
+    /**
+     * Returns the leaf nodes from a state path relative to this state node.
+     *
+     * @param relativeStateId The relative state path to retrieve the state nodes
+     * @param history The previous state to retrieve history
+     * @param resolve Whether state nodes should resolve to initial child state nodes
+     */
+    StateNode.prototype.getRelativeStateNodes = function (relativeStateId, historyValue, resolve) {
+        if (resolve === void 0) { resolve = true; }
         if (typeof relativeStateId === 'string' && isStateId(relativeStateId)) {
-            return this.getStateNodeById(relativeStateId);
+            var unresolvedStateNode = this.getStateNodeById(relativeStateId);
+            return resolve
+                ? unresolvedStateNode.history
+                    ? unresolvedStateNode.resolveHistory(historyValue)
+                    : unresolvedStateNode.initialStateNodes
+                : [unresolvedStateNode];
         }
         var statePath = utils_1.toStatePath(relativeStateId, this.delimiter);
-        try {
-            return statePath.reduce(function (subState, subPath) {
-                if (!subState.states) {
-                    throw new Error("Cannot retrieve subPath '" + subPath + "' from node with no states");
+        var rootStateNode = this.parent || this;
+        var unresolvedStateNodes = rootStateNode.getFromRelativePath(statePath, historyValue);
+        if (!resolve) {
+            return unresolvedStateNodes;
+        }
+        return utils_1.flatMap(unresolvedStateNodes.map(function (stateNode) { return stateNode.initialStateNodes; }));
+    };
+    Object.defineProperty(StateNode.prototype, "initialStateNodes", {
+        get: function () {
+            var _this = this;
+            // todo - isLeafNode or something
+            if (!this.parallel && !this.initial) {
+                return [this];
+            }
+            var initialState = this.initialState;
+            var initialStateNodePaths = utils_1.toStatePaths(initialState.value);
+            return utils_1.flatMap(initialStateNodePaths.map(function (initialPath) {
+                return _this.getFromRelativePath(initialPath);
+            }));
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /**
+     * Retrieves state nodes from a relative path to this state node.
+     *
+     * @param relativePath The relative path from this state node
+     * @param historyValue
+     */
+    StateNode.prototype.getFromRelativePath = function (relativePath, historyValue) {
+        var _this = this;
+        if (!relativePath.length) {
+            return [this];
+        }
+        var x = relativePath[0], xs = relativePath.slice(1);
+        if (!this.states) {
+            throw new Error("Cannot retrieve subPath '" + x + "' from node with no states");
+        }
+        // TODO: remove (4.0)
+        if (x === HISTORY_KEY) {
+            if (!historyValue) {
+                return [this];
+            }
+            var subHistoryValue = utils_1.nestedPath(this.path, 'states')(historyValue).current;
+            if (typeof subHistoryValue === 'string') {
+                return this.states[subHistoryValue].getFromRelativePath(xs, historyValue);
+            }
+            return utils_1.flatMap(Object.keys(subHistoryValue).map(function (key) {
+                return _this.states[key].getFromRelativePath(xs, historyValue);
+            }));
+        }
+        var childStateNode = this.getStateNode(x);
+        if (childStateNode.history) {
+            return childStateNode.resolveHistory(historyValue);
+        }
+        if (!this.states[x]) {
+            throw new Error("Child state '" + x + "' does not exist on '" + this.id + "'");
+        }
+        return this.states[x].getFromRelativePath(xs, historyValue);
+    };
+    StateNode.updateHistoryValue = function (hist, stateValue) {
+        function update(_hist, _sv) {
+            return utils_1.mapValues(_hist.states, function (subHist, key) {
+                if (!subHist) {
+                    return undefined;
+                }
+                var subStateValue = (typeof _sv === 'string' ? undefined : _sv[key]) ||
+                    (subHist ? subHist.current : undefined);
+                if (!subStateValue) {
+                    return undefined;
                 }
-                return subState.states[subPath];
-            }, this);
+                return {
+                    current: subStateValue,
+                    states: update(subHist, subStateValue)
+                };
+            });
         }
-        catch (e) {
-            throw new Error("State '" + relativeStateId + " does not exist on machine '" + this.id + "'");
+        return {
+            current: stateValue,
+            states: update(hist, stateValue)
+        };
+    };
+    StateNode.prototype.historyValue = function (relativeStateValue) {
+        if (!Object.keys(this.states).length) {
+            return undefined;
+        }
+        return {
+            current: relativeStateValue || this.initialStateValue,
+            states: utils_1.mapFilterValues(this.states, function (stateNode, key) {
+                if (!relativeStateValue) {
+                    return stateNode.historyValue();
+                }
+                var subStateValue = typeof relativeStateValue === 'string'
+                    ? undefined
+                    : relativeStateValue[key];
+                return stateNode.historyValue(subStateValue || stateNode.initialStateValue);
+            }, function (stateNode) { return !stateNode.history; })
+        };
+    };
+    /**
+     * Resolves to the historical value(s) of the parent state node,
+     * represented by state nodes.
+     *
+     * @param historyValue
+     */
+    StateNode.prototype.resolveHistory = function (historyValue) {
+        var _this = this;
+        if (!this.history) {
+            return [this];
         }
+        var parent = this.parent;
+        if (!historyValue) {
+            return this.target
+                ? utils_1.flatMap(utils_1.toStatePaths(this.target).map(function (relativeChildPath) {
+                    return parent.getFromRelativePath(relativeChildPath);
+                }))
+                : this.parent.initialStateNodes;
+        }
+        var subHistoryValue = utils_1.nestedPath(parent.path, 'states')(historyValue).current;
+        if (typeof subHistoryValue === 'string') {
+            return [parent.getStateNode(subHistoryValue)];
+        }
+        return utils_1.flatMap(utils_1.toStatePaths(subHistoryValue).map(function (subStatePath) {
+            return _this.history === 'deep'
+                ? parent.getFromRelativePath(subStatePath)
+                : [parent.states[subStatePath[0]]];
+        }));
     };
     Object.defineProperty(StateNode.prototype, "events", {
         get: function () {
@@ -637,26 +823,45 @@ var StateNode = /** @class */ (function () {
         enumerable: true,
         configurable: true
     });
+    StateNode.prototype.formatTransition = function (targets, transitionConfig) {
+        var _this = this;
+        var internal = transitionConfig ? transitionConfig.internal : false;
+        // Format targets to their full string path
+        var formattedTargets = targets.map(function (target) {
+            var internalTarget = typeof target === 'string' && target[0] === _this.delimiter;
+            internal = internal || internalTarget;
+            // If internal target is defined on machine,
+            // do not include machine key on target
+            if (internalTarget && !_this.parent) {
+                return target.slice(1);
+            }
+            return internalTarget ? _this.key + target : target;
+        });
+        return __assign({}, transitionConfig, { target: formattedTargets, internal: internal });
+    };
     StateNode.prototype.formatTransitions = function (onConfig) {
+        var _this = this;
         return utils_1.mapValues(onConfig, function (value) {
             if (value === undefined) {
                 return [];
             }
             if (Array.isArray(value)) {
-                return value;
+                return value.map(function (targetTransitionConfig) {
+                    return _this.formatTransition([].concat(targetTransitionConfig.target), targetTransitionConfig);
+                });
             }
             if (typeof value === 'string') {
-                return [{ target: value }];
+                return [_this.formatTransition([value])];
             }
             return Object.keys(value).map(function (target) {
-                return __assign({ target: target }, value[target]);
+                return _this.formatTransition([target], value[target]);
             });
         });
     };
     return StateNode;
 }());
 exports.StateNode = StateNode;
-function Machine(config) {
-    return new StateNode(config);
+function Machine(config, options) {
+    return new StateNode(config, options);
 }
 exports.Machine = Machine;