jspsych 7.3.3 → 8.0.0

package/src/timeline/util.spec.ts

@@ -0,0 +1,124 @@
+import { ParameterObjectPathCache, parameterPathArrayToString } from "./util";
+
+describe("parameterPathArrayToString()", () => {
+  it("works with flat paths", () => {
+    expect(parameterPathArrayToString(["flat"])).toEqual("flat");
+  });
+
+  it("works with nested object paths", () => {
+    expect(parameterPathArrayToString(["nested", "object", "path"])).toEqual("nested.object.path");
+  });
+
+  it("works with array indices", () => {
+    expect(parameterPathArrayToString(["arrayElement", "10"])).toEqual("arrayElement[10]");
+  });
+
+  it("works with nested object paths and array indices", () => {
+    expect(parameterPathArrayToString(["nested", "arrayElement", "10", "property"])).toEqual(
+      "nested.arrayElement[10].property"
+    );
+  });
+});
+
+describe("ParameterObjectPathCache", () => {
+  const rootObject = {
+    object: {
+      id: 1,
+      nestedObject: { id: 2 },
+    },
+    array: [{ id: 3 }, { id: 4, nestedObject: { id: 5 } }],
+    explicitlyUndefined: undefined,
+  };
+
+  let cache: ParameterObjectPathCache;
+
+  beforeEach(() => {
+    cache = new ParameterObjectPathCache();
+    cache.initialize(rootObject);
+  });
+
+  describe("lookup()", () => {
+    it("works with object properties", () => {
+      expect(cache.lookup(["nonExistent"])).toEqual({ doesPathExist: false, value: undefined });
+
+      expect(cache.lookup(["explicitlyUndefined"])).toEqual({
+        doesPathExist: true,
+        value: undefined,
+      });
+
+      expect(cache.lookup(["object"])).toEqual({
+        doesPathExist: true,
+        value: rootObject.object,
+      });
+    });
+
+    it("works with nested object properties", () => {
+      expect(cache.lookup(["object", "nestedObject"])).toEqual({
+        doesPathExist: true,
+        value: rootObject.object.nestedObject,
+      });
+
+      expect(cache.lookup(["nonExistent", "nonExistent"])).toEqual({
+        doesPathExist: false,
+        value: undefined,
+      });
+    });
+
+    it("works with nested array indices", () => {
+      expect(cache.lookup(["array", "0"])).toEqual({
+        doesPathExist: true,
+        value: rootObject.array[0],
+      });
+
+      expect(cache.lookup(["array", "1"])).toEqual({
+        doesPathExist: true,
+        value: rootObject.array[1],
+      });
+
+      expect(cache.lookup(["array", "2"])).toEqual({
+        doesPathExist: false,
+        value: undefined,
+      });
+
+      expect(cache.lookup(["array", "1", "nestedObject"])).toEqual({
+        doesPathExist: true,
+        value: rootObject.array[1].nestedObject,
+      });
+    });
+  });
+
+  describe("set()", () => {
+    it("overrides paths of the root object", () => {
+      cache.set(["object"], { nested: 1 });
+      expect(cache.lookup(["object", "nested"])).toEqual({
+        doesPathExist: true,
+        value: 1,
+      });
+
+      cache.set(["object", "nested"], 2);
+      expect(cache.lookup(["object", "nested"])).toEqual({
+        doesPathExist: true,
+        value: 2,
+      });
+
+      cache.set(["array"], [1]);
+      expect(cache.lookup(["array", "0"])).toEqual({ doesPathExist: true, value: 1 });
+    });
+  });
+
+  describe("reset()", () => {
+    it("deletes all set entries", () => {
+      cache.set(["object"], { nested: 1 });
+      expect(cache.lookup(["object", "nested"])).toEqual({
+        doesPathExist: true,
+        value: 1,
+      });
+
+      cache.reset();
+      expect(cache.lookup(["object", "nested"])).toEqual({
+        doesPathExist: false,
+        value: undefined,
+      });
+    });
+  });
+});

package/src/timeline/util.ts

