jspsych 7.3.4 → 8.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jspsych",
-  "version": "7.3.4",
+  "version": "8.0.0",
   "description": "Behavioral experiments in a browser",
   "type": "module",
   "main": "dist/index.cjs",
@@ -43,21 +43,22 @@
   "dependencies": {
     "auto-bind": "^4.0.0",
     "random-words": "^1.1.1",
-    "seedrandom": "^3.0.5"
+    "seedrandom": "^3.0.5",
+    "type-fest": "^2.9.0"
   },
   "devDependencies": {
     "@fontsource/open-sans": "4.5.3",
-    "@jspsych/config": "^2.0.0",
+    "@jspsych/config": "^3.0.0",
     "@types/dom-mediacapture-record": "^1.0.11",
     "base64-inline-loader": "^2.0.1",
     "css-loader": "^6.6.0",
     "mini-css-extract-plugin": "^2.5.3",
     "npm-run-all": "^4.1.5",
+    "replace-in-file-webpack-plugin": "^1.0.6",
     "sass": "^1.43.5",
     "sass-loader": "^12.4.0",
     "webpack": "^5.76.0",
     "webpack-cli": "^4.9.2",
-    "webpack-remove-empty-scripts": "^0.7.2",
-    "replace-in-file-webpack-plugin": "^1.0.6"
+    "webpack-remove-empty-scripts": "^0.7.2"
   }
 }

package/src/ExtensionManager.spec.ts

@@ -0,0 +1,123 @@
+import { Class } from "type-fest";
+
+import { TestExtension } from "../tests/extensions/test-extension";
+import { ExtensionManager, ExtensionManagerDependencies } from "./ExtensionManager";
+import { JsPsych } from "./JsPsych";
+import { JsPsychExtension } from "./modules/extensions";
+
+jest.mock("../src/JsPsych");
+
+export class ExtensionManagerDependenciesMock implements ExtensionManagerDependencies {
+  instantiateExtension: jest.Mock<JsPsychExtension>;
+
+  jsPsych: JsPsych; // to be passed to extensions by `instantiateExtension`
+
+  constructor() {
+    this.initializeProperties();
+  }
+
+  private initializeProperties() {
+    this.instantiateExtension = jest.fn(
+      (extensionClass: Class<JsPsychExtension>) => new extensionClass(this.jsPsych)
+    );
+
+    this.jsPsych = new JsPsych();
+  }
+
+  reset() {
+    this.initializeProperties();
+  }
+}
+
+const dependencies = new ExtensionManagerDependenciesMock();
+afterEach(() => {
+  dependencies.reset();
+});
+
+describe("ExtensionManager", () => {
+  it("instantiates all extensions upon construction", () => {
+    new ExtensionManager(dependencies, [{ type: TestExtension }]);
+
+    expect(dependencies.instantiateExtension).toHaveBeenCalledTimes(1);
+    expect(dependencies.instantiateExtension).toHaveBeenCalledWith(TestExtension);
+  });
+
+  it("exposes extensions via the `extensions` property", () => {
+    const manager = new ExtensionManager(dependencies, [{ type: TestExtension }]);
+
+    expect(manager.extensions).toEqual({ test: expect.any(TestExtension) });
+  });
+
+  describe("initialize()", () => {
+    it("calls `initialize` on all extensions, providing the parameters from the constructor", async () => {
+      const manager = new ExtensionManager(dependencies, [
+        { type: TestExtension, params: { option: 1 } },
+      ]);
+
+      await manager.initializeExtensions();
+
+      expect(manager.extensions.test.initialize).toHaveBeenCalledTimes(1);
+      expect(manager.extensions.test.initialize).toHaveBeenCalledWith({ option: 1 });
+    });
+
+    it("defaults `params` to an empty object", async () => {
+      const manager = new ExtensionManager(dependencies, [{ type: TestExtension }]);
+
+      await manager.initializeExtensions();
+      expect(manager.extensions.test.initialize).toHaveBeenCalledWith({});
+    });
+  });
+
+  describe("onStart()", () => {
+    it("calls `on_start` on all extensions specified in the provided `extensions` parameter", () => {
+      const manager = new ExtensionManager(dependencies, [{ type: TestExtension }]);
+
+      const onStartCallback = jest.mocked(manager.extensions.test.on_start);
+
+      manager.onStart();
+      expect(onStartCallback).not.toHaveBeenCalled();
+
+      manager.onStart([{ type: TestExtension, params: { my: "option" } }]);
+      expect(onStartCallback).toHaveBeenCalledWith({ my: "option" });
+    });
+  });
+
+  describe("onLoad()", () => {
+    it("calls `on_load` on all extensions specified in the provided `extensions` parameter", () => {
+      const manager = new ExtensionManager(dependencies, [{ type: TestExtension }]);
+
+      const onLoadCallback = jest.mocked(manager.extensions.test.on_load);
+
+      manager.onLoad();
+      expect(onLoadCallback).not.toHaveBeenCalled();
+
+      manager.onLoad([{ type: TestExtension, params: { my: "option" } }]);
+      expect(onLoadCallback).toHaveBeenCalledWith({ my: "option" });
+    });
+  });
+
+  describe("onFinish()", () => {
+    it("calls `on_finish` on all extensions specified in the provided `extensions` parameter and returns a joint extension results object", async () => {
+      const manager = new ExtensionManager(dependencies, [{ type: TestExtension }]);
+
+      const onFinishCallback = jest.mocked(manager.extensions.test.on_finish);
+      onFinishCallback.mockReturnValue({
+        extension_type: "test",
+        extension_version: "1.0",
+        extension: "result",
+      });
+
+      let results = await manager.onFinish(undefined);
+      expect(onFinishCallback).not.toHaveBeenCalled();
+      expect(results).toEqual({});
+
+      results = await manager.onFinish([{ type: TestExtension, params: { my: "option" } }]);
+      expect(onFinishCallback).toHaveBeenCalledWith({ my: "option" });
+      expect(results).toEqual({
+        extension_type: ["test"],
+        extension_version: ["1.0"],
+        extension: "result",
+      });
+    });
+  });
+});

