time-formatter

The time-formatter package converts a number representing elapsed time into a human readable string.

Examples

import { formatTime } from '@rwf-projects/time-formatter';

const formattedTime = formatTime(4.256128);
// 4 seconds and 256.128 milliseconds

import { formatTime } from '@rwf-projects/time-formatter';

const options = {
  precision: 2,
  inputUnit: 'millisecond',
  minUnit: 'microsecond',
  maxUnit: 'hour'
};
const formattedTime = formatTime(187696032.064, options);
// 52 hours, 8 minutes, 16 seconds, 32 milliseconds and 64 microseconds

import { formatTime } from '@rwf-projects/time-formatter';

const formattedTime: string = formatTime(4.256128);
// 4 seconds and 256.128 milliseconds

import { formatTime, Options, Units } from '@rwf-projects/time-formatter';

const options: Partial<Options> = { minUnit: Units.SECOND, maxUnit: Units.HOUR };
const formattedTime: string = formatTime(94592, options);
// 26 hours, 16 minutes and 32 seconds

import { formatTime, Options, Units } from '@rwf-projects/time-formatter';

const options: Options = {
  precision: 2,
  inputUnit: Units.MILLISECOND,
  minUnit: Units.MICROSECOND,
  maxUnit: Units.HOUR
};
const formattedTime: string = formatTime(187696032.064, options);
// 52 hours, 8 minutes, 16 seconds, 32 milliseconds and 64 microseconds

Features

• Outputs a nice human-readable string representig a time interval;
• Output units from weeks down to microsecond;
• Input unit is configurable;
• Minimum and maximum units are configurable;
• Arbitrary precision in the lower unit;
• Translatable;
• Works with require and import;
• Zero dependencies;
• 100% test coverage.

Available units

The available units are week, day, hour, minute, second, millisecond and microsecond.
In TypeScript these units are available through the Units enum.

Why not bigger than week?

• Because bigger units are not precise enough. A week is exactly 7 days. A month can have any duration between 28 and 31 days.

Why not smaller than microsecond?

• Because the way JavaScript handles floating point numbers introduces errors at very small ranges;
• It is also the maximum precision performance.now returns.

Installation

npm

npm install --save @rwf-projects/time-formatter

yarn

yarn add @rwf-projects/time-formatter

Usage

Start by importing.

import { formatTime } from '@rwf-projects/time-formatter';

... or requiring.

const { formatTime } = require('@rwf-projects/time-formatter');

Then

const formattedTime = formatTime(time, [options], [i18n]);

import { formatTime, Options, I18n } from '@rwf-projects/time-formatter';

const formattedTime: string = formatTime(time, [options], [i18n]);

Options

An object with the following keys:

| Option | Type | Default value in JS | Default value in TS | Description | |-----------|--------|---------------------|---------------------|-----------------------------------------------------------------| | precision | number | 3 | 3 | The amount of decimal places the smallest unit will have | | inputUnit | number | 'second | Units.SECOND | The input unit. One of the available units | | minUnit | string | 'millisecond' | Units.MILLISECOND | The smallest unit that will be used. One of the available units | | maxUnit | string | 'week' | Units.WEEK | The biggest unit that will be used. One of the available units |

I18n

The generated string does not have to be in English. You can specify any language, as long as it follows the format unit1, unit2 [...] and unitN.
To do so, pass the time formatter funtion an i18n object with the translations.

If you don't need to change the default options, then pass any falsy value.

I18n keys

Each i18n unit key has a mandatory singular key and an optional plural key.
The and key, used in [...] and unitN does not use singular or plural.

| Key in JS | Key in TS | Default singular value | Default plural value | |-------------|---------------------|------------------------|----------------------| | week | Units.WEEK | 'week' | Singular value + 's' | | day | Units.DAY | 'day' | Singular value + 's' | | hour | Units.HOUR | 'hour' | Singular value + 's' | | minute | Units.MINUTE | 'minute' | Singular value + 's' | | second | Units.SECOND | 'second' | Singular value + 's' | | millisecond | Units.MILLISECOND | 'millisecond' | Singular value + 's' | | microsecond | Units.MICROSECOND | 'microsecond' | Singular value + 's' | | and | and | 'and' | N/A |

Examples

Full translation

You can translate all the keys.

const fullI18n = {
  week: {
    singular: 'semana'
  },
  day: {
    singular: 'dia'
  },
  hour: {
    singular: 'hora'
  },
  minute: {
    singular: 'minuto'
  },
  second: {
    singular: 'segundo'
  },
  millisecond: {
    singular: 'milissegundo'
  },
  microsecond: {
    singular: 'microssegundo'
  },
  and: 'e'
};

const formattedTime = formatTime(694861.001001, null, fullI18n);
// 1 semana, 1 dia, 1 hora, 1 minuto, 1 segundo e 1.001 milissegundos

const fullI18n: I18n = {
  [Units.WEEK]: {
    singular: 'semana'
  },
  [Units.DAY]: {
    singular: 'dia'
  },
  [Units.HOUR]: {
    singular: 'hora'
  },
  [Units.MINUTE]: {
    singular: 'minuto'
  },
  [Units.SECOND]: {
    singular: 'segundo'
  },
  [Units.MILLISECOND]: {
    singular: 'milissegundo'
  },
  [Units.MICROSECOND]: {
    singular: 'microssegundo'
  },
  and: 'e'
};

const formattedTime: string = formatTime(694861.001001, null, fullI18n);
// 1 semana, 1 dia, 1 hora, 1 minuto, 1 segundo e 1.001 milissegundos

Partial translation

You can just specify shorter units, for example.

const options = { minUnit: 'microsecond' };

const partialI18n = {
  millisecond: {
    singular: 'ms',
    plural: 'ms'
  },
  microsecond: {
    singular: 'μs',
    plural: 'μs'
  }
};

const formattedTime = formatTime(694861.001001, options, partialI18n);
// 1 week, 1 day, 1 hour, 1 minute, 1 second, 1 ms and 1 μs

const options: Partial<Options> = { minUnit: 'microsecond' };

const partialI18n: Partial<I18n> = {
  [Units.MILLISECOND]: {
    singular: 'ms',
    plural: 'ms'
  },
  [Units.MICROSECOND]: {
    singular: 'μs',
    plural: 'μs'
  }
};

const formattedTime: string = formatTime(694861.001001, options, partialI18n);
// 1 week, 1 day, 1 hour, 1 minute, 1 second, 1 ms and 1 μs