@equinor/fusion-framework-app 13.0.3 → 13.1.1

package/src/AppConfigurator.ts

@@ -1,280 +0,0 @@
-import type { FusionModulesInstance } from '@equinor/fusion-framework';
-
-import {
-  type AnyModule,
-  type IModulesConfigurator,
-  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 auth from '@equinor/fusion-framework-module-msal';
-
-import type { AppEnv, AppModules } from './types';
-import { AppModulesConfiguredEvent } from './AppModulesConfiguredEvent';
-import { AppConfiguratorError } from './AppConfiguratorError';
-import { deepClone, deepFreeze, type DeepImmutable } from './utils';
-
-/**
- * Type definition for AppConfigurator constructor
- */
-export type AppConfiguratorConstructor<
-  TModules extends readonly AnyModule[] = [],
-  TRef extends FusionModulesInstance = FusionModulesInstance,
-  TEnv extends AppEnv = AppEnv,
-> = {
-  new (env: TEnv, ref?: TRef): IAppConfigurator<TModules, TRef>;
-};
-
-/**
- * Contract for configuring Fusion application modules.
- *
- * `IAppConfigurator` extends the base module configurator with application-specific
- * methods for setting up HTTP clients and integrating with Fusion service discovery.
- * Use this interface when typing configuration callbacks that receive the configurator.
- *
- * @template TModules - Additional application-specific modules to register beyond the defaults.
- * @template TRef - The resolved Fusion modules instance used as a reference during initialization.
- *
- * @example
- * ```ts
- * import type { IAppConfigurator } from '@equinor/fusion-framework-app';
- *
- * const configure = (configurator: IAppConfigurator) => {
- *   configurator.configureHttpClient('myApi', {
- *     baseUri: 'https://api.example.com',
- *     defaultScopes: ['api://client-id/.default'],
- *   });
- * };
- * ```
- */
-export interface IAppConfigurator<
-  TModules extends Array<AnyModule> | unknown = unknown,
-  TRef extends FusionModulesInstance = FusionModulesInstance,
-> extends IModulesConfigurator<AppModules<TModules>, TRef> {
-  readonly manifest: DeepImmutable<AppEnv['manifest']>;
-
-  /**
-   * Configure the HTTP module with custom settings.
-   *
-   * Delegates to the framework `configureHttp` helper. Use this when you need
-   * low-level control over the HTTP module configuration. For most applications,
-   * prefer {@link IAppConfigurator.configureHttpClient | configureHttpClient} instead.
-   *
-   * @param args - Arguments forwarded to the framework `configureHttp` function.
-   */
-  configureHttp(...args: Parameters<typeof configureHttp>): void;
-
-  /**
-   * Register a named HTTP client with explicit base URI and authentication scopes.
-   *
-   * Use this method when the application needs to call a specific API endpoint
-   * that is not provided through Fusion service discovery.
-   *
-   * @param args - Arguments forwarded to the framework `configureHttpClient` function.
-   *
-   * @example
-   * ```ts
-   * configurator.configureHttpClient('myClient', {
-   *   baseUri: 'https://foo.bar',
-   *   defaultScopes: ['api://client-id/.default'],
-   * });
-   * ```
-   */
-  configureHttpClient(...args: Parameters<typeof configureHttpClient>): void;
-
-  /**
-   * Register a named HTTP client resolved through Fusion service discovery.
-   *
-   * The `serviceName` is looked up in the portal’s service-discovery registry at
-   * initialization time. Base URI and default scopes are resolved automatically.
-   * Use this instead of {@link IAppConfigurator.configureHttpClient | configureHttpClient}
-   * when the service is registered with the Fusion portal.
-   *
-   * @param serviceName - Registered name of the service in Fusion service discovery.
-   * @param options - Optional HTTP client overrides (headers, interceptors, etc.).
-   *                  `baseUri` and `defaultScopes` are excluded because they are
-   *                  resolved from service discovery.
-   */
-  // TODO(#5060): rename
-  useFrameworkServiceClient(
-    serviceName: string,
-    // biome-ignore lint/suspicious/noExplicitAny: `HttpClientOptions<any>` widens to accept options for any request payload type
-    options?: Omit<HttpClientOptions<any>, 'baseUri' | 'defaultScopes'>,
-  ): void;
-}
-
-/**
- * Configurator that bootstraps default Fusion application modules and provides
- * helper methods for HTTP client and service-discovery setup.
- *
- * `AppConfigurator` is created internally by {@link configureModules}. It registers
- * the `event`, `http`, and `msal` (auth) modules by default and reads any HTTP
- * endpoints declared in the application's environment config.
- *
- * @template TModules - Additional application-specific modules beyond the defaults.
- * @template TRef - The resolved Fusion modules instance used as an initialization reference.
- * @template TEnv - The application environment descriptor (manifest, config, basename).
- *
- * @example
- * ```ts
- * // Typically used indirectly via configureModules:
- * import { configureModules } from '@equinor/fusion-framework-app';
- *
- * const initialize = configureModules((configurator) => {
- *   configurator.useFrameworkServiceClient('my-service');
- * });
- * ```
- */
-export class AppConfigurator<
-    TModules extends Array<AnyModule> | unknown = unknown,
-    TRef extends FusionModulesInstance = FusionModulesInstance,
-    TEnv extends AppEnv = AppEnv,
-  >
-  extends ModulesConfigurator<AppModules<TModules>, TRef>
-  implements IAppConfigurator<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 = 'AppConfigurator';
-
-  #manifest: DeepImmutable<AppEnv['manifest']>;
-
-  /**
-   * Create an application configurator with default modules and environment.
-   *
-   * Registers the `event`, `http`, and `msal` modules and pre-configures any
-   * HTTP clients declared in `env.config.endpoints`.
-   *
-   * @param env - The application environment containing manifest, config, and optional basename.
-   * @param ref - Optional reference to the Fusion modules instance, used for event dispatching.
-   */
-  constructor(
-    public readonly env: TEnv,
-    ref?: TRef,
-  ) {
-    super([event, http, auth]);
-    this.#manifest = deepFreeze(deepClone(env.manifest));
-    this._configureHttpClientsFromAppConfig();
-
-    this.onConfigured((configs) => {
-      const configuredEvent = new AppModulesConfiguredEvent<TModules>({
-        detail: {
-          appKey: this.#manifest.appKey,
-          configs,
-        },
-      });
-      ref?.event.dispatchEvent(configuredEvent);
-    });
-  }
-
-  /**
-   * The immutable application manifest.
-   *
-   * Deeply frozen at construction time to prevent accidental mutations.
-   *
-   * @returns The deeply immutable application manifest.
-   */
-  get manifest(): DeepImmutable<AppEnv['manifest']> {
-    return this.#manifest;
-  }
-
-  /**
-   * Read HTTP endpoint definitions from the application config and register each
-   * one as a named HTTP client.
-   *
-   * Iterates over `env.config.endpoints` and calls
-   * {@link IAppConfigurator.configureHttpClient | configureHttpClient} for each entry.
-   */
-  protected _configureHttpClientsFromAppConfig() {
-    const { endpoints = {} } = this.env.config ?? {};
-    // Register an HTTP client for each endpoint defined in the app configuration.
-    for (const [key, { url, scopes }] of Object.entries(endpoints)) {
-      this.configureHttpClient(key, {
-        baseUri: url,
-        defaultScopes: scopes,
-      });
-    }
-  }
-
-  /** {@inheritDoc IAppConfigurator.configureHttp} */
-  public configureHttp(...args: Parameters<typeof configureHttp>): void {
-    this.addConfig(configureHttp(...args));
-  }
-
-  /** {@inheritDoc IAppConfigurator.configureHttpClient} */
-  public configureHttpClient(...args: Parameters<typeof configureHttpClient>): void {
-    this.addConfig(configureHttpClient(...args));
-  }
-
-  /**
-   * Register a named HTTP client whose base URI and scopes are resolved via
-   * Fusion service discovery.
-   *
-   * Resolution priority (highest wins):
-   * 1. Session overrides (user-specific URL / scopes)
-   * 2. Application config (`env.config.endpoints`)
-   * 3. Service-discovery registry
-   *
-   * If a client with the same `serviceName` is already registered (e.g. from
-   * app config) and the service has **not** been overridden at session level,
-   * a warning is logged and the existing configuration is kept.
-   *
-   * @param serviceName - Registered name of the service in Fusion service discovery.
-   * @param options - Optional HTTP client overrides. `baseUri` and `defaultScopes`
-   *                  are excluded because they come from service discovery.
-   * @throws {Error} When the service cannot be resolved from service discovery.
-   *
-   * @example
-   * ```ts
-   * configurator.useFrameworkServiceClient('my-backend-service');
-   * ```
-   */
-  public useFrameworkServiceClient(
-    serviceName: string,
-    // biome-ignore lint/suspicious/noExplicitAny: `HttpClientOptions<any>` widens to accept options for any request payload type
-    options?: Omit<HttpClientOptions<any>, 'baseUri' | 'defaultScopes'>,
-  ): void {
-    this.addConfig({
-      module: http,
-      configure: async (config, ref) => {
-        // Service from serviceDiscovery with potential session override.
-        const service = await ref?.serviceDiscovery.resolveService(serviceName);
-        // Guard: service must resolve before the HTTP client can be configured.
-        if (!service) {
-          throw new AppConfiguratorError(
-            `Unable to resolve service [${serviceName}] during configuration.`,
-            'configuration',
-          );
-        }
-
-        // Check if serviceName is already configured (potentially with app-config)
-        // If the service is session overridden - we need the configuration to run
-        // as normal (the uri already updated).
-        if (config.hasClient(serviceName) && !service.overridden) {
-          console.warn(
-            `${serviceName} is already configured, possibly by app.config.[ENV].ts.
-             Overriding configurations may lead to unintended behaviour and should
-             be reviewed carefully.`,
-          );
-          return;
-        }
-        config.configureClient(serviceName, {
-          ...options,
-          baseUri: service.uri,
-          defaultScopes: service.defaultScopes,
-        });
-      },
-    });
-  }
-}
-
-export default AppConfigurator;

