stringFromMilliseconds

type: function
since: v2.0.0

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

The stringFromMillisecondsErrorScope app error scope array is exported by this utility and can be used to filter thrown AppError by scope for this specific utility.

To learn more about error handling please refer to error handling section of the getting started guide, and the AppError documentation.

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

   type milliseconds = number;

   • The number of milliseconds to convert to a string.
2. options

   type options = {
       maxUnit: "s" | "ms" | "m" | "h" | "d" | "w" | "mo" | "y",
       minUnit: "s" | "ms" | "m" | "h" | "d" | "w" | "mo" | "y",
       showZeroValuedUnits: boolean,
       fixedWidth: boolean,
       decimalBehavior: 'round' | 'floor' | 'ceil',
       maxDecimalCount: number,
       separator: string,
       unitsAlias: Partial<
         Record<
           "s" | "ms" | "m" | "h" | "d" | "w" | "mo" | "y",
           string
           | Partial<Record<
               'singular' | 'plural',
               string
             >>
         >
       >
     };

   • options.maxUnit
     • The largest time unit to be included in the string representation
     • See Units and their Values.
   • options.minUnit
     • since: v2.1.0
     • The smallest time unit to be included in the string representation
     • See Units and their Values.
   • options.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:

       false

   • options.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:005msinstead of For example, the output might be 1mo:2d:23m:3s:5ms
     • default:

       false

   • options.separator
     • since: v2.1.0
     • The separator between time units in the string representation
     • default:

       :

   • options.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 string and the value is the alias or an object with the singular and plural values

     • Examples

       1. const unitsAlias = {
            ms: {
              singular: 'millisecond',
              plural: 'milliseconds'
          }};

       2. const unitsAlias = { 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.
   • options.maxDecimalCount
     • since: v2.1.0
     • The maximum number of decimal places to be included in the string representation.
     • This value is used if the remaining milliseconds of the time unit are less than the value of minUnit and there are remaining milliseconds at the end

     • Examples

       1. stringFromMilliseconds(1500, { minUnit: 's', maxDecimalCount: 1 }); // 1.5s

       2. stringFromMilliseconds(1050, { minUnit: 's', maxDecimalCount: 2 }); // 1.05s

       3. stringFromMilliseconds(1050, { minUnit: 's', maxDecimalCount: 1 }); // 1s

     • Note

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

       1

     ,
   • options.decimalBehavior
     • since: v2.1.0
     • The behavior that will be applied to the decimal part of the time unit.
     • 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

type T = string;

• A TimeUnits string representation.

• Tip

  Returned 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'