date-and-time

What is date-and-time?

The date-and-time npm package is a lightweight library for date and time manipulation in JavaScript. It provides a variety of functions for parsing, formatting, adding, subtracting, and comparing dates and times.

What are date-and-time's main functionalities?

Formatting Dates

This feature allows you to format dates into various string representations. The format method takes a date object and a format string as arguments.

const date = new Date(2023, 9, 10);
const dateAndTime = require('date-and-time');
const formattedDate = dateAndTime.format(date, 'YYYY/MM/DD HH:mm:ss');
console.log(formattedDate); // Output: 2023/10/10 00:00:00

Parsing Dates

This feature allows you to parse date strings into JavaScript Date objects. The parse method takes a date string and a format string as arguments.

const dateAndTime = require('date-and-time');
const dateString = '2023/10/10 00:00:00';
const parsedDate = dateAndTime.parse(dateString, 'YYYY/MM/DD HH:mm:ss');
console.log(parsedDate); // Output: Tue Oct 10 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

Adding and Subtracting Time

This feature allows you to add or subtract time units (days, months, years, etc.) from a date. The addDays and addMonths methods are used in this example.

const dateAndTime = require('date-and-time');
let date = new Date(2023, 9, 10);
date = dateAndTime.addDays(date, 5);
console.log(date); // Output: Sun Oct 15 2023 00:00:00 GMT+0000 (Coordinated Universal Time)
date = dateAndTime.addMonths(date, -1);
console.log(date); // Output: Fri Sep 15 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

Comparing Dates

This feature allows you to compare dates. The isSameDay method checks if two dates fall on the same day.

const dateAndTime = require('date-and-time');
const date1 = new Date(2023, 9, 10);
const date2 = new Date(2023, 9, 15);
const isSameDay = dateAndTime.isSameDay(date1, date2);
console.log(isSameDay); // Output: false

Other packages similar to date-and-time

moment

Moment.js is a widely-used library for date and time manipulation. It offers extensive functionality for parsing, validating, manipulating, and formatting dates. Compared to date-and-time, Moment.js is more feature-rich but also larger in size.

date-fns

date-fns is a modern JavaScript date utility library that provides a comprehensive set of functions for date manipulation. It is modular, allowing you to import only the functions you need, making it more lightweight compared to Moment.js. date-fns is similar to date-and-time in terms of functionality but offers a more functional programming approach.

luxon

Luxon is a modern library for working with dates and times in JavaScript. It is built by one of the Moment.js developers and offers a more modern API with better support for internationalization. Luxon is more feature-rich than date-and-time and is designed to be a more modern alternative to Moment.js.

README

date-and-time

WHY

Probably the most famous DateTime library is Moment.js, that is so great but has been bloated (13.8k gz). This will be a good solution if you require a small one.

Features

• Minimalist. only has 1.8k gz
• multi language support
• not extending built-in date object
• legacy IE support. IE6+

Installation

Node.js:

$ npm install date-and-time --save

Bower:

$ bower install date-and-time

the browser:

<script src="date-and-time.min.js"></script>

Usage

Node.js:

var date = require('date-and-time');

AMD:

require(['date-and-time'], function (date) {
});

the browser:

window.date;    // global object

API

format(dateObj, formatString[, utc])

• {object} dateObj - target date
• {string} formatString - format string
• {boolean} [utc] - output as UTC

var now = new Date();
date.format(now, 'YYYY/MM/DD HH:mm:ss');    // => '2015/01/02 23:14:05'
date.format(now, 'ddd MMM DD YYYY');        // => 'Fri Jan 02 2015'
date.format(now, 'hh:mm A [GMT]Z');         // => '11:14 p.m. GMT-0800'
date.format(now, 'hh:mm A [GMT]Z', true);   // => '07:14 a.m. GMT+0000'

formatString	meaning	example
YYYY	year	2015, 1999
YY	year	15, 99
MMMM	month	January, December
MMM	month	Jan, Dec
MM	month	01, 12
M	month	1, 12
DD	day	02, 31
D	day	2, 31
dddd	day of week	Friday, Sunday
ddd	day of week	Fri, Sun
dd	day of week	Fr, Su
HH	hour-24	23, 08
H	hour-24	23, 8
A	meridiem	a.m., p.m.
hh	hour-12	11, 08
h	hour-12	11, 8
mm	minute	14, 07
m	minute	14, 7
ss	second	05, 10
s	second	5, 10
SSS	millisecond	753, 022
SS	millisecond	75, 02
S	millisecond	7, 0
Z	timezone	+0100, -0800

NOTE

[...] in the formatString will be a comment:

date.format(new Date(), 'DD-[MM]-YYYY');    // => '02-MM-2015'
date.format(new Date(), '[DD-[MM]-YYYY]');  // => 'DD-[MM]-YYYY'

parse(dateString, formatString[, utc])

• {string} dateString - date string
• {string} formatString - format string
• {boolean} [utc] - input as UTC

