List API reference for Momento Cache
This page details the Momento API methods for the list collection data types.
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('test-cache', 'test-list', ['a', 'b', 'c']);
const result = await cacheClient.listFetch('test-cache', '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 'test-cache'");
} else if (result instanceof CacheListFetch.Error) {
throw new Error(
`An error occurred while attempting to fetch the list 'test-list' from cache 'test-cache': ${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 listtoString()
: String - add the listLength
- Error
See response objects for specific information.
- JavaScript
await cacheClient.listConcatenateBack('test-cache', 'test-list', ['a', 'b', 'c']);
const result = await cacheClient.listConcatenateBack('test-cache', '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 'test-cache': ${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 itemtoString()
: String - add the listLength
- Error
See response objects for specific information.
- JavaScript
await cacheClient.listConcatenateFront('test-cache', 'test-list', ['a', 'b', 'c']);
const result = await cacheClient.listConcatenateFront('test-cache', '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 'test-cache': ${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('test-cache', 'test-list', ['one', 'two', 'three']);
const result = await cacheClient.listLength('test-cache', '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 'test-cache'");
} else if (result instanceof CacheListLength.Error) {
throw new Error(
`An error occurred while attempting to call cacheListLength on list 'test-list' in cache 'test-cache': ${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()
: StringvalueBytes()
: BytestoString()
: truncated valueString()
- Miss
- Error
See response objects for specific information.
- JavaScript
await cacheClient.listConcatenateBack('test-cache', 'test-list', ['one', 'two', 'three']);
const result = await cacheClient.listPopBack('test-cache', '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 'test-cache'");
} else if (result instanceof CacheListPopBack.Error) {
throw new Error(
`An error occurred while attempting to call cacheListPopBack on list 'test-list' in cache 'test-cache': ${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()
: StringvalueBytes()
: BytestoString()
: truncated valueString()
- Miss
- Error
See response objects for specific information.
- JavaScript
await cacheClient.listConcatenateFront('test-cache', 'test-list', ['one', 'two', 'three']);
const result = await cacheClient.listPopFront('test-cache', '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 'test-cache'");
} else if (result instanceof CacheListPopFront.Error) {
throw new Error(
`An error occurred while attempting to call cacheListPopFront on list 'test-list' in cache 'test-cache': ${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 itemtoString()
: String - add the listLength
- Error
See response objects for specific information.
- JavaScript
await cacheClient.listConcatenateBack('test-cache', 'test-list', ['a', 'b', 'c']);
const result = await cacheClient.listPushBack('test-cache', '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 'test-cache': ${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 listtoString()
: String - add the listLength
- Error
See response objects for specific information.
- JavaScript
await cacheClient.listConcatenateFront('test-cache', 'test-list', ['a', 'b', 'c']);
const result = await cacheClient.listPushFront('test-cache', '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 'test-cache': ${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('test-cache', 'test-list', ['a', 'b', 'c']);
const result = await cacheClient.listRemoveValue('test-cache', '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 'test-cache': ${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('test-cache', 'test-list', ['a', 'b', 'c', 'd', 'e', 'f']);
const result = await cacheClient.listRetain('test-cache', '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 'test-cache': ${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]
withtruncateFrontToSize: 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]
withtruncateFrontToSize: 10
the list will not be truncated. It will be[1, 2, 3, 4, 5, 6]