From 9cce414e09ed9f46fe0eda1258b0ebe8efe42ede Mon Sep 17 00:00:00 2001 From: Travis Vachon Date: Fri, 10 Feb 2023 11:09:53 +0800 Subject: [PATCH] feat: add `pre` caveat to `store/list` and `upload/list` (#423) Per https://github.com/web3-storage/w3ui/issues/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 --- packages/capabilities/src/store.js | 4 ++++ packages/capabilities/src/upload.js | 4 ++++ packages/upload-client/src/store.js | 1 + packages/upload-client/src/types.ts | 4 ++++ packages/upload-client/src/upload.js | 1 + spec/capabilities.md | 8 ++++++++ 6 files changed, 22 insertions(+) diff --git a/packages/capabilities/src/store.js b/packages/capabilities/src/store.js index 1f79de0ee..5f153f87b 100644 --- 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 index a15f3152c..7fcfaa056 100644 --- 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 index c225faa86..321b8c18a 100644 --- 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 index 670f6d488..7c89cd888 100644 --- 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 index 2f1748f1e..41f15eac0 100644 --- 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 index c8f75e4e4..bd3e3dcd0 100644 --- 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.