@equinor/fusion-framework 8.1.0 → 8.1.1

package/src/FrameworkConfigurator.ts

@@ -1,273 +0,0 @@
-import { type AnyModule, ModulesConfigurator } from '@equinor/fusion-framework-module';
-
-import event from '@equinor/fusion-framework-module-event';
-
-import http, {
-  configureHttpClient,
-  configureHttp,
-  type HttpClientOptions,
-} from '@equinor/fusion-framework-module-http';
-import type { HttpClientMsal } from '@equinor/fusion-framework-module-http/client';
-
-import auth, { type AuthConfigFn } from '@equinor/fusion-framework-module-msal';
-
-import context from '@equinor/fusion-framework-module-context';
-
-import disco from '@equinor/fusion-framework-module-service-discovery';
-import services from '@equinor/fusion-framework-module-services';
-import telemetry, { enableTelemetry } from '@equinor/fusion-framework-module-telemetry';
-
-import type { FusionModules } from './types.js';
-import type { MsalClientConfig } from '@equinor/fusion-framework-module-msal';
-import { version } from './version.js';
-
-/**
- * Configurator that registers and wires the core Fusion Framework modules.
- *
- * Extend `FrameworkConfigurator` to declare which modules (authentication,
- * HTTP, service-discovery, telemetry, context, …) the framework instance
- * should contain and how each module is configured before the framework
- * starts.
- *
- * Typical workflow:
- * 1. Create a `FrameworkConfigurator` instance.
- * 2. Call configuration helpers such as {@link configureMsal},
- *    {@link configureHttp}, {@link configureHttpClient}, and
- *    {@link configureServiceDiscovery}.
- * 3. Pass the configurator to {@link init} to bootstrap the framework.
- *
- * @template TModules - Additional module descriptors to merge with the
- *   built-in Fusion modules.
- * @template TRef - Optional reference object forwarded to module
- *   initialization (e.g. a parent framework instance).
- *
- * @example
- * ```typescript
- * import { FrameworkConfigurator, init } from '@equinor/fusion-framework';
- *
- * const configurator = new FrameworkConfigurator();
- * configurator.configureMsal({ clientId: 'my-client-id', authority: '…' });
- * configurator.configureServiceDiscovery({
- *   client: { baseUri: 'https://service-registry.example.com' },
- * });
- *
- * const fusion = await init(configurator);
- * ```
- */
-export class FrameworkConfigurator<
-  TModules extends Array<AnyModule> = [],
-  // biome-ignore lint/suspicious/noExplicitAny: default must be bivariant `any`, not `unknown` \u2014 `unknown` breaks assignability when a concrete `FrameworkConfigurator<TModules, TRef>` is used where the default-typed class is expected
-  TRef = any,
-> extends ModulesConfigurator<FusionModules<TModules>, TRef> {
-  /**
-   * The class name used for event naming. This static property ensures
-   * the name is preserved through compilation and minification.
-   */
-  static readonly className: string = 'FrameworkConfigurator';
-
-  /**
-   * Creates a new FrameworkConfigurator instance with default telemetry configuration.
-   *
-   * Initializes the framework with core modules (event, auth, http, service discovery,
-   * services, context, and telemetry) and sets up default telemetry that includes
-   * framework version metadata and 'framework' scope for all telemetry events.
-   *
-   * @example
-   * ```typescript
-   * const configurator = new FrameworkConfigurator();
-   * // Now ready to configure additional modules
-   * ```
-   */
-  constructor() {
-    super([event, auth, http, disco, services, context, telemetry]);
-
-    // default configuration
-    enableTelemetry(this, {
-      configure: (builder) => {
-        builder.setMetadata({
-          fusion: {
-            type: 'framework-telemetry',
-            framework: {
-              version,
-            },
-          },
-        });
-        builder.setDefaultScope(['framework']);
-      },
-    });
-  }
-
-  /**
-   * Configures the global HTTP module settings such as base URLs, default headers,
-   * request/response interceptors, and timeout settings.
-   *
-   * This affects all HTTP requests made through the framework's HTTP module.
-   * Use this for application-wide HTTP configuration.
-   *
-   * @param args - HTTP module configuration arguments (same as configureHttp function)
-   *
-   * @example
-   * ```typescript
-   * configurator.configureHttp({
-   *   baseUri: 'https://api.example.com',
-   *   defaultHeaders: { 'X-App-Version': '1.0.0' }
-   * });
-   * ```
-   */
-  public configureHttp(...args: Parameters<typeof configureHttp>) {
-    this.addConfig(configureHttp(...args));
-  }
-
-  /**
-   * Configures a named HTTP client instance with specific settings.
-   *
-   * Unlike configureHttp which sets global HTTP settings, this creates a named client
-   * that can have its own base URL, headers, interceptors, and other HTTP-specific
-   * configuration. Useful for connecting to different APIs or services with different requirements.
-   *
-   * @param args - HTTP client configuration arguments: [name, clientOptions]
-   *               where name is a string identifier and clientOptions contains HTTP settings
-   *
-   * @example
-   * ```typescript
-   * // Configure a client for external API
-   * configurator.configureHttpClient('external-api', {
-   *   baseUri: 'https://external-api.com',
-   *   defaultHeaders: { 'Authorization': 'Bearer token' }
-   * });
-   *
-   * // Configure a client for internal services
-   * configurator.configureHttpClient('internal', {
-   *   baseUri: 'https://internal.company.com',
-   *   timeout: 10000
-   * });
-   * ```
-   */
-  public configureHttpClient(...args: Parameters<typeof configureHttpClient>) {
-    this.addConfig(configureHttpClient(...args));
-  }
-
-  /**
-   * Configures Microsoft Authentication Library (MSAL) authentication for the framework.
-   *
-   * This sets up OAuth 2.0 / OpenID Connect authentication using Azure AD or other
-   * MSAL-compatible identity providers. The authentication module will handle token
-   * acquisition, refresh, and user session management.
-   *
-   * @param cb_or_config - Authentication configuration. Can be either:
-   *                      - A callback function that receives an auth builder for advanced configuration
-   *                      - A client configuration object with MSAL settings
-   * @param requiresAuth - Whether the application requires authentication to function.
-   *                      When true (default), unauthenticated users cannot access the app.
-   *                      When false, authentication is optional but available when needed.
-   *
-   * @example
-   * ```typescript
-   * // Simple configuration with client config object
-   * configurator.configureMsal({
-   *   clientId: 'your-client-id',
-   *   authority: 'https://login.microsoftonline.com/your-tenant-id'
-   * });
-   *
-   * // Advanced configuration with callback
-   * configurator.configureMsal((builder) => {
-   *   builder.setClientConfig({
-   *     clientId: 'your-client-id',
-   *     authority: 'https://login.microsoftonline.com/your-tenant-id'
-   *   });
-   *   builder.setScopes(['User.Read', 'api://your-api/scope']);
-   *   builder.setRequiresAuth(true);
-   * });
-   *
-   * // Optional authentication
-   * configurator.configureMsal(config, false);
-   * ```
-   */
-  public configureMsal(cb_or_config: AuthConfigFn | MsalClientConfig, requiresAuth = true) {
-    this.addConfig({
-      module: auth,
-      configure: (builder) => {
-        // Only override the default requiresAuth flag when the caller explicitly set one
-        if (requiresAuth !== undefined) {
-          builder.setRequiresAuth(!!requiresAuth);
-        }
-        // A function argument configures the builder directly
-        if (typeof cb_or_config === 'function') {
-          cb_or_config(builder);
-        }
-        // A plain object argument is applied as the MSAL client config
-        if (typeof cb_or_config === 'object') {
-          builder.setClientConfig(cb_or_config);
-        }
-      },
-    });
-  }
-
-  /**
-   * Configures the service discovery module to automatically find and connect to services.
-   *
-   * Service discovery allows the framework to dynamically locate microservices and APIs
-   * at runtime rather than hardcoding their URLs. This is essential in distributed systems
-   * where services may be deployed across multiple environments or scaled dynamically.
-   *
-   * @param args - Configuration object for service discovery
-   * @param args.client - HTTP client configuration used to communicate with the
-   *                     service discovery registry. Typically includes base URL,
-   *                     authentication, and timeout settings.
-   *
-   * @example
-   * ```typescript
-   * configurator.configureServiceDiscovery({
-   *   client: {
-   *     baseUri: 'https://service-registry.company.com',
-   *     defaultHeaders: { 'Authorization': 'Bearer token' },
-   *     timeout: 5000
-   *   }
-   * });
-   * ```
-   */
-  public configureServiceDiscovery(args: { client: HttpClientOptions<HttpClientMsal> }) {
-    this.configureHttpClient('service_discovery', args.client);
-  }
-
-  /**
-   * Configures application telemetry and observability settings.
-   *
-   * Telemetry enables tracking of application usage, performance metrics, errors,
-   * and custom events. This helps with monitoring, debugging, and understanding
-   * how your application is being used. The framework comes with default telemetry
-   * that includes framework version and scope information.
-   *
-   * @param cb - Configuration callback function that receives a telemetry builder.
-   *             Use this to customize telemetry settings like event scopes, metadata,
-   *             sampling rates, and custom instrumentation.
-   *
-   * @example
-   * ```typescript
-   * configurator.configureTelemetry((builder) => {
-   *   // Add custom metadata to all telemetry events
-   *   builder.setMetadata({
-   *     application: 'my-app',
-   *     environment: 'production',
-   *     version: '1.2.3'
-   *   });
-   *
-   *   // Set custom scopes for filtering events
-   *   builder.setDefaultScope(['app', 'performance']);
-   *
-   *   // Configure sampling (only send 10% of events)
-   *   builder.setSamplingRate(0.1);
-   *
-   *   // Add custom instrumentation
-   *   builder.addInstrumentation('custom-operation', (context) => {
-   *     // Track custom metrics
-   *   });
-   * });
-   * ```
-   */
-  public configureTelemetry(cb: Parameters<typeof enableTelemetry>[1]): void {
-    enableTelemetry(this, cb);
-  }
-}
-
-export default FrameworkConfigurator;

