SyncMap | twilio-sync

Represents a Sync map, which is a data structure that stores an unordered set of key-value pairs. Use the SyncClient.map method to obtain a reference to a Sync map. Information about rate limits can be found here.

Hierarchy

Closeable
- SyncMap

Index

Events

Accessors

Methods

Events

Static Readonly itemAdded

itemAdded: "itemAdded" = 'itemAdded'

Fired when a new item appears in the map, regardless of whether its creator was local or remote.

Parameters:

object args - info object provided with the event. It has the following properties:
- SyncMapItem item - added item
- boolean isLocal - equals true if the item was added by a local actor, false otherwise

example

map.on('itemAdded', (args) => {
  console.log(`Map item ${args.item.key} was added`);
  console.log('args.item.data:', args.item.data);
  console.log('args.isLocal:', args.isLocal);
});

Static Readonly itemRemoved

itemRemoved: "itemRemoved" = 'itemRemoved'

Fired when a map item is removed, regardless of whether the remover was local or remote.

Parameters:

object args - info object provided with the event. It has the following properties:
- string key - the key of the removed item
- boolean isLocal - equals true if the item was added by a local actor, false otherwise
- object previousItemData - contains a snapshot of the item data before removal

example

map.on('itemRemoved', (args) => {
  console.log(`Map item ${args.key} was removed`);
  console.log('args.previousItemData:', args.previousItemData);
  console.log('args.isLocal:', args.isLocal);
});

Static Readonly itemUpdated

itemUpdated: "itemUpdated" = 'itemUpdated'

Fired when a map item is updated (not added or removed, but changed), regardless of whether the updater was local or remote.

Parameters:

object args - info object provided with the event. It has the following properties:
- SyncMapItem item - updated item
- boolean isLocal - equals true if the item was updated by a local actor, false otherwise
- object previousItemData - contains a snapshot of the item data before the update

example

map.on('itemUpdated', (args) => {
  console.log(`Map item ${args.item.key} was updated`);
  console.log('args.item.data:', args.item.data);
  console.log('args.isLocal:', args.isLocal);
  console.log('args.previousItemData:', args.previousItemData);
});

Static Readonly removed

removed: "removed" = 'removed'

Fired when a map is deleted entirely, by any actor local or remote.

Parameters:

object args - info object provided with the event. It has the following properties:
- boolean isLocal - equals true if the map was removed by a local actor, false otherwise

example

map.on('removed', (args) => {
  console.log(`Map ${map.sid} was removed`);
  console.log('args.isLocal:', args.isLocal);
});

Accessors

dateUpdated

get dateUpdated(): Date

Date when the map was last updated.

Returns Date

sid

get sid(): string

An immutable identifier (a SID) assigned by the system on creation.

Returns string

uniqueName

get uniqueName(): string

An optional immutable identifier that may be assigned by the programmer to this map on creation. Unique among other Maps.

Returns string

Methods

close

close(): void

Overrides Closeable.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();
```
Returns void

get

get(key: string): Promise<SyncMapItem>

Retrieve an item by key.

example

map.get('myKey')
  .then((item) => {
    console.log('Map SyncMapItem get() successful, item data:', item.data)
  })
  .catch((error) => {
    console.error('Map SyncMapItem get() failed', error);
  });

Parameters

key: string

Identifies the desired item.

Returns Promise<SyncMapItem>

A promise that resolves when the item has been fetched. This promise will be rejected if item was not found.

getItems

getItems(queryOptions?: SyncMapItemQueryOptions): Promise<Paginator<SyncMapItem>>

Get a complete list of items from the map. Information about the query limits can be found here.

example

const pageHandler = (paginator) => {
  paginator.items.forEach((item) => {
    console.log(`SyncMapItem ${item.key}: `, item.data);
  });
  return paginator.hasNextPage
    ? paginator.nextPage().then(pageHandler)
    : null;
};
map.getItems({ from: 'myKey', order: 'asc' })
  .then(pageHandler)
  .catch((error) => {
    console.error('Map getItems() failed', error);
  });

Parameters

Optional queryOptions: SyncMapItemQueryOptions

Query options.

Returns Promise<Paginator<SyncMapItem>>

mutate

mutate(key: string, mutator: Mutator, itemMetadataUpdates?: SyncMapItemMetadata): Promise<SyncMapItem>

Schedules a modification to this Map SyncMapItem that will apply a mutation function. If no SyncMapItem with the given key exists, it will first be created, having the default data ({}).
example
```
const mutatorFunction = (currentData) => {
    currentData.viewCount = (currentData.viewCount || 0) + 1;
    return currentData;
};
map.mutate('myKey', mutatorFunction, { ttl: 86400 })
  .then((item) => {
    console.log('Map SyncMapItem mutate() successful, new data:', item.data)
  })
  .catch((error) => {
    console.error('Map SyncMapItem mutate() failed', error);
  });
