List API reference for Momento Cache

This page details the Momento API methods for the list collection data types.

info

Momento collection types use a CollectionTTL to specify their TTL behavior. This is an optional argument for all "write" operations.

List methods

ListFetch

Gets a list item from a cache, with optional slices.

Name	Type	Description
cacheName	String	Name of the cache.
listName	String	The name of the list item to be retrieved.
startIndex	Number	The starting inclusive element of the list to fetch. Default is 0. This argument is optional.
endIndex	Number	The ending exclusive element of the list to fetch. Default is end of list. This argument is optional.

Method response object

The response object for ListFetch returns three possible options, a cache hit, miss, or an error.

Hit
- valueListBytes(): Bytes[]
- valueListString(): String[]
- toString(): String - Display a truncated valueListString(). See truncation.
Miss
Error

See response objects for specific information.

JavaScript

await cacheClient.listConcatenateBack(cacheName, 'test-list', ['a', 'b', 'c']);
const result = await cacheClient.listFetch(cacheName, 'test-list');
if (result instanceof CacheListFetch.Hit) {
  // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
  console.log(`List fetched successfully: ${result.valueList()}`);
} else if (result instanceof CacheListFetch.Miss) {
  console.log(`List 'test-list' was not found in cache '${cacheName}'`);
} else if (result instanceof CacheListFetch.Error) {
  throw new Error(
    `An error occurred while attempting to fetch the list 'test-list' from cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
  );
}

ListConcatenateBack

Appends the supplied list to the end of an existing list item.

Example:

If you have [1, 2, 3] and listConcatenateBack [4, 5, 6] you will have [1, 2, 3, 4, 5, 6].

Name	Type	Description
cacheName	String	Name of the cache.
listName	String	Name of the list item to be set.
values	String[] \| Bytes[]	Values to be added as elements to the list item.
ttl	CollectionTTL object	TTL for the list item in cache. This TTL takes precedence over the TTL used when initializing a cache client connection object.
truncateFrontToSize	Number	See truncate to size.

Method response object

Success
- listLength(): Number - the new length of the list
- toString(): String - add the listLength
Error

See response objects for specific information.

JavaScript

await cacheClient.listConcatenateBack(cacheName, 'test-list', ['a', 'b', 'c']);
const result = await cacheClient.listConcatenateBack(cacheName, 'test-list', ['x', 'y', 'z']);
if (result instanceof CacheListConcatenateBack.Success) {
  console.log(`Values added successfully to the back of the list 'test-list'. Result - ${result.toString()}`);
} else if (result instanceof CacheListConcatenateBack.Error) {
  throw new Error(
    `An error occurred while attempting to call cacheListConcatenateBack on list 'test-list' in cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
  );
}

ListConcatenateFront

Appends the supplied list to the front of an existing list item.

Example:

If you have [1, 2, 3] and listConcatenateFront [4, 5, 6] you will have [4, 5, 6, 1, 2, 3].

Name	Type	Description
cacheName	String	Name of the cache.
listName	String	Name of the list item to be set.
values	String[] \| Bytes[]	Values to be added as elements to the list item.
ttl	CollectionTTL object	TTL for the list item in cache. This TTL takes precedence over the TTL used when initializing a cache client.
truncateBackToSize	Number	See truncate to size.

Method response object

Success
- listLength(): Number - the new length of the list item
- toString(): String - add the listLength
Error

See response objects for specific information.

JavaScript

