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

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @backstage/backend-plugin-api
 
+## 0.4.0-next.2
+
+### Minor Changes
+
+- e716946103: **BREAKING**: Split out the hook for both lifecycle services so that the first parameter of `addShutdownHook` is the hook function, and the second is the options.
+- 0ff03319be: **BREAKING**: The plugin ID option passed to `createBackendPlugin` is now `pluginId`, rather than just `id`. This is to make it match `createBackendModule` more closely.
+- 71a5ec0f06: **BREAKING**: Switched out `LogMeta` type for `JsonObject`.
+- 610d65e143: Switched `BackendFeature` to be an opaque type.
+
+### Patch Changes
+
+- 9c9456fd33: Removed the unused `TypesToServiceRef` type
+- 181c03edb5: Aligned opaque type markers to all use a `$type` property with namespacing.
+- Updated dependencies
+  - @backstage/backend-tasks@0.4.3-next.2
+  - @backstage/plugin-auth-node@0.2.11-next.2
+  - @backstage/config@1.0.6
+  - @backstage/types@1.0.2
+  - @backstage/plugin-permission-common@0.7.3
+
+## 0.3.2-next.1
+
+### Patch Changes
+
+- ae88f61e00: The `register` methods passed to `createBackendPlugin` and `createBackendModule`
+  now have dedicated `BackendPluginRegistrationPoints` and
+  `BackendModuleRegistrationPoints` arguments, respectively. This lets us make it
+  clear on a type level that it's not possible to pass in extension points as
+  dependencies to plugins (should only ever be done for modules). This has no
+  practical effect on code that was already well behaved.
+- Updated dependencies
+  - @backstage/backend-tasks@0.4.3-next.1
+  - @backstage/config@1.0.6
+  - @backstage/types@1.0.2
+  - @backstage/plugin-auth-node@0.2.11-next.1
+  - @backstage/plugin-permission-common@0.7.3
+
 ## 0.3.2-next.0
 
 ### Patch Changes

package/alpha/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/backend-plugin-api",
-  "version": "0.3.2-next.0",
+  "version": "0.4.0-next.2",
   "main": "../dist/index.cjs.js",
   "types": "../dist/index.alpha.d.ts"
 }

package/dist/index.alpha.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,31 +18,75 @@ import { Readable } from 'stream';
 
 /** @public */
 export declare interface BackendFeature {
-    id: string;
-    register(reg: BackendRegistrationPoints): void;
+    $$type: '@backstage/BackendFeature';
 }
 
-/** @public */
+/**
+ * The configuration options passed to {@link createBackendModule}.
+ *
+ * @public
+ * @see {@link https://backstage.io/docs/backend-system/architecture/modules | The architecture of modules}
+ * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
+ */
 export declare interface BackendModuleConfig {
+    /**
+     * The ID of this plugin.
+     *
+     * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
+     */
     pluginId: string;
+    /**
+     * Should exactly match the `id` of the plugin that the module extends.
+     */
     moduleId: string;
-    register(reg: Omit<BackendRegistrationPoints, 'registerExtensionPoint'>): void;
+    register(reg: BackendModuleRegistrationPoints): void;
 }
 
-/** @public */
+/**
+ * The callbacks passed to the `register` method of a backend module.
+ *
+ * @public
+ */
+export declare interface BackendModuleRegistrationPoints {
+    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;
+}
+
+/**
+ * The configuration options passed to {@link createBackendPlugin}.
+ *
+ * @public
+ * @see {@link https://backstage.io/docs/backend-system/architecture/plugins | The architecture of plugins}
+ * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
+ */
 export declare interface BackendPluginConfig {
-    id: string;
-    register(reg: BackendRegistrationPoints): void;
+    /**
+     * The ID of this plugin.
+     *
+     * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
+     */
+    pluginId: string;
+    register(reg: BackendPluginRegistrationPoints): void;
 }
 
-/** @public */
-export declare interface BackendRegistrationPoints {
+/**
+ * The callbacks passed to the `register` method of a backend plugin.
+ *
+ * @public
+ */
+export declare interface BackendPluginRegistrationPoints {
     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]>;
+            [name in keyof Deps]: ServiceRef<Deps[name]>;
         };
         init(deps: Deps): Promise<void>;
     }): void;
@@ -230,22 +275,26 @@ export declare namespace coreServices {
  * Creates a new backend module for a given plugin.
  *
  * @public
- *
- * @remarks
- *
- * The `moduleId` should be equal to the module-specific suffix of the exported name, such
- * that the full name is `pluginId + "Module" + ModuleId`. For example, a GitHub entity
- * provider module for the `catalog` plugin might have the module ID `'githubEntityProvider'`,
- * and the full exported name would be `catalogModuleGithubEntityProvider`.
- *
- * The `pluginId` should exactly match the `id` of the plugin that the module extends.
+ * @see {@link https://backstage.io/docs/backend-system/architecture/modules | The architecture of modules}
+ * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
  */
 export declare function createBackendModule<TOptions extends [options?: object] = []>(config: BackendModuleConfig | ((...params: TOptions) => BackendModuleConfig)): (...params: TOptions) => BackendFeature;
 
-/** @public */
+/**
+ * Creates a new backend plugin.
+ *
+ * @public
+ * @see {@link https://backstage.io/docs/backend-system/architecture/plugins | The architecture of plugins}
+ * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
+ */
 export declare function createBackendPlugin<TOptions extends [options?: object] = []>(config: BackendPluginConfig | ((...params: TOptions) => BackendPluginConfig)): (...params: TOptions) => BackendFeature;
 
-/** @public */
+/**
+ * Creates a new backend extension point.
+ *
+ * @public
+ * @see {@link https://backstage.io/docs/backend-system/architecture/extension-points | The architecture of extension points}
+ */
 export declare function createExtensionPoint<T>(config: ExtensionPointConfig): ExtensionPoint<T>;
 
 /**
@@ -323,7 +372,9 @@ export declare function createServiceRef<TService>(config: ServiceRefConfig<TSer
 export declare function createServiceRef<TService>(config: ServiceRefConfig<TService, 'root'>): ServiceRef<TService, 'root'>;
 
 /**
- * Creates a shared backend environment which can be used to create multiple backends
+ * Creates a shared backend environment which can be used to create multiple
+ * backends.
+ *
  * @public
  */
 export declare function createSharedEnvironment<TOptions extends [options?: object] = []>(config: SharedBackendEnvironmentConfig | ((...params: TOptions) => SharedBackendEnvironmentConfig)): (...options: TOptions) => SharedBackendEnvironment;
@@ -414,11 +465,22 @@ export declare type ExtensionPoint<T> = {
      */
     T: T;
     toString(): string;
-    $$ref: 'extension-point';
+    $$type: '@backstage/ExtensionPoint';
 };
 
-/** @public */
+/**
+ * The configuration options passed to {@link createExtensionPoint}.
+ *
+ * @public
+ * @see {@link https://backstage.io/docs/backend-system/architecture/extension-points | The architecture of extension points}
+ * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
+ */
 export declare interface ExtensionPointConfig {
+    /**
+     * The ID of this extension point.
+     *
+     * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
+     */
     id: string;
 }
 
@@ -435,24 +497,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.
@@ -460,20 +526,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 {
 }
@@ -814,7 +873,7 @@ export declare type ServiceRef<TService, TScope extends 'root' | 'plugin' = 'roo
      */
     T: TService;
     toString(): string;
-    $$ref: 'service';
+    $$type: '@backstage/ServiceRef';
 };
 
 /** @public */
@@ -832,13 +891,19 @@ declare type ServiceRefsToInstances<T extends {
 };
 
 /**
+ * An opaque type that represents the contents of a shared backend environment.
+ *
  * @public
  */
 export declare interface SharedBackendEnvironment {
-    $$type: 'SharedBackendEnvironment';
+    $$type: '@backstage/SharedBackendEnvironment';
 }
 
-/** @public */
+/**
+ * The configuration options passed to {@link createSharedEnvironment}.
+ *
+ * @public
+ */
 export declare interface SharedBackendEnvironmentConfig {
     services?: ServiceFactoryOrFunction[];
 }
@@ -868,11 +933,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/dist/index.beta.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,31 +18,75 @@ import { Readable } from 'stream';
 
 /** @public */
 export declare interface BackendFeature {
-    id: string;
-    register(reg: BackendRegistrationPoints): void;
+    $$type: '@backstage/BackendFeature';
 }
 
-/** @public */
+/**
+ * The configuration options passed to {@link createBackendModule}.
+ *
+ * @public
+ * @see {@link https://backstage.io/docs/backend-system/architecture/modules | The architecture of modules}
+ * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
+ */
 export declare interface BackendModuleConfig {
+    /**
+     * The ID of this plugin.
+     *
+     * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
+     */
     pluginId: string;
+    /**
+     * Should exactly match the `id` of the plugin that the module extends.
+     */
     moduleId: string;
-    register(reg: Omit<BackendRegistrationPoints, 'registerExtensionPoint'>): void;
+    register(reg: BackendModuleRegistrationPoints): void;
 }
 
-/** @public */
+/**
+ * The callbacks passed to the `register` method of a backend module.
+ *
+ * @public
+ */
+export declare interface BackendModuleRegistrationPoints {
+    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;
+}
+
+/**
+ * The configuration options passed to {@link createBackendPlugin}.
+ *
+ * @public
+ * @see {@link https://backstage.io/docs/backend-system/architecture/plugins | The architecture of plugins}
+ * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
+ */
 export declare interface BackendPluginConfig {
-    id: string;
-    register(reg: BackendRegistrationPoints): void;
+    /**
+     * The ID of this plugin.
+     *
+     * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
+     */
+    pluginId: string;
+    register(reg: BackendPluginRegistrationPoints): void;
 }
 
-/** @public */
-export declare interface BackendRegistrationPoints {
+/**
+ * The callbacks passed to the `register` method of a backend plugin.
+ *
+ * @public
+ */
+export declare interface BackendPluginRegistrationPoints {
     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]>;
+            [name in keyof Deps]: ServiceRef<Deps[name]>;
         };
         init(deps: Deps): Promise<void>;
     }): void;
