jspsych 8.1.0 → 8.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jspsych",
-  "version": "8.1.0",
+  "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/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(