Complex objects as parameter types to plugins

[awebb-nz]

Hi there, I am just getting started writing new plugins for a jspsych-based experiment. I have run into some behaviour that I find a bit strange, and I just want to check whether it is the intended behaviour or not. Specifically, I want to pass an object parameter, so I have the following in my plugin javascript file:

parameters: {
      ...
      grid_state: {
        type: jspsych.ParameterType.OBJECT,
        default: undefined,
      },
      ...

and I pass an instance of the object in:

var grid = new Grid(initialState);
var gpt = {
        type: jsGridPlugin,
        ...
        grid_state: grid
};
timeline.push(gpt);

However, when I try to call a method on the trial.grid_state object in my plugin code, I get an Uncaught TypeError, which tells me the function doesn't exist (if I call the function from outside the plugin, it works fine).
So, this suggests to me that the object that given as a parameter is not actually passed in to the plugin, but instead a copy of the public fields of the object are passed in. Is that the intended behaviour, and if so is there any way to pass in a more complex object?
I realise I can decompose the object into individual fields, and move the functionality into the plugin code itself, and I will do that if I have to. Thanks!

[awebb-nz]

Playing more, it seems that the complex (nested) objects are usable, as long as all the fields are public fields (i.e., not prefixed with a #.

No methods on objects seem to be available, however.

[jodeleeuw]

Hey @awebb-nz,

I suspect what might be happening is that function is being treated as a dynamic parameter. It is therefore evaluated at the onset of the trial.

To block this behavior, you can note the expected type of the nested parameter as a function, and then jsPsych should leave it alone.

Here's an example of a nested parameter type in the survey-text plugin:

jsPsych/packages/plugin-survey-text/src/index.ts

Lines 6 to 49 in 8099b3f

	questions: {
	type: ParameterType.COMPLEX,
	array: true,
	pretty_name: "Questions",
	default: undefined,
	nested: {
	/** Question prompt. */
	prompt: {
	type: ParameterType.HTML_STRING,
	pretty_name: "Prompt",
	default: undefined,
	},
	/** Placeholder text in the response text box. */
	placeholder: {
	type: ParameterType.STRING,
	pretty_name: "Placeholder",
	default: "",
	},
	/** The number of rows for the response text box. */
	rows: {
	type: ParameterType.INT,
	pretty_name: "Rows",
	default: 1,
	},
	/** The number of columns for the response text box. */
	columns: {
	type: ParameterType.INT,
	pretty_name: "Columns",
	default: 40,
	},
	/** Whether or not a response to this question must be given in order to continue. */
	required: {
	type: ParameterType.BOOL,
	pretty_name: "Required",
	default: false,
	},
	/** Name of the question in the trial data. If no name is given, the questions are named Q0, Q1, etc. */
	name: {
	type: ParameterType.STRING,
	pretty_name: "Question Name",
	default: "",
	},
	},
	},

And here's an example of using a function type on a parameter:

jsPsych/packages/plugin-call-function/src/index.ts

Lines 5 to 11 in 8099b3f

	parameters: {
	/** Function to call */
	func: {
	type: ParameterType.FUNCTION,
	pretty_name: "Function",
	default: undefined,
	},

[awebb-nz]

Hi @jodeleeuw, thanks for your reply!

I think we are talking about slightly different things, so I will elaborate a bit. As I mentioned in my first message, what I am describing as surprising behaviour might just be the intended behaviour, and I may have to realign my thinking. In any case, here goes:

I have a class which defines a Grid, which contains a map of coordinates to Cells, each of which contain some state. The Grid and Cell classes contain methods for getting and updating the values in the cells. E.g.,:

class Cell {
    ...
    get current() {
        return ...
    }
}

class Grid {

    constructor(state) {
        this.cells = new Map();
        ... //fill in the map using the initial state
    }
    
    current(row, col) {
        return this.cells[[row, col]].current
    }
}

The idea is to have the slightly complex behaviour encapsulated. I pass a Grid object as a parameter to a plugin where the parameter type is jspsych.ParameterType.OBJECT or jspsych.ParameterType.FUNCTION, like so:

    var grid = new Grid(state);
    var mcg = {
        type: jsMulticlickGrid,
        clicks: 5,
        grid_state: grid
    };
    timeline.push(mcg);

If I run the following code outside of the plugin it works, and it gives me the types and values I expect:

console.log(grid);
console.log(grid.current(1, 1));

So, it knows that grid.cells is a Map of Cells, and it has the current method as part of the object prototype. However, if I run (what is basically) the same code inside the plugin, I get an error on the second line, complaining that the method current doesn't exist.

console.log(trial.grid_state);
console.log(trial.grid_state.current(1, 1));

When I look at the logged object I can see that, although it can still access the direct fields of the object, it has lost all type information, so that trial.grid_state.cells is just a generic object, and the trial.grid_state object has only the default object prototype (and therefore no method bindings).

As mentioned, I can work around this, but I am just wondering if that is the expected behaviour.

---

I noticed while playing with it, that I can work around in a sort of OK way, by changing the methods to be defined as function fields on the object, rather than methods on the prototype, as follows:

class Grid {
    ...
    current = (row, col) => {
        return this.cells[[row, col]].current()
    }
}

and then it works as I expected it to.

Thanks for your help!

[jodeleeuw]

Thanks for clarifying. I think what's happening here is that the parameters for a trial are cloned...

jsPsych/packages/jspsych/src/TimelineNode.ts

Line 119 in 6e8af3e

return deepCopy(this.trial_parameters);

... through a method that isn't aware of classes...

jsPsych/packages/jspsych/src/modules/utils.ts

Lines 10 to 30 in 6e8af3e

	export function deepCopy(obj) {
	if (!obj) return obj;
	let out;
	if (Array.isArray(obj)) {
	out = [];
	for (const x of obj) {
	out.push(deepCopy(x));
	}
	return out;
	} else if (typeof obj === "object" && obj !== null) {
	out = {};
	for (const key in obj) {
	if (obj.hasOwnProperty(key)) {
	out[key] = deepCopy(obj[key]);
	}
	}
	return out;
	} else {
	return obj;
	}
	}

... producing a generic object.

The cloning is intended behavior, but it would be nice to support this use case. I'm open to ideas about how we could make that work.

[awebb-nz]

That makes perfect sense, and explains what I am seeing. From my point of view (which, admittedly, is very limited in terms of experience with jspsych) it seems like there could be also (using a different parameter type) the "opposite" case where the object is passed into the plugin (or shallow-copied) which would mean that type information is preserved, but that it was up to the user to deal with the repercussions of the fact that mutating the object in the plugin would mutate it everywhere.

I would entirely unsurprised if you had already considered this idea and discarded it, though.

Thanks again for the clarification and the help!