date-and-time 1.0.0 → 2.1.0

package/README.md

@@ -24,16 +24,30 @@ npm i date-and-time
 
 ## Recent Changes
 
-- 1.0.0
-  - **First stable release!**
-  - ES Modules support.
-  - Added Kinyarwanda support.
+- 2.1.0
+  - Fixed an issue that the lib's functions assigned to variables using ES6 destructuring assignment cause an error.
 
-- 0.14.2
-  - Fixed regular expression denial of service (ReDoS) vulnerability.
+  ```javascript
+  // Destructuring assignment
+  const { format, parse } = require('date-and-time');
 
-- 0.14.1
-  - Fixed a bug characters inside square brackets `[]` are not validated.
+  // These used to be errors in 2.0.x.
+  format(new Date(), 'MMM DD YYYY');
+  parse('Jan 11 2022', 'MMM DD YYYY');
+  ```
+
+  - Added Swedish support.
+
+- 2.0.1
+  - Fixed a bug that the timezone plugin does not support changing locales.
+
+- 2.0.0
+  - Fixed a conflict when importing multiple plugins and locales.
+  - **Breaking Changes!** Due to the above fix, the specifications of plugin, locale, and extension have been changed. The `meridiem` plugin and the `two-digit-year` plugin are now partially incompatible with previous ones. See [here](./PLUGINS.md) for details. Also the `extend()` function has changed. If you are using it, check [here](./EXTEND.md) for any impact. The locales are still compatible.
+  - Added `timezone` plugin. You can now use the IANA timezone name to output a datetime string or input a date object. See [PLUGINS.md](./PLUGINS.md) for details.
+
+- 1.0.1
+  - Updated dev dependencies to resolve vulnerability.
 
 ## Usage
 
@@ -63,58 +77,58 @@ import date from '/path/to/date-and-time.es.min.js';
 <script src="/path/to/date-and-time.min.js"></script>
 ```
 
-### NOTE
+### Note
 
 - If you want to use ES Modules in Node.js without a transpiler, you need to add `"type": "module"` in your `package.json` or change your file extension from `.js` to `.mjs`.
 
 ## API
 
-- [format](#formatdateObj-formatString-utc)
+- [format](#formatdateobj-arg-utc)
   - Formatting a Date and Time (Date -> String)
 
-- [parse](#parsedateString-arg-utc)
+- [parse](#parsedatestring-arg-utc)
   - Parsing a Date and Time string (String -> Date)
 
-- [compile](#compileformatString)
+- [compile](#compileformatstring)
   - Compiling a format string
 
-- [preparse](#preparsedateString-arg)
+- [preparse](#preparsedatestring-arg)
   - Pre-parsing a Date and Time string
 
-- [isValid](#isValidarg1-arg2)
+- [isValid](#isvalidarg1-arg2)
   - Validation
 
-- [transform](#transformdateString-arg1-arg2-utc)
+- [transform](#transformdatestring-arg1-arg2-utc)
   - Transforming a Date and Time string (String -> String)
 
-- [addYears](#addYearsdateObj-years)
+- [addYears](#addyearsdateobj-years)
   - Adding years
 
-- [addMonths](#addMonthsdateObj-months)
+- [addMonths](#addmonthsdateobj-months)
   - Adding months
 
-- [addDays](#addDaysdateObj-days)
+- [addDays](#adddaysdateobj-days)
   - Adding days
 
-- [addHours](#addHoursdateObj-hours)
+- [addHours](#addhoursdateobj-hours)
   - Adding hours
 
-- [addMinutes](#addMinutesdateObj-minutes)
+- [addMinutes](#addminutesdateobj-minutes)
   - Adding minutes
 
-- [addSeconds](#addSecondsdateObj-seconds)
+- [addSeconds](#addsecondsdateobj-seconds)
   - Adding seconds
 
-- [addMilliseconds](#addMillisecondsdateObj-milliseconds)
+- [addMilliseconds](#addmillisecondsdateobj-milliseconds)
   - Adding milliseconds
 
 - [subtract](#subtractdate1-date2)
   - Subtracting two dates
 
-- [isLeapYear](#isLeapYeary)
+- [isLeapYear](#isleapyeary)
   - Whether year is leap year
 
-- [isSameDay](#isSameDaydate1-date2)
+- [isSameDay](#issamedaydate1-date2)
   - Comparison of two dates
 
 - [locale](#localecode-locale)
@@ -126,7 +140,7 @@ import date from '/path/to/date-and-time.es.min.js';
 - [plugin](#pluginname-plugin)
   - Importing or defining plugins
 
-### format(dateObj, formatString[, utc])
+### format(dateObj, arg[, utc])
 
 - @param {**Date**} dateObj - a Date object
 - @param {**string|Array.\<string\>**} arg - a format string or its compiled object
@@ -183,7 +197,7 @@ You can also use the following tokens by importing plugins. See [PLUGINS.md](./P
 | a     | meridiem (lowercase)                 | am, pm             |
 | aa    | meridiem (lowercase with ellipsis)   | a.m., p.m.         |
 
-#### NOTE 1. Comments
+#### Note 1. Comments
 
 String in parenthese `[...]` in the `formatString` will be ignored as comments:
 
@@ -192,7 +206,7 @@ date.format(new Date(), 'DD-[MM]-YYYY');    // => '02-MM-2015'
 date.format(new Date(), '[DD-[MM]-YYYY]');  // => 'DD-[MM]-YYYY'
 ```
 