package/src/AppConfiguratorError.ts

@@ -1,34 +0,0 @@
-/**
- * Custom error class for application configurator errors.
- *
- * Provides error context to help developers debug configuration and initialization issues.
- *
- * @example
- * ```ts
- * try {
- *   const modules = await initialize({ fusion, env });
- * } catch (error) {
- *   if (error instanceof AppConfiguratorError) {
- *     console.log(`Error in ${error.phase}: ${error.message}`);
- *   }
- * }
- * ```
- */
-export class AppConfiguratorError extends Error {
-  /**
-   * @param message - Human-readable error description
-   * @param phase - The phase where the error occurred
-   * @param cause - The underlying error that caused this failure
-   */
-  constructor(
-    message: string,
-    public readonly phase: 'configuration' | 'initialization',
-    cause?: unknown,
-  ) {
-    super(message);
-    this.name = 'AppConfiguratorError';
-    this.cause = cause;
-  }
-}
-
-export default AppConfiguratorError;

package/src/AppModulesConfiguredEvent.ts

@@ -1,43 +0,0 @@
-import type { ModulesConfigType, AnyModule } from '@equinor/fusion-framework-module';
-import type { AppModules } from '@equinor/fusion-framework-module-app';
-import { FrameworkEvent, type FrameworkEventInit } from '@equinor/fusion-framework-module-event';
-import type { AppModulesInitializedEvent } from './AppModulesInitializedEvent';
-
-/**
- * Represents the initialization data for an event indicating that application modules have been configured.
- *
- * @template T - Array of additional modules configured in the application.
- * @extends FrameworkEventInit
- * @property {string} appKey - The unique key identifying the application.
- * @property {ModulesConfigType<AppModules<T>>} configs - The configuration objects for the specified application modules.
- */
-type AppModulesConfiguredEventInit<T extends AnyModule[] | unknown = unknown> = FrameworkEventInit<{
-  appKey: string;
-  configs: ModulesConfigType<AppModules<T>>;
-}>;
-
-/**
- * Event emitted when application modules have been configured.
- *
- * @template T - An array of additional modules configured in the application.
- * @extends FrameworkEvent<AppModulesConfiguredEventInit<T>>
- */
-export class AppModulesConfiguredEvent<
-  T extends AnyModule[] | unknown = unknown,
-> extends FrameworkEvent<AppModulesConfiguredEventInit<T>> {
-  /**
-   * Create an event describing configured application modules.
-   *
-   * @param init - Event initialization data containing the application key and module configs.
-   */
-  constructor(init: AppModulesConfiguredEventInit<T>) {
-    super('onAppModulesConfigured', init);
-  }
-}
-
-declare module '@equinor/fusion-framework-module-event' {
-  interface FrameworkEventMap {
-    onAppModulesConfigured: AppModulesConfiguredEvent;
-    onAppModulesInitialized: AppModulesInitializedEvent;
-  }
-}

