The time-formatter package converts a number representing elapsed time into a human readable string.
JavaScript
import { formatTime } from '@rwf-projects/time-formatter';
const formattedTime = formatTime(4.256128);
// 4 seconds and 256.128 millisecondsimport { 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 microsecondsTypeScript
import { formatTime } from '@rwf-projects/time-formatter';
const formattedTime: string = formatTime(4.256128);
// 4 seconds and 256.128 millisecondsimport { 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 secondsimport { 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- 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
requireandimport; - Zero dependencies;
- 100% test coverage.
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.nowreturns.
npm install --save @rwf-projects/time-formatteryarn add @rwf-projects/time-formatterJavaScript
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]);TypeScript
import { formatTime, Options, I18n } from '@rwf-projects/time-formatter';
const formattedTime: string = formatTime(time, [options], [i18n]);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 |
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.
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 |
You can translate all the keys.
JavaScript example
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 milissegundosTypeScript example
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 milissegundosYou can just specify shorter units, for example.
JavaScript 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 μsTypeScript example
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