Documentation

Class: List

List

Represents a Sync List, which stores an ordered list of values.
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
Fires:

Methods

get(index)

Retrieve an item by List key.
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>

getItems(args)

Query a list of items from collection.
Parameters:
Name Type Description
args Object Arguments for query
Properties
Name Type Description
from Number Item, which should be used as an anchor. If undefined, starts from the beginning or end depending on args.order
pageSize Number Results page size
order String Lexicographical order of results, should be 'asc' or 'desc'
Returns:
Type
Promise.<Paginator.<ListItem>>

mutate(index, mutator)

Modify an existing item by applying a mutation function to it.
Parameters:
Name Type 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
Returns:
A promise with a modified item containing latest known value. A promise will be rejected if an item was not found.
Type
Promise.<ListItem>

push(value)

Add a new item to the list.
Parameters:
Name Type Description
value Object Value to be added
Returns:
A newly added item.
Type
Promise.<ListItem>

remove(index)

Delete an item, given its key.
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>

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>

set(index, value)

Assign new value to an existing item, given its index.
Parameters:
Name Type Description
index Number Index of an item to be updated
value Object New value to be assigned to an item
Returns:
A promise with updated item containing latest known value. A promise will be rejected if value was remotely modified.
Type
Promise.<ListItem>

update(index, obj)

Modify an existing item by appending new fields (or overwriting existing ones) with the values from Object.
Parameters:
Name Type Description
index Number Index of an item to be changed
obj Object Set of fields to update
Returns:
A promise with a modified item containing latest known value. A promise will be rejected if an item was not found.
Type
Promise.<ListItem>

Type Definitions

Mutator(data)

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
data Object The current value of the item in the cloud.
Returns:
The desired new value for the item.
Type
Object

Events

collectionRemoved

Fired when a list is deleted entirely, by any actor local or remote.
Parameters:
Type Description
Boolean Equals 'true' if list was removed by local actor, 'false' otherwise

collectionRemovedRemotely

Fired when remote code deletes a list.

itemAdded

Fired when a new item appears in the list, whether its creator was local or remote.
Parameters:
Type Description
ListItem Added item
Boolean Equals 'true' if item was added by local actor, 'false' otherwise

itemAddedRemotely

Fired when remote code adds a new item to the list.
Parameters:
Type Description
ListItem Added item

itemRemoved

Fired when a list item is removed, whether the remover was local or remote.
Parameters:
Type Description
Number An index of removed item
Boolean Equals 'true' if item was removed by local actor, 'false' otherwise

itemRemovedRemotely

Fired when a remote actor removes a list item.
Parameters:
Type Description
Number An index of removed item
Object A snapshot of item data before removal

itemUpdated

Fired when a list item is updated (not added or removed, but changed), whether the updater was local or remote.
Parameters:
Type Description
ListItem Updated item
Boolean Equals 'true' if item was updated by local actor, 'false' otherwise

itemUpdatedRemotely

Fired when a remote actor updates a list item.
Parameters:
Type Description
ListItem Updated item