@itwin/core-frontend 5.15.0-dev.2 → 5.15.0-dev.20

package/lib/esm/quantity-formatting/QuantityFormatter.js

@@ -10,6 +10,7 @@ import { BasicUnitsProvider, Format, FormatSpecHandle, FormatterSpec, Formatting
 import { FrontendLoggerCategory } from "../common/FrontendLoggerCategory";
 import { IModelApp } from "../IModelApp";
 import { getDefaultAlternateUnitLabels } from "./AlternateUnitLabels";
+import { FormatsProviderReloadCoordinator } from "./FormatsProviderReloadCoordinator";
 // cSpell:ignore FORMATPROPS FORMATKEY ussurvey uscustomary USCUSTOM
 /**
  * Defines standard format types for tools that need to display measurements to user.
@@ -44,7 +45,12 @@ export var QuantityType;
 export class AlternateUnitLabelsRegistry {
     _alternateLabelRegistry = new Map();
     addAlternateLabels(key, ...labels) {
-        [...labels].forEach((value) => this._alternateLabelRegistry.get(key)?.add(value));
+        let entry = this._alternateLabelRegistry.get(key);
+        if (!entry) {
+            entry = new Set();
+            this._alternateLabelRegistry.set(key, entry);
+        }
+        labels.forEach((value) => entry.add(value));
     }
     constructor(defaultAlternates) {
         if (defaultAlternates) {
@@ -194,12 +200,24 @@ export class FormatsProviderManager {
     }
     get formatsProvider() { return this; }
     set formatsProvider(formatsProvider) {
+        this.setFormatsProvider(formatsProvider);
+    }
+    /**
+     * Replaces the underlying formats provider and raises an event indicating that all formats changed.
+     * @param formatsProvider The formats provider to use for subsequent format lookups.
+     * @param impliedUnitSystem The unit system implied by the replacement provider, if any. Not stored here; [[QuantityFormatter]] applies it as the active unit system when handling `onFormatsChanged`.
+     * @internal
+     */
+    setFormatsProvider(formatsProvider, impliedUnitSystem) {
         this._removeProviderListener?.();
         this._formatsProvider = formatsProvider;
         this._removeProviderListener = this._formatsProvider.onFormatsChanged.addListener((args) => {
             this.onFormatsChanged.raiseEvent(args);
         });
-        this.onFormatsChanged.raiseEvent({ formatsChanged: "all" });
+        const args = { formatsChanged: "all" };
+        if (impliedUnitSystem !== undefined)
+            args.impliedUnitSystem = impliedUnitSystem;
+        this.onFormatsChanged.raiseEvent(args);
     }
 }
 /** The QuantityFormatter class provides methods for formatting and parsing quantities. There are a set of standard quantity types
@@ -280,10 +298,13 @@ export class QuantityFormatter {
     _hasEverBeenReady = false;
     _initializedPromise;
     _resolveInitialized;
-    _reloadInFlight = false;
-    _pendingReload;
-    _deferredSystemChangedEmit;
+    _emitSystemChangedOnReady = false;
+    _isDisposed = false;
+    _disposedError = new Error("QuantityFormatter was disposed before the reload completed.");
+    _reloadCoordinator;
     _removeFormatsProviderListener;
+    _activeFormatSpecsTarget;
+    _activeParserSpecsTarget;
     /**
      * constructor
      * @param showMetricOrUnitSystem - Pass in `true` to show Metric formatted quantity values. Defaults to Imperial. To explicitly
@@ -293,6 +314,12 @@ export class QuantityFormatter {
         this._initializedPromise = new Promise((resolve) => {
             this._resolveInitialized = resolve;
         });
+        this._reloadCoordinator = new FormatsProviderReloadCoordinator({
+            startReload: () => { this._isReady = false; },
+            executeReload: async (intent) => this._executeReload(intent),
+            finalizeReload: async () => this.finalizeReload(),
+            handleReloadFailure: (error) => this._handleReloadFailure(error),
+        }, this._disposedError);
         if (undefined !== showMetricOrUnitSystem) {
             if (typeof showMetricOrUnitSystem === "boolean")
                 this._activeUnitSystem = showMetricOrUnitSystem ? "metric" : "imperial";
@@ -301,70 +328,44 @@ export class QuantityFormatter {
         }
     }
     [Symbol.dispose]() {
+        if (this._isDisposed)
+            return;
+        this._isDisposed = true;
+        this._isReady = false;
+        this._emitSystemChangedOnReady = false;
+        this._reloadCoordinator.dispose();
         if (this._removeFormatsProviderListener) {
             this._removeFormatsProviderListener();
             this._removeFormatsProviderListener = undefined;
         }
     }
+    /** Runs an action that schedules a reload and waits for the reload queue to drain.
+     * The most recent call wins. If another call is made before this reload queue drains, this call is rejected.
+     * @internal
+     */
+    async runAndWaitForReload(action) {
+        return this._reloadCoordinator.runAndWaitForReload(action);
+    }
     /** Schedule an async reload. If no reload is in flight, runs immediately. If a reload is
-     * already in flight, stores the intent as pending (latest-wins: only the last scheduled reload
-     * is kept). `finalizeReload()` fires only when the queue is fully drained.
+     * already in flight, stores the intent as pending. Pending format changes are merged and run before
+     * the latest other pending intent. `finalizeReload()` fires only when the queue is fully drained.
      *
      * **Await semantics:** When a reload is already in flight, the returned promise resolves
      * immediately *without* the requested reload having run. Callers that need to know when
-     * the reload has actually completed should listen for `onFormattingReady` instead.
+     * an explicitly triggered reload has actually completed should use [[runAndWaitForReload]].
      *
-     * Reload intents:
-     * - `"full"` — rebuild entire registry + re-register provider listener (onInitialized, setUnitsProvider)
-     * - `"formatsChanged"` — patch registry from provider + load maps (formatsChanged listener)
-     * - `"activeSystem"` — reload format/parsing maps for current unit system (setActiveUnitSystem, reinitializeFormatAndParsingsMaps)
      * @internal
      */
     async scheduleReload(intent) {
-        if (this._reloadInFlight) {
-            // A reload is already running — queue this one (latest-wins)
-            this._pendingReload = intent;
-            return;
+        return this._reloadCoordinator.scheduleReload(intent);
+    }
+    _handleReloadFailure(error) {
+        if (!this._isDisposed)
+            Logger.logError(`${FrontendLoggerCategory.Package}.QuantityFormatter`, BentleyError.getErrorMessage(error));
+        if (this._hasEverBeenReady && !this._isDisposed) {
+            Logger.logWarning(`${FrontendLoggerCategory.Package}.QuantityFormatter`, "Reload failed — restoring previous ready state. Cached specs may be stale.");
+            this._isReady = true;
         }
-        this._reloadInFlight = true;
-        this._isReady = false;
-        this._deferredSystemChangedEmit = undefined; // Clear stale deferred from prior cycle
-        try {
-            await this._executeReload(intent);
-        }
-        catch (err) {
-            Logger.logError(`${FrontendLoggerCategory.Package}.QuantityFormatter`, BentleyError.getErrorMessage(err));
-            this._reloadInFlight = false;
-            // If there's a pending reload, still try to run it
-            if (this._pendingReload) {
-                const next = this._pendingReload;
-                this._pendingReload = undefined;
-                return this.scheduleReload(next);
-            }
-            // Restore prior ready state so stale-but-usable specs remain accessible
-            if (this._hasEverBeenReady) {
-                Logger.logWarning(`${FrontendLoggerCategory.Package}.QuantityFormatter`, "Reload failed — restoring previous ready state. Cached specs may be stale.");
-                this._isReady = true;
-            }
-            return;
-        }
-        // Current reload succeeded — check if another was queued
-        if (this._pendingReload) {
-            const next = this._pendingReload;
-            this._pendingReload = undefined;
-            this._reloadInFlight = false;
-            return this.scheduleReload(next);
-        }
-        // Queue is drained — finalize
-        await this.finalizeReload();
-        // A new reload may have been queued during the async finalizeReload window
-        if (this._pendingReload) {
-            const next = this._pendingReload;
-            this._pendingReload = undefined;
-            this._reloadInFlight = false;
-            return this.scheduleReload(next);
-        }
-        this._reloadInFlight = false;
     }
     /** Execute the reload work for a given intent. All reload logic is centralized here.
      * @internal
@@ -373,47 +374,51 @@ export class QuantityFormatter {
         switch (intent.scope) {
             case "full":
                 await this._reloadCore();
+                return;
+            case "formatsChanged":
+                await this._rebuildRegistryFromProvider(intent.args);
                 break;
-            case "formatsChanged": {
-                const { args } = intent;
-                await this._rebuildRegistryFromProvider(args);
-                if (args.impliedUnitSystem && args.impliedUnitSystem !== this._activeUnitSystem) {
-                    this._activeUnitSystem = args.impliedUnitSystem;
-                }
-                await this.loadFormatAndParsingMapsForSystem(this._activeUnitSystem);
-                if (args.impliedUnitSystem) {
-                    this._deferredSystemChangedEmit = { system: this._activeUnitSystem };
-                }
-                break;
-            }
-            case "activeSystem":
-                await this.loadFormatAndParsingMapsForSystem(this._activeUnitSystem);
-                if (intent.emitSystemChanged) {
-                    this._deferredSystemChangedEmit = { system: this._activeUnitSystem };
-                }
-                break;
         }
+        // Build the active specs in temporary maps so readers keep using complete specs until the new ones are ready.
+        const nextFormatSpecs = new Map();
+        const nextParserSpecs = new Map();
+        this._activeFormatSpecsTarget = nextFormatSpecs;
+        this._activeParserSpecsTarget = nextParserSpecs;
+        try {
+            await this.loadFormatAndParsingMapsForSystem(this._activeUnitSystem);
+        }
+        finally {
+            this._activeFormatSpecsTarget = undefined;
+            this._activeParserSpecsTarget = undefined;
+        }
+        this._activeFormatSpecsByType = nextFormatSpecs;
+        this._activeParserSpecsByType = nextParserSpecs;
     }
     /** Called when the reload queue is fully drained after a successful reload.
      * Sets `isReady` to true, resolves `whenInitialized` (one-shot), and emits ready events.
      * @internal
      */
     async finalizeReload() {
+        if (this._isDisposed)
+            return;
         // Phase 1: Let providers register async work
         const collector = new FormattingReadyCollector();
         this.onBeforeFormattingReady.raiseEvent(collector);
         await collector.awaitAll();
+        if (this._isDisposed)
+            return;
         // Phase 2: Signal ready to consumers
         this._isReady = true;
         this._hasEverBeenReady = true;
         this._resolveInitialized();
         this.onFormattingReady.emit();
-        // Phase 3: Emit deferred unit-system-changed if the winning reload set one.
+        if (this._isDisposed)
+            return;
+        // Phase 3: Emit unit-system-changed if the unit system was changed since the last ready state, reporting the system that is now active.
         // This fires after isReady === true so listeners can safely use the formatter.
-        if (this._deferredSystemChangedEmit) {
-            const args = this._deferredSystemChangedEmit;
-            this._deferredSystemChangedEmit = undefined;
-            this.onActiveFormattingUnitSystemChanged.emit(args);
+        if (this._emitSystemChangedOnReady) {
+            this._emitSystemChangedOnReady = false;
+            this.onActiveFormattingUnitSystemChanged.emit({ system: this._activeUnitSystem });
         }
     }
     getOverrideFormatPropsByQuantityType(quantityTypeKey, unitSystem) {
@@ -484,8 +489,8 @@ export class QuantityFormatter {
     async loadFormatAndParserSpec(quantityTypeDefinition, formatProps) {
         const formatterSpec = await quantityTypeDefinition.generateFormatterSpec(formatProps, this.unitsProvider);
         const parserSpec = await quantityTypeDefinition.generateParserSpec(formatProps, this.unitsProvider, this.alternateUnitLabelsProvider);
-        this._activeFormatSpecsByType.set(quantityTypeDefinition.key, formatterSpec);
-        this._activeParserSpecsByType.set(quantityTypeDefinition.key, parserSpec);
+        (this._activeFormatSpecsTarget ?? this._activeFormatSpecsByType).set(quantityTypeDefinition.key, formatterSpec);
+        (this._activeParserSpecsTarget ?? this._activeParserSpecsByType).set(quantityTypeDefinition.key, parserSpec);
     }
     // repopulate formatSpec and parserSpec entries using only default format
     async loadDefaultFormatAndParserSpecForQuantity(typeKey) {
@@ -542,17 +547,20 @@ export class QuantityFormatter {
      * @internal
      */
     async onInitialized() {
+        // Register once, before the first reload, so provider changes made while a units-provider reload is running are not missed.
+        this._removeFormatsProviderListener ??= IModelApp.formatsProvider.onFormatsChanged.addListener((args) => {
+            if (args.impliedUnitSystem && args.impliedUnitSystem !== this._activeUnitSystem) {
+                this._activeUnitSystem = args.impliedUnitSystem;
+                this._emitSystemChangedOnReady = true;
+            }
+            void this.scheduleReload({ scope: "formatsChanged", args });
+        });
         await this.scheduleReload({ scope: "full" });
     }
     /** Core reload logic — does all async I/O and cache rebuilding without events or state management.
      * @internal
      */
     async _reloadCore() {
-        // Remove any existing listener before re-registering to avoid duplicates when called via setUnitsProvider.
-        if (this._removeFormatsProviderListener) {
-            this._removeFormatsProviderListener();
-            this._removeFormatsProviderListener = undefined;
-        }
         await this.initializeQuantityTypesRegistry();
         const initialKoQs = [["DefaultToolsUnits.LENGTH", "Units.M"], ["DefaultToolsUnits.ANGLE", "Units.RAD"], ["DefaultToolsUnits.AREA", "Units.SQ_M"], ["DefaultToolsUnits.VOLUME", "Units.CUB_M"], ["DefaultToolsUnits.LENGTH_COORDINATE", "Units.M"], ["CivilUnits.STATION", "Units.M"], ["CivilUnits.LENGTH", "Units.M"], ["AecUnits.LENGTH", "Units.M"]];
         for (const entry of initialKoQs) {
@@ -565,10 +573,6 @@ export class QuantityFormatter {
                 }
             }
         }
-        // Register formatsProvider listener that triggers a queued reload when formats change
-        this._removeFormatsProviderListener = IModelApp.formatsProvider.onFormatsChanged.addListener((args) => {
-            void this.scheduleReload({ scope: "formatsChanged", args });
-        });
         // initialize default format and parsing specs
         await this.loadFormatAndParsingMapsForSystem();
     }
@@ -662,6 +666,9 @@ export class QuantityFormatter {
             await IModelApp.quantityFormatter.resetToUseInternalUnitsProvider();
             return;
         }
+        // Disposal can occur while the reload is awaited, so do not notify afterward.
+        if (this._isDisposed)
+            return;
         this.onUnitsProviderChanged.emit();
     }
     /**
@@ -701,7 +708,11 @@ export class QuantityFormatter {
             this._overrideFormatPropsByUnitSystem = overrideFormatPropsByUnitSystem;
         }
         unitSystemKey && (this._activeUnitSystem = unitSystemKey);
-        await this.scheduleReload({ scope: "activeSystem", emitSystemChanged: fireUnitSystemChanged });
+        if (fireUnitSystemChanged)
+            this._emitSystemChangedOnReady = true;
+        await this.scheduleReload({ scope: "activeSystem" });
+        if (this._isDisposed)
+            return;
         IModelApp.toolAdmin && startDefaultTool && await IModelApp.toolAdmin.startDefaultTool();
     }
     /** Set the Active unit system to one of the supported types. This will asynchronously load the formatter and parser specs for the activated system. */
@@ -714,7 +725,10 @@ export class QuantityFormatter {
         if (this._activeUnitSystem === systemType)
             return;
         this._activeUnitSystem = systemType;
-        await this.scheduleReload({ scope: "activeSystem", emitSystemChanged: true });
+        this._emitSystemChangedOnReady = true;
+        await this.scheduleReload({ scope: "activeSystem" });
+        if (this._isDisposed)
+            return;
         // allow settings provider to store the change
         await this._unitFormattingSettingsProvider?.storeUnitSystemSetting({ system: systemType });
         if (IModelApp.toolAdmin && restartActiveTool)
@@ -839,7 +853,7 @@ export class QuantityFormatter {
         const entry = this.quantityTypesRegistry.get(quantityKey);
         if (!entry)
             throw new Error(`Unable to find registered quantity type with key ${quantityKey}`);
-        return entry.generateParserSpec(this.getFormatPropsByQuantityTypeEntryAndSystem(entry, requestedSystem), this.unitsProvider);
+        return entry.generateParserSpec(this.getFormatPropsByQuantityTypeEntryAndSystem(entry, requestedSystem), this.unitsProvider, this.alternateUnitLabelsProvider);
     }
     /** Asynchronous Call to get a ParserSpec for a QuantityType.
      * @param type        One of the built-in quantity types supported.
@@ -987,7 +1001,7 @@ export class QuantityFormatter {
         const { persistenceUnitName, formatProps, formatName } = props;
         const persistenceUnitProps = await this._unitsProvider.findUnitByName(persistenceUnitName);
         const format = await Format.createFromJSON(formatName ?? "temp", this._unitsProvider, formatProps);
-        return ParserSpec.create(format, this._unitsProvider, persistenceUnitProps);
+        return ParserSpec.create(format, this._unitsProvider, persistenceUnitProps, this.alternateUnitLabelsProvider);
     }
     /**
      * @beta