From 41105834527ca2742a7f4a88f150a5781118e856 Mon Sep 17 00:00:00 2001 From: Vasco Santos Date: Fri, 18 Nov 2022 11:14:29 +0100 Subject: [PATCH 1/3] feat!: add support for list pagination in list capability invocations BREAKING CHANGE: store/list and upload/list types now require nb object with optional properties --- packages/access-client/src/capabilities/store.js | 12 ++++++++++++ .../access-client/src/capabilities/upload.js | 16 ++++++++++++++-- .../test/capabilities/upload.test.js | 4 ++++ 3 files changed, 30 insertions(+), 2 deletions(-) diff --git a/packages/access-client/src/capabilities/store.js b/packages/access-client/src/capabilities/store.js index 934cbf666..92d0eb282 100644 --- a/packages/access-client/src/capabilities/store.js +++ b/packages/access-client/src/capabilities/store.js @@ -140,6 +140,18 @@ export const list = base.derive({ * be stored. */ with: URI.match({ protocol: 'did:' }), + nb: { + /** + * Item where a previous list operation stopped, inclusive of the previous + * result set. Use this value to start a new operation, inorder to paginate + * list. + */ + cursor: Schema.string().optional(), + /** + * Size of the page being requested to list. + */ + size: Schema.integer().optional(), + }, derives: (claimed, delegated) => { if (claimed.with !== delegated.with) { return new Failure( diff --git a/packages/access-client/src/capabilities/upload.js b/packages/access-client/src/capabilities/upload.js index eb1f25250..16e044f20 100644 --- a/packages/access-client/src/capabilities/upload.js +++ b/packages/access-client/src/capabilities/upload.js @@ -8,7 +8,7 @@ * * @module */ -import { capability, Link, URI } from '@ucanto/validator' + import { capability, Link, URI, Schema } from '@ucanto/validator' import { codec as CAR } from '@ucanto/transport/car' import { equalWith, fail, equal } from './utils.js' import { top } from './top.js' @@ -140,6 +140,18 @@ export const list = base.derive({ to: capability({ can: 'upload/list', with: URI.match({ protocol: 'did:' }), + nb: { + /** + * Item where a previous list operation stopped, inclusive of the previous + * result set. Use this value to start a new operation, inorder to paginate + * list. + */ + cursor: Schema.string().optional(), + /** + * Size of the page being requested to list. + */ + size: Schema.integer().optional(), + }, }), /** * `upload/list` can be derived from the `upload/*` & `*` capability @@ -150,4 +162,4 @@ export const list = base.derive({ // ⚠️ We export imports here so they are not omited in generated typedefs // @see https://github.com/microsoft/TypeScript/issues/51548 -export { Link } +export { Link, Schema } diff --git a/packages/access-client/test/capabilities/upload.test.js b/packages/access-client/test/capabilities/upload.test.js index 31422a8a1..0fb3fdc1d 100644 --- a/packages/access-client/test/capabilities/upload.test.js +++ b/packages/access-client/test/capabilities/upload.test.js @@ -328,6 +328,7 @@ describe('upload capabilities', function () { audience: w3, with: account.did(), proofs: [await any], + nb: {}, }) const result = await access(await list.delegate(), { @@ -357,6 +358,7 @@ describe('upload capabilities', function () { issuer: bob, with: account.did(), proofs: [await upload.delegate()], + nb: {}, }) const result = await access(await list.delegate(), { @@ -379,6 +381,7 @@ describe('upload capabilities', function () { audience: bob, with: account.did(), proofs: [await any], + nb: {}, }) const list = Upload.list.invoke({ @@ -386,6 +389,7 @@ describe('upload capabilities', function () { issuer: bob, with: account.did(), proofs: [await delegation.delegate()], + nb: {}, }) const result = await access(await list.delegate(), { From d8f479e0b4efb4dea666684a6c2c7d172ab6c486 Mon Sep 17 00:00:00 2001 From: Vasco Santos Date: Mon, 21 Nov 2022 11:51:10 +0100 Subject: [PATCH 2/3] chore: apply suggestions from code review Co-authored-by: Alan Shaw --- packages/access-client/src/capabilities/store.js | 4 ++-- packages/access-client/src/capabilities/upload.js | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/access-client/src/capabilities/store.js b/packages/access-client/src/capabilities/store.js index 92d0eb282..c004daedf 100644 --- a/packages/access-client/src/capabilities/store.js +++ b/packages/access-client/src/capabilities/store.js @@ -143,12 +143,12 @@ export const list = base.derive({ nb: { /** * Item where a previous list operation stopped, inclusive of the previous - * result set. Use this value to start a new operation, inorder to paginate + * result set. Use this value to start a new operation, in order to paginate * list. */ cursor: Schema.string().optional(), /** - * Size of the page being requested to list. + * Maximum number of items per page. */ size: Schema.integer().optional(), }, diff --git a/packages/access-client/src/capabilities/upload.js b/packages/access-client/src/capabilities/upload.js index 16e044f20..9af1c5368 100644 --- a/packages/access-client/src/capabilities/upload.js +++ b/packages/access-client/src/capabilities/upload.js @@ -143,12 +143,12 @@ export const list = base.derive({ nb: { /** * Item where a previous list operation stopped, inclusive of the previous - * result set. Use this value to start a new operation, inorder to paginate + * result set. Use this value to start a new operation, in order to paginate * list. */ cursor: Schema.string().optional(), /** - * Size of the page being requested to list. + * Maximum number of items per page. */ size: Schema.integer().optional(), }, From 2b200859363c62f6229374aedfca932ab832df06 Mon Sep 17 00:00:00 2001 From: Vasco Santos Date: Mon, 21 Nov 2022 12:00:31 +0100 Subject: [PATCH 3/3] fix: make cursor docs more generic --- packages/access-client/src/capabilities/store.js | 5 ++--- packages/access-client/src/capabilities/upload.js | 7 +++---- 2 files changed, 5 insertions(+), 7 deletions(-) diff --git a/packages/access-client/src/capabilities/store.js b/packages/access-client/src/capabilities/store.js index c004daedf..08d00550f 100644 --- a/packages/access-client/src/capabilities/store.js +++ b/packages/access-client/src/capabilities/store.js @@ -142,9 +142,8 @@ export const list = base.derive({ with: URI.match({ protocol: 'did:' }), nb: { /** - * Item where a previous list operation stopped, inclusive of the previous - * result set. Use this value to start a new operation, in order to paginate - * list. + * A pointer that can be moved back and forth on the list. + * It can be used to paginate a list for instance. */ cursor: Schema.string().optional(), /** diff --git a/packages/access-client/src/capabilities/upload.js b/packages/access-client/src/capabilities/upload.js index 9af1c5368..840ba2634 100644 --- a/packages/access-client/src/capabilities/upload.js +++ b/packages/access-client/src/capabilities/upload.js @@ -8,7 +8,7 @@ * * @module */ - import { capability, Link, URI, Schema } from '@ucanto/validator' +import { capability, Link, URI, Schema } from '@ucanto/validator' import { codec as CAR } from '@ucanto/transport/car' import { equalWith, fail, equal } from './utils.js' import { top } from './top.js' @@ -142,9 +142,8 @@ export const list = base.derive({ with: URI.match({ protocol: 'did:' }), nb: { /** - * Item where a previous list operation stopped, inclusive of the previous - * result set. Use this value to start a new operation, in order to paginate - * list. + * A pointer that can be moved back and forth on the list. + * It can be used to paginate a list for instance. */ cursor: Schema.string().optional(), /**