About

time-date-tools is a powerful Node.js module that allows you to easily manage time and date. You can configure a lot of features to not have date and time issues anymore.
If you have any question, you can join our community on Discord.

Features

• Installation
• Importation
• Time
  • Format : Convert a time in milliseconds to a time in string.
  • Parse : Convert a time in string to a time in milliseconds.
• Date
  • Format : Convert a date in milliseconds to a date in string.

Installation

$ npm install --save time-date-tools

Usage

Importation

import tdt from "time-date-tools";          // Es Modules
const tdt = require("time-date-tools");     // CommondJS

Time

Format Time

Class TimeSettings for the format:

Before call the format() function, you have to create a class called TimeSettings. This function allows you to save the configuration you want in a variable, instead of rewrite everything.

new TimeSettings(options);

Available options in the configuration for the format() function:

Parameter	Type	Optional	Default	Description
lang	string	✅	en	Language of time unities ('en' or 'fr').
format	string	✅	Y YYYY, M MMMM, W WWWW, D dddd, h HH, m MM, s SS, sss SSSS	Format* of the string time.
precision	boolean	✅	true	If false, it will round and return the bigger nonnull unity. Else, all the unities are returned.
long	boolean	✅	true	Complete the previous argument, if false, it will return the short unity. Else it will return the long unity.

*Format: By default, the null unities aren't displayed. If you want to display them, you can surround some parts of the format by [ and ].

Available token for the time format:

Token	Meaning	Examples of output
YYYY	Year unity	years, year
yyyy	Year unity (short)	y
Y	Year value	1
MMMM	Month unity	months, month
mmmm	Month unity (short)	mo
M	Month value	2
WWWW	Week unity	weeks, week
wwww	Week unity (short)	w
W	Week value	3
DDDD	Day unity	days, day
dddd	Day unity (short)	d
D	Day value	4
HH	Hour unity	hours, hour
hh	Hour unity (short)	h
h	Hour value	5
MM	Minute unity	minutes, minute
mm	Minute unity (short)	m
m	Minute value	6
SS	Second unity	seconds, second
ss	Second unity (short)	s
sss	Second value	7
SSSS	Millisecond unity	milliseconds, millisecond
ssss	Millisecond unity (short)	ms
sss	Millisecond value	8

Function format():

Now the settings ready, you can call the function format() which convert a time in milliseconds to a string with the format of your choice.

const TimeSettingsFormat = new TimeSettings({ lang: "en", format: "Y YYYY, M MMMM, W WWWW, D DDDD, h HH, m MM, s SS, sss SSSS" });
TimeSettingsFormat.format(timeInMilliseconds);

Available arguments in the format() function:

Parameter	Type	Optional	Default	Description
timeInMilliseconds	number	❌		Time in milliseconds to convert into a string.

Examples:

const settings_1 = new TimeSettings({ lang: "en", format: "Y YYYY, M MMMM, W WWWW, D dddd, h HH, m MM, s SS, sss SSSS" });
const settings_2 = new TimeSettings({ lang: "en", format: "[Y YYYY, M MMMM,] W WWWW, D dddd, h HH, m MM, s SS, sss SSSS" });

settings_1.format(361410); // 6 minutes, 1 second, 410 milliseconds
settings_2.format(361410); // 0 year, 0 month, 6 minutes, 1 second, 410 milliseconds


const settings_3 = new TimeSettings({ lang: "en", precision: false, long: true });
const settings_4 = new TimeSettings({ lang: "en", precision: false, long: false });
const settings_5 = new TimeSettings({ lang: "en", precision: true, long: true });

settings_3.format(486000000); // 6 days
settings_4.format(486000000); // 6d
settings_5.format(486000000); // 0 year, 0 month, 0 week, 5 days, 15 hours, 0 minute, 0 second, 0 millisecond

Parse Time

Class TimeSettings for the parse:

Before call the parse() function, you have to create a class called TimeSettings. This function allows you to save the configuration you want in a variable, instead of rewrite everything.

new TimeSettings();

There is no available option for the parse() function. You can put the same options as for the format() function, but it won't change anything for the result.

Function parse():

Now the settings ready, you can call the function parse() which convert a time in string to milliseconds.

const TimeSettingsParse = new TimeSettings();
TimeSettingsParse.parse(timeInString);

Available arguments in the parse() function:

Parameter	Type	Optional	Default	Description
timeInString	number	❌		Time in string to convert into milliseconds.

Examples:

const settings = new TimeSettings();

settings.parse("3 minutes and 8 seconds"); // 188000
settings.parse("2 y, 4 months + 22 days + 9 hours"); // 75566252000

Date

Format Date

Class DateSettings for the format:

Before call the format() function, you have to create a class called DateSettings. This function allows you to save the configuration you want in a variable, instead of rewrite everything.

new DateSettings(options);

Available options in the configuration for the format() function:

Parameter	Type	Optional	Default	Description
lang	string	✅	en	Language of date unities ('en' or 'fr').
format	string	✅	DD/MM/YYYY, HH:mm:ss.SSS	Format* of the string date.

*Format: If you want to dodge some words in the format string, you can surround them with [ and ]. It can be useful if you want to format a date, you can refer to the examples.

Available token for the date format:

Token	Meaning	Examples of output
YYYY	Four-digit year	1970, 2022
YY	Two-digit year	70, 22
MMMM	Month name (long)	January, December
MMM	Month name (short)	Jan, Dec
MM	Two-digit month	01, 12
M	One-digit month	1, 12
dddd	Day of week (long)	monday, sunday
ddd	Day of week (short - three-digit)	mon, sun
dd	Day of week (short - two-digit)	mo, su
DDD	Ordinal notation of date	1st, 2nd, 3rd, 4th
DD	Two-digit date	01, 31
D	One-digit date	1, 31
HH	Two-digit 24-hour	01, 23
H	One-digit 24-hour	1, 23
hh	Two-digit 12-hour	01, 11
h	One-digit 12 hour	1, 11
mm	Two-digit minute	01, 59
m	One-digit minute	1, 59
ss	Two-digit second	01, 59
s	One-digit second	1, 59
SSS	Three-digit millisecond	001, 999
SS	Two-digit millisecond	01, 99
S	One-digit millisecond	1, 9
R	Roman year	MMXXII
AA	Meridiem (uppercase with ellipsis)	A.M., P.M.
A	Meridiem (uppercase)	AM, PM
aa	Meridiem (lowercase with ellipsis)	a.m., p.m.
a	Meridiem	am, pm

Function format():

Now the settings ready, you can call the function format() which convert a date in milliseconds to a string with the format of your choice.

const DateSettingsFormat = new DateSettings({ lang: "en", format: "DD/MM/YYYY, HH:mm:ss.SSS" });
DateSettingsFormat.format(dateInMilliseconds);

Available arguments in the format() function:

Parameter	Type	Optional	Default	Description
dateInMilliseconds	number	❌		Date in milliseconds to convert into a string.

Examples:

const settings_1 = new DateSettings({ lang: "en", format: "[The] DDD [of] MMMM YYYY [at] hh:mm AA" }); // sunday 14/08/2022, 09:35:33.766
const settings_2 = new DateSettings({ lang: "en", format: "[It's] HH:mm:ss.SSS" });

settings_1.format(1660594792908); // The 15th of august 2022 at 10:19 P.M.
settings_2.format(1660594792908); // It's 22:19:52.908