@backstage/backend-plugin-api 0.3.2-next.1 → 0.4.0

package/dist/index.d.ts

@@ -9,6 +9,7 @@
 import { Config } from '@backstage/config';
 import { Handler } from 'express';
 import { IdentityApi } from '@backstage/plugin-auth-node';
+import { JsonObject } from '@backstage/types';
 import { JsonValue } from '@backstage/types';
 import { Knex } from 'knex';
 import { PermissionEvaluator } from '@backstage/plugin-permission-common';
@@ -17,8 +18,7 @@ import { Readable } from 'stream';
 
 /** @public */
 export declare interface BackendFeature {
-    id: string;
-    register(reg: BackendRegistrationPoints): void;
+    $$type: '@backstage/BackendFeature';
 }
 
 /**
@@ -71,7 +71,7 @@ export declare interface BackendPluginConfig {
      *
      * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
      */
-    id: string;
+    pluginId: string;
     register(reg: BackendPluginRegistrationPoints): void;
 }
 
@@ -93,54 +93,39 @@ export declare interface BackendPluginRegistrationPoints {
 }
 
 /**
- * The callbacks passed to the `register` method of a backend feature; this is
- * essentially a superset of {@link BackendPluginRegistrationPoints} and
- * {@link BackendModuleRegistrationPoints}.
- *
- * @public
- */
-export declare interface BackendRegistrationPoints {
-    registerExtensionPoint<TExtensionPoint>(ref: ExtensionPoint<TExtensionPoint>, impl: TExtensionPoint): void;
-    registerInit<Deps extends {
-        [name in string]: unknown;
-    }>(options: {
-        deps: {
-            [name in keyof Deps]: ServiceRef<Deps[name]> | ExtensionPoint<Deps[name]>;
-        };
-        init(deps: Deps): Promise<void>;
-    }): void;
-}
-
-/**
- * A pre-configured, storage agnostic cache client suitable for use by
+ * A pre-configured, storage agnostic cache service suitable for use by
  * Backstage plugins.
  *
  * @public
  */
