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:

Package manager	Command
npm	npm install human-readable-duration
yarn	yarn add human-readable-duration

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.

Input	Output
humanize().translate(twoMinuteInPastDate)	2 minutes ago
humanize().translate(oneMinuteInPastDate)	just now
humanize().translate(new Date())	now
humanize().translate(120MinutesInFutureDate)	in 2 hours
humanize().translate(twoDaysInFutureDate)	in 2 days
humanize().translate(tenWeeksInFutureDate)	in 10 weeks
humanize().translate(fiveWeeksInFutureDate)	in 1 month
humanize().translate(twelveMonthsInFutureDate)	in 1 year

humanize().asMinutes()

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

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

Input	Output
humanize().asMinutes(twoDaysInFutureDate)	in 2880 minutes
humanize().asMinutes(twelveMonthsInFutureDate)	in 525600 minutes
humanize().asMinutes(twoDaysInPastDate)	2880 minutes ago
humanize().asMinutes(twelveMonthsInPastDate)	525600 minutes ago

humanize().asHours()

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

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

Input	Output
humanize().asHours(twoDaysInFutureDate)	in 24 hours

humanize().asDays()

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

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

Input	Output
humanize().asDays(new Date())	less than 1 day ago

humanize().asWeeks()

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

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

Input	Output
humanize().asWeeks(oneMontInFuture)	in 4 weeks

humanize().asMonths()

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

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

Input	Output
humanize().asMonths(oneYearAgo)	12 months ago

humanize().asYears()

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

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

Input	Output
humanize().asYears(fiveWeeksInFuture)	in less than 1 year

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.