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

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__/requiresAssetWrapper.test.ts

@@ -0,0 +1,63 @@
+import { NodeType, Node } from "@player-ui/player";
+import { describe, expect, it } from "vitest";
+import { requiresAssetWrapper } from "../requiresAssetWrapper";
+
+describe("requiresAssetWrapper", () => {
+  it("should return true for asset nodes", () => {
+    const node: Node.Asset = {
+      type: NodeType.Asset,
+      value: {
+        type: "text",
+        id: "id",
+      },
+    };
+
+    const result = requiresAssetWrapper(node);
+
+    expect(result).toBe(true);
+  });
+
+  it("should return true for applicability nodes containing asset nodes", () => {
+    const node: Node.Applicability = {
+      type: NodeType.Applicability,
+      expression: "",
+      value: {
+        type: NodeType.Asset,
+        value: {
+          type: "text",
+          id: "id",
+        },
+      },
+    };
+
+    const result = requiresAssetWrapper(node);
+
+    expect(result).toBe(true);
+  });
+
+  it("should return false for non-asset or non-applicability nodes", () => {
+    const node: Node.Value = {
+      type: NodeType.Value,
+      value: {},
+    };
+
+    const result = requiresAssetWrapper(node);
+
+    expect(result).toBe(false);
+  });
+
+  it("should return false for applicability nodes that do not contain an asset node", () => {
+    const node: Node.Applicability = {
+      type: NodeType.Applicability,
+      expression: "",
+      value: {
+        type: NodeType.Value,
+        value: {},
+      },
+    };
+
+    const result = requiresAssetWrapper(node);
+
+    expect(result).toBe(false);
+  });
+});

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",
+      },
+    });
+  });
+});

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

@@ -0,0 +1,65 @@
+import { NodeType, Node } from "@player-ui/player";
+import { describe, expect, it } from "vitest";
+import { unwrapAsset } from "../unwrapAsset";
+
+describe("unwrapAsseet", () => {
+  it("should return the original node if the current node is not a value node", () => {
+    const node: Node.MultiNode = {
+      type: NodeType.MultiNode,
+      values: [],
+    };
+
+    const result = unwrapAsset(node);
+    expect(result).toStrictEqual({
+      type: NodeType.MultiNode,
+      values: [],
+    });
+  });
+
+  const noAssetChildren = [undefined, []];
+  it.each(noAssetChildren)(
+    "should return the original node if it can't unwrap the asset",
+    (children) => {
+      const node: Node.Value = {
+        type: NodeType.Value,
+        value: {},
+        children,
+      };
+
+      const result = unwrapAsset(node);
+      expect(result).toStrictEqual({
+        type: NodeType.Value,
+        value: {},
+        children,
+      });
+    },
+  );
+
+  it("should unwrap and return the asset from a value node", () => {
+    const node: Node.Value = {
+      type: NodeType.Value,
+      value: {},
+      children: [
+        {
+          path: ["asset"],
+          value: {
+            type: NodeType.Asset,
+            value: {
+              id: "id",
+              type: "type",
+            },
+          },
+        },
+      ],
+    };
+
+    const result = unwrapAsset(node);
+    expect(result).toStrictEqual({
+      type: NodeType.Asset,
+      value: {
+        id: "id",
+        type: "type",
+      },
+    });
+  });
+});

package/src/utils/extractNodeFromPath.ts

@@ -0,0 +1,56 @@
+import type { Node } from "@player-ui/player";
+
+/** Matches 2 segments where pathA matches or is a subset of pathB. Returns the number of matching segments */
+const getMatchValue = (
+  pathA: Node.PathSegment[],
+  pathB: Node.PathSegment[],
+): number => {
+  if (pathA.length > pathB.length) {
+    return 0;
+  }
+
+  let matchCount = 0;
+  for (let i = 0; i < pathA.length; i++) {
+    if (pathA[i] === pathB[i]) {
+      matchCount++;
+    } else {
+      return 0;
+    }
+  }
+
+  return matchCount;
+};
+
+/** Follows the given path and returns the node. If there is no match, returns undefined */
+export const extractNodeFromPath = (
+  node: Node.Node,
+  path?: string[],
+): Node.Node | undefined => {
+  if (path === undefined || path.length === 0) {
+    return node;
+  }
+
+  if (!("children" in node && node.children)) {
+    return undefined;
+  }
+
+  let matchResult = 0;
+  let bestMatch: Node.Child | undefined;
+  for (const child of node.children) {
+    const matchValue = getMatchValue(child.path, path);
+    if (matchValue > matchResult) {
+      matchResult = matchValue;
+      bestMatch = child;
+    }
+  }
+
+  if (!bestMatch) {
+    return undefined;
+  }
+
+  if (matchResult >= path.length) {
+    return bestMatch.value;
+  }
+
+  return extractNodeFromPath(bestMatch.value, path.slice(matchResult));
+};

