@itwin/core-quantity 5.9.0-dev.9 → 5.10.0-dev.3

package/lib/cjs/core-quantity.d.ts

@@ -1,5 +1,6 @@
 export * from "./Constants";
 export * from "./Exception";
+export * from "./FormatSpecHandle";
 export * from "./Interfaces";
 export * from "./Parser";
 export * from "./ParserSpec";
@@ -9,12 +10,32 @@ export * from "./Formatter/Format";
 export * from "./Formatter/FormatterSpec";
 export * from "./Formatter/FormatEnums";
 export * from "./Formatter/Formatter";
+export * from "./Formatter/FormattingReadyCollector";
 export * from "./Formatter/Interfaces";
+export * from "./QuantityLoggerCategory";
+export * from "./UnitConversion/UnitConversion";
+export * from "./UnitConversion/UnitDefinitionResolver";
+export * from "./SerializedUnitSchema";
+export { BasicUnitsProvider } from "./BasicUnitsProvider";
+export * from "./CompositeUnitsProvider";
+export * from "./internal/cross-package";
 /** @docs-package-description
- * The core-quantity package always runs in a web browser. It contains classes, interfaces, and definitions for formatting and parsing quantity values.
+ * The core-quantity package contains classes, interfaces, and definitions for formatting and parsing quantity values.
  */
 /**
  * @docs-group-description Quantity
  * Classes, Interfaces, and definitions used to format and parse quantity values.
  */
+/**
+ * @docs-group-description BasicUnitsProvider
+ * A UnitsProvider backed by the bundled BIS Units schema JSON asset.
+ */
+/**
+ * @docs-group-description CompositeUnitsProvider
+ * Factory and composition utilities for layering multiple UnitsProviders.
+ */
+/**
+ * @docs-group-description Logging
+ * Logger categories used by this package.
+ */
 //# sourceMappingURL=core-quantity.d.ts.map

package/lib/cjs/core-quantity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core-quantity.d.ts","sourceRoot":"","sources":["../../src/core-quantity.ts"],"names":[],"mappings":"AAIA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,QAAQ,CAAC;AAEvB,cAAc,oBAAoB,CAAC;AACnC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AAEvC;;GAEG;AAEH;;;GAGG"}
+{"version":3,"file":"core-quantity.d.ts","sourceRoot":"","sources":["../../src/core-quantity.ts"],"names":[],"mappings":"AAIA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,QAAQ,CAAC;AACvB,cAAc,oBAAoB,CAAC;AACnC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sCAAsC,CAAC;AACrD,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AAEzC,cAAc,iCAAiC,CAAC;AAChD,cAAc,yCAAyC,CAAC;AACxD,cAAc,wBAAwB,CAAC;AACvC,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AAEzC;;GAEG;AAEH;;;GAGG;AACH;;;GAGG;AACH;;;GAGG;AACH;;;GAGG"}

package/lib/cjs/core-quantity.js

@@ -14,12 +14,14 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.BasicUnitsProvider = void 0;
 /*---------------------------------------------------------------------------------------------
 * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
 * See LICENSE.md in the project root for license terms and full copyright notice.
 *--------------------------------------------------------------------------------------------*/
 __exportStar(require("./Constants"), exports);
 __exportStar(require("./Exception"), exports);
+__exportStar(require("./FormatSpecHandle"), exports);
 __exportStar(require("./Interfaces"), exports);
 __exportStar(require("./Parser"), exports);
 __exportStar(require("./ParserSpec"), exports);
@@ -29,12 +31,33 @@ __exportStar(require("./Formatter/Format"), exports);
 __exportStar(require("./Formatter/FormatterSpec"), exports);
 __exportStar(require("./Formatter/FormatEnums"), exports);
 __exportStar(require("./Formatter/Formatter"), exports);
+__exportStar(require("./Formatter/FormattingReadyCollector"), exports);
 __exportStar(require("./Formatter/Interfaces"), exports);
+__exportStar(require("./QuantityLoggerCategory"), exports);
+__exportStar(require("./UnitConversion/UnitConversion"), exports);
+__exportStar(require("./UnitConversion/UnitDefinitionResolver"), exports);
+__exportStar(require("./SerializedUnitSchema"), exports);
+var BasicUnitsProvider_1 = require("./BasicUnitsProvider");
+Object.defineProperty(exports, "BasicUnitsProvider", { enumerable: true, get: function () { return BasicUnitsProvider_1.BasicUnitsProvider; } });
+__exportStar(require("./CompositeUnitsProvider"), exports);
+__exportStar(require("./internal/cross-package"), exports);
 /** @docs-package-description
- * The core-quantity package always runs in a web browser. It contains classes, interfaces, and definitions for formatting and parsing quantity values.
+ * The core-quantity package contains classes, interfaces, and definitions for formatting and parsing quantity values.
  */
 /**
  * @docs-group-description Quantity
  * Classes, Interfaces, and definitions used to format and parse quantity values.
  */
+/**
+ * @docs-group-description BasicUnitsProvider
+ * A UnitsProvider backed by the bundled BIS Units schema JSON asset.
+ */
+/**
+ * @docs-group-description CompositeUnitsProvider
+ * Factory and composition utilities for layering multiple UnitsProviders.
+ */
+/**
+ * @docs-group-description Logging
+ * Logger categories used by this package.
+ */
 //# sourceMappingURL=core-quantity.js.map

package/lib/cjs/core-quantity.js.map

