Shelf - PsychoJS API

Constructor

new Shelf(options)

Source:

data/Shelf.js, line 23

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Attributes	Default	Description
`psychoJS`	module:core.PsychoJS			the PsychoJS instance
`autoLog`	boolean	<optional>	`false`	whether to log

Extends

PsychObject

Members

(static, readonly) Status :Symbol

Source:

data/Shelf.js, line 803

Properties:

Name	Type	Description
`READY`	Symbol	The shelf is ready.
`BUSY`	Symbol	The shelf is busy, e.g. storing or retrieving values.
`ERROR`	Symbol	The shelf has encountered an error.

Shelf status

Type:

Symbol

(static, readonly) Type :Symbol

Source:

data/Shelf.js, line 826

Properties:

Name	Type	Description
`INTEGER`	Symbol
`TEXT`	Symbol
`DICTIONARY`	Symbol
`BOOLEAN`	Symbol
`LIST`	Symbol

Shelf record types.

Type:

Symbol

Methods

_checkAvailability(methodNameopt)

Source:

data/Shelf.js, line 729

Check whether it is possible to run a given shelf command.

Since all Shelf methods call _checkAvailability, we also use it as a means to throttle those calls.

Parameters:

Name	Type	Attributes	Default	Description
`methodName`	string	<optional>	`""`	name of the method requiring a check

Throws:

exception if it is not possible to run the given shelf command
Type Object.<string, *>

_checkKey(key)

Source:

data/Shelf.js, line 779

Check the validity of the key.

Parameters:

Name	Type	Description
`key`	object	key whose validity is to be checked

Throws:

exception if the key is invalid
Type Object.<string, *>

(async) _getValue(key, type, optionsopt) → {Promise.<any>}

Source:

data/Shelf.js, line 659

Get the value associated with the given key.

This is a generic method, typically called from the Shelf helper methods, e.g. getBinaryValue.

Parameters:

Name	Type	Attributes	Description
`key`	Array.<string>		key as an array of key components
`type`	Shelf.Type		the type of the record associated with the given key
`options`	Object	<optional>	the options, e.g. the default value returned if no record with the given key exists on the shelf

Throws:

exception if there is a record associated with the given key but it is not of the given type
Type Object.<string, *>

Returns:

the value

Type: Promise.<any>

(async) _updateValue(key, type, update) → {Promise.<any>}

Source:

data/Shelf.js, line 593

Update the value associated with the given key.

This is a generic method, typically called from the Shelf helper methods, e.g. setBinaryValue.

Parameters:

Name	Type	Description
`key`	Array.<string>	key as an array of key components
`type`	Shelf.Type	the type of the record associated with the given key
`update`	*	the desired update

Throws:

exception if there is no record associated with the given key or if there is one but it is not of the given type
Type Object.<string, *>

Returns:

the updated value

Type: Promise.<any>

addIntegerValue(options) → {Promise.<number>}

Source:

data/Shelf.js, line 174

Add a delta to the value of a record of type INTEGER associated with the given key.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Description
`key`	Array.<string>	key as an array of key components
`delta`	number	the delta, positive or negative, to add to the value

Throws:

exception if delta is not an integer, or if there is no record with the given key, or if there is a record but it is locked or it is not of type INTEGER
Type Object.<string, *>

Returns:

the new value

Type: Promise.<number>

appendListValue(options) → {Promise.<Array.<*>>}

Source:

data/Shelf.js, line 296

Append an element, or a list of elements, to the value of a record of type LIST associated with the given key.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Description
`key`	Array.<string>	key as an array of key components
`elements`	*	the element or list of elements to be appended

Throws:

exception if there is no record with the given key, or if there is a record but it is locked or it is not of type LIST
Type Object.<string, *>

Returns:

the new value

Type: Promise.<Array.<*>>

clearListValue(options) → {Promise.<Array.<*>>}

Source:

data/Shelf.js, line 336

Empty the value of a record of type LIST associated with the given key.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Description
`key`	Array.<string>	key as an array of key components

Throws:

exception if there is no record with the given key, or if there is a record but it is locked or it is not of type LIST
Type Object.<string, *>

Returns:

the new, empty value, i.e. []

Type: Promise.<Array.<*>>

