@player-ui/async-node-plugin 0.13.0-next.1 → 0.13.0-next.3

package/src/__tests__/index.bench.ts

@@ -0,0 +1,135 @@
+import { bench, BenchOptions, describe } from "vitest";
+import { AsyncNodePlugin, AsyncNodePluginPlugin } from "..";
+import { Flow, Player } from "@player-ui/player";
+
+const asyncBenchFlow: Flow = {
+  id: "test-flow",
+  views: [
+    {
+      id: "my-view",
+      type: "view",
+      values: [
+        {
+          id: "nodeId",
+          async: "true",
+          flatten: true,
+        },
+      ],
+    },
+  ],
+  navigation: {
+    BEGIN: "FLOW_1",
+    FLOW_1: {
+      startState: "VIEW_1",
+      VIEW_1: {
+        state_type: "VIEW",
+        ref: "my-view",
+        transitions: {
+          "*": "END_DONE",
+        },
+      },
+      END_DONE: {
+        state_type: "END",
+        outcome: "done",
+      },
+    },
+  },
+};
+
+// Benchmark tests for async node resolution. Each test spins up player and resolves all but the last async node to be setup.
+// This is to make tests results easier to compare. If test results across different node counts are similar than we know that resolving additional async nodes will not have significant performance impact.
+describe("async node benchmarks", () => {
+  const asyncNodes = [1, 5, 10, 50, 100];
+
+  asyncNodes.forEach((nodeCount) => {
+    // Promise for when player reaches a completed state.
+    let playerCompletePromise: Promise<unknown>;
+    // Function to resolve the async node. Resolves the promise for the `onAsyncNode` hook.
+    let resolveAsyncNode: () => void;
+
+    // Setup function for spinning up player and setting up the above promise and function.
+    // Using a setup function also takes all the overhead of the setup itself out of the perf benchmark.
+    const setupPlayer = () => {
+      const asyncNodePlugin = new AsyncNodePlugin({
+        plugins: [new AsyncNodePluginPlugin()],
+      });
+
+      let completeSetup: (value?: unknown) => void = () => {};
+      const setupPromise = new Promise((res) => {
+        completeSetup = res;
+      });
+
+      let lastCreatedNodeIndex = -1;
+      asyncNodePlugin.hooks.onAsyncNode.tap("bench", () => {
+        return new Promise((resolve) => {
+          const nodeNumber = lastCreatedNodeIndex + 1;
+          // Setup the resolve function to add a text asset and another async node.
+          resolveAsyncNode = () => {
+            lastCreatedNodeIndex = nodeNumber;
+            resolve([
+              {
+                asset: {
+                  id: `bench-${nodeNumber}`,
+                  type: "text",
+                },
+              },
+              {
+                id: `another-async-${nodeNumber}`,
+                async: true,
+                flatten: true,
+              },
+            ]);
+          };
+
+          // If this is not the last node to be added for this test, resolve it immediately, otherwise resolve the setup promise.
+          if (nodeNumber + 1 < nodeCount) {
+            resolveAsyncNode();
+          } else {
+            completeSetup();
+          }
+        });
+      });
+
+      const player = new Player({ plugins: [asyncNodePlugin] });
+
+      player.hooks.view.tap("bench", (fc) => {
+        fc.hooks.onUpdate.tap("bench", () => {
+          // Since the created index should go up to `nodeCount - 1` we wait for that to be true before transitioning player to its end state.
+          if (lastCreatedNodeIndex < nodeCount - 1) {
+            return;
+          }
+
+          const state = player.getState();
+
+          if (state.status !== "in-progress") {
+            throw new Error("benchmark failed");
+          }
+
+          state.controllers.flow.transition("END");
+        });
+      });
+
+      playerCompletePromise = player.start(asyncBenchFlow);
+
+      return setupPromise;
+    };
+
+    // The bench setup function. This gets called once before all iterations of the test are run
+    const setup: BenchOptions["setup"] = (task) => {
+      // Add setup to the before each and wait on it to finish before starting a test run.
+      task.opts.beforeEach = async () => {
+        await setupPlayer();
+      };
+    };
+
+    bench(
+      `Resolve Async Node ${nodeCount} times`,
+      async () => {
+        // The test just resolves the last node and waits for player to complete.
+        resolveAsyncNode();
+        await playerCompletePromise;
+      },
+      { iterations: 100, throws: true, setup },
+    );
+  });
+});

package/src/__tests__/index.test.ts

