@koordinates/xstate-tree 1.0.0-beta.1

package/lib/testingUtilities.js

@@ -0,0 +1,196 @@
+// ignore file coverage
+import { useMachine } from "@xstate/react";
+import { set, transform, isEqual, isObject, isNil } from "lodash";
+import React, { useEffect, useState } from "react";
+import { TinyEmitter } from "tiny-emitter";
+import { State, createMachine, } from "xstate";
+import { initEvent } from "xstate/lib/actions";
+import { buildXStateTreeMachine } from "./builders";
+import { emitter, recursivelySend, XstateTreeView } from "./xstateTree";
+/**
+ * @public
+ */
+export function slotTestingDummyFactory(name) {
+    return buildXStateTreeMachine(createMachine({
+        id: name,
+        initial: "idle",
+        states: {
+            idle: {},
+        },
+    }), {
+        actions: () => ({}),
+        selectors: () => ({}),
+        slots: [],
+        view: () => (React.createElement("div", null,
+            React.createElement("p", null, name))),
+    });
+}
+/**
+ * @public
+ */
+export const genericSlotsTestingDummy = new Proxy({}, {
+    get(_target, prop) {
+        return () => (React.createElement("div", null,
+            React.createElement("p", null,
+                React.createElement(React.Fragment, null,
+                    prop,
+                    "-slot"))));
+    },
+});
+/**
+ * @public
+ */
+export function buildViewProps(_view, props) {
+    return {
+        ...props,
+        inState: (testState) => (state) => state === testState,
+    };
+}
+/**
+ * @public
+ *
+ * Sets up a root component for use in an \@xstate/test model backed by \@testing-library/react for the component
+ *
+ * The logger argument should just be a simple function which forwards the arguments to console.log,
+ * this is needed because Wallaby.js only displays console logs in tests that come from source code, not library code,
+ * so any logs from inside this file don't show up in the test explorer
+ *
+ * The returned object has a `rootComponent` property and a function, `awaitTransition`, that returns a Promise
+ * when called that is resolved the next time the underlying machine transitions. This can be used in the \@xstate/test
+ * model to ensure after an event action is executed the test in the next state doesn't run until after the machine transitions
+ *
+ * It also delays for 5ms to ensure any React re-rendering happens in response to the state transition
+ */
+export function buildTestRootComponent(machine, logger) {
+    if (!machine.meta) {
+        throw new Error("Root machine has no meta");
+    }
+    if (!machine.meta.view) {
+        throw new Error("Root machine has no associated view");
+    }
+    const onChangeEmitter = new TinyEmitter();
+    function addTransitionListener(listener) {
+        onChangeEmitter.once("transition", listener);
+    }
+    return {
+        rootComponent: function XstateTreeRootComponent() {
+            const [_, __, interpreter] = useMachine(machine, { devTools: true });
+            useEffect(() => {
+                function handler(event) {
+                    recursivelySend(interpreter, event);
+                }
+                function changeHandler(ctx, oldCtx) {
+                    logger("onChange: ", JSON.stringify(difference(ctx, oldCtx), null, 2));
+                    onChangeEmitter.emit("changed", ctx);
+                }
+                function onEventHandler(e) {
+                    logger("onEvent", e);
+                }
+                function onTransitionHandler(s) {
+                    logger("State: ", s.value);
+                    onChangeEmitter.emit("transition");
+                }
+                interpreter.onChange(changeHandler);
+                interpreter.onEvent(onEventHandler);
+                interpreter.onTransition(onTransitionHandler);
+                emitter.on("event", handler);
+                return () => {
+                    emitter.off("event", handler);
+                    interpreter.off(changeHandler);
+                    interpreter.off(onEventHandler);
+                    interpreter.off(onTransitionHandler);
+                };
+            }, [interpreter]);
+            if (!interpreter.initialized) {
+                return null;
+            }
+            return React.createElement(XstateTreeView, { interpreter: interpreter });
+        },
+        addTransitionListener,
+        awaitTransition() {
+            return new Promise((res) => {
+                addTransitionListener(() => {
+                    setTimeout(res, 50);
+                });
+            });
+        },
+    };
+}
+/**
+ * Deep diff between two object, using lodash
+ * @param  {Object} object Object compared
+ * @param  {Object} base   Object to compare with
+ * @return {Object}        Return a new object who represent the diff
+ */
+function difference(object, base) {
+    function changes(object, base) {
+        return transform(object, function (result, value, key) {
+            if (!isEqual(value, base[key])) {
+                result[key] =
+                    isObject(value) && isObject(base[key])
+                        ? changes(value, base[key])
+                        : value;
+            }
+        });
+    }
+    if (isNil(base)) {
+        return object;
+    }
+    return changes(object, base);
+}
+/**
+ * @internal
+ * Builds a root component for use in Storybook
+ *
+ * Pass in an initial state and context and the machine will start from that state
+ *
+ * This does _not_ work for any machines using slots, nothing will be invoked unless
+ * it would be invoked by the state you have chosen the machine to start in
+ *
+ * XState will not run any invoke handlers for parent states or sibling states that
+ * would be passed through if the machine was executing normally
+ *
+ * I have no solutions for this
+ */
+export function buildStorybookComponent(machine, state = machine.initial, context = machine.context ?? {}) {
+    // `set` converts a state.like.this to a {state: { like: this {} } }
+    const objectState = set({}, String(state), undefined);
+    const startingState = new State({
+        value: objectState,
+        context: context,
+        _event: initEvent,
+        _sessionid: null,
+        historyValue: undefined,
+        history: undefined,
+        actions: [],
+        activities: undefined,
+        meta: undefined,
+        events: [],
+        configuration: [],
+        transitions: [],
+        children: {},
+    });
+    return function XstateTreeStorybookComponent() {
+        const [_state, _send, interpreter] = useMachine(machine, {
+            devTools: true,
+            state: startingState,
+        });
+        const [_ignored, forceRender] = useState(0);
+        useEffect(() => {
+            function handler(event) {
+                recursivelySend(interpreter, event);
+            }
+            emitter.on("event", handler);
+            // Hack to get around the fact I'm not seeing it re-render after the
+            // interpreter is initialized
+            setTimeout(() => forceRender(1), 250);
+            return () => {
+                emitter.off("event", handler);
+            };
+        }, [interpreter]);
+        if (!interpreter.initialized) {
+            return null;
+        }
+        return React.createElement(XstateTreeView, { interpreter: interpreter });
+    };
+}

