A node.js package for Steven Levithan's excellent dateFormat() function.
Modifications
- Removed the
Date.prototype.formatmethod. Sorry folks, but extending native prototypes is for suckers. - Added a
module.exports = dateFormat;statement at the bottom - Added the placeholder
Nto get the ISO 8601 numeric representation of the day of the week
Installation
$ npm install dateformat $ dateformat --help
Usage
As taken from Steven's post, modified to match the Modifications listed above:
import dateFormat, { masks } from "dateformat"; const now = new Date(); // Basic usage dateFormat(now, "dddd, mmmm dS, yyyy, h:MM:ss TT"); // Saturday, June 9th, 2007, 5:46:21 PM // You can use one of several named masks dateFormat(now, "isoDateTime"); // 2007-06-09T17:46:21 // ...Or add your own masks.hammerTime = 'HH:MM! "Can\'t touch this!"'; dateFormat(now, "hammerTime"); // 17:46! Can't touch this! // You can also provide the date as a string dateFormat("Jun 9 2007", "fullDate"); // Saturday, June 9, 2007 // Note that if you don't include the mask argument, // dateFormat.masks.default is used dateFormat(now); // Sat Jun 09 2007 17:46:21 // And if you don't include the date argument, // the current date and time is used dateFormat(); // Sat Jun 09 2007 17:46:22 // You can also skip the date argument (as long as your mask doesn't // contain any numbers), in which case the current date/time is used dateFormat("longTime"); // 5:46:22 PM EST // And finally, you can convert local time to UTC time. Simply pass in // true as an additional argument (no argument skipping allowed in this case): dateFormat(now, "longTime", true); // 10:46:21 PM UTC // ...Or add the prefix "UTC:" or "GMT:" to your mask. dateFormat(now, "UTC:h:MM:ss TT Z"); // 10:46:21 PM UTC // You can also get the ISO 8601 week of the year: dateFormat(now, "W"); // 42 // and also get the ISO 8601 numeric representation of the day of the week: dateFormat(now, "N"); // 6
Mask options
| Mask | Description |
|---|---|
d |
Day of the month as digits; no leading zero for single-digit days. |
dd |
Day of the month as digits; leading zero for single-digit days. |
ddd |
Day of the week as a three-letter abbreviation. |
DDD |
"Ysd", "Tdy" or "Tmw" if date lies within these three days. Else fall back to ddd. |
dddd |
Day of the week as its full name. |
DDDD |
"Yesterday", "Today" or "Tomorrow" if date lies within these three days. Else fall back to dddd. |
m |
Month as digits; no leading zero for single-digit months. |
mm |
Month as digits; leading zero for single-digit months. |
mmm |
Month as a three-letter abbreviation. |
mmmm |
Month as its full name. |
yy |
Year as last two digits; leading zero for years less than 10. |
yyyy |
Year represented by four digits. |
h |
Hours; no leading zero for single-digit hours (12-hour clock). |
hh |
Hours; leading zero for single-digit hours (12-hour clock). |
H |
Hours; no leading zero for single-digit hours (24-hour clock). |
HH |
Hours; leading zero for single-digit hours (24-hour clock). |
M |
Minutes; no leading zero for single-digit minutes. |
MM |
Minutes; leading zero for single-digit minutes. |
N |
ISO 8601 numeric representation of the day of the week. |
o |
GMT/UTC timezone offset, e.g. -0500 or +0230. |
p |
GMT/UTC timezone offset, e.g. -05:00 or +02:30. |
s |
Seconds; no leading zero for single-digit seconds. |
ss |
Seconds; leading zero for single-digit seconds. |
S |
The date's ordinal suffix (st, nd, rd, or th). Works well with d. |
l |
Milliseconds; gives 3 digits. |
L |
Milliseconds; gives 2 digits. |
t |
Lowercase, single-character time marker string: a or p. |
tt |
Lowercase, two-character time marker string: am or pm. |
T |
Uppercase, single-character time marker string: A or P. |
TT |
Uppercase, two-character time marker string: AM or PM. |
W |
ISO 8601 week number of the year, e.g. 4, 42 |
WW |
ISO 8601 week number of the year, leading zero for single-digit, e.g. 04, 42 |
Z |
US timezone abbreviation, e.g. EST or MDT. For non-US timezones, the GMT/UTC offset is returned, e.g. GMT-0500 |
'...', "..." |
Literal character sequence. Surrounding quotes are removed. |
UTC: |
Must be the first four characters of the mask. Converts the date from local time to UTC/GMT/Zulu time before applying the mask. The "UTC:" prefix is removed. |
Named Formats
| Name | Mask | Example |
|---|---|---|
default |
ddd mmm dd yyyy HH:MM:ss |
Sat Jun 09 2007 17:46:21 |
shortDate |
m/d/yy |
6/9/07 |
paddedShortDate |
mm/dd/yyyy |
06/09/2007 |
mediumDate |
mmm d, yyyy |
Jun 9, 2007 |
longDate |
mmmm d, yyyy |
June 9, 2007 |
fullDate |
dddd, mmmm d, yyyy |
Saturday, June 9, 2007 |
shortTime |
h:MM TT |
5:46 PM |
mediumTime |
h:MM:ss TT |
5:46:21 PM |
longTime |
h:MM:ss TT Z |
5:46:21 PM EST |
isoDate |
yyyy-mm-dd |
2007-06-09 |
isoTime |
HH:MM:ss |
17:46:21 |
isoDateTime |
yyyy-mm-dd'T'HH:MM:sso |
2007-06-09T17:46:21+0700 |
isoUtcDateTime |
UTC:yyyy-mm-dd'T'HH:MM:ss'Z' |
2007-06-09T22:46:21Z |
Localization
Day names, month names and the AM/PM indicators can be localized by passing an object with the necessary strings. For example:
import { i18n } from "dateformat"; i18n.dayNames = [ "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", ]; i18n.monthNames = [ "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec", "January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December", ]; i18n.timeNames = ["a", "p", "am", "pm", "A", "P", "AM", "PM"];
Notice that only one language is supported at a time and all strings must be present in the new value.
Breaking change in 2.1.0
- 2.1.0 was published with a breaking change, for those using localized strings.
- 2.2.0 has been published without the change, to keep packages refering to ^2.0.0 to continue working. This is now branch v2_2.
- 3.0.* contains the localized AM/PM change.
License
(c) 2007-2009 Steven Levithan stevenlevithan.com, MIT license.