@@ -230,22 +275,26 @@ export declare namespace coreServices {
  * Creates a new backend module for a given plugin.
  *
  * @public
- *
- * @remarks
- *
- * The `moduleId` should be equal to the module-specific suffix of the exported name, such
- * that the full name is `pluginId + "Module" + ModuleId`. For example, a GitHub entity
- * provider module for the `catalog` plugin might have the module ID `'githubEntityProvider'`,
- * and the full exported name would be `catalogModuleGithubEntityProvider`.
- *
- * The `pluginId` should exactly match the `id` of the plugin that the module extends.
+ * @see {@link https://backstage.io/docs/backend-system/architecture/modules | The architecture of modules}
+ * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
  */
 export declare function createBackendModule<TOptions extends [options?: object] = []>(config: BackendModuleConfig | ((...params: TOptions) => BackendModuleConfig)): (...params: TOptions) => BackendFeature;
 
-/** @public */
+/**
+ * Creates a new backend plugin.
+ *
+ * @public
+ * @see {@link https://backstage.io/docs/backend-system/architecture/plugins | The architecture of plugins}
+ * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
+ */
 export declare function createBackendPlugin<TOptions extends [options?: object] = []>(config: BackendPluginConfig | ((...params: TOptions) => BackendPluginConfig)): (...params: TOptions) => BackendFeature;
 
-/** @public */
+/**
+ * Creates a new backend extension point.
+ *
+ * @public
+ * @see {@link https://backstage.io/docs/backend-system/architecture/extension-points | The architecture of extension points}
+ */
 export declare function createExtensionPoint<T>(config: ExtensionPointConfig): ExtensionPoint<T>;
 
 /**
@@ -323,7 +372,9 @@ export declare function createServiceRef<TService>(config: ServiceRefConfig<TSer
 export declare function createServiceRef<TService>(config: ServiceRefConfig<TService, 'root'>): ServiceRef<TService, 'root'>;
 
 /**
- * Creates a shared backend environment which can be used to create multiple backends
+ * Creates a shared backend environment which can be used to create multiple
+ * backends.
+ *
  * @public
  */
 export declare function createSharedEnvironment<TOptions extends [options?: object] = []>(config: SharedBackendEnvironmentConfig | ((...params: TOptions) => SharedBackendEnvironmentConfig)): (...options: TOptions) => SharedBackendEnvironment;
@@ -414,11 +465,22 @@ export declare type ExtensionPoint<T> = {
      */
     T: T;
     toString(): string;
-    $$ref: 'extension-point';
+    $$type: '@backstage/ExtensionPoint';
 };
 
-/** @public */
+/**
+ * The configuration options passed to {@link createExtensionPoint}.
+ *
+ * @public
+ * @see {@link https://backstage.io/docs/backend-system/architecture/extension-points | The architecture of extension points}
+ * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
+ */
 export declare interface ExtensionPointConfig {
+    /**
+     * The ID of this extension point.
+     *
+     * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
+     */
     id: string;
 }
 
@@ -435,24 +497,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.
@@ -460,20 +526,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 {
 }
@@ -814,7 +873,7 @@ export declare type ServiceRef<TService, TScope extends 'root' | 'plugin' = 'roo
      */
     T: TService;
     toString(): string;
-    $$ref: 'service';
+    $$type: '@backstage/ServiceRef';
 };
 
 /** @public */
@@ -832,13 +891,19 @@ declare type ServiceRefsToInstances<T extends {
 };
 
 /**
+ * An opaque type that represents the contents of a shared backend environment.
+ *
  * @public
  */
 export declare interface SharedBackendEnvironment {
-    $$type: 'SharedBackendEnvironment';
+    $$type: '@backstage/SharedBackendEnvironment';
 }
 
-/** @public */
+/**
+ * The configuration options passed to {@link createSharedEnvironment}.
+ *
+ * @public
+ */
 export declare interface SharedBackendEnvironmentConfig {
     services?: ServiceFactoryOrFunction[];
 }
@@ -868,11 +933,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/dist/index.cjs.js

@@ -13,8 +13,7 @@ function createServiceRef(config) {
     toString() {
       return `serviceRef{${config.id}}`;
     },
-    $$ref: "service",
-    // TODO: declare
+    $$type: "@backstage/ServiceRef",
     __defaultFactory: defaultFactory
   };
 }
@@ -82,7 +81,7 @@ function createSharedEnvironment(config) {
       );
     }
     const env = {
-      $$type: "SharedBackendEnvironment",
+      $$type: "@backstage/SharedBackendEnvironment",
       version: "v1",
       services
     };
