From 296d4f6179c81433c4a763365dfc2e7194774b6e Mon Sep 17 00:00:00 2001 From: Vincenzo Scamporlino Date: Thu, 23 Jun 2022 21:21:45 +0200 Subject: [PATCH] Improve api reports Signed-off-by: Vincenzo Scamporlino --- packages/catalog-client/api-report.md | 57 +++++++++++++++++-- packages/catalog-client/src/CatalogClient.ts | 2 + packages/catalog-client/src/index.ts | 1 - packages/catalog-client/src/types/api.ts | 14 ++++- packages/catalog-client/src/types/index.ts | 2 + .../service/DefaultEntitiesCatalog.test.ts | 10 ++-- 6 files changed, 74 insertions(+), 12 deletions(-) diff --git a/packages/catalog-client/api-report.md b/packages/catalog-client/api-report.md index a81314308b..f612407b1d 100644 --- a/packages/catalog-client/api-report.md +++ b/packages/catalog-client/api-report.md @@ -58,6 +58,11 @@ export interface CatalogApi { locationRef: string, options?: CatalogRequestOptions, ): Promise; + // @alpha + getPaginatedEntities?( + request?: GetPaginatedEntitiesRequest, + options?: CatalogRequestOptions, + ): Promise; refreshEntity( entityRef: string, options?: CatalogRequestOptions, @@ -124,6 +129,11 @@ export class CatalogClient implements CatalogApi { locationRef: string, options?: CatalogRequestOptions, ): Promise; + // @alpha + getPaginatedEntities?( + request?: GetPaginatedEntitiesRequest, + options?: CatalogRequestOptions, + ): Promise; refreshEntity( entityRef: string, options?: CatalogRequestOptions, @@ -149,6 +159,12 @@ export interface CatalogRequestOptions { token?: string; } +// @public +export type EntitiesFilter = + | Record[] + | Record + | undefined; + // @public export const ENTITY_STATUS_CATALOG_PROCESSING_TYPE = 'backstage.io/catalog-processing'; @@ -219,10 +235,7 @@ export interface GetEntityAncestorsResponse { // @public export interface GetEntityFacetsRequest { facets: string[]; - filter?: - | Record[] - | Record - | undefined; + filter?: EntitiesFilter; } // @public @@ -236,6 +249,42 @@ export interface GetEntityFacetsResponse { >; } +// @alpha +export type GetPaginatedEntitiesCursorRequest = { + fields?: string[]; + limit?: number; + cursor: string; +}; + +// @alpha +export type GetPaginatedEntitiesInitialRequest = + | { + fields?: string[]; + limit?: number; + filter?: EntitiesFilter; + sortField?: string; + query?: string; + sortFieldOrder?: 'asc' | 'desc'; + } + | undefined; + +// @alpha +export type GetPaginatedEntitiesRequest = + | GetPaginatedEntitiesInitialRequest + | GetPaginatedEntitiesCursorRequest; + +// @alpha +export type GetPaginatedEntitiesResponse = { + entities: Entity[]; + totalItems: number; + next?( + request?: Omit, + ): Promise; + prev?( + request?: Omit, + ): Promise; +}; + // @public type Location_2 = { id: string; diff --git a/packages/catalog-client/src/CatalogClient.ts b/packages/catalog-client/src/CatalogClient.ts index 03fdd600e9..5846430a78 100644 --- a/packages/catalog-client/src/CatalogClient.ts +++ b/packages/catalog-client/src/CatalogClient.ts @@ -207,6 +207,8 @@ export class CatalogClient implements CatalogApi { /** * {@inheritdoc CatalogApi.getPaginatedEntities} + * + * @alpha */ async getPaginatedEntities?( request?: GetPaginatedEntitiesRequest, diff --git a/packages/catalog-client/src/index.ts b/packages/catalog-client/src/index.ts index f0b10a3eef..2e81942c2f 100644 --- a/packages/catalog-client/src/index.ts +++ b/packages/catalog-client/src/index.ts @@ -22,4 +22,3 @@ export { CatalogClient } from './CatalogClient'; export * from './types'; -export * from './utils'; diff --git a/packages/catalog-client/src/types/api.ts b/packages/catalog-client/src/types/api.ts index 1390a0576e..b273eb9e13 100644 --- a/packages/catalog-client/src/types/api.ts +++ b/packages/catalog-client/src/types/api.ts @@ -356,6 +356,11 @@ export type AddLocationRequest = { dryRun?: boolean; }; +/** + * Used for filtering entities that match the given patterns. + * + * @public + */ export type EntitiesFilter = | Record[] | Record @@ -481,12 +486,12 @@ export interface CatalogApi { /** * Gets paginated entities from the catalog. - * The method takes - * @alpha + * * @remarks * * Example: * + * ``` * const response = await catalogClient.getPaginatedEntities({ * filter: [{ kind: 'group' }], * limit: 20, @@ -494,6 +499,7 @@ export interface CatalogApi { * sortField: 'metadata.name', * sortFieldOrder: 'asc' * }); + * ``` * * this will match all entities of type group having a name starting * with 'A', ordered by name ascending. @@ -502,12 +508,16 @@ export interface CatalogApi { * more than 20 entities exist, the response will contain a next function, invocable * using: * + * ``` * const secondBatchResponse = await response.next({ limit: 20 }); + * ``` * * secondBatchResponse will contain the next batch of maximum 20 entities, together * with a prev function useful for navigating backwards and a next function * in case more entities matching the filters of the first request are present in the catalog. * + * @alpha + * * @param request - Request parameters * @param options - Additional options */ diff --git a/packages/catalog-client/src/types/index.ts b/packages/catalog-client/src/types/index.ts index 7da07979fc..e85b86f4af 100644 --- a/packages/catalog-client/src/types/index.ts +++ b/packages/catalog-client/src/types/index.ts @@ -25,6 +25,7 @@ export type { EntityOrderQuery, GetEntitiesByRefsRequest, GetEntitiesByRefsResponse, + EntitiesFilter, GetEntitiesRequest, GetEntitiesResponse, GetEntityAncestorsRequest, @@ -35,6 +36,7 @@ export type { ValidateEntityResponse, GetPaginatedEntitiesCursorRequest, GetPaginatedEntitiesInitialRequest, + GetPaginatedEntitiesRequest, GetPaginatedEntitiesResponse, } from './api'; export { ENTITY_STATUS_CATALOG_PROCESSING_TYPE } from './status'; diff --git a/plugins/catalog-backend/src/service/DefaultEntitiesCatalog.test.ts b/plugins/catalog-backend/src/service/DefaultEntitiesCatalog.test.ts index 35c1f7153b..8f043a594b 100644 --- a/plugins/catalog-backend/src/service/DefaultEntitiesCatalog.test.ts +++ b/plugins/catalog-backend/src/service/DefaultEntitiesCatalog.test.ts @@ -717,7 +717,7 @@ describe('DefaultEntitiesCatalog', () => { .map(e => addEntityToSearch(knex, e)), ); - const catalog = new DefaultEntitiesCatalog(knex); + const catalog = new DefaultEntitiesCatalog(knex, stitcher); const filter = { key: 'spec.should_include_this', @@ -869,7 +869,7 @@ describe('DefaultEntitiesCatalog', () => { .map(e => addEntityToSearch(knex, e)), ); - const catalog = new DefaultEntitiesCatalog(knex); + const catalog = new DefaultEntitiesCatalog(knex, stitcher); const filter = { key: 'spec.should_include_this', @@ -1023,7 +1023,7 @@ describe('DefaultEntitiesCatalog', () => { .map(e => addEntityToSearch(knex, e)), ); - const catalog = new DefaultEntitiesCatalog(knex); + const catalog = new DefaultEntitiesCatalog(knex, stitcher); const filter = { key: 'spec.should_include_this', @@ -1064,7 +1064,7 @@ describe('DefaultEntitiesCatalog', () => { ), ); - const catalog = new DefaultEntitiesCatalog(knex); + const catalog = new DefaultEntitiesCatalog(knex, stitcher); const request: PaginatedEntitiesInitialRequest = { limit: 0, @@ -1346,7 +1346,7 @@ describe('DefaultEntitiesCatalog', () => { ], }); - const catalog = new DefaultEntitiesCatalog(knex); + const catalog = new DefaultEntitiesCatalog(knex, stitcher); await expect( catalog.facets({