jspsych 7.3.3 → 8.0.0

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

@@ -1,5 +1,6 @@
 import { ParameterType } from "../../modules/plugins";
 import { unique } from "../utils";
+import { AudioPlayer } from "./AudioPlayer";
 
 const preloadParameterTypes = <const>[
   ParameterType.AUDIO,
@@ -9,7 +10,15 @@ const preloadParameterTypes = <const>[
 type PreloadType = typeof preloadParameterTypes[number];
 
 export class MediaAPI {
-  constructor(private useWebaudio: boolean, private webaudioContext?: AudioContext) {}
+  constructor(public useWebaudio: boolean) {
+    if (
+      this.useWebaudio &&
+      typeof window !== "undefined" &&
+      typeof window.AudioContext !== "undefined"
+    ) {
+      this.context = new AudioContext();
+    }
+  }
 
   // video //
   private video_buffers = {};
@@ -21,45 +30,27 @@ export class MediaAPI {
   }
 
   // audio //
-  private context = null;
+  private context: AudioContext = null;
   private audio_buffers = [];
 
-  initAudio() {
-    this.context = this.useWebaudio ? this.webaudioContext : null;
-  }
-
-  audioContext() {
-    if (this.context !== null) {
-      if (this.context.state !== "running") {
-        this.context.resume();
-      }
+  audioContext(): AudioContext {
+    if (this.context && this.context.state !== "running") {
+      this.context.resume();
     }
     return this.context;
   }
 
-  getAudioBuffer(audioID) {
-    return new Promise((resolve, reject) => {
-      // check whether audio file already preloaded
-      if (
-        typeof this.audio_buffers[audioID] == "undefined" ||
-        this.audio_buffers[audioID] == "tmp"
-      ) {
-        // if audio is not already loaded, try to load it
-        this.preloadAudio(
-          [audioID],
-          () => {
-            resolve(this.audio_buffers[audioID]);
-          },
-          () => {},
-          (e) => {
-            reject(e.error);
-          }
-        );
-      } else {
-        // audio is already loaded
-        resolve(this.audio_buffers[audioID]);
-      }
-    });
+  async getAudioPlayer(audioID: string): Promise<AudioPlayer> {
+    if (this.audio_buffers[audioID] instanceof AudioPlayer) {
+      return this.audio_buffers[audioID];
+    } else {
+      this.audio_buffers[audioID] = new AudioPlayer(audioID, {
+        useWebAudio: this.useWebaudio,
+        audioContext: this.context,
+      });
+      await this.audio_buffers[audioID].load();
+      return this.audio_buffers[audioID];
+    }
   }
 
   // preloading stimuli //
@@ -70,8 +61,8 @@ export class MediaAPI {
   preloadAudio(
     files,
     callback_complete = () => {},
-    callback_load = (filepath) => {},
-    callback_error = (error_msg) => {}
+    callback_load = (filepath: string) => {},
+    callback_error = (error) => {}
   ) {
     files = unique(files.flat());
 
@@ -82,80 +73,31 @@ export class MediaAPI {
       return;
     }
 
-    const load_audio_file_webaudio = (source, count = 1) => {
-      const request = new XMLHttpRequest();
-      request.open("GET", source, true);
-      request.responseType = "arraybuffer";
-      request.onload = () => {
-        this.context.decodeAudioData(
-          request.response,
-          (buffer) => {
-            this.audio_buffers[source] = buffer;
-            n_loaded++;
-            callback_load(source);
-            if (n_loaded == files.length) {
-              callback_complete();
-            }
-          },
-          (e) => {
-            callback_error({ source: source, error: e });
-          }
-        );
-      };
-      request.onerror = (e) => {
-        let err: ProgressEvent | string = e;
-        if (request.status == 404) {
-          err = "404";
-        }
-        callback_error({ source: source, error: err });
-      };
-      request.onloadend = (e) => {
-        if (request.status == 404) {
-          callback_error({ source: source, error: "404" });
-        }
-      };
-      request.send();
-      this.preload_requests.push(request);
-    };
-
-    const load_audio_file_html5audio = (source, count = 1) => {
-      const audio = new Audio();
-      const handleCanPlayThrough = () => {
-        this.audio_buffers[source] = audio;
-        n_loaded++;
-        callback_load(source);
-        if (n_loaded == files.length) {
-          callback_complete();
-        }
-        audio.removeEventListener("canplaythrough", handleCanPlayThrough);
-      };
-      audio.addEventListener("canplaythrough", handleCanPlayThrough);
-      audio.addEventListener("error", function handleError(e) {
-        callback_error({ source: audio.src, error: e });
-        audio.removeEventListener("error", handleError);
-      });
-      audio.addEventListener("abort", function handleAbort(e) {
-        callback_error({ source: audio.src, error: e });
-        audio.removeEventListener("abort", handleAbort);
-      });
-      audio.src = source;
-      this.preload_requests.push(audio);
-    };
-
     for (const file of files) {
-      if (typeof this.audio_buffers[file] !== "undefined") {
+      // check if file was already loaded
+      if (this.audio_buffers[file] instanceof AudioPlayer) {
         n_loaded++;
         callback_load(file);
         if (n_loaded == files.length) {
           callback_complete();
         }
       } else {
-        this.audio_buffers[file] = "tmp";
-        if (this.audioContext() !== null) {
-          load_audio_file_webaudio(file);
-        } else {
-          load_audio_file_html5audio(file);
-        }
+        this.audio_buffers[file] = new AudioPlayer(file, {
+          useWebAudio: this.useWebaudio,
+          audioContext: this.context,
+        });
+        this.audio_buffers[file]
+          .load()
+          .then(() => {
+            n_loaded++;
+            callback_load(file);
+            if (n_loaded == files.length) {
+              callback_complete();
+            }
+          })
+          .catch((e) => {
+            callback_error(e);
+          });
       }
     }
   }
@@ -221,7 +163,7 @@ export class MediaAPI {
       const request = new XMLHttpRequest();
       request.open("GET", video, true);
       request.responseType = "blob";
-      request.onload =  () => {
+      request.onload = () => {
         if (request.status === 200 || request.status === 0) {
           const videoBlob = request.response;
           video_buffers[video] = URL.createObjectURL(videoBlob); // IE10+
@@ -232,14 +174,14 @@ export class MediaAPI {
           }
         }
       };
-      request.onerror =  (e) => {
+      request.onerror = (e) => {
         let err: ProgressEvent | string = e;
         if (request.status == 404) {
           err = "404";
         }
         callback_error({ source: video, error: err });
       };
-      request.onloadend =  (e) => {
+      request.onloadend = (e) => {
         if (request.status == 404) {
           callback_error({ source: video, error: "404" });
         }

package/src/modules/plugin-api/__mocks__/AudioPlayer.ts

@@ -0,0 +1,38 @@
+import { AudioPlayerOptions } from "../AudioPlayer";
+
+const actual = jest.requireActual("../AudioPlayer");
+
+export const mockStop = jest.fn();
+
+export const AudioPlayer = jest
+  .fn()
+  .mockImplementation((src: string, options: AudioPlayerOptions = { useWebAudio: false }) => {
+    let eventHandlers = {};
+
+    const mockInstance = Object.create(actual.AudioPlayer.prototype);
+
+    return Object.assign(mockInstance, {
+      load: jest.fn(),
+      play: jest.fn(() => {
+        setTimeout(() => {
+          if (eventHandlers["ended"]) {
+            for (const handler of eventHandlers["ended"]) {
+              handler();
+            }
+          }
+        }, 1000);
+      }),
+      stop: mockStop,
+      addEventListener: jest.fn((event, handler) => {
+        if (!eventHandlers[event]) {
+          eventHandlers[event] = [];
+        }
+        eventHandlers[event].push(handler);
+      }),
+      removeEventListener: jest.fn((event, handler) => {
+        if (eventHandlers[event] === handler) {
+          eventHandlers[event] = eventHandlers[event].filter((h) => h !== handler);
+        }
+      }),
+    });
+  });

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

@@ -1,7 +1,6 @@
 import autoBind from "auto-bind";
 
 import { JsPsych } from "../../JsPsych";
-import { HardwareAPI } from "./HardwareAPI";
 import { KeyboardListenerAPI } from "./KeyboardListenerAPI";
 import { MediaAPI } from "./MediaAPI";
 import { SimulationAPI } from "./SimulationAPI";
@@ -9,23 +8,21 @@ 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 keyboardListenerAPI = 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)
+  const timeoutAPI = new TimeoutAPI();
+  const mediaAPI = new MediaAPI(settings.use_webaudio);
+  const simulationAPI = new SimulationAPI(
+    jsPsych.getDisplayContainerElement,
+    timeoutAPI.setTimeout.bind(timeoutAPI)
   );
   return Object.assign(
     {},
-    ...[keyboardListenerAPI, timeoutAPI, mediaAPI, hardwareAPI, simulationAPI]
-  ) as KeyboardListenerAPI & TimeoutAPI & MediaAPI & HardwareAPI & SimulationAPI;
+    ...[keyboardListenerAPI, timeoutAPI, mediaAPI, simulationAPI].map((object) => autoBind(object))
+  ) as KeyboardListenerAPI & TimeoutAPI & MediaAPI & SimulationAPI;
 }
 
 export type PluginAPI = ReturnType<typeof createJointPluginAPIObject>;

package/src/modules/plugins.ts

@@ -1,16 +1,6 @@
-/**
-Flatten the type output to improve type hints shown in editors.
-Borrowed from type-fest
-*/
-type Simplify<T> = { [KeyType in keyof T]: T[KeyType] };
+import { SetRequired } from "type-fest";
 
-/**
-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>>
->;
+import { SimulationMode, SimulationOptions, TrialDescription, TrialResult } from "../timeline";
 
 /**
  * Parameter types for plugins
@@ -51,17 +41,19 @@ type ParameterTypeMap = {
   [ParameterType.TIMELINE]: any;
 };
 
-export interface ParameterInfo {
-  type: ParameterType;
+type PreloadParameterType = ParameterType.AUDIO | ParameterType.VIDEO | ParameterType.IMAGE;
+
+export type ParameterInfo = (
+  | { type: Exclude<ParameterType, ParameterType.COMPLEX | PreloadParameterType> }
+  | { type: ParameterType.COMPLEX; nested?: ParameterInfos }
+  | { type: PreloadParameterType; preload?: boolean }
+) & {
   array?: boolean;
   pretty_name?: string;
   default?: any;
-  preload?: boolean;
-}
+};
 
-export interface ParameterInfos {
-  [key: string]: ParameterInfo;
-}
+export type ParameterInfos = Record<string, ParameterInfo>;
 
 type InferredParameter<I extends ParameterInfo> = I["array"] extends true
   ? Array<ParameterTypeMap[I["type"]]>
@@ -123,7 +115,7 @@ export const universalPluginParameters = <const>{
   post_trial_gap: {
     type: ParameterType.INT,
     pretty_name: "Post trial gap",
-    default: null,
+    default: 0,
   },
   /**
    * A list of CSS classes to add to the jsPsych display element for the duration of this trial
@@ -131,14 +123,14 @@ export const universalPluginParameters = <const>{
   css_classes: {
     type: ParameterType.STRING,
     pretty_name: "Custom CSS classes",
-    default: null,
+    default: "",
   },
   /**
    * Options to control simulation mode for the trial.
    */
   simulation_options: {
     type: ParameterType.COMPLEX,
-    default: null,
+    default: {},
   },
 };
 
@@ -146,9 +138,9 @@ export type UniversalPluginParameters = InferredParameters<typeof universalPlugi
 
 export interface PluginInfo {
   name: string;
-  parameters: {
-    [key: string]: ParameterInfo;
-  };
+  version?: string;
+  parameters: ParameterInfos;
+  data?: ParameterInfos;
 }
 
 export interface JsPsychPlugin<I extends PluginInfo> {
@@ -156,10 +148,17 @@ export interface JsPsychPlugin<I extends PluginInfo> {
     display_element: HTMLElement,
     trial: TrialType<I>,
     on_load?: () => void
-  ): void | Promise<any>;
+  ): void | Promise<TrialResult | void>;
+
+  simulate?(
+    trial: TrialType<I>,
+    simulation_mode: SimulationMode,
+    simulation_options: SimulationOptions,
+    on_load?: () => void
+  ): void | Promise<TrialResult | void>;
 }
 
 export type TrialType<I extends PluginInfo> = InferredParameters<I["parameters"]> &
-  UniversalPluginParameters;
+  TrialDescription;
 
 export type PluginParameters<I extends PluginInfo> = InferredParameters<I["parameters"]>;

package/src/modules/randomization.ts

@@ -264,7 +264,7 @@ export function randomID(length = 32) {
  */
 export function randomInt(lower: number, upper: number) {
   if (upper < lower) {
-    throw new Error("Upper boundary must be less than or equal to lower boundary");
+    throw new Error("Upper boundary must be greater than or equal to lower boundary");
   }
   return lower + Math.floor(Math.random() * (upper - lower + 1));
 }