jspsych 7.2.3 → 7.3.0

package/dist/modules/extensions.d.ts

@@ -18,5 +18,5 @@ export interface JsPsychExtension {
      * Called at the end of the trial.
      * @returns Data to append to the trial's data object.
      */
-    on_finish(params?: Record<string, any>): Record<string, any>;
+    on_finish(params?: Record<string, any>): Record<string, any> | Promise<Record<string, any>>;
 }

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

@@ -3,7 +3,7 @@ export declare class MediaAPI {
     private webaudioContext?;
     constructor(useWebaudio: boolean, webaudioContext?: AudioContext);
     private video_buffers;
-    getVideoBuffer(videoID: any): any;
+    getVideoBuffer(videoID: string): any;
     private context;
     private audio_buffers;
     initAudio(): void;
@@ -24,4 +24,9 @@ export declare class MediaAPI {
     private microphone_recorder;
     initializeMicrophoneRecorder(stream: MediaStream): void;
     getMicrophoneRecorder(): MediaRecorder;
+    private camera_stream;
+    private camera_recorder;
+    initializeCameraRecorder(stream: MediaStream, opts?: MediaRecorderOptions): void;
+    getCameraStream(): MediaStream;
+    getCameraRecorder(): MediaRecorder;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jspsych",
-  "version": "7.2.3",
+  "version": "7.3.0",
   "description": "Behavioral experiments in a browser",
   "type": "module",
   "main": "dist/index.cjs",

package/src/JsPsych.ts

@@ -272,53 +272,71 @@ export class JsPsych {
         }
       }
     }
+
     // handle extension callbacks
-    if (Array.isArray(current_trial.extensions)) {
-      for (const extension of current_trial.extensions) {
-        const ext_data_values = this.extensions[extension.type.info.name].on_finish(
-          extension.params
-        );
-        Object.assign(trial_data_values, ext_data_values);
-      }
-    }
 
-    // about to execute lots of callbacks, so switch context.
-    this.internal.call_immediate = true;
+    const extensionCallbackResults = ((current_trial.extensions ?? []) as any[]).map((extension) =>
+      this.extensions[extension.type.info.name].on_finish(extension.params)
+    );
 
