jspsych 7.3.2 → 7.3.4

package/dist/modules/plugins.d.ts

@@ -1,136 +1,136 @@
-/**
-Flatten the type output to improve type hints shown in editors.
-Borrowed from type-fest
-*/
-declare type Simplify<T> = {
-    [KeyType in keyof T]: T[KeyType];
-};
-/**
-Create a type that makes the given keys required. The remaining keys are kept as is.
-Borrowed from type-fest
-*/
-declare type SetRequired<BaseType, Keys extends keyof BaseType> = Simplify<Omit<BaseType, Keys> & Required<Pick<BaseType, Keys>>>;
-/**
- * Parameter types for plugins
- */
-export declare enum ParameterType {
-    BOOL = 0,
-    STRING = 1,
-    INT = 2,
-    FLOAT = 3,
-    FUNCTION = 4,
-    KEY = 5,
-    KEYS = 6,
-    SELECT = 7,
-    HTML_STRING = 8,
-    IMAGE = 9,
-    AUDIO = 10,
-    VIDEO = 11,
-    OBJECT = 12,
-    COMPLEX = 13,
-    TIMELINE = 14
-}
-declare type ParameterTypeMap = {
-    [ParameterType.BOOL]: boolean;
-    [ParameterType.STRING]: string;
-    [ParameterType.INT]: number;
-    [ParameterType.FLOAT]: number;
-    [ParameterType.FUNCTION]: (...args: any[]) => any;
-    [ParameterType.KEY]: string;
-    [ParameterType.KEYS]: string[] | "ALL_KEYS" | "NO_KEYS";
-    [ParameterType.SELECT]: any;
-    [ParameterType.HTML_STRING]: string;
-    [ParameterType.IMAGE]: string;
-    [ParameterType.AUDIO]: string;
-    [ParameterType.VIDEO]: string;
-    [ParameterType.OBJECT]: object;
-    [ParameterType.COMPLEX]: any;
-    [ParameterType.TIMELINE]: any;
-};
-export interface ParameterInfo {
-    type: ParameterType;
-    array?: boolean;
-    pretty_name?: string;
-    default?: any;
-    preload?: boolean;
-}
-export interface ParameterInfos {
-    [key: string]: ParameterInfo;
-}
-declare type InferredParameter<I extends ParameterInfo> = I["array"] extends true ? Array<ParameterTypeMap[I["type"]]> : ParameterTypeMap[I["type"]];
-declare type RequiredParameterNames<I extends ParameterInfos> = {
-    [K in keyof I]: I[K]["default"] extends undefined ? K : never;
-}[keyof I];
-declare type InferredParameters<I extends ParameterInfos> = SetRequired<{
-    [Property in keyof I]?: InferredParameter<I[Property]>;
-}, RequiredParameterNames<I>>;
-export declare const universalPluginParameters: {
-    /**
-     * Data to add to this trial (key-value pairs)
-     */
-    readonly data: {
-        readonly type: ParameterType.OBJECT;
-        readonly pretty_name: "Data";
-        readonly default: {};
-    };
-    /**
-     * Function to execute when trial begins
-     */
-    readonly on_start: {
-        readonly type: ParameterType.FUNCTION;
-        readonly pretty_name: "On start";
-        readonly default: () => void;
-    };
-    /**
-     * Function to execute when trial is finished
-     */
-    readonly on_finish: {
-        readonly type: ParameterType.FUNCTION;
-        readonly pretty_name: "On finish";
-        readonly default: () => void;
-    };
-    /**
-     * Function to execute after the trial has loaded
-     */
-    readonly on_load: {
-        readonly type: ParameterType.FUNCTION;
-        readonly pretty_name: "On load";
-        readonly default: () => void;
-    };
-    /**
-     * Length of gap between the end of this trial and the start of the next trial
-     */
-    readonly post_trial_gap: {
-        readonly type: ParameterType.INT;
-        readonly pretty_name: "Post trial gap";
-        readonly default: any;
-    };
-    /**
-     * A list of CSS classes to add to the jsPsych display element for the duration of this trial
-     */
-    readonly css_classes: {
-        readonly type: ParameterType.STRING;
-        readonly pretty_name: "Custom CSS classes";
-        readonly default: any;
-    };
-    /**
-     * Options to control simulation mode for the trial.
-     */
-    readonly simulation_options: {
-        readonly type: ParameterType.COMPLEX;
-        readonly default: any;
-    };
-};
-export declare type UniversalPluginParameters = InferredParameters<typeof universalPluginParameters>;
-export interface PluginInfo {
-    name: string;
-    parameters: {
-        [key: string]: ParameterInfo;
-    };
-}
-export interface JsPsychPlugin<I extends PluginInfo> {
-    trial(display_element: HTMLElement, trial: TrialType<I>, on_load?: () => void): void | Promise<any>;
-}
-export declare type TrialType<I extends PluginInfo> = InferredParameters<I["parameters"]> & UniversalPluginParameters;
-export declare type PluginParameters<I extends PluginInfo> = InferredParameters<I["parameters"]>;
-export {};
+/**
+Flatten the type output to improve type hints shown in editors.
+Borrowed from type-fest
+*/
+type Simplify<T> = {
+    [KeyType in keyof T]: T[KeyType];
+};
+/**
+Create a type that makes the given keys required. The remaining keys are kept as is.
+Borrowed from type-fest
+*/
+type SetRequired<BaseType, Keys extends keyof BaseType> = Simplify<Omit<BaseType, Keys> & Required<Pick<BaseType, Keys>>>;
+/**
+ * Parameter types for plugins
+ */
+export declare enum ParameterType {
+    BOOL = 0,
+    STRING = 1,
+    INT = 2,
+    FLOAT = 3,
+    FUNCTION = 4,
+    KEY = 5,
+    KEYS = 6,
+    SELECT = 7,
+    HTML_STRING = 8,
+    IMAGE = 9,
+    AUDIO = 10,
+    VIDEO = 11,
+    OBJECT = 12,
+    COMPLEX = 13,
+    TIMELINE = 14
+}
+type ParameterTypeMap = {
+    [ParameterType.BOOL]: boolean;
+    [ParameterType.STRING]: string;
+    [ParameterType.INT]: number;
+    [ParameterType.FLOAT]: number;
+    [ParameterType.FUNCTION]: (...args: any[]) => any;
+    [ParameterType.KEY]: string;
+    [ParameterType.KEYS]: string[] | "ALL_KEYS" | "NO_KEYS";
+    [ParameterType.SELECT]: any;
+    [ParameterType.HTML_STRING]: string;
+    [ParameterType.IMAGE]: string;
+    [ParameterType.AUDIO]: string;
+    [ParameterType.VIDEO]: string;
+    [ParameterType.OBJECT]: object;
+    [ParameterType.COMPLEX]: any;
+    [ParameterType.TIMELINE]: any;
+};
+export interface ParameterInfo {
+    type: ParameterType;
+    array?: boolean;
+    pretty_name?: string;
+    default?: any;
+    preload?: boolean;
+}
+export interface ParameterInfos {
+    [key: string]: ParameterInfo;
+}
+type InferredParameter<I extends ParameterInfo> = I["array"] extends true ? Array<ParameterTypeMap[I["type"]]> : ParameterTypeMap[I["type"]];
+type RequiredParameterNames<I extends ParameterInfos> = {
+    [K in keyof I]: I[K]["default"] extends undefined ? K : never;
+}[keyof I];
+type InferredParameters<I extends ParameterInfos> = SetRequired<{
+    [Property in keyof I]?: InferredParameter<I[Property]>;
+}, RequiredParameterNames<I>>;
+export declare const universalPluginParameters: {
+    /**
+     * Data to add to this trial (key-value pairs)
+     */
+    readonly data: {
+        readonly type: ParameterType.OBJECT;
+        readonly pretty_name: "Data";
+        readonly default: {};
+    };
+    /**
+     * Function to execute when trial begins
+     */
+    readonly on_start: {
+        readonly type: ParameterType.FUNCTION;
+        readonly pretty_name: "On start";
+        readonly default: () => void;
+    };
+    /**
+     * Function to execute when trial is finished
+     */
+    readonly on_finish: {
+        readonly type: ParameterType.FUNCTION;
+        readonly pretty_name: "On finish";
+        readonly default: () => void;
+    };
+    /**
+     * Function to execute after the trial has loaded
+     */
+    readonly on_load: {
+        readonly type: ParameterType.FUNCTION;
+        readonly pretty_name: "On load";
+        readonly default: () => void;
+    };
+    /**
+     * Length of gap between the end of this trial and the start of the next trial
+     */
+    readonly post_trial_gap: {
+        readonly type: ParameterType.INT;
+        readonly pretty_name: "Post trial gap";
+        readonly default: any;
+    };
+    /**
+     * A list of CSS classes to add to the jsPsych display element for the duration of this trial
+     */
+    readonly css_classes: {
+        readonly type: ParameterType.STRING;
+        readonly pretty_name: "Custom CSS classes";
+        readonly default: any;
+    };
+    /**
+     * Options to control simulation mode for the trial.
+     */
+    readonly simulation_options: {
+        readonly type: ParameterType.COMPLEX;
+        readonly default: any;
+    };
+};
+export type UniversalPluginParameters = InferredParameters<typeof universalPluginParameters>;
+export interface PluginInfo {
+    name: string;
+    parameters: {
+        [key: string]: ParameterInfo;
+    };
+}
+export interface JsPsychPlugin<I extends PluginInfo> {
+    trial(display_element: HTMLElement, trial: TrialType<I>, on_load?: () => void): void | Promise<any>;
+}
+export type TrialType<I extends PluginInfo> = InferredParameters<I["parameters"]> & UniversalPluginParameters;
+export type PluginParameters<I extends PluginInfo> = InferredParameters<I["parameters"]>;
+export {};

