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

package/src/view/resolver/utils.ts

@@ -7,7 +7,7 @@ import type { Resolve } from "./types";
 export function caresAboutDataChanges(
   dataChanges?: Set<BindingInstance>,
   dependencies?: Set<BindingInstance>,
-) {
+): boolean {
   if (!dataChanges || !dependencies) {
     return true;
   }

package/types/controllers/data/utils.d.ts

@@ -1,14 +1,10 @@
 import type { DataController } from ".";
-import type { Logger } from "../../logger";
 import type { BindingLike } from "../../binding";
-import type { DataModelWithParser, DataModelOptions, Updates } from "../../data";
+import type { DataModelWithParser, DataModelOptions } from "../../data";
 /** Wrapper for the Data Controller Class that prevents writes */
-export declare class ReadOnlyDataController implements DataModelWithParser<DataModelOptions> {
+export declare class ReadOnlyDataController implements Pick<DataModelWithParser<DataModelOptions>, "get"> {
     private controller;
-    private logger?;
-    constructor(controller: DataController, logger?: Logger);
+    constructor(controller: DataController);
     get(binding: BindingLike, options?: DataModelOptions | undefined): any;
-    set(transaction: [BindingLike, any][], options?: DataModelOptions | undefined): Updates;
-    delete(binding: BindingLike, options?: DataModelOptions | undefined): void;
 }
 //# sourceMappingURL=utils.d.ts.map

package/types/controllers/error/controller.d.ts

@@ -0,0 +1,82 @@
+import { SyncBailHook } from "tapable-ts";
+import type { Logger } from "../../logger";
+import type { DataController } from "../data/controller";
+import type { FlowController } from "../flow/controller";
+import type { PlayerError } from "./types";
+import { ErrorStateMiddleware } from "./middleware";
+export interface ErrorControllerHooks {
+    /**
+     * Fired when any error is captured
+     * - Called in order for each tapped plugin
+     * - Return true to bail and prevent error state navigation
+     * - Return undefined/false to continue to next handler
+     * - Once true is returned, no further plugins are called
+     */
+    onError: SyncBailHook<[PlayerError], boolean | undefined>;
+}
+export interface ErrorControllerOptions {
+    /** Logger for error operations */
+    logger: Logger;
+    /** Flow controller for error navigation */
+    flow: FlowController;
+    /** Callback to fail/reject the flow */
+    fail: (error: Error) => void;
+    /** Data model for setting errorState (can be set later via setOptions) */
+    model?: DataController;
+}
+/** The orchestrator for player error handling */
+export declare class ErrorController {
+    hooks: ErrorControllerHooks;
+    private options;
+    private readonly middleware;
+    /**
+     * Complete history of all captured errors in chronological order
+     * Newest errors are APPENDED to the end of the array
+     */
+    private errorHistory;
+    private currentError?;
+    constructor(options: ErrorControllerOptions);
+    /**
+     * Get the middleware for protecting errorState
+     * This should be added to DataController's middleware array
+     */
+    getDataMiddleware(): ErrorStateMiddleware;
+    /**
+     * Set the DataController after initialization
+     */
+    setOptions(options: Pick<ErrorControllerOptions, "model">): void;
+    /**
+     * Capture an error and try to recover. Errors implementing the `PlayerErrorMetadata` interface will be added to history, fire hooks and update data model. As a fallback, all errors will try to trigger an errorTransition. If the error does not have a `type` property, it will default to only using the wildcard navigation.
+     */
+    captureError(error: Error): boolean;
+    /**
+     * Navigate to error state using errorTransitions.
+     * Uses errorTransition() which handles node-level and flow-level fallback internally.
+     */
+    private tryNavigateToErrorState;
+    /**
+     * Get most recent error
+     */
+    getCurrentError(): PlayerError | undefined;
+    /**
+     * Get error history (read-only)
+     */
+    getErrors(): ReadonlyArray<PlayerError>;
+    /**
+     * Clear all errors (history + current + data model)
+     */
+    clearErrors(): void;
+    /**
+     * Clear only current error and remove from data model, preserve history
+     */
+    clearCurrentError(): void;
+    /**
+     * Write error to data model errorState
+     */
+    private setErrorInDataModel;
+    /**
+     * Remove errorState from data model
+     */
+    private deleteErrorFromDataModel;
+}
+//# sourceMappingURL=controller.d.ts.map

package/types/controllers/error/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./controller";
+export * from "./types";
+export * from "./middleware";
+//# sourceMappingURL=index.d.ts.map

package/types/controllers/error/middleware.d.ts

@@ -0,0 +1,23 @@
+import type { BindingInstance } from "../../binding";
+import { BatchSetTransaction, DataModelImpl, DataModelMiddleware, DataModelOptions, Updates } from "../../data";
+import type { Logger } from "../../logger";
+/** Top-level key for all error information. */
+export declare const ERROR_BINDING_PREFIX = "errorState";
+/**
+ * Middleware that prevents external writes to errorState
+ * Only authorized callers (with the write symbol) can write to this path
+ */
+export declare class ErrorStateMiddleware implements DataModelMiddleware {
+    name: string;
+    private logger?;
+    private writeSymbol;
+    private dataModel;
+    constructor(options: {
+        logger?: Logger;
+        writeSymbol: symbol;
+    });
+    set(transaction: BatchSetTransaction, options?: DataModelOptions, next?: DataModelImpl): Updates;
+    get(binding: BindingInstance, options?: DataModelOptions, next?: DataModelImpl): unknown;
+    delete(binding: BindingInstance, options?: DataModelOptions, next?: DataModelImpl): void;
+}
+//# sourceMappingURL=middleware.d.ts.map

package/types/controllers/error/types.d.ts

@@ -0,0 +1,35 @@
+/** Severity levels */
+export declare enum ErrorSeverity {
+    FATAL = "fatal",// Cannot continue, flow must end
+    ERROR = "error",// Standard error, may allow recovery
+    WARNING = "warning"
+}
+/** Known error types for Player */
+export declare const ErrorTypes: {
+    readonly EXPRESSION: "expression";
+    readonly BINDING: "binding";
+    readonly VIEW: "view";
+    readonly ASSET: "asset";
+    readonly NAVIGATION: "navigation";
+    readonly VALIDATION: "validation";
+    readonly DATA: "data";
+    readonly SCHEMA: "schema";
+    readonly NETWORK: "network";
+    readonly PLUGIN: "plugin";
+    readonly RENDER: "render";
+    readonly EXTERNAL_STATE: "externalState";
+};
+/**
+ * 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>;
+//# sourceMappingURL=types.d.ts.map

package/types/controllers/error/utils/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./isErrorWithMetadata";
+export * from "./makeJsonStringifyReplacer";
+//# sourceMappingURL=index.d.ts.map

package/types/controllers/error/utils/isErrorWithMetadata.d.ts

@@ -0,0 +1,3 @@
+import { PlayerError } from "../types";
+export declare const isErrorWithMetadata: (error: Error) => error is PlayerError;
+//# sourceMappingURL=isErrorWithMetadata.d.ts.map

package/types/controllers/error/utils/makeJsonStringifyReplacer.d.ts

@@ -0,0 +1,5 @@
+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 declare const makeJsonStringifyReplacer: () => ReplacerFunction;
+export {};
+//# sourceMappingURL=makeJsonStringifyReplacer.d.ts.map

package/types/controllers/flow/flow.d.ts

@@ -57,6 +57,23 @@ export declare class FlowInstance {
     });
     /** Start the state machine */
     start(): Promise<NavigationFlowEndState>;
+    /**
+     * Get the flow-level error transitions map
+     */
+    getFlowErrorTransitions(): Record<string, string> | undefined;
+    /**
+     * Helper to lookup a key in a map with wildcard fallback
+     */
+    private lookupInMap;
+    /** Check if the flow has a transition for the given error type in its current state. */
+    getErrorTransitionState(errorType: string): string | 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
+     */
+    errorTransition(errorType: string): void;
     transition(transitionValue: string, options?: TransitionOptions): void;
     private pushHistory;
 }

package/types/controllers/index.d.ts

@@ -3,4 +3,5 @@ export * from "./validation";
 export * from "./view";
 export * from "./data/controller";
 export * from "./constants";
+export * from "./error";
 //# sourceMappingURL=index.d.ts.map

package/types/controllers/view/controller.d.ts

@@ -7,6 +7,7 @@ import type { FlowController } from "../flow";
 import type { DataController } from "../data/controller";
 import type { TransformRegistry } from "./types";
 import type { Node } from "../../view";
+import { ErrorController } from "../error";
 export interface ViewControllerOptions {
     /** Where to get data from */
     model: DataController;
@@ -14,6 +15,8 @@ export interface ViewControllerOptions {
     logger?: Logger;
     /** 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 = {
     /** Do any processing before the `View` instance is created */
@@ -37,6 +40,7 @@ export declare class ViewController {
     optimizeUpdates: boolean;
     constructor(initialViews: View[], options: Resolve.ResolverOptions & ViewControllerOptions);
     private queueUpdate;
+    private updateView;
     private getViewForRef;
     onView(state: NavigationFlowViewState): void;
     private applyViewPlugins;

package/types/data/model.d.ts

@@ -35,6 +35,11 @@ export interface DataModelOptions {
      * A flag to indicate that this update should happen silently
      */
     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/types/types.d.ts

@@ -3,7 +3,7 @@ import type { BindingParser, BindingLike } from "./binding";
 import type { SchemaController } from "./schema";
 import type { ExpressionEvaluator } from "./expressions";
 import type { Logger } from "./logger";
-import type { ViewController, DataController, ValidationController, FlowController } from "./controllers";
+import type { ViewController, DataController, ValidationController, FlowController, ErrorController } from "./controllers";
 import type { ReadOnlyDataController } from "./controllers/data/utils";
 import { SyncHook, SyncWaterfallHook } from "tapable-ts";
 import { ViewInstance } from "./view";
@@ -27,6 +27,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 */
@@ -70,6 +72,8 @@ export interface ControllerState {
     binding: BindingParser;
     /** the manager for the flow state machine */
     flow: FlowController;
+    /** The manager for error handling */
+    error: ErrorController;
 }
 /** A flow is currently executing */
 export type InProgressState = BaseFlowState<"in-progress"> & PlayerFlowExecutionData & {

package/types/view/resolver/ResolverError.d.ts

@@ -0,0 +1,13 @@
+import { Node } from "../parser";
+import { ErrorSeverity, type PlayerErrorMetadata } from "../../controllers";
+import type { ResolverErrorMetadata, ResolverStage } from "./types";
+/** Error class to represent errors in the player resolver. */
+export declare class ResolverError extends Error implements PlayerErrorMetadata {
+    readonly cause: unknown;
+    readonly stage: ResolverStage;
+    readonly type: string;
+    readonly severity: ErrorSeverity;
+    readonly metadata: ResolverErrorMetadata;
+    constructor(cause: unknown, stage: ResolverStage, node: Node.Node);
+}
+//# sourceMappingURL=ResolverError.d.ts.map

package/types/view/resolver/index.d.ts

@@ -1,9 +1,10 @@
 import { SyncHook, SyncWaterfallHook } from "tapable-ts";
 import type { BindingInstance } from "../../binding";
 import { Node } from "../parser";
-import type { Resolve } from "./types";
+import { type Resolve } from "./types";
 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 */
     updated: boolean;

package/types/view/resolver/types.d.ts

@@ -126,4 +126,15 @@ export declare namespace Resolve {
         afterResolve?: NodeResolveFunction;
     }
 }
+export declare enum ResolverStage {
+    ResolveOptions = "resolveOptions",
+    SkipResolve = "skipResolve",
+    BeforeResolve = "beforeResolve",
+    Resolve = "resolve",
+    AfterResolve = "afterResolve",
+    AfterNodeUpdate = "afterNodeUpdate"
+}
+export type ResolverErrorMetadata = {
+    node: Node.Node;
+};
 //# sourceMappingURL=types.d.ts.map