@player-ui/player 0.0.1-next.1

package/src/player.ts

@@ -0,0 +1,497 @@
+import { SyncHook, SyncWaterfallHook } from 'tapable';
+import type { FlowInstance } from '@player-ui/flow';
+import { FlowController } from '@player-ui/flow';
+import type { Logger } from '@player-ui/logger';
+import { TapableLogger } from '@player-ui/logger';
+import type { ExpressionHandler } from '@player-ui/expressions';
+import { ExpressionEvaluator } from '@player-ui/expressions';
+import { SchemaController } from '@player-ui/schema';
+import { BindingParser } from '@player-ui/binding';
+import type { ViewInstance } from '@player-ui/view';
+import { setIn } from 'timm';
+import deferred from 'p-defer';
+import type { Flow as FlowType, FlowResult } from '@player-ui/types';
+import { resolveDataRefs } from '@player-ui/string-resolver';
+import { ConstantsController } from '@player-ui/constants';
+import queueMicrotask from 'queue-microtask';
+import { ViewController } from './view';
+import { DataController } from './data';
+import { ValidationController } from './validation';
+import { FlowExpPlugin } from './plugins/flow-exp-plugin';
+import type {
+  PlayerFlowState,
+  InProgressState,
+  CompletedState,
+  ErrorState,
+} from './types';
+import { NOT_STARTED_STATE } from './types';
+
+// Variables injected at build time
+const PLAYER_VERSION = '!!STABLE_VERSION!!';
+const COMMIT = '!!STABLE_GIT_COMMIT!!';
+
+export interface PlayerPlugin {
+  /**
+   * Unique identifier of the plugin.
+   * Enables the plugin to be retrievable from Player.
+   */
+  symbol?: symbol;
+
+  /** The name of the plugin */
+  name: string;
+
+  /**
+   * Use this to tap into Player hooks
+   */
+  apply: (player: Player) => void;
+}
+
+export interface PlayerConfigOptions {
+  /** A set of plugins to load  */
+  plugins?: PlayerPlugin[];
+
+  /** A logger to use */
+  logger?: Logger;
+}
+
+export interface PlayerInfo {
+  /** Version of the running player */
+  version: string;
+
+  /** Hash of the HEAD commit used to build the current version */
+  commit: string;
+}
+
+/**
+ * This is it.
+ */
+export class Player {
+  public static readonly info: PlayerInfo = {
+    version: PLAYER_VERSION,
+    commit: COMMIT,
+  };
+
+  public readonly logger = new TapableLogger();
+  public readonly constantsController = new ConstantsController();
+  private config: PlayerConfigOptions;
+  private state: PlayerFlowState = NOT_STARTED_STATE;
+
+  public readonly hooks = {
+    /** The hook that fires every time we create a new flowController (a new Content blob is passed in) */
+    flowController: new SyncHook<FlowController>(['flowController']),
+
+    /** The hook that updates/handles views */
+    viewController: new SyncHook<ViewController>(['viewController']),
+
+    /** A hook called every-time there's a new view. This is equivalent to the view hook on the view-controller */
+    view: new SyncHook<ViewInstance>(['view']),
+
+    /** Called when an expression evaluator was created */
+    expressionEvaluator: new SyncHook<ExpressionEvaluator>([
+      'expressionEvaluator',
+    ]),
+
+    /** The hook that creates and manages data */
+    dataController: new SyncHook<DataController>(['dataController']),
+
+    /** Called after the schema is created for a flow */
+    schema: new SyncHook<SchemaController>(['schema']),
+
+    /** Manages validations (schema and x-field ) */
+    validationController: new SyncHook<ValidationController>([
+      'validationController',
+    ]),
+
+    /** Manages parsing binding */
+    bindingParser: new SyncHook<BindingParser>(['bindingParser']),
+
+    /** A that's called for state changes in the flow execution */
+    state: new SyncHook<PlayerFlowState>(['state']),
+
+    /** A hook to access the current flow */
+    onStart: new SyncHook<FlowType>(['flow']),
+
+    /** A hook for when the flow ends either in success or failure */
+    onEnd: new SyncHook(),
+    /** Mutate the Content flow before starting */
+    resolveFlowContent: new SyncWaterfallHook<FlowType>(['content']),
+  };
+
+  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?.forEach((plugin) => {
+      plugin.apply(this);
+    });
+  }
+
+  /** Find instance of [Plugin] that has been registered to Player */
+  public findPlugin<Plugin extends PlayerPlugin>(
+    symbol: symbol
+  ): Plugin | undefined {
+    return this.config.plugins?.find((el) => el.symbol === symbol) as Plugin;
+  }
+
+  /** Retrieve an instance of [Plugin] and conditionally invoke [apply] if it exists */
+  public applyTo<Plugin extends PlayerPlugin>(
+    symbol: symbol,
+    apply: (plugin: Plugin) => void
+  ): void {
+    const plugin = this.findPlugin<Plugin>(symbol);
+
+    if (plugin) {
+      apply(plugin);
+    }
+  }
+
+  /** Register and apply [Plugin] if one with the same symbol is not already registered. */
+  public registerPlugin(plugin: PlayerPlugin) {
+    plugin.apply(this);
+    this.config.plugins?.push(plugin);
+  }
+
+  /** Returns the current version of the running player */
+  public getVersion(): string {
+    return Player.info.version;
+  }
+
+  /** Returns the git commit used to build Player version */
+  public getCommit(): string {
+    return Player.info.commit;
+  }
+
+  /**
+   * Fetch the current state of Player.
+   * It will return either `not-started`, `in-progress`, `completed`
+   * with some extra data in each
+   */
+  public getState(): PlayerFlowState {
+    return this.state;
+  }
+
+  /**
+   * A private means of setting the state of Player
+   * Calls the hooks for subscribers to listen for this event
+   */
+  private setState(state: PlayerFlowState) {
+    this.state = state;
+    this.hooks.state.call(state);
+  }
+
+  /** Start Player with the given flow */
+  private setupFlow(userContent: FlowType): {
+    /** a callback to _actually_ start the flow */
+    start: () => void;
+
+    /** the state object to kick if off */
+    state: Omit<InProgressState, 'ref'>;
+  } {
+    const userFlow = this.hooks.resolveFlowContent.call(userContent);
+
+    const flowController = new FlowController(userFlow.navigation, {
+      logger: this.logger,
+    });
+
+    this.hooks.onStart.call(userFlow);
+
+    this.hooks.flowController.call(flowController);
+
+    // eslint-disable-next-line prefer-const
+    let expressionEvaluator: ExpressionEvaluator;
+    // eslint-disable-next-line prefer-const
+    let dataController: DataController;
+
+    const pathResolver = new BindingParser({
+      get: (binding) => {
+        return dataController.get(binding);
+      },
+      set: (transaction) => {
+        return dataController.set(transaction);
+      },
+      evaluate: (expression) => {
+        return expressionEvaluator.evaluate(expression);
+      },
+    });
+
+    this.hooks.bindingParser.call(pathResolver);
+    const parseBinding = pathResolver.parse;
+    const flowResultDeferred = deferred<FlowResult>();
+
+    const schema = new SchemaController(userFlow.schema);
+    this.hooks.schema.call(schema);
+
+    const validationController = new ValidationController(schema);
+
+    this.hooks.validationController.call(validationController);
+
+    dataController = new DataController(userFlow.data, {
+      pathResolver,
+      middleware: validationController.getDataMiddleware(),
+      logger: this.logger,
+    });
+
+    dataController.hooks.format.tap('player', (value, binding) => {
+      const formatter = schema.getFormatter(binding);
+
+      return formatter ? formatter.format(value) : value;
+    });
+
+    dataController.hooks.deformat.tap('player', (value, binding) => {
+      const formatter = schema.getFormatter(binding);
+
+      return formatter ? formatter.deformat(value) : value;
+    });
+
+    dataController.hooks.resolveDefaultValue.tap(
+      'player',
+      (binding) => schema.getApparentType(binding)?.default
+    );
+
+    // eslint-disable-next-line prefer-const
+    let viewController: ViewController;
+
+    expressionEvaluator = new ExpressionEvaluator({
+      model: dataController,
+      logger: this.logger,
+    });
+
+    this.hooks.expressionEvaluator.call(expressionEvaluator);
+
+    expressionEvaluator.hooks.onError.tap('player', (e) => {
+      flowResultDeferred.reject(e);
+
+      return true;
+    });
+
+    /** Resolve any data references in a string */
+    function resolveStrings<T>(val: T) {
+      return resolveDataRefs(val, {
+        model: dataController,
+        evaluate: expressionEvaluator.evaluate,
+      });
+    }
+
+    flowController.hooks.flow.tap('player', (flow: FlowInstance) => {
+      flow.hooks.beforeTransition.tap('player', (state, transitionVal) => {
+        if (!('transitions' in state) || !state.transitions[transitionVal]) {
+          return state;
+        }
+
+        return setIn(
+          state,
+          ['transitions', transitionVal],
+          resolveStrings(state.transitions[transitionVal])
+        ) as any;
+      });
+
+      flow.hooks.skipTransition.tap('validation', (currentState) => {
+        if (currentState?.value.state_type === 'VIEW') {
+          const { canTransition, validations } =
+            validationController.validateView('navigation');
+
+          if (!canTransition && validations) {
+            const bindings = new Set(validations.keys());
+            viewController?.currentView?.update(bindings);
+
+            return true;
+          }
+        }
+
+        return undefined;
+      });
+
+      flow.hooks.resolveTransitionNode.tap('player', (state) => {
+        let newState = state;
+
+        if ('ref' in state) {
+          newState = setIn(state, ['ref'], resolveStrings(state.ref)) as any;
+        }
+
+        if ('param' in state) {
+          newState = setIn(
+            state,
+            ['param'],
+            resolveStrings(state.param)
+          ) as any;
+        }
+
+        return newState;
+      });
+
+      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
+          // Use a queueMicrotask to make sure the expression transition is outside the scope of the flow hook
+          queueMicrotask(() => {
+            flowController?.transition(
+              String(expressionEvaluator?.evaluate(exp))
+            );
+          });
+        }
+
+        expressionEvaluator.reset();
+      });
+    });
+
+    this.hooks.dataController.call(dataController);
+
+    validationController.setOptions({
+      parseBinding,
+      model: dataController,
+      logger: this.logger,
+      evaluate: expressionEvaluator.evaluate,
+      constants: this.constantsController,
+    });
+
+    viewController = new ViewController(userFlow.views || [], {
+      evaluator: expressionEvaluator,
+      parseBinding,
+      transition: flowController.transition,
+      model: dataController,
+      logger: this.logger,
+      flowController,
+      schema,
+      format: (binding, value) => {
+        const formatter = schema.getFormatter(binding);
+
+        return formatter?.format ? formatter.format(value) : value;
+      },
+      formatValue: (ref, value) => {
+        const formatter = schema.getFormatterForType(ref);
+
+        return formatter?.format ? formatter.format(value) : value;
+      },
+      validation: {
+        ...validationController.forView(parseBinding),
+        type: (b) => schema.getType(parseBinding(b)),
+      },
+    });
+    viewController.hooks.view.tap('player', (view) => {
+      validationController.onView(view);
+      this.hooks.view.call(view);
+    });
+    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),
+              data: dataController.serialize(),
+            };
+
+            return flowResult;
+          })
+          .then(flowResultDeferred.resolve)
+          .catch((e) => {
+            this.logger.error(`Something went wrong: ${e.message}`);
+            throw e;
+          })
+          .catch(flowResultDeferred.reject)
+          .finally(() => this.hooks.onEnd.call());
+      },
+      state: {
+        status: 'in-progress',
+        flowResult: flowResultDeferred.promise,
+        controllers: {
+          data: dataController,
+          view: viewController,
+          flow: flowController,
+          schema,
+          expression: expressionEvaluator,
+          binding: pathResolver,
+          validation: validationController,
+        },
+        fail: flowResultDeferred.reject,
+        flow: userFlow,
+        logger: this.logger,
+      },
+    };
+  }
+
+  public async start(payload: FlowType): Promise<CompletedState> {
+    const ref = Symbol(payload?.id ?? 'payload');
+
+    /** A check to avoid updating the state for a flow that's not the current one */
+    const maybeUpdateState = <T extends PlayerFlowState>(newState: T) => {
+      if (this.state.ref !== ref) {
+        this.logger.warn(
+          `Received update for a flow that's not the current one`
+        );
+
+        return newState;
+      }
+
+      this.setState(newState);
+
+      return newState;
+    };
+
+    this.setState({
+      status: 'not-started',
+      ref,
+    });
+
+    try {
+      const { state, start } = this.setupFlow(payload);
+      this.setState({
+        ref,
+        ...state,
+      });
+
+      start();
+
+      // common data for the end state
+      // make sure to use the same ref as the starting one
+      const endProps = {
+        ref,
+        status: 'completed',
+        flow: state.flow,
+        dataModel: state.controllers.data.getModel(),
+      } as const;
+
+      return maybeUpdateState({
+        ...(await state.flowResult),
+        ...endProps,
+      });
+    } catch (error: any) {
+      const errorState: ErrorState = {
+        status: 'error',
+        ref,
+        flow: payload,
+        error,
+      };
+
+      maybeUpdateState(errorState);
+
+      throw error;
+    }
+  }
+}

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