```
Parameters
- key: string
  
  Selects the map item to be mutated.
- mutator: Mutator
  
  A function that outputs a new data based on the existing data. May be called multiple times, particularly if this Map SyncMapItem is modified concurrently by remote code. If the mutation ultimately succeeds, the Map SyncMapItem will have made the particular transition described by this function.
- Optional itemMetadataUpdates: SyncMapItemMetadata
  
  New item metadata.
Returns Promise<SyncMapItem>

Resolves with the most recent item state, the output of a successful mutation or a state that prompted graceful cancellation (mutator returned null).

remove

remove(key: string): Promise<void>

Delete an item, given its key.
example
```
map.remove('myKey')
  .then(() => {
    console.log('Map SyncMapItem remove() successful');
  })
  .catch((error) => {
    console.error('Map SyncMapItem remove() failed', error);
  });
```
Parameters
- key: string
  
  Selects the item to delete.
Returns Promise<void>

A promise to remove an item. The promise will be rejected if 'key' is undefined or an item was not found.

removeMap

removeMap(): Promise<void>

Delete this map. It will be impossible to restore it.

example

map.removeMap()
  .then(() => {
    console.log('Map removeMap() successful');
  })
  .catch((error) => {
    console.error('Map removeMap() failed', error);
  });

Returns Promise<void>

A promise that resolves when the map has been deleted.

set

set(key: string, data: Object, itemMetadataUpdates?: SyncMapItemMetadata): Promise<SyncMapItem>

Add a new item to the map with the given key-value pair. Overwrites any data that might already exist with that key.
example
```
map.set('myKey', { name: 'John Smith' }, { ttl: 86400 })
  .then((item) => {
    console.log('Map SyncMapItem set() successful, item data:', item.data);
  })
  .catch((error) => {
    console.error('Map SyncMapItem set() failed', error);
  });
```
Parameters
- key: string
  
  Unique item identifier.
- data: Object
  
  Data to be set.
- Optional itemMetadataUpdates: SyncMapItemMetadata
  
  New item metadata.
Returns Promise<SyncMapItem>

Newly added item, or modified one if already exists, with the latest known data.

setItemTtl

setItemTtl(key: string, ttl: number): Promise<void>

Update the time-to-live of a map item.
example
```
map.setItemTtl('myKey', 86400)
  .then(() => {
    console.log('Map setItemTtl() successful');
  })
  .catch((error) => {
    console.error('Map setItemTtl() failed', error);
  });
```
Parameters
- key: string
  
  SyncMapItem key.
- ttl: number
  
  Specifies the TTL in seconds after which the map item is subject to automatic deletion. The value 0 means infinity.
Returns Promise<void>

A promise that resolves after the TTL update was successful.

setTtl

setTtl(ttl: number): Promise<void>

Update the time-to-live of the map.
example
```
map.setTtl(3600)
  .then(() => {
    console.log('Map setTtl() successful');
  })
  .catch((error) => {
    console.error('Map setTtl() failed', error);
  });
```
Parameters
- ttl: number
  
  Specifies the TTL in seconds after which the map is subject to automatic deletion. The value 0 means infinity.
Returns Promise<void>

A promise that resolves after the TTL update was successful.

update

update(key: string, obj: Object, itemMetadataUpdates?: SyncMapItemMetadata): Promise<SyncMapItem>

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', (currentData) => Object.assign(currentData, obj));
```
example
```
// Say, the Map SyncMapItem (key: `'myKey'`) data is `{ name: 'John Smith' }`
map.update('myKey', { age: 34 }, { ttl: 86400 })
  .then((item) => {
    // Now the Map SyncMapItem data is `{ name: 'John Smith', age: 34 }`
    console.log('Map SyncMapItem update() successful, new data:', item.data);
  })
  .catch((error) => {
    console.error('Map SyncMapItem update() failed', error);
  });
```
Parameters
- key: string
  
  Selects the map item to update.
- obj: Object
  
  Specifies the particular (top-level) attributes that will receive new values.
- Optional itemMetadataUpdates: SyncMapItemMetadata
  
  New item metadata.
Returns Promise<SyncMapItem>

A promise resolving to the modified item in its new state.

Hierarchy

Index

Events

Accessors

Methods

Events

Static Readonly itemAdded

Static Readonly itemRemoved

Static Readonly itemUpdated

Static Readonly removed

Accessors

dateUpdated

Returns Date

sid

Returns string

uniqueName

Returns string

Methods

close

Returns void

get

Parameters

key: string

Returns Promise<SyncMapItem>

getItems

Parameters

Optional queryOptions: SyncMapItemQueryOptions

Returns Promise<Paginator<SyncMapItem>>

mutate

Parameters

key: string

mutator: Mutator

Optional itemMetadataUpdates: SyncMapItemMetadata

Returns Promise<SyncMapItem>

remove

Parameters

key: string

Returns Promise<void>

removeMap

Returns Promise<void>

set

Parameters

key: string

data: Object

Optional itemMetadataUpdates: SyncMapItemMetadata

Returns Promise<SyncMapItem>

setItemTtl

Parameters

key: string

ttl: number

Returns Promise<void>

setTtl

Parameters

ttl: number

Returns Promise<void>

update

Parameters

key: string

obj: Object

Optional itemMetadataUpdates: SyncMapItemMetadata

Returns Promise<SyncMapItem>