-export declare interface CacheClient {
+export declare interface CacheService {
     /**
      * Reads data from a cache store for the given key. If no data was found,
      * returns undefined.
      */
-    get(key: string): Promise<JsonValue | undefined>;
+    get<TValue extends JsonValue>(key: string): Promise<TValue | undefined>;
     /**
      * Writes the given data to a cache store, associated with the given key. An
      * optional TTL may also be provided, otherwise it defaults to the TTL that
      * was provided when the client was instantiated.
      */
-    set(key: string, value: JsonValue, options?: CacheClientSetOptions): Promise<void>;
+    set(key: string, value: JsonValue, options?: CacheServiceSetOptions): Promise<void>;
     /**
      * Removes the given key from the cache store.
      */
     delete(key: string): Promise<void>;
+    /**
+     * Creates a new {@link CacheService} instance with the given options.
+     */
+    withOptions(options: CacheServiceOptions): CacheService;
 }
 
 /**
- * Options given when constructing a {@link CacheClient}.
+ * Options passed to {@link CacheService.withOptions}.
  *
  * @public
  */
-export declare type CacheClientOptions = {
+export declare type CacheServiceOptions = {
     /**
      * An optional default TTL (in milliseconds) to be set when getting a client
      * instance. If not provided, data will persist indefinitely by default (or
@@ -150,11 +135,11 @@ export declare type CacheClientOptions = {
 };
 
 /**
- * Options passed to {@link CacheClient.set}.
+ * Options passed to {@link CacheService.set}.
  *
  * @public
  */
-export declare type CacheClientSetOptions = {
+export declare type CacheServiceSetOptions = {
     /**
      * Optional TTL in milliseconds. Defaults to the TTL provided when the client
      * was set up (or no TTL if none are provided).
@@ -162,24 +147,6 @@ export declare type CacheClientSetOptions = {
     ttl?: number;
 };
 
-/**
- * Manages access to cache stores that plugins get.
- *
- * @public
- */
-export declare interface CacheService {
-    /**
-     * Provides backend plugins cache connections for themselves.
-     *
-     * @remarks
-     *
-     * The purpose of this method is to allow plugins to get isolated data stores
-     * so that plugins are discouraged from cache-level integration and/or cache
-     * key collisions.
-     */
-    getClient: (options?: CacheClientOptions) => CacheClient;
-}
-
 /**
  * @public
  */
@@ -324,7 +291,7 @@ export declare function createExtensionPoint<T>(config: ExtensionPointConfig): E
  */
 export declare function createServiceFactory<TService, TImpl extends TService, TDeps extends {
     [name in string]: ServiceRef<unknown>;
-}, TOpts extends object | undefined = undefined>(config: RootServiceFactoryConfig<TService, TImpl, TDeps>): () => ServiceFactory<TService>;
+}, TOpts extends object | undefined = undefined>(config: RootServiceFactoryConfig<TService, TImpl, TDeps>): () => ServiceFactory<TService, 'root'>;
 
 /**
  * Creates a root scoped service factory with optional options.
@@ -334,7 +301,7 @@ export declare function createServiceFactory<TService, TImpl extends TService, T
  */
 export declare function createServiceFactory<TService, TImpl extends TService, TDeps extends {
     [name in string]: ServiceRef<unknown>;
-}, TOpts extends object | undefined = undefined>(config: (options?: TOpts) => RootServiceFactoryConfig<TService, TImpl, TDeps>): (options?: TOpts) => ServiceFactory<TService>;
+}, TOpts extends object | undefined = undefined>(config: (options?: TOpts) => RootServiceFactoryConfig<TService, TImpl, TDeps>): (options?: TOpts) => ServiceFactory<TService, 'root'>;
 
 /**
  * Creates a root scoped service factory with required options.
@@ -344,7 +311,7 @@ export declare function createServiceFactory<TService, TImpl extends TService, T
  */
 export declare function createServiceFactory<TService, TImpl extends TService, TDeps extends {
     [name in string]: ServiceRef<unknown>;
-}, TOpts extends object | undefined = undefined>(config: (options: TOpts) => RootServiceFactoryConfig<TService, TImpl, TDeps>): (options: TOpts) => ServiceFactory<TService>;
+}, TOpts extends object | undefined = undefined>(config: (options: TOpts) => RootServiceFactoryConfig<TService, TImpl, TDeps>): (options: TOpts) => ServiceFactory<TService, 'root'>;
 
 /**
  * Creates a plugin scoped service factory without options.
@@ -354,7 +321,7 @@ export declare function createServiceFactory<TService, TImpl extends TService, T
  */
 export declare function createServiceFactory<TService, TImpl extends TService, TDeps extends {
     [name in string]: ServiceRef<unknown>;
-}, TContext = undefined, TOpts extends object | undefined = undefined>(config: PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>): () => ServiceFactory<TService>;
+}, TContext = undefined, TOpts extends object | undefined = undefined>(config: PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>): () => ServiceFactory<TService, 'plugin'>;
 
 /**
  * Creates a plugin scoped service factory with optional options.
@@ -364,7 +331,7 @@ export declare function createServiceFactory<TService, TImpl extends TService, T
  */
 export declare function createServiceFactory<TService, TImpl extends TService, TDeps extends {
     [name in string]: ServiceRef<unknown>;
-}, TContext = undefined, TOpts extends object | undefined = undefined>(config: (options?: TOpts) => PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>): (options?: TOpts) => ServiceFactory<TService>;
+}, TContext = undefined, TOpts extends object | undefined = undefined>(config: (options?: TOpts) => PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>): (options?: TOpts) => ServiceFactory<TService, 'plugin'>;
 
 /**
  * Creates a plugin scoped service factory with required options.
@@ -374,7 +341,7 @@ export declare function createServiceFactory<TService, TImpl extends TService, T
  */
 export declare function createServiceFactory<TService, TImpl extends TService, TDeps extends {
     [name in string]: ServiceRef<unknown>;
-}, TContext = undefined, TOpts extends object | undefined = undefined>(config: PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps> | ((options: TOpts) => PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>)): (options: TOpts) => ServiceFactory<TService>;
+}, TContext = undefined, TOpts extends object | undefined = undefined>(config: PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps> | ((options: TOpts) => PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>)): (options: TOpts) => ServiceFactory<TService, 'plugin'>;
 
 /**
  * Creates a new service definition. This overload is used to create plugin scoped services.
@@ -484,7 +451,7 @@ export declare type ExtensionPoint<T> = {
      */
     T: T;
     toString(): string;
-    $$ref: 'extension-point';
+    $$type: '@backstage/ExtensionPoint';
 };
 
 /**
@@ -516,24 +483,28 @@ export declare interface IdentityService extends IdentityApi {
 
 /**
  * @public
- **/
+ */
 export declare interface LifecycleService {
     /**
      * Register a function to be called when the backend is shutting down.
      */
-    addShutdownHook(options: LifecycleServiceShutdownHook): void;
+    addShutdownHook(hook: LifecycleServiceShutdownHook, options?: LifecycleServiceShutdownOptions): void;
 }
 
 /**
  * @public
- **/
-export declare type LifecycleServiceShutdownHook = {
-    fn: () => void | Promise<void>;
+ */
+export declare type LifecycleServiceShutdownHook = () => void | Promise<void>;
+
+/**
+ * @public
+ */
+export declare interface LifecycleServiceShutdownOptions {
     /**
      * Optional {@link LoggerService} that will be used for logging instead of the default logger.
      */
     logger?: LoggerService;
-};
+}
 
 /**
  * A service that provides a logging facility.
@@ -541,20 +512,13 @@ export declare type LifecycleServiceShutdownHook = {
  * @public
  */
 export declare interface LoggerService {
-    error(message: string, meta?: Error | LogMeta): void;
-    warn(message: string, meta?: Error | LogMeta): void;
-    info(message: string, meta?: Error | LogMeta): void;
-    debug(message: string, meta?: Error | LogMeta): void;
-    child(meta: LogMeta): LoggerService;
+    error(message: string, meta?: Error | JsonObject): void;
+    warn(message: string, meta?: Error | JsonObject): void;
+    info(message: string, meta?: Error | JsonObject): void;
+    debug(message: string, meta?: Error | JsonObject): void;
+    child(meta: JsonObject): LoggerService;
 }
 
