search-common: introduce SearchDocument type

This type is a subset of `IndexableDocument`, and is intended to be
used in place of `IndexableDocument` in the frontend.

Signed-off-by: Mike Lewis <mtlewis@users.noreply.github.com>

.changeset/happy-mugs-camp.md

@@ -0,0 +1,7 @@
+---
+'@backstage/plugin-search-common': patch
+---
+
+- Introduce `SearchDocument` type. This type contains the subset of `IndexableDocument` properties relevant to the frontend, and is intended to be used for documents returned to the frontend from the search API.
+- `SearchResultSet` is now a wrapper for documents of type `SearchDocument`, and is intended to be used in the frontend. This isn't a breaking change, since `IndexableDocument`s are valid `SearchDocument`s, so the old and new types are compatible.
+- Introduce `IndexableResultSet` type, which wraps `IndexableDocument` instances in the same way as `SearchResultSet`.

plugins/search-common/api-report.md

@@ -30,14 +30,17 @@ export type DocumentTypeInfo = {
 };
 
 // @beta
-export interface IndexableDocument {
+export type IndexableDocument = SearchDocument & {
   authorization?: {
     resourceRef: string;
   };
-  location: string;
-  text: string;
-  title: string;
-}
+};
+
+// @beta (undocumented)
+export type IndexableResult = Result<IndexableDocument>;
+
+// @beta (undocumented)
+export type IndexableResultSet = ResultSet<IndexableDocument>;
 
 // @beta
 export type QueryRequestOptions = {
@@ -47,13 +50,38 @@ export type QueryRequestOptions = {
 // @beta
 export type QueryTranslator = (query: SearchQuery) => unknown;
 
+// @beta (undocumented)
+export interface Result<TDocument> {
+  // (undocumented)
+  document: TDocument;
+  // (undocumented)
+  type: string;
+}
+
+// @beta (undocumented)
+export interface ResultSet<TDocument> {
+  // (undocumented)
+  nextPageCursor?: string;
+  // (undocumented)
+  previousPageCursor?: string;
+  // (undocumented)
+  results: Result<TDocument>[];
+}
+
+// @beta
+export interface SearchDocument {
+  location: string;
+  text: string;
+  title: string;
+}
+
 // @beta
 export interface SearchEngine {
   getIndexer(type: string): Promise<Writable>;
   query(
     query: SearchQuery,
     options?: QueryRequestOptions,
-  ): Promise<SearchResultSet>;
+  ): Promise<IndexableResultSet>;
   setTranslator(translator: QueryTranslator): void;
 }
 
@@ -70,20 +98,8 @@ export interface SearchQuery {
 }
 
 // @beta (undocumented)
-export interface SearchResult {
-  // (undocumented)
-  document: IndexableDocument;
-  // (undocumented)
-  type: string;
-}
+export type SearchResult = Result<SearchDocument>;
 
 // @beta (undocumented)
-export interface SearchResultSet {
-  // (undocumented)
-  nextPageCursor?: string;
-  // (undocumented)
-  previousPageCursor?: string;
-  // (undocumented)
-  results: SearchResult[];
-}
+export type SearchResultSet = ResultSet<SearchDocument>;
 ```

plugins/search-common/src/types.ts

@@ -31,26 +31,45 @@ export interface SearchQuery {
 /**
  * @beta
  */
-export interface SearchResult {
+export interface Result<TDocument> {
   type: string;
-  document: IndexableDocument;
+  document: TDocument;
 }
 
 /**
  * @beta
  */
-export interface SearchResultSet {
-  results: SearchResult[];
+export interface ResultSet<TDocument> {
+  results: Result<TDocument>[];
   nextPageCursor?: string;
   previousPageCursor?: string;
 }
 
 /**
- * Base properties that all indexed documents must include, as well as some
- * common properties that documents are encouraged to use where appropriate.
  * @beta
  */
-export interface IndexableDocument {
+export type SearchResult = Result<SearchDocument>;
+
+/**
+ * @beta
+ */
+export type SearchResultSet = ResultSet<SearchDocument>;
+
+/**
+ * @beta
+ */
+export type IndexableResult = Result<IndexableDocument>;
+
+/**
+ * @beta
+ */
+export type IndexableResultSet = ResultSet<IndexableDocument>;
+
+/**
+ * Base properties that all search documents must include.
+ * @beta
+ */
+export interface SearchDocument {
   /**
    * The primary name of the document (e.g. name, title, identifier, etc).
    */
@@ -66,7 +85,13 @@ export interface IndexableDocument {
    * is clicked).
    */
   location: string;
+}
 
+/**
+ * Properties related to indexing of documents.
+ * @beta
+ */
+export type IndexableDocument = SearchDocument & {
   /**
    * Optional authorization information to be used when determining whether this
    * search result should be visible to a given user.
@@ -77,7 +102,7 @@ export interface IndexableDocument {
      */
     resourceRef: string;
   };
-}
+};
 
 /**
  * Information about a specific document type. Intended to be used in the
@@ -178,5 +203,5 @@ export interface SearchEngine {
   query(
     query: SearchQuery,
     options?: QueryRequestOptions,
-  ): Promise<SearchResultSet>;
+  ): Promise<IndexableResultSet>;
 }