@equinor/fusion-framework 8.1.0 → 8.1.1

package/src/__tests__/mock/mock-framework.test.ts

@@ -1,278 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-
-import type { Module } from '@equinor/fusion-framework-module';
-import { enableMsalMock } from '@equinor/fusion-framework-module-msal/mock';
-import { enableServiceDiscoveryMock } from '@equinor/fusion-framework-module-service-discovery/mock';
-import { TelemetryLevel } from '@equinor/fusion-framework-module-telemetry';
-
-import { FrameworkConfigurator } from '../../FrameworkConfigurator.js';
-import { init } from '../../init.js';
-import { FrameworkMockConfigurator, mockFramework } from '../../mock/index.js';
-
-/** A minimal configurator, standing in for an application's own. */
-class WidgetsConfigurator {
-  #name = 'default';
-  setName(name: string): this {
-    this.#name = name;
-    return this;
-  }
-  get name(): string {
-    return this.#name;
-  }
-}
-
-/** A minimal module, standing in for one an application supplies through `TModules`. */
-type WidgetsModule = Module<'widgets', { name: string }, WidgetsConfigurator>;
-const widgetsModule: WidgetsModule = {
-  name: 'widgets',
-  configure: () => new WidgetsConfigurator(),
-  initialize: ({ config }) => ({ name: config.name }),
-};
-
-describe('mockFramework', () => {
-  it('initializes every built-in module without configuration', async () => {
-    const fusion = await mockFramework();
-
-    expect(fusion.modules.event).toBeDefined();
-    expect(fusion.modules.auth).toBeDefined();
-    expect(fusion.modules.http).toBeDefined();
-    expect(fusion.modules.serviceDiscovery).toBeDefined();
-    expect(fusion.modules.context).toBeDefined();
-    expect(fusion.modules.telemetry).toBeDefined();
-  });
-
-  it('signs in a default user so an application has an identity to read', async () => {
-    const fusion = await mockFramework();
-
-    expect(fusion.modules.auth.account?.name).toBe('Test User');
-  });
-
-  it('resolves the services a Fusion application needs at start-up', async () => {
-    const fusion = await mockFramework();
-
-    await expect(fusion.modules.serviceDiscovery.resolveService('apps')).resolves.toMatchObject({
-      key: 'apps',
-    });
-  });
-
-  it('passes a real FrameworkConfigurator to the callback', async () => {
-    expect.assertions(2);
-
-    await mockFramework((configurator) => {
-      expect(configurator).toBeInstanceOf(FrameworkMockConfigurator);
-      expect(configurator).toBeInstanceOf(FrameworkConfigurator);
-    });
-  });
-
-  it('awaits an asynchronous callback before initializing', async () => {
-    const fusion = await mockFramework(async (configurator) => {
-      await Promise.resolve();
-      configurator.msal.setAccount({ name: 'Ada Lovelace' });
-    });
-
-    expect(fusion.modules.auth.account?.name).toBe('Ada Lovelace');
-  });
-});
-
-describe('FrameworkMockConfigurator', () => {
-  it('exposes the same msal configurator the auth module is built from', async () => {
-    const fusion = await mockFramework((configurator) => {
-      configurator.msal.setAccount({ name: 'Ada Lovelace', username: 'ada@equinor.com' });
-    });
-
-    expect(fusion.modules.auth.account).toMatchObject({
-      name: 'Ada Lovelace',
-      username: 'ada@equinor.com',
-    });
-  });
-
-  it('lets the last declared account win', async () => {
-    const fusion = await mockFramework((configurator) => {
-      configurator.msal.setAccount({ name: 'Ada Lovelace' });
-      configurator.msal.setAccount({ name: 'Grace Hopper' });
-    });
-
-    expect(fusion.modules.auth.account?.name).toBe('Grace Hopper');
-  });
-
-  it('resolves an account callback when the config is built', async () => {
-    const fusion = await mockFramework((configurator) => {
-      configurator.msal.setAccount(async () => ({ name: 'Ada Lovelace' }));
-    });
-
-    expect(fusion.modules.auth.account?.name).toBe('Ada Lovelace');
-  });
-
-  it('builds the auth client when the module builds its config, not when the account is set', async () => {
-    const configurator = new FrameworkMockConfigurator();
-
-    configurator.msal.setAccount({ name: 'Ada Lovelace' });
-
-    // The account is configuration; nothing is constructed from it yet
-    expect(configurator.msal.getClient()).toBeUndefined();
-
-    const fusion = await init(configurator);
-
-    expect(fusion.modules.auth.account?.name).toBe('Ada Lovelace');
-  });
-
-  it('exposes the same service discovery configurator the module is built from', async () => {
-    const fusion = await mockFramework((configurator) => {
-      configurator.serviceDiscovery.setBaseUri('http://localhost:6669');
-      configurator.serviceDiscovery.addService({ key: 'my-api' });
-    });
-
-    const service = await fusion.modules.serviceDiscovery.resolveService('my-api');
-
-    expect(service.uri).toContain('http://localhost:6669');
-  });
-
-  it('lets a service be removed so its absence can be asserted', async () => {
-    const fusion = await mockFramework((configurator) => {
-      configurator.serviceDiscovery.setResolveUnknownServices(false);
-      configurator.serviceDiscovery.removeService('bookmarks');
-    });
-
-    await expect(fusion.modules.serviceDiscovery.resolveService('bookmarks')).rejects.toThrow();
-  });
-
-  it('accepts an enableX helper directly, because it is a real configurator', async () => {
-    const fusion = await mockFramework((configurator) => {
-      enableMsalMock(configurator, (builder) => builder.setAccount({ name: 'Grace Hopper' }));
-      enableServiceDiscoveryMock(configurator, (builder) => builder.addService({ key: 'my-api' }));
-    });
-
-    expect(fusion.modules.auth.account?.name).toBe('Grace Hopper');
-    await expect(fusion.modules.serviceDiscovery.resolveService('my-api')).resolves.toBeDefined();
-  });
-
-  it('registers a module through addModule', async () => {
-    const fusion = await mockFramework((configurator) => {
-      configurator.addModule((c) =>
-        enableMsalMock(c, (builder) => builder.setAccount({ name: 'Grace Hopper' })),
-      );
-    });
-
-    expect(fusion.modules.auth.account?.name).toBe('Grace Hopper');
-  });
-
-  it('returns itself from addModule so calls can be chained', () => {
-    const configurator = new FrameworkMockConfigurator();
-
-    expect(configurator.addModule(() => undefined)).toBe(configurator);
-  });
-
-  it('exposes the same http configurator the http module is built from', async () => {
-    const configurator = new FrameworkMockConfigurator();
-
-    configurator.http.configureClient('my-api', { baseUri: 'http://localhost:6669' });
-
-    const fusion = await init(configurator);
-
-    expect(fusion.modules.http.createClient('my-api')).toBeDefined();
-  });
-
-  it('exposes the same services configurator the services module is built from', () => {
-    const configurator = new FrameworkMockConfigurator();
-
-    expect(configurator.services).toBeDefined();
-  });
-
-  it('exposes the same context configurator the context module is built from', () => {
-    const configurator = new FrameworkMockConfigurator();
-
-    expect(configurator.context).toBeDefined();
-  });
-
-  it('seeds the initial context through the context module, so `.context` backs the real module', async () => {
-    const fusion = await mockFramework((configurator) => {
-      configurator.context.setCurrentContext({
-        id: 'my-ctx',
-        type: { id: 'ProjectMaster' },
-        value: {},
-      });
-    });
-
-    expect(fusion.modules.context.currentContext).toMatchObject({ id: 'my-ctx' });
-  });
-
-  it('exposes the same telemetry configurator the telemetry module is built from', () => {
-    const configurator = new FrameworkMockConfigurator();
-
-    expect(configurator.telemetry).toBeDefined();
-  });
-
-  it('collects a tracked event through the telemetry mock adapter, reaching no real endpoint', async () => {
-    let mockConfigurator: FrameworkMockConfigurator | undefined;
-    const fusion = await mockFramework((configurator) => {
-      mockConfigurator = configurator;
-    });
-
-    fusion.modules.telemetry.trackEvent({
-      name: 'button-click',
-      level: TelemetryLevel.Information,
-      scope: [],
-    });
-
-    await vi.waitFor(() => {
-      expect(mockConfigurator?.telemetry.adapter.getItems('button-click')).toHaveLength(1);
-    });
-  });
-
-  it('lets a module supplied through TModules get the same kind of accessor as msal and serviceDiscovery', async () => {
-    // Standing in for an application subclassing FrameworkMockConfigurator to
-    // expose its own module the same way the built-ins are exposed.
-    class AppMockConfigurator extends FrameworkMockConfigurator<[WidgetsModule]> {
-      constructor() {
-        super();
-        this._pin(widgetsModule);
-      }
-      get widgets(): WidgetsConfigurator {
-        return this._getConfig('widgets');
-      }
-    }
-
-    const configurator = new AppMockConfigurator();
-    configurator.widgets.setName('Ada');
-
-    const fusion = await init(configurator);
-
-    expect(fusion.modules.widgets.name).toBe('Ada');
-  });
-
-  it('pins the same instance across repeated reads, so declarations accumulate on one configurator', () => {
-    class AppMockConfigurator extends FrameworkMockConfigurator<[WidgetsModule]> {
-      constructor() {
-        super();
-        this._pin(widgetsModule);
-      }
-      get widgets(): WidgetsConfigurator {
-        return this._getConfig('widgets');
-      }
-    }
-
-    const configurator = new AppMockConfigurator();
-
-    expect(configurator.widgets).toBe(configurator.widgets);
-  });
-
-  it('throws from _getConfig when nothing was pinned for that name', () => {
-    class AppMockConfigurator extends FrameworkMockConfigurator {
-      readMissing(): unknown {
-        return this._getConfig('widgets');
-      }
-    }
-
-    expect(() => new AppMockConfigurator().readMissing()).toThrow(/widgets/);
-  });
-
-  it('throws from _pin when the module declares no configure factory', () => {
-    class AppMockConfigurator extends FrameworkMockConfigurator {
-      pinMissingConfigure(): void {
-        this._pin({ ...widgetsModule, configure: undefined } as WidgetsModule);
-      }
-    }
-
-    expect(() => new AppMockConfigurator().pinMissingConfigure()).toThrow(/configure factory/);
-  });
-});