package/lib/types.js

@@ -0,0 +1 @@
+export {};

package/lib/useConstant.js

@@ -0,0 +1,8 @@
+import { useRef } from "react";
+export function useConstant(fn) {
+    const ref = useRef();
+    if (!ref.current) {
+        ref.current = { v: fn() };
+    }
+    return ref.current.v;
+}

package/lib/useService.js

@@ -0,0 +1,85 @@
+import { omit, isEqual } from "lodash";
+import { useState, useRef, useEffect } from "react";
+/**
+ * @public
+ */
+export function loggingMetaOptions(ignoredEvents, ignoreContext = undefined) {
+    const ignoredEventMap = new Map();
+    ignoredEvents.forEach((event) => {
+        ignoredEventMap.set(event, true);
+    });
+    return {
+        xstateTree: {
+            ignoredEvents: ignoredEventMap,
+            ignoreContext,
+        },
+    };
+}
+/**
+ * @internal
+ */
+export function useService(service) {
+    const [current, setCurrent] = useState(service.state);
+    const [children, setChildren] = useState(service.children);
+    const childrenRef = useRef(new Map());
+    useEffect(() => {
+        childrenRef.current = children;
+    }, [children]);
+    useEffect(function () {
+        // Set to current service state as there is a possibility
+        // of a transition occurring between the initial useState()
+        // initialization and useEffect() commit.
+        setCurrent(service.state);
+        setChildren(service.children);
+        const listener = function (state) {
+            if (state.changed) {
+                setCurrent(state);
+                if (!isEqual(childrenRef.current, service.children)) {
+                    setChildren(new Map(service.children));
+                }
+            }
+        };
+        const sub = service.subscribe(listener);
+        return function () {
+            sub.unsubscribe();
+        };
+    }, [service, setChildren]);
+    useEffect(() => {
+        function handler(event) {
+            if (event.type.includes("done")) {
+                const idOfFinishedChild = event.type.split(".")[2];
+                childrenRef.current.delete(idOfFinishedChild);
+                setChildren(new Map(childrenRef.current));
+            }
+            console.debug(`[xstate-tree] ${service.id} handling event`, service.machine.meta?.xstateTree?.ignoredEvents?.has(event.type)
+                ? event.type
+                : event);
+        }
+        let prevState = undefined;
+        function transitionHandler(state) {
+            const ignoreContext = service.machine.meta?.xstateTree?.ignoreContext;
+            const context = ignoreContext
+                ? ignoreContext.length > 0
+                    ? omit(state.context, ignoreContext)
+                    : "[context omitted]"
+                : state.context;
+            if (prevState) {
+                console.debug(`[xstate-tree] ${service.id} transitioning from`, prevState.value, "to", state.value, context);
+            }
+            else {
+                console.debug(`[xstate-tree] ${service.id} transitioning to ${state.value}`, context);
+            }
+            prevState = state;
+        }
+        service.onEvent(handler);
+        service.onTransition(transitionHandler);
+        return () => {
+            service.off(handler);
+            service.off(transitionHandler);
+        };
+    }, [service, setChildren]);
+    return [
+        current,
+        children,
+    ];
+}

package/lib/utils.js

@@ -0,0 +1,22 @@
+export function delay(ms = 0) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function assertIsDefined(val, msg) {
+    if (val === undefined || val === null) {
+        throw new Error(`Expected 'val' to be defined, but received ${val} ${msg ? `(${msg})` : ""}`);
+    }
+}
+export function assert(value, msg) {
+    if (typeof expect !== "undefined") {
+        if (value !== true && msg) {
+            console.error(msg);
+        }
+        expect(value).toEqual(true);
+    }
+    else if (value !== true) {
+        if (msg) {
+            console.error(msg);
+        }
+        throw new Error("assertion failed");
+    }
+}