@player-ui/external-state-plugin 1.0.0--canary.865.36694

package/src/__tests__/index.test.ts

@@ -0,0 +1,538 @@
+import { expect, test, vitest, describe } from "vitest";
+import type { Flow, InProgressState, NamedState } from "@player-ui/player";
+import { Player } from "@player-ui/player";
+import { ExternalStatePlugin } from "..";
+import { waitFor } from "@testing-library/react";
+
+const externalFlow = {
+  id: "test-flow",
+  data: {
+    transitionValue: "Next",
+  },
+  navigation: {
+    BEGIN: "FLOW_1",
+    FLOW_1: {
+      startState: "EXT_1",
+      EXT_1: {
+        state_type: "EXTERNAL",
+        ref: "test-1",
+        transitions: {
+          Next: "END_FWD",
+          Prev: "END_BCK",
+        },
+        testProperty: "testValue",
+      },
+      END_FWD: {
+        state_type: "END",
+        outcome: "FWD",
+      },
+      END_BCK: {
+        state_type: "END",
+        outcome: "BCK",
+      },
+    },
+  },
+};
+
+test("handles the external state", async () => {
+  const player = new Player({
+    plugins: [
+      new ExternalStatePlugin([
+        {
+          ref: "test-1",
+          handlerFunction: (state, options) => {
+            return options.data.get("transitionValue");
+          },
+        },
+      ]),
+    ],
+  });
+
+  const completed = await player.start(externalFlow as Flow);
+
+  expect(completed.endState.outcome).toBe("FWD");
+});
+
+test("thrown errors will fail player", async () => {
+  const player = new Player({
+    plugins: [
+      new ExternalStatePlugin([
+        {
+          ref: "test-1",
+          handlerFunction: () => {
+            throw new Error("Bad Code");
+          },
+        },
+      ]),
+    ],
+  });
+
+  await expect(player.start(externalFlow as Flow)).rejects.toThrow();
+
+  expect(player.getState().status).toBe("error");
+});
+
+test("works async", async () => {
+  const player = new Player({
+    plugins: [
+      new ExternalStatePlugin([
+        {
+          ref: "test-1",
+          handlerFunction: () => {
+            return Promise.resolve("Prev");
+          },
+        },
+      ]),
+    ],
+  });
+
+  const completed = await player.start(externalFlow as Flow);
+
+  expect(completed.endState.outcome).toBe("BCK");
+});
+
+test("allows multiple plugins - last one wins", async () => {
+  const player = new Player({
+    plugins: [
+      new ExternalStatePlugin([
+        {
+          ref: "test-1",
+          handlerFunction: () => {
+            return "Next";
+          },
+        },
+      ]),
+      new ExternalStatePlugin([
+        {
+          ref: "test-1",
+          handlerFunction: () => {
+            return "Prev";
+          },
+        },
+      ]),
+    ],
+  });
+
+  const completed = await player.start(externalFlow as Flow);
+
+  // Last handler registered wins (Prev)
+  expect(completed.endState.outcome).toBe("BCK");
+});
+
+test("logs debug message when replacing handler", async () => {
+  const mockDebug = vitest.fn();
+
+  const player = new Player({
+    plugins: [
+      new ExternalStatePlugin([
+        {
+          ref: "test-1",
+          handlerFunction: () => {
+            return "Next";
+          },
+        },
+      ]),
+      new ExternalStatePlugin([
+        {
+          ref: "test-1",
+          handlerFunction: () => {
+            return "Prev";
+          },
+        },
+      ]),
+    ],
+    logger: {
+      trace: vitest.fn(),
+      debug: mockDebug,
+      info: vitest.fn(),
+      warn: vitest.fn(),
+      error: vitest.fn(),
+    },
+  });
+
+  await player.start(externalFlow as Flow);
+
+  // Should have logged that the handler was replaced
+  const replacementCalls = mockDebug.mock.calls.filter(
+    (call) =>
+      call[0] === "Registry: Replacing existing entry for key " &&
+      JSON.stringify(call[1]) === JSON.stringify({ ref: "test-1" }),
+  );
+  expect(replacementCalls.length).toBeGreaterThan(0);
+});
+
+test("different plugins, more specific match overrides less specific match", async () => {
+  const player = new Player({
+    plugins: [
+      new ExternalStatePlugin([
+        {
+          ref: "test-1",
+          match: { testProperty: "testValue" },
+          handlerFunction: () => {
+            return "Next";
+          },
+        },
+      ]),
+      new ExternalStatePlugin([
+        {
+          ref: "test-1",
+          handlerFunction: () => {
+            return "Prev";
+          },
+        },
+      ]),
+    ],
+  });
+
+  const completed = await player.start(externalFlow as Flow);
+
+  // More specific match (with testProperty) should win, returning "Next" which leads to outcome "FWD"
+  expect(completed.endState.outcome).toBe("FWD");
+});
+
+test("within same plugin, more specific match overrides less specific match", async () => {
+  const moreSpecificHandlerCalled = vitest.fn();
+  const lessSpecificHandlerCalled = vitest.fn();
+
+  const player = new Player({
+    plugins: [
+      new ExternalStatePlugin([
+        {
+          ref: "test-1",
+          match: { testProperty: "testValue" },
+          handlerFunction: () => {
+            moreSpecificHandlerCalled();
+            return "Next";
+          },
+        },
+        {
+          ref: "test-1",
+          handlerFunction: () => {
+            lessSpecificHandlerCalled();
+            return "Prev";
+          },
+        },
+      ]),
+    ],
+  });
+
+  const completed = await player.start(externalFlow as Flow);
+
+  // More specific match should win regardless of insertion order
+  expect(moreSpecificHandlerCalled).toHaveBeenCalledOnce();
+  expect(lessSpecificHandlerCalled).not.toHaveBeenCalled();
+  expect(completed.endState.outcome).toBe("FWD");
+});
+
+test("only transitions if player still on this external state", async () => {
+  let resolver: (() => void) | undefined;
+  const player = new Player({
+    plugins: [
+      new ExternalStatePlugin([
+        {
+          ref: "test-1",
+          handlerFunction: (state, options) => {
+            return new Promise((res) => {
+              // Only save resolver for first external state
+              if (!resolver) {
+                resolver = () => {
+                  res(options.data.get("transitionValue"));
+                };
+              }
+            });
+          },
+        },
+      ]),
+    ],
+  });
+
+  player.start({
+    id: "test-flow",
+    data: {
+      transitionValue: "Next",
+    },
+    navigation: {
+      BEGIN: "FLOW_1",
+      FLOW_1: {
+        startState: "EXT_1",
+        EXT_1: {
+          state_type: "EXTERNAL",
+          ref: "test-1",
+          transitions: {
+            Next: "EXT_2",
+            Prev: "END_BCK",
+          },
+        },
+        EXT_2: {
+          state_type: "EXTERNAL",
+          ref: "test-2",
+          transitions: {
+            Next: "END_FWD",
+            Prev: "END_BCK",
+          },
+        },
+        END_FWD: {
+          state_type: "END",
+          outcome: "FWD",
+        },
+        END_BCK: {
+          state_type: "END",
+          outcome: "BCK",
+        },
+      },
+    },
+  } as Flow);
+
+  let state = player.getState();
+  expect(state.status).toBe("in-progress");
+  expect(
+    (state as InProgressState).controllers.flow.current?.currentState?.name,
+  ).toBe("EXT_1");
+
+  // probably dumb way to wait for async stuff to resolve
+  await new Promise<void>((res) => {
+    /**
+     *
+     */
+    function waitForResolver() {
+      if (resolver) res();
+      else setTimeout(waitForResolver, 50);
+    }
+
+    waitForResolver();
+  });
+
+  (state as InProgressState).controllers.flow.transition("Next");
+
+  state = player.getState();
+  expect(
+    (state as InProgressState).controllers.flow.current?.currentState?.name,
+  ).toBe("EXT_2");
+
+  // Attempt to resolve _after_ Player has transitioned
+  resolver?.();
+
+  // Should be same as prev
+  state = player.getState();
+  expect(
+    (state as InProgressState).controllers.flow.current?.currentState?.name,
+  ).toBe("EXT_2");
+});
+
+describe("edge cases", () => {
+  test("async action nodes not transitioning from navigation states with *", async () => {
+    const player = new Player({
+      plugins: [
+        new ExternalStatePlugin([
+          {
+            ref: "view_1",
+            handlerFunction: () => {
+              return new Promise((resolve) => {
+                setTimeout(() => {
+                  resolve("next");
+                }, 100);
+              });
+            },
+          },
+        ]),
+      ],
+    });
+
+    player.hooks.expressionEvaluator.tap("test", (expEval) => {
+      expEval.addExpressionFunction("testAsync", async (ctx, name) => {
+        return new Promise((resolve) => {
+          setTimeout(() => {
+            resolve(name);
+          }, 10);
+        });
+      });
+    });
+
+    player.start({
+      id: "test-flow",
+      data: {
+        my: {
+          puppy: "Ginger",
+        },
+      },
+      views: [
+        {
+          id: "next",
+          type: "test",
+        },
+        {
+          id: "back",
+          type: "test",
+        },
+        {
+          id: "star",
+          type: "test",
+        },
+      ],
+      navigation: {
+        BEGIN: "FLOW_1",
+        FLOW_1: {
+          startState: "ACTION_1",
+          ACTION_1: {
+            state_type: "ASYNC_ACTION",
+            exp: "{{my.puppy}} = await(testAsync('Daisy'))",
+            transitions: {
+              Daisy: "EXTERNAL_1",
+            },
+            await: true,
+          },
+          EXTERNAL_1: {
+            state_type: "EXTERNAL",
+            ref: "view_1",
+            param: {
+              best: "{{my.puppy}}",
+            },
+            transitions: {
+              next: "VIEW_1",
+              back: "VIEW_2",
+              "*": "VIEW_3",
+            },
+          },
+          VIEW_1: {
+            state_type: "VIEW",
+            ref: "next",
+            transitions: {
+              "*": "END",
+            },
+          },
+          VIEW_2: {
+            state_type: "VIEW",
+            ref: "back",
+            transitions: {
+              "*": "END",
+            },
+          },
+          VIEW_3: {
+            state_type: "VIEW",
+            ref: "star",
+            transitions: {
+              "*": "END",
+            },
+          },
+        },
+      },
+    });
+
+    await vitest.waitFor(() =>
+      expect(player.getState().status).toBe("in-progress"),
+    );
+
+    let currentState: NamedState | undefined;
+
+    await waitFor(() => {
+      const state = player.getState();
+      currentState = (state as InProgressState).controllers.flow.current
+        ?.currentState;
+      expect(currentState?.name).toBe("EXTERNAL_1");
+    });
+
+    await waitFor(() => {
+      const state = player.getState();
+      currentState = (state as InProgressState).controllers.flow.current
+        ?.currentState;
+      expect(currentState?.name).toBe("VIEW_1");
+    });
+  });
+
+  test("no handler registered for external state - no transition occurs", async () => {
+    // Create a player with NO handlers registered
+    const player = new Player({
+      plugins: [
+        new ExternalStatePlugin([
+          // Register handler for a different ref - not matching our external state
+          { ref: "different-ref", handlerFunction: () => "Next" },
+        ]),
+      ],
+    });
+
+    const started = player.start(externalFlow as Flow);
+
+    // Wait for player to reach the external state
+    await vitest.waitFor(() =>
+      expect(player.getState().status).toBe("in-progress"),
+    );
+
+    // Get the current state
+    const state = player.getState() as InProgressState;
+    const currentState = state.controllers.flow.current?.currentState;
+
+    // Should be stuck on the external state
+    expect(currentState?.name).toBe("EXT_1");
+    expect(currentState?.value.state_type).toBe("EXTERNAL");
+
+    // Wait a bit to ensure no transition occurs
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    // Should still be on the external state (no transition occurred)
+    const laterState = player.getState() as InProgressState;
+    const laterCurrentState = laterState.controllers.flow.current?.currentState;
+    expect(laterCurrentState?.name).toBe("EXT_1");
+    expect(laterCurrentState?.value.state_type).toBe("EXTERNAL");
+
+    // Clean up - manually transition to end the flow
+    laterState.controllers.flow.transition("Next");
+    await started;
+  });
+});
+
+describe("Type Safety", () => {
+  test("handlers with superfluous match.ref should warn and be skipped", async () => {
+    const superflousHandlerCalled = vitest.fn();
+    const validHandlerCalled = vitest.fn();
+    const warnSpy = vitest.fn();
+
+    const player = new Player({
+      plugins: [
+        new ExternalStatePlugin([
+          // Handler with superfluous match.ref (TypeScript error suppressed for testing)
+          {
+            ref: "test-1",
+            // @ts-expect-error - testing runtime behavior with superfluous match.ref
+            match: { ref: "test-1", testProperty: "testValue" },
+            handlerFunction: () => {
+              superflousHandlerCalled();
+              return "Next";
+            },
+          },
+          // Valid handler - no match.ref
+          {
+            ref: "test-1",
+            handlerFunction: () => {
+              validHandlerCalled();
+              return "Next";
+            },
+          },
+        ]),
+      ],
+      logger: {
+        trace: vitest.fn(),
+        debug: vitest.fn(),
+        info: vitest.fn(),
+        warn: warnSpy,
+        error: vitest.fn(),
+      },
+    });
+
+    const completed = await player.start(externalFlow as Flow);
+
+    // Warning should have been logged for the handler with superfluous match.ref
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(warnSpy).toHaveBeenCalledWith(
+      'An ExternalStateHandler contains a superfluous \'match.ref\' property. \'match.ref\' will be ignored. \'ref\' will be used instead. Handler: {"ref":"test-1","match":{"ref":"test-1","testProperty":"testValue"}}',
+    );
+
+    // The handler with superfluous match.ref should NOT have been called (it was skipped)
+    expect(superflousHandlerCalled).not.toHaveBeenCalled();
+
+    // The valid handler should have been called
+    expect(validHandlerCalled).toHaveBeenCalledTimes(1);
+
+    // Flow should complete successfully using the valid handler
+    expect(completed.endState.outcome).toBe("FWD");
+  });
+});

