Units

Package for converting and formatting units and numerical values.

v1.1.0

npm install @dynatrace-sdk/units

Conversion example

Code example

import { convert, units } from "@dynatrace-sdk/units";

convert(1000,
  // units.<category>.<unit>
  units.length.meter, // FromUnit
  units.length.kilometer, // ToUnit
);  // 1

Functions

abbreviateNumber

abbreviateNumber(input,scale,options): Object

Abbreviate large numbers to a shorter format. Example:

import { abbreviateNumber } from '@dynatrace-sdk/units';
abbreviateNumber(1500) // {"formattedValue": "2", "postfix": "k"}

Parameters

Name Type Description

input^*required number Number to be abbreviated.

Name	Type	Description
input^*required	number	Number to be abbreviated.
scale^*required	Scale	Scale to use for the abbreviation. Default is the decimal scale: `abbreviateNumber(1_000) // {"formattedValue": "1", "postfix": "k"}` `abbreviateNumber(1_000_000, ExponentialOctalByteLevels) // {"formattedValue": "977", "postfix": "KiB"}`
options^*required	AdjustFractionDigitsOptions

scale^*required

Scale

Scale to use for the abbreviation. Default is the decimal scale:

abbreviateNumber(1_000) // {"formattedValue": "1", "postfix": "k"}
abbreviateNumber(1_000_000, ExponentialOctalByteLevels) // {"formattedValue": "977", "postfix": "KiB"}

options^*required AdjustFractionDigitsOptions

adjustFractionDigits

adjustFractionDigits(input,options?): string

Adjust number of fractional digits.

Parameters

Name	Type	Description
input^*required	number	The number to be formatted.
options	AdjustFractionDigitsOptions

Returns

Description
The formatted number as a string.

convert

convert(input,from,to): number

Converts a given number to the specified unit. Example:

import { convert, units } from "@dynatrace-sdk/units";
convert(1500, units.length.meter, units.length.kilometer) // 1.5

Parameters

Name	Type	Description
input^*required	number	The number that will get converted.
from^*required	FromUnit	The unit of the input (e.g. `units.length.meter`).
to^*required	ConvertibleTarget<FromUnit \| ToUnit>	The unit of the output (e.g. `units.length.kilometer`).

Returns

Description
The result of the conversion (e.g. `1.5`).

format

format(number,options?): string

Converts and formats the provided number.

Parameters

Name	Type	Description
number^*required	number	The number that will get formatted.
options	FormatOptions<FromUnit \| ToUnit>	Formatting options.

Returns

Description
A string containing the formatted number.

formatCurrency

formatCurrency(number,currency,options?): string

Formats a number with the currency indicated

Parameters

Name	Type	Description
number^*required	number	The value to be formatted
currency^*required	undefined \| "CHF" \| "AED" \| "AFN" \| "ALL" \| "AMD" \| "ANG" \| "AOA" \| "ARS" \| "AUD" \| "AWG" \| "AZN" \| "BAM" \| "BBD" \| "BDT" \| "BGN" \| "BHD" \| "BIF" \| "BMD" \| "BND" \| "BOB" \| "BRL" \| "BSD" \| "BTN" \| "BWP" \| "BYN" \| "BZD" \| "CAD" \| "CDF" \| "CLP" \| "CNY" \| "COP" \| "CRC" \| "CUC" \| "CUP" \| "CVE" \| "CZK" \| "DJF" \| "DKK" \| "DOP" \| "DZD" \| "EGP" \| "ERN" \| "ETB" \| "EUR" \| "FJD" \| "FKP" \| "GBP" \| "GEL" \| "GHS" \| "GIP" \| "GMD" \| "GNF" \| "GTQ" \| "GYD" \| "HKD" \| "HNL" \| "HRK" \| "HTG" \| "HUF" \| "IDR" \| "ILS" \| "INR" \| "IQD" \| "IRR" \| "ISK" \| "JMD" \| "JOD" \| "JPY" \| "KES" \| "KGS" \| "KHR" \| "KMF" \| "KPW" \| "KRW" \| "KWD" \| "KYD" \| "KZT" \| "LAK" \| "LBP" \| "LKR" \| "LRD" \| "LSL" \| "LYD" \| "MAD" \| "MDL" \| "MGA" \| "MKD" \| "MMK" \| "MNT" \| "MOP" \| "MRU" \| "MUR" \| "MVR" \| "MWK" \| "MXN" \| "MYR" \| "MZN" \| "NAD" \| "NGN" \| "NIO" \| "NOK" \| "NPR" \| "NZD" \| "OMR" \| "PAB" \| "PEN" \| "PGK" \| "PHP" \| "PKR" \| "PLN" \| "PYG" \| "QAR" \| "RON" \| "RSD" \| "RUB" \| "RWF" \| "SAR" \| "SBD" \| "SCR" \| "SDG" \| "SEK" \| "SGD" \| "SHP" \| "SLE" \| "SLL" \| "SOS" \| "SRD" \| "SSP" \| "STN" \| "SVC" \| "SYP" \| "SZL" \| "THB" \| "TJS" \| "TMT" \| "TND" \| "TOP" \| "TRY" \| "TTD" \| "TWD" \| "TZS" \| "UAH" \| "UGX" \| "USD" \| "UYU" \| "UZS" \| "VES" \| "VND" \| "VUV" \| "WST" \| "XAF" \| "XCD" \| "XCG" \| "XDR" \| "XOF" \| "XPF" \| "XSU" \| "YER" \| "ZAR" \| "ZMW" \| "ZWL" \|	The ISO 4217 currency codes, such as 'USD' or 'EUR', to which the number will be formatted. This list is taken directly from INTL object
options	FormatCurrencyOptions	Options to adapt the formatting (locale and properties accepted by Intl.NumberFormat)