await cacheClient.listConcatenateFront(cacheName, 'test-list', ['a', 'b', 'c']);
const result = await cacheClient.listConcatenateFront(cacheName, 'test-list', ['x', 'y', 'z']);
if (result instanceof CacheListConcatenateFront.Success) {
  console.log(`Values added successfully to the front of the list 'test-list'. Result - ${result.toString()}`);
} else if (result instanceof CacheListConcatenateFront.Error) {
  throw new Error(
    `An error occurred while attempting to call cacheListConcatenateFront on list 'test-list' in cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
  );
}

ListLength

Get the length of an existing list item

Name	Type	Description
cacheName	String	Name of the cache.
listName	String	Name of the list item to be checked.

Method response object

Hit
- length(): Number
Miss
Error

See response objects for specific information.

JavaScript

await cacheClient.listConcatenateBack(cacheName, 'test-list', ['one', 'two', 'three']);
const result = await cacheClient.listLength(cacheName, 'test-list');
if (result instanceof CacheListLength.Hit) {
  console.log(`Length of list 'test-list' is ${result.length()}`);
} else if (result instanceof CacheListLength.Miss) {
  console.log(`List 'test-list' was not found in cache '${cacheName}'`);
} else if (result instanceof CacheListLength.Error) {
  throw new Error(
    `An error occurred while attempting to call cacheListLength on list 'test-list' in cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
  );
}

ListPopBack

Remove and return the last element from a list item.

Name	Type	Description
cacheName	String	Name of the cache.
listName	String	Name of the list item to be retrieved.

Method response object

Hit
- valueString(): String
- valueBytes(): Bytes
- toString(): truncated valueString()
Miss
Error

See response objects for specific information.

JavaScript

await cacheClient.listConcatenateBack(cacheName, 'test-list', ['one', 'two', 'three']);
const result = await cacheClient.listPopBack(cacheName, 'test-list');
if (result instanceof CacheListPopBack.Hit) {
  console.log(`Last value was removed successfully from list 'test-list': ${result.valueString()}`);
} else if (result instanceof CacheListPopBack.Miss) {
  console.log(`List 'test-list' was not found in cache '${cacheName}'`);
} else if (result instanceof CacheListPopBack.Error) {
  throw new Error(
    `An error occurred while attempting to call cacheListPopBack on list 'test-list' in cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
  );
}

ListPopFront

Remove and return the first element from a list item.

Name	Type	Description
cacheName	String	Name of the cache.
listName	String	Name of the list item to be retrieved.

Method response object

Hit
- valueString(): String
- valueBytes(): Bytes
- toString(): truncated valueString()
Miss
Error

See response objects for specific information.

JavaScript

await cacheClient.listConcatenateFront(cacheName, 'test-list', ['one', 'two', 'three']);
const result = await cacheClient.listPopFront(cacheName, 'test-list');
if (result instanceof CacheListPopFront.Hit) {
  console.log(`First value was removed successfully from list 'test-list': ${result.valueString()}`);
} else if (result instanceof CacheListPopFront.Miss) {
  console.log(`List 'test-list' was not found in cache '${cacheName}'`);
} else if (result instanceof CacheListPopFront.Error) {
  throw new Error(
    `An error occurred while attempting to call cacheListPopFront on list 'test-list' in cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
  );
}

ListPushBack

Push a value to the end of a list item. This is exactly like passing just one value to ListConcatenateBack.

Name	Type	Description
cacheName	String	Name of the cache.
listName	String	Name of the list to be set.
value	String \| Bytes	Value to be added.
ttl	CollectionTTL object	TTL for the list item in cache. This TTL takes precedence over the TTL used when initializing a cache connection client.
truncateBackToSize	Number	See truncate to size.

Method response object

Success
- listLength(): Number - the new length of the list item
- toString(): String - add the listLength
Error

See response objects for specific information.

JavaScript

await cacheClient.listConcatenateBack(cacheName, 'test-list', ['a', 'b', 'c']);
const result = await cacheClient.listPushBack(cacheName, 'test-list', 'x');
if (result instanceof CacheListPushBack.Success) {
  console.log("Value 'x' added successfully to back of list 'test-list'");
} else if (result instanceof CacheListPushBack.Error) {
  throw new Error(
    `An error occurred while attempting to call cacheListPushBack on list 'test-list' in cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
  );
}

ListPushFront

Push a value to the beginning of a list item. Just like ListPushBack, but to the front.

Name	Type	Description
cacheName	String	Name of the cache.
listName	String	Name of the list to be set.
value	String \| Bytes	Value to be added to the list item by the operation.
ttl	CollectionTTL object	TTL for the list item in cache. This TTL takes precedence over the TTL used when initializing a cache connection client.
truncateBackToSize	Number	See truncate to size.

Method response object

Success
- listLength(): Number - the new length of the list
- toString(): String - add the listLength
Error

See response objects for specific information.

JavaScript

await cacheClient.listConcatenateFront(cacheName, 'test-list', ['a', 'b', 'c']);
const result = await cacheClient.listPushFront(cacheName, 'test-list', 'x');
if (result instanceof CacheListPushFront.Success) {
  console.log("Value 'x' added successfully to front of list 'test-list'");
} else if (result instanceof CacheListPushFront.Error) {
  throw new Error(
    `An error occurred while attempting to call cacheListPushFront on list 'test-list' in cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
  );
}