@@ -1,10 +1,43 @@
-import { expect, test, describe } from "vitest";
-import { Node, InProgressState } from "@player-ui/player";
+import { expect, test, describe, vi, beforeEach } from "vitest";
+import {
+  Node,
+  InProgressState,
+  ErrorState,
+  PlayerPlugin,
+  AssetTransformCorePlugin,
+  BeforeTransformFunction,
+} from "@player-ui/player";
 import { Player, Parser } from "@player-ui/player";
 import { waitFor } from "@testing-library/react";
-import { AsyncNodePlugin, AsyncNodePluginPlugin } from "../index";
-import { ReferenceAssetsPlugin } from "@player-ui/reference-assets-plugin";
+import {
+  AsyncNodePlugin,
+  AsyncNodePluginPlugin,
+  asyncTransform,
+} from "../index";
 import { CheckPathPlugin } from "@player-ui/check-path-plugin";
+import { Registry } from "@player-ui/partial-match-registry";
+
+const transform: BeforeTransformFunction = (asset) => {
+  const newAsset = asset.children?.[0]?.value;
+
+  if (!newAsset) {
+    return asyncTransform(asset.value.id, "collection");
+  }
+  return asyncTransform(asset.value.id, "collection", newAsset);
+};
+
+const transformPlugin = new AssetTransformCorePlugin(
+  new Registry([[{ type: "chat-message" }, { beforeResolve: transform }]]),
+);
+
+class TestAsyncPlugin implements PlayerPlugin {
+  name = "test-async";
+  apply(player: Player) {
+    player.hooks.view.tap("test-async", (view) => {
+      transformPlugin.apply(view);
+    });
+  }
+}
 
 describe("view", () => {
   const basicFRFWithActions = {
@@ -734,6 +767,84 @@ describe("view", () => {
     });
   });
 
+  describe("Async Node Error Handling", () => {
+    let failingAsyncNodePlugin: AsyncNodePlugin = new AsyncNodePlugin({});
+    const onAsyncNodeErrorCallback = vi.fn();
+
+    beforeEach(() => {
+      onAsyncNodeErrorCallback.mockReset();
+      const failingHandler = vi.fn();
+      failingHandler.mockRejectedValue("Promise Rejected");
+
+      failingAsyncNodePlugin = new AsyncNodePlugin(
+        {
+          plugins: [new AsyncNodePluginPlugin()],
+        },
+        failingHandler,
+      );
+
+      failingAsyncNodePlugin.hooks.onAsyncNodeError.tap(
+        "test",
+        onAsyncNodeErrorCallback,
+      );
+    });
+
+    test("should replace the async node with the result from the onAsyncNodeError hook when there is an error handling the async node", async () => {
+      onAsyncNodeErrorCallback.mockReturnValue({
+        asset: {
+          id: "async-text",
+          type: "text",
+          value: "Fallback Text",
+        },
+      });
+
+      const player = new Player({ plugins: [failingAsyncNodePlugin] });
+      player.start(basicFRFWithActions as any);
+
+      await waitFor(() => {
+        expect(onAsyncNodeErrorCallback).toHaveBeenCalledWith(
+          new Error("Promise Rejected"),
+          expect.anything(),
+        );
+
+        const playerState = player.getState();
+        expect(playerState.status).toBe("in-progress");
+        const inProgressState = playerState as InProgressState;
+        const lastViewUpdate =
+          inProgressState.controllers.view.currentView?.lastUpdate;
+
+        expect(lastViewUpdate?.actions[1]).toStrictEqual({
+          asset: {
+            id: "async-text",
+            type: "text",
+            value: "Fallback Text",
+          },
+        });
+      });
+    });
+
+    test("should bubble up the error and cause player to fail when there is an error handling the async node and the onAsyncNodeError hook does not produce a fallback", async () => {
+      onAsyncNodeErrorCallback.mockReturnValue(undefined);
+
+      const player = new Player({ plugins: [failingAsyncNodePlugin] });
+      player.start(basicFRFWithActions as any).catch(() => {
+        /** Purposefully failing player in this test so catching the unresolved exception suppresses warnings from vitest */
+      });
+
+      await waitFor(() => {
+        expect(onAsyncNodeErrorCallback).toHaveBeenCalledWith(
+          new Error("Promise Rejected"),
+          expect.anything(),
+        );
+
+        const playerState = player.getState();
+        expect(playerState.status).toBe("error");
+        const errorState = playerState as ErrorState;
+        expect(errorState.error.message).toBe("Promise Rejected");
+      });
+    });
+  });
+
   test("chat-message asset - replaces async nodes with multi node flattened", async () => {
     const plugin = new AsyncNodePlugin({
       plugins: [new AsyncNodePluginPlugin()],
@@ -749,7 +860,7 @@ describe("view", () => {
 
     let updateNumber = 0;
 
-    const plugins = [plugin, new ReferenceAssetsPlugin()];
+    const plugins = [plugin, new TestAsyncPlugin()];
 
     const player = new Player({
       plugins: plugins,
@@ -821,7 +932,7 @@ describe("view", () => {
 
     let updateNumber = 0;
 
-    const plugins = [plugin, new ReferenceAssetsPlugin()];
+    const plugins = [plugin, new TestAsyncPlugin()];
 
     const player = new Player({
       plugins: plugins,
@@ -886,7 +997,7 @@ describe("view", () => {
     let updateNumber = 0;
 
     const player = new Player({
-      plugins: [plugin, new ReferenceAssetsPlugin()],
+      plugins: [plugin, new TestAsyncPlugin()],
     });
 
     player.hooks.viewController.tap("async-node-test", (vc) => {
@@ -953,7 +1064,7 @@ describe("view", () => {
 
     let updateNumber = 0;
 
-    const plugins = [plugin, new ReferenceAssetsPlugin()];
+    const plugins = [plugin, new TestAsyncPlugin()];
 
     const player = new Player({
       plugins: plugins,
@@ -1051,7 +1162,7 @@ describe("view", () => {
 
     const checkPathPlugin = new CheckPathPlugin();
 
-    const plugins = [plugin, new ReferenceAssetsPlugin(), checkPathPlugin];
+    const plugins = [plugin, new TestAsyncPlugin(), checkPathPlugin];
 
     const player = new Player({
       plugins: plugins,
@@ -1240,6 +1351,93 @@ describe("view", () => {
       ],
     });
   });
+
+  describe("multi-view cache", () => {
+    let asyncNodePlugin: AsyncNodePlugin = new AsyncNodePlugin({});
+    const deferHandler = vi.fn();
+    let deferredResolve = (value: any) => {};
+
+    beforeEach(() => {
+      deferHandler.mockReset();
+      deferHandler.mockImplementation(
+        () =>
+          new Promise((res) => {
+            deferredResolve = res;
+          }),
+      );
+
+      asyncNodePlugin = new AsyncNodePlugin(
+        {
+          plugins: [new AsyncNodePluginPlugin()],
+        },
+        deferHandler,
+      );
+    });
+
+    test("clear cache between views", async () => {
+      const player = new Player({ plugins: [asyncNodePlugin] });
+      player.start(basicFRFWithActions as any);
+
+      await waitFor(() => {
+        expect(deferHandler).toHaveBeenCalledOnce();
+      });
+
+      deferredResolve({
+        asset: {
+          id: "async-text",
+          type: "text",
+          value: "Fallback Text",
+        },
+      });
+
+      await waitFor(() => {
+        const playerState = player.getState();
+        expect(playerState.status).toBe("in-progress");
+        const inProgressState = playerState as InProgressState;
+        const lastViewUpdate =
+          inProgressState.controllers.view.currentView?.lastUpdate;
+
+        expect(lastViewUpdate?.actions[1]).toStrictEqual({
+          asset: {
+            id: "async-text",
+            type: "text",
+            value: "Fallback Text",
+          },
+        });
+      });
+
+      deferHandler.mockClear();
+      player.start(basicFRFWithActions as any);
+
+      await waitFor(() => {
+        expect(deferHandler).toHaveBeenCalledOnce();
+      });
+
+      deferredResolve({
+        asset: {
+          id: "async-text",
+          type: "text",
+          value: "New Fallback Text",
+        },
+      });
+
+      await waitFor(() => {
+        const playerState = player.getState();
+        expect(playerState.status).toBe("in-progress");
+        const inProgressState = playerState as InProgressState;
+        const lastViewUpdate =
+          inProgressState.controllers.view.currentView?.lastUpdate;
+
+        expect(lastViewUpdate?.actions[1]).toStrictEqual({
+          asset: {
+            id: "async-text",
+            type: "text",
+            value: "New Fallback Text",
+          },
+        });
+      });
+    });
+  });
 });
 
 describe("parser", () => {

package/src/index.ts

@@ -11,13 +11,23 @@ import type {
   Resolver,
   Resolve,
 } from "@player-ui/player";
-import { AsyncParallelBailHook } from "tapable-ts";
+import { AsyncParallelBailHook, SyncBailHook } from "tapable-ts";
 import queueMicrotask from "queue-microtask";
 import { omit } from "timm";
 
 export * from "./types";
 export * from "./transform";
 
+/** Object type for storing data related to a single `apply` of the `AsyncNodePluginPlugin`
+ * This object should be setup once per ViewInstance to keep any cached info just for that view to avoid conflicts of shared async node ids across different view states.
+ */
+type AsyncPluginContext = {
+  /** Map of async node id to resolved content */
+  nodeResolveCache: Map<string, any>;
+  /** The view instance this context is attached to. */
+  view: ViewInstance;
+};
+
 export interface AsyncNodePluginOptions {
   /** A set of plugins to load  */
   plugins?: AsyncNodeViewPlugin[];
@@ -34,12 +44,21 @@ export type AsyncHandler = (
   callback?: (result: any) => void,
 ) => Promise<any>;
 
+/** Hook declaration for the AsyncNodePlugin */
+type AsyncNodeHooks = {
+  /** Async hook to get content for an async node */
+  onAsyncNode: AsyncParallelBailHook<[Node.Async, (result: any) => void], any>;
+  /** Sync hook to manage errors coming from the onAsyncNode hook. Return a fallback node or null to render a fallback. The first argument of passed in the call is the error thrown. */
+  onAsyncNodeError: SyncBailHook<[Error, Node.Async], any>;
+};
+
 /**
  * Async node plugin used to resolve async nodes in the content
  * If an async node is present, allow users to provide a replacement node to be rendered when ready
  */
 export class AsyncNodePlugin implements PlayerPlugin {
   private plugins: AsyncNodeViewPlugin[] | undefined;
+  private playerInstance: Player | undefined;
 
   constructor(options: AsyncNodePluginOptions, asyncHandler?: AsyncHandler) {
     if (options?.plugins) {
@@ -59,16 +78,20 @@ export class AsyncNodePlugin implements PlayerPlugin {
     }
   }
 
-  public readonly hooks = {
-    onAsyncNode: new AsyncParallelBailHook<
-      [Node.Async, (result: any) => void],
-      any
-    >(),
+  public readonly hooks: AsyncNodeHooks = {
+    onAsyncNode: new AsyncParallelBailHook(),
+    onAsyncNodeError: new SyncBailHook(),
   };
 
+  getPlayerInstance(): Player | undefined {
+    return this.playerInstance;
+  }
+
   name = "AsyncNode";
 
-  apply(player: Player) {
+  apply(player: Player): void {
+    this.playerInstance = player;
+
     player.hooks.viewController.tap(this.name, (viewController) => {
       viewController.hooks.view.tap(this.name, (view) => {
         this.plugins?.forEach((plugin) => {
@@ -80,40 +103,51 @@ export class AsyncNodePlugin implements PlayerPlugin {
 }
 
 export class AsyncNodePluginPlugin implements AsyncNodeViewPlugin {
-  public asyncNode = new AsyncParallelBailHook<
+  public asyncNode: AsyncParallelBailHook<
     [Node.Async, (result: any) => void],
     any
-  >();
+  > = new AsyncParallelBailHook();
   private basePlugin: AsyncNodePlugin | undefined;
 
   name = "AsyncNode";
 
-  private resolvedMapping = new Map<string, any>();
-
-  private currentView: ViewInstance | undefined;
-
   /**
-   * Updates the node asynchronously based on the result provided.
-   * This method is responsible for handling the update logic of asynchronous nodes.
-   * It checks if the node needs to be updated based on the new result and updates the mapping accordingly.
-   * If an update is necessary, it triggers an asynchronous update on the view.
+   * Parses the node from the result and triggers an asynchronous view update if necessary.
    * @param node The asynchronous node that might be updated.
    * @param result The result obtained from resolving the async node. This could be any data structure or value.
    * @param options Options provided for node resolution, including a potential parseNode function to process the result.
    * @param view The view instance where the node resides. This can be undefined if the view is not currently active.
    */
-  private handleAsyncUpdate(
+  private parseNodeAndUpdate(
     node: Node.Async,
+    context: AsyncPluginContext,
     result: any,
     options: Resolve.NodeResolveOptions,
-    view: ViewInstance | undefined,
   ) {
     const parsedNode =
       options.parseNode && result ? options.parseNode(result) : undefined;
 
-    if (this.resolvedMapping.get(node.id) !== parsedNode) {
-      this.resolvedMapping.set(node.id, parsedNode ? parsedNode : node);
-      view?.updateAsync();
+    this.handleAsyncUpdate(node, context, parsedNode);
+  }
+
+  /**
+   * Updates the node asynchronously based on the result provided.
+   * This method is responsible for handling the update logic of asynchronous nodes.
+   * It checks if the node needs to be updated based on the new result and updates the mapping accordingly.
+   * If an update is necessary, it triggers an asynchronous update on the view.
+   * @param node The asynchronous node that might be updated.
+   * @param newNode The new node to replace the async node.
+   * @param view The view instance where the node resides. This can be undefined if the view is not currently active.
+   */
+  private handleAsyncUpdate(
+    node: Node.Async,
+    context: AsyncPluginContext,
+    newNode?: Node.Node | null,
+  ) {
+    const { nodeResolveCache, view } = context;
+    if (nodeResolveCache.get(node.id) !== newNode) {
+      nodeResolveCache.set(node.id, newNode ? newNode : node);
+      view.updateAsync();
     }
   }
 
@@ -123,36 +157,59 @@ export class AsyncNodePluginPlugin implements AsyncNodeViewPlugin {
    * @param resolver The resolver instance to attach the hook to.
    * @param view
    */
-  applyResolver(resolver: Resolver) {
+  applyResolver(resolver: Resolver, context: AsyncPluginContext): void {
     resolver.hooks.beforeResolve.tap(this.name, (node, options) => {
-      let resolvedNode;
-      if (this.isAsync(node)) {
-        const mappedValue = this.resolvedMapping.get(node.id);
-        if (mappedValue) {
-          resolvedNode = mappedValue;
-        }
-      } else {
-        resolvedNode = null;
+      if (!this.isAsync(node)) {
+        return node;
       }
 
-      const newNode = resolvedNode || node;
-      if (!resolvedNode && node?.type === NodeType.Async) {
-        queueMicrotask(async () => {
-          const result = await this.basePlugin?.hooks.onAsyncNode.call(
-            node,
-            (result) => {
-              this.handleAsyncUpdate(node, result, options, this.currentView);
-            },
-          );
-          this.handleAsyncUpdate(node, result, options, this.currentView);
-        });
-
-        return node;
+      const resolvedNode = context.nodeResolveCache.get(node.id);
+      if (resolvedNode !== undefined) {
+        return resolvedNode;
       }
-      return newNode;
+
+      queueMicrotask(() => this.runAsyncNode(node, context, options));
+
+      return node;
     });
   }
 
+  private async runAsyncNode(
+    node: Node.Async,
+    context: AsyncPluginContext,
+    options: Resolve.NodeResolveOptions,
+  ) {
+    try {
+      const result = await this.basePlugin?.hooks.onAsyncNode.call(
+        node,
+        (result) => {
+          this.parseNodeAndUpdate(node, context, result, options);
+        },
+      );
+      this.parseNodeAndUpdate(node, context, result, options);
+    } catch (e: unknown) {
+      const error = e instanceof Error ? e : new Error(String(e));
+      const result = this.basePlugin?.hooks.onAsyncNodeError.call(error, node);
+
+      if (result === undefined) {
+        const playerState = this.basePlugin?.getPlayerInstance()?.getState();
+
+        if (playerState?.status === "in-progress") {
+          playerState.fail(error);
+        }
+
+        return;
+      }
+
+      options.logger?.error(
+        "Async node handling failed and resolved with a fallback. Error:",
+        error,
+      );
+
+      this.parseNodeAndUpdate(node, context, result, options);
+    }
+  }
+
   private isAsync(node: Node.Node | null): node is Node.Async {
     return node?.type === NodeType.Async;
   }
@@ -161,7 +218,7 @@ export class AsyncNodePluginPlugin implements AsyncNodeViewPlugin {
     return obj && Object.prototype.hasOwnProperty.call(obj, "async");
   }
 
-  applyParser(parser: Parser) {
+  applyParser(parser: Parser): void {
     parser.hooks.parseNode.tap(
       this.name,
       (
@@ -209,9 +266,15 @@ export class AsyncNodePluginPlugin implements AsyncNodeViewPlugin {
   }
 
   apply(view: ViewInstance): void {
-    this.currentView = view;
+    const context: AsyncPluginContext = {
+      nodeResolveCache: new Map<string, any>(),
+      view,
+    };
+
     view.hooks.parser.tap("async", this.applyParser.bind(this));
-    view.hooks.resolver.tap("async", this.applyResolver.bind(this));
+    view.hooks.resolver.tap("async", (resolver) => {
+      this.applyResolver(resolver, context);
+    });
   }
 
   applyPlugin(asyncNodePlugin: AsyncNodePlugin): void {