package/src/ExtensionManager.ts

@@ -0,0 +1,81 @@
+import { Class } from "type-fest";
+
+import { JsPsychExtension, JsPsychExtensionInfo } from "./modules/extensions";
+import { TrialExtensionsConfiguration } from "./timeline";
+
+export type GlobalExtensionsConfiguration = Array<{
+  type: Class<JsPsychExtension>;
+  params?: Record<string, any>;
+}>;
+
+export interface ExtensionManagerDependencies {
+  /**
+   * Given an extension class, create a new instance of it and return it.
+   */
+  instantiateExtension(extensionClass: Class<JsPsychExtension>): JsPsychExtension;
+}
+
+export class ExtensionManager {
+  private static getExtensionNameByClass(extensionClass: Class<JsPsychExtension>) {
+    return (extensionClass["info"] as JsPsychExtensionInfo).name;
+  }
+
+  public readonly extensions: Record<string, JsPsychExtension>;
+
+  constructor(
+    private dependencies: ExtensionManagerDependencies,
+    private extensionsConfiguration: GlobalExtensionsConfiguration
+  ) {
+    this.extensions = Object.fromEntries(
+      extensionsConfiguration.map((extension) => [
+        ExtensionManager.getExtensionNameByClass(extension.type),
+        this.dependencies.instantiateExtension(extension.type),
+      ])
+    );
+  }
+
+  private getExtensionInstanceByClass(extensionClass: Class<JsPsychExtension>) {
+    return this.extensions[ExtensionManager.getExtensionNameByClass(extensionClass)];
+  }
+
+  public async initializeExtensions() {
+    await Promise.all(
+      this.extensionsConfiguration.map(({ type, params = {} }) =>
+        this.getExtensionInstanceByClass(type).initialize(params)
+      )
+    );
+  }
+
+  public onStart(trialExtensionsConfiguration: TrialExtensionsConfiguration = []) {
+    for (const { type, params } of trialExtensionsConfiguration) {
+      this.getExtensionInstanceByClass(type)?.on_start(params);
+    }
+  }
+
+  public onLoad(trialExtensionsConfiguration: TrialExtensionsConfiguration = []) {
+    for (const { type, params } of trialExtensionsConfiguration) {
+      this.getExtensionInstanceByClass(type)?.on_load(params);
+    }
+  }
+
+  public async onFinish(
+    trialExtensionsConfiguration: TrialExtensionsConfiguration = []
+  ): Promise<Record<string, any>> {
+    const results = await Promise.all(
+      trialExtensionsConfiguration.map(({ type, params }) =>
+        Promise.resolve(this.getExtensionInstanceByClass(type)?.on_finish(params))
+      )
+    );
+
+    const extensionInfo = trialExtensionsConfiguration.length
+      ? {
+          extension_type: results.map((result) => result.extension_type),
+          extension_version: results.map((result) => result.extension_version),
+        }
+      : {};
+
+    results.push(extensionInfo);
+
+    return Object.assign({}, ...results);
+  }
+}