package/src/__tests__/FrameworkConfigurator.test.ts

@@ -1,35 +0,0 @@
-import { describe, it, expect, beforeEach } from 'vitest';
-import { firstValueFrom, take } from 'rxjs';
-import { FrameworkConfigurator } from '../FrameworkConfigurator.js';
-import type { AnyModule } from '@equinor/fusion-framework-module';
-import { SemanticVersion } from '@equinor/fusion-framework-module';
-
-describe('FrameworkConfigurator', () => {
-  let configurator: FrameworkConfigurator;
-
-  // Create a mock module for testing
-  const createMockModule = (name: string, version = '1.0.0'): AnyModule => ({
-    name,
-    version: new SemanticVersion(version),
-    initialize: () => ({ mockInstance: true }),
-  });
-
-  beforeEach(() => {
-    configurator = new FrameworkConfigurator();
-  });
-
-  describe('Event Name Prefixing', () => {
-    it('should prefix event names with "FrameworkConfigurator::"', async () => {
-      // Trigger event by adding a config
-      configurator.addConfig({
-        module: createMockModule('test', '1.0.0'),
-        configure: () => {},
-      });
-
-      // Wait for the first event to be emitted
-      const event = await firstValueFrom(configurator.event$.pipe(take(1)));
-
-      expect(event.name).toMatch(/^FrameworkConfigurator::/);
-    });
-  });
-});

