@player-ui/player 0.15.3 → 0.15.4--canary.881.37421

package/src/controllers/error/middleware.ts

@@ -0,0 +1,106 @@
+import type { BindingInstance } from "../../binding";
+import {
+  BatchSetTransaction,
+  DataModelImpl,
+  DataModelMiddleware,
+  DataModelOptions,
+  LocalModel,
+  Updates,
+} from "../../data";
+import type { Logger } from "../../logger";
+
+/** Top-level key for all error information. */
+export const ERROR_BINDING_PREFIX = "errorState";
+
+const isErrorBinding = (binding: BindingInstance): boolean =>
+  binding.asArray()[0] === ERROR_BINDING_PREFIX;
+
+/**
+ * Middleware that prevents external writes to errorState
+ * Only authorized callers (with the write symbol) can write to this path
+ */
+export class ErrorStateMiddleware implements DataModelMiddleware {
+  name = "error-state-middleware";
+
+  private logger?: Logger;
+  private writeSymbol: symbol;
+  // Internal model for error state to avoid data serialization
+  private dataModel: LocalModel = new LocalModel();
+
+  constructor(options: { logger?: Logger; writeSymbol: symbol }) {
+    this.logger = options.logger;
+    this.writeSymbol = options.writeSymbol;
+  }
+
+  public set(
+    transaction: BatchSetTransaction,
+    options?: DataModelOptions,
+    next?: DataModelImpl,
+  ): Updates {
+    // Filter out any writes to errorState
+    const filteredTransaction: BatchSetTransaction = [];
+    const errorTransaction: BatchSetTransaction = [];
+
+    transaction.forEach((transaction) => {
+      const [binding] = transaction;
+      const targetArray = isErrorBinding(binding)
+        ? errorTransaction
+        : filteredTransaction;
+
+      targetArray.push(transaction);
+    });
+
+    // Process allowed writes
+    const nonErrorResults = next?.set(filteredTransaction, options) ?? [];
+
+    const errorResults =
+      options?.writeSymbol === this.writeSymbol
+        ? this.dataModel.set(errorTransaction)
+        : errorTransaction.map((transaction) => {
+            const [binding] = transaction;
+            this.logger?.warn(
+              `[ErrorStateMiddleware] Blocked write to protected path: ${binding.asString()}`,
+            );
+
+            const oldValue = next?.get(binding, options);
+            return {
+              binding,
+              oldValue,
+              newValue: oldValue, // Keep old value
+              force: false,
+            };
+          });
+
+    return [...nonErrorResults, ...errorResults];
+  }
+
+  public get(
+    binding: BindingInstance,
+    options?: DataModelOptions,
+    next?: DataModelImpl,
+  ): unknown {
+    return isErrorBinding(binding)
+      ? this.dataModel.get(binding)
+      : next?.get(binding, options);
+  }
+
+  public delete(
+    binding: BindingInstance,
+    options?: DataModelOptions,
+    next?: DataModelImpl,
+  ): void {
+    if (!isErrorBinding(binding)) {
+      next?.delete(binding, options);
+      return;
+    }
+    // Block deletes to errorState namespace
+    if (options?.writeSymbol !== this.writeSymbol) {
+      this.logger?.warn(
+        `[ErrorStateMiddleware] Blocked delete of protected path: ${binding.asString()}`,
+      );
+      return;
+    }
+
+    this.dataModel.delete(binding);
+  }
+}

package/src/controllers/error/types.ts

@@ -0,0 +1,42 @@
+/** Severity levels */
+export enum ErrorSeverity {
+  FATAL = "fatal", // Cannot continue, flow must end
+  ERROR = "error", // Standard error, may allow recovery
+  WARNING = "warning", // Non-blocking, logged for telemetry
+}
+
+/** Known error types for Player */
+export const ErrorTypes = {
+  EXPRESSION: "expression",
+  BINDING: "binding",
+  VIEW: "view",
+  ASSET: "asset",
+  NAVIGATION: "navigation",
+  VALIDATION: "validation",
+  DATA: "data",
+  SCHEMA: "schema",
+  NETWORK: "network",
+  PLUGIN: "plugin",
+  RENDER: "render",
+  EXTERNAL_STATE: "externalState",
+} as const;
+
+/**
+ * Error metadata
+ */
+export interface ErrorMetadata {
+  /** Allow custom fields for domain-specific information */
+  [key: string]: unknown;
+}
+
+export interface PlayerErrorMetadata<
+  ErrorMetadataType extends ErrorMetadata = ErrorMetadata,
+> {
+  type: string;
+  severity?: ErrorSeverity;
+  metadata?: ErrorMetadataType;
+}
+
+export type PlayerError<
+  ErrorMetadataType extends ErrorMetadata = ErrorMetadata,
+> = Error & PlayerErrorMetadata<ErrorMetadataType>;

