@player-ui/player 0.13.0-next.1 → 0.13.0-next.2

package/package.json

@@ -6,12 +6,12 @@
     "types"
   ],
   "name": "@player-ui/player",
-  "version": "0.13.0-next.1",
+  "version": "0.13.0-next.2",
   "main": "dist/cjs/index.cjs",
   "dependencies": {
-    "@player-ui/partial-match-registry": "0.13.0-next.1",
-    "@player-ui/make-flow": "0.13.0-next.1",
-    "@player-ui/types": "0.13.0-next.1",
+    "@player-ui/partial-match-registry": "0.13.0-next.2",
+    "@player-ui/make-flow": "0.13.0-next.2",
+    "@player-ui/types": "0.13.0-next.2",
     "@types/dlv": "^1.1.4",
     "dequal": "^2.0.2",
     "dlv": "^1.1.3",

package/src/__tests__/flow.test.ts

@@ -4,6 +4,7 @@ import type { DataController } from "..";
 import { Player } from "..";
 import type { InProgressState } from "../types";
 import { waitFor } from "@testing-library/react";
+import { describe } from "node:test";
 
 test("transitions on action nodes", async () => {
   const player = new Player();
@@ -314,9 +315,10 @@ test("works with iffe flows", async () => {
 
 test("awaited async transitions", async () => {
   const player = new Player();
-
+  let counter = 0;
   player.hooks.expressionEvaluator.tap("test", (expEval) => {
     expEval.addExpressionFunction("testAsync", async (ctx, name) => {
+      counter += 1;
       return new Promise((resolve) => {
         setTimeout(() => {
           resolve(name);
@@ -377,6 +379,8 @@ test("awaited async transitions", async () => {
     },
     transitions: {},
   });
+
+  expect(counter).toEqual(1);
 });
 
 test("unawaited async transitions", async () => {
@@ -445,3 +449,163 @@ test("unawaited async transitions", async () => {
     expect(mockFn2).not.toHaveBeenCalled();
   });
 });
+
+describe("edge cases", () => {
+  test("async action nodes firing async expressions more than once after a regular action node", async () => {
+    const player = new Player();
+    let asyncCounter = 0;
+    let syncCounter = 0;
+    player.hooks.expressionEvaluator.tap("test", (expEval) => {
+      expEval.addExpressionFunction("testAsync", async (ctx, name) => {
+        asyncCounter += 1;
+        return new Promise((resolve) => {
+          setTimeout(() => {
+            resolve(name);
+          }, 10);
+        });
+      });
+      expEval.addExpressionFunction("testSync", (ctx) => {
+        syncCounter += 1;
+        return "foo";
+      });
+    });
+
+    player.start({
+      id: "test-flow",
+      data: {
+        my: {
+          puppy: "Ginger",
+        },
+      },
+      navigation: {
+        BEGIN: "FLOW_1",
+        FLOW_1: {
+          startState: "ACTION_1",
+          ACTION_1: {
+            state_type: "ACTION",
+            exp: "{{something}} = testSync()",
+            transitions: {
+              "*": "ACTION_2",
+            },
+          },
+          ACTION_2: {
+            state_type: "ACTION",
+            exp: "{{something}} = testSync()",
+            transitions: {
+              "*": "ACTION_3",
+            },
+          },
+          ACTION_3: {
+            state_type: "ASYNC_ACTION",
+            exp: "{{my.puppy}} = await(testAsync('Daisy'))",
+            transitions: {
+              Daisy: "EXTERNAL_1",
+            },
+            await: true,
+          },
+          EXTERNAL_1: {
+            state_type: "EXTERNAL",
+            ref: "view_1",
+            param: {
+              best: "{{my.puppy}}",
+            },
+            transitions: {},
+          },
+        },
+      },
+    });
+
+    await vitest.waitFor(() =>
+      expect(player.getState().status).toBe("in-progress"),
+    );
+
+    let currentState: NamedState | undefined;
+
+    await waitFor(() => {
+      const state = player.getState();
+      currentState = (state as InProgressState).controllers.flow.current
+        ?.currentState;
+      expect(currentState?.name).toBe("EXTERNAL_1");
+    });
+
+    expect(currentState?.value.ref).toStrictEqual("view_1");
+
+    expect(asyncCounter).toEqual(1);
+    expect(syncCounter).toEqual(2);
+  });
+
+  test("async action nodes only transition when the async action is resolved", async () => {
+    const player = new Player();
+    let expressionResolve: (val: any) => void;
+
+    player.hooks.expressionEvaluator.tap("test", (expEval) => {
+      expEval.addExpressionFunction("testAsync", async (ctx, name) => {
+        return new Promise((resolve) => {
+          expressionResolve = resolve;
+        });
+      });
+    });
+
+    player.start({
+      id: "test-flow",
+      views: [
+        {
+          id: "test",
+          type: "test",
+        },
+      ],
+      data: {
+        my: {
+          puppy: "Ginger",
+        },
+      },
+      navigation: {
+        BEGIN: "FLOW_1",
+        FLOW_1: {
+          startState: "ACTION_1",
+          ACTION_1: {
+            state_type: "ASYNC_ACTION",
+            exp: "{{my.puppy}} = await(testAsync('Daisy'))",
+            transitions: {
+              "*": "VIEW_1",
+            },
+            await: true,
+          },
+          VIEW_1: {
+            state_type: "VIEW",
+            ref: "test",
+            transitions: {
+              "*": "END",
+            },
+          },
+          END: {
+            state_type: "END",
+            outcome: "done",
+          },
+        },
+      },
+    });
+
+    await vitest.waitFor(() =>
+      expect(player.getState().status).toBe("in-progress"),
+    );
+
+    let currentState: NamedState | undefined;
+
+    await waitFor(() => {
+      const state = player.getState();
+      expect(state.status).toBe("in-progress");
+      currentState = (state as InProgressState).controllers.flow.current
+        ?.currentState;
+      expect(currentState?.name).toBe("ACTION_1");
+      expressionResolve("foo");
+    });
+
+    await waitFor(() => {
+      const state = player.getState();
+      currentState = (state as InProgressState).controllers.flow.current
+        ?.currentState;
+      expect(currentState?.name).toBe("VIEW_1");
+    });
+  });
+});

package/src/__tests__/player.test.ts

@@ -543,7 +543,7 @@ describe("failure cases", () => {
     );
   });
 
-  it("fails gracefully when states after an ACTION state have failures", async () => {
+  it("fails gracefully when states after an ACTION state have failures (sync)", async () => {
     const player = new Player();
 
     const payload = {
@@ -581,6 +581,56 @@ describe("failure cases", () => {
     );
   });
 
+  it("fails gracefully when states after an ACTION state have failures (async)", async () => {
+    const player = new Player();
+
+    player.hooks.expressionEvaluator.tap("test", (expEval) => {
+      expEval.addExpressionFunction("testAsync", async (ctx, name) => {
+        return new Promise((resolve) => {
+          setTimeout(() => {
+            resolve(name);
+          }, 1);
+        });
+      });
+    });
+
+    const payload = {
+      id: "test",
+      views: [
+        {
+          id: "view",
+          type: "text",
+          value: "Some text",
+        },
+      ],
+      data: {},
+      navigation: {
+        BEGIN: "Flow",
+        Flow: {
+          startState: "ActionState",
+          ActionState: {
+            state_type: "ASYNC_ACTION",
+            exp: "await(testAsync('test'))",
+            transitions: {
+              test: "ViewState",
+            },
+            await: true,
+          },
+          ViewState: {
+            state_type: "VIEW",
+            ref: "non-existing-view-async",
+          },
+        },
+      },
+    };
+
+    const response = player.start(makeFlow(payload));
+
+    await expect(response).rejects.toThrowError(
+      "No view with id non-existing-view-async",
+    );
+  });
+
   it("can be failed from other places", async () => {
     const player = new Player();
 

package/src/controllers/flow/controller.ts

@@ -4,9 +4,13 @@ import type { Logger } from "../../logger";
 import type { TransitionOptions } from "./flow";
 import { FlowInstance } from "./flow";
 
+export interface FlowControllerHooks {
+  flow: SyncHook<[FlowInstance], Record<string, any>>;
+}
+
 /** A manager for the navigation section of a Content blob */
 export class FlowController {
-  public readonly hooks = {
+  public readonly hooks: FlowControllerHooks = {
     flow: new SyncHook<[FlowInstance]>(),
   };
 
@@ -33,7 +37,10 @@ export class FlowController {
   }
 
   /** Navigate to another state in the state-machine */
-  public transition(stateTransition: string, options?: TransitionOptions) {
+  public transition(
+    stateTransition: string,
+    options?: TransitionOptions,
+  ): void {
     if (this.current === undefined) {
       throw new Error("Not currently in a flow. Cannot transition.");
     }

package/src/controllers/flow/flow.ts

@@ -5,6 +5,11 @@ import type {
   NavigationFlow,
   NavigationFlowState,
   NavigationFlowEndState,
+  NavigationFlowActionState,
+  NavigationFlowAsyncActionState,
+  NavigationFlowExternalState,
+  NavigationFlowFlowState,
+  NavigationFlowViewState,
 } from "@player-ui/types";
 import type { Logger } from "../../logger";
 
@@ -25,6 +30,50 @@ export type TransitionFunction = (
   options?: TransitionOptions,
 ) => void;
 
+export interface FlowInstanceHooks {
+  beforeStart: SyncBailHook<
+    [NavigationFlow],
+    NavigationFlow,
+    Record<string, any>
+  >;
+  /** A callback when the onStart node was present */
+  onStart: SyncHook<[any], Record<string, any>>;
+  /** A callback when the onEnd node was present */
+  onEnd: SyncHook<[any], Record<string, any>>;
+  /** A hook to intercept and block a transition */
+  skipTransition: SyncBailHook<
+    [NamedState | undefined],
+    boolean | undefined,
+    Record<string, any>
+  >;
+  /** A chance to manipulate the flow-node used to calculate the given transition used  */
+  beforeTransition: SyncWaterfallHook<
+    [
+      (
+        | NavigationFlowViewState
+        | NavigationFlowFlowState
+        | NavigationFlowActionState
+        | NavigationFlowAsyncActionState
+        | NavigationFlowExternalState
+      ),
+      string,
+    ],
+    Record<string, any>
+  >;
+  /** A chance to manipulate the flow-node calculated after a transition */
+  resolveTransitionNode: SyncWaterfallHook<
+    [NavigationFlowState],
+    Record<string, any>
+  >;
+  /** A callback when a transition from 1 state to another was made */
+  transition: SyncHook<
+    [NamedState | undefined, NamedState],
+    Record<string, any>
+  >;
+  /** A callback to run actions after a transition occurs */
+  afterTransition: SyncHook<[FlowInstance], Record<string, any>>;
+}
+
 /** The Content navigation state machine */
 export class FlowInstance {
   private flow: NavigationFlow;
@@ -34,33 +83,19 @@ export class FlowInstance {
   private flowPromise?: DeferredPromise<NavigationFlowEndState>;
   public readonly id: string;
   public currentState?: NamedState;
-  public readonly hooks = {
+  public readonly hooks: FlowInstanceHooks = {
     beforeStart: new SyncBailHook<[NavigationFlow], NavigationFlow>(),
-
-    /** A callback when the onStart node was present */
     onStart: new SyncHook<[any]>(),
-
-    /** A callback when the onEnd node was present */
     onEnd: new SyncHook<[any]>(),
-
-    /** A hook to intercept and block a transition */
     skipTransition: new SyncBailHook<
       [NamedState | undefined],
       boolean | undefined
     >(),
-
-    /** A chance to manipulate the flow-node used to calculate the given transition used  */
     beforeTransition: new SyncWaterfallHook<
       [Exclude<NavigationFlowState, NavigationFlowEndState>, string]
     >(),
-
-    /** A chance to manipulate the flow-node calculated after a transition */
     resolveTransitionNode: new SyncWaterfallHook<[NavigationFlowState]>(),
-
-    /** A callback when a transition from 1 state to another was made */
     transition: new SyncHook<[NamedState | undefined, NamedState]>(),
-
-    /** A callback to run actions after a transition occurs */
     afterTransition: new SyncHook<[FlowInstance]>(),
   };
 
@@ -115,7 +150,10 @@ export class FlowInstance {
     return this.flowPromise.promise;
   }
 
-  public transition(transitionValue: string, options?: TransitionOptions) {
+  public transition(
+    transitionValue: string,
+    options?: TransitionOptions,
+  ): void {
     if (this.isTransitioning) {
       throw new Error(
         `Transitioning while ongoing transition from ${this.currentState?.name} is in progress is not supported`,

package/src/controllers/view/controller.ts

@@ -71,7 +71,6 @@ export class ViewController {
     this.viewOptions = options;
     this.viewMap = initialViews.reduce<Record<string, View>>(
       (viewMap, view) => {
-        // eslint-disable-next-line no-param-reassign
         viewMap[view.id] = view;
         return viewMap;
       },
@@ -171,7 +170,7 @@ export class ViewController {
     }
   }
 
-  public onView(state: NavigationFlowViewState) {
+  public onView(state: NavigationFlowViewState): void {
     const viewId = state.ref;
 
     const source = this.hooks.resolveView.call(

package/src/expressions/__tests__/evaluator.test.ts

@@ -470,6 +470,16 @@ describe("async evaluator", () => {
     expect(await result).toBe("truthy");
   });
 
+  test("Async functions are only called once", async () => {
+    const mockHandler = vitest.fn().mockReturnValue(Promise.resolve(true));
+    evaluator.addExpressionFunction("asyncTest", mockHandler);
+
+    const result = evaluator.evaluateAsync("await(asyncTest())");
+    expect(result).toBeInstanceOf(Promise);
+    expect(await result).toBe(true);
+    expect(mockHandler).toBeCalledTimes(1);
+  });
+
   test("logical operators with async values", async () => {
     evaluator.addExpressionFunction("asyncTrue", async () => {
       return Promise.resolve(true);

package/src/player.ts

@@ -346,47 +346,46 @@ export class Player {
         }
       });
 
-      // Tap for synchronous action states
-      flow.hooks.afterTransition.tap("player", (flowInstance) => {
-        const value = flowInstance.currentState?.value;
-        if (value && value.state_type === "ACTION") {
-          const { exp } = value;
-          const result = expressionEvaluator.evaluate(exp);
-          if (isPromiseLike(result)) {
-            this.logger.warn(
-              "Async expression used as return value in in non-async context, transitioning with '*' value",
-            );
-          }
-          flowController?.transition(String(result));
-        }
-
-        expressionEvaluator.reset();
-      });
-
-      // Tap for async action states
-      flow.hooks.afterTransition.tap("player", async (flowInstance) => {
+      // Tap for action states
+      flow.hooks.afterTransition.tap("player-action-states", (flowInstance) => {
         const value = flowInstance.currentState?.value;
         if (value && value.state_type === "ASYNC_ACTION") {
           const { exp } = value;
+          // defer async execution to next tick to allow transition to settle
           try {
-            let result = expressionEvaluator.evaluateAsync(exp);
+            const result = expressionEvaluator.evaluateAsync(exp);
             if (isPromiseLike(result)) {
               if (value.await) {
-                result = await result;
+                queueMicrotask(() => {
+                  result
+                    .then((r) => flowController?.transition(String(r)))
+                    .catch(flowResultDeferred.reject);
+                });
               } else {
                 this.logger.warn(
                   "Unawaited promise used as return value in in non-async context, transitioning with '*' value",
                 );
+                flowController?.transition(String(result));
               }
             } else {
               this.logger.warn(
                 "Non async expression used in async action node",
               );
+              flowController?.transition(String(result));
             }
-            flowController?.transition(String(result));
           } catch (e) {
             flowResultDeferred.reject(e);
           }
+        } else if (value && value.state_type === "ACTION") {
+          // handle sync actions
+          const { exp } = value;
+          const result = expressionEvaluator.evaluate(exp);
+          if (isPromiseLike(result)) {
+            this.logger.warn(
+              "Async expression used as return value in in non-async context, transitioning with '*' value",
+            );
+          }
+          flowController?.transition(String(result));
         }
 
         expressionEvaluator.reset();

package/types/controllers/flow/controller.d.ts

@@ -3,11 +3,12 @@ import type { Navigation, NavigationFlowEndState } from "@player-ui/types";
 import type { Logger } from "../../logger";
 import type { TransitionOptions } from "./flow";
 import { FlowInstance } from "./flow";
+export interface FlowControllerHooks {
+    flow: SyncHook<[FlowInstance], Record<string, any>>;
+}
 /** A manager for the navigation section of a Content blob */
 export declare class FlowController {
-    readonly hooks: {
-        flow: SyncHook<[FlowInstance], Record<string, any>>;
-    };
+    readonly hooks: FlowControllerHooks;
     private readonly log?;
     private navigation;
     private navStack;

package/types/controllers/flow/flow.d.ts

@@ -1,5 +1,5 @@
 import { SyncBailHook, SyncHook, SyncWaterfallHook } from "tapable-ts";
-import type { NavigationFlow, NavigationFlowState, NavigationFlowEndState } from "@player-ui/types";
+import type { NavigationFlow, NavigationFlowState, NavigationFlowEndState, NavigationFlowActionState, NavigationFlowAsyncActionState, NavigationFlowExternalState, NavigationFlowFlowState, NavigationFlowViewState } from "@player-ui/types";
 import type { Logger } from "../../logger";
 export interface NamedState {
     /** The name of the navigation node */
@@ -12,6 +12,35 @@ export interface TransitionOptions {
     force?: boolean;
 }
 export type TransitionFunction = (name: string, options?: TransitionOptions) => void;
+export interface FlowInstanceHooks {
+    beforeStart: SyncBailHook<[
+        NavigationFlow
+    ], NavigationFlow, Record<string, any>>;
+    /** A callback when the onStart node was present */
+    onStart: SyncHook<[any], Record<string, any>>;
+    /** A callback when the onEnd node was present */
+    onEnd: SyncHook<[any], Record<string, any>>;
+    /** A hook to intercept and block a transition */
+    skipTransition: SyncBailHook<[
+        NamedState | undefined
+    ], boolean | undefined, Record<string, any>>;
+    /** A chance to manipulate the flow-node used to calculate the given transition used  */
+    beforeTransition: SyncWaterfallHook<[
+        (NavigationFlowViewState | NavigationFlowFlowState | NavigationFlowActionState | NavigationFlowAsyncActionState | NavigationFlowExternalState),
+        string
+    ], Record<string, any>>;
+    /** A chance to manipulate the flow-node calculated after a transition */
+    resolveTransitionNode: SyncWaterfallHook<[
+        NavigationFlowState
+    ], Record<string, any>>;
+    /** A callback when a transition from 1 state to another was made */
+    transition: SyncHook<[
+        NamedState | undefined,
+        NamedState
+    ], Record<string, any>>;
+    /** A callback to run actions after a transition occurs */
+    afterTransition: SyncHook<[FlowInstance], Record<string, any>>;
+}
 /** The Content navigation state machine */
 export declare class FlowInstance {
     private flow;
@@ -21,23 +50,7 @@ export declare class FlowInstance {
     private flowPromise?;
     readonly id: string;
     currentState?: NamedState;
-    readonly hooks: {
-        beforeStart: SyncBailHook<[NavigationFlow], NavigationFlow, Record<string, any>>;
-        /** A callback when the onStart node was present */
-        onStart: SyncHook<[any], Record<string, any>>;
-        /** A callback when the onEnd node was present */
-        onEnd: SyncHook<[any], Record<string, any>>;
-        /** A hook to intercept and block a transition */
-        skipTransition: SyncBailHook<[NamedState | undefined], boolean | undefined, Record<string, any>>;
-        /** A chance to manipulate the flow-node used to calculate the given transition used  */
-        beforeTransition: SyncWaterfallHook<[import("@player-ui/types").NavigationFlowViewState | import("@player-ui/types").NavigationFlowFlowState | import("@player-ui/types").NavigationFlowActionState | import("@player-ui/types").NavigationFlowAsyncActionState | import("@player-ui/types").NavigationFlowExternalState, string], Record<string, any>>;
-        /** A chance to manipulate the flow-node calculated after a transition */
-        resolveTransitionNode: SyncWaterfallHook<[NavigationFlowState], Record<string, any>>;
-        /** A callback when a transition from 1 state to another was made */
-        transition: SyncHook<[NamedState | undefined, NamedState], Record<string, any>>;
-        /** A callback to run actions after a transition occurs */
-        afterTransition: SyncHook<[FlowInstance], Record<string, any>>;
-    };
+    readonly hooks: FlowInstanceHooks;
     constructor(id: string, flow: NavigationFlow, options?: {
         /** Logger instance to use */
         logger?: Logger;