Clean up search-common/search-backend-node APIs, indicating beta.

Signed-off-by: Eric Peterson <ericpeterson@spotify.com>

packages/search-common/api-report.md

@@ -11,33 +11,25 @@ import { Readable } from 'stream';
 import { Transform } from 'stream';
 import { Writable } from 'stream';
 
-// Warning: (ae-missing-release-tag) "DocumentCollatorFactory" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public
+// @beta
 export interface DocumentCollatorFactory {
   getCollator(): Promise<Readable>;
   readonly type: string;
   readonly visibilityPermission?: Permission;
 }
 
-// Warning: (ae-missing-release-tag) "DocumentDecoratorFactory" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public
+// @beta
 export interface DocumentDecoratorFactory {
   getDecorator(): Promise<Transform>;
   readonly types?: string[];
 }
 
-// Warning: (ae-missing-release-tag) "DocumentTypeInfo" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public
+// @beta
 export type DocumentTypeInfo = {
   visibilityPermission?: Permission;
 };
 
-// Warning: (ae-missing-release-tag) "IndexableDocument" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public
+// @beta
 export interface IndexableDocument {
   authorization?: {
     resourceRef: string;
@@ -47,21 +39,15 @@ export interface IndexableDocument {
   title: string;
 }
 
-// Warning: (ae-missing-release-tag) "QueryRequestOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @beta
 export type QueryRequestOptions = {
   token?: string;
 };
 
-// Warning: (ae-missing-release-tag) "QueryTranslator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public
+// @beta
 export type QueryTranslator = (query: SearchQuery) => unknown;
 
-// Warning: (ae-missing-release-tag) "SearchEngine" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public
+// @beta
 export interface SearchEngine {
   getIndexer(type: string): Promise<Writable>;
   query(
@@ -71,9 +57,7 @@ export interface SearchEngine {
   setTranslator(translator: QueryTranslator): void;
 }
 
-// Warning: (ae-missing-release-tag) "SearchQuery" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @beta (undocumented)
 export interface SearchQuery {
   // (undocumented)
   filters?: JsonObject;
@@ -85,9 +69,7 @@ export interface SearchQuery {
   types?: string[];
 }
 
-// Warning: (ae-missing-release-tag) "SearchResult" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @beta (undocumented)
 export interface SearchResult {
   // (undocumented)
   document: IndexableDocument;
@@ -95,9 +77,7 @@ export interface SearchResult {
   type: string;
 }
 
-// Warning: (ae-missing-release-tag) "SearchResultSet" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @beta (undocumented)
 export interface SearchResultSet {
   // (undocumented)
   nextPageCursor?: string;

packages/search-common/src/types.ts

@@ -18,6 +18,9 @@ import { Permission } from '@backstage/plugin-permission-common';
 import { JsonObject } from '@backstage/types';
 import { Readable, Transform, Writable } from 'stream';
 
+/**
+ * @beta
+ */
 export interface SearchQuery {
   term: string;
   filters?: JsonObject;
@@ -25,11 +28,17 @@ export interface SearchQuery {
   pageCursor?: string;
 }
 
+/**
+ * @beta
+ */
 export interface SearchResult {
   type: string;
   document: IndexableDocument;
 }
 
+/**
+ * @beta
+ */
 export interface SearchResultSet {
   results: SearchResult[];
   nextPageCursor?: string;
@@ -39,6 +48,7 @@ export interface SearchResultSet {
 /**
  * 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 {
   /**
@@ -73,6 +83,7 @@ export interface IndexableDocument {
  * Information about a specific document type. Intended to be used in the
  * {@link @backstage/search-backend-node#IndexBuilder} to collect information
  * about the types stored in the index.
+ * @beta
  */
 export type DocumentTypeInfo = {
   /**
@@ -84,6 +95,7 @@ export type DocumentTypeInfo = {
 
 /**
  * Factory class for instantiating collators.
+ * @beta
  */
 export interface DocumentCollatorFactory {
   /**
@@ -106,6 +118,7 @@ export interface DocumentCollatorFactory {
 
 /**
  * Factory class for instantiating decorators.
+ * @beta
  */
 export interface DocumentDecoratorFactory {
   /**
@@ -124,9 +137,14 @@ export interface DocumentDecoratorFactory {
 /**
  * A type of function responsible for translating an abstract search query into
  * a concrete query relevant to a particular search engine.
+ * @beta
  */
 export type QueryTranslator = (query: SearchQuery) => unknown;
 
+/**
+ * Options when querying a search engine.
+ * @beta
+ */
 export type QueryRequestOptions = {
   token?: string;
 };
@@ -135,6 +153,7 @@ export type QueryRequestOptions = {
  * Interface that must be implemented by specific search engines, responsible
  * for performing indexing and querying and translating abstract queries into
  * concrete, search engine-specific queries.
+ * @beta
  */
 export interface SearchEngine {
   /**

plugins/search-backend-node/api-report.md

@@ -19,9 +19,7 @@ import { SearchResultSet } from '@backstage/search-common';
 import { Transform } from 'stream';
 import { Writable } from 'stream';
 
-// Warning: (ae-missing-release-tag) "BatchSearchEngineIndexer" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public
+// @beta
 export abstract class BatchSearchEngineIndexer extends Writable {
   constructor(options: BatchSearchEngineOptions);
   abstract finalize(): Promise<void>;
@@ -29,16 +27,19 @@ export abstract class BatchSearchEngineIndexer extends Writable {
   abstract initialize(): Promise<void>;
 }
 
-// Warning: (ae-missing-release-tag) "BatchSearchEngineOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @beta (undocumented)
 export type BatchSearchEngineOptions = {
   batchSize: number;
 };
 
-// Warning: (ae-missing-release-tag) "DecoratorBase" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public
+// @beta (undocumented)
+export type ConcreteLunrQuery = {
+  lunrQueryBuilder: lunr_2.Index.QueryBuilder;
+  documentTypes?: string[];
+  pageSize: number;
+};
+
+// @beta
 export abstract class DecoratorBase extends Transform {
   constructor();
   abstract decorate(
@@ -48,18 +49,13 @@ export abstract class DecoratorBase extends Transform {
   abstract initialize(): Promise<void>;
 }
 
-// Warning: (ae-missing-release-tag) "IndexBuilder" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @beta (undocumented)
 export class IndexBuilder {
-  // Warning: (ae-forgotten-export) The symbol "IndexBuilderOptions" needs to be exported by the entry point index.d.ts
   constructor({ logger, searchEngine }: IndexBuilderOptions);
-  // Warning: (ae-forgotten-export) The symbol "RegisterCollatorParameters" needs to be exported by the entry point index.d.ts
   addCollator({
     factory,
     defaultRefreshIntervalSeconds,
   }: RegisterCollatorParameters): void;
-  // Warning: (ae-forgotten-export) The symbol "RegisterDecoratorParameters" needs to be exported by the entry point index.d.ts
   addDecorator({ factory }: RegisterDecoratorParameters): void;
   build(): Promise<{
     scheduler: Scheduler;
@@ -70,9 +66,16 @@ export class IndexBuilder {
   getSearchEngine(): SearchEngine;
 }
 
-// Warning: (ae-missing-release-tag) "LunrSearchEngine" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @beta (undocumented)
+export type IndexBuilderOptions = {
+  searchEngine: SearchEngine;
+  logger: Logger_2;
+};
+
+// @beta (undocumented)
+export type LunrQueryTranslator = (query: SearchQuery) => ConcreteLunrQuery;
+
+// @beta (undocumented)
 export class LunrSearchEngine implements SearchEngine {
   constructor({ logger }: { logger: Logger_2 });
   // (undocumented)
@@ -85,17 +88,13 @@ export class LunrSearchEngine implements SearchEngine {
   protected lunrIndices: Record<string, lunr_2.Index>;
   // (undocumented)
   query(query: SearchQuery): Promise<SearchResultSet>;
-  // Warning: (ae-forgotten-export) The symbol "LunrQueryTranslator" needs to be exported by the entry point index.d.ts
-  //
   // (undocumented)
   setTranslator(translator: LunrQueryTranslator): void;
   // (undocumented)
   protected translator: QueryTranslator;
 }
 
-// Warning: (ae-missing-release-tag) "LunrSearchEngineIndexer" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @beta (undocumented)
 export class LunrSearchEngineIndexer extends BatchSearchEngineIndexer {
   constructor();
   // (undocumented)
@@ -110,9 +109,18 @@ export class LunrSearchEngineIndexer extends BatchSearchEngineIndexer {
   initialize(): Promise<void>;
 }
 
-// Warning: (ae-missing-release-tag) "Scheduler" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public
+// @beta
+export interface RegisterCollatorParameters {
+  defaultRefreshIntervalSeconds: number;
+  factory: DocumentCollatorFactory;
+}
+
+// @beta
+export interface RegisterDecoratorParameters {
+  factory: DocumentDecoratorFactory;
+}
+
+// @beta (undocumented)
 export class Scheduler {
   constructor({ logger }: { logger: Logger_2 });
   addToSchedule(task: Function, interval: number): void;
@@ -122,18 +130,14 @@ export class Scheduler {
 
 export { SearchEngine };
 
-// Warning: (ae-missing-release-tag) "TestPipeline" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public
+// @beta
 export class TestPipeline {
   execute(): Promise<TestPipelineResult>;
   withDocuments(documents: IndexableDocument[]): TestPipeline;
   static withSubject(subject: Readable | Transform | Writable): TestPipeline;
 }
 
-// Warning: (ae-missing-release-tag) "TestPipelineResult" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public
+// @beta
 export type TestPipelineResult = {
   error: unknown;
   documents: IndexableDocument[];

plugins/search-backend-node/src/IndexBuilder.ts

@@ -24,6 +24,7 @@ import { Transform, pipeline } from 'stream';
 import { Logger } from 'winston';
 import { Scheduler } from './index';
 import {
+  IndexBuilderOptions,
   RegisterCollatorParameters,
   RegisterDecoratorParameters,
 } from './types';
@@ -33,11 +34,9 @@ interface CollatorEnvelope {
   refreshInterval: number;
 }
 
-type IndexBuilderOptions = {
-  searchEngine: SearchEngine;
-  logger: Logger;
-};
-
+/**
+ * @beta
+ */
 export class IndexBuilder {
   private collators: Record<string, CollatorEnvelope>;
   private decorators: Record<string, DocumentDecoratorFactory[]>;

plugins/search-backend-node/src/Scheduler.ts

@@ -26,6 +26,9 @@ type TaskEnvelope = {
  * TODO: coordination, error handling
  */
 
+/**
+ * @beta
+ */
 export class Scheduler {
   private logger: Logger;
   private schedule: TaskEnvelope[];

plugins/search-backend-node/src/engines/LunrSearchEngine.ts

@@ -25,6 +25,9 @@ import lunr from 'lunr';
 import { Logger } from 'winston';
 import { LunrSearchEngineIndexer } from './LunrSearchEngineIndexer';
 
+/**
+ * @beta
+ */
 export type ConcreteLunrQuery = {
   lunrQueryBuilder: lunr.Index.QueryBuilder;
   documentTypes?: string[];
@@ -36,8 +39,14 @@ type LunrResultEnvelope = {
   type: string;
 };
 
-type LunrQueryTranslator = (query: SearchQuery) => ConcreteLunrQuery;
+/**
+ * @beta
+ */
+export type LunrQueryTranslator = (query: SearchQuery) => ConcreteLunrQuery;
 
+/**
+ * @beta
+ */
 export class LunrSearchEngine implements SearchEngine {
   protected lunrIndices: Record<string, lunr.Index> = {};
   protected docStore: Record<string, IndexableDocument>;

plugins/search-backend-node/src/engines/LunrSearchEngineIndexer.ts

@@ -18,6 +18,9 @@ import { IndexableDocument } from '@backstage/search-common';
 import lunr from 'lunr';
 import { BatchSearchEngineIndexer } from '../indexing';
 
+/**
+ * @beta
+ */
 export class LunrSearchEngineIndexer extends BatchSearchEngineIndexer {
   private schemaInitialized = false;
   private builder: lunr.Builder;

plugins/search-backend-node/src/engines/index.ts

@@ -15,5 +15,8 @@
  */
 
 export { LunrSearchEngine } from './LunrSearchEngine';
-export type { ConcreteLunrQuery } from './LunrSearchEngine';
+export type {
+  ConcreteLunrQuery,
+  LunrQueryTranslator,
+} from './LunrSearchEngine';
 export type { LunrSearchEngineIndexer } from './LunrSearchEngineIndexer';

plugins/search-backend-node/src/index.ts

@@ -23,7 +23,16 @@
 export { IndexBuilder } from './IndexBuilder';
 export { Scheduler } from './Scheduler';
 export { LunrSearchEngine } from './engines';
-export type { LunrSearchEngineIndexer } from './engines';
+export type {
+  ConcreteLunrQuery,
+  LunrQueryTranslator,
+  LunrSearchEngineIndexer,
+} from './engines';
+export type {
+  IndexBuilderOptions,
+  RegisterCollatorParameters,
+  RegisterDecoratorParameters,
+} from './types';
 export * from './indexing';
 export * from './test-utils';
 

plugins/search-backend-node/src/indexing/BatchSearchEngineIndexer.ts

@@ -18,6 +18,9 @@ import { assertError } from '@backstage/errors';
 import { IndexableDocument } from '@backstage/search-common';
 import { Writable } from 'stream';
 
+/**
+ * @beta
+ */
 export type BatchSearchEngineOptions = {
   batchSize: number;
 };
@@ -25,6 +28,7 @@ export type BatchSearchEngineOptions = {
 /**
  * Base class encapsulating batch-based stream processing. Useful as a base
  * class for search engine indexers.
+ * @beta
  */
 export abstract class BatchSearchEngineIndexer extends Writable {
   private batchSize: number;

plugins/search-backend-node/src/indexing/DecoratorBase.ts

@@ -21,6 +21,7 @@ import { Transform } from 'stream';
 /**
  * Base class encapsulating simple async transformations. Useful as a base
  * class for Backstage search decorators.
+ * @beta
  */
 export abstract class DecoratorBase extends Transform {
   private initialized: Promise<undefined | Error>;

plugins/search-backend-node/src/test-utils/TestPipeline.ts

@@ -19,6 +19,7 @@ import { pipeline, Readable, Transform, Writable } from 'stream';
 
 /**
  * Object resolved after a test pipeline is executed.
+ * @beta
  */
 export type TestPipelineResult = {
   /**
@@ -36,6 +37,7 @@ export type TestPipelineResult = {
 
 /**
  * Test utility for Backstage Search collators, decorators, and indexers.
+ * @beta
  */
 export class TestPipeline {
   private collator?: Readable;

plugins/search-backend-node/src/types.ts

@@ -17,10 +17,21 @@
 import {
   DocumentCollatorFactory,
   DocumentDecoratorFactory,
+  SearchEngine,
 } from '@backstage/search-common';
+import { Logger } from 'winston';
+
+/**
+ * @beta
+ */
+export type IndexBuilderOptions = {
+  searchEngine: SearchEngine;
+  logger: Logger;
+};
 
 /**
  * Parameters required to register a collator.
+ * @beta
  */
 export interface RegisterCollatorParameters {
   /**
@@ -36,6 +47,7 @@ export interface RegisterCollatorParameters {
 
 /**
  * Parameters required to register a decorator
+ * @beta
  */
 export interface RegisterDecoratorParameters {
   /**

scripts/api-extractor.ts

@@ -213,6 +213,7 @@ const NO_WARNING_PACKAGES = [
   'packages/errors',
   'packages/integration',
   'packages/integration-react',
+  'packages/search-common',
   'packages/techdocs-common',
   'packages/test-utils',
   'packages/theme',
@@ -235,6 +236,7 @@ const NO_WARNING_PACKAGES = [
   'plugins/scaffolder-backend-module-rails',
   'plugins/scaffolder-backend-module-yeoman',
   'plugins/scaffolder-common',
+  'plugins/search-backend-node',
   'plugins/techdocs-backend',
   'plugins/tech-insights',
   'plugins/tech-insights-backend',