package/src/controllers/error/utils/__tests__/isErrorWithMetadata.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect } from "vitest";
+import { isErrorWithMetadata } from "../isErrorWithMetadata";
+import { ErrorSeverity } from "../../types";
+
+/** Test class to create an error with any additional properties */
+class ErrorWithProps extends Error implements Record<PropertyKey, unknown> {
+  [key: PropertyKey]: unknown;
+}
+
+const createTestError = (
+  additionalProps?: Record<PropertyKey, unknown>,
+): ErrorWithProps => {
+  const err: ErrorWithProps = new ErrorWithProps("Message");
+  if (additionalProps) {
+    for (const [key, val] of Object.entries(additionalProps)) {
+      err[key] = val;
+    }
+  }
+
+  return err;
+};
+
+describe("isErrorWithMetadata", () => {
+  const correctCases = [
+    createTestError({ type: "type" }),
+    createTestError({ type: "type", metadata: {} }),
+    createTestError({ type: "type", severity: ErrorSeverity.ERROR }),
+    createTestError({
+      type: "type",
+      metadata: {},
+      severity: ErrorSeverity.ERROR,
+    }),
+    createTestError({
+      type: "type",
+      metadata: {},
+      severity: ErrorSeverity.ERROR,
+      someUnknownProperty: "more data should not impact test case.",
+    }),
+  ];
+  it.each(correctCases)(
+    "should return true if type is present and all properties match their expected types.",
+    (err) => {
+      expect(isErrorWithMetadata(err)).toBe(true);
+    },
+  );
+
+  const badTypeCases = [
+    // `type` must be defined
+    createTestError({
+      metadata: {},
+      severity: ErrorSeverity.ERROR,
+    }),
+    // `type` must be a string
+    createTestError({
+      type: 100,
+      metadata: {},
+      severity: ErrorSeverity.ERROR,
+    }),
+  ];
+  it.each(badTypeCases)(
+    "should return false if type is not present or not a string",
+    (err) => {
+      expect(isErrorWithMetadata(err)).toBe(false);
+    },
+  );
+
+  const badSeverityCases = [
+    // `severity` must be a string
+    createTestError({
+      type: "type",
+      metadata: {},
+      severity: 100,
+    }),
+    // `severity` must be an option in the `ErrorSeverity` enum
+    createTestError({
+      type: "type",
+      metadata: {},
+      severity: "NotARealErrorSeverity",
+    }),
+  ];
+  it.each(badSeverityCases)(
+    "should return false if severity is not a value from the ErrorSeverity enum",
+    (err) => {
+      expect(isErrorWithMetadata(err)).toBe(false);
+    },
+  );
+
+  const badMetadataCases = [
+    // `metadata` must be an object
+    createTestError({
+      type: "type",
+      metadata: 100,
+      severity: ErrorSeverity.ERROR,
+    }),
+    // `metadata` cannot be an array
+    createTestError({
+      type: "type",
+      metadata: [],
+      severity: ErrorSeverity.ERROR,
+    }),
+    // `metadata` cannot be null
+    createTestError({
+      type: "type",
+      metadata: null,
+      severity: ErrorSeverity.ERROR,
+    }),
+  ];
+  it.each(badMetadataCases)(
+    "should return false if metadata is not an object",
+    (err) => {
+      expect(isErrorWithMetadata(err)).toBe(false);
+    },
+  );
+});

package/src/controllers/error/utils/__tests__/makeJsonStringifyReplacer.test.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect } from "vitest";
+import { makeJsonStringifyReplacer } from "../makeJsonStringifyReplacer";
+
+describe("makeJsonStringifyReplacer", () => {
+  it("should return [CIRCULAR] when the same object is used as the value multiple times", () => {
+    const val = {
+      prop: "value",
+    };
+    const fn = makeJsonStringifyReplacer();
+
+    expect(fn("", val)).toStrictEqual({
+      prop: "value",
+    });
+
+    expect(fn("", val)).toBe("[CIRCULAR]");
+  });
+
+  it("should return the value when it is not an object or is null", () => {
+    const fn = makeJsonStringifyReplacer();
+
+    expect(fn("", null)).toBeNull();
+    expect(fn("", "test")).toBe("test");
+  });
+});