package/src/__tests__/mock/application-module.test.ts

@@ -1,87 +0,0 @@
-import { describe, expect, it } from 'vitest';
-
-import type { IModulesConfigurator, Module } from '@equinor/fusion-framework-module';
-
-import { mockFramework } from '../../mock/index.js';
-
-/**
- * A module an application team owns, which the framework knows nothing about.
- *
- * @remarks
- * The point of these tests is that nothing below required support from
- * `@equinor/fusion-framework/mock`. If an application team can do this, the
- * extension pattern holds.
- */
-interface InvoiceClient {
-  getInvoice(id: string): Promise<{ id: string; total: number }>;
-}
-
-class InvoiceConfigurator {
-  #client?: InvoiceClient;
-
-  public setClient(client: InvoiceClient): void {
-    this.#client = client;
-  }
-
-  public createClient(): InvoiceClient {
-    if (!this.#client) {
-      throw new Error('An invoice client is required');
-    }
-    return this.#client;
-  }
-}
-
-type InvoiceModule = Module<'invoices', InvoiceClient, InvoiceConfigurator>;
-
-const invoiceModule: InvoiceModule = {
-  name: 'invoices',
-  configure: () => new InvoiceConfigurator(),
-  initialize: ({ config }) => config.createClient(),
-};
-
-/** The team's own mock, following the pattern the built-in modules use. */
-const enableInvoicesMock = (
-  // biome-ignore lint/suspicious/noExplicitAny: mirrors every enableX helper
-  configurator: IModulesConfigurator<any, any>,
-  options: { total?: number } = {},
-): void => {
-  configurator.addConfig({
-    module: invoiceModule,
-    configure: (builder: InvoiceConfigurator) =>
-      builder.setClient({
-        getInvoice: async (id) => ({ id, total: options.total ?? 0 }),
-      }),
-  } as { module: InvoiceModule });
-};
-
-describe('application modules', () => {
-  it('fails to start without its mock, so the seam is real and not a no-op', async () => {
-    await expect(
-      mockFramework<[InvoiceModule]>((configurator) => {
-        configurator.addConfig({ module: invoiceModule } as { module: InvoiceModule });
-      }),
-    ).rejects.toThrow(/invoice client is required/i);
-  });
-
-  it('composes with the built-in mocks and is typed without a cast', async () => {
-    const fusion = await mockFramework<[InvoiceModule]>((configurator) => {
-      configurator.msal.setAccount({ name: 'Ada Lovelace' });
-      enableInvoicesMock(configurator, { total: 42 });
-    });
-
-    // No cast: `TModules` must flow through to `fusion.modules`.
-    const invoice = await fusion.modules.invoices.getInvoice('inv-1');
-
-    expect(invoice).toEqual({ id: 'inv-1', total: 42 });
-    expect(fusion.modules.auth.account?.name).toBe('Ada Lovelace');
-  });
-
-  it('is registered exactly as it is in production', async () => {
-    // The same helper, against a real FrameworkConfigurator, would behave identically.
-    const fusion = await mockFramework<[InvoiceModule]>((configurator) =>
-      enableInvoicesMock(configurator, { total: 7 }),
-    );
-
-    await expect(fusion.modules.invoices.getInvoice('inv-2')).resolves.toMatchObject({ total: 7 });
-  });
-});

