Documentation

Class: Map

Map

Represents a Sync Map, which stores an unordered set of key:value pairs.
Properties:
Name Type Argument Default Description
sid String An immutable identifier (a SID) assigned by the system on creation.
uniqueName String <optional>
 null An optional immutable identifier that may be assigned by the programmer to this map on creation. Unique among other Maps.
Fires:

Methods

get(key)

Retrieve an item by key.
Parameters:
Name Type Description
key String Identifies the desired item.
Returns:
A promise that resolves when the item has been fetched. This promise will be rejected if item was not found.
Type
Promise.<MapItem>

getItems(args)

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

mutate(key, mutator)

Schedules a modification to this document that will apply a mutation function.
Parameters:
Name Type Description
key String selects the map item to be mutated.
mutator Map~Mutator A function that outputs a new value based on the existing value. May be called multiple times, particularly if this Document is modified concurrently by remote code. If the mutation ultimately succeeds, the Document will have made the particular transition described by this function.
Returns:
Resolves with the modified item, with its latest contents.
Type
Promise.<MapItem>

remove(key)

Delete an item, given its key.
Parameters:
Name Type Description
key String selects the item to delete.
Returns:
A promise to remove an item. The promise will be rejected if 'key' is undefined or an item was not found.
Type
Promise.<void>

removeMap()

Delete this map. It will be impossible to restore it.
Returns:
A promise that resolves when the map has been deleted.
Type
Promise.<void>

set(key, value)

Add a new item to the map with the given key:value pair. Overwrites any value that might already exist at that key.
Parameters:
Name Type Description
key String Unique item identifier
value Object Value to be set
Returns:
Newly added item, or modified one if already exists, with the latest known value.
Type
Promise.<MapItem>

update(key, obj)

Modify the keyed map item by appending new fields (or by overwriting existing ones) with the values from the provided Object. Creates a new item if no item by this key exists, copying all given fields and values into it.
Parameters:
Name Type Description
key String selects the map item to update.
obj Object Specifies the particular (top-level) attributes that will receive new values.
Returns:
A promise resolving to the modified item in its new state.
Type
Promise.<MapItem>

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 map is deleted entirely, by any actor local or remote.
Parameters:
Type Description
Boolean Equals 'true' if map was removed by local actor, 'false' otherwise

collectionRemovedRemotely

Fired when remote code deletes a map.

itemAdded

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

itemAddedRemotely

Fired when remote code creates a new item in the map.
Parameters:
Type Description
MapItem Added item

itemRemoved

Fired when a map item is removed, whether the remover was local or remote.
Parameters:
Type Description
String A key of removed item
Boolean Equals 'true' if item was removed by local actor, 'false' otherwise

itemRemovedRemotely

Fired when a remote actor removes a map item.
Parameters:
Type Description
String A key of removed item
Object A snapshot of item data before removal

itemUpdated

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

itemUpdatedRemotely

Fired when a remote actor updates a map item.
Parameters:
Type Description
MapItem Updated item