HoshinoKoji/jsPsych
1
0
Fork 0
mirror of https://github.com/jspsych/jsPsych.git synced 2025-05-10 11:10:54 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Use enum for parameter types and remove JsPsych.plugins

Browse Source 
`const parameterType` is now `enum ParameterType` and can only be
accessed by importing it.
This commit is contained in:
bjoluc 2021-08-17 17:19:25 +02:00
parent 743ad44e84
commit 9c519853fe
8 changed files with 88 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/overview/dynamic-parameters.md
View File

@ -142,6 +142,6 @@ var trial = {
```
## When dynamic parameters can't be used
Note that if the plugin *expects* the value of a given parameter to be a function, then this function *will not* be evaluated at the start of the trial. This is because some plugins allow the researcher to specify functions that should be called at some point during the trial. Some examples of this include the `stimulus` parameter in the canvas-* plugins, the `mistake_fn` parameter in the cloze plugin, and the `stim_function` parameter in the reconstruction plugin. If you want to check whether this is the case for a particular plugin and parameter, then the parameter's `type` in the `plugin.info` section of the plugin file. If the parameter type is `jsPsych.plugins.parameterType.FUNCTION`, then this parameter must be a function and it will not be executed before the trial starts.
Note that if the plugin *expects* the value of a given parameter to be a function, then this function *will not* be evaluated at the start of the trial. This is because some plugins allow the researcher to specify functions that should be called at some point during the trial. Some examples of this include the `stimulus` parameter in the canvas-* plugins, the `mistake_fn` parameter in the cloze plugin, and the `stim_function` parameter in the reconstruction plugin. If you want to check whether this is the case for a particular plugin and parameter, then the parameter's `type` in the `plugin.info` section of the plugin file. If the parameter type is `ParameterType.FUNCTION`, then this parameter must be a function and it will not be executed before the trial starts.
Even though function evaluation doesn't work the same way with these parameters, the fact that the parameters are functions means that you can get the same dynamic functionality. These functions are typically evaluated at some point during the trial, so you still get updates to values within the function during the trial.

13
packages/jspsych/src/JsPsych.ts
View File

@ -3,7 +3,7 @@ import autoBind from "auto-bind";
import { version } from "../package.json";
import { JsPsychData } from "./modules/data";
import { PluginAPI, createJointPluginAPIObject } from "./modules/plugin-api";
import * as plugins from "./modules/plugins";
import { ParameterType, universalPluginParameters } from "./modules/plugins";
import * as randomization from "./modules/randomization";
import * as turk from "./modules/turk";
import * as utils from "./modules/utils";
@ -15,7 +15,6 @@ function delay(ms: number) {
export class JsPsych {
extensions = <any>{};
plugins = plugins;
turk = turk;
randomization = randomization;
utils = utils;
@ -610,14 +609,14 @@ export class JsPsych {
// the first line checks if the parameter is defined in the universalPluginParameters set
// the second line checks the plugin-specific parameters
if (
typeof this.plugins.universalPluginParameters[key] !== "undefined" &&
this.plugins.universalPluginParameters[key].type !== this.plugins.parameterType.FUNCTION
typeof universalPluginParameters[key] !== "undefined" &&
universalPluginParameters[key].type !== ParameterType.FUNCTION
) {
trial[key] = this.replaceFunctionsWithValues(trial[key], null);
}
if (
typeof trial.type.info.parameters[key] !== "undefined" &&
trial.type.info.parameters[key].type !== this.plugins.parameterType.FUNCTION
trial.type.info.parameters[key].type !== ParameterType.FUNCTION
) {
trial[key] = this.replaceFunctionsWithValues(trial[key], trial.type.info.parameters[key]);
}
@ -654,7 +653,7 @@ export class JsPsych {
for (var i = 0; i < keys.length; i++) {
if (
typeof info.nested[keys[i]] == "object" &&
info.nested[keys[i]].type !== this.plugins.parameterType.FUNCTION
info.nested[keys[i]].type !== ParameterType.FUNCTION
) {
obj[keys[i]] = this.replaceFunctionsWithValues(obj[keys[i]], info.nested[keys[i]]);
}
@ -669,7 +668,7 @@ export class JsPsych {
private setDefaultValues(trial) {
for (var param in trial.type.info.parameters) {
// check if parameter is complex with nested defaults
if (trial.type.info.parameters[param].type == this.plugins.parameterType.COMPLEX) {
if (trial.type.info.parameters[param].type == ParameterType.COMPLEX) {
if (trial.type.info.parameters[param].array == true) {
// iterate over each entry in the array
trial[param].forEach(function (ip, i) {

8
packages/jspsych/src/TimelineNode.ts
View File

@ -1,5 +1,5 @@
import { JsPsych } from "./JsPsych";
import { parameterType } from "./modules/plugins";
import { ParameterType } from "./modules/plugins";
import {
repeat,
sampleWithReplacement,
@ -546,9 +546,9 @@ export class TimelineNode {
/** Maps parameter types to their corresponding preload type */
const parameterTypeMap = new Map<number, PreloadType>([
[parameterType.AUDIO, "audio"],
[parameterType.IMAGE, "image"],
[parameterType.VIDEO, "video"],
[ParameterType.AUDIO, "audio"],
[ParameterType.IMAGE, "image"],
[ParameterType.VIDEO, "video"],
]);
function recurseTimeline(node: TimelineNode) {

10
packages/jspsych/src/index.ts
View File

@ -24,5 +24,11 @@ export function initJsPsych(options?) {
}
export { JsPsych } from "./JsPsych";
export { JsPsychPlugin, PluginInfo, TrialType } from "./modules/plugins";
export { parameterType } from "./modules/plugins";
export {
JsPsychPlugin,
PluginInfo,
TrialType,
ParameterType,
universalPluginParameters,
UniversalPluginParameters,
} from "./modules/plugins";

88
packages/jspsych/src/modules/plugins.ts
View File

@ -12,45 +12,47 @@ type SetRequired<BaseType, Keys extends keyof BaseType> = Simplify<
Omit<BaseType, Keys> & Required<Pick<BaseType, Keys>>
>;
// enumerate possible parameter types for plugins
export const parameterType = <const>{
BOOL: 0,
STRING: 1,
INT: 2,
FLOAT: 3,
FUNCTION: 4,
KEY: 5,
KEYS: 6,
SELECT: 7,
HTML_STRING: 8,
IMAGE: 9,
AUDIO: 10,
VIDEO: 11,
OBJECT: 12,
COMPLEX: 13,
TIMELINE: 14,
};
/**
* Parameter types for plugins
*/
export enum ParameterType {
BOOL,
STRING,
INT,
FLOAT,
FUNCTION,
KEY,
KEYS,
SELECT,
HTML_STRING,
IMAGE,
AUDIO,
VIDEO,
OBJECT,
COMPLEX,
TIMELINE,
}
type ParameterTypeMap = {
0: boolean; // BOOL
1: string; // STRING
2: number; // INT
3: number; // FLOAT
4: (...args: any[]) => any; // FUNCTION
5: string; // KEY
6: string[] | "ALL_KEYS" | "NO_KEYS"; // KEYS
7: any; // SELECT
8: string; // HTML_STRING
9: string; // IMAGE
10: string; // AUDIO
11: string; // VIDEO
12: object; // OBJECT
13: any; // COMPLEX
14: any; // TIMELINE
[ParameterType.BOOL]: boolean;
[ParameterType.STRING]: string;
[ParameterType.INT]: number;
[ParameterType.FLOAT]: number;
[ParameterType.FUNCTION]: (...args: any[]) => any;
[ParameterType.KEY]: string;
[ParameterType.KEYS]: string[] | "ALL_KEYS" | "NO_KEYS";
[ParameterType.SELECT]: any;
[ParameterType.HTML_STRING]: string;
[ParameterType.IMAGE]: string;
[ParameterType.AUDIO]: string;
[ParameterType.VIDEO]: string;
[ParameterType.OBJECT]: object;
[ParameterType.COMPLEX]: any;
[ParameterType.TIMELINE]: any;
};
export interface ParameterInfo {
type: keyof ParameterTypeMap;
type: ParameterType;
array?: boolean;
pretty_name?: string;
default?: any;
@ -61,7 +63,7 @@ export interface ParameterInfos {
[key: string]: ParameterInfo;
}
type ParameterType<I extends ParameterInfo> = I["array"] extends true
type InferredParameter<I extends ParameterInfo> = I["array"] extends true
? Array<ParameterTypeMap[I["type"]]>
: ParameterTypeMap[I["type"]];
@ -71,17 +73,17 @@ type RequiredParameterNames<I extends ParameterInfos> = {
type InferredParameters<I extends ParameterInfos> = SetRequired<
{
[Property in keyof I]?: ParameterType<I[Property]>;
[Property in keyof I]?: InferredParameter<I[Property]>;
},
RequiredParameterNames<I>
>;
export const universalPluginParameters: ParameterInfos = {
export const universalPluginParameters = <const>{
/**
* Data to add to this trial (key-value pairs)
*/
data: {
type: parameterType.OBJECT,
type: ParameterType.OBJECT,
pretty_name: "Data",
default: {},
},
@ -89,7 +91,7 @@ export const universalPluginParameters: ParameterInfos = {
* Function to execute when trial begins
*/
on_start: {
type: parameterType.FUNCTION,
type: ParameterType.FUNCTION,
pretty_name: "On start",
default: function () {
return;
@ -99,7 +101,7 @@ export const universalPluginParameters: ParameterInfos = {
* Function to execute when trial is finished
*/
on_finish: {
type: parameterType.FUNCTION,
type: ParameterType.FUNCTION,
pretty_name: "On finish",
default: function () {
return;
@ -109,7 +111,7 @@ export const universalPluginParameters: ParameterInfos = {
* Function to execute after the trial has loaded
*/
on_load: {
type: parameterType.FUNCTION,
type: ParameterType.FUNCTION,
pretty_name: "On load",
default: function () {
return;
@ -119,7 +121,7 @@ export const universalPluginParameters: ParameterInfos = {
* Length of gap between the end of this trial and the start of the next trial
*/
post_trial_gap: {
type: parameterType.INT,
type: ParameterType.INT,
pretty_name: "Post trial gap",
default: null,
},
@ -127,7 +129,7 @@ export const universalPluginParameters: ParameterInfos = {
* A list of CSS classes to add to the jsPsych display element for the duration of this trial
*/
css_classes: {
type: parameterType.STRING,
type: ParameterType.STRING,
pretty_name: "Custom CSS classes",
default: null,
},

12
packages/jspsych/tests/core/functions-as-parameters.test.ts
View File

@ -1,7 +1,7 @@
// import cloze from "@jspsych/plugin-cloze";
import htmlKeyboardResponse from "@jspsych/plugin-html-keyboard-response";
import { JsPsych, JsPsychPlugin, TrialType, parameterType } from "../../src";
import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from "../../src";
import { clickTarget, pressKey, startTimeline } from "../utils";
// import surveyMultiChoice from "@jspsych/plugin-survey-multi-choice";
@ -20,7 +20,7 @@ describe("standard use of function as parameter", () => {
pressKey("a");
});
test.skip("parameters can be protected from early evaluation using jsPsych.plugins.parameterType.FUNCTION", async () => {
test.skip("parameters can be protected from early evaluation using ParameterType.FUNCTION", async () => {
var mock = jest.fn();
await startTimeline([
@ -142,22 +142,22 @@ describe("nested parameters as functions", () => {
await expectFinished();
});
test("nested parameters can be protected from early evaluation using jsPsych.plugins.parameterType.FUNCTION", async () => {
test("nested parameters can be protected from early evaluation using ParameterType.FUNCTION", async () => {
// currently no plugins that use this feature (Jan. 2021), so here's a simple placeholder plugin.
const info = <const>{
name: "function-test-plugin",
parameters: {
foo: {
type: parameterType.COMPLEX,
type: ParameterType.COMPLEX,
default: null,
nested: {
not_protected: {
type: parameterType.STRING,
type: ParameterType.STRING,
default: null,
},
protected: {
type: parameterType.FUNCTION,
type: ParameterType.FUNCTION,
default: null,
},
},

22
packages/jspsych/tests/core/timelines.test.ts
View File

@ -1,6 +1,6 @@
import htmlKeyboardResponse from "@jspsych/plugin-html-keyboard-response";
import { initJsPsych, parameterType } from "../../src";
import { ParameterType, initJsPsych } from "../../src";
import { TimelineNode } from "../../src/TimelineNode";
import { pressKey, startTimeline } from "../utils";
@ -520,13 +520,13 @@ describe("TimelineNode", () => {
info: {
name: "my-plugin",
parameters: {
one: { type: parameterType.IMAGE },
two: { type: parameterType.VIDEO },
three: { type: parameterType.AUDIO },
four: { type: parameterType.IMAGE, preload: true },
five: { type: parameterType.IMAGE, preload: false },
one: { type: ParameterType.IMAGE },
two: { type: ParameterType.VIDEO },
three: { type: ParameterType.AUDIO },
four: { type: ParameterType.IMAGE, preload: true },
five: { type: ParameterType.IMAGE, preload: false },
six: {
type: parameterType.STRING,
type: ParameterType.STRING,
// This is illegal! But it should still not be added
preload: true,
},
@ -551,7 +551,7 @@ describe("TimelineNode", () => {
type: {
info: {
name: "plugin1",
parameters: { one: { type: parameterType.STRING } },
parameters: { one: { type: ParameterType.STRING } },
},
},
},
@ -559,7 +559,7 @@ describe("TimelineNode", () => {
type: {
info: {
name: "plugin2",
parameters: { one: { type: parameterType.AUDIO } },
parameters: { one: { type: ParameterType.AUDIO } },
},
},
},
@ -570,8 +570,8 @@ describe("TimelineNode", () => {
info: {
name: "plugin3",
parameters: {
one: { type: parameterType.VIDEO },
two: { type: parameterType.IMAGE },
one: { type: ParameterType.VIDEO },
two: { type: ParameterType.IMAGE },
},
},
},

14
packages/plugin-html-keyboard-response/src/index.ts
View File

@ -1,4 +1,4 @@
import { JsPsych, JsPsychPlugin, TrialType, parameterType } from "jspsych";
import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from "jspsych";
const info = <const>{
name: "html-keyboard-response",
@ -7,7 +7,7 @@ const info = <const>{
* The HTML string to be displayed
*/
stimulus: {
type: parameterType.HTML_STRING,
type: ParameterType.HTML_STRING,
pretty_name: "Stimulus",
default: undefined,
},
@ -15,7 +15,7 @@ const info = <const>{
* The keys the subject is allowed to press to respond to the stimulus.
*/
choices: {
type: parameterType.KEY,
type: ParameterType.KEY,
array: true,
pretty_name: "Choices",
default: "ALL_KEYS",
@ -24,7 +24,7 @@ const info = <const>{
* Any content here will be displayed below the stimulus.
*/
prompt: {
type: parameterType.STRING,
type: ParameterType.STRING,
pretty_name: "Prompt",
default: null,
},
@ -32,7 +32,7 @@ const info = <const>{
* How long to hide the stimulus.
*/
stimulus_duration: {
type: parameterType.INT,
type: ParameterType.INT,
pretty_name: "Stimulus duration",
default: null,
},
@ -40,7 +40,7 @@ const info = <const>{
* How long to show trial before it ends.
*/
trial_duration: {
type: parameterType.INT,
type: ParameterType.INT,
pretty_name: "Trial duration",
default: null,
},
@ -48,7 +48,7 @@ const info = <const>{
* If true, trial will end when subject makes a response.
*/
response_ends_trial: {
type: parameterType.BOOL,
type: ParameterType.BOOL,
pretty_name: "Response ends trial",
default: true,
},