package/src/utils/index.ts

@@ -0,0 +1,4 @@
+export * from "./extractNodeFromPath";
+export * from "./traverseAndReplace";
+export * from "./unwrapAsset";
+export * from "./requiresAssetWrapper";

package/src/utils/requiresAssetWrapper.ts

@@ -0,0 +1,14 @@
+import { NodeType } from "@player-ui/player";
+import type { Node } from "@player-ui/player";
+
+export const requiresAssetWrapper = (node: Node.Node): boolean => {
+  if (node.type === NodeType.Asset) {
+    return true;
+  }
+
+  if (node.type !== NodeType.Applicability) {
+    return false;
+  }
+
+  return node.value.type === NodeType.Asset;
+};

package/src/utils/traverseAndReplace.ts

@@ -0,0 +1,34 @@
+import { NodeType, Node } from "@player-ui/player";
+
+/** Replaces a node using the given replace function. If the node is a multi-node it does this transformation to all of its values. */
+export const traverseAndReplace = (
+  node: Node.Node,
+  replaceFn: (node: Node.Node) => Node.Node,
+): Node.Node => {
+  if (node.type === NodeType.MultiNode) {
+    let index = 0;
+    while (index < node.values.length) {
+      const child = node.values[index];
+      if (!child) {
+        index++;
+        continue;
+      }
+
+      const result = replaceFn(child);
+      if (result.type === NodeType.MultiNode) {
+        node.values = [
+          ...node.values.slice(0, index),
+          ...result.values,
+          ...node.values.slice(index + 1),
+        ];
+      } else {
+        node.values[index] = result;
+        index++;
+      }
+    }
+
+    return node;
+  }
+
+  return replaceFn(node);
+};

package/src/utils/unwrapAsset.ts

@@ -0,0 +1,16 @@
+import { NodeType, Node } from "@player-ui/player";
+
+export const unwrapAsset = (node: Node.Node): Node.Node => {
+  if (node.type !== NodeType.Value) {
+    return node;
+  }
+  const child = node.children?.find(
+    (x) => x.path.length === 1 && x.path[0] === "asset",
+  );
+
+  if (!child) {
+    return node;
+  }
+
+  return child.value;
+};

package/types/createAsyncTransform.d.ts

@@ -0,0 +1,24 @@
+import { BeforeTransformFunction, Node } from "@player-ui/player";
+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;
+};
+/** 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 declare const createAsyncTransform: (options: AsyncTransformOptions) => BeforeTransformFunction;
+//# sourceMappingURL=createAsyncTransform.d.ts.map

package/types/index.d.ts

@@ -2,6 +2,7 @@ import type { Player, PlayerPlugin, Node, ViewInstance, Parser, ViewPlugin, Reso
 import { AsyncParallelBailHook, SyncBailHook } from "tapable-ts";
 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.
  */
@@ -23,8 +24,13 @@ 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>;
+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. */
@@ -71,6 +77,7 @@ export declare class AsyncNodePluginPlugin implements AsyncNodeViewPlugin {
      * @param view The view instance where the node resides. This can be undefined if the view is not currently active.
      */
     private handleAsyncUpdate;
+    private hasValidMapping;
     /**
      * Handles the asynchronous API integration for resolving nodes.
      * This method sets up a hook on the resolver's `beforeResolve` event to process async nodes.
@@ -78,6 +85,14 @@ export declare class AsyncNodePluginPlugin implements AsyncNodeViewPlugin {
      * @param view
      */
     applyResolver(resolver: Resolver, context: AsyncPluginContext): void;
+    /**
+     * 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;
     private runAsyncNode;
     private isAsync;
     private isDeterminedAsync;

package/types/transform.d.ts

@@ -1,10 +1,11 @@
 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
  */
 export declare const asyncTransform: AsyncTransformFunc;