@@ -99,32 +98,101 @@ function createExtensionPoint(config) {
     toString() {
       return `extensionPoint{${config.id}}`;
     },
-    $$ref: "extension-point"
-    // TODO: declare
+    $$type: "@backstage/ExtensionPoint"
   };
 }
 function createBackendPlugin(config) {
-  if (typeof config === "function") {
-    return config;
-  }
-  return () => config;
+  const configCallback = typeof config === "function" ? config : () => config;
+  return (...options) => {
+    const c = configCallback(...options);
+    let registrations;
+    return {
+      $$type: "@backstage/BackendFeature",
+      version: "v1",
+      getRegistrations() {
+        if (registrations) {
+          return registrations;
+        }
+        const extensionPoints = [];
+        let init = void 0;
+        c.register({
+          registerExtensionPoint(ext, impl) {
+            if (init) {
+              throw new Error(
+                "registerExtensionPoint called after registerInit"
+              );
+            }
+            extensionPoints.push([ext, impl]);
+          },
+          registerInit(regInit) {
+            if (init) {
+              throw new Error("registerInit must only be called once");
+            }
+            init = {
+              deps: regInit.deps,
+              func: regInit.init
+            };
+          }
+        });
+        if (!init) {
+          throw new Error(
+            `registerInit was not called by register in ${c.pluginId}`
+          );
+        }
+        registrations = [
+          {
+            type: "plugin",
+            pluginId: c.pluginId,
+            extensionPoints,
+            init
+          }
+        ];
+        return registrations;
+      }
+    };
+  };
 }
 function createBackendModule(config) {
-  if (typeof config === "function") {
-    return (...options) => {
-      const c = config(...options);
-      return {
-        id: `${c.pluginId}.${c.moduleId}`,
-        register: c.register
-      };
+  const configCallback = typeof config === "function" ? config : () => config;
+  return (...options) => {
+    const c = configCallback(...options);
+    let registrations;
+    return {
+      $$type: "@backstage/BackendFeature",
+      version: "v1",
+      getRegistrations() {
+        if (registrations) {
+          return registrations;
+        }
+        let init = void 0;
+        c.register({
+          registerInit(regInit) {
+            if (init) {
+              throw new Error("registerInit must only be called once");
+            }
+            init = {
+              deps: regInit.deps,
+              func: regInit.init
+            };
+          }
+        });
+        if (!init) {
+          throw new Error(
+            `registerInit was not called by register in ${c.moduleId} module for ${c.pluginId}`
+          );
+        }
+        registrations = [
+          {
+            type: "module",
+            pluginId: c.pluginId,
+            moduleId: c.moduleId,
+            init
+          }
+        ];
+        return registrations;
+      }
     };
-  }
-  return () => ({
-    id: `${config.pluginId}.${config.moduleId}`,
-    register(register) {
-      return config.register(register);
-    }
-  });
+  };
 }
 
 exports.createBackendModule = createBackendModule;

package/dist/index.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs.js","sources":["../src/services/system/types.ts","../src/services/definitions/coreServices.ts","../src/wiring/createSharedEnvironment.ts","../src/wiring/factories.ts"],"sourcesContent":["/*\n * Copyright 2022 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * TODO\n *\n * @public\n */\nexport type ServiceRef<\n  TService,\n  TScope extends 'root' | 'plugin' = 'root' | 'plugin',\n> = {\n  id: string;\n\n  /**\n   * This determines the scope at which this service is available.\n   *\n   * Root scoped services are available to all other services but\n   * may only depend on other root scoped services.\n   *\n   * Plugin scoped services are only available to other plugin scoped\n   * services but may depend on all other services.\n   */\n  scope: TScope;\n\n  /**\n   * Utility for getting the type of the service, using `typeof serviceRef.T`.\n   * Attempting to actually read this value will result in an exception.\n   */\n  T: TService;\n\n  toString(): string;\n\n  $$ref: 'service';\n};\n\n/** @public */\nexport type TypesToServiceRef<T> = { [key in keyof T]: ServiceRef<T[key]> };\n\n/** @public */\nexport type ServiceFactory<TService = unknown> =\n  | {\n      // This scope prop is needed in addition to the service ref, as TypeScript\n      // can't properly discriminate the two factory types otherwise.\n      scope: 'root';\n      service: ServiceRef<TService, 'root'>;\n      deps: { [key in string]: ServiceRef<unknown> };\n      factory(deps: { [key in string]: unknown }): Promise<TService>;\n    }\n  | {\n      scope: 'plugin';\n      service: ServiceRef<TService, 'plugin'>;\n      deps: { [key in string]: ServiceRef<unknown> };\n      createRootContext?(deps: { [key in string]: unknown }): Promise<unknown>;\n      factory(\n        deps: { [key in string]: unknown },\n        context: unknown,\n      ): Promise<TService>;\n    };\n\n/**\n * Represents either a {@link ServiceFactory} or a function that returns one.\n *\n * @public\n */\nexport type ServiceFactoryOrFunction<TService = unknown> =\n  | ServiceFactory<TService>\n  | (() => ServiceFactory<TService>);\n\n/** @public */\nexport interface ServiceRefConfig<TService, TScope extends 'root' | 'plugin'> {\n  id: string;\n  scope?: TScope;\n  defaultFactory?: (\n    service: ServiceRef<TService, TScope>,\n  ) => Promise<ServiceFactoryOrFunction<TService>>;\n}\n\n/**\n * Creates a new service definition. This overload is used to create plugin scoped services.\n *\n * @public\n */\nexport function createServiceRef<TService>(\n  config: ServiceRefConfig<TService, 'plugin'>,\n): ServiceRef<TService, 'plugin'>;\n\n/**\n * Creates a new service definition. This overload is used to create root scoped services.\n *\n * @public\n */\nexport function createServiceRef<TService>(\n  config: ServiceRefConfig<TService, 'root'>,\n): ServiceRef<TService, 'root'>;\nexport function createServiceRef<TService>(\n  config: ServiceRefConfig<TService, any>,\n): ServiceRef<TService, any> {\n  const { id, scope = 'plugin', defaultFactory } = config;\n  return {\n    id,\n    scope,\n    get T(): TService {\n      throw new Error(`tried to read ServiceRef.T of ${this}`);\n    },\n    toString() {\n      return `serviceRef{${config.id}}`;\n    },\n    $$ref: 'service', // TODO: declare\n    __defaultFactory: defaultFactory,\n  } as ServiceRef<TService, typeof scope> & {\n    __defaultFactory?: (\n      service: ServiceRef<TService>,\n    ) => Promise<ServiceFactory<TService> | (() => ServiceFactory<TService>)>;\n  };\n}\n\n/** @ignore */\ntype ServiceRefsToInstances<\n  T extends { [key in string]: ServiceRef<unknown> },\n  TScope extends 'root' | 'plugin' = 'root' | 'plugin',\n> = {\n  [key in keyof T as T[key]['scope'] extends TScope ? key : never]: T[key]['T'];\n};\n\n/** @public */\nexport interface RootServiceFactoryConfig<\n  TService,\n  TImpl extends TService,\n  TDeps extends { [name in string]: ServiceRef<unknown> },\n> {\n  service: ServiceRef<TService, 'root'>;\n  deps: TDeps;\n  factory(deps: ServiceRefsToInstances<TDeps, 'root'>): TImpl | Promise<TImpl>;\n}\n\n/** @public */\nexport interface PluginServiceFactoryConfig<\n  TService,\n  TContext,\n  TImpl extends TService,\n  TDeps extends { [name in string]: ServiceRef<unknown> },\n> {\n  service: ServiceRef<TService, 'plugin'>;\n  deps: TDeps;\n  createRootContext?(\n    deps: ServiceRefsToInstances<TDeps, 'root'>,\n  ): TContext | Promise<TContext>;\n  factory(\n    deps: ServiceRefsToInstances<TDeps>,\n    context: TContext,\n  ): TImpl | Promise<TImpl>;\n}\n\n/**\n * Creates a root scoped service factory without options.\n *\n * @public\n * @param config - The service factory configuration.\n */\nexport function createServiceFactory<\n  TService,\n  TImpl extends TService,\n  TDeps extends { [name in string]: ServiceRef<unknown> },\n  TOpts extends object | undefined = undefined,\n>(\n  config: RootServiceFactoryConfig<TService, TImpl, TDeps>,\n): () => ServiceFactory<TService>;\n/**\n * Creates a root scoped service factory with optional options.\n *\n * @public\n * @param config - The service factory configuration.\n */\nexport function createServiceFactory<\n  TService,\n  TImpl extends TService,\n  TDeps extends { [name in string]: ServiceRef<unknown> },\n  TOpts extends object | undefined = undefined,\n>(\n  config: (options?: TOpts) => RootServiceFactoryConfig<TService, TImpl, TDeps>,\n): (options?: TOpts) => ServiceFactory<TService>;\n/**\n * Creates a root scoped service factory with required options.\n *\n * @public\n * @param config - The service factory configuration.\n */\nexport function createServiceFactory<\n  TService,\n  TImpl extends TService,\n  TDeps extends { [name in string]: ServiceRef<unknown> },\n  TOpts extends object | undefined = undefined,\n>(\n  config: (options: TOpts) => RootServiceFactoryConfig<TService, TImpl, TDeps>,\n): (options: TOpts) => ServiceFactory<TService>;\n/**\n * Creates a plugin scoped service factory without options.\n *\n * @public\n * @param config - The service factory configuration.\n */\nexport function createServiceFactory<\n  TService,\n  TImpl extends TService,\n  TDeps extends { [name in string]: ServiceRef<unknown> },\n  TContext = undefined,\n  TOpts extends object | undefined = undefined,\n>(\n  config: PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>,\n): () => ServiceFactory<TService>;\n/**\n * Creates a plugin scoped service factory with optional options.\n *\n * @public\n * @param config - The service factory configuration.\n */\nexport function createServiceFactory<\n  TService,\n  TImpl extends TService,\n  TDeps extends { [name in string]: ServiceRef<unknown> },\n  TContext = undefined,\n  TOpts extends object | undefined = undefined,\n>(\n  config: (\n    options?: TOpts,\n  ) => PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>,\n): (options?: TOpts) => ServiceFactory<TService>;\n/**\n * Creates a plugin scoped service factory with required options.\n *\n * @public\n * @param config - The service factory configuration.\n */\nexport function createServiceFactory<\n  TService,\n  TImpl extends TService,\n  TDeps extends { [name in string]: ServiceRef<unknown> },\n  TContext = undefined,\n  TOpts extends object | undefined = undefined,\n>(\n  config:\n    | PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>\n    | ((\n        options: TOpts,\n      ) => PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>),\n): (options: TOpts) => ServiceFactory<TService>;\nexport function createServiceFactory<\n  TService,\n  TImpl extends TService,\n  TDeps extends { [name in string]: ServiceRef<unknown> },\n  TContext,\n  TOpts extends object | undefined = undefined,\n>(\n  config:\n    | RootServiceFactoryConfig<TService, TImpl, TDeps>\n    | PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>\n    | ((options: TOpts) => RootServiceFactoryConfig<TService, TImpl, TDeps>)\n    | ((\n        options: TOpts,\n      ) => PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>)\n    | (() => RootServiceFactoryConfig<TService, TImpl, TDeps>)\n    | (() => PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>),\n): (options: TOpts) => ServiceFactory<TService> {\n  const configCallback = typeof config === 'function' ? config : () => config;\n  return (options: TOpts) => {\n    const c = configCallback(options);\n    return {\n      ...c,\n      ...('createRootContext' in c\n        ? {\n            createRootContext: async (deps: TDeps) =>\n              c?.createRootContext?.(deps),\n          }\n        : {}),\n      factory: async (deps: TDeps, ctx: TContext) => c.factory(deps, ctx),\n      scope: c.service.scope,\n    } as ServiceFactory<TService>;\n  };\n}\n","/*\n * Copyright 2022 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { createServiceRef } from '../system';\n\n/**\n * All core services references\n *\n * @public\n */\nexport namespace coreServices {\n  /**\n   * The service reference for the plugin scoped {@link CacheService}.\n   *\n   * @public\n   */\n  export const cache = createServiceRef<import('./CacheService').CacheService>({\n    id: 'core.cache',\n  });\n\n  /**\n   * The service reference for the root scoped {@link ConfigService}.\n   *\n   * @public\n   */\n  export const config = createServiceRef<\n    import('./ConfigService').ConfigService\n  >({ id: 'core.config', scope: 'root' });\n\n  /**\n   * The service reference for the plugin scoped {@link DatabaseService}.\n   *\n   * @public\n   */\n  export const database = createServiceRef<\n    import('./DatabaseService').DatabaseService\n  >({ id: 'core.database' });\n\n  /**\n   * The service reference for the plugin scoped {@link DiscoveryService}.\n   *\n   * @public\n   */\n  export const discovery = createServiceRef<\n    import('./DiscoveryService').DiscoveryService\n  >({ id: 'core.discovery' });\n\n  /**\n   * The service reference for the plugin scoped {@link HttpRouterService}.\n   *\n   * @public\n   */\n  export const httpRouter = createServiceRef<\n    import('./HttpRouterService').HttpRouterService\n  >({ id: 'core.httpRouter' });\n\n  /**\n   * The service reference for the plugin scoped {@link LifecycleService}.\n   *\n   * @public\n   */\n  export const lifecycle = createServiceRef<\n    import('./LifecycleService').LifecycleService\n  >({ id: 'core.lifecycle' });\n\n  /**\n   * The service reference for the plugin scoped {@link LoggerService}.\n   *\n   * @public\n   */\n  export const logger = createServiceRef<\n    import('./LoggerService').LoggerService\n  >({ id: 'core.logger' });\n\n  /**\n   * The service reference for the plugin scoped {@link PermissionsService}.\n   *\n   * @public\n   */\n  export const permissions = createServiceRef<\n    import('./PermissionsService').PermissionsService\n  >({ id: 'core.permissions' });\n\n  /**\n   * The service reference for the plugin scoped {@link PluginMetadataService}.\n   *\n   * @public\n   */\n  export const pluginMetadata = createServiceRef<\n    import('./PluginMetadataService').PluginMetadataService\n  >({ id: 'core.pluginMetadata' });\n\n  /**\n   * The service reference for the root scoped {@link RootHttpRouterService}.\n   *\n   * @public\n   */\n  export const rootHttpRouter = createServiceRef<\n    import('./RootHttpRouterService').RootHttpRouterService\n  >({ id: 'core.rootHttpRouter', scope: 'root' });\n\n  /**\n   * The service reference for the root scoped {@link RootLifecycleService}.\n   *\n   * @public\n   */\n  export const rootLifecycle = createServiceRef<\n    import('./RootLifecycleService').RootLifecycleService\n  >({ id: 'core.rootLifecycle', scope: 'root' });\n\n  /**\n   * The service reference for the root scoped {@link RootLoggerService}.\n   *\n   * @public\n   */\n  export const rootLogger = createServiceRef<\n    import('./RootLoggerService').RootLoggerService\n  >({ id: 'core.rootLogger', scope: 'root' });\n\n  /**\n   * The service reference for the plugin scoped {@link SchedulerService}.\n   *\n   * @public\n   */\n  export const scheduler = createServiceRef<\n    import('./SchedulerService').SchedulerService\n  >({ id: 'core.scheduler' });\n\n  /**\n   * The service reference for the plugin scoped {@link TokenManagerService}.\n   *\n   * @public\n   */\n  export const tokenManager = createServiceRef<\n    import('./TokenManagerService').TokenManagerService\n  >({ id: 'core.tokenManager' });\n\n  /**\n   * The service reference for the plugin scoped {@link UrlReaderService}.\n   *\n   * @public\n   */\n  export const urlReader = createServiceRef<\n    import('./UrlReaderService').UrlReaderService\n  >({ id: 'core.urlReader' });\n\n  /**\n   * The service reference for the plugin scoped {@link IdentityService}.\n   *\n   * @public\n   */\n  export const identity = createServiceRef<\n    import('./IdentityService').IdentityService\n  >({ id: 'core.identity' });\n}\n","/*\n * Copyright 2023 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { ServiceFactory, ServiceFactoryOrFunction } from '../services';\n\n/** @public */\nexport interface SharedBackendEnvironmentConfig {\n  services?: ServiceFactoryOrFunction[];\n}\n\n// This type is opaque in order to allow for future API evolution without\n// cluttering the external API. For example we might want to add support\n// for more powerful callback based backend modifications.\n//\n// By making this opaque we also ensure that the type doesn't become an input\n// type that we need to care about, as it would otherwise be possible to pass\n// a custom environment definition to `createBackend`, which we don't want.\n/**\n * @public\n */\nexport interface SharedBackendEnvironment {\n  $$type: 'SharedBackendEnvironment';\n}\n\n/**\n * This type is NOT supposed to be used by anyone except internally by the backend-app-api package.\n * @internal */\nexport interface InternalSharedBackendEnvironment {\n  version: 'v1';\n  services?: ServiceFactory[];\n}\n\n/**\n * Creates a shared backend environment which can be used to create multiple backends\n * @public\n */\nexport function createSharedEnvironment<\n  TOptions extends [options?: object] = [],\n>(\n  config:\n    | SharedBackendEnvironmentConfig\n    | ((...params: TOptions) => SharedBackendEnvironmentConfig),\n): (...options: TOptions) => SharedBackendEnvironment {\n  const configCallback = typeof config === 'function' ? config : () => config;\n\n  return (...options) => {\n    const actualConfig = configCallback(...options);\n    const services = actualConfig?.services?.map(sf =>\n      typeof sf === 'function' ? sf() : sf,\n    );\n\n    const exists = new Set<string>();\n    const duplicates = new Set<string>();\n    for (const { service } of services ?? []) {\n      if (exists.has(service.id)) {\n        duplicates.add(service.id);\n      } else {\n        exists.add(service.id);\n      }\n    }\n\n    if (duplicates.size > 0) {\n      const dupStr = [...duplicates].map(id => `'${id}'`).join(', ');\n      throw new Error(\n        `Duplicate service implementations provided in shared environment for ${dupStr}`,\n      );\n    }\n\n    // Here to ensure type safety in this internal implementation.\n    const env: SharedBackendEnvironment & InternalSharedBackendEnvironment = {\n      $$type: 'SharedBackendEnvironment',\n      version: 'v1',\n      services,\n    };\n    return env;\n  };\n}\n","/*\n * Copyright 2022 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  BackendRegistrationPoints,\n  BackendFeature,\n  ExtensionPoint,\n} from './types';\n\n/** @public */\nexport interface ExtensionPointConfig {\n  id: string;\n}\n\n/** @public */\nexport function createExtensionPoint<T>(\n  config: ExtensionPointConfig,\n): ExtensionPoint<T> {\n  return {\n    id: config.id,\n    get T(): T {\n      throw new Error(`tried to read ExtensionPoint.T of ${this}`);\n    },\n    toString() {\n      return `extensionPoint{${config.id}}`;\n    },\n    $$ref: 'extension-point', // TODO: declare\n  };\n}\n\n/** @public */\nexport interface BackendPluginConfig {\n  id: string;\n  register(reg: BackendRegistrationPoints): void;\n}\n\n/** @public */\nexport function createBackendPlugin<TOptions extends [options?: object] = []>(\n  config: BackendPluginConfig | ((...params: TOptions) => BackendPluginConfig),\n): (...params: TOptions) => BackendFeature {\n  if (typeof config === 'function') {\n    return config;\n  }\n\n  return () => config;\n}\n\n/** @public */\nexport interface BackendModuleConfig {\n  pluginId: string;\n  moduleId: string;\n  register(\n    reg: Omit<BackendRegistrationPoints, 'registerExtensionPoint'>,\n  ): void;\n}\n\n/**\n * Creates a new backend module for a given plugin.\n *\n * @public\n *\n * @remarks\n *\n * The `moduleId` should be equal to the module-specific suffix of the exported name, such\n * that the full name is `pluginId + \"Module\" + ModuleId`. For example, a GitHub entity\n * provider module for the `catalog` plugin might have the module ID `'githubEntityProvider'`,\n * and the full exported name would be `catalogModuleGithubEntityProvider`.\n *\n * The `pluginId` should exactly match the `id` of the plugin that the module extends.\n */\nexport function createBackendModule<TOptions extends [options?: object] = []>(\n  config: BackendModuleConfig | ((...params: TOptions) => BackendModuleConfig),\n): (...params: TOptions) => BackendFeature {\n  if (typeof config === 'function') {\n    return (...options: TOptions) => {\n      const c = config(...options);\n      return {\n        id: `${c.pluginId}.${c.moduleId}`,\n        register: c.register,\n      };\n    };\n  }\n  return () => ({\n    id: `${config.pluginId}.${config.moduleId}`,\n    register(register: BackendRegistrationPoints) {\n      // TODO: Hide registerExtensionPoint\n      return config.register(register);\n    },\n  });\n}\n"],"names":["coreServices"],"mappings":"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"}
+{"version":3,"file":"index.cjs.js","sources":["../src/services/system/types.ts","../src/services/definitions/coreServices.ts","../src/wiring/createSharedEnvironment.ts","../src/wiring/factories.ts"],"sourcesContent":["/*\n * Copyright 2022 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * TODO\n *\n * @public\n */\nexport type ServiceRef<\n  TService,\n  TScope extends 'root' | 'plugin' = 'root' | 'plugin',\n> = {\n  id: string;\n\n  /**\n   * This determines the scope at which this service is available.\n   *\n   * Root scoped services are available to all other services but\n   * may only depend on other root scoped services.\n   *\n   * Plugin scoped services are only available to other plugin scoped\n   * services but may depend on all other services.\n   */\n  scope: TScope;\n\n  /**\n   * Utility for getting the type of the service, using `typeof serviceRef.T`.\n   * Attempting to actually read this value will result in an exception.\n   */\n  T: TService;\n\n  toString(): string;\n\n  $$type: '@backstage/ServiceRef';\n};\n\n/** @public */\nexport type ServiceFactory<TService = unknown> =\n  | {\n      // This scope prop is needed in addition to the service ref, as TypeScript\n      // can't properly discriminate the two factory types otherwise.\n      scope: 'root';\n      service: ServiceRef<TService, 'root'>;\n      deps: { [key in string]: ServiceRef<unknown> };\n      factory(deps: { [key in string]: unknown }): Promise<TService>;\n    }\n  | {\n      scope: 'plugin';\n      service: ServiceRef<TService, 'plugin'>;\n      deps: { [key in string]: ServiceRef<unknown> };\n      createRootContext?(deps: { [key in string]: unknown }): Promise<unknown>;\n      factory(\n        deps: { [key in string]: unknown },\n        context: unknown,\n      ): Promise<TService>;\n    };\n\n/**\n * Represents either a {@link ServiceFactory} or a function that returns one.\n *\n * @public\n */\nexport type ServiceFactoryOrFunction<TService = unknown> =\n  | ServiceFactory<TService>\n  | (() => ServiceFactory<TService>);\n\n/** @public */\nexport interface ServiceRefConfig<TService, TScope extends 'root' | 'plugin'> {\n  id: string;\n  scope?: TScope;\n  defaultFactory?: (\n    service: ServiceRef<TService, TScope>,\n  ) => Promise<ServiceFactoryOrFunction<TService>>;\n}\n\n/**\n * Creates a new service definition. This overload is used to create plugin scoped services.\n *\n * @public\n */\nexport function createServiceRef<TService>(\n  config: ServiceRefConfig<TService, 'plugin'>,\n): ServiceRef<TService, 'plugin'>;\n\n/**\n * Creates a new service definition. This overload is used to create root scoped services.\n *\n * @public\n */\nexport function createServiceRef<TService>(\n  config: ServiceRefConfig<TService, 'root'>,\n): ServiceRef<TService, 'root'>;\nexport function createServiceRef<TService>(\n  config: ServiceRefConfig<TService, any>,\n): ServiceRef<TService, any> {\n  const { id, scope = 'plugin', defaultFactory } = config;\n  return {\n    id,\n    scope,\n    get T(): TService {\n      throw new Error(`tried to read ServiceRef.T of ${this}`);\n    },\n    toString() {\n      return `serviceRef{${config.id}}`;\n    },\n    $$type: '@backstage/ServiceRef',\n    __defaultFactory: defaultFactory,\n  } as ServiceRef<TService, typeof scope> & {\n    __defaultFactory?: (\n      service: ServiceRef<TService>,\n    ) => Promise<ServiceFactory<TService> | (() => ServiceFactory<TService>)>;\n  };\n}\n\n/** @ignore */\ntype ServiceRefsToInstances<\n  T extends { [key in string]: ServiceRef<unknown> },\n  TScope extends 'root' | 'plugin' = 'root' | 'plugin',\n> = {\n  [key in keyof T as T[key]['scope'] extends TScope ? key : never]: T[key]['T'];\n};\n\n/** @public */\nexport interface RootServiceFactoryConfig<\n  TService,\n  TImpl extends TService,\n  TDeps extends { [name in string]: ServiceRef<unknown> },\n> {\n  service: ServiceRef<TService, 'root'>;\n  deps: TDeps;\n  factory(deps: ServiceRefsToInstances<TDeps, 'root'>): TImpl | Promise<TImpl>;\n}\n\n/** @public */\nexport interface PluginServiceFactoryConfig<\n  TService,\n  TContext,\n  TImpl extends TService,\n  TDeps extends { [name in string]: ServiceRef<unknown> },\n> {\n  service: ServiceRef<TService, 'plugin'>;\n  deps: TDeps;\n  createRootContext?(\n    deps: ServiceRefsToInstances<TDeps, 'root'>,\n  ): TContext | Promise<TContext>;\n  factory(\n    deps: ServiceRefsToInstances<TDeps>,\n    context: TContext,\n  ): TImpl | Promise<TImpl>;\n}\n\n/**\n * Creates a root scoped service factory without options.\n *\n * @public\n * @param config - The service factory configuration.\n */\nexport function createServiceFactory<\n  TService,\n  TImpl extends TService,\n  TDeps extends { [name in string]: ServiceRef<unknown> },\n  TOpts extends object | undefined = undefined,\n>(\n  config: RootServiceFactoryConfig<TService, TImpl, TDeps>,\n): () => ServiceFactory<TService>;\n/**\n * Creates a root scoped service factory with optional options.\n *\n * @public\n * @param config - The service factory configuration.\n */\nexport function createServiceFactory<\n  TService,\n  TImpl extends TService,\n  TDeps extends { [name in string]: ServiceRef<unknown> },\n  TOpts extends object | undefined = undefined,\n>(\n  config: (options?: TOpts) => RootServiceFactoryConfig<TService, TImpl, TDeps>,\n): (options?: TOpts) => ServiceFactory<TService>;\n/**\n * Creates a root scoped service factory with required options.\n *\n * @public\n * @param config - The service factory configuration.\n */\nexport function createServiceFactory<\n  TService,\n  TImpl extends TService,\n  TDeps extends { [name in string]: ServiceRef<unknown> },\n  TOpts extends object | undefined = undefined,\n>(\n  config: (options: TOpts) => RootServiceFactoryConfig<TService, TImpl, TDeps>,\n): (options: TOpts) => ServiceFactory<TService>;\n/**\n * Creates a plugin scoped service factory without options.\n *\n * @public\n * @param config - The service factory configuration.\n */\nexport function createServiceFactory<\n  TService,\n  TImpl extends TService,\n  TDeps extends { [name in string]: ServiceRef<unknown> },\n  TContext = undefined,\n  TOpts extends object | undefined = undefined,\n>(\n  config: PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>,\n): () => ServiceFactory<TService>;\n/**\n * Creates a plugin scoped service factory with optional options.\n *\n * @public\n * @param config - The service factory configuration.\n */\nexport function createServiceFactory<\n  TService,\n  TImpl extends TService,\n  TDeps extends { [name in string]: ServiceRef<unknown> },\n  TContext = undefined,\n  TOpts extends object | undefined = undefined,\n>(\n  config: (\n    options?: TOpts,\n  ) => PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>,\n): (options?: TOpts) => ServiceFactory<TService>;\n/**\n * Creates a plugin scoped service factory with required options.\n *\n * @public\n * @param config - The service factory configuration.\n */\nexport function createServiceFactory<\n  TService,\n  TImpl extends TService,\n  TDeps extends { [name in string]: ServiceRef<unknown> },\n  TContext = undefined,\n  TOpts extends object | undefined = undefined,\n>(\n  config:\n    | PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>\n    | ((\n        options: TOpts,\n      ) => PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>),\n): (options: TOpts) => ServiceFactory<TService>;\nexport function createServiceFactory<\n  TService,\n  TImpl extends TService,\n  TDeps extends { [name in string]: ServiceRef<unknown> },\n  TContext,\n  TOpts extends object | undefined = undefined,\n>(\n  config:\n    | RootServiceFactoryConfig<TService, TImpl, TDeps>\n    | PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>\n    | ((options: TOpts) => RootServiceFactoryConfig<TService, TImpl, TDeps>)\n    | ((\n        options: TOpts,\n      ) => PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>)\n    | (() => RootServiceFactoryConfig<TService, TImpl, TDeps>)\n    | (() => PluginServiceFactoryConfig<TService, TContext, TImpl, TDeps>),\n): (options: TOpts) => ServiceFactory<TService> {\n  const configCallback = typeof config === 'function' ? config : () => config;\n  return (options: TOpts) => {\n    const c = configCallback(options);\n    return {\n      ...c,\n      ...('createRootContext' in c\n        ? {\n            createRootContext: async (deps: TDeps) =>\n              c?.createRootContext?.(deps),\n          }\n        : {}),\n      factory: async (deps: TDeps, ctx: TContext) => c.factory(deps, ctx),\n      scope: c.service.scope,\n    } as ServiceFactory<TService>;\n  };\n}\n","/*\n * Copyright 2022 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { createServiceRef } from '../system';\n\n/**\n * All core services references\n *\n * @public\n */\nexport namespace coreServices {\n  /**\n   * The service reference for the plugin scoped {@link CacheService}.\n   *\n   * @public\n   */\n  export const cache = createServiceRef<import('./CacheService').CacheService>({\n    id: 'core.cache',\n  });\n\n  /**\n   * The service reference for the root scoped {@link ConfigService}.\n   *\n   * @public\n   */\n  export const config = createServiceRef<\n    import('./ConfigService').ConfigService\n  >({ id: 'core.config', scope: 'root' });\n\n  /**\n   * The service reference for the plugin scoped {@link DatabaseService}.\n   *\n   * @public\n   */\n  export const database = createServiceRef<\n    import('./DatabaseService').DatabaseService\n  >({ id: 'core.database' });\n\n  /**\n   * The service reference for the plugin scoped {@link DiscoveryService}.\n   *\n   * @public\n   */\n  export const discovery = createServiceRef<\n    import('./DiscoveryService').DiscoveryService\n  >({ id: 'core.discovery' });\n\n  /**\n   * The service reference for the plugin scoped {@link HttpRouterService}.\n   *\n   * @public\n   */\n  export const httpRouter = createServiceRef<\n    import('./HttpRouterService').HttpRouterService\n  >({ id: 'core.httpRouter' });\n\n  /**\n   * The service reference for the plugin scoped {@link LifecycleService}.\n   *\n   * @public\n   */\n  export const lifecycle = createServiceRef<\n    import('./LifecycleService').LifecycleService\n  >({ id: 'core.lifecycle' });\n\n  /**\n   * The service reference for the plugin scoped {@link LoggerService}.\n   *\n   * @public\n   */\n  export const logger = createServiceRef<\n    import('./LoggerService').LoggerService\n  >({ id: 'core.logger' });\n\n  /**\n   * The service reference for the plugin scoped {@link PermissionsService}.\n   *\n   * @public\n   */\n  export const permissions = createServiceRef<\n    import('./PermissionsService').PermissionsService\n  >({ id: 'core.permissions' });\n\n  /**\n   * The service reference for the plugin scoped {@link PluginMetadataService}.\n   *\n   * @public\n   */\n  export const pluginMetadata = createServiceRef<\n    import('./PluginMetadataService').PluginMetadataService\n  >({ id: 'core.pluginMetadata' });\n\n  /**\n   * The service reference for the root scoped {@link RootHttpRouterService}.\n   *\n   * @public\n   */\n  export const rootHttpRouter = createServiceRef<\n    import('./RootHttpRouterService').RootHttpRouterService\n  >({ id: 'core.rootHttpRouter', scope: 'root' });\n\n  /**\n   * The service reference for the root scoped {@link RootLifecycleService}.\n   *\n   * @public\n   */\n  export const rootLifecycle = createServiceRef<\n    import('./RootLifecycleService').RootLifecycleService\n  >({ id: 'core.rootLifecycle', scope: 'root' });\n\n  /**\n   * The service reference for the root scoped {@link RootLoggerService}.\n   *\n   * @public\n   */\n  export const rootLogger = createServiceRef<\n    import('./RootLoggerService').RootLoggerService\n  >({ id: 'core.rootLogger', scope: 'root' });\n\n  /**\n   * The service reference for the plugin scoped {@link SchedulerService}.\n   *\n   * @public\n   */\n  export const scheduler = createServiceRef<\n    import('./SchedulerService').SchedulerService\n  >({ id: 'core.scheduler' });\n\n  /**\n   * The service reference for the plugin scoped {@link TokenManagerService}.\n   *\n   * @public\n   */\n  export const tokenManager = createServiceRef<\n    import('./TokenManagerService').TokenManagerService\n  >({ id: 'core.tokenManager' });\n\n  /**\n   * The service reference for the plugin scoped {@link UrlReaderService}.\n   *\n   * @public\n   */\n  export const urlReader = createServiceRef<\n    import('./UrlReaderService').UrlReaderService\n  >({ id: 'core.urlReader' });\n\n  /**\n   * The service reference for the plugin scoped {@link IdentityService}.\n   *\n   * @public\n   */\n  export const identity = createServiceRef<\n    import('./IdentityService').IdentityService\n  >({ id: 'core.identity' });\n}\n","/*\n * Copyright 2023 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { ServiceFactory, ServiceFactoryOrFunction } from '../services';\n\n/**\n * The configuration options passed to {@link createSharedEnvironment}.\n *\n * @public\n */\nexport interface SharedBackendEnvironmentConfig {\n  services?: ServiceFactoryOrFunction[];\n}\n\n/**\n * An opaque type that represents the contents of a shared backend environment.\n *\n * @public\n */\nexport interface SharedBackendEnvironment {\n  $$type: '@backstage/SharedBackendEnvironment';\n\n  // NOTE: This type is opaque in order to allow for future API evolution without\n  // cluttering the external API. For example we might want to add support\n  // for more powerful callback based backend modifications.\n  //\n  // By making this opaque we also ensure that the type doesn't become an input\n  // type that we need to care about, as it would otherwise be possible to pass\n  // a custom environment definition to `createBackend`, which we don't want.\n}\n\n/**\n * This type is NOT supposed to be used by anyone except internally by the\n * backend-app-api package.\n *\n * @internal\n */\nexport interface InternalSharedBackendEnvironment {\n  version: 'v1';\n  services?: ServiceFactory[];\n}\n\n/**\n * Creates a shared backend environment which can be used to create multiple\n * backends.\n *\n * @public\n */\nexport function createSharedEnvironment<\n  TOptions extends [options?: object] = [],\n>(\n  config:\n    | SharedBackendEnvironmentConfig\n    | ((...params: TOptions) => SharedBackendEnvironmentConfig),\n): (...options: TOptions) => SharedBackendEnvironment {\n  const configCallback = typeof config === 'function' ? config : () => config;\n\n  return (...options) => {\n    const actualConfig = configCallback(...options);\n    const services = actualConfig?.services?.map(sf =>\n      typeof sf === 'function' ? sf() : sf,\n    );\n\n    const exists = new Set<string>();\n    const duplicates = new Set<string>();\n    for (const { service } of services ?? []) {\n      if (exists.has(service.id)) {\n        duplicates.add(service.id);\n      } else {\n        exists.add(service.id);\n      }\n    }\n\n    if (duplicates.size > 0) {\n      const dupStr = [...duplicates].map(id => `'${id}'`).join(', ');\n      throw new Error(\n        `Duplicate service implementations provided in shared environment for ${dupStr}`,\n      );\n    }\n\n    // Here to ensure type safety in this internal implementation.\n    const env: SharedBackendEnvironment & InternalSharedBackendEnvironment = {\n      $$type: '@backstage/SharedBackendEnvironment',\n      version: 'v1',\n      services,\n    };\n    return env;\n  };\n}\n","/*\n * Copyright 2022 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  BackendModuleRegistrationPoints,\n  BackendPluginRegistrationPoints,\n  BackendFeature,\n  ExtensionPoint,\n  InternalBackendFeature,\n  InternalBackendModuleRegistration,\n  InternalBackendPluginRegistration,\n} from './types';\n\n/**\n * The configuration options passed to {@link createExtensionPoint}.\n *\n * @public\n * @see {@link https://backstage.io/docs/backend-system/architecture/extension-points | The architecture of extension points}\n * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}\n */\nexport interface ExtensionPointConfig {\n  /**\n   * The ID of this extension point.\n   *\n   * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}\n   */\n  id: string;\n}\n\n/**\n * Creates a new backend extension point.\n *\n * @public\n * @see {@link https://backstage.io/docs/backend-system/architecture/extension-points | The architecture of extension points}\n */\nexport function createExtensionPoint<T>(\n  config: ExtensionPointConfig,\n): ExtensionPoint<T> {\n  return {\n    id: config.id,\n    get T(): T {\n      throw new Error(`tried to read ExtensionPoint.T of ${this}`);\n    },\n    toString() {\n      return `extensionPoint{${config.id}}`;\n    },\n    $$type: '@backstage/ExtensionPoint',\n  };\n}\n\n/**\n * The configuration options passed to {@link createBackendPlugin}.\n *\n * @public\n * @see {@link https://backstage.io/docs/backend-system/architecture/plugins | The architecture of plugins}\n * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}\n */\nexport interface BackendPluginConfig {\n  /**\n   * The ID of this plugin.\n   *\n   * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}\n   */\n  pluginId: string;\n  register(reg: BackendPluginRegistrationPoints): void;\n}\n\n/**\n * Creates a new backend plugin.\n *\n * @public\n * @see {@link https://backstage.io/docs/backend-system/architecture/plugins | The architecture of plugins}\n * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}\n */\nexport function createBackendPlugin<TOptions extends [options?: object] = []>(\n  config: BackendPluginConfig | ((...params: TOptions) => BackendPluginConfig),\n): (...params: TOptions) => BackendFeature {\n  const configCallback = typeof config === 'function' ? config : () => config;\n  return (...options: TOptions): InternalBackendFeature => {\n    const c = configCallback(...options);\n\n    let registrations: InternalBackendPluginRegistration[];\n\n    return {\n      $$type: '@backstage/BackendFeature',\n      version: 'v1',\n      getRegistrations() {\n        if (registrations) {\n          return registrations;\n        }\n        const extensionPoints: InternalBackendPluginRegistration['extensionPoints'] =\n          [];\n        let init: InternalBackendPluginRegistration['init'] | undefined =\n          undefined;\n\n        c.register({\n          registerExtensionPoint(ext, impl) {\n            if (init) {\n              throw new Error(\n                'registerExtensionPoint called after registerInit',\n              );\n            }\n            extensionPoints.push([ext, impl]);\n          },\n          registerInit(regInit) {\n            if (init) {\n              throw new Error('registerInit must only be called once');\n            }\n            init = {\n              deps: regInit.deps,\n              func: regInit.init,\n            };\n          },\n        });\n\n        if (!init) {\n          throw new Error(\n            `registerInit was not called by register in ${c.pluginId}`,\n          );\n        }\n\n        registrations = [\n          {\n            type: 'plugin',\n            pluginId: c.pluginId,\n            extensionPoints,\n            init,\n          },\n        ];\n        return registrations;\n      },\n    };\n  };\n}\n\n/**\n * The configuration options passed to {@link createBackendModule}.\n *\n * @public\n * @see {@link https://backstage.io/docs/backend-system/architecture/modules | The architecture of modules}\n * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}\n */\nexport interface BackendModuleConfig {\n  /**\n   * The ID of this plugin.\n   *\n   * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}\n   */\n  pluginId: string;\n  /**\n   * Should exactly match the `id` of the plugin that the module extends.\n   */\n  moduleId: string;\n  register(reg: BackendModuleRegistrationPoints): void;\n}\n\n/**\n * Creates a new backend module for a given plugin.\n *\n * @public\n * @see {@link https://backstage.io/docs/backend-system/architecture/modules | The architecture of modules}\n * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}\n */\nexport function createBackendModule<TOptions extends [options?: object] = []>(\n  config: BackendModuleConfig | ((...params: TOptions) => BackendModuleConfig),\n): (...params: TOptions) => BackendFeature {\n  const configCallback = typeof config === 'function' ? config : () => config;\n  return (...options: TOptions): InternalBackendFeature => {\n    const c = configCallback(...options);\n\n    let registrations: InternalBackendModuleRegistration[];\n\n    return {\n      $$type: '@backstage/BackendFeature',\n      version: 'v1',\n      getRegistrations() {\n        if (registrations) {\n          return registrations;\n        }\n        let init: InternalBackendModuleRegistration['init'] | undefined =\n          undefined;\n\n        c.register({\n          registerInit(regInit) {\n            if (init) {\n              throw new Error('registerInit must only be called once');\n            }\n            init = {\n              deps: regInit.deps,\n              func: regInit.init,\n            };\n          },\n        });\n\n        if (!init) {\n          throw new Error(\n            `registerInit was not called by register in ${c.moduleId} module for ${c.pluginId}`,\n          );\n        }\n\n        registrations = [\n          {\n            type: 'module',\n            pluginId: c.pluginId,\n            moduleId: c.moduleId,\n            init,\n          },\n        ];\n        return registrations;\n      },\n    };\n  };\n}\n"],"names":["coreServices"],"mappings":"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"}

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,31 +18,75 @@ import { Readable } from 'stream';
 
 /** @public */
 export declare interface BackendFeature {
-    id: string;
-    register(reg: BackendRegistrationPoints): void;
+    $$type: '@backstage/BackendFeature';
 }
 
-/** @public */
+/**
+ * The configuration options passed to {@link createBackendModule}.
+ *
+ * @public
+ * @see {@link https://backstage.io/docs/backend-system/architecture/modules | The architecture of modules}
+ * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
+ */
 export declare interface BackendModuleConfig {
+    /**
+     * The ID of this plugin.
+     *
+     * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
+     */
     pluginId: string;
+    /**
+     * Should exactly match the `id` of the plugin that the module extends.
+     */
     moduleId: string;
-    register(reg: Omit<BackendRegistrationPoints, 'registerExtensionPoint'>): void;
+    register(reg: BackendModuleRegistrationPoints): void;
 }
 
-/** @public */
+/**
+ * The callbacks passed to the `register` method of a backend module.
+ *
+ * @public
+ */
+export declare interface BackendModuleRegistrationPoints {
+    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;
+}
+
+/**
+ * The configuration options passed to {@link createBackendPlugin}.
+ *
+ * @public
+ * @see {@link https://backstage.io/docs/backend-system/architecture/plugins | The architecture of plugins}
+ * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
+ */
 export declare interface BackendPluginConfig {
-    id: string;
-    register(reg: BackendRegistrationPoints): void;
+    /**
+     * The ID of this plugin.
+     *
+     * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
+     */
+    pluginId: string;
+    register(reg: BackendPluginRegistrationPoints): void;
 }
 
-/** @public */
-export declare interface BackendRegistrationPoints {
+/**
+ * The callbacks passed to the `register` method of a backend plugin.
+ *
+ * @public
+ */
+export declare interface BackendPluginRegistrationPoints {
     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]>;
+            [name in keyof Deps]: ServiceRef<Deps[name]>;
         };
         init(deps: Deps): Promise<void>;
     }): void;
