Implement migration errors

.changeset/grumpy-dragons-hunt.md

@@ -0,0 +1,5 @@
+---
+"jspsych": minor
+---
+
+Throw errors if trial `type` parameters are strings, deprecated jsPsych functions are called, or the global `jsPsych` variable is used without assigning a JsPsych instance first (#2217)

packages/jspsych/src/JsPsych.ts

@@ -1,6 +1,7 @@
 import autoBind from "auto-bind";
 
 import { version } from "../package.json";
+import { MigrationError } from "./migration";
 import { JsPsychData } from "./modules/data";
 import { PluginAPI, createJointPluginAPIObject } from "./modules/plugin-api";
 import { ParameterType, universalPluginParameters } from "./modules/plugins";
@@ -517,6 +518,12 @@ export class JsPsych {
     // process all timeline variables for this trial
     this.evaluateTimelineVariables(trial);
 
+    if (typeof trial.type === "string") {
+      throw new MigrationError(
+        "A string was provided as the trial's `type` parameter. Since jsPsych v7, the `type` parameter needs to be a plugin object."
+      );
+    }
+
     // instantiate the plugin for this trial
     trial.type = {
       // this is a hack to internally keep the old plugin object structure and prevent touching more

packages/jspsych/src/index.ts

@@ -1,4 +1,5 @@
 import { JsPsych } from "./JsPsych";
+import { MigrationError } from "./migration";
 
 // temporary patch for Safari
 if (
@@ -20,7 +21,42 @@ if (
  * @returns A new JsPsych instance
  */
 export function initJsPsych(options?) {
-  return new JsPsych(options);
+  const jsPsych = new JsPsych(options);
+
+  // Handle invocations of non-existent v6 methods with migration errors
+  const migrationMessages = {
+    init: "`jsPsych.init()` was replaced by `initJsPsych()` in jsPsych v7.",
+
+    ALL_KEYS: 'jsPsych.ALL_KEYS was replaced by the "ALL_KEYS" string in jsPsych v7.',
+    NO_KEYS: 'jsPsych.NO_KEYS was replaced by the "NO_KEYS" string in jsPsych v7.',
+
+    // Getter functions that were renamed
+    currentTimelineNodeID:
+      "`currentTimelineNodeID()` was renamed to `getCurrentTimelineNodeID()` in jsPsych v7.",
+    progress: "`progress()` was renamed to `getProgress()` in jsPsych v7.",
+    startTime: "`startTime()` was renamed to `getStartTime()` in jsPsych v7.",
+    totalTime: "`totalTime()` was renamed to `getTotalTime()` in jsPsych v7.",
+    currentTrial: "`currentTrial()` was renamed to `getCurrentTrial()` in jsPsych v7.",
+    initSettings: "`initSettings()` was renamed to `getInitSettings()` in jsPsych v7.",
+    allTimelineVariables:
+      "`allTimelineVariables()` was renamed to `getAllTimelineVariables()` in jsPsych v7.",
+  };
+
+  Object.defineProperties(
+    jsPsych,
+    Object.fromEntries(
+      Object.entries(migrationMessages).map(([key, message]) => [
+        key,
+        {
+          get() {
+            throw new MigrationError(message);
+          },
+        },
+      ])
+    )
+  );
+
+  return jsPsych;
 }
 
 export { JsPsych } from "./JsPsych";

packages/jspsych/src/migration.ts

@@ -0,0 +1,37 @@
+export class MigrationError extends Error {
+  constructor(message = "The global `jsPsych` variable is no longer available in jsPsych v7.") {
+    super(
+      `${message} Please follow the migration guide at https://www.jspsych.org/7.0/support/migration-v7/ to update your experiment.`
+    );
+    this.name = "MigrationError";
+  }
+}
+
+// Define a global jsPsych object to handle invocations on it with migration errors
+(window as any).jsPsych = {
+  get init() {
+    throw new MigrationError("`jsPsych.init()` was replaced by `initJsPsych()` in jsPsych v7.");
+  },
+
+  get data() {
+    throw new MigrationError();
+  },
+  get randomization() {
+    throw new MigrationError();
+  },
+  get turk() {
+    throw new MigrationError();
+  },
+  get pluginAPI() {
+    throw new MigrationError();
+  },
+
+  get ALL_KEYS() {
+    throw new MigrationError(
+      'jsPsych.ALL_KEYS was replaced by the "ALL_KEYS" string in jsPsych v7.'
+    );
+  },
+  get NO_KEYS() {
+    throw new MigrationError('jsPsych.NO_KEYS was replaced by the "NO_KEYS" string in jsPsych v7.');
+  },
+};