Units

Package for converting and formatting units and numerical values.

@dynatrace-sdk/units

v1.0.2

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

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.

FormatDateOptions

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

Properties

Name	Type	Description
calendar	string
dateStyle	"long" | "short" | "full" | "medium"
day	"numeric" | "2-digit"
dayPeriod	"long" | "short" | "narrow"
era	"long" | "short" | "narrow"
formatMatcher	"best fit" | "basic"
fractionalSecondDigits	1 | 2 | 3
hour	"numeric" | "2-digit"
hour12	boolean
hourCycle	"h11" | "h12" | "h23" | "h24"
locale	string | Array<string>	The locale according to which the number will be formatted.
localeMatcher	"best fit" | "lookup"
minute	"numeric" | "2-digit"
month	"long" | "short" | "narrow" | "numeric" | "2-digit"
numberingSystem	string
second	"numeric" | "2-digit"
timeStyle	"long" | "short" | "full" | "medium"
timeZone	string
timeZoneName	"long" | "short" | "shortOffset" | "longOffset" | "shortGeneric" | "longGeneric"
weekday	"long" | "short" | "narrow"
year	"numeric" | "2-digit"

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

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

Functions

_cascade

_cascade(number,unit,depth,list?,fractionDigits?): ValueUnitList

Cascades the input to the best fitting unit, depth/precision can be adjusted Supported base units units.electricity.ampere, units.electricity.volt, units.electricity.ohm, units.electricity.watt, units.electricity.coulomb, units.electricity.farad, units.electricity.weber, units.electricity.tesla, units.electricity.henry, units.electricity.siemens, units.force.newton, units.frequency.hertz, units.length.meter, units.mass.gram, units.physics.gray, units.physics.sievert, units.physics.candela, units.physics.lumen, units.physics.lux, units.physics.steradian, units.pressure.pascal, units.time.second, units.length.meter, units.data.byte, units.data.bit, units.unspecified.pixel units.angle.degree

Parameters

Name	Type
number*required	number
unit*required	ConvertibleUnit
depth*required	number
list	CascadeUnit
fractionDigits	number

_convertTemperature

_convertTemperature(input,from,to): number

Parameters

Name	Type
input*required	number
from*required	FromUnit
to*required	ConvertibleTarget<FromUnit | ToUnit>

_getDateFromExpression

_getDateFromExpression(__namedParameters,relativeDate): Date | null

Converts expression details into a date object

Parameters

Name	Type
__namedParameters*required	ExpressionDetails
relativeDate*required	number | Date

_getTimeframeExpression

_getTimeframeExpression(): RegExp

Returns the TimeframeExpression regex.

_parseDatetimeInput

_parseDatetimeInput(candidate,relativeDate?): Date | null

Generates a date object out of the input string if provided in one of the accepted formats

Parameters

Name	Type
candidate*required	string
relativeDate	Date

_parseISOWithExtendedPrecision

_parseISOWithExtendedPrecision(candidate): TimeValue | null

Checks if the provided value is a valid ISO string with support for extended (up tp nano) precision. We cannot use dateFns parseISO because it returns native Date object, which do not support extended precision.

Parameters

Name	Type
candidate*required	string

_parseTimeExpression

_parseTimeExpression(candidate): ExpressionDetails | undefined

Parses the input for expression details.

Parameters

Name	Type
candidate*required	string

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.
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
candidateDEPRECATED	null | string
relativeDate*requiredDEPRECATED	number

parseTimeAsTimeValue

parseTimeAsTimeValue(candidate?,relativeDate?): 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
candidate	null | string
relativeDate	number

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

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.