@itwin/core-quantity 5.10.0-dev.16 → 5.10.0-dev.19

package/lib/esm/BasicUnitsProvider.js

@@ -1,112 +1,28 @@
-/*---------------------------------------------------------------------------------------------
-* 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;
+import { getBasicUnitConversion } from "./internal/BasicUnitConversionData";
+import { _testResetResolvedBasicUnitsDataCache, resolveBasicUnitsData } from "./internal/BasicUnitsResolvedStateCache";
 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;
+    return resolveBasicUnitsData(async () => {
+        // First caller pays the dynamic-import + schema-index build cost.
+        // Concurrent callers await the same promise, and later callers reuse the resolved state.
+        const { default: schema } = await import("./assets/Units.json");
+        return schema;
+    });
 }
-/** @internal — test use only. Resets the module-level lazy cache. */
+/** @internal — test use only. Resets the shared 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 };
+    _testResetResolvedBasicUnitsDataCache();
 }
 /**
  * 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
+ * The bundled JSON is loaded lazily via dynamic `import()` on the first provider call and cached
+ * at module scope — construction is essentially free, and multiple instances
  * share the same immutable lookup indexes.
  *
+ * If an initial schema load fails, later provider calls will retry the load instead of pinning the
+ * provider into a permanently failed module-level state.
+ *
  * 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.
  *
@@ -168,46 +84,7 @@ export class BasicUnitsProvider {
      */
     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 };
+        return getBasicUnitConversion(state, fromUnit, toUnit);
     }
 }
 //# sourceMappingURL=BasicUnitsProvider.js.map

package/lib/esm/BasicUnitsProvider.js.map

@@ -1 +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"]}
+{"version":3,"file":"BasicUnitsProvider.js","sourceRoot":"","sources":["../../src/BasicUnitsProvider.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACjC,OAAO,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAC5E,OAAO,EAAE,qCAAqC,EAAE,qBAAqB,EAAE,MAAM,yCAAyC,CAAC;AAEvH,KAAK,UAAU,YAAY;IACzB,OAAO,qBAAqB,CAAC,KAAK,IAAI,EAAE;QACtC,kEAAkE;QAClE,yFAAyF;QACzF,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,qBAAqB,CAAC,CAAC;QAChE,OAAO,MAA8B,CAAC;IACxC,CAAC,CAAC,CAAC;AACL,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,oBAAoB;IAClC,qCAAqC,EAAE,CAAC;AAC1C,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,kBAAkB;IAE7B,wEAAwE;IAExE;;;;;;OAMG;IACI,KAAK,CAAC,QAAQ,CAAC,SAAiB,EAAE,UAAmB,EAAE,UAAmB,EAAE,UAAmB;QACpG,MAAM,KAAK,GAAG,MAAM,YAAY,EAAE,CAAC;QACnC,IAAI,UAAU,IAAI,UAAU,KAAK,KAAK,CAAC,UAAU,EAAE,CAAC;YAClD,OAAO,IAAI,OAAO,EAAE,CAAC;QACvB,CAAC;QACD,MAAM,UAAU,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC;QAC/D,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3C,OAAO,IAAI,OAAO,EAAE,CAAC;QACvB,CAAC;QAED,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;YAC3B,IAAI,UAAU,IAAI,CAAC,CAAC,KAAK,CAAC,UAAU,KAAK,UAAU,EAAE,CAAC;gBACpD,SAAS;YACX,CAAC;YACD,IAAI,UAAU,IAAI,CAAC,CAAC,KAAK,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;gBAChD,SAAS;YACX,CAAC;YACD,OAAO,CAAC,CAAC,KAAK,CAAC;QACjB,CAAC;QAED,OAAO,IAAI,OAAO,EAAE,CAAC;IACvB,CAAC;IAED;;;OAGG;IACI,KAAK,CAAC,gBAAgB,CAAC,UAAkB;QAC9C,MAAM,KAAK,GAAG,MAAM,YAAY,EAAE,CAAC;QACnC,MAAM,OAAO,GAAG,KAAK,CAAC,aAAa,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACpD,OAAO,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACpD,CAAC;IAED;;;OAGG;IACI,KAAK,CAAC,cAAc,CAAC,QAAgB;QAC1C,MAAM,KAAK,GAAG,MAAM,YAAY,EAAE,CAAC;QACnC,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC1C,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,OAAO,EAAE,CAAC;IAC7C,CAAC;IAED;;;;;OAKG;IACI,KAAK,CAAC,aAAa,CAAC,QAAmB,EAAE,MAAiB;QAC/D,MAAM,KAAK,GAAG,MAAM,YAAY,EAAE,CAAC;QACnC,OAAO,sBAAsB,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IACzD,CAAC;CACF","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 type { UnitProps, UnitsProvider } from \"./Interfaces\";\r\nimport type { SerializedUnitSchema } from \"./SerializedUnitSchema\";\r\nimport { BadUnit } from \"./Unit\";\r\nimport { getBasicUnitConversion } from \"./internal/BasicUnitConversionData\";\r\nimport { _testResetResolvedBasicUnitsDataCache, resolveBasicUnitsData } from \"./internal/BasicUnitsResolvedStateCache\";\r\n\r\nasync function resolveState() {\r\n  return resolveBasicUnitsData(async () => {\r\n    // First caller pays the dynamic-import + schema-index build cost.\r\n    // Concurrent callers await the same promise, and later callers reuse the resolved state.\r\n    const { default: schema } = await import(\"./assets/Units.json\");\r\n    return schema as SerializedUnitSchema;\r\n  });\r\n}\r\n\r\n/** @internal — test use only. Resets the shared module-level lazy cache. */\r\nexport function _testResetUnitsCache(): void {\r\n  _testResetResolvedBasicUnitsDataCache();\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 bundled JSON is loaded lazily via dynamic `import()` on the first provider call and cached\r\n * at module scope — construction is essentially free, and multiple instances\r\n * share the same immutable lookup indexes.\r\n *\r\n * If an initial schema load fails, later provider calls will retry the load instead of pinning the\r\n * provider into a permanently failed module-level state.\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) {\r\n    const state = await resolveState();\r\n    return getBasicUnitConversion(state, fromUnit, toUnit);\r\n  }\r\n}\r\n"]}

package/lib/esm/Exception.d.ts

