Security News
JavaScript Leaders Demand Oracle Release the JavaScript Trademark
In an open letter, JavaScript community leaders urge Oracle to give up the JavaScript trademark, arguing that it has been effectively abandoned through nonuse.
date-and-time
Advanced tools
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.
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
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 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 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.
This library is a minimalist collection of functions for manipulating JS date and time. It's tiny, simple, easy to learn.
JS modules nowadays are getting more huge and complex, and there are also many dependencies. Trying to keep each module simple and small is meaningful.
npm install date-and-time --save
<script src="/path/to/date-and-time.min.js"></script>
0.13.0
format()
now supports a compiled formatString.const pattern = date.compile('MMM D YYYY');
date.format(new Date(2020, 2, 3), pattern); // => Mar 3 2020
date.format(new Date(2020, 3, 4), pattern); // => Apr 4 2020
date.format(new Date(2020, 4, 5), pattern); // => May 5 2020
parse()
now supports ...
(ellipsis) token. The preparse()
and the isValid()
are too.// Cannot write like this even if you want to get only a date part.
date.parse('Mar 05 2020 10:42:29 GMT-0800', 'MMM D YYYY'); // => Invalid Date
// Previously, it was necessary to adjust the length of the format string by appending white spaces of the same length as a part to ignore.
date.parse('Mar 05 2020 10:42:29 GMT-0800', 'MMM D YYYY ');
// Can write simply like this using the ellipsis token.
date.parse('Mar 05 2020 10:42:29 GMT-0800', 'MMM D YYYY...');
day-of-week
plugin for the parser. However this is a dummy, not effective at all. See PLUGINS.md for details.// If a date string has day of week at the head, cannot parse it unless remove that part from it or fill white spaces that part of the format string.
date.parse('Thu Mar 05 2020 10:42:29 GMT-0800', ' MMM D YYYY...');
// This plugin provides `dd`, `ddd` and `dddd` tokens for such a case. However they are not effective at all because day of week has not information to identify a date.
date.parse('Thu Mar 05 2020 10:42:29 GMT-0800', 'ddd MMM D YYYY...');
subtract()
now returns a REAL number. Previously, it returned values with truncated decimals.const now = new Date(2020, 2, 5, 1, 2, 3, 4);
const new_years_day = new Date(2020, 0, 1);
date.subtract(now, new_years_day).toDays(); // => 64.04309032407407
timespan
plugin. This plugin provides timeSpan()
function to display a formatted elapsed time. This will might be integrated with the subtract()
. See PLUGINS.md for details.const now = new Date(2020, 2, 5, 1, 2, 3, 4);
const new_years_day = new Date(2020, 0, 1);
date.timeSpan(now, new_years_day).toDays('D HH:mm:ss.SSS'); // => '64 01:02:03.004'
date.timeSpan(now, new_years_day).toHours('H [hours] m [minutes] s [seconds]'); // => '1537 hours 2 minutes 3 seconds'
microsecond
plugin for the parser. Microsecond is not supported by date objects so that it is rounded millisecond
at the inside. See PLUGINS.md for details.0.12.0
The parser now supports Z
token to parse timezone offset.
(Breaking Change) Excleded YY
token from the parser, added it as two-digit-year
plugin. See PLUGINS.md for details.
(Breaking Change) Decided to change the default behavior of A
token to fix the non-intuitive definition. Sepcifically, in the format()
it now outputs AM
/ PM
instead of a.m.
/ p.m.
, and in the parse()
it recognizes AM
/ PM
only. Other A
tokens are supported as meridiem
plugin.
token | new meaning | example | default |
---|---|---|---|
A | meridiem (uppercase) | AM, PM | ✔️ |
AA | meridiem (uppercase with ellipsis) | A.M., P.M. | |
a | meridiem (lowercase) | am, pm | |
aa | meridiem (lowercase with ellipsis) | a.m., p.m. |
0.11.0
compile()
function that precompiling a date-time string for the parser. If you need to process many date-time string with one format, you can get results faster than before by precompiling the format string with this function.// We have passed a string format at the 2nd parameter each time when calling the parse() function.
date.parse('Mar 22 2019 2:54:21 PM', 'MMM D YYYY h:m:s A');
date.parse('Jul 27 2019 4:15:24 AM', 'MMM D YYYY h:m:s A');
date.parse('Dec 25 2019 3:51:11 AM', 'MMM D YYYY h:m:s A');
// You can precompile the string format.
const pattern = date.compile('MMM D YYYY h:m:s A');
// The parse() will be able to finish faster than passing the format string each time.
date.parse('Mar 22 2019 2:54:21 PM', pattern);
date.parse('Jul 27 2019 4:15:24 AM', pattern);
date.parse('Dec 25 2019 3:51:11 AM', pattern);
const pattern = date.compile('MMM D YYYY h:m:s A');
// The isValid() will also too.
date.isValid('Mar 22 2019 2:54:21 PM', pattern);
const date = require('date-and-time');
import date from 'date-and-time';
window.date; // global object
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 PM GMT-0800'
date.format(now, 'hh:mm A [GMT]Z', true); // => '07:14 AM GMT+0000'
const pattern = date.compile('ddd, MMM DD YYYY');
date.format(now, pattern); // => 'Fri, Jan 02 2015'
Available tokens and their meanings are as follows:
token | meaning | examples of output |
---|---|---|
YYYY | four-digit year | 0999, 2015 |
YY | two-digit year | 99, 01, 15 |
Y | four-digit year without zero-padding | 2, 44, 888, 2015 |
MMMM | month name (long) | January, December |
MMM | month name (short) | Jan, Dec |
MM | month with zero-padding | 01, 12 |
M | month | 1, 12 |
DD | date with zero-padding | 02, 31 |
D | date | 2, 31 |
dddd | day of week (long) | Friday, Sunday |
ddd | day of week (short) | Fri, Sun |
dd | day of week (very short) | Fr, Su |
HH | 24-hour with zero-padding | 23, 08 |
H | 24-hour | 23, 8 |
hh | 12-hour with zero-padding | 11, 08 |
h | 12-hour | 11, 8 |
A | meridiem (uppercase) | AM, PM |
mm | minute with zero-padding | 14, 07 |
m | minute | 14, 7 |
ss | second with zero-padding | 05, 10 |
s | second | 5, 10 |
SSS | millisecond (high accuracy) | 753, 022 |
SS | millisecond (middle accuracy) | 75, 02 |
S | millisecond (low accuracy) | 7, 0 |
Z | timezone offset | +0100, -0800 |
You can also use the following tokens by importing plugins. See PLUGINS.md for details.
token | meaning | examples of output |
---|---|---|
DDD | ordinal notation of date | 1st, 2nd, 3rd |
AA | meridiem (uppercase with ellipsis) | A.M., P.M. |
a | meridiem (lowercase) | am, pm |
aa | meridiem (lowercase with ellipsis) | a.m., p.m. |
String 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'
This function usually outputs a local date-time string. Set to true the utc
option (the 3rd parameter) if you would like to get a UTC date-time string.
date.format(new Date(), 'hh:mm A [GMT]Z'); // => '11:14 PM GMT-0800'
date.format(new Date(), 'hh:mm A [GMT]Z', true); // => '07:14 AM GMT+0000'
You can also define your own tokens. See EXTEND.md for details.
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 PM', 'hh:mm:ss A'); // => Jan 1 1970 23:14:05 GMT-0800
date.parse('11:14:05 PM', 'hh:mm:ss A', true); // => Jan 1 1970 23:14:05 GMT+0000 (Jan 1 1970 15:14:05 GMT-0800)
date.parse('23:14:05 GMT+0900', 'HH:mm:ss [GMT]Z'); // => Jan 1 1970 23:14:05 GMT+0900 (Jan 1 1970 06:14:05 GMT-0800)
date.parse('Jam 1 2017', 'MMM D YYYY'); // => Invalid Date
date.parse('Feb 29 2017', 'MMM D YYYY'); // => Invalid Date
Available tokens and their meanings are as follows:
token | meaning | examples of acceptable form |
---|---|---|
YYYY | four-digit year | 0999, 2015 |
Y | four-digit year without zero-padding | 2, 44, 88, 2015 |
MMMM | month name (long) | January, December |
MMM | month name (short) | Jan, Dec |
MM | month with zero-padding | 01, 12 |
M | month | 1, 12 |
DD | date with zero-padding | 02, 31 |
D | date | 2, 31 |
HH | 24-hour with zero-padding | 23, 08 |
H | 24-hour | 23, 8 |
hh | 12-hour with zero-padding | 11, 08 |
h | 12-hour | 11, 8 |
A | meridiem (uppercase) | AM, PM |
mm | minute with zero-padding | 14, 07 |
m | minute | 14, 7 |
ss | second with zero-padding | 05, 10 |
s | second | 5, 10 |
SSS | millisecond (high accuracy) | 753, 022 |
SS | millisecond (middle accuracy) | 75, 02 |
S | millisecond (low accuracy) | 7, 0 |
Z | timezone offset | +0100, -0800 |
You can also use the following tokens by importing plugins. See PLUGINS.md for details.
token | meaning | examples of acceptable form |
---|---|---|
YY | two-digit year | 90, 00, 08, 19 |
Y | two-digit year without zero-padding | 90, 0, 8, 19 |
A | meridiem | AM, PM, A.M., P.M., am, pm, a.m., p.m. |
dddd | day of week (long) | Friday, Sunday |
ddd | day of week (short) | Fri, Sun |
dd | day of week (very short) | Fr, Su |
SSSSSS | microsecond (high accuracy) | 123456, 000001 |
SSSSS | microsecond (middle accuracy) | 12345, 00001 |
SSSS | microsecond (low accuracy) | 1234, 0001 |
If the function fails to parse, it will return Invalid Date
. Notice that 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
}
This function usually assumes the dateString
is a local date-time. Set to true the utc
option (the 3rd parameter) if it is a UTC date-time.
date.parse('11:14:05 PM', 'hh:mm:ss A'); // => Jan 1 1970 23:14:05 GMT-0800
date.parse('11:14:05 PM', 'hh:mm:ss A', true); // => Jan 1 1970 23:14:05 GMT+0000 (Jan 1 1970 15:14:05 GMT-0800)
Default date is January 1, 1970
, time is 00:00:00.000
. Values not passed will be complemented with them:
date.parse('11:14:05 PM', '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
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
If use hh
or h
(12-hour) token, use together 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 PM', 'hh:mm:ss A'); // => Jan 1 1970 23:14:05 GMT-0800
String 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 wildcard token. This token is not interpret into anything. This means it can be ignored a specific variable string. For example, when you would like to ignore a time part from a date string, you can write as follows:
// This will be an error.
date.parse('2015/01/02 11:14:05', 'YYYY/MM/DD'); // => Invalid Date
// Adjust the length of the format string by appending white spaces of the same length as a part to ignore to the end of it.
date.parse('2015/01/02 11:14:05', 'YYYY/MM/DD '); // => Jan 2 2015 00:00:00 GMT-0800
The parser supports ...
(ellipse) token. The above example can also be written like this:
date.parse('2015/01/02 11:14:05', 'YYYY/MM/DD...'); // => Jan 2 2015 00:00:00 GMT-0800
const pattern = date.compile('MMM D YYYY h:m:s A');
date.parse('Mar 22 2019 2:54:21 PM', pattern);
date.parse('Jul 27 2019 4:15:24 AM', pattern);
date.parse('Dec 25 2019 3:51:11 AM', pattern);
date.format(new Date(), pattern); // => Mar 16 2020 6:24:56 PM
If you are going to call the format()
, the parse()
or the isValid()
many times with one string format, recommended to precompile and reuse it for performance.
This function takes exactly the same parameters with the parse()
, but returns a date structure as follows unlike that:
date.preparse('Fri Jan 2015 02 23:14:05 GMT-0800', ' MMM YYYY DD HH:mm:ss [GMT]Z');
{
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
Z: 480, // Timsezone offset
_index: 33, // Pointer offset
_length: 33, // Length of the date string
_match: 7 // Token matching count
}
This date structure provides a parsing result. You will be able to tell from it how the date string was parsed(, or why the parsing was failed).
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
const now = new Date();
const next_year = date.addYears(now, 1);
const now = new Date();
const next_month = date.addMonths(now, 1);
const now = new Date();
const yesterday = date.addDays(now, -1);
const now = new Date();
const an_hour_ago = date.addHours(now, -1);
const now = new Date();
const two_minutes_later = date.addMinutes(now, 2);
const now = new Date();
const three_seconds_ago = date.addSeconds(now, -3);
const now = new Date();
const a_millisecond_later = date.addMilliseconds(now, 1);
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
date.isLeapYear(2015); // => false
date.isLeapYear(2012); // => true
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
It returns a current language code if called without any parameters.
date.locale(); // => "en"
To switch to any other language, call it with a language code.
date.locale('es'); // Switch to Spanish
See LOCALE.md for details.
Extend a current locale. See EXTEND.md for details.
Plugin is a named locale definition defined with the extend()
. See PLUGINS.md for details.
Chrome, Firefox, Safari, Edge, and Internet Explorer 6+.
MIT
FAQs
A Minimalist DateTime utility for Node.js and the browser
The npm package date-and-time receives a total of 409,329 weekly downloads. As such, date-and-time popularity was classified as popular.
We found that date-and-time demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In an open letter, JavaScript community leaders urge Oracle to give up the JavaScript trademark, arguing that it has been effectively abandoned through nonuse.
Security News
The initial version of the Socket Python SDK is now on PyPI, enabling developers to more easily interact with the Socket REST API in Python projects.
Security News
Floating dependency ranges in npm can introduce instability and security risks into your project by allowing unverified or incompatible versions to be installed automatically, leading to unpredictable behavior and potential conflicts.