package/src/index.ts

@@ -0,0 +1,176 @@
+import type {
+  Player,
+  PlayerPlugin,
+  InProgressState,
+  PlayerFlowState,
+  NavigationFlowState,
+  NavigationFlowExternalState,
+} from "@player-ui/player";
+import { Registry } from "@player-ui/partial-match-registry";
+import { ExternalStatePluginSymbol } from "./symbols.js";
+
+export type ExternalStateHandlerMatch = Record<string, unknown>;
+
+export type ExternalStateHandlerFunction = (
+  state: NavigationFlowExternalState,
+  options: InProgressState["controllers"],
+) => string | undefined | Promise<string | undefined>;
+
+export type ExternalStateHandler = {
+  /** The name of the external state. This will appear as it's "ref" property in the DSL. */
+  ref: string;
+  /** Additional properties to match against the external state. */
+  match?: ExternalStateHandlerMatch;
+  /** The function to run when the external state is transitioned to. This should return the `ref` of the next state to transition to. */
+  handlerFunction: ExternalStateHandlerFunction;
+};
+
+function isExternal(
+  state: NavigationFlowState,
+): state is NavigationFlowExternalState {
+  return state.state_type === "EXTERNAL";
+}
+
+function isInProgress(state: PlayerFlowState): state is InProgressState {
+  return state.status === "in-progress";
+}
+
+/**
+ * A plugin to handle external states
+ *
+ * This plugin uses a registry-based approach to match external states to handler functions.
+ * Multiple plugins can be registered, and handlers are matched using partial object matching
+ * with specificity ordering (more specific matches take precedence).
+ */
+export class ExternalStatePlugin implements PlayerPlugin {
+  name = "ExternalStatePlugin";
+
+  /** Symbol used to identify and find existing instances of this plugin */
+  static Symbol: symbol = ExternalStatePluginSymbol;
+  public readonly symbol: symbol = ExternalStatePlugin.Symbol;
+
+  /**
+   * The shared registry that maps external states to handlers.
+   * All plugin instances use the same registry.
+   */
+  private registry?: Registry<ExternalStateHandlerFunction>;
+
+  /**
+   * The handlers for this plugin instance.
+   */
+  private readonly handlers: ExternalStateHandler[];
+
+  /** Creates a new ExternalStatePlugin */
+  constructor(handlers: ExternalStateHandler[]) {
+    this.handlers = handlers;
+  }
+
+  apply(player: Player): void {
+    const isFirstInstance = this.createRegistry(player);
+    this.registerHandlers(player);
+
+    // Only the first instance should tap the hooks to avoid redundant taps
+    if (!isFirstInstance) {
+      return;
+    }
+
+    player.hooks.flowController.tap(this.name, (flowController) => {
+      flowController.hooks.flow.tap(this.name, (flow) => {
+        flow.hooks.afterTransition.tap(this.name, async (flowInstance) => {
+          const toState = flowInstance.currentState;
+          const currentState = player.getState();
+
+          if (
+            toState &&
+            toState.value &&
+            isExternal(toState.value) &&
+            isInProgress(currentState)
+          ) {
+            try {
+              const handler = this.registry?.get(toState.value);
+              const transitionValue = await handler?.(
+                toState.value,
+                currentState.controllers,
+              );
+
+              if (transitionValue !== undefined) {
+                const latestState = player.getState();
+
+                // Ensure the Player is still in the same state after waiting for transitionValue
+                if (
+                  isInProgress(latestState) &&
+                  latestState.controllers.flow.current?.currentState?.name ===
+                    toState.name
+                ) {
+                  latestState.controllers.flow.transition(transitionValue);
+                } else {
+                  player.logger.warn(
+                    `External state resolved with [${transitionValue}], but Player already navigated away from [${toState.name}]`,
+                  );
+                }
+              }
+            } catch (error) {
+              if (error instanceof Error) {
+                currentState.fail(error);
+              }
+            }
+          }
+        });
+      });
+    });
+  }
+
+  /**
+   * Create or share the registry for this plugin instance.
+   *
+   * Uses the Player's plugin registry to find if another instance of ExternalStatePlugin
+   * has already been registered. If found, this instance will share that plugin's registry.
+   * Otherwise, this instance creates a new registry.
+   */
+  private createRegistry(player: Player): boolean {
+    // Find the first instance of this plugin registered to the Player
+    const existing = player.findPlugin<ExternalStatePlugin>(
+      ExternalStatePluginSymbol,
+    );
+
+    // If we found a plugin and it's not ourselves, we are not the first plugin instance
+    if (existing && existing !== this) {
+      // Use the first plugin's registry
+      this.registry = existing.registry;
+      return false;
+    }
+
+    // We are the first plugin instance, create the registry
+    this.registry = new Registry<ExternalStateHandlerFunction>(
+      undefined,
+      player.logger,
+    );
+    return true;
+  }
+
+  /**
+   * Register this plugin's handlers to the shared registry.
+   *
+   * If a handler with the same specificity already exists, it will be replaced
+   * and a debug log will be emitted (accessible via player.logger.debug).
+   */
+  private registerHandlers(player: Player): void {
+    for (const handler of this.handlers) {
+      // Runtime check for 'ref' property is necessary despite TypeScript constraint because
+      // the Swift bridge allows improperly formatted objects to bypass TypeScript validation.
+      // We log this here and not in the constructor because the Logger is not yet available in the constructor.
+      if (handler.match?.ref) {
+        player.logger.warn(
+          `An ExternalStateHandler contains a superfluous 'match.ref' property. 'match.ref' will be ignored. 'ref' will be used instead. Handler: ${JSON.stringify({ ref: handler.ref, match: handler.match })}`,
+        );
+        delete handler.match?.["ref"];
+        continue;
+      }
+      // Registry will handle keeping only the last handlerFunction for each match
+      this.registry?.set(
+        { ref: handler.ref, ...handler.match },
+        handler.handlerFunction,
+      );
+    }
+  }
+}

package/src/symbols.ts

@@ -0,0 +1,4 @@
+// We prefix with "@player-ui" to avoid conflicts with symbols from other packages
+export const ExternalStatePluginSymbol: symbol = Symbol.for(
+  "@player-ui/ExternalStatePlugin",
+);