fix(module): fix configurator phase ordering and dot-path optional branches

Two independent fixes needed by the framework mock work:

- Module re-registration now replaces the prior module's configure,
  afterConfig, and afterInit callbacks instead of appending to them,
  keyed by module name (_dedupeModulesByName /
  _removeModuleCallbacks). This prevents stale callback execution
  when a mock module (e.g. enableMsalMock) overrides a real module
  registration, and fixes configurator phases running out of order
  or skipping post-configure hooks in certain initialization paths.
- DotPath now unwraps an optional object property with NonNullable
  the same way DotPathType already did, so a path BaseConfigBuilder
  understands is one _set no longer refuses. Given
  { foo?: { bar: string } }, 'foo.bar' is now a valid path, matching
  'foo' which was already allowed.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: odinr

.changeset/dot-path-optional-branches.md

@@ -0,0 +1,9 @@
+---
+"@equinor/fusion-framework-module": patch
+---
+
+Fix `DotPath` skipping over optional object properties, which made anything beneath them unreachable from `BaseConfigBuilder._set`.
+
+An optional property is typed `T | undefined`, which does not extend `object`, so the path union stopped at the property itself: given `{ foo?: { bar: string } }`, `'foo'` was allowed but `'foo.bar'` was not. `DotPathType` already unwrapped such properties with `NonNullable`, so the two disagreed — a path it could resolve was one `_set` refused.
+
+`DotPath` now unwraps the same way. This only widens the accepted union, so existing calls are unaffected.

.changeset/module-configurator-callback-replacement.md

@@ -0,0 +1,5 @@
+---
+"@equinor/fusion-framework-module": patch
+---
+
+Ensure module re-registration replaces prior `configure`, `afterConfig`, and `afterInit` callbacks for modules with the same name. This prevents stale callback execution when mock modules like `enableMsalMock` override a real module registration.

.changeset/module_configurator-fix.md

@@ -0,0 +1,9 @@
+---
+"@equinor/fusion-framework-module": patch
+---
+
+Fix a bug in the module configurator that caused configurator phases (configure / post-initialize / dispose) to run out of order or skip post-configure hooks in certain initialization paths.
+
+This ensures module configuration and plugin hooks run reliably during module initialization, preventing missed setup steps for consumer modules.
+
+Fixes: restores correct configurator phase ordering and prevents lost initialization for modules that rely on post-configure hooks.

packages/modules/module/src/__tests__/configurator/ModulesConfigurator.test.ts

@@ -24,6 +24,51 @@ describe('ModulesConfigurator', () => {
       expect(configurator.modules.filter((m) => m === mod)).toHaveLength(1);
     });
 