@@ -0,0 +1,146 @@
+/**
+ * Maintains a promise and offers a function to resolve it. Whenever the promise is resolved, it is
+ * replaced with a new one.
+ */
+export class PromiseWrapper<ResolveType = void> {
+  constructor() {
+    this.reset();
+  }
+
+  private promise: Promise<ResolveType>;
+  private resolvePromise: (resolveValue: ResolveType) => void;
+
+  reset() {
+    this.promise = new Promise((resolve) => {
+      this.resolvePromise = resolve;
+    });
+  }
+  get() {
+    return this.promise;
+  }
+  resolve(value: ResolveType) {
+    this.resolvePromise(value);
+    this.reset();
+  }
+}
+
+export function isPromise(value: any): value is Promise<any> {
+  return value && typeof value["then"] === "function";
+}
+
+export function delay(ms: number) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Returns the string representation of a `path` array like accepted by lodash's `get` and `set`
+ * functions.
+ */
+export function parameterPathArrayToString([firstPathElement, ...remainingPathElements]: string[]) {
+  let pathString = firstPathElement ?? "";
+
+  for (const pathElement of remainingPathElements) {
+    pathString += Number.isNaN(Number.parseInt(pathElement))
+      ? `.${pathElement}`
+      : `[${pathElement}]`;
+  }
+
+  return pathString;
+}
+
+function isObjectOrArray(value: any): value is Record<string, any> | any[] {
+  return typeof value === "object" && value !== null;
+}
+
+type LookupResult = { doesPathExist: boolean; value?: any };
+
+/**
+ * Initialized with an object, provides a `lookup` method to look up nested object and array paths
+ * and a `set` method to override the element that `lookup` uses at a given path. The original
+ * object remains unmodified. All looked up values are cached, including those at intermediate
+ * paths. This means, `set`ting the element at a path only affects nested path lookups if the paths
+ * have not been looked up and cached before.
+ */
+export class ParameterObjectPathCache {
+  private static lookupChild(
+    objectOrArray: Record<string, any> | any[],
+    childName: string
+  ): LookupResult {
+    let doesPathExist: boolean = false;
+    let childValue: any;
+
+    if (Number.isNaN(Number.parseInt(childName))) {
+      // `childName` refers to an object property
+      if (Object.hasOwn(objectOrArray, childName)) {
+        doesPathExist = true;
+        childValue = objectOrArray[childName];
+      }
+    } else {
+      // `childName` refers to an array index
+      if (Number.parseInt(childName) < objectOrArray.length) {
+        doesPathExist = true;
+        childValue = objectOrArray[childName];
+      }
+    }
+
+    return { doesPathExist, value: childValue };
+  }
+
+  private cache = new Map<string, any>();
+  private rootObject: any;
+
+  private get(path: string[]) {
+    return this.cache.get(path.join("."));
+  }
+
+  private has(path: string[]) {
+    return this.cache.has(path.join("."));
+  }
+
+  constructor() {}
+
+  public initialize(rootObject: any) {
+    this.rootObject = rootObject;
+    this.cache.set("", rootObject);
+  }
+
+  public reset() {
+    this.cache.clear();
+    this.cache.set("", this.rootObject);
+  }
+
+  public set(path: string[], value: any) {
+    this.cache.set(path.join("."), value);
+  }
+
+  public lookup(path: string[]): LookupResult {
+    if (this.has(path)) {
+      return { doesPathExist: true, value: this.get(path) };
+    }
+
+    // Recursively find the closest ancestor path that has already been cached and start looking up
+    // the path from there, caching intermediate elements along the way
+    const lookupPath = (path: string[]): LookupResult => {
+      const parentPath = path.slice(0, -1);
+      const childName = path[path.length - 1];
+      if (!this.has(parentPath) && parentPath.length > 0) {
+        if (!lookupPath(parentPath).doesPathExist) {
+          return { doesPathExist: false };
+        }
+      }
+
+      const parentValue = this.get(parentPath);
+      if (!isObjectOrArray(parentValue)) {
+        return { doesPathExist: false };
+      }
+
+      const lookupResult = ParameterObjectPathCache.lookupChild(parentValue, childName);
+      if (lookupResult.doesPathExist) {
+        this.set(path, lookupResult.value);
+      }
+      return lookupResult;
+    };
+
+    return lookupPath(path);
+  }
+}