package/src/controllers/error/utils/index.ts

@@ -0,0 +1,2 @@
+export * from "./isErrorWithMetadata";
+export * from "./makeJsonStringifyReplacer";

package/src/controllers/error/utils/isErrorWithMetadata.ts

@@ -0,0 +1,28 @@
+import { ErrorSeverity, PlayerError } from "../types";
+
+const SEVERITY_SET = new Set<string>(Object.values(ErrorSeverity));
+
+export const isErrorWithMetadata = (error: Error): error is PlayerError => {
+  // 1. "type" property must be present and a string
+  if (!("type" in error) || typeof error.type !== "string") {
+    return false;
+  }
+
+  // 2. "severity" property is optional. If present, must be a string within the set of severity options
+  if (
+    "severity" in error &&
+    error.severity !== undefined &&
+    (typeof error.severity !== "string" || !SEVERITY_SET.has(error.severity))
+  ) {
+    return false;
+  }
+
+  // 3. "metadata" property is optional. If present, must be a non-array object.
+  return (
+    !("metadata" in error) ||
+    error.metadata === undefined ||
+    (typeof error.metadata === "object" &&
+      error.metadata !== null &&
+      !Array.isArray(error.metadata))
+  );
+};

package/src/controllers/error/utils/makeJsonStringifyReplacer.ts

@@ -0,0 +1,17 @@
+type ReplacerFunction = (key: string, value: any) => any;
+
+/** Returns a function to be used as the `replacer` for JSON.stringify that tracks and ignores circular references. */
+export const makeJsonStringifyReplacer = (): ReplacerFunction => {
+  const cache = new Set();
+  return (_: string, value: any) => {
+    if (typeof value === "object" && value !== null) {
+      if (cache.has(value)) {
+        // Circular reference found, discard key
+        return "[CIRCULAR]";
+      }
+      // Store value in our collection
+      cache.add(value);
+    }
+    return value;
+  };
+};

package/src/controllers/flow/__tests__/flow.test.ts

@@ -379,3 +379,271 @@ test("fails if transitioning to unknown state", () => {
   flow.transition("Next");
   expect(flow.currentState?.name).toBe("View1");
 });