@@ -18,7 +18,8 @@ export declare enum QuantityStatus {
     UnableToConvertParseTokensToQuantity = 35046,
     UnsupportedUnit = 35047,
     MissingRequiredProperty = 35048,
-    InvertingZero = 35049
+    InvertingZero = 35049,
+    InvalidUnitConversion = 35050
 }
 /** The error type thrown by this module. See [[QuantityStatus]] for `errorNumber` values.
  * @beta

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

@@ -1 +1 @@
-{"version":3,"file":"Exception.d.ts","sourceRoot":"","sources":["../../src/Exception.ts"],"names":[],"mappings":"AAIA;;GAEG;AAEH,OAAO,EAAU,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAE3D;;;GAGG;AACH,oBAAY,cAAc;IACxB,mBAAmB,QAAS;IAC5B,OAAO,IAAI;IACX,WAAW,QAA0B;IACrC,sBAAsB,QAA0B;IAChD,2BAA2B,QAA0B;IACrD,0BAA0B,QAA0B;IACpD,8BAA8B,QAA0B;IACxD,WAAW,QAA0B;IACrC,oCAAoC,QAA0B;IAC9D,eAAe,QAA0B;IACzC,uBAAuB,QAA0B;IACjD,aAAa,QAA2B;CACzC;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,YAAY;aACD,WAAW,EAAE,MAAM;gBAAnB,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;CAIlF"}
+{"version":3,"file":"Exception.d.ts","sourceRoot":"","sources":["../../src/Exception.ts"],"names":[],"mappings":"AAIA;;GAEG;AAEH,OAAO,EAAU,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAE3D;;;GAGG;AACH,oBAAY,cAAc;IACxB,mBAAmB,QAAS;IAC5B,OAAO,IAAI;IACX,WAAW,QAA0B;IACrC,sBAAsB,QAA0B;IAChD,2BAA2B,QAA0B;IACrD,0BAA0B,QAA0B;IACpD,8BAA8B,QAA0B;IACxD,WAAW,QAA0B;IACrC,oCAAoC,QAA0B;IAC9D,eAAe,QAA0B;IACzC,uBAAuB,QAA0B;IACjD,aAAa,QAA2B;IACxC,qBAAqB,QAA2B;CACjD;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,YAAY;aACD,WAAW,EAAE,MAAM;gBAAnB,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;CAIlF"}

package/lib/esm/Exception.js

@@ -24,6 +24,7 @@ export var QuantityStatus;
     QuantityStatus[QuantityStatus["UnsupportedUnit"] = 35047] = "UnsupportedUnit";
     QuantityStatus[QuantityStatus["MissingRequiredProperty"] = 35048] = "MissingRequiredProperty";
     QuantityStatus[QuantityStatus["InvertingZero"] = 35049] = "InvertingZero";
+    QuantityStatus[QuantityStatus["InvalidUnitConversion"] = 35050] = "InvalidUnitConversion";
 })(QuantityStatus || (QuantityStatus = {}));
 /** The error type thrown by this module. See [[QuantityStatus]] for `errorNumber` values.
  * @beta

package/lib/esm/Exception.js.map

@@ -1 +1 @@
-{"version":3,"file":"Exception.js","sourceRoot":"","sources":["../../src/Exception.ts"],"names":[],"mappings":"AAAA;;;+FAG+F;AAC/F;;GAEG;AAEH,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAE3D;;;GAGG;AACH,MAAM,CAAN,IAAY,cAaX;AAbD,WAAY,cAAc;IACxB,qFAA4B,CAAA;IAC5B,yDAAW,CAAA;IACX,qEAAqC,CAAA;IACrC,2FAAgD,CAAA;IAChD,qGAAqD,CAAA;IACrD,mGAAoD,CAAA;IACpD,2GAAwD,CAAA;IACxD,qEAAqC,CAAA;IACrC,uHAA8D,CAAA;IAC9D,6EAAyC,CAAA;IACzC,6FAAiD,CAAA;IACjD,yEAAwC,CAAA;AAC1C,CAAC,EAbW,cAAc,KAAd,cAAc,QAazB;AAED;;GAEG;AACH,MAAM,OAAO,aAAc,SAAQ,YAAY;IACD;IAA5C,YAA4C,WAAmB,EAAE,OAAgB;QAC/E,KAAK,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QADc,gBAAW,GAAX,WAAW,CAAQ;QAE7D,MAAM,CAAC,WAAW,KAAK,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC1D,CAAC;CACF","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/** @packageDocumentation\r\n * @module Quantity\r\n */\r\n\r\nimport { assert, BentleyError } from \"@itwin/core-bentley\";\r\n\r\n/**\r\n * Status codes used during Quantity parsing and formatting processing.\r\n * @beta\r\n */\r\nexport enum QuantityStatus {\r\n  QUANTITY_ERROR_BASE = 0x88DF,\r\n  Success = 0,\r\n  InvalidJson = QUANTITY_ERROR_BASE + 1,\r\n  InvalidCompositeFormat = QUANTITY_ERROR_BASE + 2,\r\n  UnableToGenerateParseTokens = QUANTITY_ERROR_BASE + 3,\r\n  NoValueOrUnitFoundInString = QUANTITY_ERROR_BASE + 4,\r\n  UnitLabelSuppliedButNotMatched = QUANTITY_ERROR_BASE + 5,\r\n  UnknownUnit = QUANTITY_ERROR_BASE + 6,\r\n  UnableToConvertParseTokensToQuantity = QUANTITY_ERROR_BASE + 7,\r\n  UnsupportedUnit = QUANTITY_ERROR_BASE + 8,\r\n  MissingRequiredProperty = QUANTITY_ERROR_BASE + 9,\r\n  InvertingZero = QUANTITY_ERROR_BASE + 10,\r\n}\r\n\r\n/** The error type thrown by this module. See [[QuantityStatus]] for `errorNumber` values.\r\n * @beta\r\n */\r\nexport class QuantityError extends BentleyError {\r\n  public constructor(public override readonly errorNumber: number, message?: string) {\r\n    super(errorNumber, message);\r\n    assert(errorNumber !== QuantityStatus.Success, message);\r\n  }\r\n}\r\n"]}
+{"version":3,"file":"Exception.js","sourceRoot":"","sources":["../../src/Exception.ts"],"names":[],"mappings":"AAAA;;;+FAG+F;AAC/F;;GAEG;AAEH,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAE3D;;;GAGG;AACH,MAAM,CAAN,IAAY,cAcX;AAdD,WAAY,cAAc;IACxB,qFAA4B,CAAA;IAC5B,yDAAW,CAAA;IACX,qEAAqC,CAAA;IACrC,2FAAgD,CAAA;IAChD,qGAAqD,CAAA;IACrD,mGAAoD,CAAA;IACpD,2GAAwD,CAAA;IACxD,qEAAqC,CAAA;IACrC,uHAA8D,CAAA;IAC9D,6EAAyC,CAAA;IACzC,6FAAiD,CAAA;IACjD,yEAAwC,CAAA;IACxC,yFAAgD,CAAA;AAClD,CAAC,EAdW,cAAc,KAAd,cAAc,QAczB;AAED;;GAEG;AACH,MAAM,OAAO,aAAc,SAAQ,YAAY;IACD;IAA5C,YAA4C,WAAmB,EAAE,OAAgB;QAC/E,KAAK,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QADc,gBAAW,GAAX,WAAW,CAAQ;QAE7D,MAAM,CAAC,WAAW,KAAK,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC1D,CAAC;CACF","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/** @packageDocumentation\r\n * @module Quantity\r\n */\r\n\r\nimport { assert, BentleyError } from \"@itwin/core-bentley\";\r\n\r\n/**\r\n * Status codes used during Quantity parsing and formatting processing.\r\n * @beta\r\n */\r\nexport enum QuantityStatus {\r\n  QUANTITY_ERROR_BASE = 0x88DF,\r\n  Success = 0,\r\n  InvalidJson = QUANTITY_ERROR_BASE + 1,\r\n  InvalidCompositeFormat = QUANTITY_ERROR_BASE + 2,\r\n  UnableToGenerateParseTokens = QUANTITY_ERROR_BASE + 3,\r\n  NoValueOrUnitFoundInString = QUANTITY_ERROR_BASE + 4,\r\n  UnitLabelSuppliedButNotMatched = QUANTITY_ERROR_BASE + 5,\r\n  UnknownUnit = QUANTITY_ERROR_BASE + 6,\r\n  UnableToConvertParseTokensToQuantity = QUANTITY_ERROR_BASE + 7,\r\n  UnsupportedUnit = QUANTITY_ERROR_BASE + 8,\r\n  MissingRequiredProperty = QUANTITY_ERROR_BASE + 9,\r\n  InvertingZero = QUANTITY_ERROR_BASE + 10,\r\n  InvalidUnitConversion = QUANTITY_ERROR_BASE + 11,\r\n}\r\n\r\n/** The error type thrown by this module. See [[QuantityStatus]] for `errorNumber` values.\r\n * @beta\r\n */\r\nexport class QuantityError extends BentleyError {\r\n  public constructor(public override readonly errorNumber: number, message?: string) {\r\n    super(errorNumber, message);\r\n    assert(errorNumber !== QuantityStatus.Success, message);\r\n  }\r\n}\r\n"]}

package/lib/esm/FormatSpecHandle.d.ts

