-
<async> get(index)
-
Retrieve an item by List index.
Parameters:
Name |
Type |
Description |
index |
Number
|
Item index in a List. |
Returns:
A promise with an item containing latest known value.
A promise will be rejected if an item was not found.
-
Type
-
Promise.<ListItem>
Example
list.get(42)
.then(function(item) {
console.log('List Item get() successful, item value:', item.value)
})
.catch(function(error) {
console.error('List Item get() failed', error);
});
-
<async> getItems( [args])
-
Query a list of items from collection.
Parameters:
Name |
Type |
Argument |
Description |
args |
Object
|
<optional>
|
Arguments for query
Properties
Name |
Type |
Argument |
Default |
Description |
from |
Number
|
<optional>
|
|
Item index, which should be used as the offset.
If undefined, starts from the beginning or end depending on args.order. |
pageSize |
Number
|
<optional>
|
50
|
Results page size. |
order |
'asc'
|
'desc'
|
<optional>
|
'asc'
|
Numeric order of results. |
|
Returns:
-
Type
-
Promise.<Paginator.<ListItem>>
Example
var pageHandler = function(paginator) {
paginator.items.forEach(function(item) {
console.log('Item ' + item.index + ': ', item.value);
});
return paginator.hasNextPage ? paginator.nextPage().then(pageHandler)
: null;
};
list.getItems({ from: 0, order: 'asc' })
.then(pageHandler)
.catch(function(error) {
console.error('List getItems() failed', error);
});
-
<async> mutate(index, mutator [, itemMetadataUpdates])
-
Modify an existing item by applying a mutation function to it.
Parameters:
Name |
Type |
Argument |
Description |
index |
Number
|
|
Index of an item to be changed. |
mutator |
List~Mutator
|
|
A function that outputs a new value based on the existing value. |
itemMetadataUpdates |
List#ItemMetadata
|
<optional>
|
New item metadata. |
Returns:
Resolves with the most recent item state, the output of a successful
mutation or a state that prompted graceful cancellation (mutator returned null
). This promise
will be rejected if the indicated item does not already exist.
-
Type
-
Promise.<ListItem>
Example
var mutatorFunction = function(currentValue) {
currentValue.viewCount = (currentValue.viewCount || 0) + 1;
return currentValue;
};
list.mutate(42, mutatorFunction, { ttl: 86400 })
.then(function(item) {
console.log('List Item mutate() successful, new value:', item.value)
})
.catch(function(error) {
console.error('List Item mutate() failed', error);
});
-
<async> push(value [, itemMetadata])
-
Add a new item to the list.
Parameters:
Name |
Type |
Argument |
Description |
value |
Object
|
|
Value to be added. |
itemMetadata |
List#ItemMetadata
|
<optional>
|
Item metadata. |
Returns:
A newly added item.
-
Type
-
Promise.<ListItem>
Example
list.push({ name: 'John Smith' }, { ttl: 86400 })
.then(function(item) {
console.log('List Item push() successful, item index:' + item.index + ', value: ', item.value)
})
.catch(function(error) {
console.error('List Item push() failed', error);
});
-
<async> remove(index)
-
Delete an item, given its index.
Parameters:
Name |
Type |
Description |
index |
Number
|
Index of an item to be removed. |
Returns:
A promise to remove an item.
A promise will be rejected if an item was not found.
-
Type
-
Promise.<void>
Example
list.remove(42)
.then(function() {
console.log('List Item remove() successful');
})
.catch(function(error) {
console.error('List Item remove() failed', error);
});
-
<async> removeList()
-
Delete this list. It will be impossible to restore it.
Returns:
A promise that resolves when the list has been deleted.
-
Type
-
Promise.<void>
Example
list.removeList()
.then(function() {
console.log('List removeList() successful');
})
.catch(function(error) {
console.error('List removeList() failed', error);
});
-
set(index, value [, itemMetadataUpdates])
-
Assign new value to an existing item, given its index.
Parameters:
Name |
Type |
Argument |
Description |
index |
Number
|
|
Index of the item to be updated. |
value |
Object
|
|
New value to be assigned to an item. |
itemMetadataUpdates |
List#ItemMetadata
|
<optional>
|
New item metadata. |
Returns:
A promise with updated item containing latest known value.
The promise will be rejected if the item does not exist.
-
Type
-
Promise.<ListItem>
Example
list.set(42, { name: 'John Smith' }, { ttl: 86400 })
.then(function(item) {
console.log('List Item set() successful, item value:', item.value)
})
.catch(function(error) {
console.error('List Item set() failed', error);
});
-
<async> setItemTtl(index, ttl)
-
Update the time-to-live of a list item.
Parameters:
Name |
Type |
Description |
index |
Number
|
Item index. |
ttl |
Number
|
Specifies the TTL in seconds after which the list item is subject to automatic deletion. The value 0 means infinity. |
Returns:
A promise that resolves after the TTL update was successful.
-
Type
-
Promise.<void>
Example
list.setItemTtl(42, 86400)
.then(function() {
console.log('List setItemTtl() successful');
})
.catch(function(error) {
console.error('List setItemTtl() failed', error);
});
-
<async> setTtl(ttl)
-
Update the time-to-live of the list.
Parameters:
Name |
Type |
Description |
ttl |
Number
|
Specifies the TTL in seconds after which the list is subject to automatic deletion. The value 0 means infinity. |
Returns:
A promise that resolves after the TTL update was successful.
-
Type
-
Promise.<void>
Example
list.setTtl(3600)
.then(function() {
console.log('List setTtl() successful');
})
.catch(function(error) {
console.error('List setTtl() failed', error);
});
-
<async> update(index, obj [, itemMetadataUpdates])
-
Modify an existing item by appending new fields (or overwriting existing ones) with the values from Object.
This is equivalent to
list.mutate(42, function(currentValue) {
return Object.assign(currentValue, obj));
});
Parameters:
Name |
Type |
Argument |
Description |
index |
Number
|
|
Index of an item to be changed. |
obj |
Object
|
|
Set of fields to update. |
itemMetadataUpdates |
List#ItemMetadata
|
<optional>
|
New item metadata. |
Returns:
A promise with a modified item containing latest known value.
The promise will be rejected if an item was not found.
-
Type
-
Promise.<ListItem>
Example
// Say, the List Item (index: 42) value is { name: 'John Smith' }
list.update(42, { age: 34 }, { ttl: 86400 })
.then(function(item) {
// Now the List Item value is { name: 'John Smith', age: 34 }
console.log('List Item update() successful, new value:', item.value);
})
.catch(function(error) {
console.error('List Item update() failed', error);
});
-
itemAdded
-
Fired when a new item appears in the list, whether its creator was local or remote.
Parameters:
Name |
Type |
Description |
args |
Object
|
Arguments provided with the event.
Properties
Name |
Type |
Description |
item |
ListItem
|
Added item. |
isLocal |
Boolean
|
Equals 'true' if item was added by local actor, 'false' otherwise. |
|
Example
list.on('itemAdded', function(args) {
console.log('List item ' + args.item.index + ' was added');
console.log('args.item.value:', args.item.value);
console.log('args.isLocal:', args.isLocal);
});
-
itemRemoved
-
Fired when a list item is removed, whether the remover was local or remote.
Parameters:
Name |
Type |
Description |
args |
Object
|
Arguments provided with the event.
Properties
Name |
Type |
Description |
index |
Number
|
The index of the removed item. |
isLocal |
Boolean
|
Equals 'true' if item was removed by local actor, 'false' otherwise. |
value |
Object
|
In case item was removed by a remote actor, contains a snapshot of item data before removal. |
|
Example
list.on('itemRemoved', function(args) {
console.log('List item ' + args.index + ' was removed');
console.log('args.value:', args.value);
console.log('args.isLocal:', args.isLocal);
});
-
itemUpdated
-
Fired when a list item is updated (not added or removed, but changed), whether the updater was local or remote.
Parameters:
Name |
Type |
Description |
args |
Object
|
Arguments provided with the event.
Properties
Name |
Type |
Description |
item |
ListItem
|
Updated item. |
isLocal |
Boolean
|
Equals 'true' if item was updated by local actor, 'false' otherwise. |
|
Example
list.on('itemUpdated', function(args) {
console.log('List item ' + args.item.index + ' was updated');
console.log('args.item.value:', args.item.value);
console.log('args.isLocal:', args.isLocal);
});
-
removed
-
Fired when a list is deleted entirely, by any actor local or remote.
Parameters:
Name |
Type |
Description |
args |
Object
|
Arguments provided with the event.
Properties
Name |
Type |
Description |
isLocal |
Boolean
|
Equals 'true' if list was removed by local actor, 'false' otherwise. |
|
Example
list.on('removed', function(args) {
console.log('List ' + list.sid + ' was removed');
console.log('args.isLocal:', args.isLocal);
});