package/dist/JsPsych.d.ts

@@ -1,112 +0,0 @@
-import { JsPsychData } from "./modules/data";
-import { PluginAPI } from "./modules/plugin-api";
-import * as randomization from "./modules/randomization";
-import * as turk from "./modules/turk";
-import * as utils from "./modules/utils";
-export declare class JsPsych {
-    extensions: any;
-    turk: typeof turk;
-    randomization: typeof randomization;
-    utils: typeof utils;
-    data: JsPsychData;
-    pluginAPI: PluginAPI;
-    version(): any;
-    /**
-     * options
-     */
-    private opts;
-    /**
-     * experiment timeline
-     */
-    private timeline;
-    private timelineDescription;
-    private global_trial_index;
-    private current_trial;
-    private current_trial_finished;
-    private DOM_container;
-    private DOM_target;
-    /**
-     * time that the experiment began
-     */
-    private exp_start_time;
-    /**
-     * is the experiment paused?
-     */
-    private paused;
-    private waiting;
-    /**
-     * is the page retrieved directly via file:// protocol (true) or hosted on a server (false)?
-     */
-    private file_protocol;
-    /**
-     * Promise that is resolved when `finishExperiment()` is called
-     */
-    private finished;
-    private resolveFinishedPromise;
-    /**
-     * is the experiment running in `simulate()` mode
-     */
-    private simulation_mode;
-    /**
-     * simulation options passed in via `simulate()`
-     */
-    private simulation_options;
-    webaudio_context: AudioContext;
-    internal: {
-        /**
-         * this flag is used to determine whether we are in a scope where
-         * jsPsych.timelineVariable() should be executed immediately or
-         * whether it should return a function to access the variable later.
-         *
-         **/
-        call_immediate: boolean;
-    };
-    constructor(options?: any);
-    /**
-     * Starts an experiment using the provided timeline and returns a promise that is resolved when
-     * the experiment is finished.
-     *
-     * @param timeline The timeline to be run
-     */
-    run(timeline: any[]): Promise<void>;
-    simulate(timeline: any[], simulation_mode?: "data-only" | "visual", simulation_options?: {}): Promise<void>;
-    getProgress(): {
-        total_trials: number;
-        current_trial_global: number;
-        percent_complete: number;
-    };
-    getStartTime(): any;
-    getTotalTime(): number;
-    getDisplayElement(): HTMLElement;
-    getDisplayContainerElement(): HTMLElement;
-    finishTrial(data?: {}): void;
-    endExperiment(end_message?: string, data?: {}): void;
-    endCurrentTimeline(): void;
-    getCurrentTrial(): any;
-    getInitSettings(): any;
-    getCurrentTimelineNodeID(): any;
-    timelineVariable(varname: string, immediate?: boolean): any;
-    getAllTimelineVariables(): any;
-    addNodeToEndOfTimeline(new_timeline: any, preload_callback?: any): void;
-    pauseExperiment(): void;
-    resumeExperiment(): void;
-    loadFail(message: any): void;
-    getSafeModeStatus(): boolean;
-    getTimeline(): any[];
-    private prepareDom;
-    private loadExtensions;
-    private startExperiment;
-    private finishExperiment;
-    private nextTrial;
-    private doTrial;
-    private evaluateTimelineVariables;
-    private evaluateFunctionParameters;
-    private replaceFunctionsWithValues;
-    private setDefaultValues;
-    private checkExclusions;
-    private drawProgressBar;
-    private updateProgressBar;
-    private progress_bar_amount;
-    setProgressBar(proportion_complete: any): void;
-    getProgressBarCompleted(): number;
-}

package/dist/TimelineNode.d.ts

