date-and-time 0.14.2 → 2.0.1

package/README.md

@@ -2,11 +2,11 @@
 
 [![Circle CI](https://circleci.com/gh/knowledgecode/date-and-time.svg?style=shield)](https://circleci.com/gh/knowledgecode/date-and-time)  
 
-This library is a minimalist collection of functions for manipulating JS date and time. It's tiny, simple, easy to learn.
+This JS library is just a collection of functions for manipulating date and time. It's small, simple, and easy to learn.
 
 ## Why
 
-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.
+Nowadays, JS modules have become huge, complex, and have many dependencies. We think it makes sense to try to keep each module simple and small. Especially for modules that are at the bottom of the dependency chain, such as those dealing with date and time.
 
 ## Features
 
@@ -18,73 +18,120 @@ JS modules nowadays are getting more huge and complex, and there are also many d
 
 ## Install
 
-- via npm:
-
 ```shell
-npm install date-and-time --save
+npm i date-and-time
+```
+
+## Recent Changes
+
+- 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
+
+- ES Modules:
+
+```javascript
+import date from 'date-and-time';
+```
+
+- CommonJS:
+
+```javascript
+const date = require('date-and-time');
+```
+
+- ES Modules for the browser:
+
+```html
+<script type="module">
+import date from '/path/to/date-and-time.es.min.js';
+</script>
 ```
 
-- local:
+- Older browser:
 
 ```html
 <script src="/path/to/date-and-time.min.js"></script>
 ```
 
-## Recent Changes
+### Note
 
-- 0.14.2
-  - Fixed regular expression denial of service (ReDoS) vulnerability.
+- 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`.
 
-- 0.14.1
-  - Fixed a bug characters inside square brackets `[]` are not validated.
+## API
 
-- 0.14.0
-  - **Feature Freeze**
+- [format](#formatdateobj-arg-utc)
+  - Formatting a Date and Time (Date -> String)
 
-    We decided to freeze the feature with this version (except the following). The next will be 1.0.0.
+- [parse](#parsedatestring-arg-utc)
+  - Parsing a Date and Time string (String -> Date)
 
-  - To support `ES Modules` (without transpile) in the next version, the importing method has changed in the `locale()` and the `plugin()`. As this version you will see the warning message if using the old method. See [LOCALE.md](./LOCALE.md) and [PLUGINS.md](./PLUGINS.md) for details.
+- [compile](#compileformatstring)
+  - Compiling a format string
 
-  - Added `transform()` function to transform the format of a date string. When changing the format, previously you would convert the date string to a date object with the `parse()`, and then format it with the `format()` again, but you can now do this with a single function.
+- [preparse](#preparsedatestring-arg)
+  - Pre-parsing a Date and Time string
 
-  ```javascript
-  // 3/8/2020 => 8/3/2020
-  date.transform('3/8/2020', 'D/M/YYYY', 'M/D/YYYY');
+- [isValid](#isvalidarg1-arg2)
+  - Validation
 
-  // previously
-  const today = date.parse('3/8/2020', 'D/M/YYYY');
-  date.format(today, 'M/D/YYYY');   // => '8/3/2020'
-  ```
+- [transform](#transformdatestring-arg1-arg2-utc)
+  - Transforming a Date and Time string (String -> String)
 
-## Usage
+- [addYears](#addyearsdateobj-years)
+  - Adding years
 
-- Node.js:
+- [addMonths](#addmonthsdateobj-months)
+  - Adding months
 
-```javascript
-const date = require('date-and-time');
-```
+- [addDays](#adddaysdateobj-days)
+  - Adding days
 
-- With a transpiler:
+- [addHours](#addhoursdateobj-hours)
+  - Adding hours
 
-```javascript
-import date from 'date-and-time';
-```
+- [addMinutes](#addminutesdateobj-minutes)
+  - Adding minutes
 
-- The browser:
+- [addSeconds](#addsecondsdateobj-seconds)
+  - Adding seconds
 
-```javascript
-window.date;    // global object
-```
+- [addMilliseconds](#addmillisecondsdateobj-milliseconds)
+  - Adding milliseconds
 
-## API
+- [subtract](#subtractdate1-date2)
+  - Subtracting two dates
+
+- [isLeapYear](#isleapyeary)
+  - Whether year is leap year
+
+- [isSameDay](#issamedaydate1-date2)
+  - Comparison of two dates
+
+- [locale](#localecode-locale)
+  - Changing the locale or defining new locales
+
+- [extend](#extendextension)
+  - Feature extension
 
-### format(dateObj, formatString[, utc])
+- [plugin](#pluginname-plugin)
+  - Importing or defining plugins
 
-- Formatting a date.
-  - @param {**Date**} dateObj - a Date object
-  - @param {**string|Array.\<string\>**} arg - a format string or a compiled object
-  - @param {**boolean**} [utc] - output as UTC
-  - @returns {**string**} a formatted string
+### format(dateObj, arg[, utc])
+
+- @param {**Date**} dateObj - a Date object
+- @param {**string|Array.\<string\>**} arg - a format string or its compiled object
+- @param {**boolean**} [utc] - output as UTC
+- @returns {**string**} a formatted string
 
 ```javascript
 const now = new Date();
@@ -136,7 +183,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:
 
@@ -145,7 +192,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.
 
@@ -154,17 +201,16 @@ 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])
 
-- Parsing a date string.
-  - @param {**string**} dateString - a date string
-  - @param {**string|Array.\<string\>**} arg - a format string or a compiled object
-  - @param {**boolean**} [utc] - input as UTC
-  - @returns {**Date**} a constructed date
+- @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
 
 ```javascript
 date.parse('2015/01/02 23:14:05', 'YYYY/MM/DD HH:mm:ss');   // => Jan 2 2015 23:14:05 GMT-0800
@@ -178,45 +224,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:
 
@@ -228,7 +275,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.
 
@@ -237,7 +284,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:
 
@@ -246,7 +293,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`.
 
@@ -258,7 +305,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.
 
@@ -267,7 +314,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:
 
@@ -276,9 +323,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.
@@ -287,9 +334,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 also be 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
@@ -297,9 +344,10 @@ date.parse('2015/01/02 11:14:05', 'YYYY/MM/DD...');   // => Jan 2 2015 00:00:00
 
 ### compile(formatString)
 
-- Compiling a format string for the parser.
-  - @param {**string**} formatString - a format string
-  - @returns {**Array.\<string\>**} a compiled object
+- @param {**string**} formatString - a format string
+- @returns {**Array.\<string\>**} a compiled object
+
+If you are going to execute the `format()`, the `parse()` or the `isValid()` so many times with one string format, recommended to precompile and reuse it for performance.
 
 ```javascript
   const pattern = date.compile('MMM D YYYY h:m:s A');
@@ -311,14 +359,11 @@ date.parse('2015/01/02 11:14:05', 'YYYY/MM/DD...');   // => Jan 2 2015 00:00:00
   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.
-
 ### preparse(dateString, arg)
 
-- Pre-parsing a date string.
-  - @param {**string**} dateString - a date string
-  - @param {**string|Array.\<string\>**} arg - a format string or a compiled object
-  - @returns {**Object**} a date structure
+- @param {**string**} dateString - a date string
+- @param {**string|Array.\<string\>**} arg - a format string or its compiled object
+- @returns {**Object**} a date structure
 
 This function takes exactly the same parameters with the `parse()`, but returns a date structure as follows unlike that:
 
@@ -346,10 +391,9 @@ This date structure provides a parsing result. You will be able to tell from it
 
 ### isValid(arg1[, arg2])
 
-- Validation.
-  - @param {**Object|string**} arg1 - a date structure or a date string
-  - @param {**string|Array.\<string\>**} [arg2] - a format string or a compiled object
-  - @returns {**boolean**} whether the date string is a valid date
+- @param {**Object|string**} arg1 - a date structure or a date string
+- @param {**string|Array.\<string\>**} [arg2] - a format string or its compiled object
+- @returns {**boolean**} whether the date string is a valid date
 
 This function takes either exactly the same parameters with the `parse()` or a date structure which the `preparse()` returns, evaluates the validity of them.
 
@@ -365,12 +409,11 @@ date.isValid(result);   // => true
 
 ### transform(dateString, arg1, arg2[, utc])
 
-- Transformation of date string.
-  - @param {**string**} dateString - a date string
-  - @param {**string|Array.\<string\>**} arg1 - the format string of the date string or the compiled object
-  - @param {**string|Array.\<string\>**} arg2 - the transformed format string or the compiled object
-  - @param {**boolean**} [utc] - output as UTC
-  - @returns {**string**} a formatted string
+- @param {**string**} dateString - a date string
+- @param {**string|Array.\<string\>**} arg1 - a format string or its compiled object
+- @param {**string|Array.\<string\>**} arg2 - a transformed format string or its compiled object
+- @param {**boolean**} [utc] - output as UTC
+- @returns {**string**} a formatted string
 
 This function transforms the format of a date string. The 2nd parameter, `arg1`, is the format string of it. Available token list is equal to the `parse()`'s. The 3rd parameter, `arg2`, is the transformed format string. Available token list is equal to the `format()`'s.
 
@@ -384,10 +427,9 @@ date.transform('13:05', 'HH:mm', 'hh:mm A');
 
 ### addYears(dateObj, years)
 
-- Adding years.
-  - @param {**Date**} dateObj - a Date object
-  - @param {**number**} years - number of years to add
-  - @returns {**Date**} a date after adding the value
+- @param {**Date**} dateObj - a Date object
+- @param {**number**} years - number of years to add
+- @returns {**Date**} a date after adding the value
 
 ```javascript
 const now = new Date();
@@ -396,10 +438,9 @@ const next_year = date.addYears(now, 1);
 
 ### addMonths(dateObj, months)
 
-- Adding months.
-  - @param {**Date**} dateObj - a Date object
-  - @param {**number**} months - number of months to add
-  - @returns {**Date**} a date after adding the value
+- @param {**Date**} dateObj - a Date object
+- @param {**number**} months - number of months to add
+- @returns {**Date**} a date after adding the value
 
 ```javascript
 const now = new Date();
@@ -408,10 +449,9 @@ const next_month = date.addMonths(now, 1);
 
 ### addDays(dateObj, days)
 
-- Adding days.
-  - @param {**Date**} dateObj - a Date object
-  - @param {**number**} days - number of days to add
-  - @returns {**Date**} a date after adding the value
+- @param {**Date**} dateObj - a Date object
+- @param {**number**} days - number of days to add
+- @returns {**Date**} a date after adding the value
 
 ```javascript
 const now = new Date();
@@ -420,10 +460,9 @@ const yesterday = date.addDays(now, -1);
 
 ### addHours(dateObj, hours)
 
-- Adding hours.
-  - @param {**Date**} dateObj - a Date object
-  - @param {**number**} hours - number of hours to add
-  - @returns {**Date**} a date after adding the value
+- @param {**Date**} dateObj - a Date object
+- @param {**number**} hours - number of hours to add
+- @returns {**Date**} a date after adding the value
 
 ```javascript
 const now = new Date();
@@ -432,10 +471,9 @@ const an_hour_ago = date.addHours(now, -1);
 
 ### addMinutes(dateObj, minutes)
 
-- Adding minutes.
-  - @param {**Date**} dateObj - a Date object
-  - @param {**number**} minutes - number of minutes to add
-  - @returns {**Date**} a date after adding the value
+- @param {**Date**} dateObj - a Date object
+- @param {**number**} minutes - number of minutes to add
+- @returns {**Date**} a date after adding the value
 
 ```javascript
 const now = new Date();
@@ -444,10 +482,9 @@ const two_minutes_later = date.addMinutes(now, 2);
 
 ### addSeconds(dateObj, seconds)
 
-- Adding seconds.
-  - @param {**Date**} dateObj - a Date object
-  - @param {**number**} seconds - number of seconds to add
-  - @returns {**Date**} a date after adding the value
+- @param {**Date**} dateObj - a Date object
+- @param {**number**} seconds - number of seconds to add
+- @returns {**Date**} a date after adding the value
 
 ```javascript
 const now = new Date();
@@ -456,10 +493,9 @@ const three_seconds_ago = date.addSeconds(now, -3);
 
 ### addMilliseconds(dateObj, milliseconds)
 
-- Adding milliseconds.
-  - @param {**Date**} dateObj - a Date object
-  - @param {**number**} milliseconds - number of milliseconds to add
-  - @returns {**Date**} a date after adding the value
+- @param {**Date**} dateObj - a Date object
+- @param {**number**} milliseconds - number of milliseconds to add
+- @returns {**Date**} a date after adding the value
 
 ```javascript
 const now = new Date();
@@ -468,10 +504,9 @@ const a_millisecond_later = date.addMilliseconds(now, 1);
 
 ### subtract(date1, date2)
 
-- Subtracting.
-  - @param {**Date**} date1 - a Date object
-  - @param {**Date**} date2 - a Date object
-  - @returns {**Object**} a result object subtracting date2 from date1
+- @param {**Date**} date1 - a Date object
+- @param {**Date**} date2 - a Date object
+- @returns {**Object**} a result object subtracting date2 from date1
 
 ```javascript
 const today = new Date(2015, 0, 2);
@@ -486,9 +521,8 @@ date.subtract(today, yesterday).toMilliseconds();   // => 86400000
 
 ### isLeapYear(y)
 
-- Leap year.
-  - @param {**number**} y - year
-  - @returns {**boolean**} whether the year is a leap year
+- @param {**number**} y - year
+- @returns {**boolean**} whether year is leap year
 
 ```javascript
 date.isLeapYear(2015);  // => false
@@ -497,10 +531,9 @@ date.isLeapYear(2012);  // => true
 
 ### isSameDay(date1, date2)
 
-- Comparison of two dates.
-  - @param {**Date**} date1 - a Date object
-  - @param {**Date**} date2 - a Date object
-  - @returns {**boolean**} whether the dates are the same day (times are ignored)
+- @param {**Date**} date1 - a Date object
+- @param {**Date**} date2 - a Date object
+- @returns {**boolean**} whether the two dates are the same day (time is ignored)
 
 ```javascript
 const date1 = new Date(2017, 0, 2, 0);          // Jan 2 2017 00:00:00
@@ -512,41 +545,40 @@ date.isSameDay(date1, date3);   // => false
 
 ### locale([code[, locale]])
 
-- Change locale or setting a new locale definition.
-  - @param {**string**} [code] - language code
-  - @param {**Object**} [locale] - locale definition
-  - @returns {**string**} current language code
+- @param {**Function|string**} [code] - locale installer | language code
+- @param {**Object**} [locale] - locale definition
+- @returns {**string**} current language code
 
-It returns a current language code if called without any parameters.
+It returns the current language code if called without any parameters.
 
 ```javascript
 date.locale();  // => "en"
 ```
 
-To switch to any other language, call it with a language code.
+To switch to any other language, call it with a locale installer or a language code.
 
 ```javascript
-date.locale('es');  // Switch to Spanish
+import es from 'date-and-time/locale/es';
+
+date.locale(es);  // Switch to Spanish
 ```
 
 See [LOCALE.md](./LOCALE.md) for details.
 
 ### extend(extension)
 
-- Locale extension.
-  - @param {**Object**} extension - locale definition
-  - @returns {**void**}
+- @param {**Object**} extension - extension object
+- @returns {**void**}
 
-Extend a current locale. See [EXTEND.md](./EXTEND.md) for details.
+It extends this library. See [EXTEND.md](./EXTEND.md) for details.
 
-### plugin(name[, extension])
+### plugin(name[, plugin])
 
-- Plugin import or definition.
-  - @param {**string**} name - plugin name
-  - @param {**Object**} [extension] - locale definition
-  - @returns {**void**}
+- @param {**Function|string**} name - plugin installer | plugin name
+- @param {**Object**} [plugin] - plugin object
+- @returns {**void**}
 
-Plugin is a named locale definition defined with the `extend()`. 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