(async) counterBalanceSelect(options) → {Promise.<{string, boolean}>}

Source:

data/Shelf.js, line 524

Get the name of a group, using a counterbalanced design.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Description
`key`	Array.<string>	key as an array of key components
`groups`	Array.<string>	the names of the groups
`groupSizes`	Array.<number>	the size of the groups

Returns:

an object with the name of the selected group and whether all groups have been depleted

Type: Promise.<{string, boolean}>

flipBooleanValue(options) → {Promise.<boolean>}

Source:

data/Shelf.js, line 109

Flip the value of a record of type BOOLEAN associated with the given key.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Description
`key`	Array.<string>	key as an array of key components

Throws:

exception if there is no record with the given key, or if there is a record but it is not of type BOOLEAN
Type Object.<string, *>

Returns:

the new, flipped, value

Type: Promise.<boolean>

getBooleanValue(options) → {Promise.<boolean>}

Source:

data/Shelf.js, line 65

Get the value of a record of type BOOLEAN associated with the given key.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Description
`key`	Array.<string>	key as an array of key components
`defaultValue`	boolean	the default value returned if no record with the given key exists on the shelf

Throws:

exception if there is a record associated with the given key but it is not of type BOOLEAN
Type Object.<string, *>

Returns:

the value associated with the key

Type: Promise.<boolean>

(async) getDictionaryFieldNames(options) → {Promise.<Array.<string>>}

Source:

data/Shelf.js, line 373

Get the names of the fields in the dictionary record associated with the given key.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Description
`key`	Array.<string>	key as an array of key components

Throws:

exception if there is no record with the given key, or if there is a record but it is locked or it is not of type DICTIONARY
Type Object.<string, *>

Returns:

the list of field names

Type: Promise.<Array.<string>>

(async) getDictionaryFieldValue(options) → {Promise.<*>}

Source:

data/Shelf.js, line 390

Get the value of a given field in the dictionary record associated with the given key.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Description
`key`	Array.<string>	key as an array of key components
`fieldName`	string	the name of the field
`defaultValue`	boolean	the default value returned if no record with the given key exists on the shelf, or if is a record of type DICTIONARY with the given key but it has no such field

Throws:

exception if there is no record with the given key, or if there is a record but it is locked or it is not of type DICTIONARY
Type Object.<string, *>

Returns:

the value of that field

Type: Promise.<*>

getDictionaryValue(options) → {Promise.<Object.<string, *>>}

Source:

data/Shelf.js, line 428

Get the value of a record of type DICTIONARY associated with the given key.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Description
`key`	Array.<string>	key as an array of key components
`defaultValue`	Object.<string, *>	the default value returned if no record with the given key exists on the shelf

Throws:

exception if there is no record with the given key, or if there is a record but it is locked or it is not of type DICTIONARY
Type Object.<string, *>

Returns:

the value associated with the key

Type: Promise.<Object.<string, *>>

getIntegerValue(options) → {Promise.<number>}

Source:

data/Shelf.js, line 129

Get the value of a record of type INTEGER associated with the given key.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Description
`key`	Array.<string>	key as an array of key components
`defaultValue`	number	the default value returned if no record with the given key exists on the shelf

Throws:

exception if there is no record with the given key, or if there is a record but it is locked or it is not of type BOOLEAN
Type Object.<string, *>

Returns:

the value associated with the key

Type: Promise.<number>

getListValue(options) → {Promise.<Array.<*>>}

Source:

data/Shelf.js, line 251

Get the value of a record of type LIST associated with the given key.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Description
`key`	Array.<string>	key as an array of key components
`defaultValue`	Array.<*>	the default value returned if no record with the given key exists on the shelf

Throws:

exception if there is no record with the given key, or if there is a record but it is locked or it is not of type LIST
Type Object.<string, *>

Returns:

the value associated with the key

Type: Promise.<Array.<*>>

getTextValue(options) → {Promise.<string>}

Source:

data/Shelf.js, line 205

Get the value of a record of type TEXT associated with the given key.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Description
`key`	Array.<string>	key as an array of key components
`defaultValue`	string	the default value returned if no record with the given key exists on the shelf

Throws:

exception if there is a record associated with the given key but it is not of type TEXT
Type Object.<string, *>

Returns:

the value associated with the key