@@ -1,34 +0,0 @@
-import { JsPsych } from "./JsPsych";
-export declare class TimelineNode {
-    private jsPsych;
-    relative_id: any;
-    parent_node: any;
-    trial_parameters: any;
-    timeline_parameters: any;
-    node_trial_data: any;
-    progress: any;
-    end_message?: string;
-    constructor(jsPsych: JsPsych, parameters: any, parent?: any, relativeID?: any);
-    trial(): any;
-    markCurrentTrialComplete(): void;
-    nextRepetiton(): void;
-    setTimelineVariablesOrder(): void;
-    nextSet(): void;
-    advance(): any;
-    isComplete(): any;
-    getTimelineVariableValue(variable_name: string): any;
-    findTimelineVariable(variable_name: any): any;
-    timelineVariable(variable_name: string): any;
-    allTimelineVariables(): any;
-    allTimelineVariablesNames(so_far?: any[]): any;
-    length(): number;
-    percentComplete(): number;
-    reset(): void;
-    end(): void;
-    endActiveNode(): void;
-    ID(): string;
-    activeID(): any;
-    generatedData(): import("./modules/data/DataCollection").DataCollection;
-    trialsOfType(type: any): any;
-    insert(parameters: any): void;
-}

package/dist/migration.d.ts

@@ -1,3 +0,0 @@
-export declare class MigrationError extends Error {
-    constructor(message?: string);
-}

package/dist/modules/data/DataCollection.d.ts

@@ -1,46 +0,0 @@
-import { DataColumn } from "./DataColumn";
-export declare class DataCollection {
-    private trials;
-    constructor(data?: any[]);
-    push(new_data: any): this;
-    join(other_data_collection: DataCollection): this;
-    top(): DataCollection;
-    /**
-     * Queries the first n elements in a collection of trials.
-     *
-     * @param n A positive integer of elements to return. A value of
-     *          n that is less than 1 will throw an error.
-     *
-     * @return First n objects of a collection of trials. If fewer than
-     *         n trials are available, the trials.length elements will
-     *         be returned.
-     *
-     */
-    first(n?: number): DataCollection;
-    /**
-     * Queries the last n elements in a collection of trials.
-     *
-     * @param n A positive integer of elements to return. A value of
-     *          n that is less than 1 will throw an error.
-     *
-     * @return Last n objects of a collection of trials. If fewer than
-     *         n trials are available, the trials.length elements will
-     *         be returned.
-     *
-     */
-    last(n?: number): DataCollection;
-    values(): any[];
-    count(): number;
-    readOnly(): DataCollection;
-    addToAll(properties: any): this;
-    addToLast(properties: any): this;
-    filter(filters: any): DataCollection;
-    filterCustom(fn: any): DataCollection;
-    filterColumns(columns: Array<string>): DataCollection;
-    select(column: any): DataColumn;
-    ignore(columns: any): DataCollection;
-    uniqueNames(): any[];
-    csv(): string;
-    json(pretty?: boolean): string;
-    localSave(format: any, filename: any): void;
-}

package/dist/modules/data/DataColumn.d.ts

@@ -1,15 +0,0 @@
-export declare class DataColumn {
-    values: any[];
-    constructor(values?: any[]);
-    sum(): number;
-    mean(): number;
-    median(): any;
-    min(): any;
-    max(): any;
-    count(): number;
-    variance(): number;
-    sd(): number;
-    frequencies(): {};
-    all(eval_fn: any): boolean;
-    subset(eval_fn: any): DataColumn;
-}

package/dist/modules/data/index.d.ts

@@ -1,25 +0,0 @@
-import { JsPsych } from "../../JsPsych";
-import { DataCollection } from "./DataCollection";
-export declare class JsPsychData {
-    private jsPsych;
-    private allData;
-    private interactionData;
-    private dataProperties;
-    private query_string;
-    constructor(jsPsych: JsPsych);
-    reset(): void;
-    get(): DataCollection;
-    getInteractionData(): DataCollection;
-    write(data_object: any): void;
-    addProperties(properties: any): void;
-    addDataToLastTrial(data: any): void;
-    getDataByTimelineNode(node_id: any): DataCollection;
-    getLastTrialData(): DataCollection;
-    getLastTimelineData(): DataCollection;
-    displayData(format?: string): void;
-    urlVariables(): any;
-    getURLVariable(whichvar: any): any;
-    createInteractionListeners(): void;
-    _customInsert(data: any): void;
-    _fullreset(): void;
-}

