JSDoc: Class: Shelf

new Shelf(options)

Shelf handles persistent key/value pairs, or records, which are stored in the shelf collection on the server, and be accessed and manipulated in a concurrent fashion.

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

Source:

data/Shelf.js, line 17

Extends

PsychObject

Members

(static) MAX_KEY_LENGTH :number

Maximum number of components in a key

Type:

number

Source:

data/Shelf.js, line 32

(static, readonly) Type :Symbol

Shelf record types.

Type:

Symbol

Properties:

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

Source:

data/Shelf.js, line 902

(readonly) Status :Symbol

Shelf status

Type:

Symbol

Source:

data/Shelf.js, line 870

Methods

_checkAvailability(methodNameopt)

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

Source:

data/Shelf.js, line 788

Throws:

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

_checkKey(key)

Check the validity of the key.

Parameters:

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

Source:

data/Shelf.js, line 843

Throws:

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

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

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

Source:

data/Shelf.js, line 710

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>

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

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

Source:

data/Shelf.js, line 642

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>}

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

Source:

data/Shelf.js, line 181

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.<*>>}

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

Source:

data/Shelf.js, line 318

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.<*>>}

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

Source:

data/Shelf.js, line 365

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.<*>>

counterBalanceSelect(key, groups, groupSizes) → {Promise.<any>}

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

Parameters:

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

Source:

data/Shelf.js, line 576

Returns:

Type: Promise.<any>

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

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

Source:

data/Shelf.js, line 108

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>}

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

Source:

data/Shelf.js, line 56

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>

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

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

Source:

data/Shelf.js, line 408

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>>

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

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

Source:

data/Shelf.js, line 425

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, *>>}

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

Source:

data/Shelf.js, line 470

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>}

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

Source:

data/Shelf.js, line 129

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.<*>>}

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

Source:

data/Shelf.js, line 266

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>}

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

Source:

data/Shelf.js, line 214

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}

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

Parameters:

Name	Type	Description
`key`
`increment`
`callback`

Source:

data/Shelf.js, line 522

Returns:

a component that can be scheduled

Type: function

Example

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

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

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

Source:

data/Shelf.js, line 341

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>}

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

Source:

data/Shelf.js, line 75

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>

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

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

Source:

data/Shelf.js, line 445

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, *>>}

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

Source:

data/Shelf.js, line 489

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>}

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

Source:

data/Shelf.js, line 148

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.<*>>}

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

Source:

data/Shelf.js, line 285

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>}

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

Source:

data/Shelf.js, line 233

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.<*>>}

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

Source:

data/Shelf.js, line 386

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.<*>>