@itwin/core-quantity 5.10.0-dev.1 → 5.10.0-dev.3

package/lib/esm/Formatter/FormatterSpec.js

@@ -5,6 +5,8 @@
 /** @packageDocumentation
  * @module Quantity
  */
+import { Logger } from "@itwin/core-bentley";
+import { QuantityLoggerCategory } from "../QuantityLoggerCategory";
 import { FormatType } from "./FormatEnums";
 import { Formatter } from "./Formatter";
 // cSpell:ignore ZERONORMALIZED, nosign, onlynegative, signalways, negativeparentheses
@@ -60,6 +62,9 @@ export class FormatterSpec {
         const [denominatorUnit, denominatorLabel] = units[1];
         // Compute ratio scale: how many numerator units per denominator unit (e.g., IN:FT = 12)
         const denominatorToNumerator = await unitsProvider.getConversion(denominatorUnit, numeratorUnit);
+        if (denominatorToNumerator.error) {
+            Logger.logWarning(QuantityLoggerCategory.Formatting, `Unit conversion from "${denominatorUnit.name}" to "${numeratorUnit.name}" could not be resolved.`);
+        }
         const displayRatioScale = denominatorToNumerator.factor;
         // Avoid double-scaling: if persistence unit already encodes the display ratio, use factor 1.
         // Check by name heuristic (e.g., IN_PER_FT with ratioUnits [IN, FT] → no scaling needed)
@@ -119,6 +124,9 @@ export class FormatterSpec {
                 let unitConversion;
                 if (convertFromUnit) {
                     unitConversion = await unitsProvider.getConversion(convertFromUnit, unit[0]);
+                    if (unitConversion.error) {
+                        Logger.logWarning(QuantityLoggerCategory.Formatting, `Unit conversion from "${convertFromUnit.name}" to "${unit[0].name}" could not be resolved.`);
+                    }
                 }
                 else {
                     unitConversion = { factor: 1.0, offset: 0.0 };
@@ -151,6 +159,9 @@ export class FormatterSpec {
         if (format.azimuthBaseUnit !== undefined) {
             if (inputUnit !== undefined) {
                 azimuthBaseConversion = await unitsProvider.getConversion(format.azimuthBaseUnit, inputUnit);
+                if (azimuthBaseConversion.error) {
+                    Logger.logWarning(QuantityLoggerCategory.Formatting, `Unit conversion from "${format.azimuthBaseUnit.name}" to "${inputUnit.name}" could not be resolved.`);
+                }
             }
             else {
                 azimuthBaseConversion = { factor: 1.0, offset: 0.0 };
@@ -160,6 +171,9 @@ export class FormatterSpec {
         if (format.revolutionUnit !== undefined) {
             if (inputUnit !== undefined) {
                 revolutionConversion = await unitsProvider.getConversion(format.revolutionUnit, inputUnit);
+                if (revolutionConversion.error) {
+                    Logger.logWarning(QuantityLoggerCategory.Formatting, `Unit conversion from "${format.revolutionUnit.name}" to "${inputUnit.name}" could not be resolved.`);
+                }
             }
             else {
                 revolutionConversion = { factor: 1.0, offset: 0.0 };

package/lib/esm/Formatter/FormatterSpec.js.map

@@ -1 +1 @@
-{"version":3,"file":"FormatterSpec.js","sourceRoot":"","sources":["../../../src/Formatter/FormatterSpec.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 { UnitConversionProps, UnitConversionSpec, UnitProps, UnitsProvider } from \"../Interfaces\";\r\nimport { Format } from \"./Format\";\r\nimport { FormatType } from \"./FormatEnums\";\r\nimport { Formatter } from \"./Formatter\";\r\n\r\n// cSpell:ignore ZERONORMALIZED, nosign, onlynegative, signalways, negativeparentheses\r\n// cSpell:ignore trailzeroes, keepsinglezero, zeroempty, keepdecimalpoint, applyrounding, fractiondash, showunitlabel, prependunitlabel, exponentonlynegative\r\n\r\n/** A class that contains both formatting information and the conversion factors necessary to convert from an input unit to the units specified in the format.\r\n * Once created the FormatterSpec will be able to format quantity values with synchronous calls.\r\n * @beta\r\n */\r\nexport class FormatterSpec {\r\n  protected _name: string;\r\n  protected _conversions: UnitConversionSpec[] = [];  // max four entries\r\n  protected _format: Format;\r\n  protected _persistenceUnit: UnitProps;\r\n  protected _azimuthBaseConversion?: UnitConversionProps; // converts azimuth base unit to persistence unit\r\n  protected _revolutionConversion?: UnitConversionProps; // converts revolution unit to persistence unit\r\n\r\n  /** Constructor\r\n   *  @param name     The name of a format specification.\r\n   *  @param format   Defines the output format for the quantity value.\r\n   *  @param conversions An array of conversion factors necessary to convert from an input unit to the units specified in the format.\r\n   *  @param persistenceUnit The unit the magnitude value is input.\r\n   *  @param azimuthBaseConversion The conversion used to interpret azimuth base values.\r\n   *  @param revolutionConversion The conversion used to determine a revolution value (used for bearing and azimuth).\r\n   */\r\n  constructor(name: string, format: Format, conversions?: UnitConversionSpec[], persistenceUnit?: UnitProps, azimuthBaseConversion?: UnitConversionProps, revolutionConversion?: UnitConversionProps) {\r\n    if (!persistenceUnit) {\r\n      if (format.units) {\r\n        const [props] = format.units[0];\r\n        persistenceUnit = props;\r\n      } else {\r\n        throw new Error(\"Formatter Spec needs persistence unit to be specified\");\r\n      }\r\n    }\r\n\r\n    this._name = name;\r\n    this._format = format;\r\n    this._persistenceUnit = persistenceUnit;\r\n    if (conversions)\r\n      this._conversions = conversions;\r\n    this._azimuthBaseConversion = azimuthBaseConversion;\r\n    this._revolutionConversion = revolutionConversion;\r\n  }\r\n\r\n  public get name(): string { return this._name; }\r\n  /** Returns an array of UnitConversionSpecs, one for each unit that is to be shown in the formatted quantity string. */\r\n  public get unitConversions(): UnitConversionSpec[] { return this._conversions; }\r\n  public get format(): Format { return this._format; }\r\n  public get persistenceUnit(): UnitProps { return this._persistenceUnit; }\r\n  public get azimuthBaseConversion(): UnitConversionProps | undefined { return this._azimuthBaseConversion; }\r\n  public get revolutionConversion(): UnitConversionProps | undefined { return this._revolutionConversion; }\r\n\r\n  /** Build conversion specs for ratio format with 2 composite units (numerator/denominator). */\r\n  private static async getRatioUnitConversions(units: ReadonlyArray<[UnitProps, string | undefined]>, unitsProvider: UnitsProvider, persistenceUnit: UnitProps): Promise<UnitConversionSpec[]> {\r\n    const conversions: UnitConversionSpec[] = [];\r\n\r\n    const [numeratorUnit, numeratorLabel] = units[0];\r\n    const [denominatorUnit, denominatorLabel] = units[1];\r\n\r\n    // Compute ratio scale: how many numerator units per denominator unit (e.g., IN:FT = 12)\r\n    const denominatorToNumerator = await unitsProvider.getConversion(denominatorUnit, numeratorUnit);\r\n    const displayRatioScale = denominatorToNumerator.factor;\r\n\r\n    // Avoid double-scaling: if persistence unit already encodes the display ratio, use factor 1.\r\n    // Check by name heuristic (e.g., IN_PER_FT with ratioUnits [IN, FT] → no scaling needed)\r\n    const persistenceName = persistenceUnit.name.toUpperCase();\r\n    const numName = numeratorUnit.name.toUpperCase().split(\".\").pop() ?? \"\";\r\n    const denName = denominatorUnit.name.toUpperCase().split(\".\").pop() ?? \"\";\r\n    // Split by word boundaries (underscores, dots) and check for exact token matches\r\n    const persistenceTokens = persistenceName.split(/[._]/);\r\n    const isPersistenceMatchingRatio = persistenceTokens.includes(numName) && persistenceTokens.includes(denName);\r\n    const ratioScaleFactor = isPersistenceMatchingRatio ? 1.0 : displayRatioScale;\r\n\r\n    // First conversion spec: effective ratio unit conversion\r\n    const ratioConversionSpec: UnitConversionSpec = {\r\n      name: `${numeratorUnit.name}_per_${denominatorUnit.name}`,\r\n      label: \"\",\r\n      system: numeratorUnit.system,\r\n      conversion: { factor: ratioScaleFactor, offset: 0.0 },\r\n    };\r\n    conversions.push(ratioConversionSpec);\r\n\r\n    // Numerator unit for label lookup\r\n    const numeratorSpec: UnitConversionSpec = {\r\n      name: numeratorUnit.name,\r\n      label: numeratorLabel?.length ? numeratorLabel : numeratorUnit.label,\r\n      system: numeratorUnit.system,\r\n      conversion: { factor: 1.0, offset: 0.0 },\r\n    };\r\n    conversions.push(numeratorSpec);\r\n\r\n    // Denominator unit for label lookup\r\n    const denominatorSpec: UnitConversionSpec = {\r\n      name: denominatorUnit.name,\r\n      label: denominatorLabel?.length ? denominatorLabel : denominatorUnit.label,\r\n      system: denominatorUnit.system,\r\n      conversion: { factor: 1.0, offset: 0.0 },\r\n    };\r\n    conversions.push(denominatorSpec);\r\n\r\n    return conversions;\r\n  }\r\n\r\n  /** Get an array of UnitConversionSpecs, one for each unit that is to be shown in the formatted quantity string. */\r\n  public static async getUnitConversions(format: Format, unitsProvider: UnitsProvider, inputUnit?: UnitProps): Promise<UnitConversionSpec[]> {\r\n    const conversions: UnitConversionSpec[] = [];\r\n    let persistenceUnit = inputUnit;\r\n    if (!persistenceUnit) {\r\n      if (format.units) {\r\n        const [props] = format.units[0];\r\n        persistenceUnit = props;\r\n      } else {\r\n        throw new Error(\"Formatter Spec needs persistence unit to be specified\");\r\n      }\r\n    }\r\n\r\n    // Handle 2-unit composite for ratio formats (scale factors)\r\n    if (format.type === FormatType.Ratio && format.units && format.units.length === 2) {\r\n      return FormatterSpec.getRatioUnitConversions(format.units, unitsProvider, persistenceUnit);\r\n    }\r\n\r\n    if (format.units) {\r\n      let convertFromUnit = inputUnit;\r\n      for (const unit of format.units) {\r\n        let unitConversion: UnitConversionProps;\r\n        if (convertFromUnit) {\r\n          unitConversion = await unitsProvider.getConversion(convertFromUnit, unit[0]);\r\n        } else {\r\n          unitConversion = { factor: 1.0, offset: 0.0 };\r\n        }\r\n        const unitLabel = (unit[1] && unit[1].length > 0) ? unit[1] : unit[0].label;\r\n        const spec = ({ name: unit[0].name, label: unitLabel, conversion: unitConversion, system: unit[0].system }) as UnitConversionSpec;\r\n\r\n        conversions.push(spec);\r\n        convertFromUnit = unit[0];\r\n      }\r\n    } else {\r\n      // if format is only numeric and a input unit is defined set spec to use the input unit as the format unit\r\n      if (inputUnit) {\r\n        const spec: UnitConversionSpec = { name: inputUnit.name, label: inputUnit.label, system: inputUnit.system, conversion: { factor: 1.0, offset: 0.0 } };\r\n        conversions.push(spec);\r\n      }\r\n    }\r\n\r\n    return conversions;\r\n  }\r\n\r\n  /** Static async method to create a FormatSpec given the format and unit of the quantity that will be passed to the Formatter. The input unit will\r\n   * be used to generate conversion information for each unit specified in the Format. This method is async due to the fact that the units provider must make\r\n   * async calls to lookup unit definitions.\r\n   *  @param name     The name of a format specification.\r\n   *  @param unitsProvider The units provider is used to look up unit definitions and provide conversion information for converting between units.\r\n   *  @param inputUnit The unit the value to be formatted. This unit is often referred to as persistence unit.\r\n   */\r\n  public static async create(name: string, format: Format, unitsProvider: UnitsProvider, inputUnit?: UnitProps): Promise<FormatterSpec> {\r\n    const conversions: UnitConversionSpec[] = await FormatterSpec.getUnitConversions(format, unitsProvider, inputUnit);\r\n    let azimuthBaseConversion: UnitConversionProps | undefined;\r\n    if (format.azimuthBaseUnit !== undefined) {\r\n      if (inputUnit !== undefined) {\r\n        azimuthBaseConversion = await unitsProvider.getConversion(format.azimuthBaseUnit, inputUnit);\r\n      } else {\r\n        azimuthBaseConversion = { factor: 1.0, offset: 0.0 };\r\n      }\r\n    }\r\n    let revolutionConversion: UnitConversionProps | undefined;\r\n    if (format.revolutionUnit !== undefined) {\r\n      if (inputUnit !== undefined) {\r\n        revolutionConversion = await unitsProvider.getConversion(format.revolutionUnit, inputUnit);\r\n      } else {\r\n        revolutionConversion = { factor: 1.0, offset: 0.0 };\r\n      }\r\n    }\r\n\r\n    return new FormatterSpec(name, format, conversions, inputUnit, azimuthBaseConversion, revolutionConversion);\r\n  }\r\n\r\n  /** Format a quantity value. */\r\n  public applyFormatting(magnitude: number): string {\r\n    return Formatter.formatQuantity(magnitude, this);\r\n  }\r\n}\r\n"]}
+{"version":3,"file":"FormatterSpec.js","sourceRoot":"","sources":["../../../src/Formatter/FormatterSpec.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 { Logger } from \"@itwin/core-bentley\";\r\nimport { UnitConversionProps, UnitConversionSpec, UnitProps, UnitsProvider } from \"../Interfaces\";\r\nimport { QuantityLoggerCategory } from \"../QuantityLoggerCategory\";\r\nimport { Format } from \"./Format\";\r\nimport { FormatType } from \"./FormatEnums\";\r\nimport { Formatter } from \"./Formatter\";\r\n\r\n// cSpell:ignore ZERONORMALIZED, nosign, onlynegative, signalways, negativeparentheses\r\n// cSpell:ignore trailzeroes, keepsinglezero, zeroempty, keepdecimalpoint, applyrounding, fractiondash, showunitlabel, prependunitlabel, exponentonlynegative\r\n\r\n/** A class that contains both formatting information and the conversion factors necessary to convert from an input unit to the units specified in the format.\r\n * Once created the FormatterSpec will be able to format quantity values with synchronous calls.\r\n * @beta\r\n */\r\nexport class FormatterSpec {\r\n  protected _name: string;\r\n  protected _conversions: UnitConversionSpec[] = [];  // max four entries\r\n  protected _format: Format;\r\n  protected _persistenceUnit: UnitProps;\r\n  protected _azimuthBaseConversion?: UnitConversionProps; // converts azimuth base unit to persistence unit\r\n  protected _revolutionConversion?: UnitConversionProps; // converts revolution unit to persistence unit\r\n\r\n  /** Constructor\r\n   *  @param name     The name of a format specification.\r\n   *  @param format   Defines the output format for the quantity value.\r\n   *  @param conversions An array of conversion factors necessary to convert from an input unit to the units specified in the format.\r\n   *  @param persistenceUnit The unit the magnitude value is input.\r\n   *  @param azimuthBaseConversion The conversion used to interpret azimuth base values.\r\n   *  @param revolutionConversion The conversion used to determine a revolution value (used for bearing and azimuth).\r\n   */\r\n  constructor(name: string, format: Format, conversions?: UnitConversionSpec[], persistenceUnit?: UnitProps, azimuthBaseConversion?: UnitConversionProps, revolutionConversion?: UnitConversionProps) {\r\n    if (!persistenceUnit) {\r\n      if (format.units) {\r\n        const [props] = format.units[0];\r\n        persistenceUnit = props;\r\n      } else {\r\n        throw new Error(\"Formatter Spec needs persistence unit to be specified\");\r\n      }\r\n    }\r\n\r\n    this._name = name;\r\n    this._format = format;\r\n    this._persistenceUnit = persistenceUnit;\r\n    if (conversions)\r\n      this._conversions = conversions;\r\n    this._azimuthBaseConversion = azimuthBaseConversion;\r\n    this._revolutionConversion = revolutionConversion;\r\n  }\r\n\r\n  public get name(): string { return this._name; }\r\n  /** Returns an array of UnitConversionSpecs, one for each unit that is to be shown in the formatted quantity string. */\r\n  public get unitConversions(): UnitConversionSpec[] { return this._conversions; }\r\n  public get format(): Format { return this._format; }\r\n  public get persistenceUnit(): UnitProps { return this._persistenceUnit; }\r\n  public get azimuthBaseConversion(): UnitConversionProps | undefined { return this._azimuthBaseConversion; }\r\n  public get revolutionConversion(): UnitConversionProps | undefined { return this._revolutionConversion; }\r\n\r\n  /** Build conversion specs for ratio format with 2 composite units (numerator/denominator). */\r\n  private static async getRatioUnitConversions(units: ReadonlyArray<[UnitProps, string | undefined]>, unitsProvider: UnitsProvider, persistenceUnit: UnitProps): Promise<UnitConversionSpec[]> {\r\n    const conversions: UnitConversionSpec[] = [];\r\n\r\n    const [numeratorUnit, numeratorLabel] = units[0];\r\n    const [denominatorUnit, denominatorLabel] = units[1];\r\n\r\n    // Compute ratio scale: how many numerator units per denominator unit (e.g., IN:FT = 12)\r\n    const denominatorToNumerator = await unitsProvider.getConversion(denominatorUnit, numeratorUnit);\r\n    if (denominatorToNumerator.error) {\r\n      Logger.logWarning(QuantityLoggerCategory.Formatting, `Unit conversion from \"${denominatorUnit.name}\" to \"${numeratorUnit.name}\" could not be resolved.`);\r\n    }\r\n    const displayRatioScale = denominatorToNumerator.factor;\r\n\r\n    // Avoid double-scaling: if persistence unit already encodes the display ratio, use factor 1.\r\n    // Check by name heuristic (e.g., IN_PER_FT with ratioUnits [IN, FT] → no scaling needed)\r\n    const persistenceName = persistenceUnit.name.toUpperCase();\r\n    const numName = numeratorUnit.name.toUpperCase().split(\".\").pop() ?? \"\";\r\n    const denName = denominatorUnit.name.toUpperCase().split(\".\").pop() ?? \"\";\r\n    // Split by word boundaries (underscores, dots) and check for exact token matches\r\n    const persistenceTokens = persistenceName.split(/[._]/);\r\n    const isPersistenceMatchingRatio = persistenceTokens.includes(numName) && persistenceTokens.includes(denName);\r\n    const ratioScaleFactor = isPersistenceMatchingRatio ? 1.0 : displayRatioScale;\r\n\r\n    // First conversion spec: effective ratio unit conversion\r\n    const ratioConversionSpec: UnitConversionSpec = {\r\n      name: `${numeratorUnit.name}_per_${denominatorUnit.name}`,\r\n      label: \"\",\r\n      system: numeratorUnit.system,\r\n      conversion: { factor: ratioScaleFactor, offset: 0.0 },\r\n    };\r\n    conversions.push(ratioConversionSpec);\r\n\r\n    // Numerator unit for label lookup\r\n    const numeratorSpec: UnitConversionSpec = {\r\n      name: numeratorUnit.name,\r\n      label: numeratorLabel?.length ? numeratorLabel : numeratorUnit.label,\r\n      system: numeratorUnit.system,\r\n      conversion: { factor: 1.0, offset: 0.0 },\r\n    };\r\n    conversions.push(numeratorSpec);\r\n\r\n    // Denominator unit for label lookup\r\n    const denominatorSpec: UnitConversionSpec = {\r\n      name: denominatorUnit.name,\r\n      label: denominatorLabel?.length ? denominatorLabel : denominatorUnit.label,\r\n      system: denominatorUnit.system,\r\n      conversion: { factor: 1.0, offset: 0.0 },\r\n    };\r\n    conversions.push(denominatorSpec);\r\n\r\n    return conversions;\r\n  }\r\n\r\n  /** Get an array of UnitConversionSpecs, one for each unit that is to be shown in the formatted quantity string. */\r\n  public static async getUnitConversions(format: Format, unitsProvider: UnitsProvider, inputUnit?: UnitProps): Promise<UnitConversionSpec[]> {\r\n    const conversions: UnitConversionSpec[] = [];\r\n    let persistenceUnit = inputUnit;\r\n    if (!persistenceUnit) {\r\n      if (format.units) {\r\n        const [props] = format.units[0];\r\n        persistenceUnit = props;\r\n      } else {\r\n        throw new Error(\"Formatter Spec needs persistence unit to be specified\");\r\n      }\r\n    }\r\n\r\n    // Handle 2-unit composite for ratio formats (scale factors)\r\n    if (format.type === FormatType.Ratio && format.units && format.units.length === 2) {\r\n      return FormatterSpec.getRatioUnitConversions(format.units, unitsProvider, persistenceUnit);\r\n    }\r\n\r\n    if (format.units) {\r\n      let convertFromUnit = inputUnit;\r\n      for (const unit of format.units) {\r\n        let unitConversion: UnitConversionProps;\r\n        if (convertFromUnit) {\r\n          unitConversion = await unitsProvider.getConversion(convertFromUnit, unit[0]);\r\n          if (unitConversion.error) {\r\n            Logger.logWarning(QuantityLoggerCategory.Formatting, `Unit conversion from \"${convertFromUnit.name}\" to \"${unit[0].name}\" could not be resolved.`);\r\n          }\r\n        } else {\r\n          unitConversion = { factor: 1.0, offset: 0.0 };\r\n        }\r\n        const unitLabel = (unit[1] && unit[1].length > 0) ? unit[1] : unit[0].label;\r\n        const spec = ({ name: unit[0].name, label: unitLabel, conversion: unitConversion, system: unit[0].system }) as UnitConversionSpec;\r\n\r\n        conversions.push(spec);\r\n        convertFromUnit = unit[0];\r\n      }\r\n    } else {\r\n      // if format is only numeric and a input unit is defined set spec to use the input unit as the format unit\r\n      if (inputUnit) {\r\n        const spec: UnitConversionSpec = { name: inputUnit.name, label: inputUnit.label, system: inputUnit.system, conversion: { factor: 1.0, offset: 0.0 } };\r\n        conversions.push(spec);\r\n      }\r\n    }\r\n\r\n    return conversions;\r\n  }\r\n\r\n  /** Static async method to create a FormatSpec given the format and unit of the quantity that will be passed to the Formatter. The input unit will\r\n   * be used to generate conversion information for each unit specified in the Format. This method is async due to the fact that the units provider must make\r\n   * async calls to lookup unit definitions.\r\n   *  @param name     The name of a format specification.\r\n   *  @param unitsProvider The units provider is used to look up unit definitions and provide conversion information for converting between units.\r\n   *  @param inputUnit The unit the value to be formatted. This unit is often referred to as persistence unit.\r\n   */\r\n  public static async create(name: string, format: Format, unitsProvider: UnitsProvider, inputUnit?: UnitProps): Promise<FormatterSpec> {\r\n    const conversions: UnitConversionSpec[] = await FormatterSpec.getUnitConversions(format, unitsProvider, inputUnit);\r\n    let azimuthBaseConversion: UnitConversionProps | undefined;\r\n    if (format.azimuthBaseUnit !== undefined) {\r\n      if (inputUnit !== undefined) {\r\n        azimuthBaseConversion = await unitsProvider.getConversion(format.azimuthBaseUnit, inputUnit);\r\n        if (azimuthBaseConversion.error) {\r\n          Logger.logWarning(QuantityLoggerCategory.Formatting, `Unit conversion from \"${format.azimuthBaseUnit.name}\" to \"${inputUnit.name}\" could not be resolved.`);\r\n        }\r\n      } else {\r\n        azimuthBaseConversion = { factor: 1.0, offset: 0.0 };\r\n      }\r\n    }\r\n    let revolutionConversion: UnitConversionProps | undefined;\r\n    if (format.revolutionUnit !== undefined) {\r\n      if (inputUnit !== undefined) {\r\n        revolutionConversion = await unitsProvider.getConversion(format.revolutionUnit, inputUnit);\r\n        if (revolutionConversion.error) {\r\n          Logger.logWarning(QuantityLoggerCategory.Formatting, `Unit conversion from \"${format.revolutionUnit.name}\" to \"${inputUnit.name}\" could not be resolved.`);\r\n        }\r\n      } else {\r\n        revolutionConversion = { factor: 1.0, offset: 0.0 };\r\n      }\r\n    }\r\n\r\n    return new FormatterSpec(name, format, conversions, inputUnit, azimuthBaseConversion, revolutionConversion);\r\n  }\r\n\r\n  /** Format a quantity value. */\r\n  public applyFormatting(magnitude: number): string {\r\n    return Formatter.formatQuantity(magnitude, this);\r\n  }\r\n}\r\n"]}

package/lib/esm/Interfaces.d.ts

@@ -66,6 +66,13 @@ export interface UnitConversionProps {
     offset: number;
     /** If set, inverts the unit value (1/x) before or after conversion. */
     inversion?: UnitConversionInvert;
+    /**
+     * If `true`, the conversion could not be resolved (e.g. unknown unit, incompatible phenomena).
+     * When `error` is `true`, `factor` MUST be `1.0` and `offset` MUST be `0.0` (identity).
+     * Callers must check this flag before applying the conversion — applying an identity conversion
+     * silently produces wrong output.
+     */
+    error?: boolean;
 }
 /** Interface that defines potential parse units that may be found in user's string input of a quantity value.
  * @beta
@@ -90,6 +97,13 @@ export interface UnitsProvider {
     findUnit(unitLabel: string, schemaName?: string, phenomenon?: string, unitSystem?: string): Promise<UnitProps>;
     getUnitsByFamily(phenomenon: string): Promise<UnitProps[]>;
     findUnitByName(unitName: string): Promise<UnitProps>;
+    /**
+     * Compute the conversion factors from `fromUnit` to `toUnit`.
+     * On failure (unknown unit, incompatible phenomena), implementations MUST return
+     * `{ factor: 1.0, offset: 0.0, error: true }`. Throwing is also permitted;
+     * composite providers treat a throw as equivalent to `error: true`.
+     * Callers MUST check `result.error` before applying the conversion.
+     */
     getConversion(fromUnit: UnitProps, toUnit: UnitProps): Promise<UnitConversionProps>;
 }
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"Interfaces.d.ts","sourceRoot":"","sources":["../../src/Interfaces.ts"],"names":[],"mappings":"AAIA;;GAEG;AAEH;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,sBAAsB,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,MAAM,EAAE,GAAG,SAAS,CAAC;CACnE;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,4BAA4B;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8BAA8B;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,wHAAwH;IACxH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,uGAAuG;IACvG,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,UAAU,EAAE,mBAAmB,CAAC;IAChC,sFAAsF;IACtF,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,oBAAY,oBAAoB;IAC9B,mGAAmG;IACnG,mBAAmB,wBAAwB;IAC3C,gGAAgG;IAChG,oBAAoB,yBAAyB;CAC9C;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,SAAS,CAAC,EAAE,oBAAoB,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC;CACrC;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,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,CAAC;IAC/G,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IAC3D,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IACrD,aAAa,CAAC,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACrF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,UAAU,GAAG,aAAa,GAAG,UAAU,CAAC"}
+{"version":3,"file":"Interfaces.d.ts","sourceRoot":"","sources":["../../src/Interfaces.ts"],"names":[],"mappings":"AAIA;;GAEG;AAEH;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,sBAAsB,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,MAAM,EAAE,GAAG,SAAS,CAAC;CACnE;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,4BAA4B;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8BAA8B;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,wHAAwH;IACxH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,uGAAuG;IACvG,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,UAAU,EAAE,mBAAmB,CAAC;IAChC,sFAAsF;IACtF,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,oBAAY,oBAAoB;IAC9B,mGAAmG;IACnG,mBAAmB,wBAAwB;IAC3C,gGAAgG;IAChG,oBAAoB,yBAAyB;CAC9C;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,SAAS,CAAC,EAAE,oBAAoB,CAAC;IACjC;;;;;OAKG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC;CACrC;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,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,CAAC;IAC/G,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IAC3D,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IACrD;;;;;;OAMG;IACH,aAAa,CAAC,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACrF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,UAAU,GAAG,aAAa,GAAG,UAAU,CAAC"}

package/lib/esm/Interfaces.js.map

@@ -1 +1 @@
-{"version":3,"file":"Interfaces.js","sourceRoot":"","sources":["../../src/Interfaces.ts"],"names":[],"mappings":"AAAA;;;+FAG+F;AAC/F;;GAEG;AAmDH;;GAEG;AACH,MAAM,CAAN,IAAY,oBAKX;AALD,WAAY,oBAAoB;IAC9B,mGAAmG;IACnG,mEAA2C,CAAA;IAC3C,gGAAgG;IAChG,qEAA6C,CAAA;AAC/C,CAAC,EALW,oBAAoB,KAApB,oBAAoB,QAK/B","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\n/** This interface allows a provider to be specified that will define an array of alternate labels for a specific unit.\r\n * @beta\r\n */\r\nexport interface AlternateUnitLabelsProvider {\r\n  getAlternateUnitLabels: (unit: UnitProps) => string[] | undefined;\r\n}\r\n\r\n/** This interface provides basic information about a Unit that is return from a UnitProvider. This info\r\n * uniquely identifies a unit by its name.\r\n * @beta\r\n */\r\nexport interface UnitProps {\r\n  /** Unique name for unit. */\r\n  readonly name: string;\r\n  /** Default label for unit. */\r\n  readonly label: string;\r\n  /** Unique name of unit phenomenon. Example phenomenon names include 'Units.LENGTH', 'Units.AREA', and 'Units.VOLUME' */\r\n  readonly phenomenon: string;\r\n  /** This is set to true if the Unit is known by the UnitsProvider. */\r\n  readonly isValid: boolean;\r\n  /** Unique system name. Example \"Units.USCUSTOM\",\" Units.METRIC\", \"Units.USSURVEY\", \"Units.IMPERIAL\" */\r\n  readonly system: string;\r\n}\r\n\r\n/** This interface defines the required properties of a Quantity.\r\n * @beta\r\n */\r\nexport interface QuantityProps {\r\n  readonly magnitude: number;\r\n  readonly unit: UnitProps;\r\n  readonly isValid: boolean;\r\n}\r\n\r\n/** Interface that defines how to convert between a specific unit an another in synchronous formatting or parsing processing.\r\n * @beta\r\n */\r\nexport interface UnitConversionSpec {\r\n  /** Unit name that was used to locate the unit by the Unit Provider */\r\n  name: string;\r\n  /** The default label that is used to display unit */\r\n  label: string;\r\n  /** Unit system name, used to when finding preferred parse unit */\r\n  system: string;\r\n  /** the information necessary to convert the unit to a specific display unit */\r\n  conversion: UnitConversionProps;\r\n  /** Labels that may be used to represent the unit in a string that is to be parsed. */\r\n  parseLabels?: string[];\r\n}\r\n\r\n/** Indicates the way in which unit values are inverted during conversion\r\n * @beta\r\n */\r\nexport enum UnitConversionInvert {\r\n  /** Invert value before applying the other conversion steps (the from-unit is the inverted unit) */\r\n  InvertPreConversion = \"InvertPreConversion\",\r\n  /** Invert value after applying the other conversion steps (the to-unit is the inverted unit) */\r\n  InvertPostConversion = \"InvertPostConversion\"\r\n}\r\n\r\n/** This interface defines the properties required to convert a quantity value from one unit to another such as from meters to feet\r\n * or from Celsius to Fahrenheit.\r\n * @beta\r\n */\r\nexport interface UnitConversionProps {\r\n  /** The factor to multiply the input value by to convert to the output value. */\r\n  factor: number;\r\n  /** The offset to add to the input value to convert to the output value. */\r\n  offset: number;\r\n  /** If set, inverts the unit value (1/x) before or after conversion. */\r\n  inversion?: UnitConversionInvert;\r\n}\r\n\r\n/** Interface that defines potential parse units that may be found in user's string input of a quantity value.\r\n * @beta\r\n */\r\nexport interface PotentialParseUnit {\r\n  unitName: string;\r\n  altLabels?: string[];\r\n}\r\n\r\n/**\r\n * This interface defines extra properties to be associated with Units from Units Schema by name\r\n * @alpha\r\n */\r\nexport interface UnitExtraData {\r\n  readonly name: string;\r\n  readonly altDisplayLabels: string[];\r\n}\r\n\r\n/** This interface is implemented by the class that is responsible for locating units by name or label and providing conversion values between units.\r\n * The methods to be implemented are async allowing the UnitsProvider to query the backend when necessary to look up unit definition and conversion rules.\r\n * @beta\r\n */\r\nexport interface UnitsProvider {\r\n  findUnit(unitLabel: string, schemaName?: string, phenomenon?: string, unitSystem?: string): Promise<UnitProps>;\r\n  getUnitsByFamily(phenomenon: string): Promise<UnitProps[]>;\r\n  findUnitByName(unitName: string): Promise<UnitProps>;\r\n  getConversion(fromUnit: UnitProps, toUnit: UnitProps): Promise<UnitConversionProps>;\r\n}\r\n\r\n/**\r\n * Identifies a user-facing unit system preference group.\r\n *\r\n * A `UnitSystemKey` does **not** map one-to-one to an EC `UnitSystem` element. Instead, each key\r\n * represents a *preference group* that matches against one or more EC `UnitSystem` names in\r\n * priority order when resolving formats from a `KindOfQuantity`:\r\n *\r\n * | Key            | EC UnitSystems matched (highest priority first)         |\r\n * | -------------- | ------------------------------------------------------- |\r\n * | `\"metric\"`     | SI / METRIC, INTERNATIONAL, FINANCE                     |\r\n * | `\"imperial\"`   | IMPERIAL, USCUSTOM, INTERNATIONAL, FINANCE               |\r\n * | `\"usCustomary\"`| USCUSTOM, INTERNATIONAL, FINANCE                         |\r\n * | `\"usSurvey\"`   | USSURVEY, USCUSTOM, INTERNATIONAL, FINANCE               |\r\n *\r\n * EC `UnitSystem` elements not listed above (e.g. CGS, MARITIME, INDUSTRIAL) are not covered by\r\n * any preference group and will only appear if a `KindOfQuantity` explicitly references them.\r\n *\r\n * @see [SchemaFormatsProvider]($ecschema-metadata) for how preference groups resolve formats.\r\n * @beta\r\n */\r\nexport type UnitSystemKey = \"metric\" | \"imperial\" | \"usCustomary\" | \"usSurvey\";\r\n"]}
+{"version":3,"file":"Interfaces.js","sourceRoot":"","sources":["../../src/Interfaces.ts"],"names":[],"mappings":"AAAA;;;+FAG+F;AAC/F;;GAEG;AAmDH;;GAEG;AACH,MAAM,CAAN,IAAY,oBAKX;AALD,WAAY,oBAAoB;IAC9B,mGAAmG;IACnG,mEAA2C,CAAA;IAC3C,gGAAgG;IAChG,qEAA6C,CAAA;AAC/C,CAAC,EALW,oBAAoB,KAApB,oBAAoB,QAK/B","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\n/** This interface allows a provider to be specified that will define an array of alternate labels for a specific unit.\r\n * @beta\r\n */\r\nexport interface AlternateUnitLabelsProvider {\r\n  getAlternateUnitLabels: (unit: UnitProps) => string[] | undefined;\r\n}\r\n\r\n/** This interface provides basic information about a Unit that is return from a UnitProvider. This info\r\n * uniquely identifies a unit by its name.\r\n * @beta\r\n */\r\nexport interface UnitProps {\r\n  /** Unique name for unit. */\r\n  readonly name: string;\r\n  /** Default label for unit. */\r\n  readonly label: string;\r\n  /** Unique name of unit phenomenon. Example phenomenon names include 'Units.LENGTH', 'Units.AREA', and 'Units.VOLUME' */\r\n  readonly phenomenon: string;\r\n  /** This is set to true if the Unit is known by the UnitsProvider. */\r\n  readonly isValid: boolean;\r\n  /** Unique system name. Example \"Units.USCUSTOM\",\" Units.METRIC\", \"Units.USSURVEY\", \"Units.IMPERIAL\" */\r\n  readonly system: string;\r\n}\r\n\r\n/** This interface defines the required properties of a Quantity.\r\n * @beta\r\n */\r\nexport interface QuantityProps {\r\n  readonly magnitude: number;\r\n  readonly unit: UnitProps;\r\n  readonly isValid: boolean;\r\n}\r\n\r\n/** Interface that defines how to convert between a specific unit an another in synchronous formatting or parsing processing.\r\n * @beta\r\n */\r\nexport interface UnitConversionSpec {\r\n  /** Unit name that was used to locate the unit by the Unit Provider */\r\n  name: string;\r\n  /** The default label that is used to display unit */\r\n  label: string;\r\n  /** Unit system name, used to when finding preferred parse unit */\r\n  system: string;\r\n  /** the information necessary to convert the unit to a specific display unit */\r\n  conversion: UnitConversionProps;\r\n  /** Labels that may be used to represent the unit in a string that is to be parsed. */\r\n  parseLabels?: string[];\r\n}\r\n\r\n/** Indicates the way in which unit values are inverted during conversion\r\n * @beta\r\n */\r\nexport enum UnitConversionInvert {\r\n  /** Invert value before applying the other conversion steps (the from-unit is the inverted unit) */\r\n  InvertPreConversion = \"InvertPreConversion\",\r\n  /** Invert value after applying the other conversion steps (the to-unit is the inverted unit) */\r\n  InvertPostConversion = \"InvertPostConversion\"\r\n}\r\n\r\n/** This interface defines the properties required to convert a quantity value from one unit to another such as from meters to feet\r\n * or from Celsius to Fahrenheit.\r\n * @beta\r\n */\r\nexport interface UnitConversionProps {\r\n  /** The factor to multiply the input value by to convert to the output value. */\r\n  factor: number;\r\n  /** The offset to add to the input value to convert to the output value. */\r\n  offset: number;\r\n  /** If set, inverts the unit value (1/x) before or after conversion. */\r\n  inversion?: UnitConversionInvert;\r\n  /**\r\n   * If `true`, the conversion could not be resolved (e.g. unknown unit, incompatible phenomena).\r\n   * When `error` is `true`, `factor` MUST be `1.0` and `offset` MUST be `0.0` (identity).\r\n   * Callers must check this flag before applying the conversion — applying an identity conversion\r\n   * silently produces wrong output.\r\n   */\r\n  error?: boolean;\r\n}\r\n\r\n/** Interface that defines potential parse units that may be found in user's string input of a quantity value.\r\n * @beta\r\n */\r\nexport interface PotentialParseUnit {\r\n  unitName: string;\r\n  altLabels?: string[];\r\n}\r\n\r\n/**\r\n * This interface defines extra properties to be associated with Units from Units Schema by name\r\n * @alpha\r\n */\r\nexport interface UnitExtraData {\r\n  readonly name: string;\r\n  readonly altDisplayLabels: string[];\r\n}\r\n\r\n/** This interface is implemented by the class that is responsible for locating units by name or label and providing conversion values between units.\r\n * The methods to be implemented are async allowing the UnitsProvider to query the backend when necessary to look up unit definition and conversion rules.\r\n * @beta\r\n */\r\nexport interface UnitsProvider {\r\n  findUnit(unitLabel: string, schemaName?: string, phenomenon?: string, unitSystem?: string): Promise<UnitProps>;\r\n  getUnitsByFamily(phenomenon: string): Promise<UnitProps[]>;\r\n  findUnitByName(unitName: string): Promise<UnitProps>;\r\n  /**\r\n   * Compute the conversion factors from `fromUnit` to `toUnit`.\r\n   * On failure (unknown unit, incompatible phenomena), implementations MUST return\r\n   * `{ factor: 1.0, offset: 0.0, error: true }`. Throwing is also permitted;\r\n   * composite providers treat a throw as equivalent to `error: true`.\r\n   * Callers MUST check `result.error` before applying the conversion.\r\n   */\r\n  getConversion(fromUnit: UnitProps, toUnit: UnitProps): Promise<UnitConversionProps>;\r\n}\r\n\r\n/**\r\n * Identifies a user-facing unit system preference group.\r\n *\r\n * A `UnitSystemKey` does **not** map one-to-one to an EC `UnitSystem` element. Instead, each key\r\n * represents a *preference group* that matches against one or more EC `UnitSystem` names in\r\n * priority order when resolving formats from a `KindOfQuantity`:\r\n *\r\n * | Key            | EC UnitSystems matched (highest priority first)         |\r\n * | -------------- | ------------------------------------------------------- |\r\n * | `\"metric\"`     | SI / METRIC, INTERNATIONAL, FINANCE                     |\r\n * | `\"imperial\"`   | IMPERIAL, USCUSTOM, INTERNATIONAL, FINANCE               |\r\n * | `\"usCustomary\"`| USCUSTOM, INTERNATIONAL, FINANCE                         |\r\n * | `\"usSurvey\"`   | USSURVEY, USCUSTOM, INTERNATIONAL, FINANCE               |\r\n *\r\n * EC `UnitSystem` elements not listed above (e.g. CGS, MARITIME, INDUSTRIAL) are not covered by\r\n * any preference group and will only appear if a `KindOfQuantity` explicitly references them.\r\n *\r\n * @see [SchemaFormatsProvider]($ecschema-metadata) for how preference groups resolve formats.\r\n * @beta\r\n */\r\nexport type UnitSystemKey = \"metric\" | \"imperial\" | \"usCustomary\" | \"usSurvey\";\r\n"]}

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

@@ -1 +1 @@
-{"version":3,"file":"Parser.d.ts","sourceRoot":"","sources":["../../src/Parser.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Parser.d.ts","sourceRoot":"","sources":["../../src/Parser.ts"],"names":[],"mappings":"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"}

package/lib/esm/Parser.js

@@ -5,9 +5,11 @@
 /** @packageDocumentation
  * @module Quantity
  */
+import { Logger } from "@itwin/core-bentley";
 import { QuantityConstants } from "./Constants";
 import { QuantityError, QuantityStatus } from "./Exception";
 import { FormatTraits, FormatType } from "./Formatter/FormatEnums";
+import { QuantityLoggerCategory } from "./QuantityLoggerCategory";
 import { applyConversion, Quantity } from "./Quantity";
 /** Possible parser errors
  * @beta
@@ -388,6 +390,9 @@ export class Parser {
             else {
                 // Add new conversion to the list.
                 const conversion = await unitsProvider.getConversion(unitProps, outUnit);
+                if (conversion.error) {
+                    Logger.logWarning(QuantityLoggerCategory.Parsing, `Unit conversion from "${unitProps.name}" to "${outUnit.name}" could not be resolved.`);
+                }
                 if (conversion) {
                     spec = {
                         conversion,
@@ -408,7 +413,11 @@ export class Parser {
     static async createQuantityFromParseTokens(tokens, format, unitsProvider, altUnitLabelsProvider) {
         const unitConversionInfos = await this.getRequiredUnitsConversionsToParseTokens(tokens, format, unitsProvider, altUnitLabelsProvider);
         if (unitConversionInfos.outUnit) {
-            const value = Parser.getQuantityValueFromParseTokens(tokens, format, unitConversionInfos.specs, await unitsProvider.getConversion(unitConversionInfos.outUnit, unitConversionInfos.outUnit));
+            const outUnitConversion = await unitsProvider.getConversion(unitConversionInfos.outUnit, unitConversionInfos.outUnit);
+            if (outUnitConversion.error) {
+                Logger.logWarning(QuantityLoggerCategory.Parsing, `Unit conversion from "${unitConversionInfos.outUnit.name}" to "${unitConversionInfos.outUnit.name}" could not be resolved.`);
+            }
+            const value = Parser.getQuantityValueFromParseTokens(tokens, format, unitConversionInfos.specs, outUnitConversion);
             if (value.ok) {
                 return new Quantity(unitConversionInfos.outUnit, value.value);
             }
@@ -943,6 +952,9 @@ export class Parser {
         const familyUnits = await unitsProvider.getUnitsByFamily(outUnit.phenomenon);
         for (const unit of familyUnits) {
             const conversion = await unitsProvider.getConversion(unit, outUnit);
+            if (conversion.error) {
+                Logger.logWarning(QuantityLoggerCategory.Parsing, `Unit conversion from "${unit.name}" to "${outUnit.name}" could not be resolved.`);
+            }
             const parseLabels = [unit.label.toLocaleLowerCase()];
             const alternateLabels = altUnitLabelsProvider?.getAlternateUnitLabels(unit);
             // add any alternate labels that may be defined for the Unit
@@ -980,6 +992,9 @@ export class Parser {
                 continue;
             }
             const conversion = await unitsProvider.getConversion(unit, outUnit);
+            if (conversion.error) {
+                Logger.logWarning(QuantityLoggerCategory.Parsing, `Unit conversion from "${unit.name}" to "${outUnit.name}" could not be resolved.`);
+            }
             const parseLabels = [unit.label.toLocaleLowerCase()];
             const alternateLabels = altUnitLabelsProvider?.getAlternateUnitLabels(unit);
             // add any alternate labels that may be defined for the Unit