package/dist/modules/data/utils.d.ts

@@ -1,3 +0,0 @@
-export declare function saveTextToFile(textstr: string, filename: string): void;
-export declare function JSON2CSV(objArray: any): string;
-export declare function getQueryString(): {};

package/dist/modules/extensions.d.ts

@@ -1,22 +0,0 @@
-export interface JsPsychExtensionInfo {
-    name: string;
-}
-export interface JsPsychExtension {
-    /**
-     * Called once at the start of the experiment to initialize the extension
-     */
-    initialize(params?: Record<string, any>): Promise<void>;
-    /**
-     * Called at the start of a trial, prior to invoking the plugin's trial method.
-     */
-    on_start(params?: Record<string, any>): void;
-    /**
-     * Called during a trial, after the plugin makes initial changes to the DOM.
-     */
-    on_load(params?: Record<string, any>): void;
-    /**
-     * Called at the end of the trial.
-     * @returns Data to append to the trial's data object.
-     */
-    on_finish(params?: Record<string, any>): Record<string, any> | Promise<Record<string, any>>;
-}

package/dist/modules/plugin-api/HardwareAPI.d.ts

@@ -1,15 +0,0 @@
-export declare class HardwareAPI {
-    /**
-     * Indicates whether this instance of jspsych has opened a hardware connection through our browser
-     * extension
-     **/
-    hardwareConnected: boolean;
-    constructor();
-    /**
-     * Allows communication with user hardware through our custom Google Chrome extension + native C++ program
-     * @param		mess	The message to be passed to our extension, see its documentation for the expected members of this object.
-     * @author	Daniel Rivas
-     *
-     */
-    hardware(mess: any): void;
-}

package/dist/modules/plugin-api/KeyboardListenerAPI.d.ts

@@ -1,34 +0,0 @@
-export declare type KeyboardListener = (e: KeyboardEvent) => void;
-export declare type ValidResponses = string[] | "ALL_KEYS" | "NO_KEYS";
-export interface GetKeyboardResponseOptions {
-    callback_function: any;
-    valid_responses?: ValidResponses;
-    rt_method?: "performance" | "audio";
-    persist?: boolean;
-    audio_context?: AudioContext;
-    audio_context_start_time?: number;
-    allow_held_key?: boolean;
-    minimum_valid_rt?: number;
-}
-export declare class KeyboardListenerAPI {
-    private getRootElement;
-    private areResponsesCaseSensitive;
-    private minimumValidRt;
-    constructor(getRootElement: () => Element | undefined, areResponsesCaseSensitive?: boolean, minimumValidRt?: number);
-    private listeners;
-    private heldKeys;
-    private areRootListenersRegistered;
-    /**
-     * If not previously done and `this.getRootElement()` returns an element, adds the root key
-     * listeners to that element.
-     */
-    private registerRootListeners;
-    private rootKeydownListener;
-    private toLowerCaseIfInsensitive;
-    private rootKeyupListener;
-    private isResponseValid;
-    getKeyboardResponse({ callback_function, valid_responses, rt_method, persist, audio_context, audio_context_start_time, allow_held_key, minimum_valid_rt, }: GetKeyboardResponseOptions): KeyboardListener;
-    cancelKeyboardResponse(listener: KeyboardListener): void;
-    cancelAllKeyboardResponses(): void;
-    compareKeys(key1: string | null, key2: string | null): boolean;
-}

package/dist/modules/plugin-api/MediaAPI.d.ts

