From cc99046e0dfae4438ec694e0275ae60890a513f6 Mon Sep 17 00:00:00 2001 From: rishtigupta Date: Mon, 12 Aug 2024 11:53:14 -0700 Subject: [PATCH] feat: refactor list cache page to new style --- .../develop/api-reference/list-collections.md | 492 +++++++++++------- 1 file changed, 309 insertions(+), 183 deletions(-) diff --git a/docs/cache/develop/api-reference/list-collections.md b/docs/cache/develop/api-reference/list-collections.md index ada7e6ee75..7aee4b1ff3 100644 --- a/docs/cache/develop/api-reference/list-collections.md +++ b/docs/cache/develop/api-reference/list-collections.md @@ -1,7 +1,7 @@ --- sidebar_position: 2 -sidebar_label: Lists title: List API reference +sidebar_label: Lists description: Learn how to interact with the API for list collection data types in Momento Cache. --- @@ -20,271 +20,397 @@ Momento collection types use a [CollectionTTL](./collection-ttl.md) to specify t ::: -## List methods +## List Methods + +--- + +
+ +
+ + ### ListFetch + + Gets a list item from a cache, with optional slices. + + #### Parameters + ---------------- + - **cacheName** - *String*: Name of the cache. + - **listName** - *String*: The name of the list item to be retrieved. + + #### Optional Parameters + ---------------- + - **startIndex** - *Number*: The starting inclusive element of the list to fetch. Default is 0. + - **endIndex** - *Number*: The ending exclusive element of the list to fetch. Default is end of list. + + #### Returns + ---------------- + 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](#truncate-to-size). + + - **Miss**: + + - **Error**: + - See [response objects](./response-objects.md) for specific information. + +
+ +
+ + + +
+ +
+ +--- + +
+ +
+ + ### 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]. + + #### Parameters + ---------------- + - **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](./collection-ttl.md)*: 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](#truncate-to-size). + + #### Returns + ---------------- + One of the following: + - **Success**: + - `listLength()`: Number - the new length of the list + - `toString()`: String - add the listLength + + - **Error**: + - See [response objects](./response-objects.md) for specific information. + +
+ +
+ + + +
+ +
+ +--- + +
+ +
+ + ### 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]. + + #### Parameters + ---------------- + - **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](./collection-ttl.md)*: TTL for the list item in cache. This TTL takes precedence over the TTL used when initializing a cache client connection object. + - **truncateBackToSize** - *Number*: See [truncate to size](#truncate-to-size). + + #### Returns + ---------------- + One of the following: + - **Success**: + - `listLength()`: Number - the new length of the list + - `toString()`: String - add the listLength + + - **Error**: + - See [response objects](./response-objects.md) for specific information. + +
+ +
+ + + +
+ +
+ +--- + +
-### ListFetch +
-Gets a list item from a cache, with optional slices. + ### ListLength -| 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.** | + Get the length of an existing list item. -
- Method response object + #### Parameters + ---------------- + - **cacheName** - *String*: Name of the cache. + - **listName** - *String*: Name of the list item to be checked. -The response object for ListFetch returns three possible options, a cache hit, miss, or an error. + #### Returns + ---------------- + One of the following: + - **Hit**: + - `length()`: Number -* Hit - * valueListBytes(): Bytes[] - * valueListString(): String[] - * toString(): String - Display a truncated valueListString(). See [truncation](#truncate-to-size). -* Miss -* Error + - **Miss** -See [response objects](./response-objects.md) for specific information. + - **Error**: + - See [response objects](./response-objects.md) for specific information. -
+
- +
-### 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](./collection-ttl.md) | 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](#truncate-to-size). | +--- -
- Method response object +
-* Success - * `listLength()`: Number - the new length of the list - * `toString()`: String - add the listLength -* Error +
-See [response objects](./response-objects.md) for specific information. + ### ListPopBack -
+ Remove and return the last element from a list item. - + #### Parameters + ---------------- + - **cacheName** - *String*: Name of the cache. + - **listName** - *String*: Name of the list item to be retrieved. -### ListConcatenateFront -Appends the supplied list to the front of an existing list item. + #### Returns + ---------------- + One of the following: + - **Hit**: + - `valueString()`: String + - `valueBytes()`: Bytes + - `toString()`: truncated valueString() -Example: + - **Miss** -If you have [1, 2, 3] and listConcatenateFront [4, 5, 6] you will have [4, 5, 6, 1, 2, 3]. + - **Error**: + - See [response objects](./response-objects.md) for specific information. -| 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](./collection-ttl.md) | 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](#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](./response-objects.md) for specific information. +
-
+ - +--- -### 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 + ### ListPopFront -* Hit - * `length()`: Number -* Miss -* Error + Remove and return the first element from a list item. -See [response objects](./response-objects.md) for specific information. + #### Parameters + ---------------- + - **cacheName** - *String*: Name of the cache. + - **listName** - *String*: Name of the list item to be retrieved. -
+ #### Returns + ---------------- + One of the following: + - **Hit**: + - `valueString()`: String + - `valueBytes()`: Bytes + - `toString()`: truncated valueString() - + - **Miss** -### ListPopBack -Remove and return the last element from a list item. + - **Error**: + - See [response objects](./response-objects.md) for specific information. -| 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](./response-objects.md) for specific information. +
-
+
- +--- -### 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 + ### ListPushBack -* Hit - * `valueString()`: String - * `valueBytes()`: Bytes - * `toString()`: truncated valueString() -* Miss -* Error + Push a value to the end of a list item. This is exactly like passing just one value to [ListConcatenateBack](#listconcatenateback). -See [response objects](./response-objects.md) for specific information. + #### Parameters + ---------------- + - **cacheName** - *String*: Name of the cache. + - **listName** - *String*: Name of the list item to be set. + - **value** - *String | Bytes*: Value to be added. + - **ttl** - *[CollectionTTL object](./collection-ttl.md)*: TTL for the list item in cache. This TTL takes precedence over the TTL used when initializing a cache connection client. + - **truncateFrontToSize** - *Number*: See [truncate to size](#truncate-to-size). -
+ #### Returns + ---------------- + One of the following: + - **Success**: + - `listLength()`: Number - the new length of the list item + - `toString()`: String - add the listLength - + - **Error**: + - See [response objects](./response-objects.md) for specific information. -### ListPushBack -Push a value to the end of a list item. This is exactly like passing just one value to [ListConcatenateBack](#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](./collection-ttl.md) | 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](#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](./response-objects.md) for specific information. +
+ +--- - +
- +
-### ListPushFront -Push a value to the beginning of a list item. Just like [ListPushBack](#listpushback), but to the front. + ### ListPushFront -| 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](./collection-ttl.md) | 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](#truncate-to-size). | + Push a value to the beginning of a list item. Just like [ListPushBack](#listpushback), but to the front. -
- Method response object + #### Parameters + ---------------- + - **cacheName** - *String*: Name of the cache. + - **listName** - *String*: Name of the list item to be set. + - **value** - *String | Bytes*: Value to be added. + - **ttl** - *[CollectionTTL object](./collection-ttl.md)*: 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](#truncate-to-size). -* Success - * `listLength()`: Number - the new length of the list - * `toString()`: String - add the listLength -* Error + #### Returns + ---------------- + One of the following: + - **Success**: + - `listLength()`: Number - the new length of the list item + - `toString()`: String - add the listLength -See [response objects](./response-objects.md) for specific information. + - **Error**: + - See [response objects](./response-objects.md) for specific information. -
+
- +
-### 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 + ### ListRemoveValue -See [response objects](./response-objects.md) for specific information. + Remove all elements in a list item equal to a particular value. -
+ #### Parameters + ---------------- + - **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. - + #### Returns + ---------------- + One of the following: + - **Success**: even if the value does not exist. -### ListRetain + - **Error**: + - See [response objects](./response-objects.md) for specific information. -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](./collection-ttl.md) | 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 + ### ListRetain -See [response objects](./response-objects.md) for specific information. + 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. - + #### Parameters + ---------------- + - **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](./collection-ttl.md)*: TTL for the list item in cache. This TTL takes precedence over the TTL used when initializing a cache connection client. + #### Returns + ---------------- + One of the following: + - **Success**: even if the value does not exist. + + - **Error**: + - See [response objects](./response-objects.md) for specific information. + + + +
+ + + +
+ + + +--- ## Truncate to size