ListRemoveValue

Remove all elements in a list item equal to a particular value.

Examples

If you have the list ['up', 'up', 'down', 'down', 'left', 'right'] and remove ‘up’ the list will be ['down', 'down', 'left', 'right']

Name	Type	Description
cacheName	String	Name of the cache.
listName	String	Name of the list item to be set.
value	String \| Bytes	Value to be added to the list item by the operation.

Method response object

Responses

Success - even if the value does not exist
Error

See response objects for specific information.

JavaScript

await cacheClient.listConcatenateFront(cacheName, 'test-list', ['a', 'b', 'c']);
const result = await cacheClient.listRemoveValue(cacheName, 'test-list', 'b');
if (result instanceof CacheListRemoveValue.Success) {
  console.log("Value 'b' removed successfully from list 'test-list'");
} else if (result instanceof CacheListRemoveValue.Error) {
  throw new Error(
    `An error occurred while attempting to call cacheListRemoveValue on list 'test-list' in cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
  );
}

ListRetain

Retains only slice of the list where the start is inclusive and the end is exclusive. The items outside of this range will be dropped from the list.

Example: For the specified list, start at index 4 (the startIndex) and keep the next five elements, end at index 10 (the endIndex). Discard all other elements in the list. In this example, elements at position 0-3 and 9 or higher are dropped.

Name	Type	Description
cacheName	String	Name of the cache.
listName	String	Name of the list item to be set.
startIndex	Number	The starting inclusive element of the list to retain. Default is 0.
endIndex	Number	The ending exclusive element of the list to retain. Default is end of list.
ttl	CollectionTTL object	TTL for the list item in cache. This TTL takes precedence over the TTL used when initializing a cache connection client.

Method response object

Responses

Success - even if the value does not exist
Error

See response objects for specific information.

JavaScript

await cacheClient.listConcatenateFront(cacheName, 'test-list', ['a', 'b', 'c', 'd', 'e', 'f']);
const result = await cacheClient.listRetain(cacheName, 'test-list', {startIndex: 1, endIndex: 4});
if (result instanceof CacheListRetain.Success) {
  console.log("Retaining elements from index 1 to 4 from list 'test-list'");
} else if (result instanceof CacheListRetain.Error) {
  throw new Error(
    `An error occurred while attempting to call cacheListRetain on list 'test-list' in cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
  );
}

Truncate to size

ListConcatenate and ListPush type API calls all have truncation options. If after adding their elements the list exceeds this size, this list will be truncated.

Example: If the list is [1, 2, 3] and you ListConcatenateBack [4, 5, 6] with truncateFrontToSize: 5 the list will be truncated to [2, 3, 4, 5, 6] and the response ListLength will be 5.
Example: If the list is [1, 2, 3] and you ListConcatenateBack [4, 5, 6] with truncateFrontToSize: 10 the list will not be truncated. It will be [1, 2, 3, 4, 5, 6]

List API reference for Momento Cache

List methods​

ListFetch​

ListConcatenateBack​

ListConcatenateFront​

ListLength​

ListPopBack​

ListPopFront​

ListPushBack​

ListPushFront​

ListRemoveValue​

ListRetain​

Truncate to size​

List methods

ListFetch

ListConcatenateBack

ListConcatenateFront

ListLength

ListPopBack

ListPopFront

ListPushBack

ListPushFront

ListRemoveValue

ListRetain

Truncate to size