stringFromMilliseconds

Type : function

A function that returns a string representation of a number of milliseconds.

Usage

console.log(stringFromMilliseconds(1000)); // 1s

console.log(stringFromMilliseconds(1000), { maxUnit: 'ms' }); // 1000ms

console.log(stringFromMilliseconds(1500), { minUnit: 's' }); // 1.5s

console.log(stringFromMilliseconds(2750), { minUnit: 's', }); // 2.7s

console.log(stringFromMilliseconds(2750), { minUnit: 's', maxDecimalCount: 2 }); // 2.75s

console.log(stringFromMilliseconds(2750), { minUnit: 's', decimalBehavior: 'round'}); // 3s

console.log(stringFromMilliseconds(2750), { minUnit: 's', decimalBehavior: 'floor'}); // 2s

console.log(stringFromMilliseconds(2750), { minUnit: 's', decimalBehavior: 'ceil'}); // 3s

console.log(stringFromMilliseconds(1000), { unitsAlias: { s: 'second' }} ); // 1second

console.log(stringFromMilliseconds(2000), { unitsAlias: { s: 'second' }}); // 2second

console.log(stringFromMilliseconds(2000), { unitsAlias: { s: {plural: 'seconds', singular: 'second'} }} ); // 2seconds

console.log(stringFromMilliseconds(1000), { unitsAlias: { s: {plural: 'seconds', singular: 'second'} }} ); // 1second

console.log(stringFromMilliseconds(1500), { separator: '-' }); // 1s-500ms

console.log(stringFromMilliseconds(0), { showZeroValuedUnits: true }); // 00y:00mo:0w:00d:00h:00m:00s:000ms

console.log(stringFromMilliseconds(2005), { fixedWidth: true }); // 02s:005ms

console.log(stringFromMilliseconds(2005), { fixedWidth: true, showZeroValuedUnits: true }); // 00y:00mo:0w:00d:00h:00m:02s:005ms

Definition

export function stringFromMilliseconds(
  milliseconds: number,
  options?: Options,
): TimeUnits {}

• parameters:

  1. milliseconds: number
     • The number of milliseconds to convert to a string.
  2. options: An object with the following properties:

     • maxUnit:

       • The largest time unit to be included in the string representation.
       • It’s value should be one of the following: ms, s, m, h, d, w, mo, y.
       • See Units and their Values.

     • minUnit: since v2.1.0

       • The smallest time unit to be included in the string representation.
       • It’s value should be one of the following: ms, s, m, h, d, w, mo, y.
       • See Units and their Values.

     • showZeroValuedUnits: since v2.2.0

       • A boolean value that indicates whether to display all time units from minUnit to maxUnit, even if they have zero values.
       • For example, the output might be 1y:0mo:0w:0d:0h:2m:0s:5ms.
       • Default is false.

     • fixedWidth: since v2.2.0

       • A boolean value that indicates whether to pad the time units’ string representation with leading zeros to maintain a fixed width.
       • For example, the output might be 01mo:02d:23m:03s:005ms instead of 1mo:2d:23m:3s:5ms.
       • Default is false.

     • separator: since v2.1.0

       • The separator between time units in the string representation.
       • Default is :.

     • unitsAlias: since v2.1.0

       • specifies custom units names to be used in the string representation instead of the default ones.
       • It is an object where the key is the time unit and the value is the alias or an object with the singular and plural values.
       • For example: { ms: { singular: 'millisecond', plural: 'milliseconds' } } or { ms: 'millisecond' }.

       • Note

         If aliases is a string, it’s value will be used for both singular and plural values.
         If it is an object and one of singular or plural is missing, the default value will be used.

     • maxDecimalCount: since v2.1.0

       • The maximum number of decimal places to be included in the string representation.
       • Default is 1.
       • This value is used when the remaining milliseconds of the time unit are less than minUnit value and there are remaining milliseconds at the end when minUnit is greater than 'ms'.

       • /* EXAMPLES */
         stringFromMilliseconds(1500,
           { minUnit: 's', maxDecimalCount: 1 /* default */
         }); // 1.5s
         stringFromMilliseconds(1050,
           { minUnit: 's', maxDecimalCount: 2
         }); // 1.05s
         stringFromMilliseconds(1050,
           { minUnit: 's', maxDecimalCount: 1
         }); // 1s

       • Note

         This option is useless when decimalBehavior exists or minUnit is greater than ms.

     • decimalBehavior: since v2.1.0

       • The behavior that will be applied to the decimal part of the time unit.
       • It is a string that can be one of the following: round, floor, ceil.
       • Default is undefined.
       • It is used when there will be decimal parts in the string representation and functions the same as their equivalent JavaScript Math functions.

         Note

         When used maxDecimalCount option is useless

• returns: TimeUnits

Tip

It’s return value is a valid input for millisecondsFromString.

Units and their Values

Unit	Description
y	Year
mo	Month
w	Week
d	Day
h	Hour
m	Minute
s	Second
ms	Millisecond

TimeUnits

A string contains a number followed by one of the following units: y, mo, w, d, h, m, s, ms or a combination of them separated by :.

• For example:

  '1s' '1s:500ms' '1h:30m:45s'