jspsych 7.0.0 → 7.1.0

package/dist/migration.d.ts

@@ -0,0 +1,3 @@
+export declare class MigrationError extends Error {
+    constructor(message?: string);
+}

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

@@ -21,4 +21,7 @@ export declare class MediaAPI {
         video: string[];
     };
     cancelPreloads(): void;
+    private microphone_recorder;
+    initializeMicrophoneRecorder(stream: MediaStream): void;
+    getMicrophoneRecorder(): MediaRecorder;
 }

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

@@ -0,0 +1,41 @@
+export declare class SimulationAPI {
+    dispatchEvent(event: Event): void;
+    /**
+     * Dispatches a `keydown` event for the specified key
+     * @param key Character code (`.key` property) for the key to press.
+     */
+    keyDown(key: string): void;
+    /**
+     * Dispatches a `keyup` event for the specified key
+     * @param key Character code (`.key` property) for the key to press.
+     */
+    keyUp(key: string): void;
+    /**
+     * Dispatches a `keydown` and `keyup` event in sequence to simulate pressing a key.
+     * @param key Character code (`.key` property) for the key to press.
+     * @param delay Length of time to wait (ms) before executing action
+     */
+    pressKey(key: string, delay?: number): void;
+    /**
+     * Dispatches `mousedown`, `mouseup`, and `click` events on the target element
+     * @param target The element to click
+     * @param delay Length of time to wait (ms) before executing action
+     */
+    clickTarget(target: Element, delay?: number): void;
+    /**
+     * Sets the value of a target text input
+     * @param target A text input element to fill in
+     * @param text Text to input
+     * @param delay Length of time to wait (ms) before executing action
+     */
+    fillTextInput(target: HTMLInputElement, text: string, delay?: number): void;
+    /**
+     * Picks a valid key from `choices`, taking into account jsPsych-specific
+     * identifiers like "NO_KEYS" and "ALL_KEYS".
+     * @param choices Which keys are valid.
+     * @returns A key selected at random from the valid keys.
+     */
+    getValidKey(choices: "NO_KEYS" | "ALL_KEYS" | Array<string> | Array<Array<string>>): any;
+    mergeSimulationData(default_data: any, simulation_options: any): any;
+    ensureSimulationDataConsistency(trial: any, data: any): void;
+}

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

@@ -2,6 +2,7 @@ import { JsPsych } from "../../JsPsych";
 import { HardwareAPI } from "./HardwareAPI";
 import { KeyboardListenerAPI } from "./KeyboardListenerAPI";
 import { MediaAPI } from "./MediaAPI";
+import { SimulationAPI } from "./SimulationAPI";
 import { TimeoutAPI } from "./TimeoutAPI";
-export declare function createJointPluginAPIObject(jsPsych: JsPsych): KeyboardListenerAPI & TimeoutAPI & MediaAPI & HardwareAPI;
+export declare function createJointPluginAPIObject(jsPsych: JsPsych): KeyboardListenerAPI & TimeoutAPI & MediaAPI & HardwareAPI & SimulationAPI;
 export declare type PluginAPI = ReturnType<typeof createJointPluginAPIObject>;

package/dist/modules/randomization.d.ts

@@ -3,6 +3,33 @@ 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 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jspsych",
-  "version": "7.0.0",
+  "version": "7.1.0",
   "description": "Behavioral experiments in a browser",
   "type": "module",
   "main": "dist/index.cjs",
@@ -39,10 +39,12 @@
   },
   "homepage": "https://www.jspsych.org",
   "dependencies": {
-    "auto-bind": "^4.0.0"
+    "auto-bind": "^4.0.0",
+    "random-words": "^1.1.1"
   },
   "devDependencies": {
-    "@jspsych/config": "^1.0.0",
-    "@jspsych/test-utils": "^1.0.0"
+    "@jspsych/config": "^1.1.0",
+    "@jspsych/test-utils": "^1.1.0",
+    "@types/dom-mediacapture-record": "^1.0.11"
   }
 }

package/src/JsPsych.ts

@@ -1,6 +1,7 @@
 import autoBind from "auto-bind";
 
 import { version } from "../package.json";
