jspsych 7.3.4 → 8.0.0

package/src/timeline/Trial.ts

@@ -0,0 +1,419 @@
+import { Class } from "type-fest";
+
+import { ParameterInfos } from "../modules/plugins";
+import { JsPsychPlugin, ParameterType, PluginInfo } from "../modules/plugins";
+import { deepCopy, deepMerge } from "../modules/utils";
+import { Timeline } from "./Timeline";
+import { GetParameterValueOptions, TimelineNode } from "./TimelineNode";
+import { delay, isPromise, parameterPathArrayToString } from "./util";
+import {
+  SimulationOptions,
+  TimelineNodeDependencies,
+  TimelineNodeStatus,
+  TimelineVariable,
+  TrialDescription,
+  TrialResult,
+  timelineDescriptionKeys,
+} from ".";
+
+export class Trial extends TimelineNode {
+  public readonly pluginClass: Class<JsPsychPlugin<any>>;
+  public pluginInstance: JsPsychPlugin<any>;
+  public trialObject?: TrialDescription;
+  public index?: number;
+
+  private result: TrialResult;
+  private readonly pluginInfo: PluginInfo;
+
+  constructor(
+    dependencies: TimelineNodeDependencies,
+    public readonly description: TrialDescription,
+    public readonly parent: Timeline
+  ) {
+    super(dependencies);
+    this.initializeParameterValueCache();
+
+    this.trialObject = deepCopy(description);
+    this.pluginClass = this.getParameterValue("type", { evaluateFunctions: false });
+    this.pluginInfo = this.pluginClass["info"];
+
+    if (!("version" in this.pluginInfo) && !("data" in this.pluginInfo)) {
+      console.warn(
+        this.pluginInfo["name"],
+        "is missing the 'version' and 'data' fields. Please update plugin as 'version' and 'data' will be required in v9. See https://www.jspsych.org/latest/developers/plugin-development/ for more details."
+      );
+    } else if (!("version" in this.pluginInfo)) {
+      console.warn(
+        this.pluginInfo["name"],
+        "is missing the 'version' field. Please update plugin as 'version' will be required in v9. See https://www.jspsych.org/latest/developers/plugin-development/ for more details."
+      );
+    } else if (!("data" in this.pluginInfo)) {
+      console.warn(
+        this.pluginInfo["name"],
+        "is missing the 'data' field. Please update plugin as 'data' will be required in v9. See https://www.jspsych.org/latest/developers/plugin-development/ for more details."
+      );
+    }
+  }
+
+  public async run() {
+    this.status = TimelineNodeStatus.RUNNING;
+    this.processParameters();
+
+    this.onStart();
+    this.addCssClasses();
+
+    this.pluginInstance = this.dependencies.instantiatePlugin(this.pluginClass);
+
+    this.result = this.processResult(await this.executeTrial());
+
+    this.dependencies.onTrialResultAvailable(this);
+
+    this.status = TimelineNodeStatus.COMPLETED;
+
+    await this.onFinish();
+    this.removeCssClasses();
+
+    const gap = this.getParameterValue("post_trial_gap") ?? this.dependencies.getDefaultIti();
+    if (gap !== 0 && this.dependencies.getSimulationMode() !== "data-only") {
+      await delay(gap);
+    }
+
+    this.resetParameterValueCache();
+  }
+
+  private async executeTrial() {
+    const trialPromise = this.dependencies.finishTrialPromise.get();
+
+    /** Used as a way to figure out if `finishTrial()` has ben called without awaiting `trialPromise` */
+    let hasTrialPromiseBeenResolved = false;
+    trialPromise.then(() => {
+      hasTrialPromiseBeenResolved = true;
+    });
+
+    const { trialReturnValue, hasTrialBeenSimulated } = this.invokeTrialMethod();
+
+    // Wait until the trial has completed and grab result data
+    let result: TrialResult | void;
+    if (isPromise(trialReturnValue)) {
+      result = await Promise.race([trialReturnValue, trialPromise]);
+
+      // If `finishTrial()` was called, use the result provided to it. This may happen although
+      // `trialReturnValue` won the race ("run-to-completion").
+      if (hasTrialPromiseBeenResolved) {
+        result = await trialPromise;
+      }
+    } else {
+      // The `simulate` method always invokes `onLoad()`, so we don't call `onLoad()` when the trial
+      // has been simulated
+      if (!hasTrialBeenSimulated) {
+        this.onLoad();
+      }
+
+      result = await trialPromise;
+    }
+
+    // The trial has finished, time to clean up.
+    this.cleanupTrial();
+
+    return result;
+  }
+
+  private invokeTrialMethod(): {
+    trialReturnValue: void | Promise<void | TrialResult>;
+    hasTrialBeenSimulated: boolean;
+  } {
+    const globalSimulationMode = this.dependencies.getSimulationMode();
+
+    if (globalSimulationMode && typeof this.pluginInstance.simulate === "function") {
+      const simulationOptions = this.getSimulationOptions();
+
+      if (simulationOptions.simulate !== false) {
+        return {
+          hasTrialBeenSimulated: true,
+          trialReturnValue: this.pluginInstance.simulate(
+            this.trialObject,
+            simulationOptions.mode ?? globalSimulationMode,
+            simulationOptions,
+            this.onLoad
+          ),
+        };
+      }
+    }
+
+    return {
+      hasTrialBeenSimulated: false,
+      trialReturnValue: this.pluginInstance.trial(
+        this.dependencies.getDisplayElement(),
+        this.trialObject,
+        this.onLoad
+      ),
+    };
+  }
+
+  /**
+   * Cleanup the trial by removing the display element and removing event listeners
+   */
+  private cleanupTrial() {
+    this.dependencies.clearAllTimeouts();
+    this.dependencies.getDisplayElement().innerHTML = "";
+  }
+
+  /**
+   * Add the CSS classes from the `css_classes` parameter to the display element
+   */
+  private addCssClasses() {
+    const classes: string | string[] = this.getParameterValue("css_classes");
+    const classList = this.dependencies.getDisplayElement().classList;
+    if (typeof classes === "string") {
+      classList.add(classes);
+    } else if (Array.isArray(classes)) {
+      classList.add(...classes);
+    }
+  }
+
+  /**
+   * Removes the provided css classes from the display element
+   */
+  private removeCssClasses() {
+    const classes = this.getParameterValue("css_classes");
+    if (classes) {
+      this.dependencies
+        .getDisplayElement()
+        .classList.remove(...(typeof classes === "string" ? [classes] : classes));
+    }
+  }
+
+  private processResult(result: TrialResult | void) {
+    if (!result) {
+      result = {};
+    }
+
+    for (const [parameterName, shouldParameterBeIncluded] of Object.entries(
+      this.getParameterValue("save_trial_parameters") ?? {}
+    )) {
+      if (this.pluginInfo.parameters[parameterName]) {
+        if (shouldParameterBeIncluded && !Object.hasOwn(result, parameterName)) {
+          let parameterValue = this.trialObject[parameterName];
+          if (typeof parameterValue === "function") {
+            parameterValue = parameterValue.toString();
+          }
+          result[parameterName] = parameterValue;
+        } else if (!shouldParameterBeIncluded && Object.hasOwn(result, parameterName)) {
+          delete result[parameterName];
+        }
+      } else {
+        console.warn(
+          `Non-existent parameter "${parameterName}" specified in save_trial_parameters.`
+        );
+      }
+    }
+
+    result = {
+      ...this.getDataParameter(),
+      ...result,
+      trial_type: this.pluginInfo.name,
+      trial_index: this.index,
+      plugin_version: this.pluginInfo["version"] ? this.pluginInfo["version"] : null,
+    };
+
+    // Add timeline variables to the result according to the `save_timeline_variables` parameter
+    const saveTimelineVariables = this.getParameterValue("save_timeline_variables");
+    if (saveTimelineVariables === true) {
+      result.timeline_variables = { ...this.parent.getAllTimelineVariables() };
+    } else if (Array.isArray(saveTimelineVariables)) {
+      result.timeline_variables = Object.fromEntries(
+        Object.entries(this.parent.getAllTimelineVariables()).filter(([key, _]) =>
+          saveTimelineVariables.includes(key)
+        )
+      );
+    }
+
+    return result;
+  }
+
+  /**
+   * Runs a callback function retrieved from a parameter value and returns its result.
+   *
+   * @param parameterName The name of the parameter to retrieve the callback function from.
+   * @param callbackParameters The parameters (if any) to be passed to the callback function
+   */
+  private runParameterCallback(parameterName: string, ...callbackParameters: unknown[]) {
+    const callback = this.getParameterValue(parameterName, { evaluateFunctions: false });
+    if (callback) {
+      return callback(...callbackParameters);
+    }
+  }
+
+  private onStart() {
+    this.dependencies.onTrialStart(this);
+    this.runParameterCallback("on_start", this.trialObject);
+    this.dependencies.runOnStartExtensionCallbacks(this.getParameterValue("extensions"));
+  }
+
+  private onLoad = () => {
+    this.runParameterCallback("on_load");
+    this.dependencies.runOnLoadExtensionCallbacks(this.getParameterValue("extensions"));
+  };
+
+  private async onFinish() {
+    const extensionResults = await this.dependencies.runOnFinishExtensionCallbacks(
+      this.getParameterValue("extensions")
+    );
+    Object.assign(this.result, extensionResults);
+
+    await Promise.resolve(this.runParameterCallback("on_finish", this.getResult()));
+
+    this.dependencies.onTrialFinished(this);
+  }
+
+  public evaluateTimelineVariable(variable: TimelineVariable) {
+    // Timeline variable values are specified at the timeline level, not at the trial level, hence
+    // deferring to the parent timeline here
+    return this.parent?.evaluateTimelineVariable(variable);
+  }
+
+  public getParameterValue(
+    parameterPath: string | string[],
+    options: GetParameterValueOptions = {}
+  ) {
+    // Disable recursion for timeline description keys
+    if (
+      timelineDescriptionKeys.includes(
+        typeof parameterPath === "string" ? parameterPath : parameterPath[0]
+      )
+    ) {
+      options.recursive = false;
+    }
+    return super.getParameterValue(parameterPath, options);
+  }
+
+  /**
+   * Retrieves and evaluates the `simulation_options` parameter, considering nested properties and
+   * global simulation options.
+   */
+  public getSimulationOptions() {
+    const simulationOptions: SimulationOptions = this.getParameterValue("simulation_options", {
+      replaceResult: (result = {}) => {
+        if (typeof result === "string") {
+          // Look up the global simulation options by their key
+          const globalSimulationOptions = this.dependencies.getGlobalSimulationOptions();
+          result = globalSimulationOptions[result] ?? globalSimulationOptions["default"] ?? {};
+        }
+
+        return deepMerge(
+          deepCopy(this.dependencies.getGlobalSimulationOptions().default),
+          deepCopy(result)
+        );
+      },
+    });
+
+    if (typeof simulationOptions === "undefined") {
+      return {};
+    }
+
+    simulationOptions.mode = this.getParameterValue(["simulation_options", "mode"]);
+    simulationOptions.simulate = this.getParameterValue(["simulation_options", "simulate"]);
+    simulationOptions.data = this.getParameterValue(["simulation_options", "data"]);
+
+    if (typeof simulationOptions.data === "object") {
+      simulationOptions.data = Object.fromEntries(
+        Object.keys(simulationOptions.data).map((key) => [
+          key,
+          this.getParameterValue(["simulation_options", "data", key]),
+        ])
+      );
+    }
+
+    return simulationOptions;
+  }
+
+  /**
+   * Returns the result object of this trial or `undefined` if the result is not yet known or the
+   * `record_data` trial parameter is `false`.
+   */
+  public getResult() {
+    return this.getParameterValue("record_data") === false ? undefined : this.result;
+  }
+
+  public getResults() {
+    const result = this.getResult();
+    return result ? [result] : [];
+  }
+
+  /**
+   * Checks that the parameters provided in the trial description align with the plugin's info
+   * object, resolves missing parameter values from the parent timeline, resolves timeline variable
+   * parameters, evaluates parameter functions if the expected parameter type is not `FUNCTION`, and
+   * sets default values for optional parameters.
+   */
+  private processParameters() {
+    const assignParameterValues = (
+      parameterObject: Record<string, any>,
+      parameterInfos: ParameterInfos,
+      parentParameterPath: string[] = []
+    ) => {
+      for (const [parameterName, parameterConfig] of Object.entries(parameterInfos)) {
+        const parameterPath = [...parentParameterPath, parameterName];
+
+        let parameterValue = this.getParameterValue(parameterPath, {
+          evaluateFunctions: parameterConfig.type !== ParameterType.FUNCTION,
+          replaceResult: (originalResult) => {
+            if (typeof originalResult === "undefined") {
+              if (typeof parameterConfig.default === "undefined") {
+                throw new Error(
+                  `You must specify a value for the "${parameterPathArrayToString(
+                    parameterPath
+                  )}" parameter in the "${this.pluginInfo.name}" plugin.`
+                );
+              } else {
+                return parameterConfig.default;
+              }
+            } else {
+              return originalResult;
+            }
+          },
+        });
+
+        if (parameterConfig.array && !Array.isArray(parameterValue)) {
+          const parameterPathString = parameterPathArrayToString(parameterPath);
+          throw new Error(
+            `A non-array value (\`${parameterValue}\`) was provided for the array parameter "${parameterPathString}" in the "${this.pluginInfo.name}" plugin. Please make sure that "${parameterPathString}" is an array.`
+          );
+        }
+
+        if (parameterConfig.type === ParameterType.COMPLEX && parameterConfig.nested) {
+          // Assign parameter values according to the `nested` schema
+          if (parameterConfig.array) {
+            // ...for each nested array element
+            parameterValue = parameterValue.map((_, arrayIndex) => {
+              const arrayElementPath = [...parameterPath, arrayIndex.toString()];
+              const arrayElementValue = this.getParameterValue(arrayElementPath);
+              assignParameterValues(arrayElementValue, parameterConfig.nested, arrayElementPath);
+              return arrayElementValue;
+            });
+          } else {
+            // ...for the nested object
+            assignParameterValues(parameterValue, parameterConfig.nested, parameterPath);
+          }
+        }
+
+        parameterObject[parameterName] = parameterValue;
+      }
+    };
+
+    const trialObject = deepCopy(this.description);
+    assignParameterValues(trialObject, this.pluginInfo.parameters);
+    this.trialObject = trialObject;
+  }
+
+  public getLatestNode() {
+    return this;
+  }
+
+  public getActiveTimelineByName(name: string): Timeline | undefined {
+    // This returns undefined because the function is looking
+    // for a timeline. If we get to this point, then none
+    // of the parent nodes match the name.
+    return undefined;
+  }
+}

