feat: add pre caveat to store/list and upload/list (#423)

Per storacha/w3ui#143 we'd like to give clients a way to get the previous page of results rather than the next page. This change introduces a `pre` caveat which, when set to true, will return the page of results preceding `cursor`. I considered calling this `reverse` or `rev` but I think that implies that results will be returned sorted in reverse, which is not the intent. --------- Co-authored-by: Alan Shaw <alan.shaw@protocol.ai>
storacha · Feb 10, 2023 · 9cce414 · 9cce414
1 parent e0f67e8
commit 9cce414
Show file tree

Hide file tree

Showing 6 changed files with 22 additions and 0 deletions.
diff --git a/packages/capabilities/src/store.js b/packages/capabilities/src/store.js
@@ -150,6 +150,10 @@ export const list = base.derive({
        * Maximum number of items per page.
        */
       size: Schema.integer().optional(),
+      /**
+       * If true, return page of results preceding cursor. Defaults to false.
+       */
+      pre: Schema.boolean().optional(),
     },
     derives: (claimed, delegated) => {
       if (claimed.with !== delegated.with) {

diff --git a/packages/capabilities/src/upload.js b/packages/capabilities/src/upload.js
@@ -150,6 +150,10 @@ export const list = base.derive({
        * Maximum number of items per page.
        */
       size: Schema.integer().optional(),
+      /**
+       * If true, return page of results preceding cursor. Defaults to false.
+       */
+      pre: Schema.boolean().optional(),
     },
   }),
   /**

diff --git a/packages/upload-client/src/store.js b/packages/upload-client/src/store.js
@@ -136,6 +136,7 @@ export async function list(
       nb: {
         cursor: options.cursor,
         size: options.size,
+        pre: options.pre,
       },
     })
     .execute(conn)

diff --git a/packages/upload-client/src/types.ts b/packages/upload-client/src/types.ts
@@ -174,6 +174,10 @@ export interface Pageable {
    * Maximum number of items to return.
    */
   size?: number
+  /**
+   * If true, return page of results preceding cursor. Defaults to false.
+   */
+  pre?: boolean
 }
 
 export interface RequestOptions extends Retryable, Abortable, Connectable {}

diff --git a/packages/upload-client/src/upload.js b/packages/upload-client/src/upload.js
@@ -99,6 +99,7 @@ export async function list(
       nb: {
         cursor: options.cursor,
         size: options.size,
+        pre: options.pre,
       },
     })
     .execute(conn)

diff --git a/spec/capabilities.md b/spec/capabilities.md
@@ -199,11 +199,13 @@ The `with` field of the invocation must be set to the DID of the memory space to
 
 `cursor` can be set to start listing from an item in the middle of the list. Its value should be a `cursor` returned by a previous invocation of `store/list`
 `size` can be set to change the number of items returned by an `store/list` invocation
+`pre` can be set to `true` to return the page of results preceding `cursor` rather than the results after `cursor`. Defaults to `false`.
 
 | field       | value                    | required? | context                                                         |
 | ----------- | ------------------------ | --------- | --------------------------------------------------------------- |
 | `nb.cursor` | string                   | ❌         | A cursor returned by a previous invocation                      |
 | `nb.size`   | integer                  | ❌         | The maximum number of results to return                         |
+| `nb.pre`    | boolean                  | ❌         | If true, return the page of results preceeding the cursor |
 
 ## `upload/` namespace
 
@@ -286,12 +288,18 @@ The `with` field of the invocation must be set to the DID of the memory space to
 
 `cursor` can be set to start listing from an item in the middle of the list. Its value should be a `cursor` returned by a previous invocation of `upload/list`
 `size` can be set to change the number of items returned by an `upload/list` invocation
+`pre` can be set to `true` to return the page of results preceding `cursor` rather than the results after `cursor`. Defaults to `false`.
 
 | field       | value                    | required? | context                                                         |
 | ----------- | ------------------------ | --------- | --------------------------------------------------------------- |
 | `nb.cursor` | string                   | ❌         | A cursor returned by a previous invocation                      |
 | `nb.size`   | integer                  | ❌         | The maximum number of results to return                         |
 
+| field       | value                    | required? | context                                                         |
+| ----------- | ------------------------ | --------- | --------------------------------------------------------------- |
+| `nb.cursor` | string                   | ❌         | A cursor returned by a previous invocation                      |
+| `nb.size`   | integer                  | ❌         | The maximum number of results to return                         |
+| `nb.pre`    | boolean                  | ❌         | If true, return the page of results preceeding the cursor |
 ## `voucher/` namespace
 
 TODO: more voucher docs when implementation details settle down a bit.