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

package/src/controllers/flow/flow.ts

@@ -150,10 +150,98 @@ export class FlowInstance {
     return this.flowPromise.promise;
   }
 
+  /**
+   * Get the flow-level error transitions map
+   */
+  public getFlowErrorTransitions(): Record<string, string> | undefined {
+    return this.flow.errorTransitions;
+  }
+
+  /**
+   * Helper to lookup a key in a map with wildcard fallback
+   */
+  private lookupInMap(
+    map: Record<string, string> | undefined,
+    key: string,
+  ): string | undefined {
+    if (!map) return undefined;
+    return map[key] || map["*"];
+  }
+
+  /** Check if the flow has a transition for the given error type in its current state. */
+  public getErrorTransitionState(errorType: string): string | undefined {
+    // Can't navigate from END state
+    if (this.currentState?.value.state_type === "END") {
+      this.log?.warn("Cannot error transition from END state");
+      return undefined;
+    }
+
+    // Try node-level errorTransitions (only if we have a current state)
+    if (this.currentState) {
+      const nodeState = this.lookupInMap(
+        this.currentState.value.errorTransitions,
+        errorType,
+      );
+
+      if (nodeState) {
+        if (!Object.prototype.hasOwnProperty.call(this.flow, nodeState)) {
+          this.log?.debug(
+            `Node-level errorTransition references non-existent state "${nodeState}", trying flow-level fallback`,
+          );
+          // Fall through to try flow-level
+        } else {
+          this.log?.debug(
+            `Error transition (node-level) from ${this.currentState.name} to ${nodeState} using ${errorType}`,
+          );
+          return nodeState;
+        }
+      }
+    }
+
+    // Try flow-level errorTransitions
+    const flowState = this.lookupInMap(this.flow.errorTransitions, errorType);
+
+    if (flowState) {
+      // Validate state exists before navigating
+      if (!Object.prototype.hasOwnProperty.call(this.flow, flowState)) {
+        this.log?.debug(
+          `Flow-level errorTransition references non-existent state "${flowState}"`,
+        );
+        // No valid transition found, will warn below
+      } else {
+        this.log?.debug(
+          `Error transition (flow-level) to ${flowState} using ${errorType}${this.currentState ? ` from ${this.currentState.name}` : ""}`,
+        );
+        return flowState;
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Navigate using errorTransitions map.
+   * Tries node-level first, then falls back to flow-level.
+   * Bypasses validation hooks and expression resolution.
+   * @throws Error if errorTransitions references a non-existent state
+   */
+  public errorTransition(errorType: string): void {
+    const transitionState = this.getErrorTransitionState(errorType);
+    if (transitionState === undefined) {
+      this.log?.warn(
+        `No errorTransition found for ${errorType} (checked node and flow level)`,
+      );
+      return;
+    }
+
+    this.pushHistory(transitionState);
+  }
+
   public transition(
     transitionValue: string,
     options?: TransitionOptions,
   ): void {
+    // Check if we can transition
     if (this.isTransitioning) {
       throw new Error(
         `Transitioning while ongoing transition from ${this.currentState?.name} is in progress is not supported`,
@@ -162,9 +250,8 @@ export class FlowInstance {
 
     if (this.currentState?.value.state_type === "END") {
       this.log?.warn(
-        `Skipping transition using ${transitionValue}. Already at and END state`,
+        `Skipping transition using ${transitionValue}. Already at END state`,
       );
-
       return;
     }
 
@@ -172,6 +259,9 @@ export class FlowInstance {
       throw new Error("Cannot transition when there's no current state");
     }
 
+    const currentState = this.currentState.value;
+
+    // For normal transitions: use hooks
     if (options?.force) {
       this.log?.debug(`Forced transition. Skipping validation checks`);
     } else {
@@ -186,7 +276,7 @@ export class FlowInstance {
     }
 
     const state = this.hooks.beforeTransition.call(
-      this.currentState.value,
+      currentState as Exclude<NavigationFlowState, NavigationFlowEndState>,
       transitionValue,
     );
 
@@ -232,7 +322,9 @@ export class FlowInstance {
     const prevState = this.currentState;
 
     this.isTransitioning = true;
-    nextState = this.hooks.resolveTransitionNode.call(nextState);
+    nextState = this.hooks.resolveTransitionNode.call(
+      nextState as NavigationFlowState,
+    );
 
     const newCurrentState = {
       name: stateName,

package/src/controllers/index.ts

@@ -3,3 +3,4 @@ export * from "./validation";
 export * from "./view";
 export * from "./data/controller";
 export * from "./constants";
+export * from "./error";

package/src/controllers/view/controller.ts

@@ -22,6 +22,7 @@ import type { DataController } from "../data/controller";
 import type { TransformRegistry } from "./types";
 import type { BindingInstance } from "../../binding";
 import type { Node } from "../../view";
+import { ErrorController } from "../error";
 
 export interface ViewControllerOptions {
   /** Where to get data from */
@@ -32,6 +33,9 @@ export interface ViewControllerOptions {
 
   /** A flow-controller instance to listen for view changes */
   flowController: FlowController;
+
+  /** Error controller to use when managing view-level errors */
+  errorController: ErrorController;
 }
 
 export type ViewControllerHooks = {
@@ -104,7 +108,7 @@ export class ViewController {
         if (this.optimizeUpdates) {
           this.queueUpdate(updates, undefined, silent);
         } else {
-          this.currentView.update();
+          this.updateView();
         }
       }
     };
@@ -158,11 +162,26 @@ export class ViewController {
       queueMicrotask(() => {
         const { changedBindings, changedNodes } = this.pendingUpdate ?? {};
         this.pendingUpdate = undefined;
-        this.currentView?.update(changedBindings, changedNodes);
+        this.updateView(changedBindings, changedNodes);
       });
     }
   }
 
+  private updateView(
+    changedBindings?: Set<BindingInstance>,
+    changedNodes?: Set<Node.Node>,
+  ) {
+    try {
+      this.currentView?.update(changedBindings, changedNodes);
+    } catch (exception: unknown) {
+      const err =
+        exception instanceof Error ? exception : new Error(String(exception));
+      // Can't assume any node or binding changes were consumed correctly during the update, so trigger a silent update to ensure that any additional update triggered to recover still updates everything.
+      this.queueUpdate(changedBindings, changedNodes, true);
+      this.viewOptions.errorController.captureError(err);
+    }
+  }
+
   private getViewForRef(viewRef: string): View | undefined {
     // First look for a 1:1 viewRef -> id mapping (this is most common)
     if (this.viewMap[viewRef]) {
@@ -204,7 +223,7 @@ export class ViewController {
     // own listeners to the view before we resolve it
     this.applyViewPlugins(view);
     this.hooks.view.call(view);
-    view.update();
+    this.updateView();
   }
 
   private applyViewPlugins(view: ViewInstance): void {

package/src/data/model.ts

@@ -46,6 +46,12 @@ export interface DataModelOptions {
    */
   silent?: boolean;
 
+  /**
+   * Write authorization symbol for internal middleware operations
+   * Middleware can use this to verify the caller has permission for write operations
+   */
+  writeSymbol?: symbol;
+
   /** Other context associated with this request */
   context?: {
     /** The data model to use when getting other data from the context of this request */

package/src/expressions/types.ts

@@ -129,13 +129,15 @@ export interface LiteralNode extends BaseNode<"Literal"> {
 }
 
 export interface BinaryNode
-  extends BaseNode<"BinaryExpression">, DirectionalNode {
+  extends BaseNode<"BinaryExpression">,
+    DirectionalNode {
   /** The operation to perform on the nodes */
   operator: string;
 }
 
 export interface LogicalNode
-  extends BaseNode<"LogicalExpression">, DirectionalNode {
+  extends BaseNode<"LogicalExpression">,
+    DirectionalNode {
   /** The logical operation to perform on the nodes */
   operator: string;
 }
@@ -177,7 +179,8 @@ export interface MemberExpressionNode extends BaseNode<"MemberExpression"> {
   property: ExpressionNode;
 }
 
-export interface ConditionalExpressionNode extends BaseNode<"ConditionalExpression"> {
+export interface ConditionalExpressionNode
+  extends BaseNode<"ConditionalExpression"> {
   /** The test for the ternary */
   test: ExpressionNode;
 
@@ -214,7 +217,8 @@ export interface IdentifierNode extends BaseNode<"Identifier"> {
 export type AssignmentNode = BaseNode<"Assignment"> & DirectionalNode;
 
 export interface ModificationNode
-  extends BaseNode<"Modification">, DirectionalNode {
+  extends BaseNode<"Modification">,
+    DirectionalNode {
   /** The operator for the modification */
   operator: string;
 }

package/src/player.ts

@@ -19,6 +19,7 @@ import {
   DataController,
   ValidationController,
   FlowController,
+  ErrorController,
 } from "./controllers";
 import { FlowExpPlugin } from "./plugins/flow-exp-plugin";
 import { DefaultExpPlugin } from "./plugins/default-exp-plugin";
@@ -119,6 +120,7 @@ export class Player {
     schema: new SyncHook<[SchemaController]>(),
     validationController: new SyncHook<[ValidationController]>(),
     bindingParser: new SyncHook<[BindingParser]>(),
+    errorController: new SyncHook<[ErrorController]>(),
     state: new SyncHook<[PlayerFlowState]>(),
     onStart: new SyncHook<[Flow]>(),
     onEnd: new SyncHook<[]>(),
@@ -245,9 +247,20 @@ export class Player {
 
     this.hooks.validationController.call(validationController);
 
+    const errorController = new ErrorController({
+      logger: this.logger,
+      flow: flowController,
+      fail: flowResultDeferred.reject,
+    });
+
+    this.hooks.errorController.call(errorController);
+
     dataController = new DataController(userFlow.data, {
       pathResolver,
-      middleware: validationController.getDataMiddleware(),
+      middleware: [
+        ...validationController.getDataMiddleware(),
+        errorController.getDataMiddleware(),
+      ],
       logger: this.logger,
     });
 
@@ -268,6 +281,10 @@ export class Player {
       (binding) => schema.getApparentType(binding)?.default,
     );
 
+    errorController.setOptions({
+      model: dataController,
+    });
+
     // eslint-disable-next-line prefer-const
     let viewController: ViewController;
 
@@ -447,6 +464,7 @@ export class Player {
         type: (b) => schema.getType(parseBinding(b)),
       },
       constants: this.constantsController,
+      errorController,
     });
 
     viewController.hooks.view.tap("player", (view) => {
@@ -486,6 +504,7 @@ export class Player {
           expression: expressionEvaluator,
           binding: pathResolver,
           validation: validationController,
+          error: errorController,
         },
         fail: flowResultDeferred.reject,
         flow: userFlow,

package/src/types.ts

@@ -8,6 +8,7 @@ import type {
   DataController,
   ValidationController,
   FlowController,
+  ErrorController,
 } from "./controllers";
 import type { ReadOnlyDataController } from "./controllers/data/utils";
 import { SyncHook, SyncWaterfallHook } from "tapable-ts";
@@ -33,6 +34,8 @@ export interface PlayerHooks {
   validationController: SyncHook<[ValidationController], Record<string, any>>;
   /** Manages parsing binding */
   bindingParser: SyncHook<[BindingParser], Record<string, any>>;
+  /** Manages error handling and captures errors from all subsystems */
+  errorController: SyncHook<[ErrorController], Record<string, any>>;
   /** A that's called for state changes in the flow execution */
   state: SyncHook<[PlayerFlowState], Record<string, any>>;
   /** A hook to access the current flow */
@@ -97,6 +100,9 @@ export interface ControllerState {
 
   /** the manager for the flow state machine */
   flow: FlowController;
+
+  /** The manager for error handling */
+  error: ErrorController;
 }
 
 /** A flow is currently executing */

package/src/validator/types.ts

@@ -23,7 +23,8 @@ interface BaseValidationResponse<T = Validation.Severity> {
   blocking?: boolean | "once";
 }
 
-export interface WarningValidationResponse extends BaseValidationResponse<"warning"> {
+export interface WarningValidationResponse
+  extends BaseValidationResponse<"warning"> {
   /** Warning validations can be dismissed without correcting the error */
   dismiss?: () => void;
 }

package/src/view/parser/types.ts

@@ -43,13 +43,15 @@ export declare namespace Node {
   }
 
   export interface Asset<T extends AnyAssetType = AnyAssetType>
-    extends BaseWithChildren<NodeType.Asset>, PluginOptions {
+    extends BaseWithChildren<NodeType.Asset>,
+      PluginOptions {
     /** Any asset nested within a view */
     value: T;
   }
 
   export interface View<T extends AnyAssetType = AnyAssetType>
-    extends BaseWithChildren<NodeType.View>, PluginOptions {
+    extends BaseWithChildren<NodeType.View>,
+      PluginOptions {
     /** The root of the parsed view */
     value: T;
   }
@@ -80,7 +82,8 @@ export declare namespace Node {
   }
 
   export interface Value
-    extends BaseWithChildren<NodeType.Value>, PluginOptions {
+    extends BaseWithChildren<NodeType.Value>,
+      PluginOptions {
     /** A simple node representing a value */
     value: any;
   }

package/src/view/plugins/__tests__/template.test.ts

@@ -7,8 +7,13 @@ import { SchemaController } from "../../../schema";
 import { Parser } from "../../parser";
 import { ViewInstance } from "../../view";
 import type { Options } from "../options";
-import { TemplatePlugin, MultiNodePlugin, AssetPlugin } from "../";
-import { StringResolverPlugin, toNodeResolveOptions } from "../..";
+import {
+  TemplatePlugin,
+  MultiNodePlugin,
+  AssetPlugin,
+  StringResolverPlugin,
+} from "../";
+import { toNodeResolveOptions } from "../../resolver";
 import type { View } from "@player-ui/types";
 
 const templateJoinValues = {

package/src/view/resolver/ResolverError.ts

@@ -0,0 +1,25 @@
+import { Node } from "../parser";
+import {
+  ErrorSeverity,
+  ErrorTypes,
+  type PlayerErrorMetadata,
+} from "../../controllers";
+import type { ResolverErrorMetadata, ResolverStage } from "./types";
+
+/** Error class to represent errors in the player resolver. */
+export class ResolverError extends Error implements PlayerErrorMetadata {
+  readonly type: string = ErrorTypes.VIEW;
+  readonly severity: ErrorSeverity = ErrorSeverity.ERROR;
+  readonly metadata: ResolverErrorMetadata;
+
+  constructor(
+    public readonly cause: unknown,
+    public readonly stage: ResolverStage,
+    node: Node.Node,
+  ) {
+    super(`An error in the resolver occurred at stage '${stage}'`);
+    this.metadata = {
+      node,
+    };
+  }
+}

package/src/view/resolver/__tests__/index.test.ts

@@ -3,7 +3,7 @@ import { BindingParser } from "../../../binding";
 import { ExpressionEvaluator } from "../../../expressions";
 import { LocalModel, withParser } from "../../../data";
 import { SchemaController } from "../../../schema";
-import { Resolve, Resolver } from "..";
+import { Resolve, Resolver, ResolverError } from "..";
 import type { Node } from "../../parser";
 import { NodeType, Parser } from "../../parser";
 
@@ -137,3 +137,55 @@ describe("Node cache updates", () => {
     );
   });
 });
+
+describe("error handling", () => {
+  let resolverOptions: Resolve.ResolverOptions;
+
+  beforeEach(() => {
+    const model = new LocalModel({});
+    const parser = new Parser();
+    const bindingParser = new BindingParser();
+
+    resolverOptions = {
+      model,
+      parseBinding: bindingParser.parse.bind(bindingParser),
+      parseNode: parser.parseObject.bind(parser),
+      evaluator: new ExpressionEvaluator({
+        model: withParser(model, bindingParser.parse),
+      }),
+      schema: new SchemaController(),
+    };
+  });
+
+  const computeTreeHooks: Array<keyof Resolver["hooks"]> = [
+    "afterNodeUpdate",
+    "afterResolve",
+    "beforeResolve",
+    "resolve",
+    "resolveOptions",
+    "skipResolve",
+  ];
+  it.each(computeTreeHooks)(
+    "should wrap errors in hooks in a ResolverError",
+    (hook) => {
+      const resolver = new Resolver(simpleViewWithAsync, resolverOptions);
+
+      resolver.hooks[hook].tap("test", () => {
+        throw new Error("ERROR!");
+      });
+
+      let error: unknown;
+      try {
+        resolver.update();
+      } catch (err: unknown) {
+        error = err;
+      }
+
+      expect(error).toBeDefined();
+      expect(error).toBeInstanceOf(ResolverError);
+      const resolverError = error as ResolverError;
+      expect(resolverError.cause).toStrictEqual(new Error("ERROR!"));
+      expect(resolverError.stage).toStrictEqual(hook);
+    },
+  );
+});

package/src/view/resolver/index.ts

@@ -12,11 +12,13 @@ import { DependencyModel, withParser } from "../../data";
 import type { Logger } from "../../logger";
 import { Node, NodeType } from "../parser";
 import { caresAboutDataChanges, toNodeResolveOptions } from "./utils";
-import type { Resolve } from "./types";
+import { ResolverStage, type Resolve } from "./types";
 import { getNodeID } from "../parser/utils";
+import { ResolverError } from "./ResolverError";
 
 export * from "./types";
 export * from "./utils";
+export * from "./ResolverError";
 
 interface NodeUpdate extends Resolve.ResolvedNode {
   /** A flag to track if a node has changed since the last resolution */
@@ -252,36 +254,44 @@ export class Resolver {
     nodeChanges: Set<Node.Node>,
   ): NodeUpdate {
     const dependencyModel = new DependencyModel(options.data.model);
-
     dependencyModel.trackSubset("core");
     const depModelWithParser = withContext(
       withParser(dependencyModel, this.options.parseBinding),
     );
 
-    const resolveOptions = this.hooks.resolveOptions.call(
-      {
-        ...options,
-        data: {
-          ...options.data,
-          model: depModelWithParser,
-        },
-        evaluate: (exp) =>
-          this.options.evaluator.evaluate(exp, { model: depModelWithParser }),
-        node,
+    let resolveOptions: Resolve.NodeResolveOptions = {
+      ...options,
+      data: {
+        ...options.data,
+        model: depModelWithParser,
       },
+      evaluate: (exp) =>
+        this.options.evaluator.evaluate(exp, { model: depModelWithParser }),
       node,
-    );
+    };
+
+    try {
+      resolveOptions = this.hooks.resolveOptions.call(resolveOptions, node);
+    } catch (err: unknown) {
+      throw new ResolverError(err, ResolverStage.ResolveOptions, node);
+    }
 
     const previousResult = this.getPreviousResult(node);
     const previousDeps = previousResult?.dependencies;
 
     const isChanged = nodeChanges.has(node);
     const dataChanged = caresAboutDataChanges(dataChanges, previousDeps);
-    const shouldUseLastValue = this.hooks.skipResolve.call(
-      !dataChanged && !isChanged,
-      node,
-      resolveOptions,
-    );
+    let shouldUseLastValue = !dataChanged && !isChanged;
+
+    try {
+      shouldUseLastValue = this.hooks.skipResolve.call(
+        shouldUseLastValue,
+        node,
+        resolveOptions,
+      );
+    } catch (err: unknown) {
+      throw new ResolverError(err, ResolverStage.SkipResolve, node);
+    }
 
     if (previousResult && shouldUseLastValue) {
       const update = {
@@ -325,7 +335,11 @@ export class Resolver {
           resolvedASTLocal.values.forEach(handleChildNode);
         }
 
-        this.hooks.afterNodeUpdate.call(AST, ASTParent, resolvedUpdate);
+        try {
+          this.hooks.afterNodeUpdate.call(AST, ASTParent, resolvedUpdate);
+        } catch (err: unknown) {
+          throw new ResolverError(err, ResolverStage.AfterNodeUpdate, node);
+        }
       };
 
       // Point the root of the cached node to the new resolved node.
@@ -338,16 +352,20 @@ export class Resolver {
 
     // Shallow clone the node so that changes to it during the resolve steps don't impact the original.
     // We are trusting that this becomes a deep clone once the whole node tree has been traversed.
-    const clonedNode: Node.Node = {
+    let resolvedAST: Node.Node = {
       ...this.cloneNode(node),
       parent: partiallyResolvedParent,
     };
-    const resolvedAST = this.hooks.beforeResolve.call(
-      clonedNode,
-      resolveOptions,
-    ) ?? {
-      type: NodeType.Empty,
-    };
+    try {
+      resolvedAST = this.hooks.beforeResolve.call(
+        resolvedAST,
+        resolveOptions,
+      ) ?? {
+        type: NodeType.Empty,
+      };
+    } catch (err: unknown) {
+      throw new ResolverError(err, ResolverStage.BeforeResolve, node);
+    }
 
     resolvedAST.parent = partiallyResolvedParent;
 
@@ -355,11 +373,16 @@ export class Resolver {
 
     this.ASTMap.set(resolvedAST, node);
 
-    let resolved = this.hooks.resolve.call(
-      undefined,
-      resolvedAST,
-      resolveOptions,
-    );
+    let resolved: any = undefined;
+    try {
+      resolved = this.hooks.resolve.call(
+        undefined,
+        resolvedAST,
+        resolveOptions,
+      );
+    } catch (err: unknown) {
+      throw new ResolverError(err, ResolverStage.Resolve, node);
+    }
 
     let updated = !dequal(previousResult?.value, resolved);
 
@@ -449,11 +472,15 @@ export class Resolver {
       resolved = previousResult?.value;
     }
 
-    resolved = this.hooks.afterResolve.call(resolved, resolvedAST, {
-      ...resolveOptions,
-      getDependencies: (scope?: "core" | "children") =>
-        dependencyModel.getDependencies(scope),
-    });
+    try {
+      resolved = this.hooks.afterResolve.call(resolved, resolvedAST, {
+        ...resolveOptions,
+        getDependencies: (scope?: "core" | "children") =>
+          dependencyModel.getDependencies(scope),
+      });
+    } catch (err: unknown) {
+      throw new ResolverError(err, ResolverStage.AfterResolve, node);
+    }
 
     const update: NodeUpdate = {
       node: resolvedAST,
@@ -465,7 +492,11 @@ export class Resolver {
       ]),
     };
 
-    this.hooks.afterNodeUpdate.call(node, rawParent, update);
+    try {
+      this.hooks.afterNodeUpdate.call(node, rawParent, update);
+    } catch (err: unknown) {
+      throw new ResolverError(err, ResolverStage.AfterNodeUpdate, node);
+    }
     cacheUpdate.set(node, update);
 
     return update;

package/src/view/resolver/types.ts

@@ -200,3 +200,16 @@ export declare namespace Resolve {
     afterResolve?: NodeResolveFunction;
   }
 }
+
+export enum ResolverStage {
+  ResolveOptions = "resolveOptions",
+  SkipResolve = "skipResolve",
+  BeforeResolve = "beforeResolve",
+  Resolve = "resolve",
+  AfterResolve = "afterResolve",
+  AfterNodeUpdate = "afterNodeUpdate",
+}
+
+export type ResolverErrorMetadata = {
+  node: Node.Node;
+};