Documentation

Class: Map

Map

Represents a Sync Map, which stores an unordered set of key:value pairs. Use the Client#map method to obtain a reference to a Sync Map.
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.
dateUpdated Date Date when the Map was last updated.
Fires:

Methods

close()

Conclude work with the map 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 map will continue operating and receiving events normally.
Example
map.close();

<async> 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>
Example
map.get('myKey')
  .then(function(item) {
    console.log('Map Item get() successful, item value:', item.value)
  })
  .catch(function(error) {
    console.error('Map Item get() failed', error);
  });

<async> getItems( [args])

Get a complete list of items from the map.
Parameters:
Name Type Argument Description
args Object <optional>
 Arguments for query.
Properties
Name Type Argument Default Description
from String <optional>
 Item key, which should be used as the offset. If undefined, starts from the beginning or end depending on args.order.
pageSize Number <optional>
 50 Result page size.
order 'asc' | 'desc' <optional>
 'asc' Lexicographical order of results.
Returns:
Type
Promise.<Paginator.<MapItem>>
Example
var pageHandler = function(paginator) {
  paginator.items.forEach(function(item) {
    console.log('Item ' + item.key + ': ', item.value);
  });
  return paginator.hasNextPage ? paginator.nextPage().then(pageHandler)
                               : null;
};
map.getItems({ from: 'myKey', order: 'asc' })
  .then(pageHandler)
  .catch(function(error) {
    console.error('Map getItems() failed', error);
  });

<async> mutate(key, mutator [, itemMetadataUpdates])

Schedules a modification to this Map Item that will apply a mutation function. If no Item with the given key exists, it will first be created, having the default value ({}).
Parameters:
Name Type Argument 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 Map Item is modified concurrently by remote code. If the mutation ultimately succeeds, the Map Item will have made the particular transition described by this function.
itemMetadataUpdates Map#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).
Type
Promise.<MapItem>
Example
var mutatorFunction = function(currentValue) {
    currentValue.viewCount = (currentValue.viewCount || 0) + 1;
    return currentValue;
};
map.mutate('myKey', mutatorFunction, { ttl: 86400 })
  .then(function(item) {
    console.log('Map Item mutate() successful, new value:', item.value)
  })
  .catch(function(error) {
    console.error('Map Item mutate() failed', error);
  });

<async> 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>
Example
map.remove('myKey')
  .then(function() {
    console.log('Map Item remove() successful');
  })
  .catch(function(error) {
    console.error('Map Item remove() failed', error);
  });

<async> 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>
Example
map.removeMap()
  .then(function() {
    console.log('Map removeMap() successful');
  })
  .catch(function(error) {
    console.error('Map removeMap() failed', error);
  });

<async> set(key, value [, itemMetadataUpdates])

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 Argument Description
key String Unique item identifier.
value Object Value to be set.
itemMetadataUpdates Map#ItemMetadata <optional>
 New item metadata.
Returns:
Newly added item, or modified one if already exists, with the latest known value.
Type
Promise.<MapItem>
Example
map.set('myKey', { name: 'John Smith' }, { ttl: 86400 })
  .then(function(item) {
    console.log('Map Item set() successful, item value:', item.value);
  })
  .catch(function(error) {
    console.error('Map Item set() failed', error);
  });

<async> setItemTtl(key, ttl)

Update the time-to-live of a map item.
Parameters:
Name Type Description
key Number Item key.
ttl Number Specifies the TTL in seconds after which the map 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
map.setItemTtl('myKey', 86400)
  .then(function() {
    console.log('Map setItemTtl() successful');
  })
  .catch(function(error) {
    console.error('Map setItemTtl() failed', error);
  });

<async> setTtl(ttl)

Update the time-to-live of the map.
Parameters:
Name Type Description
ttl Number Specifies the TTL in seconds after which the map 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
map.setTtl(3600)
  .then(function() {
    console.log('Map setTtl() successful');
  })
  .catch(function(error) {
    console.error('Map setTtl() failed', error);
  });

<async> update(key, obj [, itemMetadataUpdates])

Modify a 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. This is equivalent to 
map.mutate('myKey', function(currentValue) {
  return Object.assign(currentValue, obj));
});
Parameters:
Name Type Argument Description
key String Selects the map item to update.
obj Object Specifies the particular (top-level) attributes that will receive new values.
itemMetadataUpdates Map#ItemMetadata <optional>
 New item metadata.
Returns:
A promise resolving to the modified item in its new state.
Type
Promise.<MapItem>
Example
// Say, the Map Item (key: 'myKey') value is { name: 'John Smith' }
map.update('myKey', { age: 34 }, { ttl: 86400 })
  .then(function(item) {
    // Now the Map Item value is { name: 'John Smith', age: 34 }
    console.log('Map Item update() successful, new value:', item.value);
  })
  .catch(function(error) {
    console.error('Map Item update() failed', error);
  });

Type Definitions

ItemMetadata

Contains Map Item metadata.
Type:
  • Object
Properties:
Name Type Argument Description
ttl Number <optional>
 Specifies the time-to-live in seconds after which the map 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 map, whether its creator was local or remote.
Parameters:
Name Type Description
args Object Arguments provided with the event.
Properties
Name Type Description
item MapItem Added item.
isLocal Boolean Equals 'true' if item was added by local actor, 'false' otherwise.
Example
map.on('itemAdded', function(args) {
  console.log('Map item ' + args.item.key + ' was added');
  console.log('args.item.value:', args.item.value);
  console.log('args.isLocal:', args.isLocal);
});

itemRemoved

Fired when a map 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
key String The key 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
map.on('itemRemoved', function(args) {
  console.log('Map item ' + args.key + ' was removed');
  console.log('args.value:', args.value);
  console.log('args.isLocal:', args.isLocal);
});

itemUpdated

Fired when a map 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 MapItem Updated item.
isLocal Boolean Equals 'true' if item was updated by local actor, 'false' otherwise.
Example
map.on('itemUpdated', function(args) {
  console.log('Map item ' + args.item.key + ' was updated');
  console.log('args.item.value:', args.item.value);
  console.log('args.isLocal:', args.isLocal);
});

removed

Fired when a map 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 map was removed by local actor, 'false' otherwise.
Example
map.on('removed', function(args) {
  console.log('Map ' + map.sid + ' was removed');
  console.log('args.isLocal:', args.isLocal);
});