Returns

Description
the formatted number to the specified currency

formatDate

formatDate(input,options?): string

Formats a date according to locale.

Parameters

Name	Type	Description
input^*required	number \| Date	Number of milliseconds since UNIX epoch or a Javascript Date.
options	FormatDateOptions	An object that contains one or more properties that specify comparison options.

Returns

Description
Date string

formatLong

formatLong(value,options?): string

Parameters

Name	Type
value^*required	string \| number \| bigint
options	FormatLong

formatUnit

formatUnit(unit): string

Formats a unit to a string.

Parameters

Name	Type
unit^*required	FormattableUnit

getFormatting

getFormatting(number,options?): Formatting

Converts and formats the provided number, but returns the formatting as parts.

Parameters

Name	Type	Description
number^*required	number	The number that will get formatted.
options	FormatOptions<FromUnit \| ToUnit>	Formatting options.

Returns

Description
An Array of parts containing the formatting result object.

mapGrailUnit

mapGrailUnit(grailUnit): GrailUnitEquivalency

Finds the corresponding units value based on the Grail string we are passing

Parameters

Name	Type	Description
grailUnit^*required	string	The grail string which we want to obtain its corresponding unit equivalent

Returns

Description
Object containing the corresponding equivalent grail value to units

parseTime

parseTime(candidate?,relativeDate): null | TimeDetails

You can use the parseTime utility function to convert a string into TimeDetails, giving you a normalized version of the input string (trimmed string), a Date object created from the given input, and the type of input. The type can be either an expression or iso8601 string. If it is not possible to convert the input, the function will return null.

Parameters

Name	Type
~~candidate~~^DEPRECATED	null \| string
~~relativeDate~~^*required^DEPRECATED	number

parseTimeAsTimeValue

parseTimeAsTimeValue(candidate?,relativeDate?,precision?): TimeValue | null

You can use the parseTime utility function to convert a string into TimeValue, giving you a normalized version of the input string (trimmed string), a Date object created from the given input, and the type of input. The type can be either an expression or iso8601 string. If it is not possible to convert the input, the function will return null.

Parameters

Name Type Description

candidate null | string The input string to be parsed into a TimeValue.

relativeDate number An optional number representing a relative date.

precision

"day" | "minutes" | "seconds" | "milliseconds"

Name	Type	Description
candidate	null \| string	The input string to be parsed into a `TimeValue`.
relativeDate	number	An optional number representing a relative date.
precision	"day" \| "minutes" \| "seconds" \| "milliseconds"	Specifies the level of precision for the parsed time. Can be one of the following: 'day': Only the date part is considered, ignoring the time. 'minutes': Includes the date and time up to minutes. 'seconds': Includes the date and time up to seconds. 'milliseconds': Includes the date and time up to milliseconds. If empty or undefined, the original precision of the candidate is used.

Specifies the level of precision for the parsed time. Can be one of the following:

'day': Only the date part is considered, ignoring the time.
'minutes': Includes the date and time up to minutes.
'seconds': Includes the date and time up to seconds.
'milliseconds': Includes the date and time up to milliseconds.
If empty or undefined, the original precision of the candidate is used.

Returns

Description
A `TimeValue` object containing the normalized input string, a `Date` object,
and the type of input, or `null` if the input can't be converted.

variantNames

variantNames(unit): VariantNames<U>

Returns the names of all units to which the provided unit can be converted to.

Parameters

Name	Type
unit^*required	U

variantUnits

variantUnits(unit): VariantUnits<U>

Returns all units to which the provided unit can be converted to.

Parameters

Name	Type
unit^*required	U

Variables

ExponentialDecimalLevels: Object

Abbreviation levels for decimal metric prefixes from kilo to quecto, 10^3, 10^6, ...

ExponentialOctalBitLevels: Object

Abbreviation levels for bit binary prefixes from kilobit to quebibit, 2^10, 2^20, ...

ExponentialOctalByteLevels: Object

Abbreviation levels for byte binary prefixes from kibibyte to quebibyte, 2^10, 2^20, ...

timeframeTranslations: Object

units: Object

Grouped collection of all the supported units

