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

What

This library is just a function collection for manipulation of date and time. It's tiny, simple, easy to learn.

Why

Because JS modules nowadays are getting more huge and complex, and there are many dependencies. Trying to keep simple and small each module is meaningful.

Features

• Minimalist. Less than 2k. (minified and gzipped)
• Universal (Isomorphic)
• Multi language support
• Not extending built-in Date object
• Old browser support. It even works on IE6

Install

via npm:

$ npm install date-and-time --save

via Bower (DEPRECATED):

$ bower install date-and-time

directly:

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

Changes

• 0.8.0 (Parser Update)

  • The parse() has become to return Invalid Date instead of NaN when parsing is failure (Breaking Change).
  • Added preparse(). It returns a Date Structure.
  • The isValid() has become to take a Date Structure in addition to a date string.
  • The isLeapYear() has become to take a year (number type) instead of a Date object (Breaking Change).

• 0.7.0

  • Added Danish support

Usage

Node.js:

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

Babel:

import date from 'date-and-time';

AMD:

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

Browser:

window.date;    // global object

API

format(dateObj, formatString[, utc])

Formatting a date

• @param {Date} dateObj - a Date object
• @param {string} formatString - a format string
• @param {boolean} [utc] - output as UTC
• @returns {string} a formatted string

const 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'

token	meaning	example
YYYY	year	0999, 2015
YY	year	15, 99
Y	year	999, 2015
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	24-hour	23, 08
H	24-hour	23, 8
A	meridiem	a.m., p.m.
hh	12-hour	11, 08
h	12-hour	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 1. Comments

Strings in parenthese [...] in the formatString will be ignored as comments:

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

---

parse(dateString, formatString[, utc])

Parsing a date string

• @param {string} dateString - a date string
• @param {string} formatString - a format string
• @param {boolean} [utc] - input as UTC
• @returns {Date} a constructed date

date.parse('2015/01/02 23:14:05', 'YYYY/MM/DD HH:mm:ss');   // => Jan 2 2015 23:14:05 GMT-0800
date.parse('02-01-2015', 'DD-MM-YYYY');                     // => Jan 2 2015 00:00:00 GMT-0800
date.parse('11:14:05 p.m.', 'hh:mm:ss A');                  // => Jan 1 1970 23:14:05 GMT-0800
date.parse('11:14:05 p.m.', 'hh:mm:ss A', true);            // => Jan 1 1970 15:14:05 GMT-0800
date.parse('Jam 1 2017', 'MMM D YYYY');                     // => Invalid Date
date.parse('Feb 29 2016', 'MMM D YYYY');                    // => Feb 29 2016 00:00:00 GMT-0800
date.parse('Feb 29 2017', 'MMM D YYYY');                    // => Invalid Date

token	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	24-hour	23, 08
H	24-hour	23, 8
hh	12-hour	11, 08
h	12-hour	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 1. Invalid Date

If the function fails to parse, it will return Invalid Date. Be careful as the Invalid Date is a Date object, not NaN or null. You can tell whether the Date object is invalid as follows:

const today = date.parse('Jam 1 2017', 'MMM D YYYY');

if (isNaN(today)) {
    // Failure
}

NOTE 2. Default Date Time

Default date is January 1, 1970, time is 00:00:00.000. Not passed values will be replaced with them:

date.parse('11:14:05 p.m.', 'hh:mm:ss A');  // => Jan 1 1970 23:14:05 GMT-0800
date.parse('Feb 2000', 'MMM YYYY');         // => Feb 1 2000 00:00:00 GMT-0800

NOTE 3. Max Date / Min Date

Parsable maximum date is December 31, 9999, minimum date is January 1, 0001.

date.parse('Dec 31 9999', 'MMM D YYYY');    // => Dec 31 9999 00:00:00 GMT-0800
date.parse('Dec 31 10000', 'MMM D YYYY');   // => Invalid Date

date.parse('Jan 1 0001', 'MMM D YYYY');     // => Jan 1 0001 00:00:00 GMT-0800
date.parse('Jan 1 0000', 'MMM D YYYY');     // => Invalid Date

NOTE 4. Auto Mapping

The YY token maps the year 69 or less to 2000s, the year 70 or more to 1900s. Using it is not recommended.

date.parse('Dec 31 0', 'MMM D YY');     // => Dec 31 2000 00:00:00 GMT-0800
date.parse('Dec 31 69', 'MMM D YY');    // => Dec 31 2069 00:00:00 GMT-0800
date.parse('Dec 31 70', 'MMM D YY');    // => Dec 31 1970 00:00:00 GMT-0800
date.parse('Dec 31 99', 'MMM D YY');    // => Dec 31 1999 00:00:00 GMT-0800

NOTE 5. 12-hour notation and Meridiem

If use the hh or h (12-hour) token, use together the A (meridiem) token to get the right value.

date.parse('11:14:05', 'hh:mm:ss');         // => Jan 1 1970 11:14:05 GMT-0800
date.parse('11:14:05 p.m.', 'hh:mm:ss A');  // => Jan 1 1970 23:14:05 GMT-0800

NOTE 6. Comments

Strings in parenthese [...] in the formatString will be ignored as comments:

date.parse('12 hours 34 minutes', 'HH hours mm minutes');       // => Invalid Date
date.parse('12 hours 34 minutes', 'HH [hours] mm [minutes]');   // => Jan 1 1970 12:34:00 GMT-0800

A white space works as a wild card, so that you can also write as follows:

date.parse('12 hours 34 minutes', 'HH       mm        ');   // => Jan 1 1970 12:34:00 GMT-0800

