From 2a49ffbcb30b70c1dd57045b955741dc5661968b Mon Sep 17 00:00:00 2001 From: Eric Peterson Date: Mon, 9 Jan 2023 13:28:53 +0100 Subject: [PATCH 1/3] Clean up / improve client instantiation docs. Signed-off-by: Eric Peterson --- .changeset/search-es-new-client-docs.md | 5 +++++ docs/features/search/search-engines.md | 2 +- .../src/engines/ElasticSearchSearchEngine.ts | 18 +++++++++++++++--- 3 files changed, 21 insertions(+), 4 deletions(-) create mode 100644 .changeset/search-es-new-client-docs.md diff --git a/.changeset/search-es-new-client-docs.md b/.changeset/search-es-new-client-docs.md new file mode 100644 index 0000000000..b0a1025938 --- /dev/null +++ b/.changeset/search-es-new-client-docs.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-search-backend-module-elasticsearch': patch +--- + +Improved documentation on the `ElasticSearchSearchEngine.newClient()` method. diff --git a/docs/features/search/search-engines.md b/docs/features/search/search-engines.md index 2e7341a0d7..bb1b07f050 100644 --- a/docs/features/search/search-engines.md +++ b/docs/features/search/search-engines.md @@ -133,7 +133,7 @@ used internally by the Elasticsearch engine plugin. For example: ```typescript import { isOpenSearchCompatible } from '@backstage/plugin-search-backend-module-elasticsearch'; -import { Client as ElasticClient } from '@elastic/elastic-search'; +import { Client as ElasticClient } from '@elastic/elasticsearch'; import { Client as OpenSearchClient } from '@opensearch-project/opensearch'; const client = searchEngine.newClient(options => { diff --git a/plugins/search-backend-module-elasticsearch/src/engines/ElasticSearchSearchEngine.ts b/plugins/search-backend-module-elasticsearch/src/engines/ElasticSearchSearchEngine.ts index 0a2c2ce7df..c47cc35c47 100644 --- a/plugins/search-backend-module-elasticsearch/src/engines/ElasticSearchSearchEngine.ts +++ b/plugins/search-backend-module-elasticsearch/src/engines/ElasticSearchSearchEngine.ts @@ -171,9 +171,21 @@ export class ElasticSearchSearchEngine implements SearchEngine { } /** - * Create a custom search client from the derived elastic search - * configuration. This need not be the same client that the engine uses - * internally. + * Create a custom search client from the derived search client configuration. + * This need not be the same client that the engine uses internally. + * + * @example Instantiate an instance of an Elasticsearch client. + * ```ts + * import { isOpenSearchCompatible } from '@backstage/plugin-search-backend-module-elasticsearch'; + * import { Client } from '@elastic/elasticsearch'; + * + * const client = searchEngine.newClient(options => { + * if (!isOpenSearchCompatible(options)) { + * return new Client(options); + * } + * throw new Error('Incompatible options provided'); + * }); + * ``` */ newClient(create: (options: ElasticSearchClientOptions) => T): T { return create(this.elasticSearchClientOptions); From 0fcbe29c6b8c564e6c23ab6a19fb38dc9791e622 Mon Sep 17 00:00:00 2001 From: Eric Peterson Date: Tue, 10 Jan 2023 11:34:11 +0100 Subject: [PATCH 2/3] Clarify typeguard usage Signed-off-by: Eric Peterson --- .../src/engines/ElasticSearchSearchEngine.ts | 2 ++ 1 file changed, 2 insertions(+) diff --git a/plugins/search-backend-module-elasticsearch/src/engines/ElasticSearchSearchEngine.ts b/plugins/search-backend-module-elasticsearch/src/engines/ElasticSearchSearchEngine.ts index c47cc35c47..9edad973de 100644 --- a/plugins/search-backend-module-elasticsearch/src/engines/ElasticSearchSearchEngine.ts +++ b/plugins/search-backend-module-elasticsearch/src/engines/ElasticSearchSearchEngine.ts @@ -180,6 +180,8 @@ export class ElasticSearchSearchEngine implements SearchEngine { * import { Client } from '@elastic/elasticsearch'; * * const client = searchEngine.newClient(options => { + * // This typeguard ensures options are compatible with either OpenSearch + * // or Elasticsearch client constructors. * if (!isOpenSearchCompatible(options)) { * return new Client(options); * } From ec2d3935b3e80364dbd2029b2a973ea651120c1f Mon Sep 17 00:00:00 2001 From: Eric Peterson Date: Tue, 10 Jan 2023 13:45:56 +0100 Subject: [PATCH 3/3] Clarify type generics in docs Signed-off-by: Eric Peterson --- docs/features/search/search-engines.md | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/docs/features/search/search-engines.md b/docs/features/search/search-engines.md index bb1b07f050..d06e401847 100644 --- a/docs/features/search/search-engines.md +++ b/docs/features/search/search-engines.md @@ -136,14 +136,22 @@ import { isOpenSearchCompatible } from '@backstage/plugin-search-backend-module- import { Client as ElasticClient } from '@elastic/elasticsearch'; import { Client as OpenSearchClient } from '@opensearch-project/opensearch'; -const client = searchEngine.newClient(options => { - // In reality, you would only import / instantiate one of the following, but - // for illustrative purposes, here are both: - if (isOpenSearchCompatible(options)) { - return new OpenSearchClient(options); - } else { +// Return an Elasticsearch client +const esClient = searchEngine.newClient(options => { + if (!isOpenSearchCompatible(options)) { return new ElasticClient(options); } + + throw new Error('Incompatible options'); +}); + +// Return an OpenSearch client +const osClient = searchEngine.newClient(options => { + if (isOpenSearchCompatible(options)) { + return new OpenSearchClient(options); + } + + throw new Error('Incompatible options'); }); ```