human-readable-duration v1.0.1

human readable duration

Translate a duration to a human friendly format in any language* (eg. 2 weeks ago)

Think of moment.duration().humanize() but lightweight (only 3.5k).

* since you provide the translation

TOC

• Install
• Import
• Usage
• API
• Locales

Install

Pick your flavor:

Import

Browser

<script src="./path/to/human-readable-duration.js"></script>
<script>
  console.log(humanize().translate(date));
</script>

ES6

import { humanize } from 'human-readable-duration';
console.log(humanize().translate(date));

AMD/NODE

const { humanize } = require('human-readable-duration');
console.log(humanize().translate(date));

Usage

const dateInfuture = new Date();
dateInfuture.setTime(dateInfuture.getTime() + 120000);
const translation = humanize().translate(dateInfuture);
expect(translation).toBe('in 2 minutes');

const dateInPast = new Date();
dateInPast.setTime(dateInPast.getTime() - 120000);
const translation = humanize().translate(dateInPast);
expect(translation).toBe('2 minutes ago');

API

The library uses the current date as starting point, it means that all translations are relative to Date.now(). eg. if you add two minutes to the current time and call the translate() function, the library will translate it as "in 2 minutes" (with the default locale).

• humanize()
  • .translate()
  • .asMinutes()
  • .asHours()
  • .asDays()
  • .asWeeks()
  • .asMonths()
  • .asYears()

humanize()

humanize(
    locale: Object
): Object

Instantiates the translator function and returns the translation functions. Accepts a locale object to be used in all translations. See the locales section for more details on how to customize translations to other languges.

humanize().translate()

humanize().translate(
    date: Date
): String

Translates the duration between date and Date.now() in a human friendly format. The long the duration the higher the unit of time is choosen for the translation. Available units of time are: minute, hours, days, weeks, months and years.

humanize().asMinutes()

humanize().asMinutes(
    date: Date
): String

Set minutes as the highest unit of time for the translation. eg:

humanize().asHours()

humanize().asHours(
    date: Date
): String

Set hours as the highest unit of time for the translation. eg:

humanize().asDays()

humanize().asDays(
    date: Date
): String

Set days as the highest unit of time for the translation. eg:

humanize().asWeeks()

humanize().asWeeks(
    date: Date
): String

Set weeks as the highest unit of time for the translation. eg:

humanize().asMonths()

humanize().asMonths(
    date: Date
): String

Set months as the highest unit of time for the translation. eg:

humanize().asYears()

humanize().asYears(
    date: Date
): String

Set years as the highest unit of time for the translation. eg:

Locales

The library uses en-US as the default locale, but one can easily override it passing a locale object to the humanize() function.

const ptBr = {
    NOW: 'agora',
    MINUTE: {
        NAME: 'minuto',
        PAST_SINGULAR: 'há 1 minuto',
        PAST_PLURAL: 'há {0} minutos',
        . . .
    },
    . . .
}

const { translate } humanize(ptBr);

console.log(translate(new Date()));
//"agora"

You can even change only specific translations without the need to fully replace the default locale:

const myLocale = {
  MINUTE: {
    FUTURE_SINGULAR: 'in one minute (hurry up!)',
  },
};

const { translate } humanize(myLocale);
console.log(translate(new Date()));
//"now"
console.log(translate(oneMinuteInFutureDate));
//"in one minute (hurry up!)"

Please, check the src/locales folder for the required structure a locale file must have.