@@ -0,0 +1,65 @@
+import type { Expression, ExpressionObject } from '@player-ui/types';
+import type { ExpressionEvaluator } from '@player-ui/expressions';
+import type { FlowInstance } from '@player-ui/flow';
+import type { Player, PlayerPlugin } from '../player';
+import type { InProgressState } from '../types';
+
+/**
+ * A plugin that taps into the flow controller to evaluate available expressions
+ * Expressions can be exposed via lifecycle "hooks" in flow/state nodes
+ * e.g: onStart, onEnd
+ */
+export class FlowExpPlugin implements PlayerPlugin {
+  name = 'flow-exp-plugin';
+
+  apply(player: Player) {
+    let expressionEvaluator: ExpressionEvaluator | undefined;
+
+    /**
+     * Eval Helper
+     *
+     * @param exp - an expression to be evaluated
+     */
+    const handleEval = (exp: Expression | ExpressionObject) => {
+      if (exp) {
+        if (typeof exp === 'object' && 'exp' in exp) {
+          expressionEvaluator?.evaluate(exp.exp);
+        } else {
+          expressionEvaluator?.evaluate(exp);
+        }
+      }
+    };
+
+    player.hooks.expressionEvaluator.tap(this.name, (evaluator) => {
+      expressionEvaluator = evaluator;
+    });
+
+    player.hooks.flowController.tap(this.name, (fc) => {
+      fc.hooks.flow.tap(this.name, (flow: FlowInstance) => {
+        // Eval flow nodes
+        flow.hooks.onStart.tap(this.name, (exp) => handleEval(exp));
+
+        flow.hooks.onEnd.tap(this.name, (exp) => handleEval(exp));
+        // Eval state nodes
+        flow.hooks.resolveTransitionNode.intercept({
+          call: (nextState) => {
+            /** Get the current state of Player */
+            const currentState = () => player.getState() as InProgressState;
+
+            /** Get the current flow state */
+            const currentFlowState =
+              currentState().controllers.flow.current?.currentState;
+
+            if (currentFlowState?.value.onEnd) {
+              handleEval(currentFlowState.value.onEnd);
+            }
+
+            if (nextState?.onStart) {
+              handleEval(nextState.onStart);
+            }
+          },
+        });
+      });
+    });
+  }
+}

