Skip to content

Commit

Permalink
Merge upstream branch 'master' into patch-1
Browse files Browse the repository at this point in the history
  • Loading branch information
Matthew Badeau committed Mar 10, 2021
2 parents 61e2c52 + f309c8a commit 6c6f3eb
Show file tree
Hide file tree
Showing 45 changed files with 5,565 additions and 349 deletions.
2 changes: 1 addition & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ vendor
build
dest
dist
src
lib
lib-cov
coverage
nbproject
Expand Down
5 changes: 5 additions & 0 deletions .npmignore
Original file line number Diff line number Diff line change
@@ -1,2 +1,7 @@
test
.travis.yml
benchmark
CONTRIBUTING.md
src
.gitignore
babel.config.json
3 changes: 1 addition & 2 deletions .travis.yml
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
language: node_js
node_js:
- "0.11"
- "0.10"
- "node"
30 changes: 30 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# Contributing to dateformat

Thanks for taking the time to contribute to dateformat!!!
Feel free to raise a PR or Issue for any suggested improvements to the package.

## Running dateformat

To run dateformat, first clone the repository to your local machine.
Then run `npm i` to install all the required dependencies.
Then build dateformat by running `npm run build`.
Then you can import dateformat from the `lib` directory and call it as needed.

## Benchmarking

If you want to try and improve the performance of dateformat, you can use the benchmarking script.
To use the script:

- Copy the contents of the `lib/dateformat.js` file into the `benchmark/previousDateFormat.js` file.
- Make your code changes to `lib/dateformat.js` as you normaly would
- run `npm run benchmark` in root directory to see the comparison of performance before and after your change

A positive number for improvement indicates that your changes have improved the speed of dateformat.
Any different between -5% and 5% can be disregarded as minor variance.
It is recommended that you run this benchmark after any changes to the business logic of dateformat.
This is to ensure that there is no detrimental impact on performance from your change.
A screenshot it the PR would be much appreciated also.

## Running Tests

To test dateformat, just run `npm run test` and see the results.
174 changes: 108 additions & 66 deletions Readme.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@ A node.js package for Steven Levithan's excellent [dateFormat()][dateformat] fun

## 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
- 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

Expand All @@ -20,8 +20,9 @@ $ dateformat --help
## Usage

As taken from Steven's post, modified to match the Modifications listed above:

```js
var dateFormat = require('dateformat');
var dateFormat = require("dateformat");
var now = new Date();

// Basic usage
Expand Down Expand Up @@ -70,89 +71,130 @@ dateFormat(now, "W");
// 42

// and also get the ISO 8601 numeric representation of the day of the week:
dateFormat(now,"N");
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.
`dddd` | Day of the week as its full name.
`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.
`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. 42
`Z` | US timezone abbreviation, e.g. EST or MDT. With non-US timezones or in the
`'...'`, `"..."` | 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.
| 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
`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:ss` | 2007-06-09T17:46:21
`isoUtcDateTime` | `UTC:yyyy-mm-dd'T'HH:MM:ss'Z'` | 2007-06-09T22:46:21Z
| 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:

```js
var dateFormat = require('dateformat');
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'
]
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.
> _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.
- 3.0.\* contains the localized AM/PM change.

## License

Expand Down
10 changes: 10 additions & 0 deletions babel.config.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
{
"presets": [
[
"@babel/env",
{
"targets": "> 0.01%, not dead"
}
]
]
}
38 changes: 38 additions & 0 deletions benchmark/benchmark.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
var previousDateFormat = require("./previousDateFormat");
var newDateFormat = require("../lib/dateformat");

const masks = [
"d",
"W",
"o",
"N",
"shortDate",
"fullDate",
"longTime",
"default",
];
let results = [];

masks.forEach((mask) => {
const previousSpeed = getSpeed(false, mask);
const newSpeed = getSpeed(true, mask);
results.push({
mask: mask,
previous: previousSpeed + "ms",
new: newSpeed + "ms",
improvement: Math.round((previousSpeed / newSpeed - 1) * 100, 2) + "%",
});
});

function getSpeed(newVersion, mask) {
const startTime = new Date();
const date = new Date();
for (var i = 0; i < 100_000; i++) {
if (newVersion) newDateFormat(date, mask);
else previousDateFormat(date, mask);
}
const endTime = new Date();
return endTime - startTime;
}

console.table(results);

0 comments on commit 6c6f3eb

Please sign in to comment.