-#### NOTE 2. Output as UTC
+#### Note 2. Output as UTC
 
 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.
 
@@ -201,13 +215,13 @@ 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'
 ```
 
-#### NOTE 3. More Tokens
+#### Note 3. More Tokens
 
 You can also define your own tokens. See [EXTEND.md](./EXTEND.md) for details.
 
 ### parse(dateString, arg[, utc])
 
-- @param {string} dateString - a date string
+- @param {**string**} dateString - a date string
 - @param {**string|Array.\<string\>**} arg - a format string or its compiled object
 - @param {**boolean**} [utc] - input as UTC
 - @returns {**Date**} a constructed date
@@ -224,45 +238,46 @@ 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                           |
+| 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](./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                             |
-
-#### NOTE 1. Invalid Date
+| token  | meaning                              | examples of acceptable form |
+|:-------|:-------------------------------------|:----------------------------|
+| YY     | two-digit year                       | 90, 00, 08, 19              |
+| AA     | meridiem (uppercase with ellipsis)   | A.M., P.M.                  |
+| a      | meridiem (lowercase)                 | am, pm                      |
+| aa     | meridiem (lowercase with ellipsis)   | 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                  |
+
+#### Note 1. Invalid Date
 
 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:
 
@@ -274,7 +289,7 @@ if (isNaN(today)) {
 }
 ```
 
-#### NOTE 2. Input as UTC
+#### Note 2. Input as UTC
 
 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.
 
@@ -283,7 +298,7 @@ date.parse('11:14:05 PM', 'hh:mm:ss A');          // => Jan 1 1970 23:14:05 GMT-
 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)
 ```
 
-#### NOTE 3. Default Date Time
+#### Note 3. Default Date Time
 
 Default date is `January 1, 1970`, time is `00:00:00.000`. Values not passed will be complemented with them:
 
@@ -292,7 +307,7 @@ 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
 ```
 
-#### NOTE 4. Max Date / Min Date
+#### Note 4. Max Date / Min Date
 
 Parsable maximum date is `December 31, 9999`, minimum date is `January 1, 0001`.
 
@@ -304,7 +319,7 @@ 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 5. 12-hour notation and Meridiem
+#### Note 5. 12-hour notation and Meridiem
 
 If use `hh` or `h` (12-hour) token, use together `A` (meridiem) token to get the right value.
 
@@ -313,7 +328,7 @@ 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
 ```
 
-#### NOTE 6. Token disablement
+#### Note 6. Token disablement
 
 Use square brackets `[]` if a date-time string includes some token characters. Tokens inside square brackets in the `formatString` will be interpreted as normal characters:
 
@@ -322,9 +337,9 @@ date.parse('12 hours 34 minutes', 'HH hours mm minutes');       // => Invalid Da
 date.parse('12 hours 34 minutes', 'HH [hours] mm [minutes]');   // => Jan 1 1970 12:34:00 GMT-0800
 ```
 
-#### NOTE 7. Wildcard
+#### Note 7. Wildcard
 
-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:
+A white space works as a wildcard token. This token is not interpreted 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:
 
 ```javascript
 // This will be an error.
@@ -333,9 +348,9 @@ date.parse('2015/01/02 11:14:05', 'YYYY/MM/DD');            // => Invalid Date
 date.parse('2015/01/02 11:14:05', 'YYYY/MM/DD         ');   // => Jan 2 2015 00:00:00 GMT-0800
 ```
 
-#### NOTE 8. Ellipsis
+#### Note 8. Ellipsis
 
-The parser supports `...` (ellipse) token. The above example can be also written like this:
+The parser supports `...` (ellipsis) token. The above example can be also written like this:
 
 ```javascript
 date.parse('2015/01/02 11:14:05', 'YYYY/MM/DD...');   // => Jan 2 2015 00:00:00 GMT-0800
@@ -569,7 +584,7 @@ See [LOCALE.md](./LOCALE.md) for details.
 - @param {**Object**} extension - extension object
 - @returns {**void**}
 
-It extends the formatter and the parser of the current locale. See [EXTEND.md](./EXTEND.md) for details.
+It extends this library. See [EXTEND.md](./EXTEND.md) for details.
 
 ### plugin(name[, plugin])
 
@@ -577,7 +592,7 @@ It extends the formatter and the parser of the current locale. See [EXTEND.md](.
 - @param {**Object**} [plugin] - plugin object
 - @returns {**void**}
 
-Plugin is a named extension object. By installing predefined plugins, you can easily extend the formatter and the parser of the current locale. See [PLUGINS.md](./PLUGINS.md) for details.
+Plugin is a named extension object. By installing predefined plugins, you can easily extend this library. See [PLUGINS.md](./PLUGINS.md) for details.
 
 ## Browser Support