+import { MigrationError } from "./migration";
 import { JsPsychData } from "./modules/data";
 import { PluginAPI, createJointPluginAPIObject } from "./modules/plugin-api";
 import { ParameterType, universalPluginParameters } from "./modules/plugins";
@@ -71,6 +72,16 @@ export class JsPsych {
   private finished: Promise<void>;
   private resolveFinishedPromise: () => void;
 
+  /**
+   * is the experiment running in `simulate()` mode
+   */
+  private simulation_mode: "data-only" | "visual" = null;
+
+  /**
+   * simulation options passed in via `simulate()`
+   */
+  private simulation_options;
+
   // storing a single webaudio context to prevent problems with multiple inits
   // of jsPsych
   webaudio_context: AudioContext = null;
@@ -176,6 +187,16 @@ export class JsPsych {
     await this.finished;
   }
 
+  async simulate(
+    timeline: any[],
+    simulation_mode: "data-only" | "visual",
+    simulation_options = {}
+  ) {
+    this.simulation_mode = simulation_mode;
+    this.simulation_options = simulation_options;
+    await this.run(timeline);
+  }
+
   getProgress() {
     return {
       total_trials: typeof this.timeline === "undefined" ? undefined : this.timeline.length(),
@@ -299,12 +320,12 @@ export class JsPsych {
     }
   }
 
-  endExperiment(end_message: string) {
+  endExperiment(end_message = "", data = {}) {
     this.timeline.end_message = end_message;
     this.timeline.end();
     this.pluginAPI.cancelAllKeyboardResponses();
     this.pluginAPI.clearAllTimeouts();
-    this.finishTrial();
+    this.finishTrial(data);
   }
 
   endCurrentTimeline() {
@@ -517,6 +538,12 @@ export class JsPsych {
     // process all timeline variables for this trial
     this.evaluateTimelineVariables(trial);
 
+    if (typeof trial.type === "string") {
+      throw new MigrationError(
+        "A string was provided as the trial's `type` parameter. Since jsPsych v7, the `type` parameter needs to be a plugin object."
+      );
+    }
+
     // instantiate the plugin for this trial
     trial.type = {
       // this is a hack to internally keep the old plugin object structure and prevent touching more
@@ -579,11 +606,60 @@ export class JsPsych {
       }
     };
 
-    const trial_complete = trial.type.trial(this.DOM_target, trial, load_callback);
+    let trial_complete;
+    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;
+        }
+        if (trial.simulation_options) {
+          if (typeof trial.simulation_options == "string") {
+            if (this.simulation_options[trial.simulation_options]) {
+              trial_sim_opts = this.simulation_options[trial.simulation_options];
+            } else if (this.simulation_options.default) {
+              console.log(
+                `No matching simulation options found for "${trial.simulation_options}". Using "default" options.`
+              );
+              trial_sim_opts = this.simulation_options.default;
+            } else {
+              console.log(
+                `No matching simulation options found for "${trial.simulation_options}" and no "default" options provided. Using the default values provided by the plugin.`
+              );
+              trial_sim_opts = {};
+            }
+          } else {
+            trial_sim_opts = trial.simulation_options;
+          }
+        }
+        trial_sim_opts = this.utils.deepCopy(trial_sim_opts);
+        trial_sim_opts = this.replaceFunctionsWithValues(trial_sim_opts, null);
+
+        if (trial_sim_opts?.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,
+            load_callback
+          );
+        }
+      } else {
+        // trial doesn't have a simulate method, so just run as usual
+        trial_complete = trial.type.trial(this.DOM_target, trial, load_callback);
+      }
+    }
+
     // see if trial_complete is a Promise by looking for .then() function
     const is_promise = trial_complete && typeof trial_complete.then == "function";
 
-    if (!is_promise) {
+    // in simulation mode we let the simulate function call the load_callback always.
+    if (!is_promise && !this.simulation_mode) {
       load_callback();
     }
 
@@ -727,6 +803,11 @@ export class JsPsych {
   }
 
   private async checkExclusions(exclusions) {
+    if (exclusions.min_width || exclusions.min_height || exclusions.audio) {
+      console.warn(
+        "The exclusions option in `initJsPsych()` is deprecated and will be removed in a future version. We recommend using the browser-check plugin instead. See https://www.jspsych.org/latest/plugins/browser-check/."
+      );
+    }
     // MINIMUM SIZE
     if (exclusions.min_width || exclusions.min_height) {
       const mw = exclusions.min_width || 0;

package/src/index.ts

@@ -1,4 +1,5 @@
 import { JsPsych } from "./JsPsych";
+import { MigrationError } from "./migration";
 
 // temporary patch for Safari
 if (
@@ -20,7 +21,42 @@ if (
  * @returns A new JsPsych instance
  */
 export function initJsPsych(options?) {
-  return new JsPsych(options);
+  const jsPsych = new JsPsych(options);
+
+  // Handle invocations of non-existent v6 methods with migration errors
+  const migrationMessages = {
+    init: "`jsPsych.init()` was replaced by `initJsPsych()` in jsPsych v7.",
+
+    ALL_KEYS: 'jsPsych.ALL_KEYS was replaced by the "ALL_KEYS" string in jsPsych v7.',
+    NO_KEYS: 'jsPsych.NO_KEYS was replaced by the "NO_KEYS" string in jsPsych v7.',
+
+    // Getter functions that were renamed
+    currentTimelineNodeID:
+      "`currentTimelineNodeID()` was renamed to `getCurrentTimelineNodeID()` in jsPsych v7.",
+    progress: "`progress()` was renamed to `getProgress()` in jsPsych v7.",
+    startTime: "`startTime()` was renamed to `getStartTime()` in jsPsych v7.",
+    totalTime: "`totalTime()` was renamed to `getTotalTime()` in jsPsych v7.",
+    currentTrial: "`currentTrial()` was renamed to `getCurrentTrial()` in jsPsych v7.",
+    initSettings: "`initSettings()` was renamed to `getInitSettings()` in jsPsych v7.",
+    allTimelineVariables:
+      "`allTimelineVariables()` was renamed to `getAllTimelineVariables()` in jsPsych v7.",
+  };
+
+  Object.defineProperties(
+    jsPsych,
+    Object.fromEntries(
+      Object.entries(migrationMessages).map(([key, message]) => [
+        key,
+        {
+          get() {
+            throw new MigrationError(message);
+          },
+        },
+      ])
+    )
+  );
+
+  return jsPsych;
 }
 
 export { JsPsych } from "./JsPsych";

package/src/migration.ts

@@ -0,0 +1,37 @@
+export class MigrationError extends Error {
+  constructor(message = "The global `jsPsych` variable is no longer available in jsPsych v7.") {
+    super(
+      `${message} Please follow the migration guide at https://www.jspsych.org/7.0/support/migration-v7/ to update your experiment.`
+    );
+    this.name = "MigrationError";
+  }
+}
+
+// Define a global jsPsych object to handle invocations on it with migration errors
+(window as any).jsPsych = {
+  get init() {
+    throw new MigrationError("`jsPsych.init()` was replaced by `initJsPsych()` in jsPsych v7.");
+  },
+
+  get data() {
+    throw new MigrationError();
+  },
+  get randomization() {
+    throw new MigrationError();
+  },
+  get turk() {
+    throw new MigrationError();
+  },
+  get pluginAPI() {
+    throw new MigrationError();
+  },
+
+  get ALL_KEYS() {
+    throw new MigrationError(
+      'jsPsych.ALL_KEYS was replaced by the "ALL_KEYS" string in jsPsych v7.'
+    );
+  },
+  get NO_KEYS() {
+    throw new MigrationError('jsPsych.NO_KEYS was replaced by the "NO_KEYS" string in jsPsych v7.');
+  },
+};

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

@@ -323,4 +323,15 @@ export class MediaAPI {
     }
     this.preload_requests = [];
   }
+
+  private microphone_recorder: MediaRecorder = null;
+
+  initializeMicrophoneRecorder(stream: MediaStream) {
+    const recorder = new MediaRecorder(stream);
+    this.microphone_recorder = recorder;
+  }
+
+  getMicrophoneRecorder(): MediaRecorder {
+    return this.microphone_recorder;
+  }
 }

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

@@ -0,0 +1,181 @@
+export class SimulationAPI {
+  dispatchEvent(event: Event) {
+    document.body.dispatchEvent(event);
+  }
+
+  /**
+   * Dispatches a `keydown` event for the specified key
+   * @param key Character code (`.key` property) for the key to press.
+   */
+  keyDown(key: string) {
+    this.dispatchEvent(new KeyboardEvent("keydown", { key }));
+  }
+
+  /**
+   * Dispatches a `keyup` event for the specified key
+   * @param key Character code (`.key` property) for the key to press.
+   */
+  keyUp(key: string) {
+    this.dispatchEvent(new KeyboardEvent("keyup", { key }));
+  }
+
+  /**
+   * Dispatches a `keydown` and `keyup` event in sequence to simulate pressing a key.
+   * @param key Character code (`.key` property) for the key to press.
+   * @param delay Length of time to wait (ms) before executing action
+   */
+  pressKey(key: string, delay = 0) {
+    if (delay > 0) {
+      setTimeout(() => {
+        this.keyDown(key);
+        this.keyUp(key);
+      }, delay);
+    } else {
+      this.keyDown(key);
+      this.keyUp(key);
+    }
+  }
+
+  /**
+   * Dispatches `mousedown`, `mouseup`, and `click` events on the target element
+   * @param target The element to click
+   * @param delay Length of time to wait (ms) before executing action
+   */
+  clickTarget(target: Element, delay = 0) {
+    if (delay > 0) {
+      setTimeout(() => {
+        target.dispatchEvent(new MouseEvent("mousedown", { bubbles: true }));
+        target.dispatchEvent(new MouseEvent("mouseup", { bubbles: true }));
+        target.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+      }, delay);
+    } else {
+      target.dispatchEvent(new MouseEvent("mousedown", { bubbles: true }));
+      target.dispatchEvent(new MouseEvent("mouseup", { bubbles: true }));
+      target.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    }
+  }
+
+  /**
+   * Sets the value of a target text input
+   * @param target A text input element to fill in
+   * @param text Text to input
+   * @param delay Length of time to wait (ms) before executing action
+   */
+  fillTextInput(target: HTMLInputElement, text: string, delay = 0) {
+    if (delay > 0) {
+      setTimeout(() => {
+        target.value = text;
+      }, delay);
+    } else {
+      target.value = text;
+    }
+  }
+
+  /**
+   * Picks a valid key from `choices`, taking into account jsPsych-specific
+   * identifiers like "NO_KEYS" and "ALL_KEYS".
+   * @param choices Which keys are valid.
+   * @returns A key selected at random from the valid keys.
+   */
+  getValidKey(choices: "NO_KEYS" | "ALL_KEYS" | Array<string> | Array<Array<string>>) {
+    const possible_keys = [
+      "a",
+      "b",
+      "c",
+      "d",
+      "e",
+      "f",
+      "g",
+      "h",
+      "i",
+      "j",
+      "k",
+      "l",
+      "m",
+      "n",
+      "o",
+      "p",
+      "q",
+      "r",
+      "s",
+      "t",
+      "u",
+      "v",
+      "w",
+      "x",
+      "y",
+      "z",
+      "0",
+      "1",
+      "2",
+      "3",
+      "4",
+      "5",
+      "6",
+      "7",
+      "8",
+      "9",
+      " ",
+    ];
+
+    let key;
+    if (choices == "NO_KEYS") {
+      key = null;
+    } else if (choices == "ALL_KEYS") {
+      key = possible_keys[Math.floor(Math.random() * possible_keys.length)];
+    } else {
+      const flat_choices = choices.flat();
+      key = flat_choices[Math.floor(Math.random() * flat_choices.length)];
+    }
+
+    return key;
+  }
+
+  mergeSimulationData(default_data, simulation_options) {
+    // override any data with data from simulation object
+    return {
+      ...default_data,
+      ...simulation_options?.data,
+    };
+  }
+
+  ensureSimulationDataConsistency(trial, data) {
+    // All RTs must be rounded
+    if (data.rt) {
+      data.rt = Math.round(data.rt);
+    }
+
+    // If a trial_duration and rt exist, make sure that the RT is not longer than the trial.
+    if (trial.trial_duration && data.rt && data.rt > trial.trial_duration) {
+      data.rt = null;
+      if (data.response) {
+        data.response = null;
+      }
+      if (data.correct) {
+        data.correct = false;
+      }
+    }
+
+    // If trial.choices is NO_KEYS make sure that response and RT are null
+    if (trial.choices && trial.choices == "NO_KEYS") {
+      if (data.rt) {
+        data.rt = null;
+      }
+      if (data.response) {
+        data.response = null;
+      }
+    }
+
+    // If response is not allowed before stimulus display complete, ensure RT
+    // is longer than display time.
+    if (trial.allow_response_before_complete) {
+      if (trial.sequence_reps && trial.frame_time) {
+        const min_time = trial.sequence_reps * trial.frame_time * trial.stimuli.length;
+        if (data.rt < min_time) {
+          data.rt = null;
+          data.response = null;
+        }
+      }
+    }
+  }
+}

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

@@ -4,6 +4,7 @@ import { JsPsych } from "../../JsPsych";
 import { HardwareAPI } from "./HardwareAPI";
 import { KeyboardListenerAPI } from "./KeyboardListenerAPI";
 import { MediaAPI } from "./MediaAPI";
+import { SimulationAPI } from "./SimulationAPI";
 import { TimeoutAPI } from "./TimeoutAPI";
 
 export function createJointPluginAPIObject(jsPsych: JsPsych) {
@@ -19,8 +20,9 @@ export function createJointPluginAPIObject(jsPsych: JsPsych) {
       new TimeoutAPI(),
       new MediaAPI(settings.use_webaudio, jsPsych.webaudio_context),
       new HardwareAPI(),
+      new SimulationAPI(),
     ].map((object) => autoBind(object))
-  ) as KeyboardListenerAPI & TimeoutAPI & MediaAPI & HardwareAPI;
+  ) as KeyboardListenerAPI & TimeoutAPI & MediaAPI & HardwareAPI & SimulationAPI;
 }
 
 export type PluginAPI = ReturnType<typeof createJointPluginAPIObject>;

package/src/modules/randomization.ts

@@ -1,3 +1,5 @@
+import rw from "random-words";
+
 export function repeat(array, repetitions, unpack = false) {
   const arr_isArray = Array.isArray(array);
   const rep_isArray = Array.isArray(repetitions);
@@ -173,7 +175,7 @@ export function sampleWithoutReplacement(arr, size) {
   return shuffle(arr).slice(0, size);
 }
 
-export function sampleWithReplacement(arr, size, weights) {
+export function sampleWithReplacement(arr, size, weights?) {
   if (!Array.isArray(arr)) {
     console.error("First argument to sampleWithReplacement() must be an array");
   }
@@ -240,6 +242,75 @@ export function randomID(length = 32) {
   return result;
 }
 
+/**
+ * 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 function randomInt(lower: number, upper: number) {
+  if (upper < lower) {
+    throw new Error("Upper boundary must be less than or equal to lower boundary");
+  }
+  return lower + Math.floor(Math.random() * (upper - lower + 1));
+}
+
+/**
+ * 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 function sampleBernoulli(p: number) {
+  return Math.random() <= p ? 1 : 0;
+}
+
+export function sampleNormal(mean: number, standard_deviation: number) {
+  return randn_bm() * standard_deviation + mean;
+}
+
+export function sampleExponential(rate: number) {
+  return -Math.log(Math.random()) / rate;
+}
+
+export function sampleExGaussian(
+  mean: number,
+  standard_deviation: number,
+  rate: number,
+  positive = false
+) {
+  let s = sampleNormal(mean, standard_deviation) + sampleExponential(rate);
+  if (positive) {
+    while (s <= 0) {
+      s = sampleNormal(mean, standard_deviation) + sampleExponential(rate);
+    }
+  }
+  return s;
+}
+
+/**
+ * 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 function randomWords(opts) {
+  return rw(opts);
+}
+
+// Box-Muller transformation for a random sample from normal distribution with mean = 0, std = 1
+// https://stackoverflow.com/a/36481059/3726673
+function randn_bm() {
+  var u = 0,
+    v = 0;
+  while (u === 0) u = Math.random(); //Converting [0,1) to (0,1)
+  while (v === 0) v = Math.random();
+  return Math.sqrt(-2.0 * Math.log(u)) * Math.cos(2.0 * Math.PI * v);
+}
+
 function unpackArray(array) {
   const out = {};