backend-plugin-api: internal refactor to split creators

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

packages/backend-plugin-api/src/wiring/createBackendModule.test.ts

@@ -14,60 +14,9 @@
  * limitations under the License.
  */
 
-import {
-  createBackendModule,
-  createBackendPlugin,
-  createExtensionPoint,
-} from './factories';
+import { createBackendModule } from './createBackendModule';
 import { InternalBackendFeature } from './types';
 
-describe('createExtensionPoint', () => {
-  it('should create an ExtensionPoint', () => {
-    const extensionPoint = createExtensionPoint({ id: 'x' });
-    expect(extensionPoint).toBeDefined();
-    expect(extensionPoint.id).toBe('x');
-    expect(() => extensionPoint.T).not.toThrow();
-    expect(String(extensionPoint)).toBe('extensionPoint{x}');
-  });
-});
-
-describe('createBackendPlugin', () => {
-  it('should create a BackendPlugin', () => {
-    const result = createBackendPlugin({
-      pluginId: 'x',
-      register(r) {
-        r.registerInit({ deps: {}, async init() {} });
-      },
-    });
-
-    // legacy form
-    const legacy = result() as unknown as InternalBackendFeature;
-    expect(legacy.$$type).toEqual('@backstage/BackendFeature');
-    expect(legacy.version).toEqual('v1');
-    expect(legacy.getRegistrations).toEqual(expect.any(Function));
-
-    // new form
-    const plugin = result as unknown as InternalBackendFeature;
-    expect(plugin.$$type).toEqual('@backstage/BackendFeature');
-    expect(plugin.version).toEqual('v1');
-    expect(plugin.getRegistrations).toEqual(expect.any(Function));
-    expect(plugin.getRegistrations()).toEqual([
-      {
-        type: 'plugin',
-        pluginId: 'x',
-        extensionPoints: [],
-        init: {
-          deps: expect.any(Object),
-          func: expect.any(Function),
-        },
-      },
-    ]);
-
-    // @ts-expect-error
-    expect(plugin({ a: 'a' })).toBeDefined();
-  });
-});
-
 describe('createBackendModule', () => {
   it('should create a BackendModule', () => {
     const result = createBackendModule({

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

@@ -0,0 +1,107 @@
+/*
+ * Copyright 2022 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.
+ */
+
+import { BackendFeatureCompat } from '../types';
+import {
+  BackendModuleRegistrationPoints,
+  InternalBackendModuleRegistration,
+  InternalBackendPluginRegistration,
+} from './types';
+
+/**
+ * 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 interface CreateBackendModuleOptions {
+  /**
+   * Should exactly match the `id` of the plugin that the module extends.
+   *
+   * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
+   */
+  pluginId: string;
+
+  /**
+   * The ID of this module, used to identify the module and ensure that it is not installed twice.
+   */
+  moduleId: string;
+  register(reg: BackendModuleRegistrationPoints): void;
+}
+
+/**
+ * Creates a new backend module for a given plugin.
+ *
+ * @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 function createBackendModule(
+  options: CreateBackendModuleOptions,
+): BackendFeatureCompat {
+  function getRegistrations() {
+    const extensionPoints: InternalBackendPluginRegistration['extensionPoints'] =
+      [];
+    let init: InternalBackendModuleRegistration['init'] | undefined = undefined;
+
+    options.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 ${options.moduleId} module for ${options.pluginId}`,
+      );
+    }
+
+    return [
+      {
+        type: 'module',
+        pluginId: options.pluginId,
+        moduleId: options.moduleId,
+        extensionPoints,
+        init,
+      },
+    ];
+  }
+
+  function backendFeatureCompatWrapper() {
+    return backendFeatureCompatWrapper;
+  }
+
+  Object.assign(backendFeatureCompatWrapper, {
+    $$type: '@backstage/BackendFeature' as const,
+    version: 'v1',
+    getRegistrations,
+  });
+
+  return backendFeatureCompatWrapper as BackendFeatureCompat;
+}

packages/backend-plugin-api/src/wiring/createBackendPlugin.test.ts

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2022 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.
+ */
+
+import { createBackendPlugin } from './createBackendPlugin';
+import { InternalBackendFeature } from './types';
+
+describe('createBackendPlugin', () => {
+  it('should create a BackendPlugin', () => {
+    const result = createBackendPlugin({
+      pluginId: 'x',
+      register(r) {
+        r.registerInit({ deps: {}, async init() {} });
+      },
+    });
+
+    // legacy form
+    const legacy = result() as unknown as InternalBackendFeature;
+    expect(legacy.$$type).toEqual('@backstage/BackendFeature');
+    expect(legacy.version).toEqual('v1');
+    expect(legacy.getRegistrations).toEqual(expect.any(Function));
+
+    // new form
+    const plugin = result as unknown as InternalBackendFeature;
+    expect(plugin.$$type).toEqual('@backstage/BackendFeature');
+    expect(plugin.version).toEqual('v1');
+    expect(plugin.getRegistrations).toEqual(expect.any(Function));
+    expect(plugin.getRegistrations()).toEqual([
+      {
+        type: 'plugin',
+        pluginId: 'x',
+        extensionPoints: [],
+        init: {
+          deps: expect.any(Object),
+          func: expect.any(Function),
+        },
+      },
+    ]);
+
+    // @ts-expect-error
+    expect(plugin({ a: 'a' })).toBeDefined();
+  });
+});

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

@@ -0,0 +1,100 @@
+/*
+ * Copyright 2022 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.
+ */
+
+import { BackendFeatureCompat } from '../types';
+import {
+  BackendPluginRegistrationPoints,
+  InternalBackendPluginRegistration,
+} from './types';
+
+/**
+ * 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 interface CreateBackendPluginOptions {
+  /**
+   * 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;
+}
+
+/**
+ * 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 function createBackendPlugin(
+  options: CreateBackendPluginOptions,
+): BackendFeatureCompat {
+  function getRegistrations() {
+    const extensionPoints: InternalBackendPluginRegistration['extensionPoints'] =
+      [];
+    let init: InternalBackendPluginRegistration['init'] | undefined = undefined;
+
+    options.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 ${options.pluginId}`,
+      );
+    }
+
+    return [
+      {
+        type: 'plugin',
+        pluginId: options.pluginId,
+        extensionPoints,
+        init,
+      },
+    ];
+  }
+
+  function backendFeatureCompatWrapper() {
+    return backendFeatureCompatWrapper;
+  }
+
+  Object.assign(backendFeatureCompatWrapper, {
+    $$type: '@backstage/BackendFeature' as const,
+    version: 'v1',
+    getRegistrations,
+  });
+
+  return backendFeatureCompatWrapper as BackendFeatureCompat;
+}

packages/backend-plugin-api/src/wiring/createExtensionPoint.test.ts

@@ -0,0 +1,27 @@
+/*
+ * Copyright 2022 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.
+ */
+
+import { createExtensionPoint } from './createExtensionPoint';
+
+describe('createExtensionPoint', () => {
+  it('should create an ExtensionPoint', () => {
+    const extensionPoint = createExtensionPoint({ id: 'x' });
+    expect(extensionPoint).toBeDefined();
+    expect(extensionPoint.id).toBe('x');
+    expect(() => extensionPoint.T).not.toThrow();
+    expect(String(extensionPoint)).toBe('extensionPoint{x}');
+  });
+});

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

@@ -0,0 +1,58 @@
+/*
+ * Copyright 2022 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.
+ */
+
+import { ExtensionPoint } from './types';
+
+/**
+ * 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 interface CreateExtensionPointOptions {
+  /**
+   * The ID of this extension point.
+   *
+   * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
+   */
+  id: string;
+}
+
+/**
+ * Creates a new backend extension point.
+ *
+ * @public
+ * @see {@link https://backstage.io/docs/backend-system/architecture/extension-points | The architecture of extension points}
+ */
+export function createExtensionPoint<T>(
+  options: CreateExtensionPointOptions,
+): ExtensionPoint<T> {
+  return {
+    id: options.id,
+    get T(): T {
+      if (process.env.NODE_ENV === 'test') {
+        // Avoid throwing errors so tests asserting extensions' properties cannot be easily broken
+        return null as T;
+      }
+      throw new Error(`tried to read ExtensionPoint.T of ${this}`);
+    },
+    toString() {
+      return `extensionPoint{${options.id}}`;
+    },
+    $$type: '@backstage/ExtensionPoint',
+  };
+}

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

@@ -1,229 +0,0 @@
-/*
- * Copyright 2022 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.
- */
-
-import { BackendFeatureCompat } from '../types';
-import {
-  BackendModuleRegistrationPoints,
-  BackendPluginRegistrationPoints,
-  ExtensionPoint,
-  InternalBackendModuleRegistration,
-  InternalBackendPluginRegistration,
-} from './types';
-
-/**
- * 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 interface CreateExtensionPointOptions {
-  /**
-   * The ID of this extension point.
-   *
-   * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
-   */
-  id: string;
-}
-
-/**
- * Creates a new backend extension point.
- *
- * @public
- * @see {@link https://backstage.io/docs/backend-system/architecture/extension-points | The architecture of extension points}
- */
-export function createExtensionPoint<T>(
-  options: CreateExtensionPointOptions,
-): ExtensionPoint<T> {
-  return {
-    id: options.id,
-    get T(): T {
-      if (process.env.NODE_ENV === 'test') {
-        // Avoid throwing errors so tests asserting extensions' properties cannot be easily broken
-        return null as T;
-      }
-      throw new Error(`tried to read ExtensionPoint.T of ${this}`);
-    },
-    toString() {
-      return `extensionPoint{${options.id}}`;
-    },
-    $$type: '@backstage/ExtensionPoint',
-  };
-}
-
-/**
- * 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 interface CreateBackendPluginOptions {
-  /**
-   * 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;
-}
-
-/**
- * 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 function createBackendPlugin(
-  options: CreateBackendPluginOptions,
-): BackendFeatureCompat {
-  function getRegistrations() {
-    const extensionPoints: InternalBackendPluginRegistration['extensionPoints'] =
-      [];
-    let init: InternalBackendPluginRegistration['init'] | undefined = undefined;
-
-    options.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 ${options.pluginId}`,
-      );
-    }
-
-    return [
-      {
-        type: 'plugin',
-        pluginId: options.pluginId,
-        extensionPoints,
-        init,
-      },
-    ];
-  }
-
-  function backendFeatureCompatWrapper() {
-    return backendFeatureCompatWrapper;
-  }
-
-  Object.assign(backendFeatureCompatWrapper, {
-    $$type: '@backstage/BackendFeature' as const,
-    version: 'v1',
-    getRegistrations,
-  });
-
-  return backendFeatureCompatWrapper as BackendFeatureCompat;
-}
-
-/**
- * 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 interface CreateBackendModuleOptions {
-  /**
-   * Should exactly match the `id` of the plugin that the module extends.
-   *
-   * @see {@link https://backstage.io/docs/backend-system/architecture/naming-patterns | Recommended naming patterns}
-   */
-  pluginId: string;
-
-  /**
-   * The ID of this module, used to identify the module and ensure that it is not installed twice.
-   */
-  moduleId: string;
-  register(reg: BackendModuleRegistrationPoints): void;
-}
-
-/**
- * Creates a new backend module for a given plugin.
- *
- * @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 function createBackendModule(
-  options: CreateBackendModuleOptions,
-): BackendFeatureCompat {
-  function getRegistrations() {
-    const extensionPoints: InternalBackendPluginRegistration['extensionPoints'] =
-      [];
-    let init: InternalBackendModuleRegistration['init'] | undefined = undefined;
-
-    options.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 ${options.moduleId} module for ${options.pluginId}`,
-      );
-    }
-
-    return [
-      {
-        type: 'module',
-        pluginId: options.pluginId,
-        moduleId: options.moduleId,
-        extensionPoints,
-        init,
-      },
-    ];
-  }
-
-  function backendFeatureCompatWrapper() {
-    return backendFeatureCompatWrapper;
-  }
-
-  Object.assign(backendFeatureCompatWrapper, {
-    $$type: '@backstage/BackendFeature' as const,
-    version: 'v1',
-    getRegistrations,
-  });
-
-  return backendFeatureCompatWrapper as BackendFeatureCompat;
-}

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

@@ -14,17 +14,13 @@
  * limitations under the License.
  */
 
-import type {
-  CreateBackendPluginOptions,
-  CreateBackendModuleOptions,
-  CreateExtensionPointOptions,
-} from './factories';
+import { type CreateBackendModuleOptions } from './createBackendModule';
+import { type CreateBackendPluginOptions } from './createBackendPlugin';
+import { type CreateExtensionPointOptions } from './createExtensionPoint';
 
-export {
-  createBackendModule,
-  createBackendPlugin,
-  createExtensionPoint,
-} from './factories';
+export { createBackendModule } from './createBackendModule';
+export { createBackendPlugin } from './createBackendPlugin';
+export { createExtensionPoint } from './createExtensionPoint';
 
 export type {
   BackendModuleRegistrationPoints,