@matteo.collina/dateformat
v5.0.1
Published
A node.js package for Steven Levithan's excellent dateFormat() function. A commonjs module.
Downloads
337
Readme
dateformat
A node.js package for Steven Levithan's excellent dateFormat() function.
This module was forked from https://github.com/felixge/node-dateformat to avoid a CJS to ESM migration. This fork will be maintained as long as it is necessary.
Modifications
- Removed the
Date.prototype.format
method. Sorry folks, but extending native prototypes is for suckers. - Added a
module.exports = dateFormat;
statement at the bottom - Added the placeholder
N
to get the ISO 8601 numeric representation of the day of the week
Installation
$ npm install @matteo.collina/dateformat
$ dateformat --help
Usage
As taken from Steven's post, modified to match the Modifications listed above:
var dateFormat = require("@matteo.collina/dateformat");
var 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
dateFormat.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:
var dateFormat = require("dateformat");
dateFormat.i18n = {
dayNames: [
"Sun",
"Mon",
"Tue",
"Wed",
"Thu",
"Fri",
"Sat",
"Sunday",
"Monday",
"Tuesday",
"Wednesday",
"Thursday",
"Friday",
"Saturday",
],
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",
],
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.