Respect dynamically added trial/timeline descriptions

.changeset/large-plums-guess.md

@@ -0,0 +1,5 @@
+---
+"jspsych": minor
+---
+
+We added a feature that allows users to dynamically add or remove trials or nested timelines to a timeline array during runtime.

docs/overview/timeline.md

@@ -467,6 +467,104 @@ const after_if_trial = {
 jsPsych.run([pre_if_trial, if_node, after_if_trial]);
 ```
 
+## Modifying timelines at runtime
+
+Although this functionality can also be achieved through a combination of the `conditional_function` and the use of dynamic variables in the `stimulus` parameter, our timeline implementation allows you to dynamically insert or remove trials and nested timelines during runtime.
+
+### Inserting timeline nodes at runtime
+For example, you may have a branching point in your experiment where the participant is given 3 choices, each leading to a different timeline: 
+
+```javascript
+const jspsych = initJsPsych();
+let timeline = [];
+
+const welcome_trial = {
+	type: jsPsychHtmlKeyboardResponse,
+	stimulus: 'Welcome!'
+}
+
+const choice_trial = {
+	type: jsPsychHtmlKeyboardResponse,
+	stimulus: 'Press 1 if you are a new participant. Press 2 for inquiries about an existing experiment run. Press 3 for Spanish.',
+	choices: ['1','2','3']
+}
+```
+This would be trickier to implement with the `conditional_function` since it can only handle 2 branches -- case when `True` or case when `False`. Instead, you can modify the timeline by modifying `choice_trial` to dynamically adding a timeline at the end of the choice trial according to the chosen condition:
+
+```javascript
+const b1_t1 = {...};
+const b1_t2 = {...};
+const b1_t3 = {...};
+// So on and so forth
+const b3_t3 = {...};
+
+const branch_1 = [b1_t1, b1_t2, b1_t3];
+const branch_2 = [b2_t1, b2_t2, b2_t3];
+const branch_3 = [b3_t1, b3_t2, b3_t3];
+
+const choice_trial = {
+	type: jsPsychHtmlKeyboardResponse,
+	stimulus: 'Press 1 if you are a new participant. Press 2 for inquiries about an existing experiment run. Press 3 for Spanish.',
+	choices: ['1','2','3'],
+	on_finish: (data) => {
+		switch(data.response) {
+			case '1':
+				timeline.push(branch_1);
+				break;
+			case '2':
+				timeline.push(branch_2);
+				break;
+			case '3':
+				timeline.push(branch_3);
+				break;
+		}
+	}
+}
+timeline.push(start_trial, choice_trial);
+```
+During runtime, choices 1, 2 and 3 will dynamically add a different (nested) timeline, `branch_1`, `branch_2` and `branch_3` respectively, to the end of the main timeline.
+
+### Removing timeline nodes at runtime
+
+You can also remove upcoming timeline nodes from the timeline at runtime. To demonstrate this, we can modify the above example by adding a 4th choice and extra trial at the end of the timeline:
+
+```javascript
+const choice_trial = {
+	type: jsPsychHtmlKeyboardResponse,
+	stimulus: 'Press 1 if you are a new participant. Press 2 for inquiries about an existing experiment run. Press 3 for Spanish. Press 4 to exit.',
+	choices: ['1','2','3', '4'],
+	on_finish: (data) => {
+		switch(data.response) {
+			case '1':
+				timeline.push(branch_1);
+				break;
+			case '2':
+				timeline.push(branch_2);
+				break;
+			case '3':
+				timeline.push(branch_3);
+				break;
+			case '4':
+				timeline.pop();
+				break;
+		}
+	}
+}
+
+const end_trial = {
+	type: JsPsychHtmlKeyboardResponse,
+	stimulus: 'End of experiment'
+}
+
+timeline.push(start_trial, choice_trial, end_trial)
+```
+Now, if 1, 2 or 3 were chosen during runtime, the `end_trial` will run after the dynamically added timeline corresponding to the choice has been run; but if 4 was chosen, `end_trial` will be removed at runtime, and the timeline will terminate.
+
+### Exception cases for adding/removing timeline nodes dynamically
+Adding or removing timeline nodes work as expected when the addition/removal occurs at a future point in the timeline relative to the current executing node, but not if it occurs before the current node. The example above works as expected becaues all added/removed nodes occur at the end of the timeline via `push()` and `pop()`, but if the branches were inserted at a point in the timeline that has already been executed, e.g. `timeline.splice(0, 0, branch_1)`, then `branch_1` will not be executed.
+
+In the case of a looping timeline, adding a timeline node at a point before the current node will cause the current node to be executed again; and removing a timeline node at a point before the current node will cause the next node to be skipped.
+
 ## Timeline start and finish functions
 
 You can run a custom function at the start and end of a timeline node using the `on_timeline_start` and `on_timeline_finish` callback function parameters. These are functions that will run when the timeline starts and ends, respectively. 

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

@@ -58,6 +58,126 @@ describe("Timeline", () => {
       expect((children[1] as Timeline).children.map((child) => child.index)).toEqual([1, 2]);
     });
 
+    it("respects dynamically added child node descriptions", async () => {
+      TestPlugin.setManualFinishTrialMode();
+
+      const timelineDescription: TimelineArray = [{ type: TestPlugin }];
+      const timeline = createTimeline(timelineDescription);
+
+      const runPromise = timeline.run();
+      expect(timeline.children.length).toEqual(1);
+
+      timelineDescription.push({ timeline: [{ type: TestPlugin }] });
+      await TestPlugin.finishTrial();
+      await TestPlugin.finishTrial();
+      await runPromise;
+
+      expect(timeline.children.length).toEqual(2);
+    });
+
+    it("respects dynamically added child node descriptions at the start", async () => {
+      TestPlugin.setManualFinishTrialMode();
+
+      const timelineDescription: TimelineArray = [{ type: TestPlugin }];
+      const timeline = createTimeline(timelineDescription);
+
+      const runPromise = timeline.run();
+      expect(timeline.children.length).toEqual(1);
+
+      timelineDescription.splice(0, 0, { timeline: [{ type: TestPlugin }] });
+      await TestPlugin.finishTrial();
+      await TestPlugin.finishTrial();
+      await runPromise;
+
+      expect(timeline.children.length).toEqual(2);
+    });
+
+    it("dynamically added child node descriptions before a node after it has been run", async () => {
+      TestPlugin.setManualFinishTrialMode();
+
+      const timelineDescription: TimelineArray = [{ type: TestPlugin }];
+      const timeline = createTimeline(timelineDescription);
+
+      const runPromise = timeline.run();
+      expect(timeline.children.length).toEqual(1);
+
+      await TestPlugin.finishTrial();
+      timelineDescription.splice(0, 0, { timeline: [{ type: TestPlugin }] });
+      await TestPlugin.finishTrial();
+      await runPromise;
+
+      expect(timeline.children.length).toEqual(1);
+    });
+
+    it("respects dynamically removed end child node descriptions", async () => {
+      TestPlugin.setManualFinishTrialMode();
+
+      const timelineDescription: TimelineArray = [
+        { type: TestPlugin },
+        { timeline: [{ type: TestPlugin }] },
+        { type: TestPlugin },
+      ];
+      const timeline = createTimeline(timelineDescription);
+
+      const runPromise = timeline.run();
+      expect(timeline.children.length).toEqual(1); // Only the first child is instantiated because they are incrementally instantiated now
+
+      timelineDescription.pop();
+      await TestPlugin.finishTrial();
+      await TestPlugin.finishTrial();
+      await runPromise;
+
+      expect(timeline.children.length).toEqual(2);
+      expect(timeline.children).toEqual([expect.any(Trial), expect.any(Timeline)]);
+    });
+
+    it("respects dynamically removed middle child node descriptions", async () => {
+      TestPlugin.setManualFinishTrialMode();
+
+      const timelineDescription: TimelineArray = [
+        { type: TestPlugin },
+        { timeline: [{ type: TestPlugin }] },
+        { type: TestPlugin },
+      ];
+      const timeline = createTimeline(timelineDescription);
+
+      const runPromise = timeline.run();
+      expect(timeline.children.length).toEqual(1);
+
+      timelineDescription.splice(1, 1);
+      await TestPlugin.finishTrial();
+      await TestPlugin.finishTrial();
+      await runPromise;
+
+      expect(timeline.children.length).toEqual(2);
+      expect(timeline.children).toEqual([expect.any(Trial), expect.any(Trial)]);
+    });
+
+    it("dynamically remove first node after running it", async () => {
+      TestPlugin.setManualFinishTrialMode();
+
+      const timelineDescription: TimelineArray = [
+        { type: TestPlugin, data: { I: 0 } },
+        { timeline: [{ type: TestPlugin, data: { I: 1 } }] },
+        { type: TestPlugin, data: { I: 2 } },
+        { type: TestPlugin, data: { I: 3 } },
+      ];
+      const timeline = createTimeline(timelineDescription);
+
+      const runPromise = timeline.run();
+      await TestPlugin.finishTrial();
+      timelineDescription.shift();
+      await TestPlugin.finishTrial();
+      await TestPlugin.finishTrial();
+      await runPromise;
+
+      expect(timeline.children.length).toEqual(3);
+      expect(timeline.children[0].getDataParameter().I).toEqual(0);
+      const secondChildDescription = timeline.children[1].description as TimelineDescription;
+      expect(secondChildDescription["timeline"][0]).toHaveProperty("data.I", 1);
+      expect(timeline.children[2].getDataParameter().I).toEqual(3);
+    });
+
     describe("with `pause()` and `resume()` calls`", () => {
       beforeEach(() => {
         TestPlugin.setManualFinishTrialMode();
@@ -84,12 +204,9 @@ describe("Timeline", () => {
 
         await TestPlugin.finishTrial();
         expect(timeline.children[1].getStatus()).toBe(TimelineNodeStatus.COMPLETED);
-        expect(timeline.children[2].getStatus()).toBe(TimelineNodeStatus.PENDING);
-
-        // Resolving the next trial promise shouldn't continue the experiment since no trial should be running.
-        await TestPlugin.finishTrial();
 
-        expect(timeline.children[2].getStatus()).toBe(TimelineNodeStatus.PENDING);
+        // The timeline is paused, so it shouldn't have instantiated the next child node yet.
+        expect(timeline.children.length).toEqual(2);
 
         timeline.resume();
         await flushPromises();

packages/jspsych/src/timeline/Timeline.ts

@@ -75,7 +75,9 @@ export class Timeline extends TimelineNode {
           for (const timelineVariableIndex of timelineVariableOrder) {
             this.setCurrentTimelineVariablesByIndex(timelineVariableIndex);
 
-            for (const childNode of this.instantiateChildNodes()) {
+            for (const childNodeDescription of this.description.timeline) {
+              const childNode = this.instantiateChildNode(childNodeDescription);
+
               const previousChild = this.currentChild;
               this.currentChild = childNode;
               childNode.index = previousChild
@@ -151,14 +153,15 @@ export class Timeline extends TimelineNode {
     }
   }
 
-  private instantiateChildNodes() {
-    const newChildNodes = this.description.timeline.map((childDescription) => {
-      return isTimelineDescription(childDescription)
-        ? new Timeline(this.dependencies, childDescription, this)
-        : new Trial(this.dependencies, childDescription, this);
-    });
-    this.children.push(...newChildNodes);
-    return newChildNodes;
+  private instantiateChildNode(
+    childDescription: TimelineDescription | TimelineArray | TrialDescription
+  ) {
+    const newChildNode = isTimelineDescription(childDescription)
+      ? new Timeline(this.dependencies, childDescription, this)
+      : new Trial(this.dependencies, childDescription, this);
+
+    this.children.push(newChildNode);
+    return newChildNode;
   }
 
   private currentTimelineVariables: Record<string, any>;