package/src/index.ts

@@ -1,44 +0,0 @@
-/**
- * Entry point for `@equinor/fusion-framework` — the core initialization
- * package of Fusion Framework.
- *
- * @remarks
- * Re-exports the {@link FrameworkConfigurator} (used to configure framework
- * modules before initialization), the {@link init} function (used to
- * bootstrap the framework), and all public type aliases that describe
- * the resulting module graph.
- *
- * @packageDocumentation
- */
-
-import type { FrameworkEvent, FrameworkEventInit } from '@equinor/fusion-framework-module-event';
-import type { Fusion } from './types.js';
-
-declare module '@equinor/fusion-framework-module-event' {
-  interface FrameworkEventMap {
-    /**
-     * Dispatched after all framework modules have been initialized and the
-     * global `window.Fusion` reference has been set.
-     */
-    onFrameworkLoaded: FrameworkEvent<FrameworkEventInit<Fusion>>;
-  }
-}
-
-declare global {
-  interface Window {
-    /** Global Fusion instance, set during {@link init}. */
-    Fusion: Fusion;
-  }
-}
-
-export {
-  FrameworkConfigurator,
-  /**
-   * @deprecated Use {@link FrameworkConfigurator} instead.
-   */
-  FrameworkConfigurator as FusionConfigurator,
-} from './FrameworkConfigurator';
-
-export type { FusionModules, FusionModulesInstance, Fusion, FusionRenderFn } from './types';
-
-export { default, init } from './init';