package/src/AppModulesInitializedEvent.ts

@@ -1,40 +0,0 @@
-import type { AnyModule } from '@equinor/fusion-framework-module';
-import type { AppModulesInstance } from '@equinor/fusion-framework-module-app';
-import { FrameworkEvent, type FrameworkEventInit } from '@equinor/fusion-framework-module-event';
-
-/**
- * Event initialization type for the "AppModulesInitialized" event.
- *
- * @template T - An array of module types extending `AnyModule`. Defaults to an empty array.
- * @property appKey - The unique key identifying the application.
- * @property modules - The instance containing all initialized application modules.
- */
-type AppModulesInitializedEventInit<T extends AnyModule[] | unknown = unknown> =
-  FrameworkEventInit<{
-    appKey: string;
-    modules: AppModulesInstance<T>;
-  }>;
-
-/**
- * Event triggered when application modules have been initialized.
- *
- * @template T - An array of modules extending `AnyModule`. Defaults to an empty array.
- * @extends FrameworkEvent<AppModulesInitializedEventInit<T>>
- *
- * @example
- * ```typescript
- * const event = new AppModulesInitializedEvent({ modules: [...] });
- * ```
- */
-export class AppModulesInitializedEvent<
-  T extends AnyModule[] | unknown = unknown,
-> extends FrameworkEvent<AppModulesInitializedEventInit<T>> {
-  /**
-   * Create an event describing initialized application modules.
-   *
-   * @param init - Event initialization data containing the application key and module instance.
-   */
-  constructor(init: AppModulesInitializedEventInit<T>) {
-    super('onAppModulesInitialized', init);
-  }
-}