@@ -230,22 +275,26 @@ export declare namespace coreServices {
  * Creates a new backend module for a given plugin.
  *
  * @public
- *
- * @remarks
- *
- * The `moduleId` should be equal to the module-specific suffix of the exported name, such
- * that the full name is `pluginId + "Module" + ModuleId`. For example, a GitHub entity
- * provider module for the `catalog` plugin might have the module ID `'githubEntityProvider'`,
- * and the full exported name would be `catalogModuleGithubEntityProvider`.
- *
- * The `pluginId` should exactly match the `id` of the plugin that the module extends.
+ * @see {@link https://backstage.io/docs/backend-system/architecture/modules | The architecture of modules}
+ * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
  */
 export declare function createBackendModule<TOptions extends [options?: object] = []>(config: BackendModuleConfig | ((...params: TOptions) => BackendModuleConfig)): (...params: TOptions) => BackendFeature;
 
-/** @public */
+/**
+ * Creates a new backend plugin.
+ *
+ * @public
+ * @see {@link https://backstage.io/docs/backend-system/architecture/plugins | The architecture of plugins}
+ * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
+ */
 export declare function createBackendPlugin<TOptions extends [options?: object] = []>(config: BackendPluginConfig | ((...params: TOptions) => BackendPluginConfig)): (...params: TOptions) => BackendFeature;
 
-/** @public */
+/**
+ * Creates a new backend extension point.
+ *
+ * @public
+ * @see {@link https://backstage.io/docs/backend-system/architecture/extension-points | The architecture of extension points}
+ */
 export declare function createExtensionPoint<T>(config: ExtensionPointConfig): ExtensionPoint<T>;
 
 /**
@@ -323,7 +372,9 @@ export declare function createServiceRef<TService>(config: ServiceRefConfig<TSer
 export declare function createServiceRef<TService>(config: ServiceRefConfig<TService, 'root'>): ServiceRef<TService, 'root'>;
 
 /**
- * Creates a shared backend environment which can be used to create multiple backends
+ * Creates a shared backend environment which can be used to create multiple
+ * backends.
+ *
  * @public
  */
 export declare function createSharedEnvironment<TOptions extends [options?: object] = []>(config: SharedBackendEnvironmentConfig | ((...params: TOptions) => SharedBackendEnvironmentConfig)): (...options: TOptions) => SharedBackendEnvironment;
@@ -414,11 +465,22 @@ export declare type ExtensionPoint<T> = {
      */
     T: T;
     toString(): string;
-    $$ref: 'extension-point';
+    $$type: '@backstage/ExtensionPoint';
 };
 
-/** @public */
+/**
+ * The configuration options passed to {@link createExtensionPoint}.
+ *
+ * @public
+ * @see {@link https://backstage.io/docs/backend-system/architecture/extension-points | The architecture of extension points}
+ * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
+ */
 export declare interface ExtensionPointConfig {
+    /**
+     * The ID of this extension point.
+     *
+     * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
+     */
     id: string;
 }
 
@@ -435,24 +497,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.
@@ -460,20 +526,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 {
 }
@@ -814,7 +873,7 @@ export declare type ServiceRef<TService, TScope extends 'root' | 'plugin' = 'roo
      */
     T: TService;
     toString(): string;
-    $$ref: 'service';
+    $$type: '@backstage/ServiceRef';
 };
 
 /** @public */
@@ -832,13 +891,19 @@ declare type ServiceRefsToInstances<T extends {
 };
 
 /**
+ * An opaque type that represents the contents of a shared backend environment.
+ *
  * @public
  */
 export declare interface SharedBackendEnvironment {
-    $$type: 'SharedBackendEnvironment';
+    $$type: '@backstage/SharedBackendEnvironment';
 }
 
-/** @public */
+/**
+ * The configuration options passed to {@link createSharedEnvironment}.
+ *
+ * @public
+ */
 export declare interface SharedBackendEnvironmentConfig {
     services?: ServiceFactoryOrFunction[];
 }
@@ -868,11 +933,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.0",
+  "version": "0.4.0-next.2",
   "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.0",
+    "@backstage/backend-tasks": "^0.4.3-next.2",
     "@backstage/config": "^1.0.6",
-    "@backstage/plugin-auth-node": "^0.2.11-next.0",
+    "@backstage/plugin-auth-node": "^0.2.11-next.2",
     "@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.1"
+    "@backstage/cli": "^0.22.2-next.1"
   },
   "files": [
     "dist",