date.parse('2015/01/02 23:14:05', 'YYYY/MM/DD HH:mm:ss');   // => date object
date.parse('02-01-2015', 'DD-MM-YYYY');                     // => date object
date.parse('11:14:05 p.m.', 'hh:mm:ss A');                  // => (23:14:05 GMT-0800)
date.parse('11:14:05 p.m.', 'hh:mm:ss A', true);            // => (15:14:05 GMT-0800)

formatString	meaning	example
YYYY	year	2015, 1999
YY	year	15, 99
MMMM	month	January, December
MMM	month	Jan, Dec
MM	month	01, 12
M	month	1, 12
DD	day	02, 31
D	day	2, 31
HH	hour-24	23, 08
H	hour-24	23, 8
hh	hour-12	11, 08
h	hour-12	11, 8
A	meridiem	a.m., p.m.
mm	minute	14, 07
m	minute	14, 7
ss	second	05, 10
s	second	5, 10
SSS	millisecond	753, 022
SS	millisecond	75, 02
S	millisecond	7, 0

NOTE

When using hh or h (hour-12), need to use together A (meridiem).

isValid(dateString, formatString)

• {string} dateString - date string
• {string} formatString - format string

date.isValid('2015/01/02 23:14:05', 'YYYY/MM/DD HH:mm:ss'); // => true
date.isValid('02-29-2015', 'DD-MM-YYYY');                   // => false

formatString is the same as one of parse.

addYears(dateObj, years)

• {object} dateObj - the augend
• {number} years - the addend

var now = new Date();
var next_year = date.addYears(now, 1);  // => Date object

addMonths(dateObj, months)

• {object} dateObj - the augend
• {number} months - the addend

var now = new Date();
var next_month = date.addMonths(now, 1); // => Date object

addDays(dateObj, days)

• {object} dateObj - the augend
• {number} days - the addend

var now = new Date();
var yesterday = date.addDays(now, -1);  // => Date object

addHours(dateObj, hours)

• {object} dateObj - the augend
• {number} hours - the addend

var now = new Date();
var an_hour_ago = date.addHours(now, -1); // => Date object

addMinutes(dateObj, minutes)

• {object} dateObj - the augend
• {number} minutes - the addend

var now = new Date();
var two_minutes_later = date.addMinutes(now, 2);    // => Date object

addSeconds(dateObj, seconds)

• {object} dateObj - the augend
• {number} seconds - the addend

var now = new Date();
var three_seconds_ago = date.addSeconds(now, -3);   // => Date object

addMilliseconds(dateObj, milliseconds)

• {object} dateObj - the augend
• {number} milliseconds -the addend

var now = new Date();
var a_millisecond_later = date.addMilliseconds(now, 1); // => Date object

subtract(dateObj1, dateObj2)

• {object} date1 - the minuend
• {object} date2 - the subtrahend

var today = new Date(2015, 0, 2);
var yesterday = new Date(2015, 0, 1);
date.subtract(today, yesterday).toDays();           // => 1
date.subtract(today, yesterday).toHours();          // => 24
date.subtract(today, yesterday).toMinutes();        // => 1440
date.subtract(today, yesterday).toSeconds();        // => 86400
date.subtract(today, yesterday).toMilliseconds();   // => 86400000

isLeapYear(dateObj)

• {object} dateObj - target date

var date1 = new Date(2015, 0, 2);
var date2 = new Date(2012, 0, 2);
date.isLeapYear(date1); // => false
date.isLeapYear(date2); // => true

Locale

It supports the following languages for now:

• Arabic (ar)
• Bengali (bn)
• Chinese (zh-cn)
• Chinese (zh-tw)
• English (en)
• French (fr)
• German (de)
• Hindi (hi)
• Italian (it)
• Japanese (ja)
• Korean (ko)
• Portuguese (pt)
• Russian (ru)
• Spanish (es)

Month, day of week, and meridiem are used English by default. If you want to use other languages, can switch to them as follows:
Node.js:

var date = require('date-and-time');
date.locale('fr');  // French
date.format(new Date(), 'dddd D MMMM'); // => 'lundi 11 janvier'

AMD:

require(['date-and-time', 'locale/de'], function (date) {
    date.locale('de');  // German
    date.format(new Date(), 'dddd, D. MMMM');   // => 'Montag, 11. Januar'
});

the browser:

<script src="date-and-time.min.js"></script>
<script src="locale/zh-cn.js"></script>
<script>
date.locale('zh-cn');  // Chinese
date.format(new Date(), 'MMMD日dddd');  // => '1月11日星期一'
</script>

Customizing

You can not only switch to other languages, but can customize them as you want:

var now = new Date();
date.format(now, 'h:m A');  // => '12:34 p.m.'

date.setLocales('en', {
    A: ['AM', 'PM']
});

date.format(now, 'h:m A');  // => '12:34 PM'

Browser Support

Chrome, Firefox, Safari, Opera, and Internet Explorer 6+.

License

MIT