@@ -1 +1 @@
-{"version":3,"file":"core-quantity.js","sourceRoot":"","sources":["../../src/core-quantity.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;+FAG+F;AAC/F,8CAA4B;AAC5B,8CAA4B;AAC5B,+CAA6B;AAC7B,2CAAyB;AACzB,+CAA6B;AAC7B,6CAA2B;AAC3B,yCAAuB;AAEvB,qDAAmC;AACnC,4DAA0C;AAC1C,0DAAwC;AACxC,wDAAsC;AACtC,yDAAuC;AAEvC;;GAEG;AAEH;;;GAGG","sourcesContent":["/*---------------------------------------------------------------------------------------------\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n* See LICENSE.md in the project root for license terms and full copyright notice.\n*--------------------------------------------------------------------------------------------*/\nexport * from \"./Constants\";\nexport * from \"./Exception\";\nexport * from \"./Interfaces\";\nexport * from \"./Parser\";\nexport * from \"./ParserSpec\";\nexport * from \"./Quantity\";\nexport * from \"./Unit\";\n\nexport * from \"./Formatter/Format\";\nexport * from \"./Formatter/FormatterSpec\";\nexport * from \"./Formatter/FormatEnums\";\nexport * from \"./Formatter/Formatter\";\nexport * from \"./Formatter/Interfaces\";\n\n/** @docs-package-description\n * The core-quantity package always runs in a web browser. It contains classes, interfaces, and definitions for formatting and parsing quantity values.\n */\n\n/**\n * @docs-group-description Quantity\n * Classes, Interfaces, and definitions used to format and parse quantity values.\n */\n"]}
+{"version":3,"file":"core-quantity.js","sourceRoot":"","sources":["../../src/core-quantity.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA;;;+FAG+F;AAC/F,8CAA4B;AAC5B,8CAA4B;AAC5B,qDAAmC;AACnC,+CAA6B;AAC7B,2CAAyB;AACzB,+CAA6B;AAC7B,6CAA2B;AAC3B,yCAAuB;AACvB,qDAAmC;AACnC,4DAA0C;AAC1C,0DAAwC;AACxC,wDAAsC;AACtC,uEAAqD;AACrD,yDAAuC;AACvC,2DAAyC;AAEzC,kEAAgD;AAChD,0EAAwD;AACxD,yDAAuC;AACvC,2DAA0D;AAAjD,wHAAA,kBAAkB,OAAA;AAC3B,2DAAyC;AACzC,2DAAyC;AAEzC;;GAEG;AAEH;;;GAGG;AACH;;;GAGG;AACH;;;GAGG;AACH;;;GAGG","sourcesContent":["/*---------------------------------------------------------------------------------------------\r\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\r\n* See LICENSE.md in the project root for license terms and full copyright notice.\r\n*--------------------------------------------------------------------------------------------*/\r\nexport * from \"./Constants\";\r\nexport * from \"./Exception\";\r\nexport * from \"./FormatSpecHandle\";\r\nexport * from \"./Interfaces\";\r\nexport * from \"./Parser\";\r\nexport * from \"./ParserSpec\";\r\nexport * from \"./Quantity\";\r\nexport * from \"./Unit\";\r\nexport * from \"./Formatter/Format\";\r\nexport * from \"./Formatter/FormatterSpec\";\r\nexport * from \"./Formatter/FormatEnums\";\r\nexport * from \"./Formatter/Formatter\";\r\nexport * from \"./Formatter/FormattingReadyCollector\";\r\nexport * from \"./Formatter/Interfaces\";\r\nexport * from \"./QuantityLoggerCategory\";\r\n\r\nexport * from \"./UnitConversion/UnitConversion\";\r\nexport * from \"./UnitConversion/UnitDefinitionResolver\";\r\nexport * from \"./SerializedUnitSchema\";\r\nexport { BasicUnitsProvider } from \"./BasicUnitsProvider\";\r\nexport * from \"./CompositeUnitsProvider\";\r\nexport * from \"./internal/cross-package\";\r\n\r\n/** @docs-package-description\r\n * The core-quantity package contains classes, interfaces, and definitions for formatting and parsing quantity values.\r\n */\r\n\r\n/**\r\n * @docs-group-description Quantity\r\n * Classes, Interfaces, and definitions used to format and parse quantity values.\r\n */\r\n/**\r\n * @docs-group-description BasicUnitsProvider\r\n * A UnitsProvider backed by the bundled BIS Units schema JSON asset.\r\n */\r\n/**\r\n * @docs-group-description CompositeUnitsProvider\r\n * Factory and composition utilities for layering multiple UnitsProviders.\r\n */\r\n/**\r\n * @docs-group-description Logging\r\n * Logger categories used by this package.\r\n */\r\n"]}

package/lib/cjs/internal/cross-package.d.ts

@@ -0,0 +1,4 @@
+export { UnitConversionGraph } from "../UnitConversion/Graph";
+export { parseDefinition } from "../UnitConversion/Parser";
+export type { DefinitionFragment } from "../UnitConversion/Parser";
+//# sourceMappingURL=cross-package.d.ts.map

package/lib/cjs/internal/cross-package.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-package.d.ts","sourceRoot":"","sources":["../../../src/internal/cross-package.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,YAAY,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC"}

package/lib/cjs/internal/cross-package.js

@@ -0,0 +1,13 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDefinition = exports.UnitConversionGraph = void 0;
+// Used by ecschema-metadata (UnitTree.ts)
+var Graph_1 = require("../UnitConversion/Graph");
+Object.defineProperty(exports, "UnitConversionGraph", { enumerable: true, get: function () { return Graph_1.UnitConversionGraph; } });
+var Parser_1 = require("../UnitConversion/Parser");
+Object.defineProperty(exports, "parseDefinition", { enumerable: true, get: function () { return Parser_1.parseDefinition; } });
+//# sourceMappingURL=cross-package.js.map

package/lib/cjs/internal/cross-package.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-package.js","sourceRoot":"","sources":["../../../src/internal/cross-package.ts"],"names":[],"mappings":";AAAA;;;+FAG+F;;;AAE/F,0CAA0C;AAC1C,iDAA8D;AAArD,4GAAA,mBAAmB,OAAA;AAC5B,mDAA2D;AAAlD,yGAAA,eAAe,OAAA","sourcesContent":["/*---------------------------------------------------------------------------------------------\r\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\r\n* See LICENSE.md in the project root for license terms and full copyright notice.\r\n*--------------------------------------------------------------------------------------------*/\r\n\r\n// Used by ecschema-metadata (UnitTree.ts)\r\nexport { UnitConversionGraph } from \"../UnitConversion/Graph\";\r\nexport { parseDefinition } from \"../UnitConversion/Parser\";\r\nexport type { DefinitionFragment } from \"../UnitConversion/Parser\";\r\n"]}

package/lib/esm/BasicUnitsProvider.d.ts

@@ -0,0 +1,44 @@
+import { type UnitConversionProps, type UnitProps, type UnitsProvider } from "./Interfaces";
+/** @internal — test use only. Resets the module-level lazy cache. */
+export declare function _testResetUnitsCache(): void;
+/**
+ * A `UnitsProvider` backed by the full BIS `Units.ecschema.json` bundled as a JSON asset.
+ *
+ * The ~90 KB bundled JSON is loaded lazily via dynamic `import()` on the first provider method
+ * call and cached at module scope — construction is essentially free, and multiple instances
+ * share the same immutable lookup indexes.
+ *
+ * This is the zero-dependency default for backends, tools, and any frontend that doesn't need
+ * iModel overrides. Equivalent to calling `createUnitsProvider()` with no arguments.
+ *
+ * @see createUnitsProvider for layering schema-defined units on top of basic BIS units.
+ * @beta
+ */
+export declare class BasicUnitsProvider implements UnitsProvider {
+    /** Find a unit by its display label, optionally filtering by schema name, phenomenon, and unit system.
+     * @param unitLabel - The display label to search for (case-insensitive).
+     * @param schemaName - Optional schema name filter. Returns `BadUnit` if provided and not `"Units"`.
+     * @param phenomenon - Optional phenomenon filter (e.g. `"Units.LENGTH"`).
+     * @param unitSystem - Optional unit system filter (e.g. `"Units.METRIC"`).
+     * @returns The matching `UnitProps`, or a `BadUnit` if no match is found.
+     */
+    findUnit(unitLabel: string, schemaName?: string, phenomenon?: string, unitSystem?: string): Promise<UnitProps>;
+    /** Return all units belonging to the given phenomenon (unit family).
+     * @param phenomenon - The phenomenon full name (e.g. `"Units.LENGTH"`).
+     * @returns An array of matching `UnitProps`, or an empty array if none.
+     */
+    getUnitsByFamily(phenomenon: string): Promise<UnitProps[]>;
+    /** Find a unit by its fully-qualified name (e.g. `"Units.M"`).
+     * @param unitName - The qualified unit name.
+     * @returns The matching `UnitProps`, or a `BadUnit` if not found.
+     */
+    findUnitByName(unitName: string): Promise<UnitProps>;
+    /** Compute the conversion factors from `fromUnit` to `toUnit`.
+     * Handles normal units, inverted units, and mixed (inverted ↔ non-inverted) conversions.
+     * @param fromUnit - The source unit.
+     * @param toUnit - The target unit.
+     * @returns A `UnitConversionProps` with `factor`, `offset`, and optionally `inversion` and `error`.
+     */
+    getConversion(fromUnit: UnitProps, toUnit: UnitProps): Promise<UnitConversionProps>;
+}
+//# sourceMappingURL=BasicUnitsProvider.d.ts.map

package/lib/esm/BasicUnitsProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BasicUnitsProvider.d.ts","sourceRoot":"","sources":["../../src/BasicUnitsProvider.ts"],"names":[],"mappings":"AAIA,OAAO,EAAwB,KAAK,mBAAmB,EAAE,KAAK,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAgDlH,qEAAqE;AACrE,wBAAgB,oBAAoB,IAAI,IAAI,CAG3C;AAsFD;;;;;;;;;;;;GAYG;AACH,qBAAa,kBAAmB,YAAW,aAAa;IAItD;;;;;;OAMG;IACU,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAuB3H;;;OAGG;IACU,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAMvE;;;OAGG;IACU,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAMjE;;;;;OAKG;IACU,aAAa,CAAC,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,mBAAmB,CAAC;CAkDjG"}

package/lib/esm/BasicUnitsProvider.js

@@ -0,0 +1,213 @@
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+import { UnitConversionInvert } from "./Interfaces";
+import { UnitDefinitionResolver } from "./UnitConversion/UnitDefinitionResolver";
+import { qualifyItemName } from "./UnitConversion/nameUtils";
+import { BadUnit } from "./Unit";
+// Module-level cache: the unit data is derived deterministically from the bundled Units.json
+// asset, so the resolved indexes are effectively an immutable constant. Caching at module
+// scope avoids redundant work when multiple BasicUnitsProvider instances are created (e.g.
+// in tests or when composed inside CompositeUnitsProvider).
+// The JSON is loaded lazily via dynamic import() on first use, keeping the module footprint
+// near-zero until a provider method is actually called.
+let _resolvePromise;
+let _permanentError;
+async function resolveState() {
+    if (_permanentError !== undefined) {
+        throw _permanentError;
+    }
+    if (!_resolvePromise) {
+        _resolvePromise = _buildState().catch((err) => {
+            _permanentError = err instanceof Error ? err : new Error(String(err));
+            _resolvePromise = undefined;
+            throw _permanentError;
+        });
+    }
+    return _resolvePromise;
+}
+/** @internal — test use only. Resets the module-level lazy cache. */
+export function _testResetUnitsCache() {
+    _resolvePromise = undefined;
+    _permanentError = undefined;
+}
+async function _buildState() {
+    const { default: schema } = await import("./assets/Units.json");
+    const nameMap = new Map();
+    const labelMap = new Map();
+    const phenomenonMap = new Map();
+    const invertedUnits = new Map();
+    const s = schema;
+    const resolver = new UnitDefinitionResolver(s);
+    const resolved = resolver.resolveAll();
+    for (const [name, entry] of resolved) {
+        const item = s.items[name];
+        const phenomenon = item.phenomenon;
+        const unitSystem = item.unitSystem;
+        const fullName = `${s.name}.${name}`;
+        const props = {
+            name: fullName,
+            label: entry.label,
+            phenomenon,
+            isValid: true,
+            system: unitSystem,
+        };
+        const indexed = { props, resolved: entry };
+        nameMap.set(fullName, indexed);
+        const lowerLabel = entry.label.toLowerCase();
+        const byLabel = labelMap.get(lowerLabel) ?? [];
+        byLabel.push(indexed);
+        labelMap.set(lowerLabel, byLabel);
+        const byPhen = phenomenonMap.get(phenomenon) ?? [];
+        byPhen.push(indexed);
+        phenomenonMap.set(phenomenon, byPhen);
+    }
+    // Handle InvertedUnit items — must run after nameMap is fully populated above because
+    // invertedSource lookup requires the inverted unit's target to already be in nameMap.
+    for (const [name, item] of Object.entries(s.items)) {
+        if (item.schemaItemType !== "InvertedUnit") {
+            continue;
+        }
+        const inv = item;
+        const fullName = `${s.name}.${name}`;
+        const invertsName = qualifyItemName(inv.invertsUnit, s.name);
+        const unitSystem = inv.unitSystem;
+        const invertedSource = nameMap.get(invertsName);
+        const phenomenon = invertedSource?.props.phenomenon ?? "";
+        const props = {
+            name: fullName,
+            label: inv.label ?? name,
+            phenomenon,
+            isValid: true,
+            system: unitSystem,
+        };
+        invertedUnits.set(fullName, { props, invertsUnitName: invertsName });
+        if (invertedSource) {
+            const indexed = {
+                props,
+                resolved: { ...invertedSource.resolved, name: fullName, label: props.label, unitSystem },
+            };
+            nameMap.set(fullName, indexed);
+            const lowerLabel = props.label.toLowerCase();
+            const byLabel = labelMap.get(lowerLabel) ?? [];
+            byLabel.push(indexed);
+            labelMap.set(lowerLabel, byLabel);
+            const byPhen = phenomenonMap.get(phenomenon) ?? [];
+            byPhen.push(indexed);
+            phenomenonMap.set(phenomenon, byPhen);
+        }
+    }
+    return { nameMap, labelMap, phenomenonMap, invertedUnits, schemaName: s.name };
+}
+/**
+ * A `UnitsProvider` backed by the full BIS `Units.ecschema.json` bundled as a JSON asset.
+ *
+ * The ~90 KB bundled JSON is loaded lazily via dynamic `import()` on the first provider method
+ * call and cached at module scope — construction is essentially free, and multiple instances
+ * share the same immutable lookup indexes.
+ *
+ * This is the zero-dependency default for backends, tools, and any frontend that doesn't need
+ * iModel overrides. Equivalent to calling `createUnitsProvider()` with no arguments.
+ *
+ * @see createUnitsProvider for layering schema-defined units on top of basic BIS units.
+ * @beta
+ */
+export class BasicUnitsProvider {
+    // ── UnitsProvider implementation ─────────────────────────────────────
+    /** Find a unit by its display label, optionally filtering by schema name, phenomenon, and unit system.
+     * @param unitLabel - The display label to search for (case-insensitive).
+     * @param schemaName - Optional schema name filter. Returns `BadUnit` if provided and not `"Units"`.
+     * @param phenomenon - Optional phenomenon filter (e.g. `"Units.LENGTH"`).
+     * @param unitSystem - Optional unit system filter (e.g. `"Units.METRIC"`).
+     * @returns The matching `UnitProps`, or a `BadUnit` if no match is found.
+     */
+    async findUnit(unitLabel, schemaName, phenomenon, unitSystem) {
+        const state = await resolveState();
+        if (schemaName && schemaName !== state.schemaName) {
+            return new BadUnit();
+        }
+        const candidates = state.labelMap.get(unitLabel.toLowerCase());
+        if (!candidates || candidates.length === 0) {
+            return new BadUnit();
+        }
+        for (const c of candidates) {
+            if (phenomenon && c.props.phenomenon !== phenomenon) {
+                continue;
+            }
+            if (unitSystem && c.props.system !== unitSystem) {
+                continue;
+            }
+            return c.props;
+        }
+        return new BadUnit();
+    }
+    /** Return all units belonging to the given phenomenon (unit family).
+     * @param phenomenon - The phenomenon full name (e.g. `"Units.LENGTH"`).
+     * @returns An array of matching `UnitProps`, or an empty array if none.
+     */
+    async getUnitsByFamily(phenomenon) {
+        const state = await resolveState();
+        const entries = state.phenomenonMap.get(phenomenon);
+        return entries ? entries.map((e) => e.props) : [];
+    }
+    /** Find a unit by its fully-qualified name (e.g. `"Units.M"`).
+     * @param unitName - The qualified unit name.
+     * @returns The matching `UnitProps`, or a `BadUnit` if not found.
+     */
+    async findUnitByName(unitName) {
+        const state = await resolveState();
+        const entry = state.nameMap.get(unitName);
+        return entry ? entry.props : new BadUnit();
+    }
+    /** Compute the conversion factors from `fromUnit` to `toUnit`.
+     * Handles normal units, inverted units, and mixed (inverted ↔ non-inverted) conversions.
+     * @param fromUnit - The source unit.
+     * @param toUnit - The target unit.
+     * @returns A `UnitConversionProps` with `factor`, `offset`, and optionally `inversion` and `error`.
+     */
+    async getConversion(fromUnit, toUnit) {
+        const state = await resolveState();
+        const from = state.nameMap.get(fromUnit.name);
+        const to = state.nameMap.get(toUnit.name);
+        if (!from || !to) {
+            return { factor: 1.0, offset: 0.0, error: true };
+        }
+        const fromInverted = state.invertedUnits.get(fromUnit.name);
+        const toInverted = state.invertedUnits.get(toUnit.name);
+        const fromPhenomenon = fromInverted
+            ? state.nameMap.get(fromInverted.invertsUnitName)?.props.phenomenon
+            : from.props.phenomenon;
+        const toPhenomenon = toInverted
+            ? state.nameMap.get(toInverted.invertsUnitName)?.props.phenomenon
+            : to.props.phenomenon;
+        if (fromPhenomenon !== toPhenomenon) {
+            return { factor: 1.0, offset: 0.0, error: true };
+        }
+        if (fromInverted && toInverted) {
+            const innerFrom = state.nameMap.get(fromInverted.invertsUnitName);
+            const innerTo = state.nameMap.get(toInverted.invertsUnitName);
+            if (innerFrom && innerTo) {
+                const c = innerFrom.resolved.conversion.inverse().compose(innerTo.resolved.conversion);
+                return { factor: c.factor, offset: c.offset };
+            }
+        }
+        if (fromInverted) {
+            const innerFrom = state.nameMap.get(fromInverted.invertsUnitName);
+            if (innerFrom) {
+                const c = innerFrom.resolved.conversion.inverse().compose(to.resolved.conversion);
+                return { factor: c.factor, offset: c.offset, inversion: UnitConversionInvert.InvertPreConversion };
+            }
+        }
+        if (toInverted) {
+            const innerTo = state.nameMap.get(toInverted.invertsUnitName);
+            if (innerTo) {
+                const c = from.resolved.conversion.inverse().compose(innerTo.resolved.conversion);
+                return { factor: c.factor, offset: c.offset, inversion: UnitConversionInvert.InvertPostConversion };
+            }
+        }
+        const conv = from.resolved.conversion.inverse().compose(to.resolved.conversion);
+        return { factor: conv.factor, offset: conv.offset };
+    }
+}
+//# sourceMappingURL=BasicUnitsProvider.js.map

package/lib/esm/BasicUnitsProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BasicUnitsProvider.js","sourceRoot":"","sources":["../../src/BasicUnitsProvider.ts"],"names":[],"mappings":"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","sourcesContent":["/*---------------------------------------------------------------------------------------------\r\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\r\n* See LICENSE.md in the project root for license terms and full copyright notice.\r\n*--------------------------------------------------------------------------------------------*/\r\nimport { UnitConversionInvert, type UnitConversionProps, type UnitProps, type UnitsProvider } from \"./Interfaces\";\r\nimport type { SerializedInvertedUnit, SerializedUnit, SerializedUnitSchema } from \"./SerializedUnitSchema\";\r\nimport { type ResolvedUnit, UnitDefinitionResolver } from \"./UnitConversion/UnitDefinitionResolver\";\r\nimport { qualifyItemName } from \"./UnitConversion/nameUtils\";\r\nimport { BadUnit } from \"./Unit\";\r\n\r\ninterface IndexedUnit {\r\n  readonly props: UnitProps;\r\n  readonly resolved: ResolvedUnit;\r\n}\r\n\r\ninterface InvertedEntry {\r\n  readonly props: UnitProps;\r\n  readonly invertsUnitName: string;\r\n}\r\n\r\n/** Immutable lookup indexes resolved from the bundled Units.json. */\r\ninterface ResolvedState {\r\n  readonly nameMap: Map<string, IndexedUnit>;\r\n  readonly labelMap: Map<string, IndexedUnit[]>;\r\n  readonly phenomenonMap: Map<string, IndexedUnit[]>;\r\n  readonly invertedUnits: Map<string, InvertedEntry>;\r\n  readonly schemaName: string;\r\n}\r\n\r\n// Module-level cache: the unit data is derived deterministically from the bundled Units.json\r\n// asset, so the resolved indexes are effectively an immutable constant. Caching at module\r\n// scope avoids redundant work when multiple BasicUnitsProvider instances are created (e.g.\r\n// in tests or when composed inside CompositeUnitsProvider).\r\n// The JSON is loaded lazily via dynamic import() on first use, keeping the module footprint\r\n// near-zero until a provider method is actually called.\r\nlet _resolvePromise: Promise<ResolvedState> | undefined;\r\nlet _permanentError: Error | undefined;\r\n\r\nasync function resolveState(): Promise<ResolvedState> {\r\n  if (_permanentError !== undefined) {\r\n    throw _permanentError;\r\n  }\r\n  if (!_resolvePromise) {\r\n    _resolvePromise = _buildState().catch((err) => {\r\n      _permanentError = err instanceof Error ? err : new Error(String(err));\r\n      _resolvePromise = undefined;\r\n      throw _permanentError;\r\n    });\r\n  }\r\n  return _resolvePromise;\r\n}\r\n\r\n/** @internal — test use only. Resets the module-level lazy cache. */\r\nexport function _testResetUnitsCache(): void {\r\n  _resolvePromise = undefined;\r\n  _permanentError = undefined;\r\n}\r\n\r\nasync function _buildState(): Promise<ResolvedState> {\r\n  const { default: schema } = await import(\"./assets/Units.json\");\r\n\r\n  const nameMap = new Map<string, IndexedUnit>();\r\n  const labelMap = new Map<string, IndexedUnit[]>();\r\n  const phenomenonMap = new Map<string, IndexedUnit[]>();\r\n  const invertedUnits = new Map<string, InvertedEntry>();\r\n\r\n  const s = schema as SerializedUnitSchema;\r\n  const resolver = new UnitDefinitionResolver(s);\r\n  const resolved = resolver.resolveAll();\r\n\r\n  for (const [name, entry] of resolved) {\r\n    const item = s.items[name] as SerializedUnit;\r\n    const phenomenon = item.phenomenon;\r\n    const unitSystem = item.unitSystem;\r\n\r\n    const fullName = `${s.name}.${name}`;\r\n    const props: UnitProps = {\r\n      name: fullName,\r\n      label: entry.label,\r\n      phenomenon,\r\n      isValid: true,\r\n      system: unitSystem,\r\n    };\r\n\r\n    const indexed: IndexedUnit = { props, resolved: entry };\r\n\r\n    nameMap.set(fullName, indexed);\r\n    const lowerLabel = entry.label.toLowerCase();\r\n    const byLabel = labelMap.get(lowerLabel) ?? [];\r\n    byLabel.push(indexed);\r\n    labelMap.set(lowerLabel, byLabel);\r\n\r\n    const byPhen = phenomenonMap.get(phenomenon) ?? [];\r\n    byPhen.push(indexed);\r\n    phenomenonMap.set(phenomenon, byPhen);\r\n  }\r\n\r\n  // Handle InvertedUnit items — must run after nameMap is fully populated above because\r\n  // invertedSource lookup requires the inverted unit's target to already be in nameMap.\r\n  for (const [name, item] of Object.entries(s.items)) {\r\n    if (item.schemaItemType !== \"InvertedUnit\") {\r\n      continue;\r\n    }\r\n    const inv: SerializedInvertedUnit = item;\r\n    const fullName = `${s.name}.${name}`;\r\n    const invertsName = qualifyItemName(inv.invertsUnit, s.name);\r\n    const unitSystem = inv.unitSystem;\r\n\r\n    const invertedSource = nameMap.get(invertsName);\r\n    const phenomenon = invertedSource?.props.phenomenon ?? \"\";\r\n\r\n    const props: UnitProps = {\r\n      name: fullName,\r\n      label: inv.label ?? name,\r\n      phenomenon,\r\n      isValid: true,\r\n      system: unitSystem,\r\n    };\r\n\r\n    invertedUnits.set(fullName, { props, invertsUnitName: invertsName });\r\n\r\n    if (invertedSource) {\r\n      const indexed: IndexedUnit = {\r\n        props,\r\n        resolved: { ...invertedSource.resolved, name: fullName, label: props.label, unitSystem },\r\n      };\r\n      nameMap.set(fullName, indexed);\r\n\r\n      const lowerLabel = props.label.toLowerCase();\r\n      const byLabel = labelMap.get(lowerLabel) ?? [];\r\n      byLabel.push(indexed);\r\n      labelMap.set(lowerLabel, byLabel);\r\n\r\n      const byPhen = phenomenonMap.get(phenomenon) ?? [];\r\n      byPhen.push(indexed);\r\n      phenomenonMap.set(phenomenon, byPhen);\r\n    }\r\n  }\r\n\r\n  return { nameMap, labelMap, phenomenonMap, invertedUnits, schemaName: s.name };\r\n}\r\n\r\n/**\r\n * A `UnitsProvider` backed by the full BIS `Units.ecschema.json` bundled as a JSON asset.\r\n *\r\n * The ~90 KB bundled JSON is loaded lazily via dynamic `import()` on the first provider method\r\n * call and cached at module scope — construction is essentially free, and multiple instances\r\n * share the same immutable lookup indexes.\r\n *\r\n * This is the zero-dependency default for backends, tools, and any frontend that doesn't need\r\n * iModel overrides. Equivalent to calling `createUnitsProvider()` with no arguments.\r\n *\r\n * @see createUnitsProvider for layering schema-defined units on top of basic BIS units.\r\n * @beta\r\n */\r\nexport class BasicUnitsProvider implements UnitsProvider {\r\n\r\n  // ── UnitsProvider implementation ─────────────────────────────────────\r\n\r\n  /** Find a unit by its display label, optionally filtering by schema name, phenomenon, and unit system.\r\n   * @param unitLabel - The display label to search for (case-insensitive).\r\n   * @param schemaName - Optional schema name filter. Returns `BadUnit` if provided and not `\"Units\"`.\r\n   * @param phenomenon - Optional phenomenon filter (e.g. `\"Units.LENGTH\"`).\r\n   * @param unitSystem - Optional unit system filter (e.g. `\"Units.METRIC\"`).\r\n   * @returns The matching `UnitProps`, or a `BadUnit` if no match is found.\r\n   */\r\n  public async findUnit(unitLabel: string, schemaName?: string, phenomenon?: string, unitSystem?: string): Promise<UnitProps> {\r\n    const state = await resolveState();\r\n    if (schemaName && schemaName !== state.schemaName) {\r\n      return new BadUnit();\r\n    }\r\n    const candidates = state.labelMap.get(unitLabel.toLowerCase());\r\n    if (!candidates || candidates.length === 0) {\r\n      return new BadUnit();\r\n    }\r\n\r\n    for (const c of candidates) {\r\n      if (phenomenon && c.props.phenomenon !== phenomenon) {\r\n        continue;\r\n      }\r\n      if (unitSystem && c.props.system !== unitSystem) {\r\n        continue;\r\n      }\r\n      return c.props;\r\n    }\r\n\r\n    return new BadUnit();\r\n  }\r\n\r\n  /** Return all units belonging to the given phenomenon (unit family).\r\n   * @param phenomenon - The phenomenon full name (e.g. `\"Units.LENGTH\"`).\r\n   * @returns An array of matching `UnitProps`, or an empty array if none.\r\n   */\r\n  public async getUnitsByFamily(phenomenon: string): Promise<UnitProps[]> {\r\n    const state = await resolveState();\r\n    const entries = state.phenomenonMap.get(phenomenon);\r\n    return entries ? entries.map((e) => e.props) : [];\r\n  }\r\n\r\n  /** Find a unit by its fully-qualified name (e.g. `\"Units.M\"`).\r\n   * @param unitName - The qualified unit name.\r\n   * @returns The matching `UnitProps`, or a `BadUnit` if not found.\r\n   */\r\n  public async findUnitByName(unitName: string): Promise<UnitProps> {\r\n    const state = await resolveState();\r\n    const entry = state.nameMap.get(unitName);\r\n    return entry ? entry.props : new BadUnit();\r\n  }\r\n\r\n  /** Compute the conversion factors from `fromUnit` to `toUnit`.\r\n   * Handles normal units, inverted units, and mixed (inverted ↔ non-inverted) conversions.\r\n   * @param fromUnit - The source unit.\r\n   * @param toUnit - The target unit.\r\n   * @returns A `UnitConversionProps` with `factor`, `offset`, and optionally `inversion` and `error`.\r\n   */\r\n  public async getConversion(fromUnit: UnitProps, toUnit: UnitProps): Promise<UnitConversionProps> {\r\n    const state = await resolveState();\r\n    const from = state.nameMap.get(fromUnit.name);\r\n    const to = state.nameMap.get(toUnit.name);\r\n\r\n    if (!from || !to) {\r\n      return { factor: 1.0, offset: 0.0, error: true };\r\n    }\r\n\r\n    const fromInverted = state.invertedUnits.get(fromUnit.name);\r\n    const toInverted = state.invertedUnits.get(toUnit.name);\r\n\r\n    const fromPhenomenon = fromInverted\r\n      ? state.nameMap.get(fromInverted.invertsUnitName)?.props.phenomenon\r\n      : from.props.phenomenon;\r\n    const toPhenomenon = toInverted\r\n      ? state.nameMap.get(toInverted.invertsUnitName)?.props.phenomenon\r\n      : to.props.phenomenon;\r\n    if (fromPhenomenon !== toPhenomenon) {\r\n      return { factor: 1.0, offset: 0.0, error: true };\r\n    }\r\n\r\n    if (fromInverted && toInverted) {\r\n      const innerFrom = state.nameMap.get(fromInverted.invertsUnitName);\r\n      const innerTo = state.nameMap.get(toInverted.invertsUnitName);\r\n      if (innerFrom && innerTo) {\r\n        const c = innerFrom.resolved.conversion.inverse().compose(innerTo.resolved.conversion);\r\n        return { factor: c.factor, offset: c.offset };\r\n      }\r\n    }\r\n\r\n    if (fromInverted) {\r\n      const innerFrom = state.nameMap.get(fromInverted.invertsUnitName);\r\n      if (innerFrom) {\r\n        const c = innerFrom.resolved.conversion.inverse().compose(to.resolved.conversion);\r\n        return { factor: c.factor, offset: c.offset, inversion: UnitConversionInvert.InvertPreConversion };\r\n      }\r\n    }\r\n\r\n    if (toInverted) {\r\n      const innerTo = state.nameMap.get(toInverted.invertsUnitName);\r\n      if (innerTo) {\r\n        const c = from.resolved.conversion.inverse().compose(innerTo.resolved.conversion);\r\n        return { factor: c.factor, offset: c.offset, inversion: UnitConversionInvert.InvertPostConversion };\r\n      }\r\n    }\r\n\r\n    const conv = from.resolved.conversion.inverse().compose(to.resolved.conversion);\r\n    return { factor: conv.factor, offset: conv.offset };\r\n  }\r\n}\r\n"]}