package/dist/modules/randomization.d.ts

@@ -1,42 +1,42 @@
-/**
- * Uses the `seedrandom` package to replace Math.random() with a seedable PRNG.
- *
- * @param seed An optional seed. If none is given, a random seed will be generated.
- * @returns The seed value.
- */
-export declare function setSeed(seed?: string): string;
-export declare function repeat(array: any, repetitions: any, unpack?: boolean): any;
-export declare function shuffle(array: Array<any>): any[];
-export declare function shuffleNoRepeats(arr: Array<any>, equalityTest: (a: any, b: any) => boolean): any[];
-export declare function shuffleAlternateGroups(arr_groups: any, random_group_order?: boolean): any[];
-export declare function sampleWithoutReplacement(arr: any, size: any): any[];
-export declare function sampleWithReplacement(arr: any, size: any, weights?: any): any[];
-export declare function factorial(factors: Record<string, any>, repetitions?: number, unpack?: boolean): any;
-export declare function randomID(length?: number): string;
-/**
- * Generate a random integer from `lower` to `upper`, inclusive of both end points.
- * @param lower The lowest value it is possible to generate
- * @param upper The highest value it is possible to generate
- * @returns A random integer
- */
-export declare function randomInt(lower: number, upper: number): number;
-/**
- * Generates a random sample from a Bernoulli distribution.
- * @param p The probability of sampling 1.
- * @returns 0, with probability 1-p, or 1, with probability p.
- */
-export declare function sampleBernoulli(p: number): 0 | 1;
-export declare function sampleNormal(mean: number, standard_deviation: number): number;
-export declare function sampleExponential(rate: number): number;
-export declare function sampleExGaussian(mean: number, standard_deviation: number, rate: number, positive?: boolean): number;
-/**
- * Generate one or more random words.
- *
- * This is a wrapper function for the {@link https://www.npmjs.com/package/random-words `random-words` npm package}.
- *
- * @param opts An object with optional properties `min`, `max`, `exactly`,
- * `join`, `maxLength`, `wordsPerString`, `separator`, and `formatter`.
- *
- * @returns An array of words or a single string, depending on parameter choices.
- */
-export declare function randomWords(opts: any): any;
+/**
+ * Uses the `seedrandom` package to replace Math.random() with a seedable PRNG.
+ *
+ * @param seed An optional seed. If none is given, a random seed will be generated.
+ * @returns The seed value.
+ */
+export declare function setSeed(seed?: string): string;
+export declare function repeat(array: any, repetitions: any, unpack?: boolean): any;
+export declare function shuffle(array: Array<any>): any[];
+export declare function shuffleNoRepeats(arr: Array<any>, equalityTest: (a: any, b: any) => boolean): any[];
+export declare function shuffleAlternateGroups(arr_groups: any, random_group_order?: boolean): any[];
+export declare function sampleWithoutReplacement(arr: any, size: any): any[];
+export declare function sampleWithReplacement(arr: any, size: any, weights?: any): any[];
+export declare function factorial(factors: Record<string, any>, repetitions?: number, unpack?: boolean): any;
+export declare function randomID(length?: number): string;
+/**
+ * Generate a random integer from `lower` to `upper`, inclusive of both end points.
+ * @param lower The lowest value it is possible to generate
+ * @param upper The highest value it is possible to generate
+ * @returns A random integer
+ */
+export declare function randomInt(lower: number, upper: number): number;
+/**
+ * Generates a random sample from a Bernoulli distribution.
+ * @param p The probability of sampling 1.
+ * @returns 0, with probability 1-p, or 1, with probability p.
+ */
+export declare function sampleBernoulli(p: number): 0 | 1;
+export declare function sampleNormal(mean: number, standard_deviation: number): number;
+export declare function sampleExponential(rate: number): number;
+export declare function sampleExGaussian(mean: number, standard_deviation: number, rate: number, positive?: boolean): number;
+/**
+ * Generate one or more random words.
+ *
+ * This is a wrapper function for the {@link https://www.npmjs.com/package/random-words `random-words` npm package}.
+ *
+ * @param opts An object with optional properties `min`, `max`, `exactly`,
+ * `join`, `maxLength`, `wordsPerString`, `separator`, and `formatter`.
+ *
+ * @returns An array of words or a single string, depending on parameter choices.
+ */
+export declare function randomWords(opts: any): string[];

