jspsych 8.0.2 → 8.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jspsych",
-  "version": "8.0.2",
+  "version": "8.1.0",
   "description": "Behavioral experiments in a browser",
   "type": "module",
   "main": "dist/index.cjs",
@@ -48,7 +48,7 @@
   },
   "devDependencies": {
     "@fontsource/open-sans": "4.5.3",
-    "@jspsych/config": "^3.0.0",
+    "@jspsych/config": "^3.0.1",
     "@types/dom-mediacapture-record": "^1.0.11",
     "base64-inline-loader": "^2.0.1",
     "css-loader": "^6.6.0",

package/src/modules/randomization.ts

@@ -12,7 +12,7 @@ export function setSeed(seed: string = Math.random().toString()) {
   return seed;
 }
 
-export function repeat(array, repetitions, unpack = false) {
+export function repeat(array: any, repetitions: any, unpack = false) {
   const arr_isArray = Array.isArray(array);
   const rep_isArray = Array.isArray(repetitions);
 
@@ -77,7 +77,7 @@ export function repeat(array, repetitions, unpack = false) {
   return out;
 }
 
-export function shuffle(array: Array<any>) {
+export function shuffle<T>(array: Array<T>) {
   if (!Array.isArray(array)) {
     console.error("Argument to shuffle() must be an array.");
   }
@@ -101,7 +101,7 @@ export function shuffle(array: Array<any>) {
   return copy_array;
 }
 
-export function shuffleNoRepeats(arr: Array<any>, equalityTest: (a: any, b: any) => boolean) {
+export function shuffleNoRepeats<T>(arr: Array<T>, equalityTest: (a: T, b: T) => boolean) {
   if (!Array.isArray(arr)) {
     console.error("First argument to shuffleNoRepeats() must be an array.");
   }
@@ -143,7 +143,10 @@ export function shuffleNoRepeats(arr: Array<any>, equalityTest: (a: any, b: any)
   return random_shuffle;
 }
 
-export function shuffleAlternateGroups(arr_groups, random_group_order = false) {
+export function shuffleAlternateGroups<T extends any[]>(
+  arr_groups: Array<T>,
+  random_group_order = false
+) {
   const n_groups = arr_groups.length;
   if (n_groups == 1) {
     console.warn(
@@ -178,7 +181,7 @@ export function shuffleAlternateGroups(arr_groups, random_group_order = false) {
   return out;
 }
 
-export function sampleWithoutReplacement(arr, size) {
+export function sampleWithoutReplacement<T>(arr: Array<T>, size: number) {
   if (!Array.isArray(arr)) {
     console.error("First argument to sampleWithoutReplacement() must be an array");
   }
@@ -189,7 +192,7 @@ export function sampleWithoutReplacement(arr, size) {
   return shuffle(arr).slice(0, size);
 }
 
-export function sampleWithReplacement(arr, size, weights?) {
+export function sampleWithReplacement<T>(arr: Array<T>, size: number, weights?: number[]) {
   if (!Array.isArray(arr)) {
     console.error("First argument to sampleWithReplacement() must be an array");
   }
@@ -301,6 +304,21 @@ export function sampleExGaussian(
   return s;
 }
 
+type RandomWordsOptions = {
+  min?: number;
+  max?: number;
+  exactly?: number;
+  maxLength?: number;
+  wordsPerString?: number;
+  seperator?: string;
+  formatter?: (word: string, index: number) => string;
+  join?: string;
+};
+
+type RandomWordsResult<T extends RandomWordsOptions> = T extends { join: string }
+  ? string
+  : string[];
+
 /**
  * Generate one or more random words.
  *
@@ -311,8 +329,9 @@ export function sampleExGaussian(
  *
  * @returns An array of words or a single string, depending on parameter choices.
  */
-export function randomWords(opts) {
-  return rw(opts);
+export function randomWords<T extends RandomWordsOptions>(opts: T) {
+  // there is a type incompatibility here because `random-words` uses overloads rather than generics
+  return rw(opts) as RandomWordsResult<T>;
 }
 
 // Box-Muller transformation for a random sample from normal distribution with mean = 0, std = 1
@@ -325,8 +344,8 @@ function randn_bm() {
   return Math.sqrt(-2.0 * Math.log(u)) * Math.cos(2.0 * Math.PI * v);
 }
 
-function unpackArray(array) {
-  const out = {};
+function unpackArray(array: object[]) {
+  const out: Record<string, any> = {};
 
   for (const x of array) {
     for (const key of Object.keys(x)) {

package/src/timeline/Timeline.spec.ts

@@ -58,6 +58,109 @@ 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("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 +187,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();

package/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>;