+
+describe("errorTransition", () => {
+  test("navigates using node-level errorTransitions", () => {
+    const flow = new FlowInstance("flow", {
+      startState: "View1",
+      View1: {
+        state_type: "VIEW",
+        ref: "view-1",
+        transitions: {
+          next: "End",
+        },
+        errorTransitions: {
+          network: "NetworkError",
+          validation: "ValidationError",
+        },
+      },
+      NetworkError: {
+        state_type: "VIEW",
+        ref: "network-error",
+        transitions: {},
+      },
+      ValidationError: {
+        state_type: "VIEW",
+        ref: "validation-error",
+        transitions: {},
+      },
+      End: {
+        state_type: "END",
+        outcome: "done",
+      },
+    });
+
+    flow.start();
+    flow.errorTransition("network");
+
+    expect(flow.currentState?.name).toBe("NetworkError");
+  });
+
+  test("uses wildcard in node-level errorTransitions", () => {
+    const flow = new FlowInstance("flow", {
+      startState: "View1",
+      View1: {
+        state_type: "VIEW",
+        ref: "view-1",
+        transitions: {},
+        errorTransitions: {
+          network: "NetworkError",
+          "*": "GenericError",
+        },
+      },
+      NetworkError: {
+        state_type: "VIEW",
+        ref: "network-error",
+        transitions: {},
+      },
+      GenericError: {
+        state_type: "VIEW",
+        ref: "generic-error",
+        transitions: {},
+      },
+    });
+
+    flow.start();
+    flow.errorTransition("unknown");
+
+    expect(flow.currentState?.name).toBe("GenericError");
+  });
+
+  test("falls back to flow-level errorTransitions", () => {
+    const flow = new FlowInstance("flow", {
+      startState: "View1",
+      errorTransitions: {
+        network: "NetworkError",
+        "*": "GenericError",
+      },
+      View1: {
+        state_type: "VIEW",
+        ref: "view-1",
+        transitions: {},
+      },
+      NetworkError: {
+        state_type: "VIEW",
+        ref: "network-error",
+        transitions: {},
+      },
+      GenericError: {
+        state_type: "VIEW",
+        ref: "generic-error",
+        transitions: {},
+      },
+    });
+
+    flow.start();
+    flow.errorTransition("network");
+
+    expect(flow.currentState?.name).toBe("NetworkError");
+  });
+
+  test("node-level errorTransitions takes priority over flow-level", () => {
+    const flow = new FlowInstance("flow", {
+      startState: "View1",
+      errorTransitions: {
+        network: "FlowNetworkError",
+      },
+      View1: {
+        state_type: "VIEW",
+        ref: "view-1",
+        transitions: {},
+        errorTransitions: {
+          network: "NodeNetworkError",
+        },
+      },
+      NodeNetworkError: {
+        state_type: "VIEW",
+        ref: "node-network-error",
+        transitions: {},
+      },
+      FlowNetworkError: {
+        state_type: "VIEW",
+        ref: "flow-network-error",
+        transitions: {},
+      },
+    });
+
+    flow.start();
+    flow.errorTransition("network");
+
+    expect(flow.currentState?.name).toBe("NodeNetworkError");
+  });
+
+  test("warns when no errorTransitions match", () => {
+    const logger = {
+      trace: vitest.fn(),
+      debug: vitest.fn(),
+      info: vitest.fn(),
+      warn: vitest.fn(),
+      error: vitest.fn(),
+    };
+
+    const flow = new FlowInstance(
+      "flow",
+      {
+        startState: "View1",
+        View1: {
+          state_type: "VIEW",
+          ref: "view-1",
+          transitions: {},
+        },
+      },
+      { logger },
+    );
+
+    flow.start();
+    flow.errorTransition("network");
+
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.stringContaining("No errorTransition found"),
+    );
+    expect(flow.currentState?.name).toBe("View1");
+  });
+
+  test("cannot transition from END state", () => {
+    const logger = {
+      trace: vitest.fn(),
+      debug: vitest.fn(),
+      info: vitest.fn(),
+      warn: vitest.fn(),
+      error: vitest.fn(),
+    };
+
+    const flow = new FlowInstance(
+      "flow",
+      {
+        startState: "End",
+        errorTransitions: {
+          network: "ErrorView",
+        },
+        End: {
+          state_type: "END",
+          outcome: "done",
+        },
+        ErrorView: {
+          state_type: "VIEW",
+          ref: "error-view",
+          transitions: {},
+        },
+      },
+      { logger },
+    );
+
+    flow.start();
+    flow.errorTransition("network");
+
+    expect(logger.warn).toHaveBeenCalledWith(
+      "Cannot error transition from END state",
+    );
+    expect(flow.currentState?.name).toBe("End");
+  });
+
+  test("uses flow-level errorTransitions when no currentState", () => {
+    const flow = new FlowInstance("flow", {
+      startState: "View1",
+      errorTransitions: {
+        init: "ErrorView",
+      },
+      View1: {
+        state_type: "VIEW",
+        ref: "view-1",
+        transitions: {},
+      },
+      ErrorView: {
+        state_type: "VIEW",
+        ref: "error-view",
+        transitions: {},
+      },
+    });
+
+    // Don't call flow.start() - no currentState
+    flow.errorTransition("init");
+
+    // Should navigate to ErrorView via flow-level errorTransitions
+    expect(flow.currentState?.name).toBe("ErrorView");
+  });
+});
+
+describe("getErrorTransitionState", () => {
+  test("should return true when the error exists", () => {
+    const flow = new FlowInstance("flow", {
+      startState: "View1",
+      errorTransitions: {
+        init: "ErrorView",
+      },
+      View1: {
+        state_type: "VIEW",
+        ref: "view-1",
+        transitions: {},
+      },
+      ErrorView: {
+        state_type: "VIEW",
+        ref: "error-view",
+        transitions: {},
+      },
+    });
+
+    expect(flow.getErrorTransitionState("init")).toBe("ErrorView");
+  });
+
+  test("should return false when the error does not exist", () => {
+    const flow = new FlowInstance("flow", {
+      startState: "View1",
+      errorTransitions: {
+        init: "ErrorView",
+      },
+      View1: {
+        state_type: "VIEW",
+        ref: "view-1",
+        transitions: {},
+      },
+      ErrorView: {
+        state_type: "VIEW",
+        ref: "error-view",
+        transitions: {},
+      },
+    });
+
+    expect(flow.getErrorTransitionState("not-init")).toBe(undefined);
+  });
+});