-/**
- * @public
- */
-export declare type LogMeta = {
-    [name: string]: unknown;
-};
-
 /** @public */
 export declare interface PermissionsService extends PermissionEvaluator {
 }
@@ -842,35 +806,17 @@ export declare type SearchResponseFile = {
 };
 
 /** @public */
-export declare type ServiceFactory<TService = unknown> = {
-    scope: 'root';
-    service: ServiceRef<TService, 'root'>;
-    deps: {
-        [key in string]: ServiceRef<unknown>;
-    };
-    factory(deps: {
-        [key in string]: unknown;
-    }): Promise<TService>;
-} | {
-    scope: 'plugin';
-    service: ServiceRef<TService, 'plugin'>;
-    deps: {
-        [key in string]: ServiceRef<unknown>;
-    };
-    createRootContext?(deps: {
-        [key in string]: unknown;
-    }): Promise<unknown>;
-    factory(deps: {
-        [key in string]: unknown;
-    }, context: unknown): Promise<TService>;
-};
+export declare interface ServiceFactory<TService = unknown, TScope extends 'plugin' | 'root' = 'plugin' | 'root'> {
+    $$type: '@backstage/ServiceFactory';
+    service: ServiceRef<TService, TScope>;
+}
 
 /**
  * Represents either a {@link ServiceFactory} or a function that returns one.
  *
  * @public
  */
-export declare type ServiceFactoryOrFunction<TService = unknown> = ServiceFactory<TService> | (() => ServiceFactory<TService>);
+export declare type ServiceFactoryOrFunction = ServiceFactory | (() => ServiceFactory);
 
 /**
  * TODO
@@ -895,14 +841,14 @@ export declare type ServiceRef<TService, TScope extends 'root' | 'plugin' = 'roo
      */
     T: TService;
     toString(): string;
-    $$ref: 'service';
+    $$type: '@backstage/ServiceRef';
 };
 
 /** @public */
 export declare interface ServiceRefConfig<TService, TScope extends 'root' | 'plugin'> {
     id: string;
     scope?: TScope;
-    defaultFactory?: (service: ServiceRef<TService, TScope>) => Promise<ServiceFactoryOrFunction<TService>>;
+    defaultFactory?: (service: ServiceRef<TService, TScope>) => Promise<ServiceFactoryOrFunction>;
 }
 
 /** @ignore */
@@ -918,7 +864,7 @@ declare type ServiceRefsToInstances<T extends {
  * @public
  */
 export declare interface SharedBackendEnvironment {
-    $$type: 'SharedBackendEnvironment';
+    $$type: '@backstage/SharedBackendEnvironment';
 }
 
 /**
@@ -955,11 +901,6 @@ export declare interface TokenManagerService {
     authenticate(token: string): Promise<void>;
 }
 
-/** @public */
-export declare type TypesToServiceRef<T> = {
-    [key in keyof T]: ServiceRef<T[key]>;
-};
-
 /**
  * A generic interface for fetching plain data from URLs.
  *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@backstage/backend-plugin-api",
   "description": "Core API used by Backstage backend plugins",
-  "version": "0.3.2-next.1",
+  "version": "0.4.0",
   "main": "dist/index.cjs.js",
   "types": "dist/index.d.ts",
   "publishConfig": {
@@ -33,9 +33,9 @@
     "start": "backstage-cli package start"
   },
   "dependencies": {
-    "@backstage/backend-tasks": "^0.4.3-next.1",
+    "@backstage/backend-tasks": "^0.4.3",
     "@backstage/config": "^1.0.6",
-    "@backstage/plugin-auth-node": "^0.2.11-next.1",
+    "@backstage/plugin-auth-node": "^0.2.11",
     "@backstage/plugin-permission-common": "^0.7.3",
     "@backstage/types": "^1.0.2",
     "@types/express": "^4.17.6",
@@ -43,7 +43,7 @@
     "knex": "^2.0.0"
   },
   "devDependencies": {
-    "@backstage/cli": "^0.22.2-next.0"
+    "@backstage/cli": "^0.22.2"
   },
   "files": [
     "dist",