package/src/__tests__/AppConfigurator.test.ts

@@ -1,49 +0,0 @@
-import { describe, it, expect, beforeEach } from 'vitest';
-import { firstValueFrom, take } from 'rxjs';
-import { AppConfigurator } from '../AppConfigurator';
-import type { AnyModule } from '@equinor/fusion-framework-module';
-import { SemanticVersion } from '@equinor/fusion-framework-module';
-
-describe('AppConfigurator', () => {
-  let configurator: AppConfigurator;
-
-  // Create a mock module for testing
-  const createMockModule = (name: string, version = '1.0.0'): AnyModule => ({
-    name,
-    version: new SemanticVersion(version),
-    initialize: () => ({ mockInstance: true }),
-  });
-
-  // Mock environment object
-  const mockEnv = {
-    manifest: {
-      appKey: 'test-app',
-      displayName: 'Test App',
-      description: 'A test application',
-      type: 'standalone' as const,
-      build: {
-        version: '1.0.0',
-        entryPoint: 'index.js',
-      },
-    },
-  };
-
-  beforeEach(() => {
-    configurator = new AppConfigurator(mockEnv);
-  });
-
-  describe('Event Name Prefixing', () => {
-    it('should prefix event names with "AppConfigurator::"', 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(/^AppConfigurator::/);
-    });
-  });
-});

package/src/configure-modules.ts