package/src/init.ts

@@ -1,61 +0,0 @@
-import type { AnyModule } from '@equinor/fusion-framework-module';
-
-import type { FrameworkConfigurator } from './FrameworkConfigurator.js';
-import type { Fusion, FusionModules } from './types.js';
-
-/**
- * Initialize Fusion Framework from a fully-configured
- * {@link FrameworkConfigurator}.
- *
- * This is the main bootstrap entry point. It resolves all module
- * configurations, instantiates every registered module, assigns the
- * resulting {@link Fusion} object to `window.Fusion`, and dispatches
- * the `onFrameworkLoaded` event.
- *
- * @template TModules - Additional module descriptors beyond the built-in
- *   Fusion modules.
- * @template TRef - Reference object forwarded to modules during
- *   initialization (e.g. a parent framework instance).
- *
- * @param configurator - A {@link FrameworkConfigurator} that has been set up
- *   with the desired module configurations (MSAL, HTTP, service discovery,
- *   etc.).
- * @param ref - Optional reference object passed through to each module's
- *   initializer, typically used when an application framework is initialized
- *   within an outer host framework.
- * @returns A promise that resolves to the initialized {@link Fusion}
- *   instance containing all configured module instances.
- *
- * @example
- * ```typescript
- * import { FrameworkConfigurator, init } from '@equinor/fusion-framework';
- *
- * const configurator = new FrameworkConfigurator();
- * configurator.configureMsal({ clientId: '…', authority: '…' });
- *
- * const fusion = await init(configurator);
- * console.log(fusion.modules); // all instantiated modules
- * ```
- */
-export const init = async <TModules extends Array<AnyModule>, TRef extends object>(
-  configurator: FrameworkConfigurator<TModules>,
-  ref?: TRef,
-): Promise<Fusion<TModules>> => {
-  const modules = await configurator.initialize<FusionModules>(ref);
-  const fusion = {
-    modules,
-  };
-  // Expose globally so portal shells and widgets can access the running instance.
-  // Guarded because the framework must also initialize where no DOM exists, such as
-  // a test runner or a server-side render.
-  if (typeof window !== 'undefined') {
-    // Global exposure predates strict typing on `Window.Fusion`; the shape is guaranteed by this function's own construction above
-    window.Fusion = fusion as unknown as Fusion;
-  }
-  modules.event.dispatchEvent('onFrameworkLoaded', { detail: fusion });
-
-  // The generic TModules type is erased on the plain object above; restore it for the return type
-  return fusion as unknown as Fusion<TModules>;
-};
-
-export default init;