@@ -6,7 +6,7 @@ import type { FormattingSpecArgs, FormattingSpecProvider } from "./Formatter/Int
 import type { ParserSpec } from "./ParserSpec";
 import type { UnitSystemKey } from "./Interfaces";
 /** Arguments for constructing a [[FormatSpecHandle]].
- * @internal
+ * @beta
  */
 export interface FormatSpecHandleArgs extends FormattingSpecArgs {
     /** The provider that supplies current formatting spec lookups. */
@@ -27,7 +27,6 @@ export declare class FormatSpecHandle implements Disposable {
     private readonly _koqName;
     private readonly _persistenceUnit;
     private readonly _system;
-    /** @internal */
     constructor(args: FormatSpecHandleArgs);
     /** The KoQ name this handle is keyed to. */
     get koqName(): string;

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

@@ -1 +1 @@
-{"version":3,"file":"FormatSpecHandle.d.ts","sourceRoot":"","sources":["../../src/FormatSpecHandle.ts"],"names":[],"mappings":"AAKA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,KAAK,EAAE,kBAAkB,EAAuB,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAC9G,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,kBAAkB;IAC9D,kEAAkE;IAClE,QAAQ,EAAE,sBAAsB,CAAC;CAClC;AAED;;;;;;;;GAQG;AACH,qBAAa,gBAAiB,YAAW,UAAU;IACjD,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;IACnD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IAEpD,gBAAgB;gBACJ,IAAI,EAAE,oBAAoB;IAOtC,4CAA4C;IAC5C,IAAW,OAAO,IAAI,MAAM,CAA0B;IAEtD,oDAAoD;IACpD,IAAW,eAAe,IAAI,MAAM,CAAkC;IAEtE,sFAAsF;IACtF,IAAW,MAAM,IAAI,aAAa,GAAG,SAAS,CAAyB;IAEvE,iEAAiE;IACjE,IAAW,aAAa,IAAI,aAAa,GAAG,SAAS,CAA4C;IAEjG,8DAA8D;IAC9D,IAAW,UAAU,IAAI,UAAU,GAAG,SAAS,CAAyC;IAExF;;;;OAIG;IACI,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAOpC;;;OAGG;IACI,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;IAI/B,OAAO,CAAC,SAAS;CAUlB"}
+{"version":3,"file":"FormatSpecHandle.d.ts","sourceRoot":"","sources":["../../src/FormatSpecHandle.ts"],"names":[],"mappings":"AAKA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,KAAK,EAAE,kBAAkB,EAAuB,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAC9G,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,kBAAkB;IAC9D,kEAAkE;IAClE,QAAQ,EAAE,sBAAsB,CAAC;CAClC;AAED;;;;;;;;GAQG;AACH,qBAAa,gBAAiB,YAAW,UAAU;IACjD,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;IACnD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;gBAExC,IAAI,EAAE,oBAAoB;IAOtC,4CAA4C;IAC5C,IAAW,OAAO,IAAI,MAAM,CAA0B;IAEtD,oDAAoD;IACpD,IAAW,eAAe,IAAI,MAAM,CAAkC;IAEtE,sFAAsF;IACtF,IAAW,MAAM,IAAI,aAAa,GAAG,SAAS,CAAyB;IAEvE,iEAAiE;IACjE,IAAW,aAAa,IAAI,aAAa,GAAG,SAAS,CAA4C;IAEjG,8DAA8D;IAC9D,IAAW,UAAU,IAAI,UAAU,GAAG,SAAS,CAAyC;IAExF;;;;OAIG;IACI,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAOpC;;;OAGG;IACI,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;IAI/B,OAAO,CAAC,SAAS;CAUlB"}

package/lib/esm/FormatSpecHandle.js

@@ -17,7 +17,6 @@ export class FormatSpecHandle {
     _koqName;
     _persistenceUnit;
     _system;
-    /** @internal */
     constructor(args) {
         this._provider = args.provider;
         this._koqName = args.name;

package/lib/esm/FormatSpecHandle.js.map

@@ -1 +1 @@
-{"version":3,"file":"FormatSpecHandle.js","sourceRoot":"","sources":["../../src/FormatSpecHandle.ts"],"names":[],"mappings":"AAAA;;;+FAG+F;AAmB/F;;;;;;;;GAQG;AACH,MAAM,OAAO,gBAAgB;IACnB,SAAS,GAAG,KAAK,CAAC;IACT,SAAS,CAAyB;IAClC,QAAQ,CAAS;IACjB,gBAAgB,CAAS;IACzB,OAAO,CAA4B;IAEpD,gBAAgB;IAChB,YAAY,IAA0B;QACpC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC/B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC;QAC1B,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,mBAAmB,CAAC;QACjD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC;IAC7B,CAAC;IAED,4CAA4C;IAC5C,IAAW,OAAO,KAAa,OAAO,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IAEtD,oDAAoD;IACpD,IAAW,eAAe,KAAa,OAAO,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC;IAEtE,sFAAsF;IACtF,IAAW,MAAM,KAAgC,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;IAEvE,iEAAiE;IACjE,IAAW,aAAa,KAAgC,OAAO,IAAI,CAAC,SAAS,EAAE,EAAE,aAAa,CAAC,CAAC,CAAC;IAEjG,8DAA8D;IAC9D,IAAW,UAAU,KAA6B,OAAO,IAAI,CAAC,SAAS,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC;IAExF;;;;OAIG;IACI,MAAM,CAAC,KAAa;QACzB,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC;QACzC,IAAI,CAAC,aAAa;YAChB,OAAO,KAAK,CAAC,QAAQ,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;IAC7D,CAAC;IAED;;;OAGG;IACI,CAAC,MAAM,CAAC,OAAO,CAAC;QACrB,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;IACxB,CAAC;IAEO,SAAS;QACf,IAAI,IAAI,CAAC,SAAS;YAChB,OAAO,SAAS,CAAC;QAEnB,OAAO,IAAI,CAAC,SAAS,CAAC,qBAAqB,CAAC;YAC1C,IAAI,EAAE,IAAI,CAAC,QAAQ;YACnB,mBAAmB,EAAE,IAAI,CAAC,gBAAgB;YAC1C,MAAM,EAAE,IAAI,CAAC,OAAO;SACrB,CAAC,CAAC;IACL,CAAC;CACF","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/** @packageDocumentation\r\n * @module Quantity\r\n */\r\n\r\nimport type { FormatterSpec } from \"./Formatter/FormatterSpec\";\r\nimport type { FormattingSpecArgs, FormattingSpecEntry, FormattingSpecProvider } from \"./Formatter/Interfaces\";\r\nimport type { ParserSpec } from \"./ParserSpec\";\r\nimport type { UnitSystemKey } from \"./Interfaces\";\r\n\r\n/** Arguments for constructing a [[FormatSpecHandle]].\r\n * @internal\r\n */\r\nexport interface FormatSpecHandleArgs extends FormattingSpecArgs {\r\n  /** The provider that supplies current formatting spec lookups. */\r\n  provider: FormattingSpecProvider;\r\n}\r\n\r\n/** A handle to formatting and parsing specs for a specific KoQ and persistence unit.\r\n * Reads the current specs from the provider on access. Use [[QuantityFormatter.getFormatSpecHandle]]\r\n * to create instances.\r\n *\r\n * When formatting is not yet ready, [[format]] returns a `value.toString()` fallback.\r\n * Dispose the handle when it is no longer needed to invalidate it.\r\n *\r\n * @beta\r\n */\r\nexport class FormatSpecHandle implements Disposable {\r\n  private _disposed = false;\r\n  private readonly _provider: FormattingSpecProvider;\r\n  private readonly _koqName: string;\r\n  private readonly _persistenceUnit: string;\r\n  private readonly _system: UnitSystemKey | undefined;\r\n\r\n  /** @internal */\r\n  constructor(args: FormatSpecHandleArgs) {\r\n    this._provider = args.provider;\r\n    this._koqName = args.name;\r\n    this._persistenceUnit = args.persistenceUnitName;\r\n    this._system = args.system;\r\n  }\r\n\r\n  /** The KoQ name this handle is keyed to. */\r\n  public get koqName(): string { return this._koqName; }\r\n\r\n  /** The persistence unit this handle is keyed to. */\r\n  public get persistenceUnit(): string { return this._persistenceUnit; }\r\n\r\n  /** The unit system this handle is pinned to, or `undefined` for the active system. */\r\n  public get system(): UnitSystemKey | undefined { return this._system; }\r\n\r\n  /** The current FormatterSpec, or undefined if not yet loaded. */\r\n  public get formatterSpec(): FormatterSpec | undefined { return this._getEntry()?.formatterSpec; }\r\n\r\n  /** The current ParserSpec, or undefined if not yet loaded. */\r\n  public get parserSpec(): ParserSpec | undefined { return this._getEntry()?.parserSpec; }\r\n\r\n  /** Format a quantity value using the current spec.\r\n   * If the formatter is not yet ready, returns `value.toString()` as a fallback.\r\n   * @param value - The numeric value to format.\r\n   * @returns The formatted string.\r\n   */\r\n  public format(value: number): string {\r\n    const formatterSpec = this.formatterSpec;\r\n    if (!formatterSpec)\r\n      return value.toString();\r\n    return this._provider.formatQuantity(value, formatterSpec);\r\n  }\r\n\r\n  /** Invalidate this handle.\r\n   * Idempotent and safe to call multiple times.\r\n   * No additional teardown is required because the handle owns no external resources.\r\n   */\r\n  public [Symbol.dispose](): void {\r\n    this._disposed = true;\r\n  }\r\n\r\n  private _getEntry(): FormattingSpecEntry | undefined {\r\n    if (this._disposed)\r\n      return undefined;\r\n\r\n    return this._provider.getSpecsByNameAndUnit({\r\n      name: this._koqName,\r\n      persistenceUnitName: this._persistenceUnit,\r\n      system: this._system,\r\n    });\r\n  }\r\n}\r\n"]}
+{"version":3,"file":"FormatSpecHandle.js","sourceRoot":"","sources":["../../src/FormatSpecHandle.ts"],"names":[],"mappings":"AAAA;;;+FAG+F;AAmB/F;;;;;;;;GAQG;AACH,MAAM,OAAO,gBAAgB;IACnB,SAAS,GAAG,KAAK,CAAC;IACT,SAAS,CAAyB;IAClC,QAAQ,CAAS;IACjB,gBAAgB,CAAS;IACzB,OAAO,CAA4B;IAEpD,YAAY,IAA0B;QACpC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC/B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC;QAC1B,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,mBAAmB,CAAC;QACjD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC;IAC7B,CAAC;IAED,4CAA4C;IAC5C,IAAW,OAAO,KAAa,OAAO,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IAEtD,oDAAoD;IACpD,IAAW,eAAe,KAAa,OAAO,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC;IAEtE,sFAAsF;IACtF,IAAW,MAAM,KAAgC,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;IAEvE,iEAAiE;IACjE,IAAW,aAAa,KAAgC,OAAO,IAAI,CAAC,SAAS,EAAE,EAAE,aAAa,CAAC,CAAC,CAAC;IAEjG,8DAA8D;IAC9D,IAAW,UAAU,KAA6B,OAAO,IAAI,CAAC,SAAS,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC;IAExF;;;;OAIG;IACI,MAAM,CAAC,KAAa;QACzB,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC;QACzC,IAAI,CAAC,aAAa;YAChB,OAAO,KAAK,CAAC,QAAQ,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;IAC7D,CAAC;IAED;;;OAGG;IACI,CAAC,MAAM,CAAC,OAAO,CAAC;QACrB,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;IACxB,CAAC;IAEO,SAAS;QACf,IAAI,IAAI,CAAC,SAAS;YAChB,OAAO,SAAS,CAAC;QAEnB,OAAO,IAAI,CAAC,SAAS,CAAC,qBAAqB,CAAC;YAC1C,IAAI,EAAE,IAAI,CAAC,QAAQ;YACnB,mBAAmB,EAAE,IAAI,CAAC,gBAAgB;YAC1C,MAAM,EAAE,IAAI,CAAC,OAAO;SACrB,CAAC,CAAC;IACL,CAAC;CACF","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/** @packageDocumentation\r\n * @module Quantity\r\n */\r\n\r\nimport type { FormatterSpec } from \"./Formatter/FormatterSpec\";\r\nimport type { FormattingSpecArgs, FormattingSpecEntry, FormattingSpecProvider } from \"./Formatter/Interfaces\";\r\nimport type { ParserSpec } from \"./ParserSpec\";\r\nimport type { UnitSystemKey } from \"./Interfaces\";\r\n\r\n/** Arguments for constructing a [[FormatSpecHandle]].\r\n * @beta\r\n */\r\nexport interface FormatSpecHandleArgs extends FormattingSpecArgs {\r\n  /** The provider that supplies current formatting spec lookups. */\r\n  provider: FormattingSpecProvider;\r\n}\r\n\r\n/** A handle to formatting and parsing specs for a specific KoQ and persistence unit.\r\n * Reads the current specs from the provider on access. Use [[QuantityFormatter.getFormatSpecHandle]]\r\n * to create instances.\r\n *\r\n * When formatting is not yet ready, [[format]] returns a `value.toString()` fallback.\r\n * Dispose the handle when it is no longer needed to invalidate it.\r\n *\r\n * @beta\r\n */\r\nexport class FormatSpecHandle implements Disposable {\r\n  private _disposed = false;\r\n  private readonly _provider: FormattingSpecProvider;\r\n  private readonly _koqName: string;\r\n  private readonly _persistenceUnit: string;\r\n  private readonly _system: UnitSystemKey | undefined;\r\n\r\n  constructor(args: FormatSpecHandleArgs) {\r\n    this._provider = args.provider;\r\n    this._koqName = args.name;\r\n    this._persistenceUnit = args.persistenceUnitName;\r\n    this._system = args.system;\r\n  }\r\n\r\n  /** The KoQ name this handle is keyed to. */\r\n  public get koqName(): string { return this._koqName; }\r\n\r\n  /** The persistence unit this handle is keyed to. */\r\n  public get persistenceUnit(): string { return this._persistenceUnit; }\r\n\r\n  /** The unit system this handle is pinned to, or `undefined` for the active system. */\r\n  public get system(): UnitSystemKey | undefined { return this._system; }\r\n\r\n  /** The current FormatterSpec, or undefined if not yet loaded. */\r\n  public get formatterSpec(): FormatterSpec | undefined { return this._getEntry()?.formatterSpec; }\r\n\r\n  /** The current ParserSpec, or undefined if not yet loaded. */\r\n  public get parserSpec(): ParserSpec | undefined { return this._getEntry()?.parserSpec; }\r\n\r\n  /** Format a quantity value using the current spec.\r\n   * If the formatter is not yet ready, returns `value.toString()` as a fallback.\r\n   * @param value - The numeric value to format.\r\n   * @returns The formatted string.\r\n   */\r\n  public format(value: number): string {\r\n    const formatterSpec = this.formatterSpec;\r\n    if (!formatterSpec)\r\n      return value.toString();\r\n    return this._provider.formatQuantity(value, formatterSpec);\r\n  }\r\n\r\n  /** Invalidate this handle.\r\n   * Idempotent and safe to call multiple times.\r\n   * No additional teardown is required because the handle owns no external resources.\r\n   */\r\n  public [Symbol.dispose](): void {\r\n    this._disposed = true;\r\n  }\r\n\r\n  private _getEntry(): FormattingSpecEntry | undefined {\r\n    if (this._disposed)\r\n      return undefined;\r\n\r\n    return this._provider.getSpecsByNameAndUnit({\r\n      name: this._koqName,\r\n      persistenceUnitName: this._persistenceUnit,\r\n      system: this._system,\r\n    });\r\n  }\r\n}\r\n"]}

package/lib/esm/Quantity.d.ts

@@ -31,6 +31,8 @@ export declare class Quantity implements QuantityProps {
      *  @param toUnit   The new unit for the quantity.
      *  @param conversion  Defines the information needed to convert the Quantity's magnitude from the current unit to another unit. This conversion info is usually
      *                     returned from the UnitsProvider.
+     *  @throws [[QuantityError]] with [[QuantityStatus.InvalidUnitConversion]] when `conversion.error === true`.
+     *  @throws [[QuantityError]] with [[QuantityStatus.InvertingZero]] when inversion would require dividing by zero or almost-zero.
      */
     convertTo(toUnit: UnitProps, conversion: UnitConversionProps): Quantity;
 }
@@ -42,6 +44,8 @@ export declare class Quantity implements QuantityProps {
 export declare function almostZero(value: number): boolean;
 /**
  * Applies a unit conversion to a given value.
+ * Does not throw when `props.error === true`; callers are expected to have already handled that contract.
+ * For the throwing apply helper, use `UnitConversions.convertValue(...)`.
  * @param value - The value to be converted.
  * @param props - The unit conversion properties.
  * @returns The converted value.

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

@@ -1 +1 @@
-{"version":3,"file":"Quantity.d.ts","sourceRoot":"","sources":["../../src/Quantity.ts"],"names":[],"mappings":"AAIA;;GAEG;AAGH,OAAO,EAAE,aAAa,EAAwB,mBAAmB,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEnG;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,SAAS,GAAE,MAA+B,GAAG,OAAO,CAIrG;AAED;;;GAGG;AACH,qBAAa,QAAS,YAAW,aAAa;IAC5C,SAAS,CAAC,UAAU,EAAE,MAAM,CAAO;IACnC,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC;IAC3B,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAS;IAEpC,IAAW,IAAI,IAAI,SAAS,CAAuB;IACnD,IAAW,SAAS,IAAI,MAAM,CAA4B;IAC1D,IAAW,OAAO,IAAI,OAAO,CAA0B;IAEvD;;;OAGG;gBACgB,IAAI,CAAC,EAAE,SAAS,EAAE,SAAS,CAAC,EAAE,MAAM;IAYvD;;;;OAIG;IACI,SAAS,CAAC,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,mBAAmB,GAAG,QAAQ;CAI/E;AAQD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,GAAG,MAAM,CAiBjF"}
+{"version":3,"file":"Quantity.d.ts","sourceRoot":"","sources":["../../src/Quantity.ts"],"names":[],"mappings":"AAIA;;GAEG;AAGH,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAG7E;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,SAAS,GAAE,MAA+B,GAAG,OAAO,CAErG;AAED;;;GAGG;AACH,qBAAa,QAAS,YAAW,aAAa;IAC5C,SAAS,CAAC,UAAU,EAAE,MAAM,CAAO;IACnC,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC;IAC3B,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAS;IAEpC,IAAW,IAAI,IAAI,SAAS,CAAuB;IACnD,IAAW,SAAS,IAAI,MAAM,CAA4B;IAC1D,IAAW,OAAO,IAAI,OAAO,CAA0B;IAEvD;;;OAGG;gBACgB,IAAI,CAAC,EAAE,SAAS,EAAE,SAAS,CAAC,EAAE,MAAM;IAYvD;;;;;;OAMG;IACI,SAAS,CAAC,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,mBAAmB,GAAG,QAAQ;CAW/E;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,GAAG,MAAM,CAEjF"}

package/lib/esm/Quantity.js

@@ -6,7 +6,7 @@
  * @module Quantity
  */
 import { QuantityError, QuantityStatus } from "./Exception";
-import { UnitConversionInvert } from "./Interfaces";
+import { applyConversionInternal, convertValueOrThrow, almostEqual as internalAlmostEqual, almostZero as internalAlmostZero } from "./internal/UnitConversionMath";
 /**
  * Checks if two numbers are approximately equal within given relative tolerance.
  * @param a - The first number to compare.
@@ -16,9 +16,7 @@ import { UnitConversionInvert } from "./Interfaces";
  * @internal
  */
 export function almostEqual(a, b, tolerance = 2.2204460492503131e-16) {
-    const absDiff = Math.abs(a - b);
-    const scaledTolerance = Math.max(1, Math.abs(a), Math.abs(b)) * tolerance;
-    return absDiff <= scaledTolerance;
+    return internalAlmostEqual(a, b, tolerance);
 }
 /** The Quantity class is convenient container to specify both the magnitude and unit of a quantity. This class is commonly
  * returned as the result of parsing a string that represents a quantity.
@@ -50,44 +48,35 @@ export class Quantity {
      *  @param toUnit   The new unit for the quantity.
      *  @param conversion  Defines the information needed to convert the Quantity's magnitude from the current unit to another unit. This conversion info is usually
      *                     returned from the UnitsProvider.
+     *  @throws [[QuantityError]] with [[QuantityStatus.InvalidUnitConversion]] when `conversion.error === true`.
+     *  @throws [[QuantityError]] with [[QuantityStatus.InvertingZero]] when inversion would require dividing by zero or almost-zero.
      */
     convertTo(toUnit, conversion) {
-        const newMagnitude = applyConversion(this.magnitude, conversion);
+        if (conversion.error) {
+            throw new QuantityError(QuantityStatus.InvalidUnitConversion, `Cannot convert quantity from "${this.unit.name}" to "${toUnit.name}" using invalid conversion metadata.`);
+        }
+        const newMagnitude = convertValueOrThrow(this.magnitude, conversion);
         return new Quantity(toUnit, newMagnitude);
     }
 }
-function invert(input) {
-    if (almostZero(input)) // mimic the behavior of native here. We don't want to invert those very small values
-        throw new QuantityError(QuantityStatus.InvertingZero, "Cannot invert zero value");
-    return 1 / input;
-}
 /** Determines if a value is almost zero. (less than 1e-16)
  * @param value - The value to be checked.
  * @returns `true` if the value is almost zero, `false` otherwise.
  * @internal
  */
 export function almostZero(value) {
-    return almostEqual(value, 0.0);
+    return internalAlmostZero(value);
 }
 /**
  * Applies a unit conversion to a given value.
+ * Does not throw when `props.error === true`; callers are expected to have already handled that contract.
+ * For the throwing apply helper, use `UnitConversions.convertValue(...)`.
  * @param value - The value to be converted.
  * @param props - The unit conversion properties.
  * @returns The converted value.
  * @internal
  */
 export function applyConversion(value, props) {
-    let convertedValue = value;
-    // Apply pre-conversion inversion if specified
-    if (props.inversion === UnitConversionInvert.InvertPreConversion) {
-        convertedValue = invert(convertedValue);
-    }
-    // Apply the conversion factor and offset
-    convertedValue = (convertedValue * props.factor) + props.offset;
-    // Apply post-conversion inversion if specified
-    if (props.inversion === UnitConversionInvert.InvertPostConversion) {
-        convertedValue = invert(convertedValue);
-    }
-    return convertedValue;
+    return applyConversionInternal(value, props, false);
 }
 //# sourceMappingURL=Quantity.js.map

package/lib/esm/Quantity.js.map

@@ -1 +1 @@
-{"version":3,"file":"Quantity.js","sourceRoot":"","sources":["../../src/Quantity.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\n/** @packageDocumentation\r\n * @module Quantity\r\n */\r\n\r\nimport { QuantityError, QuantityStatus } from \"./Exception\";\r\nimport { QuantityProps, UnitConversionInvert, UnitConversionProps, UnitProps } from \"./Interfaces\";\r\n\r\n/**\r\n * Checks if two numbers are approximately equal within given relative tolerance.\r\n * @param a - The first number to compare.\r\n * @param b - The second number to compare.\r\n * @param tolerance - Tolerance, scales based on the input number values (multiplied by 1, abs(a) or abs(b), whichever is biggest).\r\n * @returns True if the numbers are approximately equal, false otherwise.\r\n * @internal\r\n */\r\nexport function almostEqual(a: number, b: number, tolerance: number = 2.2204460492503131e-16): boolean {\r\n  const absDiff = Math.abs(a - b);\r\n  const scaledTolerance = Math.max(1, Math.abs(a), Math.abs(b)) * tolerance;\r\n  return absDiff <= scaledTolerance;\r\n}\r\n\r\n/** The Quantity class is convenient container to specify both the magnitude and unit of a quantity. This class is commonly\r\n * returned as the result of parsing a string that represents a quantity.\r\n * @beta\r\n */\r\nexport class Quantity implements QuantityProps {\r\n  protected _magnitude: number = 0.0;\r\n  protected _unit: UnitProps;\r\n  protected _isValid: boolean = false;\r\n\r\n  public get unit(): UnitProps { return this._unit; }\r\n  public get magnitude(): number { return this._magnitude; }\r\n  public get isValid(): boolean { return this._isValid; }\r\n\r\n  /** Constructor. The Quantity will only be set as valid if a unit is specified.\r\n   *  @param unit     Defines the quantity's unit.\r\n   *  @param magnitude   Defines the magnitude of the quantity.\r\n   */\r\n  public constructor(unit?: UnitProps, magnitude?: number) {\r\n    if (undefined !== unit) {\r\n      this._unit = unit;\r\n      this._isValid = true;\r\n    } else {\r\n      this._unit = { name: \"unknown\", label: \"unknown\", phenomenon: \"unknown\", isValid: false, system: \"unknown\" };\r\n    }\r\n\r\n    if (undefined !== magnitude)\r\n      this._magnitude = magnitude;\r\n  }\r\n\r\n  /** Convert a Quantity to the specified unit given the UnitConversion.\r\n   *  @param toUnit   The new unit for the quantity.\r\n   *  @param conversion  Defines the information needed to convert the Quantity's magnitude from the current unit to another unit. This conversion info is usually\r\n   *                     returned from the UnitsProvider.\r\n   */\r\n  public convertTo(toUnit: UnitProps, conversion: UnitConversionProps): Quantity {\r\n    const newMagnitude = applyConversion(this.magnitude, conversion);\r\n    return new Quantity(toUnit, newMagnitude);\r\n  }\r\n}\r\n\r\nfunction invert(input: number): number {\r\n  if (almostZero(input)) // mimic the behavior of native here. We don't want to invert those very small values\r\n    throw new QuantityError(QuantityStatus.InvertingZero, \"Cannot invert zero value\");\r\n  return 1 / input;\r\n}\r\n\r\n/** Determines if a value is almost zero. (less than 1e-16)\r\n * @param value - The value to be checked.\r\n * @returns `true` if the value is almost zero, `false` otherwise.\r\n * @internal\r\n */\r\nexport function almostZero(value: number): boolean {\r\n  return almostEqual(value, 0.0);\r\n}\r\n\r\n/**\r\n * Applies a unit conversion to a given value.\r\n * @param value - The value to be converted.\r\n * @param props - The unit conversion properties.\r\n * @returns The converted value.\r\n * @internal\r\n */\r\nexport function applyConversion(value: number, props: UnitConversionProps): number {\r\n  let convertedValue = value;\r\n\r\n  // Apply pre-conversion inversion if specified\r\n  if (props.inversion === UnitConversionInvert.InvertPreConversion) {\r\n    convertedValue = invert(convertedValue);\r\n  }\r\n\r\n  // Apply the conversion factor and offset\r\n  convertedValue = (convertedValue * props.factor) + props.offset;\r\n\r\n  // Apply post-conversion inversion if specified\r\n  if (props.inversion === UnitConversionInvert.InvertPostConversion) {\r\n    convertedValue = invert(convertedValue);\r\n  }\r\n\r\n  return convertedValue;\r\n}\r\n"]}
+{"version":3,"file":"Quantity.js","sourceRoot":"","sources":["../../src/Quantity.ts"],"names":[],"mappings":"AAAA;;;+FAG+F;AAC/F;;GAEG;AAEH,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE5D,OAAO,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,WAAW,IAAI,mBAAmB,EAAE,UAAU,IAAI,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAEnK;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,CAAS,EAAE,CAAS,EAAE,YAAoB,sBAAsB;IAC1F,OAAO,mBAAmB,CAAC,CAAC,EAAE,CAAC,EAAE,SAAS,CAAC,CAAC;AAC9C,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,QAAQ;IACT,UAAU,GAAW,GAAG,CAAC;IACzB,KAAK,CAAY;IACjB,QAAQ,GAAY,KAAK,CAAC;IAEpC,IAAW,IAAI,KAAgB,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACnD,IAAW,SAAS,KAAa,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;IAC1D,IAAW,OAAO,KAAc,OAAO,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IAEvD;;;OAGG;IACH,YAAmB,IAAgB,EAAE,SAAkB;QACrD,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;YACvB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;YAClB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACvB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,KAAK,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;QAC/G,CAAC;QAED,IAAI,SAAS,KAAK,SAAS;YACzB,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;IAChC,CAAC;IAED;;;;;;OAMG;IACI,SAAS,CAAC,MAAiB,EAAE,UAA+B;QACjE,IAAI,UAAU,CAAC,KAAK,EAAE,CAAC;YACrB,MAAM,IAAI,aAAa,CACrB,cAAc,CAAC,qBAAqB,EACpC,iCAAiC,IAAI,CAAC,IAAI,CAAC,IAAI,SAAS,MAAM,CAAC,IAAI,sCAAsC,CAC1G,CAAC;QACJ,CAAC;QAED,MAAM,YAAY,GAAG,mBAAmB,CAAC,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;QACrE,OAAO,IAAI,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC5C,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,kBAAkB,CAAC,KAAK,CAAC,CAAC;AACnC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa,EAAE,KAA0B;IACvE,OAAO,uBAAuB,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;AACtD,CAAC","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/** @packageDocumentation\r\n * @module Quantity\r\n */\r\n\r\nimport { QuantityError, QuantityStatus } from \"./Exception\";\r\nimport { QuantityProps, UnitConversionProps, UnitProps } from \"./Interfaces\";\r\nimport { applyConversionInternal, convertValueOrThrow, almostEqual as internalAlmostEqual, almostZero as internalAlmostZero } from \"./internal/UnitConversionMath\";\r\n\r\n/**\r\n * Checks if two numbers are approximately equal within given relative tolerance.\r\n * @param a - The first number to compare.\r\n * @param b - The second number to compare.\r\n * @param tolerance - Tolerance, scales based on the input number values (multiplied by 1, abs(a) or abs(b), whichever is biggest).\r\n * @returns True if the numbers are approximately equal, false otherwise.\r\n * @internal\r\n */\r\nexport function almostEqual(a: number, b: number, tolerance: number = 2.2204460492503131e-16): boolean {\r\n  return internalAlmostEqual(a, b, tolerance);\r\n}\r\n\r\n/** The Quantity class is convenient container to specify both the magnitude and unit of a quantity. This class is commonly\r\n * returned as the result of parsing a string that represents a quantity.\r\n * @beta\r\n */\r\nexport class Quantity implements QuantityProps {\r\n  protected _magnitude: number = 0.0;\r\n  protected _unit: UnitProps;\r\n  protected _isValid: boolean = false;\r\n\r\n  public get unit(): UnitProps { return this._unit; }\r\n  public get magnitude(): number { return this._magnitude; }\r\n  public get isValid(): boolean { return this._isValid; }\r\n\r\n  /** Constructor. The Quantity will only be set as valid if a unit is specified.\r\n   *  @param unit     Defines the quantity's unit.\r\n   *  @param magnitude   Defines the magnitude of the quantity.\r\n   */\r\n  public constructor(unit?: UnitProps, magnitude?: number) {\r\n    if (undefined !== unit) {\r\n      this._unit = unit;\r\n      this._isValid = true;\r\n    } else {\r\n      this._unit = { name: \"unknown\", label: \"unknown\", phenomenon: \"unknown\", isValid: false, system: \"unknown\" };\r\n    }\r\n\r\n    if (undefined !== magnitude)\r\n      this._magnitude = magnitude;\r\n  }\r\n\r\n  /** Convert a Quantity to the specified unit given the UnitConversion.\r\n   *  @param toUnit   The new unit for the quantity.\r\n   *  @param conversion  Defines the information needed to convert the Quantity's magnitude from the current unit to another unit. This conversion info is usually\r\n   *                     returned from the UnitsProvider.\r\n   *  @throws [[QuantityError]] with [[QuantityStatus.InvalidUnitConversion]] when `conversion.error === true`.\r\n   *  @throws [[QuantityError]] with [[QuantityStatus.InvertingZero]] when inversion would require dividing by zero or almost-zero.\r\n   */\r\n  public convertTo(toUnit: UnitProps, conversion: UnitConversionProps): Quantity {\r\n    if (conversion.error) {\r\n      throw new QuantityError(\r\n        QuantityStatus.InvalidUnitConversion,\r\n        `Cannot convert quantity from \"${this.unit.name}\" to \"${toUnit.name}\" using invalid conversion metadata.`,\r\n      );\r\n    }\r\n\r\n    const newMagnitude = convertValueOrThrow(this.magnitude, conversion);\r\n    return new Quantity(toUnit, newMagnitude);\r\n  }\r\n}\r\n\r\n/** Determines if a value is almost zero. (less than 1e-16)\r\n * @param value - The value to be checked.\r\n * @returns `true` if the value is almost zero, `false` otherwise.\r\n * @internal\r\n */\r\nexport function almostZero(value: number): boolean {\r\n  return internalAlmostZero(value);\r\n}\r\n\r\n/**\r\n * Applies a unit conversion to a given value.\r\n * Does not throw when `props.error === true`; callers are expected to have already handled that contract.\r\n * For the throwing apply helper, use `UnitConversions.convertValue(...)`.\r\n * @param value - The value to be converted.\r\n * @param props - The unit conversion properties.\r\n * @returns The converted value.\r\n * @internal\r\n */\r\nexport function applyConversion(value: number, props: UnitConversionProps): number {\r\n  return applyConversionInternal(value, props, false);\r\n}\r\n\r\n\r\n"]}

package/lib/esm/UnitConversion/UnitConversion.js

@@ -2,7 +2,7 @@
 * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
 * See LICENSE.md in the project root for license terms and full copyright notice.
 *--------------------------------------------------------------------------------------------*/
-import { almostEqual } from "../Quantity";
+import { almostEqual } from "../internal/UnitConversionMath";
 /**
  * Class used for storing calculated conversion between two Units and converting values from one Unit to another.
  * @internal

package/lib/esm/UnitConversion/UnitConversion.js.map

@@ -1 +1 @@
-{"version":3,"file":"UnitConversion.js","sourceRoot":"","sources":["../../../src/UnitConversion/UnitConversion.ts"],"names":[],"mappings":"AAAA;;;+FAG+F;AAC/F,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAc1C;;;GAGG;AACH,MAAM,OAAO,cAAc;IACG;IAAsC;IAAlE,YAA4B,SAAiB,GAAG,EAAkB,SAAiB,GAAG;QAA1D,WAAM,GAAN,MAAM,CAAc;QAAkB,WAAM,GAAN,MAAM,CAAc;IAAG,CAAC;IAE1F;;;;OAIG;IACI,QAAQ,CAAC,CAAS;QACvB,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;IACvC,CAAC;IAED;;;OAGG;IACI,OAAO;QACZ,MAAM,aAAa,GAAG,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC;QACxC,OAAO,IAAI,cAAc,CAAC,aAAa,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,aAAa,CAAC,CAAC;IACzE,CAAC;IAED;;;;OAIG;IACI,OAAO,CAAC,UAA0B;QACvC,OAAO,IAAI,cAAc,CACvB,IAAI,CAAC,MAAM,GAAG,UAAU,CAAC,MAAM,EAC/B,UAAU,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,GAAG,UAAU,CAAC,MAAM,CACpD,CAAC;IACJ,CAAC;IAED;;;OAGG;IACI,QAAQ,CAAC,UAA0B;QACxC,IAAI,WAAW,CAAC,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC;YACtE,OAAO,IAAI,cAAc,CAAC,IAAI,CAAC,MAAM,GAAG,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAElE,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;IACpE,CAAC;IAED;;;OAGG;IACI,KAAK,CAAC,KAAa;QACxB,IAAI,WAAW,CAAC,KAAK,EAAE,GAAG,CAAC;YACzB,OAAO,IAAI,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;aACjD,IAAI,WAAW,CAAC,KAAK,EAAE,GAAG,CAAC;YAC9B,OAAO,IAAI,cAAc,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAEtC,IAAI,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC;YAC/B,OAAO,IAAI,cAAc,CAAC,IAAI,CAAC,MAAM,IAAI,KAAK,EAAE,GAAG,CAAC,CAAC;QAEvD,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAC3D,CAAC;IAED,gBAAgB;IACT,MAAM,CAAC,QAAQ,GAAG,IAAI,cAAc,EAAE,CAAC;IAE9C;;;;OAIG;IACI,MAAM,CAAC,IAAI,CAAC,MAA4B;QAC7C,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC;QAClC,MAAM,SAAS,GAAG,CAAC,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC5C,OAAO,IAAI,cAAc,CAAC,MAAM,CAAC,WAAW,GAAG,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC9F,CAAC","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 { almostEqual } from \"../Quantity\";\r\n\r\n/**\r\n * Structural interface satisfied by any object that carries a numerator/denominator\r\n * factor and an optional offset — for example, the EC `Unit` and `Constant` classes in\r\n * `@itwin/ecschema-metadata`.\r\n * @internal\r\n */\r\nexport interface UnitConversionSource {\r\n  readonly numerator: number;\r\n  readonly denominator: number;\r\n  readonly offset?: number;\r\n}\r\n\r\n/**\r\n * Class used for storing calculated conversion between two Units and converting values from one Unit to another.\r\n * @internal\r\n */\r\nexport class UnitConversion {\r\n  constructor(public readonly factor: number = 1.0, public readonly offset: number = 0.0) {}\r\n\r\n  /**\r\n   * Converts x using UnitConversion\r\n   * @param x Input magnitude to be converted\r\n   * @returns Output magnitude after conversion\r\n   */\r\n  public evaluate(x: number): number {\r\n    return this.factor * x + this.offset;\r\n  }\r\n\r\n  /**\r\n   * Used to invert source's UnitConversion so that it can be composed with target's UnitConversion cleanly\r\n   * @internal\r\n   */\r\n  public inverse(): UnitConversion {\r\n    const inverseFactor = 1.0 / this.factor;\r\n    return new UnitConversion(inverseFactor, -this.offset * inverseFactor);\r\n  }\r\n\r\n  /**\r\n   * Combines two UnitConversions\r\n   * Used to combine source's UnitConversion and target's UnitConversion for a final UnitConversion that can be evaluated\r\n   * @internal\r\n   */\r\n  public compose(conversion: UnitConversion): UnitConversion {\r\n    return new UnitConversion(\r\n      this.factor * conversion.factor,\r\n      conversion.factor * this.offset + conversion.offset,\r\n    );\r\n  }\r\n\r\n  /**\r\n   * Multiples two UnitConversions together to calculate factor during reducing\r\n   * @internal\r\n   */\r\n  public multiply(conversion: UnitConversion): UnitConversion {\r\n    if (almostEqual(conversion.offset, 0.0) && almostEqual(this.offset, 0.0))\r\n      return new UnitConversion(this.factor * conversion.factor, 0.0);\r\n\r\n    throw new Error(\"Cannot multiply two maps with non-zero offsets\");\r\n  }\r\n\r\n  /**\r\n   * Raise UnitConversion's factor with power exponent to calculate factor during reducing\r\n   * @internal\r\n   */\r\n  public raise(power: number): UnitConversion {\r\n    if (almostEqual(power, 1.0))\r\n      return new UnitConversion(this.factor, this.offset);\r\n    else if (almostEqual(power, 0.0))\r\n      return new UnitConversion(1.0, 0.0);\r\n\r\n    if (almostEqual(this.offset, 0.0))\r\n      return new UnitConversion(this.factor ** power, 0.0);\r\n\r\n    throw new Error(\"Cannot raise map with non-zero offset\");\r\n  }\r\n\r\n  /** @internal */\r\n  public static identity = new UnitConversion();\r\n\r\n  /**\r\n   * Returns UnitConversion with source's numerator and denominator in factor and source's offset in offset for reducing.\r\n   * Accepts any object that structurally satisfies `UnitConversionSource` (e.g. EC `Unit` or `Constant`).\r\n   * @internal\r\n   */\r\n  public static from(source: UnitConversionSource): UnitConversion {\r\n    const offset = source.offset ?? 0;\r\n    const hasOffset = !almostEqual(offset, 0.0);\r\n    return new UnitConversion(source.denominator / source.numerator, hasOffset ? -offset : 0.0);\r\n  }\r\n}\r\n"]}
+{"version":3,"file":"UnitConversion.js","sourceRoot":"","sources":["../../../src/UnitConversion/UnitConversion.ts"],"names":[],"mappings":"AAAA;;;+FAG+F;AAC/F,OAAO,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAc7D;;;GAGG;AACH,MAAM,OAAO,cAAc;IACG;IAAsC;IAAlE,YAA4B,SAAiB,GAAG,EAAkB,SAAiB,GAAG;QAA1D,WAAM,GAAN,MAAM,CAAc;QAAkB,WAAM,GAAN,MAAM,CAAc;IAAG,CAAC;IAE1F;;;;OAIG;IACI,QAAQ,CAAC,CAAS;QACvB,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;IACvC,CAAC;IAED;;;OAGG;IACI,OAAO;QACZ,MAAM,aAAa,GAAG,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC;QACxC,OAAO,IAAI,cAAc,CAAC,aAAa,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,aAAa,CAAC,CAAC;IACzE,CAAC;IAED;;;;OAIG;IACI,OAAO,CAAC,UAA0B;QACvC,OAAO,IAAI,cAAc,CACvB,IAAI,CAAC,MAAM,GAAG,UAAU,CAAC,MAAM,EAC/B,UAAU,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,GAAG,UAAU,CAAC,MAAM,CACpD,CAAC;IACJ,CAAC;IAED;;;OAGG;IACI,QAAQ,CAAC,UAA0B;QACxC,IAAI,WAAW,CAAC,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC;YACtE,OAAO,IAAI,cAAc,CAAC,IAAI,CAAC,MAAM,GAAG,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAElE,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;IACpE,CAAC;IAED;;;OAGG;IACI,KAAK,CAAC,KAAa;QACxB,IAAI,WAAW,CAAC,KAAK,EAAE,GAAG,CAAC;YACzB,OAAO,IAAI,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;aACjD,IAAI,WAAW,CAAC,KAAK,EAAE,GAAG,CAAC;YAC9B,OAAO,IAAI,cAAc,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAEtC,IAAI,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC;YAC/B,OAAO,IAAI,cAAc,CAAC,IAAI,CAAC,MAAM,IAAI,KAAK,EAAE,GAAG,CAAC,CAAC;QAEvD,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAC3D,CAAC;IAED,gBAAgB;IACT,MAAM,CAAC,QAAQ,GAAG,IAAI,cAAc,EAAE,CAAC;IAE9C;;;;OAIG;IACI,MAAM,CAAC,IAAI,CAAC,MAA4B;QAC7C,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC;QAClC,MAAM,SAAS,GAAG,CAAC,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC5C,OAAO,IAAI,cAAc,CAAC,MAAM,CAAC,WAAW,GAAG,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC9F,CAAC","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 { almostEqual } from \"../internal/UnitConversionMath\";\r\n\r\n/**\r\n * Structural interface satisfied by any object that carries a numerator/denominator\r\n * factor and an optional offset — for example, the EC `Unit` and `Constant` classes in\r\n * `@itwin/ecschema-metadata`.\r\n * @internal\r\n */\r\nexport interface UnitConversionSource {\r\n  readonly numerator: number;\r\n  readonly denominator: number;\r\n  readonly offset?: number;\r\n}\r\n\r\n/**\r\n * Class used for storing calculated conversion between two Units and converting values from one Unit to another.\r\n * @internal\r\n */\r\nexport class UnitConversion {\r\n  constructor(public readonly factor: number = 1.0, public readonly offset: number = 0.0) {}\r\n\r\n  /**\r\n   * Converts x using UnitConversion\r\n   * @param x Input magnitude to be converted\r\n   * @returns Output magnitude after conversion\r\n   */\r\n  public evaluate(x: number): number {\r\n    return this.factor * x + this.offset;\r\n  }\r\n\r\n  /**\r\n   * Used to invert source's UnitConversion so that it can be composed with target's UnitConversion cleanly\r\n   * @internal\r\n   */\r\n  public inverse(): UnitConversion {\r\n    const inverseFactor = 1.0 / this.factor;\r\n    return new UnitConversion(inverseFactor, -this.offset * inverseFactor);\r\n  }\r\n\r\n  /**\r\n   * Combines two UnitConversions\r\n   * Used to combine source's UnitConversion and target's UnitConversion for a final UnitConversion that can be evaluated\r\n   * @internal\r\n   */\r\n  public compose(conversion: UnitConversion): UnitConversion {\r\n    return new UnitConversion(\r\n      this.factor * conversion.factor,\r\n      conversion.factor * this.offset + conversion.offset,\r\n    );\r\n  }\r\n\r\n  /**\r\n   * Multiples two UnitConversions together to calculate factor during reducing\r\n   * @internal\r\n   */\r\n  public multiply(conversion: UnitConversion): UnitConversion {\r\n    if (almostEqual(conversion.offset, 0.0) && almostEqual(this.offset, 0.0))\r\n      return new UnitConversion(this.factor * conversion.factor, 0.0);\r\n\r\n    throw new Error(\"Cannot multiply two maps with non-zero offsets\");\r\n  }\r\n\r\n  /**\r\n   * Raise UnitConversion's factor with power exponent to calculate factor during reducing\r\n   * @internal\r\n   */\r\n  public raise(power: number): UnitConversion {\r\n    if (almostEqual(power, 1.0))\r\n      return new UnitConversion(this.factor, this.offset);\r\n    else if (almostEqual(power, 0.0))\r\n      return new UnitConversion(1.0, 0.0);\r\n\r\n    if (almostEqual(this.offset, 0.0))\r\n      return new UnitConversion(this.factor ** power, 0.0);\r\n\r\n    throw new Error(\"Cannot raise map with non-zero offset\");\r\n  }\r\n\r\n  /** @internal */\r\n  public static identity = new UnitConversion();\r\n\r\n  /**\r\n   * Returns UnitConversion with source's numerator and denominator in factor and source's offset in offset for reducing.\r\n   * Accepts any object that structurally satisfies `UnitConversionSource` (e.g. EC `Unit` or `Constant`).\r\n   * @internal\r\n   */\r\n  public static from(source: UnitConversionSource): UnitConversion {\r\n    const offset = source.offset ?? 0;\r\n    const hasOffset = !almostEqual(offset, 0.0);\r\n    return new UnitConversion(source.denominator / source.numerator, hasOffset ? -offset : 0.0);\r\n  }\r\n}\r\n"]}

package/lib/esm/UnitConversions.d.ts

@@ -0,0 +1,40 @@
+/** @packageDocumentation
+ * @module Quantity
+ */
+import { type UnitConversionProps } from "./Interfaces";
+import { Phenomena, type PhenomenonName, type UnitName } from "./generated/Units.generated";
+/** Type guard verifying a string is a known canonical built-in unit name.
+ *
+ * Returns true only for unit names shipped in the bundled built-in canonical unit set.
+ * Use this at system boundaries (e.g. when ingesting unit names from JSON config,
+ * iModel metadata, user input, or other dynamic sources) before calling
+ * `UnitConversions.getConversion`, `convert`, or `isCompatible`. Narrows the input
+ * type to `UnitName` so subsequent calls type-check without casts.
+ *
+ * @beta
+ */
+export declare function isUnitName(value: string): value is UnitName;
+/** Returns the package's default built-in persistence unit for a supported bundled built-in phenomenon.
+ *
+ * This helper is intentionally limited to the built-in canonical unit set shipped with `@itwin/core-quantity`.
+ * `Phenomena.LENGTH_RATIO` is intentionally excluded because the bundled built-in unit set does not yet provide an agreed default for that phenomenon.
+ * For schema-defined, custom, or iModel-specific persistence units, use a `UnitsProvider`-based workflow instead.
+ *
+ * @beta
+ */
+export declare function getDefaultPersistenceUnit(phenomenon: Exclude<PhenomenonName, typeof Phenomena.LENGTH_RATIO>): UnitName;
+/** One-stop unit conversion helpers for the built-in canonical unit set generated from `@bentley/units-schema`.
+ * This surface is synchronous and only supports built-in canonical unit names shipped with `core-quantity`.
+ * `getConversion(...)` returns `UnitConversionProps` and uses `error: true` as the compatibility sentinel for known-but-incompatible built-in units.
+ * `convert(...)` and `convertValue(...)` are the throwing application helpers to use when invalid conversion metadata should fail fast.
+ * `isCompatible(...)` is the explicit built-in compatibility check to use before applying a conversion when a non-throwing branch is preferred.
+ * For schema-defined, custom, or provider-resolved units outside that built-in set, use a `UnitsProvider`-based workflow instead.
+ * @beta
+ */
+export declare const UnitConversions: {
+    readonly getConversion: (fromUnit: UnitName, toUnit: UnitName) => UnitConversionProps;
+    readonly convert: (fromUnit: UnitName, toUnit: UnitName, value: number) => number;
+    readonly convertValue: (value: number, conversion: UnitConversionProps) => number;
+    readonly isCompatible: (fromUnit: UnitName, toUnit: UnitName) => boolean;
+};
+//# sourceMappingURL=UnitConversions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"UnitConversions.d.ts","sourceRoot":"","sources":["../../src/UnitConversions.ts"],"names":[],"mappings":"AAIA;;GAEG;AAGH,OAAO,EAAwB,KAAK,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAqC5F;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,QAAQ,CAE3D;AAkED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,OAAO,CAAC,cAAc,EAAE,OAAO,SAAS,CAAC,YAAY,CAAC,GACjE,QAAQ,CAEV;AAED;;;;;;;GAOG;AAEH,eAAO,MAAM,eAAe,EAAE;IAC5B,QAAQ,CAAC,aAAa,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,KAAK,mBAAmB,CAAC;IACtF,QAAQ,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IAClF,QAAQ,CAAC,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,mBAAmB,KAAK,MAAM,CAAC;IAClF,QAAQ,CAAC,YAAY,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,KAAK,OAAO,CAAC;CAM1E,CAAC"}