package/lib/esm/CompositeUnitsProvider.d.ts

@@ -0,0 +1,45 @@
+import type { UnitsProvider } from "./Interfaces";
+/**
+ * Options for [[createUnitsProvider]].
+ * @beta
+ */
+export interface CreateUnitsProviderOptions {
+    /**
+     * A `UnitsProvider` consulted before the basic BIS units (e.g. a `SchemaUnitProvider`
+     * for an open iModel's `SchemaContext`). When omitted, the returned provider behaves
+     * exactly like `new BasicUnitsProvider()`.
+     */
+    primary?: UnitsProvider;
+    /**
+     * Controls which provider is consulted first and wins ties.
+     * - `"preferSchema"` (default): `primary` is authoritative; bundled BIS units are fallback.
+     * - `"preferBundled"`: bundled BIS units win; `primary` is consulted only for units not in
+     *   the bundled set. Use when the iModel's schema may be stale.
+     *
+     * Affects `findUnit`, `findUnitByName`, and `getConversion` (first-consulted wins or
+     * falls through). `getUnitsByFamily` always merges both providers — the first-consulted
+     * provider wins name collisions.
+     *
+     * Has no effect when `primary` is omitted — the returned provider is a plain `BasicUnitsProvider`.
+     */
+    bisUnitsPolicy?: "preferSchema" | "preferBundled";
+}
+/**
+ * Returns a `UnitsProvider` that layers the basic BIS units under (or over) an optional
+ * `primary` provider. Typical use: layer an iModel's schema units on top of the bundled
+ * defaults from `@itwin/core-quantity`.
+ *
+ * Precedence rules:
+ * - When `primary` is supplied and `bisUnitsPolicy` is `"preferSchema"` (the default): `primary` wins;
+ *   basic BIS units fill any gaps where `primary` returns an invalid unit or throws.
+ * - When `bisUnitsPolicy` is `"preferBundled"`: basic BIS units win; `primary` is consulted only when the
+ *   basic provider can't answer.
+ * - `getUnitsByFamily` always merges results from both providers, deduplicated by
+ *   `UnitProps.name` (fully-qualified). The first-consulted provider wins ties.
+ * - When no `primary` is supplied, the returned provider is exactly `new BasicUnitsProvider()`
+ *   (no wrapper), preserving `instanceof` checks and keeping the hot path fast.
+ *
+ * @beta
+ */
+export declare function createUnitsProvider(options?: CreateUnitsProviderOptions): UnitsProvider;
+//# sourceMappingURL=CompositeUnitsProvider.d.ts.map