package/src/mock/FrameworkMockConfigurator.ts

@@ -1,270 +0,0 @@
-import type { AnyModule } from '@equinor/fusion-framework-module';
-
-import {
-  contextMockModule,
-  type ContextMockConfigurator,
-} from '@equinor/fusion-framework-module-context/mock';
-import {
-  module as httpModule,
-  type IHttpClientConfigurator,
-} from '@equinor/fusion-framework-module-http';
-import {
-  msalMockModule,
-  type MsalMockConfigurator,
-} from '@equinor/fusion-framework-module-msal/mock';
-import {
-  serviceDiscoveryMockModule,
-  type ServiceDiscoveryMockConfigurator,
-} from '@equinor/fusion-framework-module-service-discovery/mock';
-import servicesModule, { type IApiConfigurator } from '@equinor/fusion-framework-module-services';
-import {
-  telemetryMockModule,
-  type TelemetryMockConfigurator,
-} from '@equinor/fusion-framework-module-telemetry/mock';
-
-import { FrameworkConfigurator } from '../FrameworkConfigurator.js';
-
-/**
- * The real framework configurator, with every built-in module that reaches
- * outside the process backed by a test double, and every other built-in
- * module reachable the same way.
- *
- * @remarks
- * Nothing else changes: the same module set, the same configuration pipeline and
- * the same lifecycle are used. Only the boundaries that would need credentials or
- * network access are substituted, so a test still exercises module wiring,
- * configuration validation and lifecycle hooks.
- *
- * Every built-in module exposes its own configurator as a property, so a test
- * reaches it directly instead of registering a callback to receive it. `http`
- * is the real configurator — fake a response by registering a
- * short-circuiting middleware through `.http.addMiddleware(...)` instead of
- * swapping the module out; see `@equinor/fusion-framework-module-http/mock`'s
- * `createOpenApiMockMiddleware` for faking a whole `@equinor/fusion-openapi-mock`
- * document that way. `services` is not backed by a test double yet either, so
- * calls through its configurator still reach the network — but
- * the configurator itself is reachable the same way `.msal` is, since its
- * `configure` factory takes no `ref` and so loses nothing by being pinned early.
- *
- * `event` is deliberately not pinned: its `configure` factory reads `ref` to
- * wire bubbling to a parent event provider when this configurator is hoisted
- * inside a host framework, and pinning would freeze that decision before a
- * `ref` could ever be known.
- *
- * Because this *is* a `FrameworkConfigurator`, every `enableX` helper an
- * application already uses accepts it unchanged — including the ones an
- * application team writes for their own modules.
- *
- * @typeParam TModules - Module descriptors beyond the built-in set. Supply this
- *   when a test registers application modules, so they are typed on the resulting
- *   instance.
- *
- * @example
- * ```typescript
- * const configurator = new FrameworkMockConfigurator();
- *
- * configurator.msal.setAccount({ name: 'Ada Lovelace' });
- * configurator.serviceDiscovery.setBaseUri('http://localhost:6669');
- *
- * const fusion = await init(configurator);
- * ```
- */
-export class FrameworkMockConfigurator<
-  TModules extends Array<AnyModule> = [],
-> extends FrameworkConfigurator<TModules> {
-  static override readonly className: string = 'FrameworkMockConfigurator';
-
-  // Keyed by module name, so `_getConfig` can look a pinned configurator up
-  // without needing the module descriptor again.
-  #configurators = new Map<string, unknown>();
-
-  /**
-   * Creates a framework configurator backed by the built-in mock modules.
-   */
-  constructor() {
-    super();
-
-    // Pinning up front — rather than waiting for an accessor to be read — is
-    // what replaces the modules `FrameworkConfigurator`'s own constructor
-    // already registered, whether or not a test ever touches the accessor.
-    this._pin(msalMockModule);
-    this._pin(serviceDiscoveryMockModule);
-    this._pin(httpModule);
-    this._pin(servicesModule);
-    this._pin(contextMockModule);
-    this._pin(telemetryMockModule);
-  }
-
-  /**
-   * Pins a module to a single configurator instance for the lifetime of this
-   * configurator, so it can be reached by name through {@link _getConfig}.
-   *
-   * @remarks
-   * The module system otherwise builds a fresh configurator from its own
-   * `configure` factory during the configure phase — too late for a test to
-   * reach, and a new instance on every call besides. This replaces that
-   * factory with one that always returns the same instance, and registers the
-   * result under the module's own name.
-   *
-   * A subclass registering a module supplied through {@link TModules} uses
-   * this the same way `.msal` and `.serviceDiscovery` do, to expose its own
-   * named accessor:
-   *
-   * ```typescript
-   * class MyMockConfigurator extends FrameworkMockConfigurator<[InvoiceModule]> {
-   *   constructor() {
-   *     super();
-   *     this._pin(invoiceMockModule);
-   *   }
-   *
-   *   public get invoices(): InvoiceMockConfigurator {
-   *     return this._getConfig('invoices');
-   *   }
-   * }
-   * ```
-   *
-   * @param module - The module descriptor to pin a configurator for.
-   * @template TModule - The specific module descriptor type being pinned.
-   * @throws {Error} If the module declares no `configure` factory to pin, or
-   *   the factory returns a promise instead of a configurator — pinning is
-   *   synchronous, so a test can reach the accessor immediately.
-   */
-  protected _pin<TModule extends AnyModule>(module: TModule): void {
-    // A module without a configure factory has nothing this method could pin
-    if (!module.configure) {
-      throw new Error(`Cannot pin "${module.name}": it declares no configure factory.`);
-    }
-    const instance = module.configure();
-    // Async factories would make the pinned instance unavailable until the module system
-    // resolves it later, defeating the point of pinning it for immediate synchronous access
-    if (instance instanceof Promise) {
-      throw new Error(
-        `Cannot pin "${module.name}": its configure factory returns a promise, so it cannot be resolved synchronously.`,
-      );
-    }
-    this.#configurators.set(module.name, instance);
-    this.addConfig({ module: { ...module, configure: () => instance } as TModule });
-  }
-
-  /**
-   * Returns the configurator pinned for a module by name.
-   *
-   * @param name - The module's name, as passed to {@link _pin}.
-   * @template TConfig - The specific configurator type expected for this module.
-   * @returns The configurator pinned under `name`.
-   * @throws {Error} If no configurator has been pinned for that name.
-   */
-  protected _getConfig<TConfig>(name: string): TConfig {
-    const config = this.#configurators.get(name);
-    // A missing entry means _pin was never called for this module name
-    if (config === undefined) {
-      throw new Error(
-        `No configurator is pinned for module "${name}" — call this._pin(module) before this._getConfig("${name}").`,
-      );
-    }
-    return config as TConfig;
-  }
-
-  /**
-   * Configures the user the framework signs in.
-   *
-   * @remarks
-   * The same {@link MsalMockConfigurator} the auth module is configured from, so
-   * a change made here is what the module sees.
-   *
-   * @returns The MSAL mock configurator.
-   */
-  public get msal(): MsalMockConfigurator {
-    return this._getConfig<MsalMockConfigurator>(msalMockModule.name);
-  }
-
-  /**
-   * Configures the registry services are resolved from.
-   *
-   * @remarks
-   * The same {@link ServiceDiscoveryMockConfigurator} the service discovery
-   * module is configured from, so a change made here is what the module sees.
-   *
-   * @returns The service discovery mock configurator.
-   */
-  public get serviceDiscovery(): ServiceDiscoveryMockConfigurator {
-    return this._getConfig<ServiceDiscoveryMockConfigurator>(serviceDiscoveryMockModule.name);
-  }
-
-  /**
-   * Configures the HTTP module's named clients.
-   *
-   * @remarks
-   * The same {@link IHttpClientConfigurator} the HTTP module is configured
-   * from — the real one, not a test double. Register a short-circuiting
-   * {@link HttpMiddleware} through `addMiddleware` to answer from that
-   * instead of the network.
-   *
-   * @returns The real HTTP configurator.
-   */
-  public get http(): IHttpClientConfigurator {
-    return this._getConfig<IHttpClientConfigurator>(httpModule.name);
-  }
-
-  /**
-   * Configures the typed API clients the `services` module builds.
-   *
-   * @remarks
-   * The real configurator — `services` has no test double yet.
-   *
-   * @returns The real API configurator.
-   */
-  public get services(): IApiConfigurator {
-    return this._getConfig<IApiConfigurator>(servicesModule.name);
-  }
-
-  /**
-   * Configures context resolution.
-   *
-   * @remarks
-   * The same {@link ContextMockConfigurator} the context module is configured
-   * from, so seeding an item here is what `fusion.modules.context` resolves.
-   *
-   * @returns The context mock configurator.
-   */
-  public get context(): ContextMockConfigurator {
-    return this._getConfig<ContextMockConfigurator>(contextMockModule.name);
-  }
-
-  /**
-   * Configures telemetry.
-   *
-   * @remarks
-   * The same {@link TelemetryMockConfigurator} the telemetry module is
-   * configured from, so a tracked event or measurement can be read back from
-   * its adapter instead of reaching Application Insights.
-   *
-   * @returns The telemetry mock configurator.
-   */
-  public get telemetry(): TelemetryMockConfigurator {
-    return this._getConfig<TelemetryMockConfigurator>(telemetryMockModule.name);
-  }
-
-  /**
-   * Registers a module through its own enabler.
-   *
-   * @remarks
-   * Sugar for calling the enabler directly — `enableMyModuleMock(configurator)`
-   * works just as well, because this class *is* a `FrameworkConfigurator`. Use
-   * whichever reads better at the call site.
-   *
-   * @param configure - Callback receiving this configurator.
-   * @returns This configurator, for chaining.
-   *
-   * @example
-   * ```typescript
-   * configurator.addModule((c) => enableMyModuleMock(c, { total: 42 }));
-   * ```
-   */
-  public addModule(configure: (configurator: this) => void): this {
-    configure(this);
-    return this;
-  }
-}
-
-export default FrameworkMockConfigurator;