Merge pull request #15634 from backstage/search/new-client-docs

[Search] Clean up / improve ES client instantiation docs

.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.

docs/features/search/search-engines.md

@@ -133,17 +133,25 @@ 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 => {
-  // 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<ElasticClient>(options => {
+  if (!isOpenSearchCompatible(options)) {
     return new ElasticClient(options);
   }
+
+  throw new Error('Incompatible options');
+});
+
+// Return an OpenSearch client
+const osClient = searchEngine.newClient<OpenSearchClient>(options => {
+  if (isOpenSearchCompatible(options)) {
+    return new OpenSearchClient(options);
+  }
+
+  throw new Error('Incompatible options');
 });
 ```
 

plugins/search-backend-module-elasticsearch/src/engines/ElasticSearchSearchEngine.ts

@@ -171,9 +171,23 @@ 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<Client>(options => {
+   *   // This typeguard ensures options are compatible with either OpenSearch
+   *   // or Elasticsearch client constructors.
+   *   if (!isOpenSearchCompatible(options)) {
+   *     return new Client(options);
+   *   }
+   *   throw new Error('Incompatible options provided');
+   * });
+   * ```
    */
   newClient<T>(create: (options: ElasticSearchClientOptions) => T): T {
     return create(this.elasticSearchClientOptions);