package/dist/modules/turk.d.ts

@@ -1,40 +1,40 @@
-interface turkInformation {
-    /**
-     * Is the experiment being loaded in preview mode on Mechanical Turk?
-     */
-    previewMode: boolean;
-    /**
-     * Is the experiment being loaded outside of the Mechanical Turk environment?
-     */
-    outsideTurk: boolean;
-    /**
-     * The HIT ID.
-     */
-    hitId: string;
-    /**
-     * The Assignment ID.
-     */
-    assignmentId: string;
-    /**
-     * The worker ID.
-     */
-    workerId: string;
-    /**
-     * URL for submission of the HIT.
-     */
-    turkSubmitTo: string;
-}
-/**
- * Gets information about the Mechanical Turk Environment, HIT, Assignment, and Worker
- * by parsing the URL variables that Mechanical Turk generates.
- * @returns An object containing information about the Mechanical Turk Environment, HIT, Assignment, and Worker.
- */
-export declare function turkInfo(): turkInformation;
-/**
- * Send data to Mechnical Turk for storage.
- * @param data An object containing `key:value` pairs to send to Mechanical Turk. Values
- * cannot contain nested objects, arrays, or functions.
- * @returns Nothing
- */
-export declare function submitToTurk(data: any): void;
-export {};
+interface turkInformation {
+    /**
+     * Is the experiment being loaded in preview mode on Mechanical Turk?
+     */
+    previewMode: boolean;
+    /**
+     * Is the experiment being loaded outside of the Mechanical Turk environment?
+     */
+    outsideTurk: boolean;
+    /**
+     * The HIT ID.
+     */
+    hitId: string;
+    /**
+     * The Assignment ID.
+     */
+    assignmentId: string;
+    /**
+     * The worker ID.
+     */
+    workerId: string;
+    /**
+     * URL for submission of the HIT.
+     */
+    turkSubmitTo: string;
+}
+/**
+ * Gets information about the Mechanical Turk Environment, HIT, Assignment, and Worker
+ * by parsing the URL variables that Mechanical Turk generates.
+ * @returns An object containing information about the Mechanical Turk Environment, HIT, Assignment, and Worker.
+ */
+export declare function turkInfo(): turkInformation;
+/**
+ * Send data to Mechnical Turk for storage.
+ * @param data An object containing `key:value` pairs to send to Mechanical Turk. Values
+ * cannot contain nested objects, arrays, or functions.
+ * @returns Nothing
+ */
+export declare function submitToTurk(data: any): void;
+export {};

package/dist/modules/utils.d.ts

@@ -1,7 +1,13 @@
-/**
- * Finds all of the unique items in an array.
- * @param arr The array to extract unique values from
- * @returns An array with one copy of each unique item in `arr`
- */
-export declare function unique(arr: Array<any>): any[];
-export declare function deepCopy(obj: any): any;
+/**
+ * Finds all of the unique items in an array.
+ * @param arr The array to extract unique values from
+ * @returns An array with one copy of each unique item in `arr`
+ */
+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.2",
+  "version": "7.3.4",
   "description": "Behavioral experiments in a browser",
   "type": "module",
   "main": "dist/index.cjs",
@@ -47,7 +47,7 @@
   },
   "devDependencies": {
     "@fontsource/open-sans": "4.5.3",
-    "@jspsych/config": "^1.3.1",
+    "@jspsych/config": "^2.0.0",
     "@types/dom-mediacapture-record": "^1.0.11",
     "base64-inline-loader": "^2.0.1",
     "css-loader": "^6.6.0",
@@ -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();
     }
 

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;
 }