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

package/src/createAsyncTransform.ts

@@ -0,0 +1,91 @@
+import {
+  BeforeTransformFunction,
+  Builder,
+  Node,
+  NodeType,
+} from "@player-ui/player";
+import { extractNodeFromPath, 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) {
+      const assetNode = Builder.assetWrapper(asset);
+      multiNode = Builder.multiNode(assetNode, 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;

package/src/utils/__tests__/extractNodeFromPath.test.ts

@@ -0,0 +1,181 @@
+import { NodeType, Node } from "@player-ui/player";
+import { describe, expect, it } from "vitest";
+import { extractNodeFromPath } from "../extractNodeFromPath";
+
+describe("extractNodeFromPath", () => {
+  it("should return any child with an exact match", () => {
+    const node: Node.Value = {
+      type: NodeType.Value,
+      value: {},
+      children: [
+        {
+          path: ["value", "asset"],
+          value: {
+            type: NodeType.Asset,
+            value: {
+              id: "id-1",
+              type: "type-1",
+            },
+          },
+        },
+        {
+          path: ["value"],
+          value: {
+            type: NodeType.Value,
+            value: {},
+            children: [
+              {
+                path: ["asset"],
+                value: {
+                  type: NodeType.Asset,
+                  value: {
+                    id: "id-2",
+                    type: "type-2",
+                  },
+                },
+              },
+            ],
+          },
+        },
+      ],
+    };
+
+    const result = extractNodeFromPath(node, ["value", "asset"]);
+
+    expect(result).toStrictEqual({
+      type: NodeType.Asset,
+      value: {
+        id: "id-1",
+        type: "type-1",
+      },
+    });
+  });
+
+  it("should follow partial matches to find the path nested", () => {
+    const node: Node.Value = {
+      type: NodeType.Value,
+      value: {},
+      children: [
+        {
+          path: ["value"],
+          value: {
+            type: NodeType.Value,
+            value: {},
+            children: [
+              {
+                path: ["asset"],
+                value: {
+                  type: NodeType.Asset,
+                  value: {
+                    id: "id-2",
+                    type: "type-2",
+                  },
+                },
+              },
+            ],
+          },
+        },
+      ],
+    };
+
+    const result = extractNodeFromPath(node, ["value", "asset"]);
+
+    expect(result).toStrictEqual({
+      type: NodeType.Asset,
+      value: {
+        id: "id-2",
+        type: "type-2",
+      },
+    });
+  });
+
+  const emptyPaths = [undefined, []];
+  it.each(emptyPaths)(
+    "should return the original node if the path is empty or undefined",
+    (path) => {
+      const node: Node.Value = {
+        type: NodeType.Value,
+        value: {},
+        children: [
+          {
+            path: ["value"],
+            value: {
+              type: NodeType.Value,
+              value: {},
+              children: [
+                {
+                  path: ["asset"],
+                  value: {
+                    type: NodeType.Asset,
+                    value: {
+                      id: "id-2",
+                      type: "type-2",
+                    },
+                  },
+                },
+              ],
+            },
+          },
+        ],
+      };
+
+      const result = extractNodeFromPath(node, path);
+
+      expect(result).toStrictEqual(node);
+    },
+  );
+
+  const noChildrenNodes: Node.Node[] = [
+    // No children property
+    {
+      id: "test",
+      type: NodeType.Async,
+      value: {
+        type: NodeType.Value,
+        value: {
+          id: "test",
+        },
+      },
+    },
+    // Children explicitly set to undefined
+    {
+      type: NodeType.Value,
+      value: {},
+      children: undefined,
+    },
+  ];
+
+  it.each(noChildrenNodes)(
+    "should return undefined if there are no children in the node",
+    (node) => {
+      const result = extractNodeFromPath(node, ["value", "asset"]);
+      expect(result).toBeUndefined();
+    },
+  );
+
+  it("should return undefined if there is no match", () => {
+    const node: Node.Value = {
+      type: NodeType.Value,
+      children: [
+        {
+          path: ["very", "long", "path"],
+          value: {
+            type: NodeType.Value,
+            value: {},
+          },
+        },
+        {
+          path: ["value", "not-asset"],
+          value: {
+            type: NodeType.Value,
+            value: {},
+          },
+        },
+      ],
+      value: {},
+    };
+
+    const result = extractNodeFromPath(node, ["value", "asset"]);
+    expect(result).toBeUndefined();
+  });
+});

package/src/utils/__tests__/traverseAndReplace.test.ts

@@ -0,0 +1,182 @@
+import { describe, expect, it, vi } from "vitest";
+import { Node, NodeType } from "@player-ui/player";
+import { traverseAndReplace } from "../traverseAndReplace";
+
+describe("traverseAndReplace", () => {
+  it("should call the replace function against the given node if it is not a multi-node", () => {
+    const node: Node.Value = {
+      type: NodeType.Value,
+      value: {
+        prop: "value",
+      },
+    };
+
+    const replaceFunction = vi.fn();
+    replaceFunction.mockReturnValue({
+      type: NodeType.Value,
+      value: {
+        prop: "new-value",
+      },
+    });
+
+    const result = traverseAndReplace(node, replaceFunction);
+
+    expect(result).toStrictEqual({
+      type: "value",
+      value: {
+        prop: "new-value",
+      },
+    });
+    expect(replaceFunction).toHaveBeenCalledOnce();
+    expect(replaceFunction).toHaveBeenCalledWith({
+      type: "value",
+      value: {
+        prop: "value",
+      },
+    });
+  });
+
+  it("should call the replace function once for each value in the multi-node", () => {
+    const node: Node.MultiNode = {
+      type: NodeType.MultiNode,
+      values: [
+        {
+          type: NodeType.Value,
+          value: {
+            prop: "value-1",
+          },
+        },
+        {
+          type: NodeType.Value,
+          value: {
+            prop: "value-2",
+          },
+        },
+      ],
+    };
+
+    const replaceFunction = vi.fn();
+    replaceFunction.mockReturnValue({
+      type: NodeType.Value,
+      value: {
+        prop: "new-value",
+      },
+    });
+
+    const result = traverseAndReplace(node, replaceFunction);
+
+    expect(result).toStrictEqual({
+      type: "multi-node",
+      values: [
+        {
+          type: NodeType.Value,
+          value: {
+            prop: "new-value",
+          },
+        },
+        {
+          type: NodeType.Value,
+          value: {
+            prop: "new-value",
+          },
+        },
+      ],
+    });
+    expect(replaceFunction).toHaveBeenCalledTimes(2);
+    expect(replaceFunction).toHaveBeenCalledWith({
+      type: "value",
+      value: {
+        prop: "value-1",
+      },
+    });
+    expect(replaceFunction).toHaveBeenCalledWith({
+      type: "value",
+      value: {
+        prop: "value-2",
+      },
+    });
+  });
+
+  it("should flatten multi-node values generated by the replace function if the top-level node is a multi-node", () => {
+    const node: Node.MultiNode = {
+      type: NodeType.MultiNode,
+      values: [
+        {
+          type: NodeType.Value,
+          value: {
+            prop: "first",
+          },
+        },
+      ],
+    };
+
+    const replaceFunction = vi.fn();
+    replaceFunction.mockImplementation((node: Node.Node) => {
+      if (node.type === NodeType.Value && node.value.prop === "first") {
+        return {
+          type: NodeType.MultiNode,
+          values: [
+            {
+              type: NodeType.Value,
+              value: {
+                prop: "second",
+              },
+            },
+            {
+              type: NodeType.Value,
+              value: {
+                prop: "third",
+              },
+            },
+          ],
+        };
+      }
+
+      return {
+        type: NodeType.Value,
+        value: {
+          prop: "new-value",
+        },
+      };
+    });
+
+    const result = traverseAndReplace(node, replaceFunction);
+
+    expect(result).toStrictEqual({
+      type: "multi-node",
+      values: [
+        {
+          type: NodeType.Value,
+          value: {
+            prop: "new-value",
+          },
+        },
+        {
+          type: NodeType.Value,
+          value: {
+            prop: "new-value",
+          },
+        },
+      ],
+    });
+    expect(replaceFunction).toHaveBeenCalledTimes(3);
+    expect(replaceFunction).toHaveBeenCalledWith({
+      type: "value",
+      value: {
+        prop: "first",
+      },
+    });
+    expect(replaceFunction).toHaveBeenCalledWith({
+      type: "value",
+      value: {
+        prop: "second",
+      },
+    });
+    expect(replaceFunction).toHaveBeenCalledWith({
+      type: "value",
+      value: {
+        prop: "third",
+      },
+    });
+  });
+});