-    // handle callback at plugin level
-    if (typeof current_trial.on_finish === "function") {
-      current_trial.on_finish(trial_data_values);
-    }
+    const onExtensionCallbacksFinished = () => {
+      // about to execute lots of callbacks, so switch context.
+      this.internal.call_immediate = true;
 
-    // handle callback at whole-experiment level
-    this.opts.on_trial_finish(trial_data_values);
+      // handle callback at plugin level
+      if (typeof current_trial.on_finish === "function") {
+        current_trial.on_finish(trial_data_values);
+      }
 
-    // after the above callbacks are complete, then the data should be finalized
-    // for this trial. call the on_data_update handler, passing in the same
-    // data object that just went through the trial's finish handlers.
-    this.opts.on_data_update(trial_data_values);
+      // handle callback at whole-experiment level
+      this.opts.on_trial_finish(trial_data_values);
 
-    // done with callbacks
-    this.internal.call_immediate = false;
+      // after the above callbacks are complete, then the data should be finalized
+      // for this trial. call the on_data_update handler, passing in the same
+      // data object that just went through the trial's finish handlers.
+      this.opts.on_data_update(trial_data_values);
 
-    // wait for iti
-    if (this.simulation_mode === "data-only") {
-      this.nextTrial();
-    } else if (
-      typeof current_trial.post_trial_gap === null ||
-      typeof current_trial.post_trial_gap === "undefined"
-    ) {
-      if (this.opts.default_iti > 0) {
-        setTimeout(this.nextTrial, this.opts.default_iti);
-      } else {
+      // done with callbacks
+      this.internal.call_immediate = false;
+
+      // wait for iti
+      if (this.simulation_mode === "data-only") {
         this.nextTrial();
+      } else if (
+        typeof current_trial.post_trial_gap === null ||
+        typeof current_trial.post_trial_gap === "undefined"
+      ) {
+        if (this.opts.default_iti > 0) {
+          setTimeout(this.nextTrial, this.opts.default_iti);
+        } else {
+          this.nextTrial();
+        }
+      } else {
+        if (current_trial.post_trial_gap > 0) {
+          setTimeout(this.nextTrial, current_trial.post_trial_gap);
+        } else {
+          this.nextTrial();
+        }
       }
+    };
+
+    // Strictly using Promise.resolve to turn all values into promises would be cleaner here, but it
+    // would require user test code to make the event loop tick after every simulated key press even
+    // if there are no async `on_finish` methods. Hence, in order to avoid a breaking change, we
+    // only rely on the event loop if at least one `on_finish` method returns a promise.
+    if (extensionCallbackResults.some((result) => typeof result.then === "function")) {
+      Promise.all(
+        extensionCallbackResults.map((result) =>
+          Promise.resolve(result).then((ext_data_values) => {
+            Object.assign(trial_data_values, ext_data_values);
+          })
+        )
+      ).then(onExtensionCallbacksFinished);
     } else {
-      if (current_trial.post_trial_gap > 0) {
-        setTimeout(this.nextTrial, current_trial.post_trial_gap);
-      } else {
-        this.nextTrial();
+      for (const values of extensionCallbackResults) {
+        Object.assign(trial_data_values, values);
       }
+      onExtensionCallbacksFinished();
     }
   }
 
@@ -671,22 +689,20 @@ export class JsPsych {
 
   private evaluateTimelineVariables(trial) {
     for (const key of Object.keys(trial)) {
-      if (key === "type") {
-        // skip the `type` parameter as it contains a plugin
-        //continue;
-      }
-      // timeline variables on the root level
       if (
         typeof trial[key] === "object" &&
         trial[key] !== null &&
         typeof trial[key].timelineVariablePlaceholder !== "undefined"
       ) {
-        /*trial[key].toString().replace(/\s/g, "") ==
-          "function(){returntimeline.timelineVariable(varname);}"
-      )*/ trial[key] = trial[key].timelineVariableFunction();
+        trial[key] = trial[key].timelineVariableFunction();
       }
       // timeline variables that are nested in objects
-      if (typeof trial[key] === "object" && trial[key] !== null) {
+      if (
+        typeof trial[key] === "object" &&
+        trial[key] !== null &&
+        key !== "timeline" &&
+        key !== "timeline_variables"
+      ) {
         this.evaluateTimelineVariables(trial[key]);
       }
     }
@@ -736,9 +752,11 @@ export class JsPsych {
     else if (typeof obj === "object") {
       if (info === null || !info.nested) {
         for (const key of Object.keys(obj)) {
-          if (key === "type") {
+          if (key === "type" || key === "timeline" || key === "timeline_variables") {
             // Ignore the object's `type` field because it contains a plugin and we do not want to
-            // call plugin functions
+            // call plugin functions. Also ignore `timeline` and `timeline_variables` because they
+            // are used in the `trials` parameter of the preload plugin and we don't want to actually
+            // evaluate those in that context.
             continue;
           }
           obj[key] = this.replaceFunctionsWithValues(obj[key], null);

package/src/TimelineNode.ts

@@ -357,7 +357,11 @@ export class TimelineNode {
   // recursive downward search for active trial to extract timeline variable
   timelineVariable(variable_name: string) {
     if (typeof this.timeline_parameters == "undefined") {
-      return this.findTimelineVariable(variable_name);
+      const val = this.findTimelineVariable(variable_name);
+      if (typeof val === "undefined") {
+        console.warn("Timeline variable " + variable_name + " not found.");
+      }
+      return val;
     } else {
       // if progress.current_location is -1, then the timeline variable is being evaluated
       // in a function that runs prior to the trial starting, so we should treat that trial
@@ -371,7 +375,11 @@ export class TimelineNode {
         loc = loc - 1;
       }
       // now find the variable
-      return this.timeline_parameters.timeline[loc].timelineVariable(variable_name);
+      const val = this.timeline_parameters.timeline[loc].timelineVariable(variable_name);
+      if (typeof val === "undefined") {
+        console.warn("Timeline variable " + variable_name + " not found.");
+      }
+      return val;
     }
   }
 

package/src/modules/extensions.ts

@@ -19,5 +19,5 @@ export interface JsPsychExtension {
    * Called at the end of the trial.
    * @returns Data to append to the trial's data object.
    */
-  on_finish(params?: Record<string, any>): Record<string, any>;
+  on_finish(params?: Record<string, any>): Record<string, any> | Promise<Record<string, any>>;
 }

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

@@ -13,7 +13,10 @@ export class MediaAPI {
 
   // video //
   private video_buffers = {};
-  getVideoBuffer(videoID) {
+  getVideoBuffer(videoID: string) {
+    if (videoID.startsWith("blob:")) {
+      this.video_buffers[videoID] = videoID;
+    }
     return this.video_buffers[videoID];
   }
 
@@ -334,4 +337,21 @@ export class MediaAPI {
   getMicrophoneRecorder(): MediaRecorder {
     return this.microphone_recorder;
   }
+
+  private camera_stream: MediaStream = null;
+  private camera_recorder: MediaRecorder = null;
+
+  initializeCameraRecorder(stream: MediaStream, opts?: MediaRecorderOptions) {
+    this.camera_stream = stream;
+    const recorder = new MediaRecorder(stream, opts);
+    this.camera_recorder = recorder;
+  }
+
+  getCameraStream(): MediaStream {
+    return this.camera_stream;
+  }
+
+  getCameraRecorder(): MediaRecorder {
+    return this.camera_recorder;
+  }
 }