Allow trial on_finish methods to be async (#3182)

.changeset/old-moons-lay.md

@@ -0,0 +1,5 @@
+---
+"jspsych": minor
+---
+
+Allow trial `on_finish` methods to be asynchronous, i.e. return a `Promise`. Prior to this, promises returned by `on_finish` were not awaited before proceeding with the next trial.

packages/jspsych/src/timeline/Trial.spec.ts

@@ -6,7 +6,7 @@ import TestPlugin from "../../tests/TestPlugin";
 import { JsPsychPlugin, ParameterType } from "../modules/plugins";
 import { Timeline } from "./Timeline";
 import { Trial } from "./Trial";
-import { parameterPathArrayToString } from "./util";
+import { PromiseWrapper, parameterPathArrayToString } from "./util";
 import {
   SimulationOptionsParameter,
   TimelineVariable,
@@ -168,6 +168,27 @@ describe("Trial", () => {
       expect(onFinishCallback).toHaveBeenCalledWith(expect.objectContaining({ my: "result" }));
     });
 
+    it("awaits async `on_finish` callbacks", async () => {
+      const onFinishCallbackPromise = new PromiseWrapper();
+      const trial = createTrial({
+        type: TestPlugin,
+        on_finish: () => onFinishCallbackPromise.get(),
+      });
+
+      let hasTrialCompleted = false;
+      trial.run().then(() => {
+        hasTrialCompleted = true;
+      });
+
+      await flushPromises();
+      expect(hasTrialCompleted).toBe(false);
+
+      onFinishCallbackPromise.resolve();
+      await flushPromises();
+
+      expect(hasTrialCompleted).toBe(true);
+    });
+
     it("invokes the global `onTrialResultAvailable` and `onTrialFinished` callbacks", async () => {
       const invocations: string[] = [];
       dependencies.onTrialResultAvailable.mockImplementationOnce(() => {

packages/jspsych/src/timeline/Trial.ts

@@ -232,7 +232,7 @@ export class Trial extends TimelineNode {
     );
     Object.assign(this.result, extensionResults);
 
-    this.runParameterCallback("on_finish", this.getResult());
+    await Promise.resolve(this.runParameterCallback("on_finish", this.getResult()));
 
     this.dependencies.onTrialFinished(this);
   }