Tiempo -

Library to format time into text with a custom format.

Install

yarn add tiempo
# or 
npm install tiempo

Format time

import tiempo from 'tiempo';
 
// The format function if the second parameter is not defined, it will use current date as now.
 
// now: 2018-07-01 14:30:50.
tiempo.format('2018-07-01 14:30:00', '2018-07-01 14:30:50');
// returns: 50 seconds ago.
tiempo.format('2018-07-01 14:15:00', '2018-07-01 14:30:50');
// returns: 15 minutes ago.
tiempo.format('2018-06-30 16:10:00', '2018-07-01 14:30:50');
// returns: yesterday at 16:10.

Change locale

import tiempo from 'tiempo';
 
// same example as above.
 
// if locale doest exist it will warn you to register new locale.
tiempo.config({ locale: 'es' });
 
// now: 2018-07-01 14:30:50.
tiempo.format('2018-07-01 14:30:00', '2018-07-01 14:30:50');
// returns: hace 50 segundos.
tiempo.format('2018-07-01 14:15:00', '2018-07-01 14:30:50');
// returns: hace 15 minutos.
tiempo.format('2018-06-30 16:10:00', '2018-07-01 14:30:50');
// returns: ayer a las 16:10.

Add a custom or new locale

import tiempo from 'tiempo';
 
// register locale, if it exist will be replaced otherwise added as a new one.
config({
  locales: {
    es: {
      relativeTime: {
        // [PAST,FUTURE]
        s: ['recien', 'ahora'],
        ss: ['hace %s segundos', 'en %s segundos'],
        m: ['hace un minuto', 'en un minuto'],
        mm: ['hace %m minutos', 'en %m minutos'],
        h: ['hace una hora', 'en una hora'],
        hh: ['hoy a las {hh:mm}'],
        d: ['ayer a las {hh:mm}', 'mañana a las {hh:mm}'],
        dd: ['hace %d días', 'en %d dias'],
        M: ['hace un mes', 'en un mes'],
        MM: ['hace %M meses', 'en %M meses'],
        y: ['hace un año', 'en un año'],
        yy: ['hace %y años', 'en %y años'],
      },
    },
  },
});

Replace relative time

import tiempo from 'tiempo';
 
// This will replace all locales(*) or a specific one, only is replaced de relativeTime you want to replace, if you replace 'dd' for a new one, it will replace that one and the rest will remain the same
config({
  locales: {
    '*': {
      relativeTime: {
        // [PAST,FUTURE]
        MM: ['{dd/MM/yy hh:mm}'],
        yy: ['{dd/MM/yyyy hh:mm A}'],
      },
    },
    en: {
      relativeTime: {
        // [PAST,FUTURE]
        dd: [
          '%d days ago at {hh:mm A}',
          'in %d days %h hours %m minutes %s seconds',
        ],
        MM: ['{dd/MM/yy hh:mm}'],
        yy: ['{dd/MM/yyyy hh:mm A}', 'in %y years'],
      },
    },
  },
});

Get difference between two dates

import tiempo from 'tiempo';
 
tiempo.diff('2018-01-04 22:00:00', '2018-01-02 23:00:00');
// returns: { y: 0, M: 0, d: 1, h: 23, m: 0, s: 0 }

Realtime format

import tiempo from 'tiempo';
 
// Set realtime in config
tiempo.config({ realtime: true });
 
// Use realtime format
tiempo
  .realtime(newFormat => console.log(newFormat))
  .format('2018-10-04 19:37:00');

Functionality

export interface Tiempo {
  format(d1: string | Date, d2?: string | Date): string;
  diff(d1: string | Date, d2: string | Date): DifferenceTime;
  config(options: Partial<ConfigOptions>): any;
  realtime(fn: (result?: string) => void): Realtime;
}

Config

import tiempo from 'tiempo';
 
tiempo.config({
  realtime: true, // Set realtime
  format: ['s', 'm', 'h', 'd'], // The formats you want to use and ignore the rest
  locale: 'es',
  locales: {es:{relativeTime:{...}}},
});
 
// All configs are merged into one, so you can change it multiple times without losing data(except format)
tiempo.config({
  format: ['s'], // The formats you want to use and ignore the rest
  locale: 'en',
  locales: {en:{relativeTime:{...}}},
});
 
// This will result in
 
{
  realtime: true,
  format: ['s'],
  locale: 'en',
  locales: {es:{relativeTime:{...}},en:{relativeTime:{...}}},
}

Format Table to use inside format {}.

example: '{hh:mm A} == 01:05 AM'

	Token	Output
Second	s	0 1 ... 58 59
	ss	00 01 ... 58 59
Minute	m	0 1 ... 58 59
	mm	00 01 ... 58 59
Hour	h	1 2 ... 23 24 | AM/PM ...11 12
	hh	01 02 ... 23 24 | AM/PM ...11 12
Day	d	1 2 ... 11 12
	dd	01 02 ... 11 12
Month	M	1 2 ... 11 12
	MM	01 02 ... 11 12
Year	y	1 2 ... 11 12
	yy	01 02 ... 11 12
AM/PM	A	AM PM
	a	am pm

Licence

MIT