jspsych 7.3.1 → 7.3.3

package/dist/modules/plugin-api/SimulationAPI.d.ts

@@ -1,4 +1,7 @@
 export declare class SimulationAPI {
+    private getDisplayContainerElement;
+    private setJsPsychTimeout;
+    constructor(getDisplayContainerElement: () => HTMLElement, setJsPsychTimeout: (callback: () => void, delay: number) => number);
     dispatchEvent(event: Event): void;
     /**
      * Dispatches a `keydown` event for the specified key

package/dist/modules/plugin-api/TimeoutAPI.d.ts

@@ -1,5 +1,17 @@
+/**
+ * A class that provides a wrapper around the global setTimeout and clearTimeout functions.
+ */
 export declare class TimeoutAPI {
     private timeout_handlers;
-    setTimeout(callback: any, delay: any): number;
+    /**
+     * Calls a function after a specified delay, in milliseconds.
+     * @param callback The function to call after the delay.
+     * @param delay The number of milliseconds to wait before calling the function.
+     * @returns A handle that can be used to clear the timeout with clearTimeout.
+     */
+    setTimeout(callback: () => void, delay: number): number;
+    /**
+     * Clears all timeouts that have been created with setTimeout.
+     */
     clearAllTimeouts(): void;
 }

package/dist/modules/utils.d.ts

@@ -5,3 +5,9 @@
  */
 export declare function unique(arr: Array<any>): any[];
 export declare function deepCopy(obj: any): any;
+/**
+ * Merges two objects, recursively.
+ * @param obj1 Object to merge
+ * @param obj2 Object to merge
+ */
+export declare function deepMerge(obj1: any, obj2: any): any;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jspsych",
-  "version": "7.3.1",
+  "version": "7.3.3",
   "description": "Behavioral experiments in a browser",
   "type": "module",
   "main": "dist/index.cjs",
@@ -55,7 +55,7 @@
     "npm-run-all": "^4.1.5",
     "sass": "^1.43.5",
     "sass-loader": "^12.4.0",
-    "webpack": "^5.68.0",
+    "webpack": "^5.76.0",
     "webpack-cli": "^4.9.2",
     "webpack-remove-empty-scripts": "^0.7.2",
     "replace-in-file-webpack-plugin": "^1.0.6"

package/src/JsPsych.ts

@@ -627,13 +627,14 @@ export class JsPsych {
     };
 
     let trial_complete;
+    let trial_sim_opts;
+    let trial_sim_opts_merged;
     if (!this.simulation_mode) {
       trial_complete = trial.type.trial(this.DOM_target, trial, load_callback);
     }
     if (this.simulation_mode) {
       // check if the trial supports simulation
       if (trial.type.simulate) {
-        let trial_sim_opts;
         if (!trial.simulation_options) {
           trial_sim_opts = this.simulation_options.default;
         }
@@ -656,16 +657,23 @@ export class JsPsych {
             trial_sim_opts = trial.simulation_options;
           }
         }
-        trial_sim_opts = this.utils.deepCopy(trial_sim_opts);
-        trial_sim_opts = this.replaceFunctionsWithValues(trial_sim_opts, null);
+        // merge in default options that aren't overriden by the trial's simulation_options
+        // including nested parameters in the simulation_options
+        trial_sim_opts_merged = this.utils.deepMerge(
+          this.simulation_options.default,
+          trial_sim_opts
+        );
 
-        if (trial_sim_opts?.simulate === false) {
+        trial_sim_opts_merged = this.utils.deepCopy(trial_sim_opts_merged);
+        trial_sim_opts_merged = this.replaceFunctionsWithValues(trial_sim_opts_merged, null);
+
+        if (trial_sim_opts_merged?.simulate === false) {
           trial_complete = trial.type.trial(this.DOM_target, trial, load_callback);
         } else {
           trial_complete = trial.type.simulate(
             trial,
-            trial_sim_opts?.mode || this.simulation_mode,
-            trial_sim_opts,
+            trial_sim_opts_merged?.mode || this.simulation_mode,
+            trial_sim_opts_merged,
             load_callback
           );
         }
@@ -678,8 +686,13 @@ export class JsPsych {
     // see if trial_complete is a Promise by looking for .then() function
     const is_promise = trial_complete && typeof trial_complete.then == "function";
 
-    // in simulation mode we let the simulate function call the load_callback always.
-    if (!is_promise && !this.simulation_mode) {
+    // in simulation mode we let the simulate function call the load_callback always,
+    // so we don't need to call it here. however, if we are in simulation mode but not simulating
+    // this particular trial we need to call it.
+    if (
+      !is_promise &&
+      (!this.simulation_mode || (this.simulation_mode && trial_sim_opts_merged?.simulate === false))
+    ) {
       load_callback();
     }
 
@@ -781,7 +794,14 @@ export class JsPsych {
     for (const param in trial.type.info.parameters) {
       // check if parameter is complex with nested defaults
       if (trial.type.info.parameters[param].type === ParameterType.COMPLEX) {
-        if (trial.type.info.parameters[param].array === true) {
+        // check if parameter is undefined and has a default value
+        if (typeof trial[param] === "undefined" && trial.type.info.parameters[param].default) {
+          trial[param] = trial.type.info.parameters[param].default;
+        }
+        // if parameter is an array, iterate over each entry after confirming that there are
+        // entries to iterate over. this is common when some parameters in a COMPLEX type have
+        // default values and others do not.
+        if (trial.type.info.parameters[param].array === true && Array.isArray(trial[param])) {
           // iterate over each entry in the array
           trial[param].forEach(function (ip, i) {
             // check each parameter in the plugin description
@@ -789,13 +809,7 @@ export class JsPsych {
               if (typeof trial[param][i][p] === "undefined" || trial[param][i][p] === null) {
                 if (typeof trial.type.info.parameters[param].nested[p].default === "undefined") {
                   console.error(
-                    "You must specify a value for the " +
-                      p +
-                      " parameter (nested in the " +
-                      param +
-                      " parameter) in the " +
-                      trial.type +
-                      " plugin."
+                    `You must specify a value for the ${p} parameter (nested in the ${param} parameter) in the ${trial.type.info.name} plugin.`
                   );
                 } else {
                   trial[param][i][p] = trial.type.info.parameters[param].nested[p].default;
@@ -809,11 +823,7 @@ export class JsPsych {
       else if (typeof trial[param] === "undefined" || trial[param] === null) {
         if (typeof trial.type.info.parameters[param].default === "undefined") {
           console.error(
-            "You must specify a value for the " +
-              param +
-              " parameter in the " +
-              trial.type.info.name +
-              " plugin."
+            `You must specify a value for the ${param} parameter in the ${trial.type.info.name} plugin.`
           );
         } else {
           trial[param] = trial.type.info.parameters[param].default;

package/src/modules/plugin-api/SimulationAPI.ts

@@ -1,6 +1,11 @@
 export class SimulationAPI {
+  constructor(
+    private getDisplayContainerElement: () => HTMLElement,
+    private setJsPsychTimeout: (callback: () => void, delay: number) => number
+  ) {}
+
   dispatchEvent(event: Event) {
-    document.body.dispatchEvent(event);
+    this.getDisplayContainerElement().dispatchEvent(event);
   }
 
   /**
@@ -26,7 +31,7 @@ export class SimulationAPI {
    */
   pressKey(key: string, delay = 0) {
     if (delay > 0) {
-      setTimeout(() => {
+      this.setJsPsychTimeout(() => {
         this.keyDown(key);
         this.keyUp(key);
       }, delay);
@@ -43,7 +48,7 @@ export class SimulationAPI {
    */
   clickTarget(target: Element, delay = 0) {
     if (delay > 0) {
-      setTimeout(() => {
+      this.setJsPsychTimeout(() => {
         target.dispatchEvent(new MouseEvent("mousedown", { bubbles: true }));
         target.dispatchEvent(new MouseEvent("mouseup", { bubbles: true }));
         target.dispatchEvent(new MouseEvent("click", { bubbles: true }));
@@ -63,7 +68,7 @@ export class SimulationAPI {
    */
   fillTextInput(target: HTMLInputElement, text: string, delay = 0) {
     if (delay > 0) {
-      setTimeout(() => {
+      this.setJsPsychTimeout(() => {
         target.value = text;
       }, delay);
     } else {

package/src/modules/plugin-api/TimeoutAPI.ts

@@ -1,13 +1,25 @@
+/**
+ * A class that provides a wrapper around the global setTimeout and clearTimeout functions.
+ */
 export class TimeoutAPI {
-  private timeout_handlers = [];
+  private timeout_handlers: number[] = [];
 
-  setTimeout(callback, delay) {
+  /**
+   * Calls a function after a specified delay, in milliseconds.
+   * @param callback The function to call after the delay.
+   * @param delay The number of milliseconds to wait before calling the function.
+   * @returns A handle that can be used to clear the timeout with clearTimeout.
+   */
+  setTimeout(callback: () => void, delay: number): number {
     const handle = window.setTimeout(callback, delay);
     this.timeout_handlers.push(handle);
     return handle;
   }
 
-  clearAllTimeouts() {
+  /**
+   * Clears all timeouts that have been created with setTimeout.
+   */
+  clearAllTimeouts(): void {
     for (const handler of this.timeout_handlers) {
       clearTimeout(handler);
     }

package/src/modules/plugin-api/index.ts

@@ -9,19 +9,22 @@ import { TimeoutAPI } from "./TimeoutAPI";
 
 export function createJointPluginAPIObject(jsPsych: JsPsych) {
   const settings = jsPsych.getInitSettings();
+  const keyboardListenerAPI = autoBind(
+    new KeyboardListenerAPI(
+      jsPsych.getDisplayContainerElement,
+      settings.case_sensitive_responses,
+      settings.minimum_valid_rt
+    )
+  );
+  const timeoutAPI = autoBind(new TimeoutAPI());
+  const mediaAPI = autoBind(new MediaAPI(settings.use_webaudio, jsPsych.webaudio_context));
+  const hardwareAPI = autoBind(new HardwareAPI());
+  const simulationAPI = autoBind(
+    new SimulationAPI(jsPsych.getDisplayContainerElement, timeoutAPI.setTimeout)
+  );
   return Object.assign(
     {},
-    ...[
-      new KeyboardListenerAPI(
-        jsPsych.getDisplayContainerElement,
-        settings.case_sensitive_responses,
-        settings.minimum_valid_rt
-      ),
-      new TimeoutAPI(),
-      new MediaAPI(settings.use_webaudio, jsPsych.webaudio_context),
-      new HardwareAPI(),
-      new SimulationAPI(),
-    ].map((object) => autoBind(object))
+    ...[keyboardListenerAPI, timeoutAPI, mediaAPI, hardwareAPI, simulationAPI]
   ) as KeyboardListenerAPI & TimeoutAPI & MediaAPI & HardwareAPI & SimulationAPI;
 }
 

package/src/modules/utils.ts

@@ -28,3 +28,34 @@ export function deepCopy(obj) {
     return obj;
   }
 }
+
+/**
+ * Merges two objects, recursively.
+ * @param obj1 Object to merge
+ * @param obj2 Object to merge
+ */
+export function deepMerge(obj1: any, obj2: any): any {
+  let merged = {};
+  for (const key in obj1) {
+    if (obj1.hasOwnProperty(key)) {
+      if (typeof obj1[key] === "object" && obj2.hasOwnProperty(key)) {
+        merged[key] = deepMerge(obj1[key], obj2[key]);
+      } else {
+        merged[key] = obj1[key];
+      }
+    }
+  }
+  for (const key in obj2) {
+    if (obj2.hasOwnProperty(key)) {
+      if (!merged.hasOwnProperty(key)) {
+        merged[key] = obj2[key];
+      } else if (typeof obj2[key] === "object") {
+        merged[key] = deepMerge(merged[key], obj2[key]);
+      } else {
+        merged[key] = obj2[key];
+      }
+    }
+  }
+
+  return merged;
+}