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

package/src/__tests__/index.test.ts

@@ -6,25 +6,23 @@ import {
   PlayerPlugin,
   AssetTransformCorePlugin,
   BeforeTransformFunction,
+  Flow,
 } from "@player-ui/player";
 import { Player, Parser } from "@player-ui/player";
 import { waitFor } from "@testing-library/react";
 import {
   AsyncNodePlugin,
   AsyncNodePluginPlugin,
-  asyncTransform,
+  createAsyncTransform,
 } 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 transform: BeforeTransformFunction = createAsyncTransform({
+  transformAssetType: "chat-message",
+  wrapperAssetType: "collection",
+  getNestedAsset: (node) => node.children?.[0]?.value,
+});
 
 const transformPlugin = new AssetTransformCorePlugin(
   new Registry([[{ type: "chat-message" }, { beforeResolve: transform }]]),
@@ -110,6 +108,31 @@ describe("view", () => {
     },
   };
 
+  const simpleAsyncContent: Flow = {
+    id: "test-flow",
+    views: [
+      {
+        type: "view",
+        id: "my-view",
+        values: {
+          async: true,
+          id: "async-values",
+        },
+      },
+    ],
+    navigation: {
+      BEGIN: "FLOW_1",
+      FLOW_1: {
+        startState: "VIEW_1",
+        VIEW_1: {
+          state_type: "VIEW",
+          ref: "my-view",
+          transitions: {},
+        },
+      },
+    },
+  };
+
   const asyncNodeTest = async (resolvedValue: any) => {
     const plugin = new AsyncNodePlugin({
       plugins: [new AsyncNodePluginPlugin()],
@@ -189,6 +212,64 @@ describe("view", () => {
     expect(view?.actions.length).toBe(1);
   };
 
+  test("should resolve async content children", async () => {
+    const plugin = new AsyncNodePlugin({
+      plugins: [new AsyncNodePluginPlugin()],
+    });
+
+    const asyncNodeHandler = vi.fn();
+    asyncNodeHandler.mockResolvedValue([
+      {
+        asset: {
+          id: "test-1",
+          type: "text",
+          value: "Test 1",
+        },
+      },
+      {
+        asset: {
+          id: "test-2",
+          type: "text",
+          value: "Test 2",
+        },
+      },
+    ]);
+
+    plugin.hooks.onAsyncNode.tap("test", asyncNodeHandler);
+    const player = new Player({ plugins: [plugin] });
+
+    player.start(simpleAsyncContent);
+
+    await waitFor(() => {
+      expect(asyncNodeHandler).toHaveBeenCalled();
+      const playerState = player.getState();
+      expect(playerState.status).toBe("in-progress");
+      expect(
+        (playerState as InProgressState).controllers.view.currentView
+          ?.lastUpdate,
+      ).toStrictEqual(
+        expect.objectContaining({
+          values: [
+            {
+              asset: {
+                id: "test-1",
+                type: "text",
+                value: "Test 1",
+              },
+            },
+            {
+              asset: {
+                id: "test-2",
+                type: "text",
+                value: "Test 2",
+              },
+            },
+          ],
+        }),
+      );
+    });
+  });
+
   test("should return current node view when the resolved node is null", async () => {
     await asyncNodeTest(null);
   });
@@ -852,7 +933,7 @@ describe("view", () => {
 
     let deferredResolve: ((value: any) => void) | undefined;
 
-    plugin.hooks.onAsyncNode.tap("test", async (node) => {
+    plugin.hooks.onAsyncNode.tap("test", async () => {
       return new Promise((resolve) => {
         deferredResolve = resolve;
       });
@@ -868,7 +949,7 @@ describe("view", () => {
 
     player.hooks.viewController.tap("async-node-test", (vc) => {
       vc.hooks.view.tap("async-node-test", (view) => {
-        view.hooks.onUpdate.tap("async-node-test", (update) => {
+        view.hooks.onUpdate.tap("async-node-test", () => {
           updateNumber++;
         });
       });
@@ -913,8 +994,8 @@ describe("view", () => {
     view = (player.getState() as InProgressState).controllers.view.currentView
       ?.lastUpdate;
 
-    expect(view?.values[1][0].asset.type).toBe("text");
-    expect(view?.values[1][1].asset.type).toBe("text");
+    expect(view?.values[1].asset.type).toBe("text");
+    expect(view?.values[2].asset.type).toBe("text");
   });
 
   test("chat-message asset - replaces async nodes with provided node", async () => {

package/src/__tests__/transform.bench.ts

@@ -0,0 +1,177 @@
+import { bench, BenchOptions, describe } from "vitest";
+import {
+  AsyncNodePlugin,
+  AsyncNodePluginPlugin,
+  createAsyncTransform,
+} from "..";
+import {
+  Asset,
+  AssetTransformCorePlugin,
+  BeforeTransformFunction,
+  Flow,
+  Player,
+  PlayerPlugin,
+} from "@player-ui/player";
+import { Registry } from "@player-ui/partial-match-registry";
+
+export const transform: BeforeTransformFunction<Asset<"chat-message">> =
+  createAsyncTransform({
+    transformAssetType: "chat-message",
+    wrapperAssetType: "collection",
+    getNestedAsset: (node) => node.children?.[0]?.value,
+  });
+
+const asyncTransformBenchFlow: Flow = {
+  id: "test-flow",
+  views: [
+    {
+      id: "my-view",
+      type: "view",
+      values: [
+        {
+          asset: {
+            id: "chat",
+            type: "chat-message",
+            value: {
+              asset: {
+                type: "text",
+                id: "original-text",
+                value: "TEST",
+              },
+            },
+          },
+        },
+      ],
+    },
+  ],
+  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",
+      },
+    },
+  },
+};
+
+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("async transform 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: `chat-${nodeNumber}`,
+                  type: "chat-message",
+                  value: {
+                    asset: {
+                      type: "text",
+                      id: `chat-label-${nodeNumber}`,
+                      value: "Test",
+                    },
+                  },
+                },
+              },
+            ]);
+          };
+
+          // 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, new TestAsyncPlugin()],
+      });
+
+      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(asyncTransformBenchFlow);
+
+      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/createAsyncTransform.ts

@@ -0,0 +1,101 @@
+import {
+  BeforeTransformFunction,
+  Builder,
+  Node,
+  NodeType,
+} from "@player-ui/player";
+import {
+  extractNodeFromPath,
+  requiresAssetWrapper,
+  traverseAndReplace,
+  unwrapAsset,
+} from "./utils";
+
+export type AsyncTransformOptions = {
+  /** Whether or not to flatten the results into its container. Defaults to true */
+  flatten?: boolean;
+  /** The path to the array within the `wrapperAssetType` that will contain the async content. Defaults to ["values"] */
+  path?: string[];
+  /** The asset type that the transform is matching against. */
+  transformAssetType: string;
+  /** The asset type that will contain the async content. */
+  wrapperAssetType: string;
+  /** Function to get any nested asset that will need to be extracted and kept when creating the wrapper asset. */
+  getNestedAsset?: (node: Node.ViewOrAsset) => Node.Node | undefined;
+  /** Function to get the id for the async node being generated. Defaults to creating an id with the format of async-<ASSET.ID> */
+  getAsyncNodeId?: (node: Node.ViewOrAsset) => string;
+};
+
+const defaultGetNodeId = (node: Node.ViewOrAsset): string => {
+  return `async-${node.value.id}`;
+};
+
+/** Creates a BeforeTransformFunction that turns the given asset into a wrapper asset with an async node in it.
+ * By setting {@link AsyncTransformOptions.flatten} to true, you can chain multiple of the same asset type to create a flow of async content that
+ * exists within a single collection.
+ *
+ * @param options - Options for managing the transform
+ * @returns The {@link BeforeTransformFunction} that can be used for your asset.
+ */
+export const createAsyncTransform = (
+  options: AsyncTransformOptions,
+): BeforeTransformFunction => {
+  const {
+    transformAssetType,
+    wrapperAssetType,
+    getNestedAsset,
+    getAsyncNodeId = defaultGetNodeId,
+    path = ["values"],
+    flatten = true,
+  } = options;
+
+  const replaceNode = (node: Node.Node): Node.Node => {
+    const unwrapped = unwrapAsset(node);
+
+    if (
+      unwrapped.type !== NodeType.Asset ||
+      unwrapped.value.type !== transformAssetType
+    ) {
+      return node;
+    }
+
+    const transformed = asyncTransform(unwrapped);
+    return extractNodeFromPath(transformed, path) ?? node;
+  };
+
+  const replacer = (node: Node.Node) => traverseAndReplace(node, replaceNode);
+
+  const asyncTransform = (node: Node.ViewOrAsset) => {
+    const id = getAsyncNodeId(node);
+    const asset = getNestedAsset?.(node);
+
+    // If flattening is disabled, don't need to extract the multi-node when async node is resolved.
+    const replaceFunction = flatten ? replacer : undefined;
+    const asyncNode = Builder.asyncNode(id, flatten, replaceFunction);
+
+    let multiNode: Node.MultiNode | undefined;
+    if (asset) {
+      if (requiresAssetWrapper(asset)) {
+        const assetWrappedNode = Builder.assetWrapper(asset);
+        multiNode = Builder.multiNode(assetWrappedNode, asyncNode);
+      } else if (asset.type === NodeType.MultiNode) {
+        multiNode = Builder.multiNode(...(asset.values as any[]), asyncNode);
+      } else {
+        multiNode = Builder.multiNode(asset as any, asyncNode);
+      }
+    } else {
+      multiNode = Builder.multiNode(asyncNode);
+    }
+
+    const wrapperAsset: Node.ViewOrAsset = Builder.asset({
+      id: wrapperAssetType + "-" + id,
+      type: wrapperAssetType,
+    });
+
+    Builder.addChild(wrapperAsset, path, multiNode);
+
+    return wrapperAsset;
+  };
+
+  return asyncTransform;
+};

package/src/index.ts

@@ -13,10 +13,10 @@ import type {
 } from "@player-ui/player";
 import { AsyncParallelBailHook, SyncBailHook } from "tapable-ts";
 import queueMicrotask from "queue-microtask";
-import { omit } from "timm";
 
 export * from "./types";
 export * from "./transform";
+export * from "./createAsyncTransform";
 
 /** 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.
@@ -46,8 +46,14 @@ export type AsyncHandler = (
   callback?: (result: any) => void,
 ) => Promise<any>;
 
+export type AsyncContent = {
+  async: true;
+  flatten?: boolean;
+  [key: string]: unknown;
+};
+
 /** Hook declaration for the AsyncNodePlugin */
-type AsyncNodeHooks = {
+export 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. */
@@ -131,9 +137,13 @@ export class AsyncNodePluginPlugin implements AsyncNodeViewPlugin {
     result: any,
     options: Resolve.NodeResolveOptions,
   ) {
-    const parsedNode =
+    let parsedNode =
       options.parseNode && result ? options.parseNode(result) : undefined;
 
+    if (parsedNode && node.onValueReceived) {
+      parsedNode = node.onValueReceived(parsedNode);
+    }
+
     this.handleAsyncUpdate(node, context, parsedNode);
   }
 
@@ -154,10 +164,20 @@ export class AsyncNodePluginPlugin implements AsyncNodeViewPlugin {
     const { nodeResolveCache, view } = context;
     if (nodeResolveCache.get(node.id) !== newNode) {
       nodeResolveCache.set(node.id, newNode ? newNode : node);
-      view.updateAsync();
+      view.updateAsync(node.id);
     }
   }
 
+  private hasValidMapping(
+    node: Node.Async,
+    context: AsyncPluginContext,
+  ): boolean {
+    const { nodeResolveCache } = context;
+    return (
+      nodeResolveCache.has(node.id) && nodeResolveCache.get(node.id) !== node
+    );
+  }
+
   /**
    * Handles the asynchronous API integration for resolving nodes.
    * This method sets up a hook on the resolver's `beforeResolve` event to process async nodes.
@@ -167,12 +187,12 @@ export class AsyncNodePluginPlugin implements AsyncNodeViewPlugin {
   applyResolver(resolver: Resolver, context: AsyncPluginContext): void {
     resolver.hooks.beforeResolve.tap(this.name, (node, options) => {
       if (!this.isAsync(node)) {
-        return node;
+        return node === null ? node : this.resolveAsyncChildren(node, context);
       }
 
       const resolvedNode = context.nodeResolveCache.get(node.id);
       if (resolvedNode !== undefined) {
-        return resolvedNode;
+        return this.resolveAsyncChildren(resolvedNode, context);
       }
 
       if (context.inProgressNodes.has(node.id)) {
@@ -189,6 +209,63 @@ export class AsyncNodePluginPlugin implements AsyncNodeViewPlugin {
     });
   }
 
+  /**
+   * Replaces child async nodes with their resolved content and flattens when necessary. Resolving the children directly helps manage the `parent` reference without needing as much work within the resolver itself.
+   * Handles async node chains as well to make sure all applicable nodes can get flattened.
+   * @param node - The node whose children need to be resolved.
+   * @param context - the async plugin context needed to reach into the cache
+   * @returns The same node but with async node children mapped to their resolved AST.
+   */
+  private resolveAsyncChildren(
+    node: Node.Node,
+    context: AsyncPluginContext,
+  ): Node.Node {
+    const asyncNodesResolved: string[] = node.asyncNodesResolved ?? [];
+    node.asyncNodesResolved = asyncNodesResolved;
+    if (node.type === NodeType.MultiNode) {
+      // Using a while loop lets us catch when async nodes produce more async nodes that need to be flattened further
+      let index = 0;
+      while (index < node.values.length) {
+        const childNode = node.values[index];
+        if (
+          childNode?.type !== NodeType.Async ||
+          !this.hasValidMapping(childNode, context)
+        ) {
+          index++;
+          continue;
+        }
+
+        const mappedNode = context.nodeResolveCache.get(childNode.id);
+        asyncNodesResolved.push(childNode.id);
+        if (mappedNode.type === NodeType.MultiNode && childNode.flatten) {
+          mappedNode.values.forEach((v: Node.Node) => (v.parent = node));
+          node.values = [
+            ...node.values.slice(0, index),
+            ...mappedNode.values,
+            ...node.values.slice(index + 1),
+          ];
+        } else {
+          node.values[index] = mappedNode;
+          mappedNode.parent = node;
+        }
+      }
+    } else if ("children" in node) {
+      node.children?.forEach((c) => {
+        // Similar to above, using a while loop lets us handle when async nodes produce more async nodes.
+        while (
+          c.value.type === NodeType.Async &&
+          this.hasValidMapping(c.value, context)
+        ) {
+          asyncNodesResolved.push(c.value.id);
+          c.value = context.nodeResolveCache.get(c.value.id);
+          c.value.parent = node;
+        }
+      });
+    }
+
+    return node;
+  }
+
   private async runAsyncNode(
     node: Node.Async,
     context: AsyncPluginContext,
@@ -234,8 +311,12 @@ export class AsyncNodePluginPlugin implements AsyncNodeViewPlugin {
     return node?.type === NodeType.Async;
   }
 
-  private isDeterminedAsync(obj: any) {
-    return obj && Object.prototype.hasOwnProperty.call(obj, "async");
+  private isDeterminedAsync(obj: unknown): obj is AsyncContent {
+    return (
+      typeof obj === "object" &&
+      obj !== null &&
+      Object.prototype.hasOwnProperty.call(obj, "async")
+    );
   }
 
   applyParser(parser: Parser): void {
@@ -248,11 +329,9 @@ export class AsyncNodePluginPlugin implements AsyncNodeViewPlugin {
         childOptions?: ParseObjectChildOptions,
       ) => {
         if (this.isDeterminedAsync(obj)) {
-          const parsedAsync = parser.parseObject(
-            omit(obj, "async"),
-            nodeType,
-            options,
-          );
+          // eslint-disable-next-line @typescript-eslint/no-unused-vars
+          const { async, flatten, ...rest } = obj;
+          const parsedAsync = parser.parseObject(rest, nodeType, options);
           const parsedNodeId = getNodeID(parsedAsync);
 
           if (parsedAsync === null || !parsedNodeId) {
@@ -264,6 +343,7 @@ export class AsyncNodePluginPlugin implements AsyncNodeViewPlugin {
               id: parsedNodeId,
               type: NodeType.Async,
               value: parsedAsync,
+              flatten,
             },
             obj,
           );

package/src/transform.ts

@@ -2,11 +2,12 @@ import { Builder } from "@player-ui/player";
 import type { AsyncTransformFunc } from "./types";
 
 /**
+ * @deprecated Use {@link createAsyncTransform} to create your before transform function.
  * Util function to generate transform function for async asset
  * @param asset - async asset to apply beforeResolve transform
- * @param transformedAssetType: transformed asset type for rendering
  * @param wrapperAssetType: container asset type
  * @param flatten: flatten the streamed in content
+ * @param path: property path to add the multinode containing the next async node to
  * @returns - wrapper asset with children of transformed asset and async node
  */
 
@@ -15,10 +16,12 @@ export const asyncTransform: AsyncTransformFunc = (
   wrapperAssetType,
   asset,
   flatten,
+  path = ["values"],
 ) => {
   const id = "async-" + assetId;
 
   const asyncNode = Builder.asyncNode(id, flatten);
+
   let multiNode;
   let assetNode;
 
@@ -34,7 +37,7 @@ export const asyncTransform: AsyncTransformFunc = (
     type: wrapperAssetType,
   });
 
-  Builder.addChild(wrapperAsset, ["values"], multiNode);
+  Builder.addChild(wrapperAsset, path, multiNode);
 
   return wrapperAsset;
 };

package/src/types.ts

@@ -10,4 +10,5 @@ export type AsyncTransformFunc = (
   wrapperAssetType: string,
   asset?: Node.Node,
   flatten?: boolean,
+  path?: string[],
 ) => Node.Asset;