From 2e6b24d53704cc15714df9965399f2b88ff8beb5 Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Thu, 2 Jun 2022 12:02:00 +0200 Subject: [PATCH] clean up api report for search-backend-node package Signed-off-by: Emma Indal --- plugins/search-backend-node/api-report.md | 43 ++++++++----------- .../search-backend-node/src/IndexBuilder.ts | 9 +++- plugins/search-backend-node/src/Scheduler.ts | 10 +++-- .../NewlineDelimitedJsonCollatorFactory.ts | 8 ++-- .../src/engines/LunrSearchEngine.ts | 9 ++-- .../src/engines/LunrSearchEngineIndexer.ts | 3 +- .../src/indexing/BatchSearchEngineIndexer.ts | 5 ++- .../src/indexing/DecoratorBase.ts | 2 +- .../src/test-utils/TestPipeline.ts | 4 +- plugins/search-backend-node/src/types.ts | 7 +-- 10 files changed, 54 insertions(+), 46 deletions(-) diff --git a/plugins/search-backend-node/api-report.md b/plugins/search-backend-node/api-report.md index 8c10b031a2..7649bc5d0f 100644 --- a/plugins/search-backend-node/api-report.md +++ b/plugins/search-backend-node/api-report.md @@ -24,7 +24,7 @@ import { Transform } from 'stream'; import { UrlReader } from '@backstage/backend-common'; import { Writable } from 'stream'; -// @beta +// @public export abstract class BatchSearchEngineIndexer extends Writable { constructor(options: BatchSearchEngineOptions); abstract finalize(): Promise; @@ -32,19 +32,19 @@ export abstract class BatchSearchEngineIndexer extends Writable { abstract initialize(): Promise; } -// @beta (undocumented) +// @public export type BatchSearchEngineOptions = { batchSize: number; }; -// @beta (undocumented) +// @public export type ConcreteLunrQuery = { lunrQueryBuilder: lunr_2.Index.QueryBuilder; documentTypes?: string[]; pageSize: number; }; -// @beta +// @public export abstract class DecoratorBase extends Transform { constructor(); abstract decorate( @@ -54,7 +54,7 @@ export abstract class DecoratorBase extends Transform { abstract initialize(): Promise; } -// @beta (undocumented) +// @public export class IndexBuilder { constructor({ logger, searchEngine }: IndexBuilderOptions); addCollator({ factory, schedule }: RegisterCollatorParameters): void; @@ -62,22 +62,20 @@ export class IndexBuilder { build(): Promise<{ scheduler: Scheduler; }>; - // (undocumented) getDocumentTypes(): Record; - // (undocumented) getSearchEngine(): SearchEngine; } -// @beta (undocumented) +// @public export type IndexBuilderOptions = { searchEngine: SearchEngine; logger: Logger; }; -// @beta (undocumented) +// @public export type LunrQueryTranslator = (query: SearchQuery) => ConcreteLunrQuery; -// @beta (undocumented) +// @public export class LunrSearchEngine implements SearchEngine { constructor({ logger }: { logger: Logger }); // (undocumented) @@ -100,7 +98,7 @@ export class LunrSearchEngine implements SearchEngine { protected translator: QueryTranslator; } -// @beta (undocumented) +// @public export class LunrSearchEngineIndexer extends BatchSearchEngineIndexer { constructor(); // (undocumented) @@ -115,7 +113,7 @@ export class LunrSearchEngineIndexer extends BatchSearchEngineIndexer { initialize(): Promise; } -// @beta +// @public export class NewlineDelimitedJsonCollatorFactory implements DocumentCollatorFactory { @@ -131,7 +129,7 @@ export class NewlineDelimitedJsonCollatorFactory readonly visibilityPermission: Permission | undefined; } -// @beta (undocumented) +// @public export type NewlineDelimitedJsonCollatorFactoryOptions = { type: string; searchPattern: string; @@ -140,18 +138,18 @@ export type NewlineDelimitedJsonCollatorFactoryOptions = { visibilityPermission?: Permission; }; -// @beta +// @public export interface RegisterCollatorParameters { factory: DocumentCollatorFactory; schedule: TaskRunner; } -// @beta +// @public export interface RegisterDecoratorParameters { factory: DocumentDecoratorFactory; } -// @beta (undocumented) +// @public export class Scheduler { constructor({ logger }: { logger: Logger }); addToSchedule({ id, task, scheduledRunner }: ScheduleTaskParameters): void; @@ -160,25 +158,22 @@ export class Scheduler { } // @public -export interface ScheduleTaskParameters { - // (undocumented) +export type ScheduleTaskParameters = { id: string; - // (undocumented) - scheduledRunner: TaskRunner; - // (undocumented) task: TaskFunction; -} + scheduledRunner: TaskRunner; +}; export { SearchEngine }; -// @beta +// @public export class TestPipeline { execute(): Promise; withDocuments(documents: IndexableDocument[]): TestPipeline; static withSubject(subject: Readable | Transform | Writable): TestPipeline; } -// @beta +// @public export type TestPipelineResult = { error: unknown; documents: IndexableDocument[]; diff --git a/plugins/search-backend-node/src/IndexBuilder.ts b/plugins/search-backend-node/src/IndexBuilder.ts index 2131c6937d..3e1dae1c2f 100644 --- a/plugins/search-backend-node/src/IndexBuilder.ts +++ b/plugins/search-backend-node/src/IndexBuilder.ts @@ -28,7 +28,8 @@ import { } from './types'; /** - * @beta + * Used for adding collators, decorators and compile them into tasks which are added to a scheduler returned to the caller. + * @public */ export class IndexBuilder { private collators: Record; @@ -45,10 +46,16 @@ export class IndexBuilder { this.searchEngine = searchEngine; } + /** + * Responsible for returning the registered search engine. + */ getSearchEngine(): SearchEngine { return this.searchEngine; } + /** + * Responsible for returning the registered document types. + */ getDocumentTypes(): Record { return this.documentTypes; } diff --git a/plugins/search-backend-node/src/Scheduler.ts b/plugins/search-backend-node/src/Scheduler.ts index 9f3d95b112..404823c53a 100644 --- a/plugins/search-backend-node/src/Scheduler.ts +++ b/plugins/search-backend-node/src/Scheduler.ts @@ -24,16 +24,18 @@ type TaskEnvelope = { }; /** - * @public ScheduleTaskParameters + * ScheduleTaskParameters + * @public */ -export interface ScheduleTaskParameters { +export type ScheduleTaskParameters = { id: string; task: TaskFunction; scheduledRunner: TaskRunner; -} +}; /** - * @beta + * Scheduler responsible for all search tasks. + * @public */ export class Scheduler { private logger: Logger; diff --git a/plugins/search-backend-node/src/collators/NewlineDelimitedJsonCollatorFactory.ts b/plugins/search-backend-node/src/collators/NewlineDelimitedJsonCollatorFactory.ts index 42c43818f1..fde6b9412a 100644 --- a/plugins/search-backend-node/src/collators/NewlineDelimitedJsonCollatorFactory.ts +++ b/plugins/search-backend-node/src/collators/NewlineDelimitedJsonCollatorFactory.ts @@ -23,7 +23,8 @@ import { Readable } from 'stream'; import { Logger } from 'winston'; /** - * @beta + * Options for instansiate NewlineDelimitedJsonCollatorFactory + * @public */ export type NewlineDelimitedJsonCollatorFactoryOptions = { type: string; @@ -60,15 +61,13 @@ export type NewlineDelimitedJsonCollatorFactoryOptions = { * }); * ``` * - * @beta + * @public */ export class NewlineDelimitedJsonCollatorFactory implements DocumentCollatorFactory { - /** {@inheritDoc @backstage/plugin-search-common#DocumentCollatorFactory."type"} */ readonly type: string; - /** {@inheritDoc @backstage/plugin-search-common#DocumentCollatorFactory.visibilityPermission} */ public readonly visibilityPermission: Permission | undefined; private constructor( @@ -123,7 +122,6 @@ export class NewlineDelimitedJsonCollatorFactory } } - /** {@inheritDoc @backstage/plugin-search-common#DocumentCollatorFactory.getCollator} */ async getCollator(): Promise { // Search for files matching the given pattern. const lastUrl = await this.lastUrl(); diff --git a/plugins/search-backend-node/src/engines/LunrSearchEngine.ts b/plugins/search-backend-node/src/engines/LunrSearchEngine.ts index 656cd3e1eb..4a5f4cdd18 100644 --- a/plugins/search-backend-node/src/engines/LunrSearchEngine.ts +++ b/plugins/search-backend-node/src/engines/LunrSearchEngine.ts @@ -27,7 +27,8 @@ import { Logger } from 'winston'; import { LunrSearchEngineIndexer } from './LunrSearchEngineIndexer'; /** - * @beta + * Type of translated query for the Lunr Search Engine. + * @public */ export type ConcreteLunrQuery = { lunrQueryBuilder: lunr.Index.QueryBuilder; @@ -41,12 +42,14 @@ type LunrResultEnvelope = { }; /** - * @beta + * Translator repsonsible for translating search term and filters to a query that the Lunr Search Engine understands. + * @public */ export type LunrQueryTranslator = (query: SearchQuery) => ConcreteLunrQuery; /** - * @beta + * Lunr specific search engine implementation. + * @public */ export class LunrSearchEngine implements SearchEngine { protected lunrIndices: Record = {}; diff --git a/plugins/search-backend-node/src/engines/LunrSearchEngineIndexer.ts b/plugins/search-backend-node/src/engines/LunrSearchEngineIndexer.ts index 4da27be94b..e723957077 100644 --- a/plugins/search-backend-node/src/engines/LunrSearchEngineIndexer.ts +++ b/plugins/search-backend-node/src/engines/LunrSearchEngineIndexer.ts @@ -19,7 +19,8 @@ import lunr from 'lunr'; import { BatchSearchEngineIndexer } from '../indexing'; /** - * @beta + * Lunr specific search engine indexer + * @public */ export class LunrSearchEngineIndexer extends BatchSearchEngineIndexer { private schemaInitialized = false; diff --git a/plugins/search-backend-node/src/indexing/BatchSearchEngineIndexer.ts b/plugins/search-backend-node/src/indexing/BatchSearchEngineIndexer.ts index 6070a577ed..24b90c2a59 100644 --- a/plugins/search-backend-node/src/indexing/BatchSearchEngineIndexer.ts +++ b/plugins/search-backend-node/src/indexing/BatchSearchEngineIndexer.ts @@ -19,7 +19,8 @@ import { IndexableDocument } from '@backstage/plugin-search-common'; import { Writable } from 'stream'; /** - * @beta + * Options for {@link BatchSearchEngineIndexer} + * @public */ export type BatchSearchEngineOptions = { batchSize: number; @@ -28,7 +29,7 @@ export type BatchSearchEngineOptions = { /** * Base class encapsulating batch-based stream processing. Useful as a base * class for search engine indexers. - * @beta + * @public */ export abstract class BatchSearchEngineIndexer extends Writable { private batchSize: number; diff --git a/plugins/search-backend-node/src/indexing/DecoratorBase.ts b/plugins/search-backend-node/src/indexing/DecoratorBase.ts index 0541ab82d7..bcf5729674 100644 --- a/plugins/search-backend-node/src/indexing/DecoratorBase.ts +++ b/plugins/search-backend-node/src/indexing/DecoratorBase.ts @@ -21,7 +21,7 @@ import { Transform } from 'stream'; /** * Base class encapsulating simple async transformations. Useful as a base * class for Backstage search decorators. - * @beta + * @public */ export abstract class DecoratorBase extends Transform { private initialized: Promise; diff --git a/plugins/search-backend-node/src/test-utils/TestPipeline.ts b/plugins/search-backend-node/src/test-utils/TestPipeline.ts index 688cab55be..00dd9b3755 100644 --- a/plugins/search-backend-node/src/test-utils/TestPipeline.ts +++ b/plugins/search-backend-node/src/test-utils/TestPipeline.ts @@ -19,7 +19,7 @@ import { pipeline, Readable, Transform, Writable } from 'stream'; /** * Object resolved after a test pipeline is executed. - * @beta + * @public */ export type TestPipelineResult = { /** @@ -37,7 +37,7 @@ export type TestPipelineResult = { /** * Test utility for Backstage Search collators, decorators, and indexers. - * @beta + * @public */ export class TestPipeline { private collator?: Readable; diff --git a/plugins/search-backend-node/src/types.ts b/plugins/search-backend-node/src/types.ts index a92398e8c8..dfcf4d12ce 100644 --- a/plugins/search-backend-node/src/types.ts +++ b/plugins/search-backend-node/src/types.ts @@ -23,7 +23,8 @@ import { import { Logger } from 'winston'; /** - * @beta + * Options required to instantiate the index builder. + * @public */ export type IndexBuilderOptions = { searchEngine: SearchEngine; @@ -32,7 +33,7 @@ export type IndexBuilderOptions = { /** * Parameters required to register a collator. - * @beta + * @public */ export interface RegisterCollatorParameters { /** @@ -48,7 +49,7 @@ export interface RegisterCollatorParameters { /** * Parameters required to register a decorator - * @beta + * @public */ export interface RegisterDecoratorParameters { /**