backend-plugin-api: document core service refs

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

.changeset/rich-clouds-smile.md

@@ -0,0 +1,5 @@
+---
+'@backstage/backend-plugin-api': patch
+---
+
+Documented `coreServices` an all of its members.

packages/backend-plugin-api/api-report.md

@@ -69,34 +69,26 @@ export interface BackendRegistrationPoints {
 // @public (undocumented)
 export type CacheService = PluginCacheManager;
 
-// @public (undocumented)
-const cacheServiceRef: ServiceRef<PluginCacheManager, 'plugin'>;
-
 // @public (undocumented)
 export type ConfigService = Config;
 
-// @public (undocumented)
-const configServiceRef: ServiceRef<Config, 'root'>;
-
-declare namespace coreServices {
-  export {
-    configServiceRef as config,
-    httpRouterServiceRef as httpRouter,
-    loggerServiceRef as logger,
-    urlReaderServiceRef as urlReader,
-    cacheServiceRef as cache,
-    databaseServiceRef as database,
-    discoveryServiceRef as discovery,
-    tokenManagerServiceRef as tokenManager,
-    permissionsServiceRef as permissions,
-    schedulerServiceRef as scheduler,
-    rootLifecycleServiceRef as rootLifecycle,
-    rootLoggerServiceRef as rootLogger,
-    pluginMetadataServiceRef as pluginMetadata,
-    lifecycleServiceRef as lifecycle,
-  };
+// @public
+export namespace coreServices {
+  const cache: ServiceRef<PluginCacheManager, 'plugin'>;
+  const config: ServiceRef<Config, 'root'>;
+  const database: ServiceRef<PluginDatabaseManager, 'plugin'>;
+  const discovery: ServiceRef<DiscoveryService, 'plugin'>;
+  const httpRouter: ServiceRef<HttpRouterService, 'plugin'>;
+  const lifecycle: ServiceRef<LifecycleService, 'plugin'>;
+  const logger: ServiceRef<LoggerService, 'plugin'>;
+  const permissions: ServiceRef<PermissionsService, 'plugin'>;
+  const pluginMetadata: ServiceRef<PluginMetadataService, 'plugin'>;
+  const rootLifecycle: ServiceRef<LifecycleService, 'root'>;
+  const rootLogger: ServiceRef<LoggerService, 'root'>;
+  const scheduler: ServiceRef<PluginTaskScheduler, 'plugin'>;
+  const tokenManager: ServiceRef<TokenManager, 'plugin'>;
+  const urlReader: ServiceRef<UrlReaderService, 'plugin'>;
 }
-export { coreServices };
 
 // @public
 export function createBackendModule<
@@ -165,18 +157,12 @@ export function createServiceRef<T>(options: {
 // @public (undocumented)
 export type DatabaseService = PluginDatabaseManager;
 
-// @public (undocumented)
-const databaseServiceRef: ServiceRef<PluginDatabaseManager, 'plugin'>;
-
 // @public
 export type DiscoveryService = {
   getBaseUrl(pluginId: string): Promise<string>;
   getExternalBaseUrl(pluginId: string): Promise<string>;
 };
 
-// @public (undocumented)
-const discoveryServiceRef: ServiceRef<DiscoveryService, 'plugin'>;
-
 // @public
 export type ExtensionPoint<T> = {
   id: string;
@@ -191,24 +177,18 @@ export interface HttpRouterService {
   use(handler: Handler): void;
 }
 
-// @public (undocumented)
-const httpRouterServiceRef: ServiceRef<HttpRouterService, 'plugin'>;
-
 // @public (undocumented)
 export interface LifecycleService {
   addShutdownHook(options: LifecycleServiceShutdownHook): void;
 }
 
-// @public (undocumented)
-const lifecycleServiceRef: ServiceRef<LifecycleService, 'plugin'>;
-
 // @public (undocumented)
 export type LifecycleServiceShutdownHook = {
   fn: () => void | Promise<void>;
   labels?: Record<string, string>;
 };
 
-// @public (undocumented)
+// @public
 export interface LoggerService {
   // (undocumented)
   child(meta: LogMeta): LoggerService;
@@ -222,9 +202,6 @@ export interface LoggerService {
   warn(message: string, meta?: Error | LogMeta): void;
 }
 
-// @public (undocumented)
-const loggerServiceRef: ServiceRef<LoggerService, 'plugin'>;
-
 // @public (undocumented)
 export function loggerToWinstonLogger(
   logger: LoggerService,
@@ -239,18 +216,12 @@ export type LogMeta = {
 // @public (undocumented)
 export type PermissionsService = PermissionEvaluator | PermissionAuthorizer;
 
-// @public (undocumented)
-const permissionsServiceRef: ServiceRef<PermissionsService, 'plugin'>;
-
 // @public (undocumented)
 export interface PluginMetadataService {
   // (undocumented)
   getId(): string;
 }
 
-// @public (undocumented)
-const pluginMetadataServiceRef: ServiceRef<PluginMetadataService, 'plugin'>;
-
 // @public
 export type ReadTreeOptions = {
   filter?(
@@ -298,21 +269,12 @@ export type ReadUrlResponse = {
 // @public (undocumented)
 export type RootLifecycleService = LifecycleService;
 
-// @public (undocumented)
-const rootLifecycleServiceRef: ServiceRef<LifecycleService, 'root'>;
-
 // @public (undocumented)
 export type RootLoggerService = LoggerService;
 
-// @public (undocumented)
-const rootLoggerServiceRef: ServiceRef<LoggerService, 'root'>;
-
 // @public (undocumented)
 export type SchedulerService = PluginTaskScheduler;
 
-// @public (undocumented)
-const schedulerServiceRef: ServiceRef<PluginTaskScheduler, 'plugin'>;
-
 // @public
 export type SearchOptions = {
   etag?: string;
@@ -373,9 +335,6 @@ export type ServiceRef<
 // @public (undocumented)
 export type TokenManagerService = TokenManager;
 
-// @public (undocumented)
-const tokenManagerServiceRef: ServiceRef<TokenManager, 'plugin'>;
-
 // @public (undocumented)
 export type TypesToServiceRef<T> = {
   [key in keyof T]: ServiceRef<T[key]>;
@@ -387,7 +346,4 @@ export type UrlReaderService = {
   readTree(url: string, options?: ReadTreeOptions): Promise<ReadTreeResponse>;
   search(url: string, options?: SearchOptions): Promise<SearchResponse>;
 };
-
-// @public (undocumented)
-const urlReaderServiceRef: ServiceRef<UrlReaderService, 'plugin'>;
 ```

packages/backend-plugin-api/src/services/definitions/CacheService.ts

@@ -14,15 +14,7 @@
  * limitations under the License.
  */
 
-import { createServiceRef } from '../system/types';
 import { PluginCacheManager } from '@backstage/backend-common';
 
 /** @public */
 export type CacheService = PluginCacheManager;
-
-/**
- * @public
- */
-export const cacheServiceRef = createServiceRef<CacheService>({
-  id: 'core.cache',
-});

packages/backend-plugin-api/src/services/definitions/ConfigService.ts

@@ -15,17 +15,8 @@
  */
 
 import { Config } from '@backstage/config';
-import { createServiceRef } from '../system/types';
 
 /**
  * @public
  */
 export type ConfigService = Config;
-
-/**
- * @public
- */
-export const configServiceRef = createServiceRef<ConfigService>({
-  id: 'core.root.config',
-  scope: 'root',
-});

packages/backend-plugin-api/src/services/definitions/DatabaseService.ts

@@ -15,14 +15,6 @@
  */
 
 import { PluginDatabaseManager } from '@backstage/backend-common';
-import { createServiceRef } from '../system/types';
 
 /** @public */
 export type DatabaseService = PluginDatabaseManager;
-
-/**
- * @public
- */
-export const databaseServiceRef = createServiceRef<DatabaseService>({
-  id: 'core.database',
-});

packages/backend-plugin-api/src/services/definitions/DiscoveryService.ts

@@ -14,8 +14,6 @@
  * limitations under the License.
  */
 
-import { createServiceRef } from '../system/types';
-
 /**
  * The DiscoveryService is used to provide a mechanism for backend
  * plugins to discover the endpoints for itself or other backend plugins.
@@ -63,10 +61,3 @@ export type DiscoveryService = {
    */
   getExternalBaseUrl(pluginId: string): Promise<string>;
 };
-
-/**
- * @public
- */
-export const discoveryServiceRef = createServiceRef<DiscoveryService>({
-  id: 'core.discovery',
-});

packages/backend-plugin-api/src/services/definitions/HttpRouterService.ts

@@ -14,7 +14,6 @@
  * limitations under the License.
  */
 
-import { createServiceRef } from '../system/types';
 import { Handler } from 'express';
 
 /**
@@ -23,10 +22,3 @@ import { Handler } from 'express';
 export interface HttpRouterService {
   use(handler: Handler): void;
 }
-
-/**
- * @public
- */
-export const httpRouterServiceRef = createServiceRef<HttpRouterService>({
-  id: 'core.httpRouter',
-});

packages/backend-plugin-api/src/services/definitions/LifecycleService.ts

@@ -14,8 +14,6 @@
  * limitations under the License.
  */
 
-import { createServiceRef } from '../system/types';
-
 /**
  * @public
  **/
@@ -35,11 +33,3 @@ export interface LifecycleService {
    */
   addShutdownHook(options: LifecycleServiceShutdownHook): void;
 }
-
-/**
- * @public
- */
-export const lifecycleServiceRef = createServiceRef<LifecycleService>({
-  id: 'core.lifecycle',
-  scope: 'plugin',
-});

packages/backend-plugin-api/src/services/definitions/LoggerService.ts

@@ -14,14 +14,14 @@
  * limitations under the License.
  */
 
-import { createServiceRef } from '../system/types';
-
 /**
  * @public
  */
 export type LogMeta = { [name: string]: unknown };
 
 /**
+ * A service that provides a logging facility.
+ *
  * @public
  */
 export interface LoggerService {
@@ -32,10 +32,3 @@ export interface LoggerService {
 
   child(meta: LogMeta): LoggerService;
 }
-
-/**
- * @public
- */
-export const loggerServiceRef = createServiceRef<LoggerService>({
-  id: 'core.logger',
-});

packages/backend-plugin-api/src/services/definitions/PermissionsService.ts

@@ -14,7 +14,6 @@
  * limitations under the License.
  */
 
-import { createServiceRef } from '../system/types';
 import {
   PermissionAuthorizer,
   PermissionEvaluator,
@@ -22,10 +21,3 @@ import {
 
 /** @public */
 export type PermissionsService = PermissionEvaluator | PermissionAuthorizer;
-
-/**
- * @public
- */
-export const permissionsServiceRef = createServiceRef<PermissionsService>({
-  id: 'core.permissions',
-});

packages/backend-plugin-api/src/services/definitions/PluginMetadataService.ts

@@ -14,20 +14,9 @@
  * limitations under the License.
  */
 
-import { createServiceRef } from '../system/types';
-
 /**
  * @public
  */
 export interface PluginMetadataService {
   getId(): string;
 }
-
-/**
- * @public
- */
-export const pluginMetadataServiceRef = createServiceRef<PluginMetadataService>(
-  {
-    id: 'core.plugin-metadata',
-  },
-);

packages/backend-plugin-api/src/services/definitions/RootLifecycleService.ts

@@ -14,16 +14,7 @@
  * limitations under the License.
  */
 
-import { createServiceRef } from '../system/types';
-import { LifecycleService } from './lifecycleServiceRef';
+import { LifecycleService } from './LifecycleService';
 
 /** @public */
 export type RootLifecycleService = LifecycleService;
-
-/**
- * @public
- */
-export const rootLifecycleServiceRef = createServiceRef<RootLifecycleService>({
-  id: 'core.rootLifecycle',
-  scope: 'root',
-});

packages/backend-plugin-api/src/services/definitions/RootLoggerService.ts

@@ -14,16 +14,7 @@
  * limitations under the License.
  */
 
-import { createServiceRef } from '../system/types';
-import { LoggerService } from './loggerServiceRef';
+import { LoggerService } from './LoggerService';
 
 /** @public */
 export type RootLoggerService = LoggerService;
-
-/**
- * @public
- */
-export const rootLoggerServiceRef = createServiceRef<RootLoggerService>({
-  id: 'core.root.logger',
-  scope: 'root',
-});

packages/backend-plugin-api/src/services/definitions/SchedulerService.ts

@@ -14,15 +14,7 @@
  * limitations under the License.
  */
 
-import { createServiceRef } from '../system/types';
 import { PluginTaskScheduler } from '@backstage/backend-tasks';
 
 /** @public */
 export type SchedulerService = PluginTaskScheduler;
-
-/**
- * @public
- */
-export const schedulerServiceRef = createServiceRef<SchedulerService>({
-  id: 'core.scheduler',
-});

packages/backend-plugin-api/src/services/definitions/TokenManagerService.ts

@@ -14,15 +14,7 @@
  * limitations under the License.
  */
 
-import { createServiceRef } from '../system/types';
 import { TokenManager } from '@backstage/backend-common';
 
 /** @public */
 export type TokenManagerService = TokenManager;
-
-/**
- * @public
- */
-export const tokenManagerServiceRef = createServiceRef<TokenManagerService>({
-  id: 'core.tokenManager',
-});

packages/backend-plugin-api/src/services/definitions/UrlReaderService.ts

@@ -14,7 +14,6 @@
  * limitations under the License.
  */
 
-import { createServiceRef } from '../system/types';
 import { Readable } from 'stream';
 
 /**
@@ -280,10 +279,3 @@ export type SearchResponseFile = {
    */
   content(): Promise<Buffer>;
 };
-
-/**
- * @public
- */
-export const urlReaderServiceRef = createServiceRef<UrlReaderService>({
-  id: 'core.urlReader',
-});

packages/backend-plugin-api/src/services/definitions/coreServices.ts

@@ -14,17 +14,165 @@
  * limitations under the License.
  */
 
-export { configServiceRef as config } from './configServiceRef';
-export { httpRouterServiceRef as httpRouter } from './httpRouterServiceRef';
-export { loggerServiceRef as logger } from './loggerServiceRef';
-export { urlReaderServiceRef as urlReader } from './urlReaderServiceRef';
-export { cacheServiceRef as cache } from './cacheServiceRef';
-export { databaseServiceRef as database } from './databaseServiceRef';
-export { discoveryServiceRef as discovery } from './discoveryServiceRef';
-export { tokenManagerServiceRef as tokenManager } from './tokenManagerServiceRef';
-export { permissionsServiceRef as permissions } from './permissionsServiceRef';
-export { schedulerServiceRef as scheduler } from './schedulerServiceRef';
-export { rootLifecycleServiceRef as rootLifecycle } from './rootLifecycleServiceRef';
-export { rootLoggerServiceRef as rootLogger } from './rootLoggerServiceRef';
-export { pluginMetadataServiceRef as pluginMetadata } from './pluginMetadataServiceRef';
-export { lifecycleServiceRef as lifecycle } from './lifecycleServiceRef';
+import { createServiceRef } from '../system';
+
+/**
+ * All core services references
+ *
+ * @public
+ */
+export namespace coreServices {
+  /**
+   * The service reference for the plugin scoped {@link CacheService}.
+   *
+   * @public
+   */
+  export const cache = createServiceRef<import('./CacheService').CacheService>({
+    id: 'core.cache',
+  });
+
+  /**
+   * The service reference for the root scoped {@link ConfigService}.
+   *
+   * @public
+   */
+  export const config = createServiceRef<
+    import('./ConfigService').ConfigService
+  >({
+    id: 'core.root.config',
+    scope: 'root',
+  });
+
+  /**
+   * The service reference for the plugin scoped {@link DatabaseService}.
+   *
+   * @public
+   */
+  export const database = createServiceRef<
+    import('./DatabaseService').DatabaseService
+  >({
+    id: 'core.database',
+  });
+
+  /**
+   * The service reference for the plugin scoped {@link DiscoveryService}.
+   *
+   * @public
+   */
+  export const discovery = createServiceRef<
+    import('./DiscoveryService').DiscoveryService
+  >({
+    id: 'core.discovery',
+  });
+
+  /**
+   * The service reference for the plugin scoped {@link HttpRouterService}.
+   *
+   * @public
+   */
+  export const httpRouter = createServiceRef<
+    import('./HttpRouterService').HttpRouterService
+  >({ id: 'core.httpRouter' });
+
+  /**
+   * The service reference for the plugin scoped {@link LifecycleService}.
+   *
+   * @public
+   */
+  export const lifecycle = createServiceRef<
+    import('./LifecycleService').LifecycleService
+  >({
+    id: 'core.lifecycle',
+    scope: 'plugin',
+  });
+
+  /**
+   * The service reference for the plugin scoped {@link LoggerService}.
+   *
+   * @public
+   */
+  export const logger = createServiceRef<
+    import('./LoggerService').LoggerService
+  >({
+    id: 'core.logger',
+  });
+
+  /**
+   * The service reference for the plugin scoped {@link PermissionsService}.
+   *
+   * @public
+   */
+  export const permissions = createServiceRef<
+    import('./PermissionsService').PermissionsService
+  >({
+    id: 'core.permissions',
+  });
+
+  /**
+   * The service reference for the plugin scoped {@link PluginMetadataService}.
+   *
+   * @public
+   */
+  export const pluginMetadata = createServiceRef<
+    import('./PluginMetadataService').PluginMetadataService
+  >({
+    id: 'core.plugin-metadata',
+  });
+
+  /**
+   * The service reference for the root scoped {@link RootLifecycleService}.
+   *
+   * @public
+   */
+  export const rootLifecycle = createServiceRef<
+    import('./RootLifecycleService').RootLifecycleService
+  >({
+    id: 'core.rootLifecycle',
+    scope: 'root',
+  });
+
+  /**
+   * The service reference for the root scoped {@link RootLoggerService}.
+   *
+   * @public
+   */
+  export const rootLogger = createServiceRef<
+    import('./RootLoggerService').RootLoggerService
+  >({
+    id: 'core.root.logger',
+    scope: 'root',
+  });
+
+  /**
+   * The service reference for the plugin scoped {@link SchedulerService}.
+   *
+   * @public
+   */
+  export const scheduler = createServiceRef<
+    import('./SchedulerService').SchedulerService
+  >({
+    id: 'core.scheduler',
+  });
+
+  /**
+   * The service reference for the plugin scoped {@link TokenManagerService}.
+   *
+   * @public
+   */
+  export const tokenManager = createServiceRef<
+    import('./TokenManagerService').TokenManagerService
+  >({
+    id: 'core.tokenManager',
+  });
+
+  /**
+   * The service reference for the plugin scoped {@link UrlReaderService}.
+   *
+   * @public
+   */
+  export const urlReader = createServiceRef<
+    import('./UrlReaderService').UrlReaderService
+  >({
+    id: 'core.urlReader',
+  });
+}

packages/backend-plugin-api/src/services/definitions/index.ts

@@ -14,25 +14,23 @@
  * limitations under the License.
  */
 
-import * as coreServices from './coreServices';
-
-export { coreServices };
-export type { CacheService } from './cacheServiceRef';
-export type { ConfigService } from './configServiceRef';
-export type { DatabaseService } from './databaseServiceRef';
-export type { DiscoveryService } from './discoveryServiceRef';
-export type { HttpRouterService } from './httpRouterServiceRef';
+export { coreServices } from './coreServices';
+export type { CacheService } from './CacheService';
+export type { ConfigService } from './ConfigService';
+export type { DatabaseService } from './DatabaseService';
+export type { DiscoveryService } from './DiscoveryService';
+export type { HttpRouterService } from './HttpRouterService';
 export type {
   LifecycleService,
   LifecycleServiceShutdownHook,
-} from './lifecycleServiceRef';
-export type { LoggerService, LogMeta } from './loggerServiceRef';
-export type { PermissionsService } from './permissionsServiceRef';
-export type { PluginMetadataService } from './pluginMetadataServiceRef';
-export type { RootLifecycleService } from './rootLifecycleServiceRef';
-export type { RootLoggerService } from './rootLoggerServiceRef';
-export type { SchedulerService } from './schedulerServiceRef';
-export type { TokenManagerService } from './tokenManagerServiceRef';
+} from './LifecycleService';
+export type { LoggerService, LogMeta } from './LoggerService';
+export type { PermissionsService } from './PermissionsService';
+export type { PluginMetadataService } from './PluginMetadataService';
+export type { RootLifecycleService } from './RootLifecycleService';
+export type { RootLoggerService } from './RootLoggerService';
+export type { SchedulerService } from './SchedulerService';
+export type { TokenManagerService } from './TokenManagerService';
 export type {
   ReadTreeOptions,
   ReadTreeResponse,
@@ -44,4 +42,4 @@ export type {
   SearchResponse,
   SearchResponseFile,
   UrlReaderService,
-} from './urlReaderServiceRef';
+} from './UrlReaderService';