backend-plugin-api: doc and type cleanup for wiring API

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

packages/backend-plugin-api/src/types.ts

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Base type for options objects that aren't required.
+ *
+ * @internal
+ * @ignore
+ */
+export type MaybeOptions = object | undefined;
+
+/**
+ * Helper type that makes the options argument optional if options are not required.
+ *
+ * @internal
+ * @ignore
+ */
+export type FactoryFunctionWithOptions<TResult, TOptions> =
+  undefined extends TOptions
+    ? (options?: TOptions) => TResult
+    : (options: TOptions) => TResult;

packages/backend-plugin-api/src/wiring/factories.ts

@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
+import { FactoryFunctionWithOptions, MaybeOptions } from '../types';
 import {
   BackendRegistrationPoints,
   BackendFeature,
@@ -21,16 +22,21 @@ import {
 } from './types';
 
 /** @public */
-export function createExtensionPoint<T>(options: {
+export interface ExtensionPointConfig {
   id: string;
-}): ExtensionPoint<T> {
+}
+
+/** @public */
+export function createExtensionPoint<T>(
+  config: ExtensionPointConfig,
+): ExtensionPoint<T> {
   return {
-    id: options.id,
+    id: config.id,
     get T(): T {
       throw new Error(`tried to read ExtensionPoint.T of ${this}`);
     },
     toString() {
-      return `extensionPoint{${options.id}}`;
+      return `extensionPoint{${config.id}}`;
     },
     $$ref: 'extension-point', // TODO: declare
   };
@@ -43,14 +49,9 @@ export interface BackendPluginConfig<TOptions> {
 }
 
 /** @public */
-export function createBackendPlugin<
-  TOptions extends object | undefined = undefined,
->(config: {
-  id: string;
-  register(reg: BackendRegistrationPoints, options: TOptions): void;
-}): undefined extends TOptions
-  ? (options?: TOptions) => BackendFeature
-  : (options: TOptions) => BackendFeature {
+export function createBackendPlugin<TOptions extends MaybeOptions = undefined>(
+  config: BackendPluginConfig<TOptions>,
+): FactoryFunctionWithOptions<BackendFeature, TOptions> {
   return (options?: TOptions) => ({
     id: config.id,
     register(register: BackendRegistrationPoints) {
@@ -70,9 +71,11 @@ export interface BackendModuleConfig<TOptions> {
 }
 
 /**
+ * Creates a new backend module for a given plugin.
+ *
  * @public
  *
- * Creates a new backend module for a given plugin.
+ * @remarks
  *
  * The `moduleId` should be equal to the module-specific prefix of the exported name, such
  * that the full name is `moduleId + PluginId + "Module"`. For example, a GitHub entity
@@ -81,13 +84,9 @@ export interface BackendModuleConfig<TOptions> {
  *
  * The `pluginId` should exactly match the `id` of the plugin that the module extends.
  */
-export function createBackendModule<
-  TOptions extends object | undefined = undefined,
->(
+export function createBackendModule<TOptions extends MaybeOptions = undefined>(
   config: BackendModuleConfig<TOptions>,
-): undefined extends TOptions
-  ? (options?: TOptions) => BackendFeature
-  : (options: TOptions) => BackendFeature {
+): FactoryFunctionWithOptions<BackendFeature, TOptions> {
   return (options?: TOptions) => ({
     id: `${config.pluginId}.${config.moduleId}`,
     register(register: BackendRegistrationPoints) {

packages/backend-plugin-api/src/wiring/index.ts

@@ -14,7 +14,11 @@
  * limitations under the License.
  */
 
-export type { BackendModuleConfig, BackendPluginConfig } from './factories';
+export type {
+  BackendModuleConfig,
+  BackendPluginConfig,
+  ExtensionPointConfig,
+} from './factories';
 export {
   createBackendModule,
   createBackendPlugin,