@player-ui/player 0.4.0 → 0.4.1-next.0

package/src/player.ts

@@ -1,12 +1,11 @@
 import { setIn } from 'timm';
 import deferred from 'p-defer';
-import queueMicrotask from 'queue-microtask';
 import type { Flow as FlowType, FlowResult } from '@player-ui/types';
 
 import { SyncHook, SyncWaterfallHook } from 'tapable-ts';
 import type { Logger } from './logger';
 import { TapableLogger } from './logger';
-import type { ExpressionHandler } from './expressions';
+import type { ExpressionType } from './expressions';
 import { ExpressionEvaluator } from './expressions';
 import { SchemaController } from './schema';
 import { BindingParser } from './binding';
@@ -21,6 +20,7 @@ import {
   FlowController,
 } from './controllers';
 import { FlowExpPlugin } from './plugins/flow-exp-plugin';
+import { DefaultExpPlugin } from './plugins/default-exp-plugin';
 import type {
   PlayerFlowState,
   InProgressState,
@@ -30,8 +30,8 @@ import type {
 import { NOT_STARTED_STATE } from './types';
 
 // Variables injected at build time
-const PLAYER_VERSION = '0.4.0';
-const COMMIT = '39b851fc45e4903eae2f5b0697dea142c890443c';
+const PLAYER_VERSION = '0.4.1-next.0';
+const COMMIT = '3fca14a3bf47195b400f5989a2f3ecbc5f73ac4b';
 
 export interface PlayerPlugin {
   /**
@@ -49,6 +49,18 @@ export interface PlayerPlugin {
   apply: (player: Player) => void;
 }
 
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface ExtendedPlayerPlugin<
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  Assets = void,
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  Views = void,
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  Expressions = void,
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  DataTypes = void
+> {}
+
 export interface PlayerConfigOptions {
   /** A set of plugins to load  */
   plugins?: PlayerPlugin[];
@@ -117,17 +129,16 @@ export class Player {
   };
 
   constructor(config?: PlayerConfigOptions) {
-    const initialPlugins: PlayerPlugin[] = [];
-    const flowExpPlugin = new FlowExpPlugin();
-
-    initialPlugins.push(flowExpPlugin);
-
     if (config?.logger) {
       this.logger.addHandler(config.logger);
     }
 
     this.config = config || {};
-    this.config.plugins = [...(this.config.plugins || []), ...initialPlugins];
+    this.config.plugins = [
+      new DefaultExpPlugin(),
+      ...(this.config.plugins || []),
+      new FlowExpPlugin(),
+    ];
     this.config.plugins?.forEach((plugin) => {
       plugin.apply(this);
     });
@@ -277,10 +288,11 @@ export class Player {
     });
 
     /** Resolve any data references in a string */
-    function resolveStrings<T>(val: T) {
+    function resolveStrings<T>(val: T, formatted?: boolean) {
       return resolveDataRefs(val, {
         model: dataController,
         evaluate: expressionEvaluator.evaluate,
+        formatted,
       });
     }
 
@@ -294,7 +306,7 @@ export class Player {
           if (typeof state.onEnd === 'object' && 'exp' in state.onEnd) {
             expressionEvaluator?.evaluate(state.onEnd.exp);
           } else {
-            expressionEvaluator?.evaluate(state.onEnd);
+            expressionEvaluator?.evaluate(state.onEnd as ExpressionType);
           }
         }
 
@@ -341,7 +353,7 @@ export class Player {
           newState = setIn(
             state,
             ['param'],
-            resolveStrings(state.param)
+            resolveStrings(state.param, false)
           ) as any;
         }
 
@@ -349,26 +361,18 @@ export class Player {
       });
 
       flow.hooks.transition.tap('player', (_oldState, newState) => {
-        if (newState.value.state_type === 'ACTION') {
-          const { exp } = newState.value;
-
-          // The nested transition call would trigger another round of the flow transition hooks to be called.
-          // This created a weird timing where this nested transition would happen before the view had a chance to respond to the first one
-
-          // Additionally, because we are using queueMicrotask, errors could get swallowed in the detached queue
-          // Use a try catch and fail player explicitly if any errors are caught in the nested transition/state
-          queueMicrotask(() => {
-            try {
-              flowController?.transition(
-                String(expressionEvaluator?.evaluate(exp))
-              );
-            } catch (error) {
-              const state = this.getState();
-              if (error instanceof Error && state.status === 'in-progress') {
-                state.fail(error);
-              }
-            }
-          });
+        if (newState.value.state_type !== 'VIEW') {
+          validationController.reset();
+        }
+      });
+
+      flow.hooks.afterTransition.tap('player', (flowInstance) => {
+        const value = flowInstance.currentState?.value;
+        if (value && value.state_type === 'ACTION') {
+          const { exp } = value;
+          flowController?.transition(
+            String(expressionEvaluator?.evaluate(exp))
+          );
         }
 
         expressionEvaluator.reset();
@@ -390,6 +394,11 @@ export class Player {
       parseBinding,
       transition: flowController.transition,
       model: dataController,
+      utils: {
+        findPlugin: <Plugin = unknown>(pluginSymbol: symbol) => {
+          return this.findPlugin(pluginSymbol) as unknown as Plugin;
+        },
+      },
       logger: this.logger,
       flowController,
       schema,
@@ -407,6 +416,7 @@ export class Player {
         ...validationController.forView(parseBinding),
         type: (b) => schema.getType(parseBinding(b)),
       },
+      constants: this.constantsController,
     });
     viewController.hooks.view.tap('player', (view) => {
       validationController.onView(view);
@@ -414,26 +424,13 @@ export class Player {
     });
     this.hooks.viewController.call(viewController);
 
-    /** Gets formatter for given formatName and formats value if found, returns value otherwise */
-    const formatFunction: ExpressionHandler<[unknown, string], any> = (
-      ctx,
-      value,
-      formatName
-    ) => {
-      return (
-        schema.getFormatterForType({ type: formatName })?.format(value) ?? value
-      );
-    };
-
-    expressionEvaluator.addExpressionFunction('format', formatFunction);
-
     return {
       start: () => {
         flowController
           .start()
           .then((endState) => {
             const flowResult: FlowResult = {
-              endState: resolveStrings(endState),
+              endState: resolveStrings(endState, false),
               data: dataController.serialize(),
             };
 
@@ -504,7 +501,9 @@ export class Player {
         ref,
         status: 'completed',
         flow: state.flow,
-        dataModel: state.controllers.data.getModel(),
+        controllers: {
+          data: state.controllers.data.makeReadOnly(),
+        },
       } as const;
 
       return maybeUpdateState({

package/src/plugins/default-exp-plugin.ts

@@ -0,0 +1,57 @@
+import type { ExpressionHandler, ExpressionType } from '../expressions';
+import type { SchemaController } from '../schema';
+import type { Player, PlayerPlugin } from '../player';
+
+/** Gets formatter for given formatName and formats value if found, returns value otherwise */
+const createFormatFunction = (schema: SchemaController) => {
+  /**
+   * The generated handler for the given schema
+   */
+  const handler: ExpressionHandler<[unknown, string], any> = (
+    ctx,
+    value,
+    formatName
+  ) => {
+    return (
+      schema.getFormatterForType({ type: formatName })?.format(value) ?? value
+    );
+  };
+
+  return handler;
+};
+
+/**
+ * A plugin that provides the out-of-the-box expressions for player
+ */
+export class DefaultExpPlugin implements PlayerPlugin {
+  name = 'flow-exp-plugin';
+
+  apply(player: Player) {
+    let formatFunction: ExpressionHandler<[unknown, string]> | undefined;
+
+    player.hooks.schema.tap(this.name, (schemaController) => {
+      formatFunction = createFormatFunction(schemaController);
+    });
+
+    player.hooks.expressionEvaluator.tap(this.name, (expEvaluator) => {
+      if (formatFunction) {
+        expEvaluator.addExpressionFunction('format', formatFunction);
+      }
+
+      expEvaluator.addExpressionFunction('log', (ctx, ...args) => {
+        player.logger.info(...args);
+      });
+
+      expEvaluator.addExpressionFunction('debug', (ctx, ...args) => {
+        player.logger.debug(...args);
+      });
+
+      expEvaluator.addExpressionFunction(
+        'eval',
+        (ctx, ...args: [ExpressionType]) => {
+          return ctx.evaluate(...args);
+        }
+      );
+    });
+  }
+}

package/src/plugins/flow-exp-plugin.ts

@@ -3,7 +3,7 @@ import type {
   ExpressionObject,
   NavigationFlowState,
 } from '@player-ui/types';
-import type { ExpressionEvaluator } from '../expressions';
+import type { ExpressionEvaluator, ExpressionType } from '../expressions';
 import type { FlowInstance } from '../controllers';
 import type { Player, PlayerPlugin } from '../player';
 
@@ -28,7 +28,7 @@ export class FlowExpPlugin implements PlayerPlugin {
         if (typeof exp === 'object' && 'exp' in exp) {
           expressionEvaluator?.evaluate(exp.exp);
         } else {
-          expressionEvaluator?.evaluate(exp);
+          expressionEvaluator?.evaluate(exp as ExpressionType);
         }
       }
     };

package/src/schema/schema.ts

@@ -11,8 +11,8 @@ const identify = (val: any) => val;
 /** Expand the authored schema into a set of paths -> DataTypes */
 export function parse(
   schema: SchemaType.Schema
-): Map<string, SchemaType.DataType> {
-  const expandedPaths = new Map<string, SchemaType.DataType>();
+): Map<string, SchemaType.DataTypes> {
+  const expandedPaths = new Map<string, SchemaType.DataTypes>();
 
   if (!schema.ROOT) {
     return expandedPaths;
@@ -62,6 +62,10 @@ export function parse(
         nestedPath.push('[]');
       }
 
+      if (type.isRecord) {
+        nestedPath.push('{}');
+      }
+
       if (type.type && schema[type.type]) {
         parseQueue.push({
           path: nestedPath,
@@ -85,14 +89,14 @@ export class SchemaController implements ValidationProvider {
     new Map();
 
   private types: Map<string, SchemaType.DataType<any>> = new Map();
-  public readonly schema: Map<string, SchemaType.DataType> = new Map();
+  public readonly schema: Map<string, SchemaType.DataTypes> = new Map();
 
   private bindingSchemaNormalizedCache: Map<BindingInstance, string> =
     new Map();
 
   public readonly hooks = {
     resolveTypeForBinding: new SyncWaterfallHook<
-      [SchemaType.DataType | undefined, BindingInstance]
+      [SchemaType.DataTypes | undefined, BindingInstance]
     >(),
   };
 
@@ -135,17 +139,32 @@ export class SchemaController implements ValidationProvider {
       return cached;
     }
 
-    const normalized = binding
-      .asArray()
+    let bindingArray = binding.asArray();
+    let normalized = bindingArray
       .map((p) => (typeof p === 'number' ? '[]' : p))
       .join('.');
 
-    this.bindingSchemaNormalizedCache.set(binding, normalized);
+    if (normalized) {
+      this.bindingSchemaNormalizedCache.set(binding, normalized);
+      bindingArray = normalized.split('.');
+    }
+
+    bindingArray.forEach((item) => {
+      const recordBinding = bindingArray
+        .map((p) => (p === item ? '{}' : p))
+        .join('.');
+
+      if (this.schema.get(recordBinding)) {
+        this.bindingSchemaNormalizedCache.set(binding, recordBinding);
+        bindingArray = recordBinding.split('.');
+        normalized = recordBinding;
+      }
+    });
 
     return normalized;
   }
 
-  public getType(binding: BindingInstance): SchemaType.DataType | undefined {
+  public getType(binding: BindingInstance): SchemaType.DataTypes | undefined {
     return this.hooks.resolveTypeForBinding.call(
       this.schema.get(this.normalizeBinding(binding)),
       binding
@@ -154,7 +173,7 @@ export class SchemaController implements ValidationProvider {
 
   public getApparentType(
     binding: BindingInstance
-  ): SchemaType.DataType | undefined {
+  ): SchemaType.DataTypes | undefined {
     const schemaType = this.getType(binding);
 
     if (schemaType === undefined) {

package/src/string-resolver/index.ts

@@ -6,11 +6,22 @@ const DOUBLE_OPEN_CURLY = '{{';
 const DOUBLE_CLOSE_CURLY = '}}';
 
 export interface Options {
-  /** The model to use when resolving refs */
-  model: DataModelWithParser;
-
-  /** A function to evaluate an expression */
-  evaluate: (exp: Expression) => any;
+  /**
+   * The model to use when resolving refs
+   * Passing `false` will skip trying to resolve any direct model refs ({{foo}})
+   */
+  model: false | DataModelWithParser;
+
+  /**
+   * A function to evaluate an expression
+   * Passing `false` will skip trying to evaluate any expressions (@[ foo() ]@)
+   */
+  evaluate: false | ((exp: Expression) => any);
+
+  /**
+   * Optionaly resolve binding without formatting in case Type format applies
+   */
+  formatted?: boolean;
 }
 
 /** Search the given string for the coordinates of the next expression to resolve */
@@ -70,6 +81,10 @@ export function resolveExpressionsInString(
   val: string,
   { evaluate }: Options
 ): string {
+  if (!evaluate) {
+    return val;
+  }
+
   const expMatch = /@\[.*?\]@/;
   let newVal = val;
   let match = newVal.match(expMatch);
@@ -106,10 +121,11 @@ export function resolveExpressionsInString(
 
 /** Return a string with all data model references resolved */
 export function resolveDataRefsInString(val: string, options: Options): string {
-  const { model } = options;
+  const { model, formatted = true } = options;
   let workingString = resolveExpressionsInString(val, options);
 
   if (
+    !model ||
     typeof workingString !== 'string' ||
     workingString.indexOf(DOUBLE_OPEN_CURLY) === -1
   ) {
@@ -133,7 +149,7 @@ export function resolveDataRefsInString(val: string, options: Options): string {
       )
       .trim();
 
-    const evaledVal = model.get(binding, { formatted: true });
+    const evaledVal = model.get(binding, { formatted });
 
     // Exit early if the string is _just_ a model lookup
     // If the result is a string, we may need further processing for nested bindings
@@ -166,13 +182,13 @@ function traverseObject<T>(val: T, options: Options): T {
       let newVal = val;
 
       if (keys.length > 0) {
-        for (const key of keys) {
+        keys.forEach((key) => {
           newVal = setIn(
             newVal as any,
             [key],
             traverseObject((val as any)[key], options)
           ) as any;
-        }
+        });
       }
 
       return newVal;

package/src/types.ts

@@ -1,5 +1,4 @@
 import type { Flow, FlowResult } from '@player-ui/types';
-import type { DataModelWithParser } from './data';
 import type { BindingParser, BindingLike } from './binding';
 import type { SchemaController } from './schema';
 import type { ExpressionEvaluator } from './expressions';
@@ -10,6 +9,7 @@ import type {
   ValidationController,
   FlowController,
 } from './controllers';
+import type { ReadOnlyDataController } from './controllers/data/utils';
 
 /** The status for a flow's execution state */
 export type PlayerFlowStatus =
@@ -86,8 +86,11 @@ export type InProgressState = BaseFlowState<'in-progress'> &
 export type CompletedState = BaseFlowState<'completed'> &
   PlayerFlowExecutionData &
   FlowResult & {
-    /** The top-level data-model for the flow */
-    dataModel: DataModelWithParser;
+    /** Readonly Player controllers to provide Player functionality after the flow has ended */
+    controllers: {
+      /** A read only instance of the Data Controller */
+      data: ReadOnlyDataController;
+    };
   };
 
 /** The flow finished but not successfully */

package/src/validator/binding-map-splice.ts

@@ -0,0 +1,59 @@
+import type { BindingInstance } from '../binding';
+
+/**
+ * Remove a binding, and any children from from the map
+ * If the binding is an array-item, then it will be spliced from the array and the others will be shifted down
+ *
+ * @param sourceMap - A map of bindings to values
+ * @param binding - The binding to remove from the map
+ */
+export function removeBindingAndChildrenFromMap<T>(
+  sourceMap: Map<BindingInstance, T>,
+  binding: BindingInstance
+): Map<BindingInstance, T> {
+  const targetMap = new Map(sourceMap);
+
+  const parentBinding = binding.parent();
+  const property = binding.key();
+
+  // Clear out any that are sub-bindings of this binding
+
+  targetMap.forEach((_value, trackedBinding) => {
+    if (binding === trackedBinding || binding.contains(trackedBinding)) {
+      targetMap.delete(trackedBinding);
+    }
+  });
+
+  if (typeof property === 'number') {
+    // Splice out this index from the rest
+
+    // Order matters here b/c we are shifting items in the array
+    // Start with the smallest index and work our way down
+    const bindingsToRewrite = Array.from(sourceMap.keys())
+      .filter((b) => {
+        if (parentBinding.contains(b)) {
+          const [childIndex] = b.relative(parentBinding);
+          return typeof childIndex === 'number' && childIndex > property;
+        }
+
+        return false;
+      })
+      .sort();
+
+    bindingsToRewrite.forEach((trackedBinding) => {
+      // If the tracked binding is a sub-binding of the parent binding, then we need to
+      // update the path to reflect the new index
+
+      const [childIndex, ...childPath] = trackedBinding.relative(parentBinding);
+
+      if (typeof childIndex === 'number') {
+        const newSegments = [childIndex - 1, ...childPath];
+        const newChildBinding = parentBinding.descendent(newSegments);
+        targetMap.set(newChildBinding, targetMap.get(trackedBinding) as T);
+        targetMap.delete(trackedBinding);
+      }
+    });
+  }
+
+  return targetMap;
+}

package/src/validator/index.ts

@@ -1,3 +1,4 @@
 export * from './validation-middleware';
 export * from './types';
 export * from './registry';
+export * from './binding-map-splice';

package/src/validator/types.ts

@@ -1,4 +1,4 @@
-import type { Validation } from '@player-ui/types';
+import type { Schema, Validation } from '@player-ui/types';
 
 import type { BindingInstance, BindingFactory } from '../binding';
 import type { DataModelWithParser } from '../data';
@@ -40,12 +40,17 @@ type RequiredValidationKeys = 'severity' | 'trigger';
 export type ValidationObject = Validation.Reference &
   Required<Pick<Validation.Reference, RequiredValidationKeys>>;
 
+export type ValidationObjectWithHandler = ValidationObject & {
+  /** A predefined handler for this validation object */
+  handler?: ValidatorFunction;
+};
+
 export interface ValidationProvider {
   getValidationsForBinding?(
     binding: BindingInstance
-  ): Array<ValidationObject> | undefined;
+  ): Array<ValidationObjectWithHandler> | undefined;
 
-  getValidationsForView?(): Array<ValidationObject> | undefined;
+  getValidationsForView?(): Array<ValidationObjectWithHandler> | undefined;
 }
 
 export interface ValidatorContext {
@@ -66,6 +71,9 @@ export interface ValidatorContext {
 
   /** The constants for messages */
   constants: ConstantsProvider;
+
+  /** The type in the schema that triggered the validation if there is one */
+  schemaType: Schema.DataType | undefined;
 }
 
 export type ValidatorFunction<Options = unknown> = (

package/src/validator/validation-middleware.ts

@@ -11,6 +11,7 @@ import { toModel } from '../data';
 import type { Logger } from '../logger';
 
 import type { ValidationResponse } from './types';
+import { removeBindingAndChildrenFromMap } from './binding-map-splice';
 
 /**
  * A BindingInstance with an indicator of whether or not it's a strong binding
@@ -37,17 +38,21 @@ export class ValidationMiddleware implements DataModelMiddleware {
   public validator: MiddlewareChecker;
   public shadowModelPaths: Map<BindingInstance, any>;
   private logger?: Logger;
+  private shouldIncludeInvalid?: (options?: DataModelOptions) => boolean;
 
   constructor(
     validator: MiddlewareChecker,
     options?: {
       /** A logger instance */
       logger?: Logger;
+      /** Optional function to include data staged in shadowModel */
+      shouldIncludeInvalid?: (options?: DataModelOptions) => boolean;
     }
   ) {
     this.validator = validator;
     this.shadowModelPaths = new Map();
     this.logger = options?.logger;
+    this.shouldIncludeInvalid = options?.shouldIncludeInvalid;
   }
 
   public set(
@@ -58,8 +63,11 @@ export class ValidationMiddleware implements DataModelMiddleware {
     const asModel = toModel(this, { ...options, includeInvalid: true }, next);
     const nextTransaction: BatchSetTransaction = [];
 
+    const includedBindings = new Set<BindingInstance>();
+
     transaction.forEach(([binding, value]) => {
       this.shadowModelPaths.set(binding, value);
+      includedBindings.add(binding);
     });
 
     const invalidBindings: Array<BindingInstance> = [];
@@ -72,11 +80,15 @@ export class ValidationMiddleware implements DataModelMiddleware {
       } else if (validations instanceof Set) {
         validations.forEach((validation) => {
           invalidBindings.push(validation.binding);
-          if (!validation.isStrong) {
+          if (
+            !validation.isStrong &&
+            validation.binding.asString() === binding.asString()
+          ) {
             nextTransaction.push([validation.binding, value]);
           }
         });
-      } else {
+      } else if (includedBindings.has(binding)) {
+        invalidBindings.push(binding);
         this.logger?.debug(
           `Invalid value for path: ${binding.asString()} - ${
             validations.severity
@@ -85,6 +97,8 @@ export class ValidationMiddleware implements DataModelMiddleware {
       }
     });
 
+    let validResults: Updates = [];
+
     if (next && nextTransaction.length > 0) {
       // defer clearing the shadow model to prevent validations that are run twice due to weak binding refs still needing the data
       nextTransaction.forEach(([binding]) =>
@@ -94,9 +108,11 @@ export class ValidationMiddleware implements DataModelMiddleware {
       if (invalidBindings.length === 0) {
         return result;
       }
+
+      validResults = result;
     }
 
-    return invalidBindings.map((binding) => {
+    const invalidResults = invalidBindings.map((binding) => {
       return {
         binding,
         oldValue: asModel.get(binding),
@@ -104,6 +120,8 @@ export class ValidationMiddleware implements DataModelMiddleware {
         force: true,
       };
     });
+
+    return [...validResults, ...invalidResults];
   }
 
   public get(
@@ -113,7 +131,10 @@ export class ValidationMiddleware implements DataModelMiddleware {
   ) {
     let val = next?.get(binding, options);
 
-    if (options?.includeInvalid === true) {
+    if (
+      this.shouldIncludeInvalid?.(options) ??
+      options?.includeInvalid === true
+    ) {
       this.shadowModelPaths.forEach((shadowValue, shadowBinding) => {
         if (shadowBinding === binding) {
           val = shadowValue;
@@ -129,4 +150,17 @@ export class ValidationMiddleware implements DataModelMiddleware {
 
     return val;
   }
+
+  public delete(
+    binding: BindingInstance,
+    options?: DataModelOptions,
+    next?: DataModelImpl
+  ) {
+    this.shadowModelPaths = removeBindingAndChildrenFromMap(
+      this.shadowModelPaths,
+      binding
+    );
+
+    return next?.delete(binding, options);
+  }
 }