package/lib/esm/CompositeUnitsProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CompositeUnitsProvider.d.ts","sourceRoot":"","sources":["../../src/CompositeUnitsProvider.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAkC,aAAa,EAAE,MAAM,cAAc,CAAC;AAGlF;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;;OAIG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;IAExB;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,EAAE,cAAc,GAAG,eAAe,CAAC;CACnD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,0BAA+B,GAAG,aAAa,CAY3F"}

package/lib/esm/CompositeUnitsProvider.js

@@ -0,0 +1,108 @@
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+import { BasicUnitsProvider } from "./BasicUnitsProvider";
+import { BadUnit } from "./Unit";
+/**
+ * Returns a `UnitsProvider` that layers the basic BIS units under (or over) an optional
+ * `primary` provider. Typical use: layer an iModel's schema units on top of the bundled
+ * defaults from `@itwin/core-quantity`.
+ *
+ * Precedence rules:
+ * - When `primary` is supplied and `bisUnitsPolicy` is `"preferSchema"` (the default): `primary` wins;
+ *   basic BIS units fill any gaps where `primary` returns an invalid unit or throws.
+ * - When `bisUnitsPolicy` is `"preferBundled"`: basic BIS units win; `primary` is consulted only when the
+ *   basic provider can't answer.
+ * - `getUnitsByFamily` always merges results from both providers, deduplicated by
+ *   `UnitProps.name` (fully-qualified). The first-consulted provider wins ties.
+ * - When no `primary` is supplied, the returned provider is exactly `new BasicUnitsProvider()`
+ *   (no wrapper), preserving `instanceof` checks and keeping the hot path fast.
+ *
+ * @beta
+ */
+export function createUnitsProvider(options = {}) {
+    const basic = new BasicUnitsProvider();
+    const primary = options.primary;
+    // NOTE: returns BasicUnitsProvider directly when no primary is provided.
+    // QuantityFormatter.resetToUseInternalUnitsProvider uses instanceof BasicUnitsProvider to detect this.
+    // If this fast-path is ever wrapped (e.g. for telemetry), that guard must be updated.
+    if (!primary) {
+        return basic;
+    }
+    const providers = options.bisUnitsPolicy === "preferBundled" ? [basic, primary] : [primary, basic];
+    return new CompositeUnitsProvider(providers);
+}
+class CompositeUnitsProvider {
+    _providers;
+    constructor(_providers) {
+        this._providers = _providers;
+    }
+    async findUnit(label, schemaName, phenomenon, unitSystem) {
+        for (let i = 0; i < this._providers.length - 1; i++) {
+            const hit = await tryFind(async () => this._providers[i].findUnit(label, schemaName, phenomenon, unitSystem));
+            if (hit?.isValid) {
+                return hit;
+            }
+        }
+        return tryFind(async () => this._providers[this._providers.length - 1].findUnit(label, schemaName, phenomenon, unitSystem)).then((hit) => hit ?? new BadUnit());
+    }
+    async findUnitByName(name) {
+        for (let i = 0; i < this._providers.length - 1; i++) {
+            const hit = await tryFind(async () => this._providers[i].findUnitByName(name));
+            if (hit?.isValid) {
+                return hit;
+            }
+        }
+        return tryFind(async () => this._providers[this._providers.length - 1].findUnitByName(name)).then((hit) => hit ?? new BadUnit());
+    }
+    async getUnitsByFamily(phenomenon) {
+        const seen = new Set();
+        const out = [];
+        // Query all providers in parallel; process results in declaration order to honour precedence.
+        const results = await Promise.all(this._providers.map(async (p) => tryList(async () => p.getUnitsByFamily(phenomenon))));
+        for (const units of results) {
+            for (const u of units) {
+                if (!seen.has(u.name)) {
+                    seen.add(u.name);
+                    out.push(u);
+                }
+            }
+        }
+        return out;
+    }
+    async getConversion(from, to) {
+        for (let i = 0; i < this._providers.length - 1; i++) {
+            try {
+                const result = await this._providers[i].getConversion(from, to);
+                if (!result.error) {
+                    return result;
+                }
+            }
+            catch { /* fall through to next provider */ }
+        }
+        try {
+            return await this._providers[this._providers.length - 1].getConversion(from, to);
+        }
+        catch {
+            return { factor: 1.0, offset: 0.0, error: true };
+        }
+    }
+}
+async function tryFind(fn) {
+    try {
+        return await fn();
+    }
+    catch {
+        return undefined;
+    }
+}
+async function tryList(fn) {
+    try {
+        return await fn();
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=CompositeUnitsProvider.js.map

package/lib/esm/CompositeUnitsProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CompositeUnitsProvider.js","sourceRoot":"","sources":["../../src/CompositeUnitsProvider.ts"],"names":[],"mappings":"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","sourcesContent":["/*---------------------------------------------------------------------------------------------\r\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\r\n* See LICENSE.md in the project root for license terms and full copyright notice.\r\n*--------------------------------------------------------------------------------------------*/\r\nimport { BasicUnitsProvider } from \"./BasicUnitsProvider\";\r\nimport type { UnitConversionProps, UnitProps, UnitsProvider } from \"./Interfaces\";\r\nimport { BadUnit } from \"./Unit\";\r\n\r\n/**\r\n * Options for [[createUnitsProvider]].\r\n * @beta\r\n */\r\nexport interface CreateUnitsProviderOptions {\r\n  /**\r\n   * A `UnitsProvider` consulted before the basic BIS units (e.g. a `SchemaUnitProvider`\r\n   * for an open iModel's `SchemaContext`). When omitted, the returned provider behaves\r\n   * exactly like `new BasicUnitsProvider()`.\r\n   */\r\n  primary?: UnitsProvider;\r\n\r\n  /**\r\n   * Controls which provider is consulted first and wins ties.\r\n   * - `\"preferSchema\"` (default): `primary` is authoritative; bundled BIS units are fallback.\r\n   * - `\"preferBundled\"`: bundled BIS units win; `primary` is consulted only for units not in\r\n   *   the bundled set. Use when the iModel's schema may be stale.\r\n   *\r\n   * Affects `findUnit`, `findUnitByName`, and `getConversion` (first-consulted wins or\r\n   * falls through). `getUnitsByFamily` always merges both providers — the first-consulted\r\n   * provider wins name collisions.\r\n   *\r\n   * Has no effect when `primary` is omitted — the returned provider is a plain `BasicUnitsProvider`.\r\n   */\r\n  bisUnitsPolicy?: \"preferSchema\" | \"preferBundled\";\r\n}\r\n\r\n/**\r\n * Returns a `UnitsProvider` that layers the basic BIS units under (or over) an optional\r\n * `primary` provider. Typical use: layer an iModel's schema units on top of the bundled\r\n * defaults from `@itwin/core-quantity`.\r\n *\r\n * Precedence rules:\r\n * - When `primary` is supplied and `bisUnitsPolicy` is `\"preferSchema\"` (the default): `primary` wins;\r\n *   basic BIS units fill any gaps where `primary` returns an invalid unit or throws.\r\n * - When `bisUnitsPolicy` is `\"preferBundled\"`: basic BIS units win; `primary` is consulted only when the\r\n *   basic provider can't answer.\r\n * - `getUnitsByFamily` always merges results from both providers, deduplicated by\r\n *   `UnitProps.name` (fully-qualified). The first-consulted provider wins ties.\r\n * - When no `primary` is supplied, the returned provider is exactly `new BasicUnitsProvider()`\r\n *   (no wrapper), preserving `instanceof` checks and keeping the hot path fast.\r\n *\r\n * @beta\r\n */\r\nexport function createUnitsProvider(options: CreateUnitsProviderOptions = {}): UnitsProvider {\r\n  const basic = new BasicUnitsProvider();\r\n  const primary = options.primary;\r\n  // NOTE: returns BasicUnitsProvider directly when no primary is provided.\r\n  // QuantityFormatter.resetToUseInternalUnitsProvider uses instanceof BasicUnitsProvider to detect this.\r\n  // If this fast-path is ever wrapped (e.g. for telemetry), that guard must be updated.\r\n  if (!primary) {\r\n    return basic;\r\n  }\r\n\r\n  const providers = options.bisUnitsPolicy === \"preferBundled\" ? [basic, primary] : [primary, basic];\r\n  return new CompositeUnitsProvider(providers);\r\n}\r\n\r\nclass CompositeUnitsProvider implements UnitsProvider {\r\n  constructor(private readonly _providers: UnitsProvider[]) {}\r\n\r\n  public async findUnit(label: string, schemaName?: string, phenomenon?: string, unitSystem?: string): Promise<UnitProps> {\r\n    for (let i = 0; i < this._providers.length - 1; i++) {\r\n      const hit = await tryFind(async () => this._providers[i].findUnit(label, schemaName, phenomenon, unitSystem));\r\n      if (hit?.isValid) {\r\n        return hit;\r\n      }\r\n    }\r\n    return tryFind(async () => this._providers[this._providers.length - 1].findUnit(label, schemaName, phenomenon, unitSystem)).then((hit) => hit ?? new BadUnit());\r\n  }\r\n\r\n  public async findUnitByName(name: string): Promise<UnitProps> {\r\n    for (let i = 0; i < this._providers.length - 1; i++) {\r\n      const hit = await tryFind(async () => this._providers[i].findUnitByName(name));\r\n      if (hit?.isValid) {\r\n        return hit;\r\n      }\r\n    }\r\n    return tryFind(async () => this._providers[this._providers.length - 1].findUnitByName(name)).then((hit) => hit ?? new BadUnit());\r\n  }\r\n\r\n  public async getUnitsByFamily(phenomenon: string): Promise<UnitProps[]> {\r\n    const seen = new Set<string>();\r\n    const out: UnitProps[] = [];\r\n    // Query all providers in parallel; process results in declaration order to honour precedence.\r\n    const results = await Promise.all(this._providers.map(async (p) => tryList(async () => p.getUnitsByFamily(phenomenon))));\r\n    for (const units of results) {\r\n      for (const u of units) {\r\n        if (!seen.has(u.name)) {\r\n          seen.add(u.name);\r\n          out.push(u);\r\n        }\r\n      }\r\n    }\r\n    return out;\r\n  }\r\n\r\n  public async getConversion(from: UnitProps, to: UnitProps): Promise<UnitConversionProps> {\r\n    for (let i = 0; i < this._providers.length - 1; i++) {\r\n      try {\r\n        const result = await this._providers[i].getConversion(from, to);\r\n        if (!result.error) {\r\n          return result;\r\n        }\r\n      } catch { /* fall through to next provider */ }\r\n    }\r\n    try {\r\n      return await this._providers[this._providers.length - 1].getConversion(from, to);\r\n    } catch {\r\n      return { factor: 1.0, offset: 0.0, error: true };\r\n    }\r\n  }\r\n}\r\n\r\nasync function tryFind(fn: () => Promise<UnitProps>): Promise<UnitProps | undefined> {\r\n  try { return await fn(); } catch { return undefined; }\r\n}\r\n\r\nasync function tryList(fn: () => Promise<UnitProps[]>): Promise<UnitProps[]> {\r\n  try { return await fn(); } catch { return []; }\r\n}\r\n"]}