@@ -1,121 +0,0 @@
-/**
- * @fileoverview Application module configuration factory
- *
- * Provides the core factory function for configuring and initializing
- * application-specific modules in the Fusion framework.
- */
-
-import type { Fusion } from '@equinor/fusion-framework';
-import type { AnyModule } from '@equinor/fusion-framework-module';
-import {
-  enableTelemetry,
-  type MetadataExtractor,
-} from '@equinor/fusion-framework-module-telemetry';
-
-import { AppConfigurator } from './AppConfigurator';
-
-import type { AppModulesInstance, AppModuleInitiator, AppEnv } from './types';
-
-/**
- * Create an application module initializer for a Fusion application.
- *
- * `configureModules` is the primary entry point for setting up an application’s
- * module pipeline. It returns an async function that, when called with the Fusion
- * instance and the application environment, will:
- *
- * 1. Create an {@link AppConfigurator} with the provided environment.
- * 2. Wire up telemetry scoped to the application.
- * 3. Invoke the optional user-supplied configuration callback.
- * 4. Initialize all registered modules and dispatch an `onAppModulesLoaded` event.
- *
- * @template TModules - Additional application-specific modules to register.
- * @template TRef - The Fusion instance type, used as a configuration reference.
- * @template TEnv - The application environment descriptor (manifest, config, basename).
- *
- * @param cb - Optional configuration callback invoked before modules are initialized.
- *             Use this to register HTTP clients, enable bookmarks, or add custom modules.
- * @returns An async initializer function that accepts `{ fusion, env }` and resolves
- *          with the fully initialized application module instance.
- *
- * @example
- * ```ts
- * import { configureModules } from '@equinor/fusion-framework-app';
- *
- * const initialize = configureModules((configurator, { fusion, env }) => {
- *   configurator.useFrameworkServiceClient('my-service');
- * });
- *
- * // Later, during app bootstrap:
- * const modules = await initialize({ fusion, env });
- * ```
- */
-export const configureModules =
-  <
-    TModules extends Array<AnyModule> | never,
-    TRef extends Fusion = Fusion,
-    TEnv extends AppEnv = AppEnv,
-  >(
-    cb?: AppModuleInitiator<TModules, TRef, TEnv>,
-  ): ((args: { fusion: TRef; env: TEnv }) => Promise<AppModulesInstance<TModules>>) =>
-  /**
-   * Async initializer that bootstraps application modules.
-   *
-   * @param args - Object containing the Fusion instance and the application environment.
-   * @param args.fusion - The active Fusion framework instance.
-   * @param args.env - The application environment with manifest, config, and basename.
-   * @returns The fully initialized application module instance.
-   */
-  async (args: { fusion: TRef; env: TEnv }): Promise<AppModulesInstance<TModules>> => {
-    const { fusion } = args;
-
-    // Create app configurator
-    const configurator = new AppConfigurator<TModules, TRef['modules'], TEnv>(args.env);
-
-    // Extract telemetry metadata from app manifest for tracking and debugging
-    const metadataExtractor: MetadataExtractor = () => {
-      return {
-        fusion: {
-          type: 'app-telemetry',
-          app: {
-            key: args.env.manifest?.appKey || 'unknown-app',
-            version: args.env.manifest?.build?.version || 'unknown-version',
-          },
-        },
-      };
-    };
-
-    // Enable telemetry collection for module configuration events
-    // attachConfiguratorEvents automatically prefixes events with configurator class name
-    enableTelemetry(configurator, {
-      attachConfiguratorEvents: true,
-      configure: (builder) => {
-        builder.setMetadata(metadataExtractor);
-        builder.setParent(fusion.modules.telemetry);
-        // Scope telemetry to 'app' level for app-specific event filtering
-        builder.setDefaultScope(['app']);
-      },
-    });
-
-    // Allow user configuration callback to run before module initialization
-    if (cb) {
-      await Promise.resolve(cb(configurator, args));
-    }
-    // Type cast is safe because AppConfigurator.initialize() returns the exact module
-    // instance that was registered and configured above. The intermediate 'unknown'
-    // cast is necessary due to TypeScript's generic inference limitations with the
-    // configurator's initialization chain, but the runtime value is guaranteed to match.
-    const modules: AppModulesInstance<TModules> = (await configurator.initialize(
-      args.fusion.modules,
-    )) as unknown as AppModulesInstance<TModules>;
-
-    // Dispatch app modules loaded event for app lifecycle tracking
-    // TODO(#5061): remove check after fusion-cli is updated (app module is not enabled in fusion-cli)
-    if (args.env.manifest?.appKey) {
-      modules.event.dispatchEvent('onAppModulesLoaded', {
-        detail: { appKey: args.env.manifest.appKey, manifest: args.env.manifest, modules },
-      });
-    }
-    return modules;
-  };
-
-export default configureModules;

