SyncList | twilio-sync

Represents a Sync list, which stores an ordered list of values. Use the SyncClient.list method to obtain a reference to a Sync list. Information about rate limits can be found here.

Hierarchy

Closeable
- SyncList

Index

Events

Accessors

Methods

Events

Static Readonly itemAdded

itemAdded: "itemAdded" = 'itemAdded'

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

Parameters:

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

example

list.on('itemAdded', (args) => {
  console.log(`List item ${args.item.index} 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 list 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:
- number index - index of the removed item
- boolean isLocal - equals true if the item was removed by a local actor, false otherwise
- object previousItemData - contains a snapshot of the item data before the removal

example

list.on('itemRemoved', (args) => {
  console.log(`List item ${args.index} was removed`);
  console.log('args.previousItemData:', args.previousItemData);
  console.log('args.isLocal:', args.isLocal);
});

Static Readonly itemUpdated

itemUpdated: "itemUpdated" = 'itemUpdated'

Fired when a list 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:
- SyncListItem 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

list.on('itemUpdated', (args) => {
  console.log(`List item ${args.item.index} 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 list 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 list was removed by a local actor, false otherwise

example

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

Accessors

dateUpdated

get dateUpdated(): Date

Date when the list was last updated, given in UTC ISO 8601 format (e.g., '2018-04-26T15:23:19.732Z').

Returns Date

sid

get sid(): string

Unique ID of the list, immutable identifier assigned by the system.

Returns string

uniqueName

get uniqueName(): string

Unique name of the list, immutable identifier that can be assigned to the list during creation.

Returns string

Methods

close

close(): void

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

get

get(index: number): Promise<SyncListItem>

Retrieve an item by List index.
example
```
list.get(42)
  .then((item) => {
    console.log('List Item get() successful, item data:', item.data)
  })
  .catch((error) => {
    console.error('List Item get() failed', error);
  });
```
Parameters
- index: number
  
  Item index in the list.
Returns Promise<SyncListItem>

A promise with the item containing latest known data. The promise will be rejected if the item was not found.

getItems

getItems(queryOptions: SyncListItemQueryOptions): Promise<Paginator<SyncListItem>>

Query a list of items from collection. Information about the query limits can be found here.

example

const pageHandler = (paginator) => {
  paginator.items.forEach((item) => {
    console.log(`Item ${item.index}:`, item.data);
  });
  return paginator.hasNextPage
    ? paginator.nextPage().then(pageHandler)
    : null;
};
list.getItems({ from: 0, order: 'asc' })
  .then(pageHandler)
  .catch((error) => {
    console.error('List getItems() failed', error);
  });

Parameters

queryOptions: SyncListItemQueryOptions

Query options.

Returns Promise<Paginator<SyncListItem>>

mutate

mutate(index: number, mutator: Mutator, itemMetadataUpdates?: SyncListItemMetadata): Promise<SyncListItem>

Modify an existing item by applying a mutation function to it.
example
```
const mutatorFunction = (currentValue) => {
    currentValue.viewCount = (currentValue.viewCount || 0) + 1;
    return currentValue;
};
list.mutate(42, mutatorFunction, { ttl: 86400 })
  .then((item) => {
    console.log('List Item mutate() successful, new data:', item.data)
  })
  .catch((error) => {
    console.error('List Item mutate() failed', error);
  });
```
Parameters
- index: number
  
  Index of the item to be changed.
- mutator: Mutator
  
  A function that outputs a new data based on the existing data.
- Optional itemMetadataUpdates: SyncListItemMetadata
  
  New item metadata.
Returns Promise<SyncListItem>

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.

push

push(data: any, itemMetadata?: SyncListItemMetadata): Promise<SyncListItem>

Add a new item to the list.

example

list.push({ name: 'John Smith' }, { ttl: 86400 })
  .then((item) => {
    console.log(`List Item push() successful, item index: ${item.index}, data:`, item.data)
  })
  .catch((error) => {
    console.error('List Item push() failed', error);
  });

Parameters

data: any

Data to be added.
Optional itemMetadata: SyncListItemMetadata

Item metadata.

Returns Promise<SyncListItem>

The newly added item.

remove

remove(index: number): Promise<void>

Delete an item given its index.
example
```
list.remove(42)
  .then(() => {
    console.log('List Item remove() successful');
  })
  .catch((error) => {
    console.error('List Item remove() failed', error);
  });
```
Parameters
- index: number
  
  Index of the item to be removed.
Returns Promise<void>

A promise to remove the item. The promise will be rejected if the item was not found.

removeList

removeList(): Promise<void>

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

example

list.removeList() .then(() => { console.log('List removeList() successful'); }) .catch((error) => { console.error('List removeList() failed', error); });

Returns Promise<void>

A promise that resolves when the list has been deleted.

set

set(index: number, value: Object, itemMetadataUpdates?: SyncListItemMetadata): Promise<SyncListItem>

Assign new data to an existing item, given its index.
example
```
list.set(42, { name: 'John Smith' }, { ttl: 86400 })
  .then((item) => {
    console.log('List Item set() successful, item data:', item.data)
  })
  .catch((error) => {
    console.error('List Item set() failed', error);
  });
```
Parameters
- index: number
  
  Index of the item to be updated.
- value: Object
  
  New data to be assigned to an item.
- Optional itemMetadataUpdates: SyncListItemMetadata
  
  New item metadata.
Returns Promise<SyncListItem>

A promise with the updated item containing latest known data. The promise will be rejected if the item does not exist.

setItemTtl

setItemTtl(index: number, ttl: number): Promise<void>

Update the time-to-live of a list item.
example
```
list.setItemTtl(42, 86400)
  .then(() => {
    console.log('List setItemTtl() successful');
  })
  .catch((error) => {
    console.error('List setItemTtl() failed', error);
  });
```
Parameters
- 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 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 list.
example
```
list.setTtl(3600)
  .then(() => {
    console.log('List setTtl() successful');
  })
  .catch((error) => {
    console.error('List setTtl() failed', error);
  });
```
Parameters
- ttl: number
  
  Specifies the TTL in seconds after which the list 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(index: number, obj: Object, itemMetadataUpdates?: SyncListItemMetadata): Promise<SyncListItem>

Modify an existing item by appending new fields (or overwriting existing ones) with the values from the object. This is equivalent to

list.mutate(42, (currentValue) => Object.assign(currentValue, obj));

example

// Say, the List Item (index: 42) data is `{ name: 'John Smith' }`
list.update(42, { age: 34 }, { ttl: 86400 })
  .then((item) => {
    // Now the List Item data is `{ name: 'John Smith', age: 34 }`
    console.log('List Item update() successful, new data:', item.data);
  })
  .catch((error) => {
    console.error('List Item update() failed', error);
  });

Parameters

index: number

Index of an item to be changed.
obj: Object

Set of fields to update.
Optional itemMetadataUpdates: SyncListItemMetadata

New item metadata.

Returns Promise<SyncListItem>

A promise with a modified item containing latest known data. The promise will be rejected if the item was not found.

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

index: number

Returns Promise<SyncListItem>

getItems

Parameters

queryOptions: SyncListItemQueryOptions

Returns Promise<Paginator<SyncListItem>>

mutate

Parameters

index: number

mutator: Mutator

Optional itemMetadataUpdates: SyncListItemMetadata

Returns Promise<SyncListItem>

push

Parameters

data: any

Optional itemMetadata: SyncListItemMetadata

Returns Promise<SyncListItem>

remove

Parameters

index: number

Returns Promise<void>

removeList

Returns Promise<void>

set

Parameters

index: number

value: Object

Optional itemMetadataUpdates: SyncListItemMetadata

Returns Promise<SyncListItem>

setItemTtl

Parameters

index: number

ttl: number

Returns Promise<void>

setTtl

Parameters

ttl: number

Returns Promise<void>

update

Parameters

index: number

obj: Object

Optional itemMetadataUpdates: SyncListItemMetadata

Returns Promise<SyncListItem>