# Shelf

## data Shelf

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

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