package/src/__tests__/mock/documented-usage.test.ts

@@ -1,98 +0,0 @@
-import { afterEach, describe, expect, it, vi } from 'vitest';
-
-import { decodeJwtSegment } from '@equinor/fusion-framework-module-msal/mock';
-
-import { init } from '../../init.js';
-import { createMockService, FrameworkMockConfigurator, mockFramework } from '../../mock/index.js';
-
-/**
- * Pins the snippets in `docs/testing.md` and the package README to real
- * behaviour, so documentation cannot drift away from the API it describes.
- */
-describe('documented usage', () => {
-  afterEach(() => vi.restoreAllMocks());
-
-  it('composes the service registry on the builder', async () => {
-    const fusion = await mockFramework((configurator) => {
-      configurator.serviceDiscovery.setBaseUri('http://localhost:6669');
-      configurator.serviceDiscovery.addService({ key: 'my-api' });
-      configurator.serviceDiscovery.removeService('bookmarks');
-    });
-
-    await expect(fusion.modules.serviceDiscovery.resolveService('my-api')).resolves.toMatchObject({
-      key: 'my-api',
-    });
-  });
-
-  it('replaces the baseline registry with setServices', async () => {
-    const fusion = await mockFramework((configurator) => {
-      configurator.serviceDiscovery.setServices([{ key: 'apps', uri: 'http://localhost:3000' }]);
-    });
-
-    await expect(fusion.modules.serviceDiscovery.resolveService('apps')).resolves.toMatchObject({
-      uri: 'http://localhost:3000',
-    });
-  });
-
-  it('keeps startup working when the registry is replaced, because unknown services synthesise', async () => {
-    // The context module resolves `context` while initializing, so a replaced
-    // registry that omits it would break start-up if synthesis were disabled.
-    const fusion = await mockFramework((configurator) => {
-      configurator.serviceDiscovery.setServices([{ key: 'apps', uri: 'http://localhost:3000' }]);
-    });
-
-    await expect(fusion.modules.serviceDiscovery.resolveService('people')).resolves.toBeDefined();
-  });
-
-  it('lets the test runner spy on the discovery client', async () => {
-    const fusion = await mockFramework();
-
-    vi.spyOn(fusion.modules.serviceDiscovery.client, 'resolveService').mockResolvedValue(
-      createMockService({ key: 'apps', uri: 'http://spied' }),
-    );
-
-    await expect(fusion.modules.serviceDiscovery.resolveService('apps')).resolves.toMatchObject({
-      uri: 'http://spied',
-    });
-  });
-
-  it('lets the test runner spy on the auth client', async () => {
-    const fusion = await mockFramework();
-
-    const spy = vi.spyOn(fusion.modules.auth.client, 'acquireToken');
-
-    await fusion.modules.auth.acquireAccessToken({ request: { scopes: ['Files.Read'] } });
-
-    expect(spy).toHaveBeenCalled();
-  });
-
-  it('resolves the real scope through the real provider, not the test double', async () => {
-    const fusion = await mockFramework((configurator) => {
-      // The client is configured with what it talks to, exactly as in production
-      configurator.msal.setClientConfig({ auth: { clientId: 'my-app', tenantId: 'my-tenant' } });
-    });
-
-    const token = await fusion.modules.auth.acquireAccessToken();
-    const claims = JSON.parse(decodeJwtSegment(token?.split('.')[1] ?? ''));
-
-    // MsalProvider — not the mock — turns "no scopes requested" into `${clientId}/.default`
-    expect(claims.scp).toBe('my-app/.default');
-  });
-
-  it('signs nobody in when the account is signed out', async () => {
-    const fusion = await mockFramework((configurator) => {
-      configurator.msal.setAccount({ signedOut: true });
-    });
-
-    expect(fusion.modules.auth.account).toBeFalsy();
-  });
-
-  it('can be constructed directly and initialized with init', async () => {
-    const configurator = new FrameworkMockConfigurator();
-    configurator.msal.setAccount({ name: 'Ada Lovelace' });
-
-    const fusion = await init(configurator);
-
-    expect(fusion.modules.auth.account?.name).toBe('Ada Lovelace');
-  });
-});