jspsych 8.0.3 → 8.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jspsych",
-  "version": "8.0.3",
+  "version": "8.2.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.1",
+    "@jspsych/config": "^3.2.0",
     "@types/dom-mediacapture-record": "^1.0.11",
     "base64-inline-loader": "^2.0.1",
     "css-loader": "^6.6.0",

package/src/ExtensionManager.spec.ts

@@ -1,6 +1,6 @@
 import { Class } from "type-fest";
 
-import { TestExtension } from "../tests/extensions/test-extension";
+import { TestExtension } from "../tests/extensions/TestExtension";
 import { ExtensionManager, ExtensionManagerDependencies } from "./ExtensionManager";
 import { JsPsych } from "./JsPsych";
 import { JsPsychExtension } from "./modules/extensions";

package/src/JsPsych.ts

@@ -1,9 +1,13 @@
 import autoBind from "auto-bind";
+// To work with citations
+import { Class } from "type-fest";
 
 import { version } from "../package.json";
 import { ExtensionManager, ExtensionManagerDependencies } from "./ExtensionManager";
 import { JsPsychData, JsPsychDataDependencies } from "./modules/data";
+import { JsPsychExtension } from "./modules/extensions";
 import { PluginAPI, createJointPluginAPIObject } from "./modules/plugin-api";
+import { JsPsychPlugin } from "./modules/plugins";
 import * as randomization from "./modules/randomization";
 import * as turk from "./modules/turk";
 import * as utils from "./modules/utils";
@@ -257,6 +261,48 @@ export class JsPsych {
     return this.timeline?.description.timeline;
   }
 
+  /**
+   * Prints out a string containing citations for the jsPsych library and all input plugins/extensions in the specified format.
+   * If called without input, prints citation for jsPsych library.
+   *
+   * @param plugins The plugins/extensions to generate citations for. Always prints the citation for the jsPsych library at the top.
+   * @param format The desired output citation format. Currently supports "apa" and "bibtex".
+   * @returns String containing citations separated with newline character.
+   */
+  getCitations(
+    plugins: Array<Class<JsPsychPlugin<any>> | Class<JsPsychExtension>> = [],
+    format: "apa" | "bibtex" = "apa"
+  ) {
+    const formatOptions = ["apa", "bibtex"];
+    // prettier-ignore
+    const jsPsychCitations: any = '__CITATIONS__';
+    format = format.toLowerCase() as "apa" | "bibtex";
+    // Check if plugins is an array
+    if (!Array.isArray(plugins)) {
+      throw new Error("Expected array of plugins/extensions");
+    }
+    // Check if format is supported
+    else if (!formatOptions.includes(format)) {
+      throw new Error("Unsupported citation format");
+    }
+    // Print citations
+    else {
+      const jsPsychCitation = jsPsychCitations[format];
+      const citationSet = new Set([jsPsychCitation]);
+
+      for (const plugin of plugins) {
+        try {
+          const pluginCitation = plugin["info"].citations[format];
+          citationSet.add(pluginCitation);
+        } catch {
+          console.error(`${plugin} does not have citation in ${format} format.`);
+        }
+      }
+      const citationList = Array.from(citationSet).join("\n");
+      return citationList;
+    }
+  }
+
   get extensions() {
     return this.extensionManager?.extensions ?? {};
   }

package/src/modules/extensions.ts

@@ -4,6 +4,7 @@ export interface JsPsychExtensionInfo {
   name: string;
   version?: string;
   data?: ParameterInfos;
+  citations?: Record<string, string> | string;
 }
 
 export interface JsPsychExtension {

package/src/modules/plugins.ts

@@ -141,6 +141,7 @@ export interface PluginInfo {
   version?: string;
   parameters: ParameterInfos;
   data?: ParameterInfos;
+  citations?: Record<string, string> | string;
 }
 
 export interface JsPsychPlugin<I extends PluginInfo> {

package/src/modules/randomization.ts

@@ -1,5 +1,5 @@
 import rw from "random-words";
-import seedrandom from "seedrandom/lib/alea";
+import seedrandom from "seedrandom/lib/alea.js";
 
 /**
  * Uses the `seedrandom` package to replace Math.random() with a seedable PRNG.

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

package/src/timeline/Trial.spec.ts

@@ -36,6 +36,16 @@ describe("Trial", () => {
     return trial;
   };
 
+  it("throws an error upon construction when the `type` parameter or plugin info object is undefined", () => {
+    for (const description of [{}, { type: {} }] as TrialDescription[]) {
+      expect(
+        () => new Trial(dependencies, description, timeline)
+      ).toThrowErrorMatchingInlineSnapshot(
+        "\"Plugin not recognized. Please provide a valid plugin using the 'type' parameter.\""
+      );
+    }
+  });
+
   describe("run()", () => {
     it("instantiates the corresponding plugin", async () => {
       const trial = createTrial({ type: TestPlugin });
@@ -436,6 +446,8 @@ describe("Trial", () => {
                 return TestPlugin;
               case "x":
                 return "foo";
+              case "y":
+                return ["foo", "bar"];
               default:
                 return undefined;
             }
@@ -444,17 +456,19 @@ describe("Trial", () => {
         const trial = createTrial({
           type: new TimelineVariable("t"),
           requiredString: new TimelineVariable("x"),
+          stringArray: new TimelineVariable("y"),
           requiredComplexNested: { requiredChild: () => new TimelineVariable("x") },
           requiredComplexNestedArray: [{ requiredChild: () => new TimelineVariable("x") }],
         });
 
         await trial.run();
 
-        // The `x` timeline variables should have been replaced with `foo`
+        // The `x` and `y` timeline variables should have been evaluated
         expect(trial.pluginInstance.trial).toHaveBeenCalledWith(
           expect.anything(),
           expect.objectContaining({
             requiredString: "foo",
+            stringArray: ["foo", "bar"],
             requiredComplexNested: expect.objectContaining({ requiredChild: "foo" }),
             requiredComplexNestedArray: [expect.objectContaining({ requiredChild: "foo" })],
           }),

package/src/timeline/Trial.ts

@@ -35,7 +35,12 @@ export class Trial extends TimelineNode {
 
     this.trialObject = deepCopy(description);
     this.pluginClass = this.getParameterValue("type", { evaluateFunctions: false });
-    this.pluginInfo = this.pluginClass["info"];
+    this.pluginInfo = this.pluginClass?.["info"];
+    if (!this.pluginInfo) {
+      throw new Error(
+        "Plugin not recognized. Please provide a valid plugin using the 'type' parameter."
+      );
+    }
 
     if (!("version" in this.pluginInfo) && !("data" in this.pluginInfo)) {
       console.warn(