@player-ui/async-node-plugin 0.13.0-next.2 → 0.13.0-next.4

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,160 @@ 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",
+          },
+        });
+      });
+    });
+  });
+
+  // For tests dealing with the startup and cleanup of promises for async nodes.
+  describe("Promise Management", () => {
+    test("should not start async node handling if process has already started", async () => {
+      const plugin = new AsyncNodePlugin({
+        plugins: [new AsyncNodePluginPlugin()],
+      });
+
+      // Create a promise that won't be resolved.
+      const asyncTapFn = vi.fn();
+      asyncTapFn.mockReturnValue(new Promise(() => {}));
+
+      plugin.hooks.onAsyncNode.tap("test", asyncTapFn);
+
+      const player = new Player({ plugins: [plugin] });
+      player.start(basicFRFWithActions as any);
+
+      await vi.waitFor(() => {
+        expect(asyncTapFn).toHaveBeenCalledOnce();
+      });
+
+      // Clear the one call since it has already been checked.
+      asyncTapFn.mockClear();
+      const playerState = player.getState();
+      expect(playerState.status).toBe("in-progress");
+      // force an update while ignoring the cache.
+      (playerState as InProgressState).controllers.view.currentView?.update();
+
+      // Should not be called again.
+      expect(
+        vi.waitFor(() => {
+          expect(asyncTapFn).toHaveBeenCalledOnce();
+        }),
+      ).rejects.toThrowError();
+    });
+
+    test("should allow for handling to start again if the promise completes", async () => {
+      const plugin = new AsyncNodePlugin({
+        plugins: [new AsyncNodePluginPlugin()],
+      });
+
+      // Create a promise that won't be resolved.
+      const asyncTapFn = vi.fn();
+      asyncTapFn.mockResolvedValue(null);
+
+      plugin.hooks.onAsyncNode.tap("test", asyncTapFn);
+
+      const player = new Player({ plugins: [plugin] });
+      player.start(basicFRFWithActions as any);
+
+      await vi.waitFor(() => {
+        expect(asyncTapFn).toHaveBeenCalledOnce();
+      });
+
+      // Clear the one call since it has already been checked.
+      asyncTapFn.mockClear();
+      const playerState = player.getState();
+      expect(playerState.status).toBe("in-progress");
+      // force an update while ignoring the cache.
+      (playerState as InProgressState).controllers.view.currentView?.update();
+
+      // Should be called again.
+      vi.waitFor(() => {
+        expect(asyncTapFn).toHaveBeenCalledOnce();
+      });
+    });
+  });
 });
 
 describe("parser", () => {

package/src/index.ts

@@ -11,13 +11,25 @@ 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;
+  /** Map of async node id to promises being used to resolve them */
+  inProgressNodes: Set<string>;
+};
+
 export interface AsyncNodePluginOptions {
   /** A set of plugins to load  */
   plugins?: AsyncNodeViewPlugin[];
@@ -34,12 +46,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 +80,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 +105,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 +159,72 @@ 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);
-        });
+      const resolvedNode = context.nodeResolveCache.get(node.id);
+      if (resolvedNode !== undefined) {
+        return resolvedNode;
+      }
 
+      if (context.inProgressNodes.has(node.id)) {
         return node;
       }
-      return newNode;
+
+      // Track that the node is in progress.
+      context.inProgressNodes.add(node.id);
+      queueMicrotask(() => {
+        this.runAsyncNode(node, context, options).finally();
+      });
+
+      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);
+        },
+      );
+
+      // Stop tracking before the next update is triggered
+      context.inProgressNodes.delete(node.id);
+      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,
+      );
+
+      // Stop tracking before the next update is triggered
+      context.inProgressNodes.delete(node.id);
+      this.parseNodeAndUpdate(node, context, result, options);
+    }
+  }
+
   private isAsync(node: Node.Node | null): node is Node.Async {
     return node?.type === NodeType.Async;
   }
@@ -161,7 +233,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 +281,16 @@ export class AsyncNodePluginPlugin implements AsyncNodeViewPlugin {
   }
 
   apply(view: ViewInstance): void {
-    this.currentView = view;
+    const context: AsyncPluginContext = {
+      nodeResolveCache: new Map(),
+      inProgressNodes: new Set(),
+      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 {

package/types/index.d.ts

@@ -1,7 +1,18 @@
 import type { Player, PlayerPlugin, Node, ViewInstance, Parser, ViewPlugin, Resolver } from "@player-ui/player";
-import { AsyncParallelBailHook } from "tapable-ts";
+import { AsyncParallelBailHook, SyncBailHook } from "tapable-ts";
 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;
+    /** Map of async node id to promises being used to resolve them */
+    inProgressNodes: Set<string>;
+};
 export interface AsyncNodePluginOptions {
     /** A set of plugins to load  */
     plugins?: AsyncNodeViewPlugin[];
@@ -12,33 +23,48 @@ export interface AsyncNodeViewPlugin extends ViewPlugin {
     asyncNode: AsyncParallelBailHook<[Node.Async, (result: any) => void], any>;
 }
 export type AsyncHandler = (node: Node.Async, 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 declare class AsyncNodePlugin implements PlayerPlugin {
     private plugins;
+    private playerInstance;
     constructor(options: AsyncNodePluginOptions, asyncHandler?: AsyncHandler);
-    readonly hooks: {
-        onAsyncNode: AsyncParallelBailHook<[Node.Async, (result: any) => void], any, Record<string, any>>;
-    };
+    readonly hooks: AsyncNodeHooks;
+    getPlayerInstance(): Player | undefined;
     name: string;
     apply(player: Player): void;
 }
 export declare class AsyncNodePluginPlugin implements AsyncNodeViewPlugin {
-    asyncNode: AsyncParallelBailHook<[Node.Async, (result: any) => void], any, Record<string, any>>;
+    asyncNode: AsyncParallelBailHook<[
+        Node.Async,
+        (result: any) => void
+    ], any>;
     private basePlugin;
     name: string;
-    private resolvedMapping;
-    private currentView;
+    /**
+     * 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 parseNodeAndUpdate;
     /**
      * 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 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 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;
@@ -48,7 +74,8 @@ export declare class AsyncNodePluginPlugin implements AsyncNodeViewPlugin {
      * @param resolver The resolver instance to attach the hook to.
      * @param view
      */
-    applyResolver(resolver: Resolver): void;
+    applyResolver(resolver: Resolver, context: AsyncPluginContext): void;
+    private runAsyncNode;
     private isAsync;
     private isDeterminedAsync;
     applyParser(parser: Parser): void;