Interfaces

AdjustFractionDigitsOptions

Properties

Name	Type	Description
locale	string \| Array<string>	The locale according to which the number will be adjusted.
maximumFractionDigits	number	Maximum number of decimal digits.
maximumSignificantDigits	number	Maximum number of significant digits. Default is 21
minimumFractionDigits	number	Minimum number of decimal digits.
minimumSignificantDigits	number	Minimum number of significant digits. Default is 1
useGrouping	boolean	Whether to use grouping separators, such as thousands separators or thousand/lakh/crore separators.

FormatCurrencyOptions

Properties

Name	Type	Description
abbreviate	boolean	It will shorten the number to a shorter format. (e.g. `input: 1500, output: 1.5k`).
locale	string \| Array<string>	The locale according to which the number will be formatted.

FormatDateOptions

Interface that extends Intl.DateTimeFormatOptions to pass an optional property to overwrite the default locale. See MDN.

Properties

Name	Type	Description
locale	string \| Array<string>	The locale according to which the number will be formatted.

FormatOptions

Properties

Name	Type	Description
abbreviate	boolean	It will shorten the number to a shorter format. (e.g. `input: 1500, output: 1.5k`).
cascade	number	Will search for the biggest unit within its group and cascade it down the the specified depth. The last number will get rounded to `maximumFractionDigits`. (e.g. `format(1500, { input: units.length.meter, cascade: 2}), output: "1 km 500 m")`).
input	FromUnit	If input unit is defined, it will convert it to the best fitting unit. (e.g. `format(1500, { input: units.length.meter }), output: "1.5 km")`).
locale	string \| Array<string>	The locale that will be used to format the number. By default it will use the platform locale specified by the user.
maximumFractionDigits	number	The amount of maximumFractionDigits points. See MDN. If minimumFractionDigits is passed, set to minimumFractionDigits by default. Otherwise set to 0 by default.
maximumSignificantDigits	number	Maximum number of significant digits. Default is 21
minimumFractionDigits	number	The amount of minimumFractionDigits points. See MDN.
minimumSignificantDigits	number	Minimum number of significant digits. Default is 1
output	OutputUnit<UndefinedCoalescing<FromUnit \| > \| ToUnit>	If not specified, the conversion is disabled (e.g. `format(1500), output: 1.5K`).
suffix	string	A custom suffix that overwrites the unit symbol.
useGrouping	boolean	Whether to use grouping separators, such as thousands separators or thousand/lakh/crore separators See MDN

ConvertibleUnit

All supported convertible units. For more details see a conversion example.

import { units } from '@dynatrace-sdk/units';
units.length.meter // extends ConvertibleUnit

FromUnit

A type for every convertible unit. For more details see a conversion example.

ToUnit

All units to which the FromUnit can be converted. For more details see a conversion example.

FormattableUnit

A unit that can be formatted. Example:

import { units } from '@dynatrace-sdk/units';
units.currency.eur // extends FormattableUnit

Unit

A ConvertibleUnit or a FormattableUnit or both.

ConvertibleTarget

TypeScript helper that returns all the possible convertible targets, where the first generic is FromUnit, and second is ToUnit.

Still have questions?

Find answers in the Dynatrace Community

Go to Dynatrace Community

Units

Conversion example​

Functions​

abbreviateNumber​

Parameters​

adjustFractionDigits​

Parameters​

Returns​

convert​

Parameters​

Returns​

format​

Parameters​

Returns​

formatCurrency​

Parameters​

Returns​

formatDate​

Parameters​

Returns​

formatLong​

Parameters​

formatUnit​

Parameters​

getFormatting​

Parameters​

Returns​

mapGrailUnit​

Parameters​

Returns​

parseTime​

Parameters​

parseTimeAsTimeValue​

Parameters​

Returns​

variantNames​

Parameters​

variantUnits​

Parameters​

Variables​

Interfaces​

AdjustFractionDigitsOptions​

Properties​

FormatCurrencyOptions​

Properties​

FormatDateOptions​

Properties​

FormatOptions​

Properties​

ConvertibleUnit​

FromUnit​

ToUnit​

FormattableUnit​

Unit​

ConvertibleTarget​

Conversion example

Functions

abbreviateNumber

Parameters

adjustFractionDigits

Parameters

Returns

convert

Parameters

Returns

format

Parameters

Returns

formatCurrency

Parameters

Returns

formatDate

Parameters

Returns

formatLong

Parameters

formatUnit

Parameters

getFormatting

Parameters

Returns

mapGrailUnit

Parameters

Returns

parseTime

Parameters

parseTimeAsTimeValue

Parameters

Returns

variantNames

Parameters

variantUnits

Parameters

Variables

Interfaces

AdjustFractionDigitsOptions

Properties

FormatCurrencyOptions

Properties

FormatDateOptions

Properties

FormatOptions

Properties

ConvertibleUnit

FromUnit

ToUnit

FormattableUnit

Unit

ConvertibleTarget