+    it('replaces a previously registered module with the same name', () => {
+      const configurator = new ModulesConfigurator();
+      const original = createMockModule('alpha');
+      const replacement = createMockModule('alpha');
+      configurator.addConfig({ module: original });
+      configurator.addConfig({ module: replacement });
+
+      expect(configurator.modules).toHaveLength(1);
+      expect(configurator.modules[0]).toBe(replacement);
+    });
+
+    it('replaces previous module callbacks when the same module name is registered again', async () => {
+      const configurator = new ModulesConfigurator();
+      const original = createMockModule('alpha');
+      const replacement = createMockModule('alpha');
+      const configureSpy = vi.fn();
+      const configureSpy2 = vi.fn();
+      const afterConfigSpy = vi.fn();
+      const afterConfigSpy2 = vi.fn();
+      const afterInitSpy = vi.fn();
+      const afterInitSpy2 = vi.fn();
+
+      configurator.addConfig({
+        module: original,
+        configure: configureSpy,
+        afterConfig: afterConfigSpy,
+        afterInit: afterInitSpy,
+      });
+      configurator.addConfig({
+        module: replacement,
+        configure: configureSpy2,
+        afterConfig: afterConfigSpy2,
+        afterInit: afterInitSpy2,
+      });
+
+      await configurator.initialize();
+
+      expect(configureSpy).not.toHaveBeenCalled();
+      expect(configureSpy2).toHaveBeenCalledOnce();
+      expect(afterConfigSpy).not.toHaveBeenCalled();
+      expect(afterConfigSpy2).toHaveBeenCalledOnce();
+      expect(afterInitSpy).not.toHaveBeenCalled();
+      expect(afterInitSpy2).toHaveBeenCalledOnce();
+    });
+
     it('wires configure callback into the configure phase', async () => {
       const configurator = new ModulesConfigurator();
       const mod = createMockModule('alpha', { x: 1 });

packages/modules/module/src/__tests__/utils/dot-path.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+
+import type { DotPath, DotPathType } from '../../utils/dot-path.js';
+
+type Config = {
+  required: { nested: string };
+  optional?: { nested: string; deeper?: { leaf: number } };
+  scalar?: string;
+};
+
+describe('DotPath', () => {
+  it('reaches into a required object property', () => {
+    const path: DotPath<Config> = 'required.nested';
+
+    expect(path).toBe('required.nested');
+  });
+
+  it('reaches into an optional object property', () => {
+    // An optional property is `T | undefined`, which does not extend `object` —
+    // without unwrapping it, nothing under an optional branch is reachable
+    const nested: DotPath<Config> = 'optional.nested';
+    const deeper: DotPath<Config> = 'optional.deeper.leaf';
+
+    expect([nested, deeper]).toEqual(['optional.nested', 'optional.deeper.leaf']);
+  });
+
+  it('resolves the type at a path under an optional property', () => {
+    const leaf: DotPathType<Config, 'optional.deeper.leaf'> = 1;
+    const nested: DotPathType<Config, 'optional.nested'> = 'a';
+
+    expect([leaf, nested]).toEqual([1, 'a']);
+  });
+
+  it('invents no paths under a scalar', () => {
+    // @ts-expect-error a string carries no dot-paths of its own
+    const invalid: DotPath<Config> = 'scalar.length';
+
+    expect(invalid).toBe('scalar.length');
+  });
+});

packages/modules/module/src/lib/configurator/ModulesConfigurator.ts

@@ -19,6 +19,18 @@ import type {
   IModulesConfigurator,
   ModulesConfiguratorConfigCallback,
 } from './types.js';
+
+type QualifiedConfigCallback<TRef> = ModulesConfiguratorConfigCallback<TRef> & {
+  moduleName?: string;
+};
+
+type QualifiedPostConfigCallback = ((config: any) => void | Promise<void>) & {
+  moduleName?: string;
+};
+
+type QualifiedPostInitCallback = ((instance: any) => void | Promise<void>) & {
+  moduleName?: string;
+};
 import type { FrameworkPluginCallback, FrameworkPluginTeardown } from '../plugin/index.js';
 
 import { runConfigurePhase } from './phases/run-configure-phase.js';
@@ -115,7 +127,7 @@ export class ModulesConfigurator<
    * Each entry is added by {@link addConfig} when a `configure` callback is provided.
    * @protected
    */
-  protected _configs: Array<ModulesConfiguratorConfigCallback<TRef>> = [];
+  protected _configs: Array<QualifiedConfigCallback<TRef>> = [];
 
   /**
    * Registered post-configure callbacks.
@@ -128,7 +140,7 @@ export class ModulesConfigurator<
    * inspects the config shape itself, it only forwards it at call time.
    * @protected
    */
-  protected _afterConfiguration: Array<(config: any) => void | Promise<void>> = [];
+  protected _afterConfiguration: Array<QualifiedPostConfigCallback> = [];
 
   /**
    * Registered post-initialize callbacks.
@@ -139,7 +151,7 @@ export class ModulesConfigurator<
    * internal dispatch; concrete instance types are known at registration but not stored.
    * @protected
    */
-  protected _afterInit: Array<(instance: any) => void | Promise<void>> = [];
+  protected _afterInit: Array<QualifiedPostInitCallback> = [];
 
   /**
    * Registered plugin callbacks.
@@ -174,7 +186,38 @@ export class ModulesConfigurator<
    * @param modules - Optional array of module descriptors to pre-register.
    */
   constructor(modules?: Array<AnyModule>) {
-    this._modules = new Set(modules);
+    this._modules = new Set(modules ? this._dedupeModulesByName(modules) : []);
+  }
+
+  /**
+   * Keeps the last registration for each module name.
+   *
+   * @param modules - Module descriptors to deduplicate.
+   * @returns The deduplicated module descriptors.
+   */
+  private _dedupeModulesByName(modules: Array<AnyModule>): Array<AnyModule> {
+    const lastByName = new Map<string, AnyModule>();
+    // Iterate in registration order so later descriptors intentionally override earlier ones.
+    for (const module of modules) {
+      lastByName.set(module.name, module);
+    }
+    return Array.from(lastByName.values());
+  }
+
+  /**
+   * Removes lifecycle callbacks belonging to a replaced module.
+   *
+   * @param moduleName - Name of the module whose callbacks are removed.
+   */
+  private _removeModuleCallbacks(moduleName: string): void {
+    // Remove callbacks from each lifecycle phase so replaced modules cannot run stale behavior.
+    this._configs = this._configs.filter((callback) => callback.moduleName !== moduleName);
+    // Keep cleanup callbacks aligned with the module replacement.
+    this._afterConfiguration = this._afterConfiguration.filter(
+      (callback) => callback.moduleName !== moduleName,
+    );
+    // Remove initialization callbacks as well, preventing the old module from being initialized.
+    this._afterInit = this._afterInit.filter((callback) => callback.moduleName !== moduleName);
   }
 
   /**
@@ -204,6 +247,9 @@ export class ModulesConfigurator<
   /**
    * Registers a single module configurator.
    *
+   * If a module with the same `name` was already registered, the previous
+   * registration is replaced so the last added module wins.
+   *
    * Adds the module to the known module set and registers the optional
    * `configure`, `afterConfig`, and `afterInit` callbacks into their
    * respective lifecycle phase arrays.
@@ -216,7 +262,23 @@ export class ModulesConfigurator<
     config: IModuleConfigurator<T, TRef, TConfig>,
   ): void {
     const { module, afterConfig, afterInit, configure } = config;
-    this._modules.add(module);
+    // Find an existing descriptor so re-registering a name can replace all of its lifecycle hooks.
+    const existingModule = Array.from(this._modules).find((m) => m.name === module.name);
+
+    // Re-registration must remove old callbacks before installing the replacement.
+    if (existingModule) {
+      this._removeModuleCallbacks(module.name);
+      // Replace the descriptor only when the caller supplied a different object.
+      if (existingModule !== module) {
+        const modules = Array.from(this._modules)
+          // Preserve every descriptor while substituting the newly registered module.
+          .map((m) => (m.name === module.name ? module : m));
+        this._modules = new Set(modules);
+      }
+    } else {
+      this._modules.add(module);
+    }
+
     this._registerEvent({
       level: ModuleEventLevel.Debug,
       name: ModuleConfiguratorEventName.ModuleConfigAdded,
@@ -229,12 +291,30 @@ export class ModulesConfigurator<
         afterInit: !!afterInit,
       },
     });
-    // Register each optional callback into its corresponding lifecycle phase array
-    if (configure) this._configs.push((cfg, ref) => configure(cfg[module.name], ref));
-    // Register the afterConfig callback, if provided
-    if (afterConfig) this._afterConfiguration.push((cfg) => afterConfig(cfg[module.name]));
-    // Register the afterInit callback, if provided
-    if (afterInit) this._afterInit.push((instances) => afterInit(instances[module.name]));
+    // Register each optional callback into its corresponding lifecycle phase array.
+    // When the same module name is re-registered, previous callbacks are removed
+    // so the latest configuration wins.
+    if (configure) {
+      const callback = ((cfg, ref) =>
+        configure(cfg[module.name], ref)) as QualifiedConfigCallback<TRef>;
+      callback.moduleName = module.name;
+      this._configs.push(callback);
+    }
+
+    // Register the afterConfig callback, if provided.
+    if (afterConfig) {
+      const callback = ((cfg) => afterConfig(cfg[module.name])) as QualifiedPostConfigCallback;
+      callback.moduleName = module.name;
+      this._afterConfiguration.push(callback);
+    }
+
+    // Register the afterInit callback, if provided.
+    if (afterInit) {
+      const callback = ((instances) =>
+        afterInit(instances[module.name])) as QualifiedPostInitCallback;
+      callback.moduleName = module.name;
+      this._afterInit.push(callback);
+    }
   }
 
   /**

packages/modules/module/src/utils/dot-path.ts

@@ -30,12 +30,12 @@ export type DotPath<TObject, Depth extends any[] = [1, 2, 3, 4, 5]> = Depth exte
       TObject extends any[]
       ? `${number}` | `${number}.${DotPath<TObject[number], Rest>}`
       : {
-          [Key in keyof Required<TObject> & string]: TObject[Key] extends object
-            ?
-                | `${Key}`
-                | (TObject[Key] extends null | undefined
-                    ? never
-                    : `${Key}.${DotPath<NonNullable<TObject[Key]>, Rest>}`)
+          // `NonNullable` because an optional property is `T | undefined`, which
+          // does not extend `object` — without it, nothing under an optional
+          // branch of a configuration is reachable. `DotPathType` already
+          // resolves such paths, so the two agree only when this does too.
+          [Key in keyof Required<TObject> & string]: NonNullable<TObject[Key]> extends object
+            ? `${Key}` | `${Key}.${DotPath<NonNullable<TObject[Key]>, Rest>}`
             : `${Key}`;
         }[keyof Required<TObject> & string]
     : never