Documentation

Class: List

List

Represents a Sync List, which stores an ordered list of values. Use the Client#list method to obtain a reference to a Sync List.
Properties:
Name Type Argument Default Description
sid String List unique id, immutable identifier assigned by the system.
uniqueName String <optional>
 null List unique name, immutable identifier that can be assigned to list during creation.
dateUpdated Date Date when the List was last updated.
Fires:

Methods

close()

Conclude work with the list instance and remove all event listeners attached to it. Any subsequent operation on this object will be rejected with error. Other local copies of this list will continue operating and receiving events normally.
Example
list.close();

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

<async> 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);
  });

Type Definitions

ItemMetadata

Contains List Item metadata.
Type:
  • Object
Properties:
Name Type Argument Description
ttl Number <optional>
 Specifies the time-to-live in seconds after which the list item is subject to automatic deletion. The value 0 means infinity.

Mutator(currentValue)

Applies a transformation to the item value. May be called multiple times on the same datum in case of collisions with remote code.
Parameters:
Name Type Description
currentValue Object The current value of the item in the cloud.
Returns:
The desired new value for the item or null to gracefully cancel the mutation.
Type
Object

Events

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