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
Rust

await cacheClient.listConcatenateBack(cacheName, 'test-list', ['a', 'b', 'c']);
const result = await cacheClient.listFetch(cacheName, 'test-list');

// simplified style; assume the value was found
console.log(`cache hit: ${result.value()!}`);

// pattern-matching style; safer for production code
switch (result.type) {
  case CacheListFetchResponse.Hit:
    console.log(`List fetched successfully: ${result.value()}`);
    break;
  case CacheListFetchResponse.Miss:
    console.log(`List 'test-list' was not found in cache '${cacheName}'`);
    break;
  case CacheListFetchResponse.Error:
    throw new Error(
      `An error occurred while attempting to fetch the list 'test-list' from cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
    );
}

info

Full example code and imports can be found here

  let _fetched_values: Vec<String> = cache_client
      .list_fetch(cache_name, "list_name")
      .await?
      .try_into()
      .expect("Expected a list fetch!");

info

Full example code and imports can be found here

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
Rust

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

info

Full example code and imports can be found here

  cache_client
      .list_concatenate_back(cache_name, "list_name", vec!["value1", "value2"])
      .await?;
  println!("Elements appended to list");

info

Full example code and imports can be found here

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
Rust

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

info

Full example code and imports can be found here

  cache_client
      .list_concatenate_front(cache_name, "list_name", vec!["value1", "value2"])
      .await?;
  println!("Elements prepended to list");

info

Full example code and imports can be found here

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
Rust

await cacheClient.listConcatenateBack(cacheName, 'test-list', ['one', 'two', 'three']);
const result = await cacheClient.listLength(cacheName, 'test-list');

// simplified style; assume the value was found
console.log(`Length of list 'test-list' is: ${result.value()!}`);

// pattern-matching style; safer for production code
switch (result.type) {
  case CacheListLengthResponse.Hit:
    console.log(`Length of list 'test-list' is ${result.length()}`);
    break;
  case CacheListLengthResponse.Miss:
    console.log(`List 'test-list' was not found in cache '${cacheName}'`);
    break;
  case CacheListLengthResponse.Error:
    throw new Error(
      `An error occurred while attempting to call cacheListLength on list 'test-list' in cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
    );
}

info

Full example code and imports can be found here

  let _length: u32 = cache_client
      .list_length(cache_name, "list_name")
      .await?
      .try_into()
      .expect("Expected a list length!");

info

Full example code and imports can be found here

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
Rust

await cacheClient.listConcatenateBack(cacheName, 'test-list', ['one', 'two', 'three']);
const result = await cacheClient.listPopBack(cacheName, 'test-list');

// simplified style; assume the value was found
console.log(`Last value, removed from 'test-list' is: ${result.value()!}`);

// pattern-matching style; safer for production code
switch (result.type) {
  case CacheListPopBackResponse.Hit:
    console.log(`Last value was removed successfully from list 'test-list': ${result.value()}`);
    break;
  case CacheListPopBackResponse.Miss:
    console.log(`List 'test-list' was not found in cache '${cacheName}'`);
    break;
  case CacheListPopBackResponse.Error:
    throw new Error(
      `An error occurred while attempting to call cacheListPopBack on list 'test-list' in cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
    );
}

info

Full example code and imports can be found here

  let _popped_value: String = cache_client
      .list_pop_back(cache_name, "list_name")
      .await?
      .try_into()
      .expect("Expected a popped list value!");

info

Full example code and imports can be found here

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
Rust

await cacheClient.listConcatenateFront(cacheName, 'test-list', ['one', 'two', 'three']);
const result = await cacheClient.listPopFront(cacheName, 'test-list');

// simplified style; assume the value was found
console.log(`First value, removed from 'test-list' is: ${result.value()!}`);

// pattern-matching style; safer for production code
switch (result.type) {
  case CacheListPopFrontResponse.Hit:
    console.log(`First value was removed successfully from list 'test-list': ${result.value()}`);
    break;
  case CacheListPopFrontResponse.Miss:
    console.log(`List 'test-list' was not found in cache '${cacheName}'`);
    break;
  case CacheListPopFrontResponse.Error:
    throw new Error(
      `An error occurred while attempting to call cacheListPopFront on list 'test-list' in cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
    );
}

info

Full example code and imports can be found here

  let _popped_value: String = cache_client
      .list_pop_front(cache_name, "list_name")
      .await?
      .try_into()
      .expect("Expected a popped list value!");

info

Full example code and imports can be found here

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');
switch (result.type) {
  case CacheListPushBackResponse.Success:
    console.log("Value 'x' added successfully to back of list 'test-list'");
    break;
  case CacheListPushBackResponse.Error:
    throw new Error(
      `An error occurred while attempting to call cacheListPushBack on list 'test-list' in cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
    );
}

info

Full example code and imports can be found here

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');
switch (result.type) {
  case CacheListPushFrontResponse.Success:
    console.log("Value 'x' added successfully to front of list 'test-list'");
    break;
  case CacheListPushFrontResponse.Error:
    throw new Error(
      `An error occurred while attempting to call cacheListPushFront on list 'test-list' in cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
    );
}

info

Full example code and imports can be found here

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
Rust

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

info

Full example code and imports can be found here

  cache_client
      .list_remove_value(cache_name, "list_name", "value1")
      .await?;
  println!("Value removed from list");

info

Full example code and imports can be found here

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});
switch (result.type) {
  case CacheListRetainResponse.Success:
    console.log("Retaining elements from index 1 to 4 from list 'test-list'");
    break;
  case CacheListRetainResponse.Error:
    throw new Error(
      `An error occurred while attempting to call cacheListRetain on list 'test-list' in cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
    );
}

info

Full example code and imports can be found here

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 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