---

preparse(dateString, formatString)

Pre-parsing a date string

• @param {string} dateString - a date string
• @param {string} formatString - a format string
• @returns {Object} a date structure

This function takes exactly the same parameters with the parse(), but instead it returns a date structure like this:

date.preparse('2015/01/02 23:14:05', 'YYYY/MM/DD HH:mm:ss');

{
    Y: 2015,        // Year
    M: 1,           // Month
    D: 2,           // Day
    H: 23,          // 24-hour
    A: 0,           // Meridiem
    h: 0,           // 12-hour
    m: 14,          // Minute
    s: 5,           // Second
    S: 0,           // Millisecond
    _index: 19,     // Pointer offset
    _length: 19,    // Length of the date string
    _match: 6       // Token matching count
}

This object shows a parsing result. You can realize from it how the date string was parsed(, or why the parsing was failed).

---

isValid(arg[, formatString])

Validation

• @param {Object|string} arg - a date structure or a date string
• @param {string} [formatString] - a format string
• @returns {boolean} whether the date string is a valid date

This function takes either exactly the same parameters with the parse() or a date structure which the preparse() returns, evaluates the validity of them.

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

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

---

addYears(dateObj, years)

Adding years

• @param {Date} dateObj - a Date object
• @param {number} years - number of years to add
• @returns {Date} a date after adding the value

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

---

addMonths(dateObj, months)

Adding months

• @param {Date} dateObj - a Date object
• @param {number} months - number of months to add
• @returns {Date} a date after adding the value

const now = new Date();
const next_month = date.addMonths(now, 1);

---

addDays(dateObj, days)

Adding days

• @param {Date} dateObj - a Date object
• @param {number} days - number of days to add
• @returns {Date} a date after adding the value

const now = new Date();
const yesterday = date.addDays(now, -1);

---

addHours(dateObj, hours)

Adding hours

• @param {Date} dateObj - a Date object
• @param {number} hours - number of hours to add
• @returns {Date} a date after adding the value

const now = new Date();
const an_hour_ago = date.addHours(now, -1);

---

addMinutes(dateObj, minutes)

Adding minutes

• @param {Date} dateObj - a Date object
• @param {number} minutes - number of minutes to add
• @returns {Date} a date after adding the value

const now = new Date();
const two_minutes_later = date.addMinutes(now, 2);

---

addSeconds(dateObj, seconds)

Adding seconds

• @param {Date} dateObj - a Date object
• @param {number} seconds - number of seconds to add
• @returns {Date} a date after adding the value

const now = new Date();
const three_seconds_ago = date.addSeconds(now, -3);

---

addMilliseconds(dateObj, milliseconds)

Adding milliseconds

• @param {Date} dateObj - a Date object
• @param {number} milliseconds - number of milliseconds to add
• @returns {Date} a date after adding the value

const now = new Date();
const a_millisecond_later = date.addMilliseconds(now, 1);

---

subtract(date1, date2)

Subtracting

• @param {Date} date1 - a Date object
• @param {Date} date2 - a Date object
• @returns {Object} a result object subtracting date2 from date1

const today = new Date(2015, 0, 2);
const yesterday = new Date(2015, 0, 1);

date.subtract(today, yesterday).toDays();           // => 1 = today - yesterday
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(y)

Leap year

• @param {number} y - year
• @returns {boolean} whether the year is a leap year

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

---

isSameDay(date1, date2)

Comparison of two dates

• @param {Date} date1 - a Date object
• @param {Date} date2 - a Date object
• @returns {boolean} whether the dates are the same day (times are ignored)

const date1 = new Date(2017, 0, 2, 0);          // Jan 2 2017 00:00:00
const date2 = new Date(2017, 0, 2, 23, 59);     // Jan 2 2017 23:59:00
const date3 = new Date(2017, 0, 1, 23, 59);     // Jan 1 2017 23:59:00
date.isSameDay(date1, date2);   // => true
date.isSameDay(date1, date3);   // => false

---

locale([code])

Setting a locale

• @param {string} [code] - language code
• @returns {string} current language code

See the Locale section for details.

---

getLocales([code])

Getting a definition of locale

• @param {string} [code] - language code
• @returns {Object} definition of locale

See the Locale section for details.

---

setLocales(code, options)

Adding a new definition of locale

• @param {string} code - language code
• @param {Object} options - definition of locale

See the Locale section for details.

---

Locale

Although month, day of week, and meridiem (am / pm) are displayed in English, you can switch to other languages as follows:

Node.js:

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

Babel:

import date from 'date-and-time';
import 'date-and-time/locale/it';

date.locale('it');  // Italian
date.format(new Date(), 'dddd D MMMM'); // => 'Lunedì 11 gennaio'

AMD:

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

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>

It supports the following languages for now:

Arabic (ar), Azerbaijani (az), Bengali (bn), Burmese (my), Chinese (zh-cn), Chinese (zh-tw), Czech (cs), Danish (dk), Dutch (nl), English (en), French (fr), German (de), Greek (el), Hindi (hi), Hungarian (hu), Indonesian (id), Italian (it), Japanese (ja), Javanese (jv), Korean (ko), Persian (fa), Polish (pl), Portuguese (pt), Punjabi (pa-in), Romanian (ro), Russian (ru), Serbian (sr), Spanish (es), Thai (th), Turkish (tr), Ukrainian (uk), Uzbek (uz), Vietnamese (vi)

Customizing

If you have some problems with the default translation, you could change them as you want:

const 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'

However, If obviously wrong, please send a PR or post the issue.

Browser Support

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

License

MIT