paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 20 Packages Projects Releases Wiki Activity

Merge pull request #11805 from backstage/emmaindal/clean-up-search-api-reports

Browse Source 
[Search] clean up search api reports
This commit is contained in:
Emma Indal
2022-06-03 16:37:56 +02:00
committed by GitHub
parent 05d572ec63 28972473a0
commit e27877b9e1
33 changed files with 305 additions and 129 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.changeset/famous-cups-clap.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/plugin-search-common': patch
---
`@beta` exports now replaced with `@public` exports
.changeset/hip-pears-shout.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/plugin-catalog-common': patch
---
Replaced all usages of `@backstage/search-common` with `@backstage/plugin-search-common`
.changeset/nervous-ravens-smash.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/plugin-search-backend': patch
---
`RouterOptions` and `createRouter` now marked as public exports
.changeset/pre.json
-1
View File
@@ -25,7 +25,6 @@
"@backstage/integration": "1.2.0",
"@backstage/integration-react": "1.1.0",
"@backstage/release-manifests": "0.0.3",
"@backstage/search-common": "0.3.4",
"@techdocs/cli": "1.1.1",
"techdocs-cli-embedded-app": "0.2.70",
"@backstage/techdocs-common": "0.11.15",
.changeset/seven-readers-drop.md
+14
View File
@@ -0,0 +1,14 @@
---
'@backstage/plugin-search-backend-module-elasticsearch': patch
---
Additional types now exported publicly:
- ElasticSearchAgentOptions
- ElasticSearchConcreteQuery
- ElasticSearchQueryTranslator
- ElasticSearchConnectionConstructor,
- ElasticSearchTransportConstructor,
- ElasticSearchNodeOptions,
- ElasticSearchOptions,
- ElasticSearchAuth,
.changeset/twenty-mangos-clap.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/plugin-search-backend-node': patch
---
Replaced all `@beta` exports with `@public` exports
contrib/search/confluence/ConfluenceCollator.md
+1 -1
View File
@@ -1,7 +1,7 @@
ConfluenceCollator.ts reference
```ts
import { DocumentCollator } from '@backstage/search-common';
import { DocumentCollator } from '@backstage/plugin-search-common';
import fetch from 'cross-fetch';
export class ConfluenceCollator implements DocumentCollator {
contrib/search/confluence/ConfluenceResultListItem.md
+1 -1
View File
@@ -3,7 +3,7 @@ ConfluenceResultListItem.tsx reference
```tsx
import React from 'react';
import { Link } from '@backstage/core-components';
import { IndexableDocument } from '@backstage/search-common';
import { IndexableDocument } from '@backstage/plugin-search-common';
import {
Divider,
ListItem,
plugins/catalog-common/api-report.md
+1 -1
View File
@@ -4,7 +4,7 @@
```ts
import { BasicPermission } from '@backstage/plugin-permission-common';
import { IndexableDocument } from '@backstage/search-common';
import { IndexableDocument } from '@backstage/plugin-search-common';
import { ResourcePermission } from '@backstage/plugin-permission-common';
// @alpha
plugins/catalog-common/package.json
+1 -1
View File
@@ -35,7 +35,7 @@
},
"dependencies": {
"@backstage/plugin-permission-common": "^0.6.2-next.0",
"@backstage/search-common": "^0.3.5-next.0"
"@backstage/plugin-search-common": "^0.3.5-next.0"
},
"devDependencies": {
"@backstage/cli": "^0.17.2-next.1"
plugins/catalog-common/src/search/CatalogEntityDocument.ts
+1 -1
View File
@@ -13,7 +13,7 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { IndexableDocument } from '@backstage/search-common';
import { IndexableDocument } from '@backstage/plugin-search-common';
/**
* The Document format for an Entity in the Catalog for search
plugins/search-backend-module-elasticsearch/api-report.md
+103 -26
View File
@@ -15,17 +15,37 @@ 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 (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 +56,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 +68,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 +108,35 @@ 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
export type ElasticSearchConcreteQuery = {
documentTypes?: string[];
elasticSearchQuery: Object;
pageSize: number;
};
// @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<string, any>;
// (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,
) => ElasticSearchConcreteQuery;
// @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,22 +214,16 @@ export class ElasticSearchSearchEngine implements SearchEngine {
newClient<T>(create: (options: ElasticSearchClientOptions) => T): T;
// (undocumented)
query(query: SearchQuery): Promise<IndexableResultSet>;
// 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,
options?: ElasticSearchQueryTranslatorOptions,
): ConcreteElasticSearchQuery;
): ElasticSearchConcreteQuery;
}
// 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<void>;
}
// 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;
};
}
```
plugins/search-backend-module-elasticsearch/src/engines/ElasticSearchClientOptions.ts
+18 -2
View File
@@ -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: {
plugins/search-backend-module-elasticsearch/src/engines/ElasticSearchSearchEngine.test.ts
+7 -7
View File
@@ -19,7 +19,7 @@ import { ConfigReader } from '@backstage/config';
import { Client, errors } from '@elastic/elasticsearch';
import Mock from '@elastic/elasticsearch-mock';
import {
ConcreteElasticSearchQuery,
ElasticSearchConcreteQuery,
decodePageCursor,
ElasticSearchSearchEngine,
encodePageCursor,
@@ -131,7 +131,7 @@ describe('ElasticSearchSearchEngine', () => {
types: ['indexName'],
term: 'testTerm',
filters: { kind: 'testKind' },
}) as ConcreteElasticSearchQuery;
}) as ElasticSearchConcreteQuery;
expect(actualTranslatedQuery).toMatchObject({
documentTypes: ['indexName'],
@@ -170,7 +170,7 @@ describe('ElasticSearchSearchEngine', () => {
types: ['indexName'],
term: 'testTerm',
pageCursor: 'MQ==',
}) as ConcreteElasticSearchQuery;
}) as ElasticSearchConcreteQuery;
expect(actualTranslatedQuery).toMatchObject({
documentTypes: ['indexName'],
@@ -210,7 +210,7 @@ describe('ElasticSearchSearchEngine', () => {
foo: 123,
bar: true,
},
}) as ConcreteElasticSearchQuery;
}) as ElasticSearchConcreteQuery;
expect(actualTranslatedQuery).toMatchObject({
documentTypes: ['indexName'],
@@ -266,7 +266,7 @@ describe('ElasticSearchSearchEngine', () => {
types: ['indexName'],
term: 'testTerm',
filters: { kind: ['testKind', 'kastTeint'] },
}) as ConcreteElasticSearchQuery;
}) as ElasticSearchConcreteQuery;
expect(actualTranslatedQuery).toMatchObject({
documentTypes: ['indexName'],
@@ -327,7 +327,7 @@ describe('ElasticSearchSearchEngine', () => {
fragmentDelimiter: ' ... ',
},
},
) as ConcreteElasticSearchQuery;
) as ElasticSearchConcreteQuery;
expect(actualTranslatedQuery).toMatchObject({
documentTypes: ['indexName'],
@@ -369,7 +369,7 @@ describe('ElasticSearchSearchEngine', () => {
types: ['indexName'],
term: 'testTerm',
filters: { kind: { a: 'b' } },
}) as ConcreteElasticSearchQuery;
}) as ElasticSearchConcreteQuery;
expect(actualTranslatedQuery).toThrow();
});
});
plugins/search-backend-module-elasticsearch/src/engines/ElasticSearchSearchEngine.ts
+18 -5
View File
@@ -36,25 +36,38 @@ import { ElasticSearchSearchEngineIndexer } from './ElasticSearchSearchEngineInd
export type { ElasticSearchClientOptions };
export type ConcreteElasticSearchQuery = {
/**
* Search query that the elasticsearch engine understands.
* @public
*/
export type ElasticSearchConcreteQuery = {
documentTypes?: string[];
elasticSearchQuery: Object;
pageSize: number;
};
/**
* 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;
) => ElasticSearchConcreteQuery;
type ElasticSearchOptions = {
/**
* Options for instansiate ElasticSearchSearchEngine
* @public
*/
export type ElasticSearchOptions = {
logger: Logger;
config: Config;
aliasPostfix?: string;
@@ -161,7 +174,7 @@ export class ElasticSearchSearchEngine implements SearchEngine {
protected translator(
query: SearchQuery,
options?: ElasticSearchQueryTranslatorOptions,
): ConcreteElasticSearchQuery {
): ElasticSearchConcreteQuery {
const { term, filters = {}, types, pageCursor } = query;
const filter = Object.entries(filters)
plugins/search-backend-module-elasticsearch/src/engines/ElasticSearchSearchEngineIndexer.ts
+8
View File
@@ -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;
plugins/search-backend-module-elasticsearch/src/engines/index.ts
+10 -1
View File
@@ -16,11 +16,20 @@
export { ElasticSearchSearchEngine } from './ElasticSearchSearchEngine';
export type {
ConcreteElasticSearchQuery,
ElasticSearchAgentOptions,
ElasticSearchConnectionConstructor,
ElasticSearchTransportConstructor,
ElasticSearchNodeOptions,
ElasticSearchAuth,
} from './ElasticSearchClientOptions';
export type {
ElasticSearchConcreteQuery,
ElasticSearchClientOptions,
ElasticSearchHighlightConfig,
ElasticSearchHighlightOptions,
ElasticSearchQueryTranslator,
ElasticSearchQueryTranslatorOptions,
ElasticSearchOptions,
} from './ElasticSearchSearchEngine';
export type {
ElasticSearchSearchEngineIndexer,
plugins/search-backend-module-elasticsearch/src/index.ts
+8
View File
@@ -22,10 +22,18 @@
export { ElasticSearchSearchEngine } from './engines';
export type {
ElasticSearchAgentOptions,
ElasticSearchConcreteQuery,
ElasticSearchClientOptions,
ElasticSearchHighlightConfig,
ElasticSearchHighlightOptions,
ElasticSearchQueryTranslator,
ElasticSearchQueryTranslatorOptions,
ElasticSearchConnectionConstructor,
ElasticSearchTransportConstructor,
ElasticSearchNodeOptions,
ElasticSearchOptions,
ElasticSearchAuth,
ElasticSearchSearchEngineIndexer,
ElasticSearchSearchEngineIndexerOptions,
} from './engines';
plugins/search-backend-node/api-report.md
+19 -24
View File
@@ -24,7 +24,7 @@ import { Transform } from 'stream';
import { UrlReader } from '@backstage/backend-common';
import { Writable } from 'stream';
// @beta
// @public
export abstract class BatchSearchEngineIndexer extends Writable {
constructor(options: BatchSearchEngineOptions);
abstract finalize(): Promise<void>;
@@ -32,19 +32,19 @@ export abstract class BatchSearchEngineIndexer extends Writable {
abstract initialize(): Promise<void>;
}
// @beta (undocumented)
// @public
export type BatchSearchEngineOptions = {
batchSize: number;
};
// @beta (undocumented)
// @public
export type ConcreteLunrQuery = {
lunrQueryBuilder: lunr_2.Index.QueryBuilder;
documentTypes?: string[];
pageSize: number;
};
// @beta
// @public
export abstract class DecoratorBase extends Transform {
constructor();
abstract decorate(
@@ -54,7 +54,7 @@ export abstract class DecoratorBase extends Transform {
abstract initialize(): Promise<void>;
}
// @beta (undocumented)
// @public
export class IndexBuilder {
constructor({ logger, searchEngine }: IndexBuilderOptions);
addCollator({ factory, schedule }: RegisterCollatorParameters): void;
@@ -62,22 +62,20 @@ export class IndexBuilder {
build(): Promise<{
scheduler: Scheduler;
}>;
// (undocumented)
getDocumentTypes(): Record<string, DocumentTypeInfo>;
// (undocumented)
getSearchEngine(): SearchEngine;
}
// @beta (undocumented)
// @public
export type IndexBuilderOptions = {
searchEngine: SearchEngine;
logger: Logger;
};
// @beta (undocumented)
// @public
export type LunrQueryTranslator = (query: SearchQuery) => ConcreteLunrQuery;
// @beta (undocumented)
// @public
export class LunrSearchEngine implements SearchEngine {
constructor({ logger }: { logger: Logger });
// (undocumented)
@@ -100,7 +98,7 @@ export class LunrSearchEngine implements SearchEngine {
protected translator: QueryTranslator;
}
// @beta (undocumented)
// @public
export class LunrSearchEngineIndexer extends BatchSearchEngineIndexer {
constructor();
// (undocumented)
@@ -115,7 +113,7 @@ export class LunrSearchEngineIndexer extends BatchSearchEngineIndexer {
initialize(): Promise<void>;
}
// @beta
// @public
export class NewlineDelimitedJsonCollatorFactory
implements DocumentCollatorFactory
{
@@ -131,7 +129,7 @@ export class NewlineDelimitedJsonCollatorFactory
readonly visibilityPermission: Permission | undefined;
}
// @beta (undocumented)
// @public
export type NewlineDelimitedJsonCollatorFactoryOptions = {
type: string;
searchPattern: string;
@@ -140,18 +138,18 @@ export type NewlineDelimitedJsonCollatorFactoryOptions = {
visibilityPermission?: Permission;
};
// @beta
// @public
export interface RegisterCollatorParameters {
factory: DocumentCollatorFactory;
schedule: TaskRunner;
}
// @beta
// @public
export interface RegisterDecoratorParameters {
factory: DocumentDecoratorFactory;
}
// @beta (undocumented)
// @public
export class Scheduler {
constructor({ logger }: { logger: Logger });
addToSchedule({ id, task, scheduledRunner }: ScheduleTaskParameters): void;
@@ -160,25 +158,22 @@ export class Scheduler {
}
// @public
export interface ScheduleTaskParameters {
// (undocumented)
export type ScheduleTaskParameters = {
id: string;
// (undocumented)
scheduledRunner: TaskRunner;
// (undocumented)
task: TaskFunction;
}
scheduledRunner: TaskRunner;
};
export { SearchEngine };
// @beta
// @public
export class TestPipeline {
execute(): Promise<TestPipelineResult>;
withDocuments(documents: IndexableDocument[]): TestPipeline;
static withSubject(subject: Readable | Transform | Writable): TestPipeline;
}
// @beta
// @public
export type TestPipelineResult = {
error: unknown;
documents: IndexableDocument[];
plugins/search-backend-node/src/IndexBuilder.ts
+8 -1
View File
@@ -28,7 +28,8 @@ import {
} from './types';
/**
* @beta
* Used for adding collators, decorators and compile them into tasks which are added to a scheduler returned to the caller.
* @public
*/
export class IndexBuilder {
private collators: Record<string, RegisterCollatorParameters>;
@@ -45,10 +46,16 @@ export class IndexBuilder {
this.searchEngine = searchEngine;
}
/**
* Responsible for returning the registered search engine.
*/
getSearchEngine(): SearchEngine {
return this.searchEngine;
}
/**
* Responsible for returning the registered document types.
*/
getDocumentTypes(): Record<string, DocumentTypeInfo> {
return this.documentTypes;
}
plugins/search-backend-node/src/Scheduler.ts
+6 -4
View File
@@ -24,16 +24,18 @@ type TaskEnvelope = {
};
/**
* @public ScheduleTaskParameters
* ScheduleTaskParameters
* @public
*/
export interface ScheduleTaskParameters {
export type ScheduleTaskParameters = {
id: string;
task: TaskFunction;
scheduledRunner: TaskRunner;
}
};
/**
* @beta
* Scheduler responsible for all search tasks.
* @public
*/
export class Scheduler {
private logger: Logger;
plugins/search-backend-node/src/collators/NewlineDelimitedJsonCollatorFactory.ts
+3 -5
View File
@@ -23,7 +23,8 @@ import { Readable } from 'stream';
import { Logger } from 'winston';
/**
* @beta
* Options for instansiate NewlineDelimitedJsonCollatorFactory
* @public
*/
export type NewlineDelimitedJsonCollatorFactoryOptions = {
type: string;
@@ -60,15 +61,13 @@ export type NewlineDelimitedJsonCollatorFactoryOptions = {
* });
* ```
*
* @beta
* @public
*/
export class NewlineDelimitedJsonCollatorFactory
implements DocumentCollatorFactory
{
/** {@inheritDoc @backstage/plugin-search-common#DocumentCollatorFactory."type"} */
readonly type: string;
/** {@inheritDoc @backstage/plugin-search-common#DocumentCollatorFactory.visibilityPermission} */
public readonly visibilityPermission: Permission | undefined;
private constructor(
@@ -123,7 +122,6 @@ export class NewlineDelimitedJsonCollatorFactory
}
}
/** {@inheritDoc @backstage/plugin-search-common#DocumentCollatorFactory.getCollator} */
async getCollator(): Promise<Readable> {
// Search for files matching the given pattern.
const lastUrl = await this.lastUrl();
plugins/search-backend-node/src/engines/LunrSearchEngine.ts
+6 -3
View File
@@ -27,7 +27,8 @@ import { Logger } from 'winston';
import { LunrSearchEngineIndexer } from './LunrSearchEngineIndexer';
/**
* @beta
* Type of translated query for the Lunr Search Engine.
* @public
*/
export type ConcreteLunrQuery = {
lunrQueryBuilder: lunr.Index.QueryBuilder;
@@ -41,12 +42,14 @@ type LunrResultEnvelope = {
};
/**
* @beta
* Translator repsonsible for translating search term and filters to a query that the Lunr Search Engine understands.
* @public
*/
export type LunrQueryTranslator = (query: SearchQuery) => ConcreteLunrQuery;
/**
* @beta
* Lunr specific search engine implementation.
* @public
*/
export class LunrSearchEngine implements SearchEngine {
protected lunrIndices: Record<string, lunr.Index> = {};
plugins/search-backend-node/src/engines/LunrSearchEngineIndexer.ts
+2 -1
View File
@@ -19,7 +19,8 @@ import lunr from 'lunr';
import { BatchSearchEngineIndexer } from '../indexing';
/**
* @beta
* Lunr specific search engine indexer
* @public
*/
export class LunrSearchEngineIndexer extends BatchSearchEngineIndexer {
private schemaInitialized = false;
plugins/search-backend-node/src/indexing/BatchSearchEngineIndexer.ts
+3 -2
View File
@@ -19,7 +19,8 @@ import { IndexableDocument } from '@backstage/plugin-search-common';
import { Writable } from 'stream';
/**
* @beta
* Options for {@link BatchSearchEngineIndexer}
* @public
*/
export type BatchSearchEngineOptions = {
batchSize: number;
@@ -28,7 +29,7 @@ export type BatchSearchEngineOptions = {
/**
* Base class encapsulating batch-based stream processing. Useful as a base
* class for search engine indexers.
* @beta
* @public
*/
export abstract class BatchSearchEngineIndexer extends Writable {
private batchSize: number;
plugins/search-backend-node/src/indexing/DecoratorBase.ts
+1 -1
View File
@@ -21,7 +21,7 @@ import { Transform } from 'stream';
/**
* Base class encapsulating simple async transformations. Useful as a base
* class for Backstage search decorators.
* @beta
* @public
*/
export abstract class DecoratorBase extends Transform {
private initialized: Promise<undefined | Error>;
plugins/search-backend-node/src/test-utils/TestPipeline.ts
+2 -2
View File
@@ -19,7 +19,7 @@ import { pipeline, Readable, Transform, Writable } from 'stream';
/**
* Object resolved after a test pipeline is executed.
* @beta
* @public
*/
export type TestPipelineResult = {
/**
@@ -37,7 +37,7 @@ export type TestPipelineResult = {
/**
* Test utility for Backstage Search collators, decorators, and indexers.
* @beta
* @public
*/
export class TestPipeline {
private collator?: Readable;
plugins/search-backend-node/src/types.ts
+4 -3
View File
@@ -23,7 +23,8 @@ import {
import { Logger } from 'winston';
/**
* @beta
* Options required to instantiate the index builder.
* @public
*/
export type IndexBuilderOptions = {
searchEngine: SearchEngine;
@@ -32,7 +33,7 @@ export type IndexBuilderOptions = {
/**
* Parameters required to register a collator.
* @beta
* @public
*/
export interface RegisterCollatorParameters {
/**
@@ -48,7 +49,7 @@ export interface RegisterCollatorParameters {
/**
* Parameters required to register a decorator
* @beta
* @public
*/
export interface RegisterDecoratorParameters {
/**
plugins/search-backend/api-report.md
-4
View File
@@ -11,13 +11,9 @@ import { PermissionAuthorizer } from '@backstage/plugin-permission-common';
import { PermissionEvaluator } from '@backstage/plugin-permission-common';
import { SearchEngine } from '@backstage/plugin-search-backend-node';
// Warning: (ae-missing-release-tag) "createRouter" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export function createRouter(options: RouterOptions): Promise<express.Router>;
// Warning: (ae-missing-release-tag) "RouterOptions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export type RouterOptions = {
engine: SearchEngine;
plugins/search-backend/src/service/router.ts
+6
View File
@@ -51,6 +51,9 @@ const jsonObjectSchema: z.ZodSchema<JsonObject> = z.lazy(() => {
return z.record(jsonValueSchema);
});
/**
* @public
*/
export type RouterOptions = {
engine: SearchEngine;
types: Record<string, DocumentTypeInfo>;
@@ -61,6 +64,9 @@ export type RouterOptions = {
const allowedLocationProtocols = ['http:', 'https:'];
/**
* @public
*/
export async function createRouter(
options: RouterOptions,
): Promise<express.Router> {
plugins/search-common/api-report.md
+16 -16
View File
@@ -11,46 +11,46 @@ import { Readable } from 'stream';
import { Transform } from 'stream';
import { Writable } from 'stream';
// @beta
// @public
export interface DocumentCollatorFactory {
getCollator(): Promise<Readable>;
readonly type: string;
readonly visibilityPermission?: Permission;
}
// @beta
// @public
export interface DocumentDecoratorFactory {
getDecorator(): Promise<Transform>;
readonly types?: string[];
}
// @beta
// @public
export type DocumentTypeInfo = {
visibilityPermission?: Permission;
};
// @beta
// @public
export type IndexableDocument = SearchDocument & {
authorization?: {
resourceRef: string;
};
};
// @beta (undocumented)
// @public (undocumented)
export type IndexableResult = Result<IndexableDocument>;
// @beta (undocumented)
// @public (undocumented)
export type IndexableResultSet = ResultSet<IndexableDocument>;
// @beta
// @public
export type QueryRequestOptions = {
token?: string;
};
// @beta
// @public
export type QueryTranslator = (query: SearchQuery) => unknown;
// @beta (undocumented)
// @public (undocumented)
export interface Result<TDocument extends SearchDocument> {
// (undocumented)
document: TDocument;
@@ -60,7 +60,7 @@ export interface Result<TDocument extends SearchDocument> {
type: string;
}
// @beta
// @public
export interface ResultHighlight {
// (undocumented)
fields: {
@@ -70,7 +70,7 @@ export interface ResultHighlight {
preTag: string;
}
// @beta (undocumented)
// @public (undocumented)
export interface ResultSet<TDocument extends SearchDocument> {
// (undocumented)
nextPageCursor?: string;
@@ -80,14 +80,14 @@ export interface ResultSet<TDocument extends SearchDocument> {
results: Result<TDocument>[];
}
// @beta
// @public
export interface SearchDocument {
location: string;
text: string;
title: string;
}
// @beta
// @public
export interface SearchEngine {
getIndexer(type: string): Promise<Writable>;
query(
@@ -97,7 +97,7 @@ export interface SearchEngine {
setTranslator(translator: QueryTranslator): void;
}
// @beta (undocumented)
// @public (undocumented)
export interface SearchQuery {
// (undocumented)
filters?: JsonObject;
@@ -109,9 +109,9 @@ export interface SearchQuery {
types?: string[];
}
// @beta (undocumented)
// @public (undocumented)
export type SearchResult = Result<SearchDocument>;
// @beta (undocumented)
// @public (undocumented)
export type SearchResultSet = ResultSet<SearchDocument>;
```
plugins/search-common/src/types.ts
+16 -16
View File
@@ -19,7 +19,7 @@ import { JsonObject } from '@backstage/types';
import { Readable, Transform, Writable } from 'stream';
/**
* @beta
* @public
*/
export interface SearchQuery {
term: string;
@@ -29,10 +29,10 @@ export interface SearchQuery {
}
/**
* @beta
* Metadata for result relevant document fields with matched terms highlighted
* via wrapping in associated pre/post tags. The UI is expected to parse these
* field excerpts by replacing wrapping tags with applicable UI elements for rendering.
* @public
*/
export interface ResultHighlight {
/**
@@ -53,7 +53,7 @@ export interface ResultHighlight {
}
/**
* @beta
* @public
*/
export interface Result<TDocument extends SearchDocument> {
type: string;
@@ -62,7 +62,7 @@ export interface Result<TDocument extends SearchDocument> {
}
/**
* @beta
* @public
*/
export interface ResultSet<TDocument extends SearchDocument> {
results: Result<TDocument>[];
@@ -71,28 +71,28 @@ export interface ResultSet<TDocument extends SearchDocument> {
}
/**
* @beta
* @public
*/
export type SearchResult = Result<SearchDocument>;
/**
* @beta
* @public
*/
export type SearchResultSet = ResultSet<SearchDocument>;
/**
* @beta
* @public
*/
export type IndexableResult = Result<IndexableDocument>;
/**
* @beta
* @public
*/
export type IndexableResultSet = ResultSet<IndexableDocument>;
/**
* Base properties that all search documents must include.
* @beta
* @public
*/
export interface SearchDocument {
/**
@@ -117,7 +117,7 @@ export interface SearchDocument {
* backends working directly with documents being inserted or retrieved from
* search indexes. When dealing with documents in the frontend, use
* {@link SearchDocument}.
* @beta
* @public
*/
export type IndexableDocument = SearchDocument & {
/**
@@ -136,7 +136,7 @@ export type IndexableDocument = SearchDocument & {
* Information about a specific document type. Intended to be used in the
* {@link @backstage/plugin-search-backend-node#IndexBuilder} to collect information
* about the types stored in the index.
* @beta
* @public
*/
export type DocumentTypeInfo = {
/**
@@ -148,7 +148,7 @@ export type DocumentTypeInfo = {
/**
* Factory class for instantiating collators.
* @beta
* @public
*/
export interface DocumentCollatorFactory {
/**
@@ -171,7 +171,7 @@ export interface DocumentCollatorFactory {
/**
* Factory class for instantiating decorators.
* @beta
* @public
*/
export interface DocumentDecoratorFactory {
/**
@@ -190,13 +190,13 @@ 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
* @public
*/
export type QueryTranslator = (query: SearchQuery) => unknown;
/**
* Options when querying a search engine.
* @beta
* @public
*/
export type QueryRequestOptions = {
token?: string;
@@ -206,7 +206,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
* @public
*/
export interface SearchEngine {
/**
scripts/api-extractor.ts
+2
View File
@@ -256,7 +256,9 @@ const NO_WARNING_PACKAGES = [
'plugins/scaffolder-backend-module-rails',
'plugins/scaffolder-backend-module-yeoman',
'plugins/scaffolder-common',
'plugins/search-backend',
'plugins/search-backend-node',
'plugins/search-backend-module-elasticsearch',
'plugins/search-common',
'plugins/search-react',
'plugins/techdocs',