package/src/timeline/index.ts

@@ -0,0 +1,232 @@
+import { Class } from "type-fest";
+
+import { JsPsychExtension } from "../modules/extensions";
+import { JsPsychPlugin, PluginInfo } from "../modules/plugins";
+import { Trial } from "./Trial";
+import { PromiseWrapper } from "./util";
+
+export class TimelineVariable {
+  constructor(public readonly name: string) {}
+}
+
+export type Parameter<T> = T | (() => T) | TimelineVariable;
+
+export type TrialExtensionsConfiguration = Array<{
+  type: Class<JsPsychExtension>;
+  params?: Record<string, any>;
+}>;
+
+export type SimulationMode = "visual" | "data-only";
+
+export type SimulationOptions = {
+  data?: Record<string, any>;
+  mode?: SimulationMode;
+  simulate?: boolean;
+};
+
+export type SimulationOptionsParameter = Parameter<{
+  data?: Parameter<Record<string, Parameter<any>>>;
+  mode?: Parameter<SimulationMode>;
+  simulate?: Parameter<boolean>;
+}>;
+
+export interface TrialDescription extends Record<string, any> {
+  type: Parameter<Class<JsPsychPlugin<any>>>;
+
+  /** https://www.jspsych.org/latest/overview/plugins/#the-post_trial_gap-iti-parameter */
+  post_trial_gap?: Parameter<number>;
+
+  /** https://www.jspsych.org/latest/overview/plugins/#the-save_trial_parameters-parameter */
+  save_trial_parameters?: Parameter<Record<string, boolean>>;
+
+  /**
+   * Whether to include the values of timeline variables under a `timeline_variables` key. Can be
+   * `true` to save the values of all timeline variables, or an array of timeline variable names to
+   * only save specific timeline variables. Defaults to `false`.
+   */
+  save_timeline_variables?: Parameter<boolean | string[]>;
+
+  /** https://www.jspsych.org/latest/overview/style/#using-the-css_classes-trial-parameter */
+  css_classes?: Parameter<string | string[]>;
+
+  /** https://www.jspsych.org/latest/overview/simulation/#controlling-simulation-mode-with-simulation_options */
+  simulation_options?: SimulationOptionsParameter | string;
+
+  /** https://www.jspsych.org/latest/overview/extensions/ */
+  extensions?: Parameter<TrialExtensionsConfiguration>;
+
+  /**
+   * Whether to record the data of this trial. Defaults to `true`.
+   */
+  record_data?: Parameter<boolean>;
+
+  // Events
+
+  /** https://www.jspsych.org/latest/overview/events/#on_start-trial */
+  on_start?: (trial: any) => void;
+
+  /** https://www.jspsych.org/latest/overview/events/#on_load */
+  on_load?: () => void;
+
+  /** https://www.jspsych.org/latest/overview/events/#on_finish-trial */
+  on_finish?: (data: any) => void;
+}
+
+/** https://www.jspsych.org/latest/overview/timeline/#sampling-methods */
+export type SampleOptions =
+  | { type: "with-replacement"; size: number; weights?: number[] }
+  | { type: "without-replacement"; size: number }
+  | { type: "fixed-repetitions"; size: number }
+  | { type: "alternate-groups"; groups: number[][]; randomize_group_order?: boolean }
+  | { type: "custom"; fn: (ids: number[]) => number[] };
+
+export type TimelineArray = Array<TimelineDescription | TrialDescription | TimelineArray>;
+
+export interface TimelineDescription extends Record<string, any> {
+  timeline: TimelineArray;
+  timeline_variables?: Record<string, any>[];
+
+  name?: string;
+
+  // Control flow
+
+  /** https://www.jspsych.org/latest/overview/timeline/#repeating-a-set-of-trials */
+  repetitions?: number;
+
+  /** https://www.jspsych.org/latest/overview/timeline/#looping-timelines */
+  loop_function?: (data: any) => boolean;
+
+  /** https://www.jspsych.org/latest/overview/timeline/#conditional-timelines */
+  conditional_function?: () => boolean;
+
+  // Randomization
+
+  /** https://www.jspsych.org/latest/overview/timeline/#random-orders-of-trials */
+  randomize_order?: boolean;
+
+  /** https://www.jspsych.org/latest/overview/timeline/#sampling-methods */
+  sample?: SampleOptions;
+
+  // Events
+
+  /** https://www.jspsych.org/latest/overview/events/#on_timeline_start */
+  on_timeline_start?: () => void;
+
+  /** https://www.jspsych.org/latest/overview/events/#on_timeline_finish */
+  on_timeline_finish?: () => void;
+}
+
+export const timelineDescriptionKeys = [
+  "timeline",
+  "timeline_variables",
+  "name",
+  "repetitions",
+  "loop_function",
+  "conditional_function",
+  "randomize_order",
+  "sample",
+  "on_timeline_start",
+  "on_timeline_finish",
+];
+
+export function isTrialDescription(
+  description: TrialDescription | TimelineDescription
+): description is TrialDescription {
+  return !isTimelineDescription(description);
+}
+
+export function isTimelineDescription(
+  description: TrialDescription | TimelineDescription | TimelineArray
+): description is TimelineDescription | TimelineArray {
+  return Boolean((description as TimelineDescription).timeline) || Array.isArray(description);
+}
+
+export enum TimelineNodeStatus {
+  PENDING,
+  RUNNING,
+  PAUSED,
+  COMPLETED,
+  ABORTED,
+}
+
+/**
+ * Functions and options needed by `TimelineNode`s, provided by the `JsPsych` instance. This
+ * approach allows to keep the public `JsPsych` API slim and decouples the `JsPsych` and timeline
+ * node classes, simplifying unit testing.
+ */
+export interface TimelineNodeDependencies {
+  /**
+   * Called at the start of a trial, prior to invoking the plugin's trial method.
+   */
+  onTrialStart: (trial: Trial) => void;
+
+  /**
+   * Called when a trial's result data is available, before invoking `onTrialFinished()`.
+   */
+  onTrialResultAvailable: (trial: Trial) => void;
+
+  /**
+   * Called after a trial has finished.
+   */
+  onTrialFinished: (trial: Trial) => void;
+
+  /**
+   * Invoke `on_start` extension callbacks according to `extensionsConfiguration`
+   */
+  runOnStartExtensionCallbacks(extensionsConfiguration: TrialExtensionsConfiguration): void;
+
+  /**
+   * Invoke `on_load` extension callbacks according to `extensionsConfiguration`
+   */
+  runOnLoadExtensionCallbacks(extensionsConfiguration: TrialExtensionsConfiguration): void;
+
+  /**
+   * Invoke `on_finish` extension callbacks according to `extensionsConfiguration` and return a
+   * joint extensions result object
+   */
+  runOnFinishExtensionCallbacks(
+    extensionsConfiguration: TrialExtensionsConfiguration
+  ): Promise<Record<string, any>>;
+
+  /**
+   * Returns the simulation mode or `undefined`, if the experiment is not running in simulation
+   * mode.
+   */
+  getSimulationMode(): SimulationMode | undefined;
+
+  /**
+   * Returns the global simulation options as passed to `jsPsych.simulate()`
+   */
+  getGlobalSimulationOptions(): Record<string, SimulationOptionsParameter>;
+
+  /**
+   * Given a plugin class, create a new instance of it and return it.
+   */
+  instantiatePlugin: <Info extends PluginInfo>(
+    pluginClass: Class<JsPsychPlugin<Info>>
+  ) => JsPsychPlugin<Info>;
+
+  /**
+   * Return JsPsych's display element so it can be provided to plugins
+   */
+  getDisplayElement: () => HTMLElement;
+
+  /**
+   * Return the default inter-trial interval as provided to `initJsPsych()`
+   */
+  getDefaultIti: () => number;
+
+  /**
+   * A `PromiseWrapper` whose promise is resolved with result data whenever `jsPsych.finishTrial()`
+   * is called.
+   */
+  finishTrialPromise: PromiseWrapper<TrialResult | void>;
+
+  /**
+   * Clear all of the timeouts
+   */
+  clearAllTimeouts: () => void;
+}
+
+export type TrialResult = Record<string, any>;
+export type TrialResults = Array<Record<string, any>>;