Type: Promise.<string>

incrementComponent(key, increment, callback) → {function}

Source:

data/Shelf.js, line 477

Schedulable component that will block the experiment until the counter associated with the given key has been incremented by the given amount.

Example

const flowScheduler = new Scheduler(psychoJS);
var experimentCounter = '<>';
flowScheduler.add(psychoJS.shelf.incrementComponent(['counter'], 1, (value) => experimentCounter = value));

Parameters:

Name	Type	Default	Description
`key`
`increment`		`1`
`callback`

Returns:

a component that can be scheduled

Type: function

popListValue(options) → {Promise.<*>}

Source:

data/Shelf.js, line 317

Pop an element, at the given index, from the value of a record of type LIST associated with the given key.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Attributes	Default	Description
`key`	Array.<string>			key as an array of key components
`index`	number	<optional>	`-1`	the index of the element to be popped

Throws:

exception if there is no record with the given key, or if there is a record but it is locked or it is not of type LIST
Type Object.<string, *>

Returns:

the popped element

Type: Promise.<*>

setBooleanValue(options) → {Promise.<boolean>}

Source:

data/Shelf.js, line 80

Set the value of a record of type BOOLEAN associated with the given key.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Description
`key`	Array.<string>	key as an array of key components
`value`	boolean	the new value

Throws:

exception if value is not a boolean, or if there is no record with the given key, or if there is a record but it is locked or it is not of type BOOLEAN
Type Object.<string, *>

Returns:

the new value

Type: Promise.<boolean>

(async) setDictionaryFieldValue(options) → {Promise.<Object.<string, *>>}

Source:

data/Shelf.js, line 406

Set a field in the dictionary record associated to the given key.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Description
`key`	Array.<string>	key as an array of key components
`fieldName`	string	the name of the field
`fieldValue`	*	the value of the field

Throws:

exception if there is no record with the given key, or if there is a record but it is locked or it is not of type DICTIONARY
Type Object.<string, *>

Returns:

the updated dictionary

Type: Promise.<Object.<string, *>>

setDictionaryValue(options) → {Promise.<Object.<string, *>>}

Source:

data/Shelf.js, line 443

Set the value of a record of type DICTIONARY associated with the given key.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Description
`key`	Array.<string>	key as an array of key components
`value`	Object.<string, *>	the new value

Throws:

exception if value is not an object, or or if there is no record with the given key, or if there is a record but it is locked or it is not of type DICTIONARY
Type Object.<string, *>

Returns:

the new value

Type: Promise.<Object.<string, *>>

setIntegerValue(options) → {Promise.<number>}

Source:

data/Shelf.js, line 144

Set the value of a record of type INTEGER associated with the given key.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Description
`key`	Array.<string>	key as an array of key components
`value`	number	the new value

Throws:

exception if value is not an integer, or or if there is no record with the given key, or if there is a record but it is locked or it is not of type INTEGER
Type Object.<string, *>

Returns:

the new value

Type: Promise.<number>

setListValue(options) → {Promise.<Array.<*>>}

Source:

data/Shelf.js, line 266

Set the value of a record of type LIST associated with the given key.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Description
`key`	Array.<string>	key as an array of key components
`value`	Array.<*>	the new value

Throws:

exception if value is not an array or if there is no record with the given key, or if there is a record but it is locked or it is not of type LIST
Type Object.<string, *>

Returns:

the new value

Type: Promise.<Array.<*>>

setTextValue(options) → {Promise.<string>}

Source:

data/Shelf.js, line 220

Set the value of a record of type TEXT associated with the given key.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Description
`key`	Array.<string>	key as an array of key components
`value`	string	the new value

Throws:

exception if value is not a string, or if there is a record associated with the given key but it is not of type TEXT
Type Object.<string, *>

Returns:

the new value

Type: Promise.<string>

shuffleListValue(options) → {Promise.<Array.<*>>}

Source:

data/Shelf.js, line 354

Shuffle the elements of the value of a record of type LIST associated with the given key.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Description
`key`	Array.<string>	key as an array of key components

Throws:

exception if there is no record with the given key, or if there is a record but it is locked or it is not of type LIST
Type Object.<string, *>

Returns:

the new, shuffled value

Type: Promise.<Array.<*>>