@@ -1,32 +0,0 @@
-export declare class MediaAPI {
-    private useWebaudio;
-    private webaudioContext?;
-    constructor(useWebaudio: boolean, webaudioContext?: AudioContext);
-    private video_buffers;
-    getVideoBuffer(videoID: string): any;
-    private context;
-    private audio_buffers;
-    initAudio(): void;
-    audioContext(): any;
-    getAudioBuffer(audioID: any): Promise<unknown>;
-    private preload_requests;
-    private img_cache;
-    preloadAudio(files: any, callback_complete?: () => void, callback_load?: (filepath: any) => void, callback_error?: (error_msg: any) => void): void;
-    preloadImages(images: any, callback_complete?: () => void, callback_load?: (filepath: any) => void, callback_error?: (error_msg: any) => void): void;
-    preloadVideo(videos: any, callback_complete?: () => void, callback_load?: (filepath: any) => void, callback_error?: (error_msg: any) => void): void;
-    private preloadMap;
-    getAutoPreloadList(timeline_description: any[]): {
-        images: string[];
-        audio: string[];
-        video: string[];
-    };
-    cancelPreloads(): void;
-    private microphone_recorder;
-    initializeMicrophoneRecorder(stream: MediaStream): void;
-    getMicrophoneRecorder(): MediaRecorder;
-    private camera_stream;
-    private camera_recorder;
-    initializeCameraRecorder(stream: MediaStream, opts?: MediaRecorderOptions): void;
-    getCameraStream(): MediaStream;
-    getCameraRecorder(): MediaRecorder;
-}

package/dist/modules/plugin-api/SimulationAPI.d.ts

@@ -1,44 +0,0 @@
-export declare class SimulationAPI {
-    private getDisplayContainerElement;
-    private setJsPsychTimeout;
-    constructor(getDisplayContainerElement: () => HTMLElement, setJsPsychTimeout: (callback: () => void, delay: number) => number);
-    dispatchEvent(event: Event): void;
-    /**
-     * Dispatches a `keydown` event for the specified key
-     * @param key Character code (`.key` property) for the key to press.
-     */
-    keyDown(key: string): void;
-    /**
-     * Dispatches a `keyup` event for the specified key
-     * @param key Character code (`.key` property) for the key to press.
-     */
-    keyUp(key: string): void;
-    /**
-     * Dispatches a `keydown` and `keyup` event in sequence to simulate pressing a key.
-     * @param key Character code (`.key` property) for the key to press.
-     * @param delay Length of time to wait (ms) before executing action
-     */
-    pressKey(key: string, delay?: number): void;
-    /**
-     * Dispatches `mousedown`, `mouseup`, and `click` events on the target element
-     * @param target The element to click
-     * @param delay Length of time to wait (ms) before executing action
-     */
-    clickTarget(target: Element, delay?: number): void;
-    /**
-     * Sets the value of a target text input
-     * @param target A text input element to fill in
-     * @param text Text to input
-     * @param delay Length of time to wait (ms) before executing action
-     */
-    fillTextInput(target: HTMLInputElement, text: string, delay?: number): void;
-    /**
-     * Picks a valid key from `choices`, taking into account jsPsych-specific
-     * identifiers like "NO_KEYS" and "ALL_KEYS".
-     * @param choices Which keys are valid.
-     * @returns A key selected at random from the valid keys.
-     */
-    getValidKey(choices: "NO_KEYS" | "ALL_KEYS" | Array<string> | Array<Array<string>>): any;
-    mergeSimulationData(default_data: any, simulation_options: any): any;
-    ensureSimulationDataConsistency(trial: any, data: any): void;
-}

package/dist/modules/plugin-api/TimeoutAPI.d.ts

@@ -1,17 +0,0 @@
-/**
- * A class that provides a wrapper around the global setTimeout and clearTimeout functions.
- */
-export declare class TimeoutAPI {
-    private timeout_handlers;
-    /**
-     * Calls a function after a specified delay, in milliseconds.
-     * @param callback The function to call after the delay.
-     * @param delay The number of milliseconds to wait before calling the function.
-     * @returns A handle that can be used to clear the timeout with clearTimeout.
-     */
-    setTimeout(callback: () => void, delay: number): number;
-    /**
-     * Clears all timeouts that have been created with setTimeout.
-     */
-    clearAllTimeouts(): void;
-}