From 0afede342d39dc7b3e0467f979f93a5e5e798ee3 Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Thu, 2 Jun 2022 13:10:40 +0200 Subject: [PATCH] clean up api report for search-backend-module-elasticsearch package Signed-off-by: Emma Indal --- .../api-report.md | 127 ++++++++++++++---- .../src/engines/ElasticSearchClientOptions.ts | 20 ++- .../src/engines/ElasticSearchSearchEngine.ts | 17 ++- .../ElasticSearchSearchEngineIndexer.ts | 8 ++ .../src/engines/index.ts | 9 ++ .../src/index.ts | 8 ++ 6 files changed, 160 insertions(+), 29 deletions(-) diff --git a/plugins/search-backend-module-elasticsearch/api-report.md b/plugins/search-backend-module-elasticsearch/api-report.md index 7ef026745f..77ce0af61e 100644 --- a/plugins/search-backend-module-elasticsearch/api-report.md +++ b/plugins/search-backend-module-elasticsearch/api-report.md @@ -15,17 +15,44 @@ import { Logger } from 'winston'; import { SearchEngine } from '@backstage/plugin-search-common'; import { SearchQuery } from '@backstage/plugin-search-common'; -// Warning: (ae-missing-release-tag) "ElasticSearchClientOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@backstage/plugin-search-backend-module-elasticsearch" does not have an export "ElasticSearchEngine" -// +// @public +export type ConcreteElasticSearchQuery = { + documentTypes?: string[]; + elasticSearchQuery: Object; + pageSize: number; +}; + +// @public (undocumented) +export interface ElasticSearchAgentOptions { + // (undocumented) + keepAlive?: boolean; + // (undocumented) + keepAliveMsecs?: number; + // (undocumented) + maxFreeSockets?: number; + // (undocumented) + maxSockets?: number; +} + +// @public (undocumented) +export type ElasticSearchAuth = + | { + username: string; + password: string; + } + | { + apiKey: + | string + | { + id: string; + api_key: string; + }; + }; + // @public export interface ElasticSearchClientOptions { - // Warning: (ae-forgotten-export) The symbol "ElasticSearchAgentOptions" needs to be exported by the entry point index.d.ts - // // (undocumented) agent?: ElasticSearchAgentOptions | ((opts?: any) => unknown) | false; - // Warning: (ae-forgotten-export) The symbol "ElasticSearchAuth" needs to be exported by the entry point index.d.ts - // // (undocumented) auth?: ElasticSearchAuth; // (undocumented) @@ -36,8 +63,6 @@ export interface ElasticSearchClientOptions { }; // (undocumented) compression?: 'gzip'; - // Warning: (ae-forgotten-export) The symbol "ElasticSearchConnectionConstructor" needs to be exported by the entry point index.d.ts - // // (undocumented) Connection?: ElasticSearchConnectionConstructor; // (undocumented) @@ -50,8 +75,6 @@ export interface ElasticSearchClientOptions { maxRetries?: number; // (undocumented) name?: string | symbol; - // Warning: (ae-forgotten-export) The symbol "ElasticSearchNodeOptions" needs to be exported by the entry point index.d.ts - // // (undocumented) node?: | string @@ -92,12 +115,28 @@ export interface ElasticSearchClientOptions { ssl?: ConnectionOptions; // (undocumented) suggestCompression?: boolean; - // Warning: (ae-forgotten-export) The symbol "ElasticSearchTransportConstructor" needs to be exported by the entry point index.d.ts - // // (undocumented) Transport?: ElasticSearchTransportConstructor; } +// @public (undocumented) +export interface ElasticSearchConnectionConstructor { + // (undocumented) + new (opts?: any): any; + // (undocumented) + roles: { + MASTER: string; + DATA: string; + INGEST: string; + ML: string; + }; + // (undocumented) + statuses: { + ALIVE: string; + DEAD: string; + }; +} + // @public (undocumented) export type ElasticSearchHighlightConfig = { fragmentDelimiter: string; @@ -115,6 +154,41 @@ export type ElasticSearchHighlightOptions = { }; // @public (undocumented) +export interface ElasticSearchNodeOptions { + // (undocumented) + agent?: ElasticSearchAgentOptions; + // (undocumented) + headers?: Record; + // (undocumented) + id?: string; + // (undocumented) + roles?: { + master: boolean; + data: boolean; + ingest: boolean; + ml: boolean; + }; + // (undocumented) + ssl?: ConnectionOptions; + // (undocumented) + url: URL; +} + +// @public +export type ElasticSearchOptions = { + logger: Logger; + config: Config; + aliasPostfix?: string; + indexPrefix?: string; +}; + +// @public +export type ElasticSearchQueryTranslator = ( + query: SearchQuery, + options?: ElasticSearchQueryTranslatorOptions, +) => ConcreteElasticSearchQuery; + +// @public export type ElasticSearchQueryTranslatorOptions = { highlightOptions?: ElasticSearchHighlightConfig; }; @@ -128,8 +202,6 @@ export class ElasticSearchSearchEngine implements SearchEngine { logger: Logger, highlightOptions?: ElasticSearchHighlightOptions, ); - // Warning: (ae-forgotten-export) The symbol "ElasticSearchOptions" needs to be exported by the entry point index.d.ts - // // (undocumented) static fromConfig({ logger, @@ -142,12 +214,8 @@ export class ElasticSearchSearchEngine implements SearchEngine { newClient(create: (options: ElasticSearchClientOptions) => T): T; // (undocumented) query(query: SearchQuery): Promise; - // Warning: (ae-forgotten-export) The symbol "ElasticSearchQueryTranslator" needs to be exported by the entry point index.d.ts - // // (undocumented) setTranslator(translator: ElasticSearchQueryTranslator): void; - // Warning: (ae-forgotten-export) The symbol "ConcreteElasticSearchQuery" needs to be exported by the entry point index.d.ts - // // (undocumented) protected translator( query: SearchQuery, @@ -155,9 +223,7 @@ export class ElasticSearchSearchEngine implements SearchEngine { ): ConcreteElasticSearchQuery; } -// Warning: (ae-missing-release-tag) "ElasticSearchSearchEngineIndexer" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export class ElasticSearchSearchEngineIndexer extends BatchSearchEngineIndexer { constructor(options: ElasticSearchSearchEngineIndexerOptions); // (undocumented) @@ -170,9 +236,7 @@ export class ElasticSearchSearchEngineIndexer extends BatchSearchEngineIndexer { initialize(): Promise; } -// Warning: (ae-missing-release-tag) "ElasticSearchSearchEngineIndexerOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export type ElasticSearchSearchEngineIndexerOptions = { type: string; indexPrefix: string; @@ -181,4 +245,17 @@ export type ElasticSearchSearchEngineIndexerOptions = { logger: Logger; elasticSearchClient: Client; }; + +// @public (undocumented) +export interface ElasticSearchTransportConstructor { + // (undocumented) + new (opts?: any): any; + // (undocumented) + sniffReasons: { + SNIFF_ON_START: string; + SNIFF_INTERVAL: string; + SNIFF_ON_CONNECTION_FAULT: string; + DEFAULT: string; + }; +} ``` diff --git a/plugins/search-backend-module-elasticsearch/src/engines/ElasticSearchClientOptions.ts b/plugins/search-backend-module-elasticsearch/src/engines/ElasticSearchClientOptions.ts index 73cb149c0a..c5d1f11b0c 100644 --- a/plugins/search-backend-module-elasticsearch/src/engines/ElasticSearchClientOptions.ts +++ b/plugins/search-backend-module-elasticsearch/src/engines/ElasticSearchClientOptions.ts @@ -18,10 +18,12 @@ import type { ConnectionOptions as TLSConnectionOptions } from 'tls'; /** * Options used to configure the `@elastic/elasticsearch` client and * are what will be passed as an argument to the - * {@link ElasticSearchEngine.newClient} method + * {@link ElasticSearchSearchEngine.newClient} method * * They are drawn from the `ClientOptions` class of `@elastic/elasticsearch`, * but are maintained separately so that this interface is not coupled to + * + * @public */ export interface ElasticSearchClientOptions { provider?: 'aws' | 'elastic'; @@ -65,6 +67,9 @@ export interface ElasticSearchClientOptions { disablePrototypePoisoningProtection?: boolean | 'proto' | 'constructor'; } +/** + * @public + */ export type ElasticSearchAuth = | { username: string; @@ -79,6 +84,9 @@ export type ElasticSearchAuth = }; }; +/** + * @public + */ export interface ElasticSearchNodeOptions { url: URL; id?: string; @@ -93,6 +101,9 @@ export interface ElasticSearchNodeOptions { }; } +/** + * @public + */ export interface ElasticSearchAgentOptions { keepAlive?: boolean; keepAliveMsecs?: number; @@ -100,6 +111,9 @@ export interface ElasticSearchAgentOptions { maxFreeSockets?: number; } +/** + * @public + */ export interface ElasticSearchConnectionConstructor { new (opts?: any): any; statuses: { @@ -113,7 +127,9 @@ export interface ElasticSearchConnectionConstructor { ML: string; }; } - +/** + * @public + */ export interface ElasticSearchTransportConstructor { new (opts?: any): any; sniffReasons: { diff --git a/plugins/search-backend-module-elasticsearch/src/engines/ElasticSearchSearchEngine.ts b/plugins/search-backend-module-elasticsearch/src/engines/ElasticSearchSearchEngine.ts index 70b085e5a7..621fe1cd55 100644 --- a/plugins/search-backend-module-elasticsearch/src/engines/ElasticSearchSearchEngine.ts +++ b/plugins/search-backend-module-elasticsearch/src/engines/ElasticSearchSearchEngine.ts @@ -36,6 +36,10 @@ import { ElasticSearchSearchEngineIndexer } from './ElasticSearchSearchEngineInd export type { ElasticSearchClientOptions }; +/** + * Search query that the elasticsearch engine understands. + * @public + */ export type ConcreteElasticSearchQuery = { documentTypes?: string[]; elasticSearchQuery: Object; @@ -43,18 +47,27 @@ export type ConcreteElasticSearchQuery = { }; /** + * Options available for the Elasticsearch specific query translator. * @public */ export type ElasticSearchQueryTranslatorOptions = { highlightOptions?: ElasticSearchHighlightConfig; }; -type ElasticSearchQueryTranslator = ( +/** + * Elasticsearch specific query translator. + * @public + */ +export type ElasticSearchQueryTranslator = ( query: SearchQuery, options?: ElasticSearchQueryTranslatorOptions, ) => ConcreteElasticSearchQuery; -type ElasticSearchOptions = { +/** + * Options for instansiate ElasticSearchSearchEngine + * @public + */ +export type ElasticSearchOptions = { logger: Logger; config: Config; aliasPostfix?: string; diff --git a/plugins/search-backend-module-elasticsearch/src/engines/ElasticSearchSearchEngineIndexer.ts b/plugins/search-backend-module-elasticsearch/src/engines/ElasticSearchSearchEngineIndexer.ts index 2a738e1506..fd16d0c963 100644 --- a/plugins/search-backend-module-elasticsearch/src/engines/ElasticSearchSearchEngineIndexer.ts +++ b/plugins/search-backend-module-elasticsearch/src/engines/ElasticSearchSearchEngineIndexer.ts @@ -20,6 +20,10 @@ import { Client } from '@elastic/elasticsearch'; import { Readable } from 'stream'; import { Logger } from 'winston'; +/** + * Options for instansiate ElasticSearchSearchEngineIndexer + * @public + */ export type ElasticSearchSearchEngineIndexerOptions = { type: string; indexPrefix: string; @@ -35,6 +39,10 @@ function duration(startTimestamp: [number, number]): string { return `${seconds.toFixed(1)}s`; } +/** + * Elasticsearch specific search engine indexer. + * @public + */ export class ElasticSearchSearchEngineIndexer extends BatchSearchEngineIndexer { private received: number = 0; private processed: number = 0; diff --git a/plugins/search-backend-module-elasticsearch/src/engines/index.ts b/plugins/search-backend-module-elasticsearch/src/engines/index.ts index c5628776ef..625c0d9b60 100644 --- a/plugins/search-backend-module-elasticsearch/src/engines/index.ts +++ b/plugins/search-backend-module-elasticsearch/src/engines/index.ts @@ -15,12 +15,21 @@ */ export { ElasticSearchSearchEngine } from './ElasticSearchSearchEngine'; +export type { + ElasticSearchAgentOptions, + ElasticSearchConnectionConstructor, + ElasticSearchTransportConstructor, + ElasticSearchNodeOptions, + ElasticSearchAuth, +} from './ElasticSearchClientOptions'; export type { ConcreteElasticSearchQuery, ElasticSearchClientOptions, ElasticSearchHighlightConfig, ElasticSearchHighlightOptions, + ElasticSearchQueryTranslator, ElasticSearchQueryTranslatorOptions, + ElasticSearchOptions, } from './ElasticSearchSearchEngine'; export type { ElasticSearchSearchEngineIndexer, diff --git a/plugins/search-backend-module-elasticsearch/src/index.ts b/plugins/search-backend-module-elasticsearch/src/index.ts index 744e12f8c8..3cfb3c403f 100644 --- a/plugins/search-backend-module-elasticsearch/src/index.ts +++ b/plugins/search-backend-module-elasticsearch/src/index.ts @@ -22,10 +22,18 @@ export { ElasticSearchSearchEngine } from './engines'; export type { + ElasticSearchAgentOptions, + ConcreteElasticSearchQuery, ElasticSearchClientOptions, ElasticSearchHighlightConfig, ElasticSearchHighlightOptions, + ElasticSearchQueryTranslator, ElasticSearchQueryTranslatorOptions, + ElasticSearchConnectionConstructor, + ElasticSearchTransportConstructor, + ElasticSearchNodeOptions, + ElasticSearchOptions, + ElasticSearchAuth, ElasticSearchSearchEngineIndexer, ElasticSearchSearchEngineIndexerOptions, } from './engines';