package/src/types.ts

@@ -0,0 +1,114 @@
+import type { Flow, FlowResult } from '@player-ui/types';
+import { Expression } from '@player-ui/types';
+import type { DataModelWithParser } from '@player-ui/data';
+import { DataModelOptions } from '@player-ui/data';
+import type { FlowController } from '@player-ui/flow';
+import { NamedState, TransitionFunction } from '@player-ui/flow';
+import { ViewInstance } from '@player-ui/view';
+import type { BindingParser, BindingLike } from '@player-ui/binding';
+import type { SchemaController } from '@player-ui/schema';
+import type { ExpressionEvaluator } from '@player-ui/expressions';
+import type { Logger } from '@player-ui/logger';
+import type { ViewController } from './view';
+import type { DataController } from './data';
+import type { ValidationController } from './validation';
+
+/** The status for a flow's execution state */
+export type PlayerFlowStatus =
+  | 'not-started'
+  | 'in-progress'
+  | 'completed'
+  | 'error';
+
+/** Common interface for the state of Player's flow execution */
+export interface BaseFlowState<T extends PlayerFlowStatus> {
+  /** A unique reference for the life-cycle of a flow */
+  ref: symbol;
+
+  /** The status of the given flow */
+  status: T;
+}
+
+/** The beginning state of Player, before it's seen a flow  */
+export type NotStartedState = BaseFlowState<'not-started'>;
+
+export const NOT_STARTED_STATE: NotStartedState = {
+  ref: Symbol('not-started'),
+  status: 'not-started',
+};
+
+/** Shared properties for a flow in any state of execution (in-progress, completed successfully, or errored out) */
+export interface PlayerFlowExecutionData {
+  /** The currently executing flow */
+  flow: Flow;
+}
+
+export interface ControllerState {
+  /** The manager for data for a flow */
+  data: DataController;
+
+  /** The view manager for a flow */
+  view: ViewController;
+
+  /** The schema manager for a flow */
+  schema: SchemaController;
+
+  /** The validation manager for a flow */
+  validation: ValidationController;
+
+  /** The expression evaluator for a flow */
+  expression: ExpressionEvaluator;
+
+  /** The manager for parsing and resolving bindings */
+  binding: BindingParser;
+
+  /** the manager for the flow state machine */
+  flow: FlowController;
+}
+
+/** A flow is currently executing */
+export type InProgressState = BaseFlowState<'in-progress'> &
+  PlayerFlowExecutionData & {
+    /** A promise that resolves when the flow is completed */
+    flowResult: Promise<FlowResult>;
+
+    /** The underlying state controllers for the current flow */
+    controllers: ControllerState;
+
+    /** Allow other platforms to abort the current flow with an error  */
+    fail: (error: Error) => void;
+
+    /**
+     * The Logger for the current player instance
+     */
+    logger: Logger;
+  };
+
+/** The flow completed properly */
+export type CompletedState = BaseFlowState<'completed'> &
+  PlayerFlowExecutionData &
+  FlowResult & {
+    /** The top-level data-model for the flow */
+    dataModel: DataModelWithParser;
+  };
+
+/** The flow finished but not successfully */
+export type ErrorState = BaseFlowState<'error'> & {
+  /** The currently executing flow */
+  flow: Flow;
+
+  /** The error associated with the failed flow */
+  error: Error;
+};
+
+/** Any Player state  */
+export type PlayerFlowState =
+  | NotStartedState
+  | InProgressState
+  | CompletedState
+  | ErrorState;
+
+// Model
+
+export type RawSetType = [BindingLike, any];
+export type RawSetTransaction = Record<string, any> | RawSetType[];

package/src/utils/desc.d.ts

@@ -0,0 +1,2 @@
+// Declaration for libraries that don't have types
+declare module 'babel-plugin-preval/macro';