package/src/enable-bookmark.ts

@@ -1,95 +0,0 @@
-import type {
-  BookmarkModule,
-  BookmarkPayloadGenerator,
-} from '@equinor/fusion-framework-module-bookmark';
-import type { IAppConfigurator } from './AppConfigurator';
-
-/**
- * Enable the bookmark module for a Fusion application.
- *
- * Adds bookmark support by wiring the portal’s bookmark provider into the
- * application’s module set. Payload generators registered by the application
- * are automatically cleaned up when the module is disposed, preventing memory
- * leaks across application load/unload cycles.
- *
- * Import this function from `@equinor/fusion-framework-app/enable-bookmark` or, for
- * React apps, from `@equinor/fusion-framework-react-app/bookmark`.
- *
- * @remarks
- * - The portal must expose a bookmark provider on `ref.bookmark`; if it is
- *   missing, an error is logged and the module initializes as a no-op.
- * - The `@equinor/fusion-framework-module-bookmark` package must be installed,
- *   but do **not** call its `enableBookmark` directly in app code — use this
- *   app-level enabler instead.
- *
- * @param config - The application configurator to register the bookmark module on.
- *
- * @example
- * ```ts
- * import { configureModules } from '@equinor/fusion-framework-app';
- * import { enableBookmark } from '@equinor/fusion-framework-app/enable-bookmark';
- *
- * const initialize = configureModules((configurator) => {
- *   enableBookmark(configurator);
- * });
- * ```
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export const enableBookmark = (config: IAppConfigurator): void => {
-  // collection of cleanup functions
-  const cleanupFunctions = new Set<VoidFunction>();
-  config.addConfig({
-    module: {
-      name: 'bookmark',
-      initialize(args) {
-        // get the bookmark provider from the ref (portal)
-        const provider = args.ref?.bookmark;
-        // Bail out early if the portal did not expose a bookmark provider.
-        if (!provider) {
-          console.error('Bookmark provider not found');
-          return {};
-        }
-        // create a proxy to intercept the addPayloadGenerator method
-        return new Proxy(provider, {
-          get(target, prop) {
-            // Intercept specific property access to wrap bookmark lifecycle management.
-            switch (prop) {
-              case 'addPayloadGenerator':
-                return (generator: BookmarkPayloadGenerator) => {
-                  // catch the teardown function and add it to the cleanup functions
-                  const cleanupHandler = target.addPayloadGenerator(generator);
-                  cleanupFunctions.add(cleanupHandler);
-                  // wrap the teardown function to remove it from the cleanup functions
-                  return () => {
-                    cleanupFunctions.delete(cleanupHandler);
-                    cleanupHandler();
-                  };
-                };
-            }
-            /**
-             * If the property is not addPayloadGenerator, we want to access the property on the provider
-             *
-             * @remarks we can not use the Reflect API to access the property, as the provider is a proxy
-             * and the Reflect API will not work as expected (can not access private properties)
-             */
-            if (prop in target) {
-              // if the property is a function, bind it to the provider
-              if (typeof target[prop] === 'function') {
-                return target[prop].bind(target);
-              }
-              // access the property
-              return target[prop];
-            }
-          },
-        });
-      },
-      dispose() {
-        // Run all registered cleanup functions to prevent memory leaks on module disposal.
-        for (const teardown of cleanupFunctions) {
-          teardown();
-        }
-        cleanupFunctions.clear();
-      },
-    } satisfies BookmarkModule,
-  });
-};