date-and-time 0.14.2 → 2.0.1

package/EXTEND.md

@@ -1,6 +1,6 @@
 # Extension
 
-By using `extend()`, you could add your own tokens or modify behavior of existing tokens. This is equivalent to define a new plugin without name.
+The easiest way to extend the default formatter and parser is to use plugins, but if the existing plugins do not meet your requirements, you can extend them yourself.
 
 ## Token
 
@@ -23,12 +23,26 @@ Tokens in this library have the following rules:
 'Eee'         // Not good
 ```
 
-- To the parser, it is not able to add token of new alphabet.
+- Only tokens consisting of the following alphabets can be added to the parser.
 
 ```javascript
-'EEE'         // This is not able to add because `E` is not an existing token in the parser.
-'YYY'         // This is OK because `Y` token is existing in the parser.
-'SSS'         // This is modifying, not adding. Because exactly the same token is existing.
+'Y'           // Year
+'M'           // Month
+'D'           // Day
+'H'           // 24-hour
+'A'           // AM PM
+'h'           // 12-hour
+'s'           // Second
+'S'           // Millisecond
+'Z'           // Timezone offset
+```
+
+- Existing tokens cannot be overwritten.
+
+```javascript
+'YYY'         // This is OK because the same token does not exists.
+'SSS'         // This cannot be added because the exact same token exists.
+'EEE'         // This is OK for the formatter, but cannot be added to the parser.
 ```
 
 ## Examples
@@ -61,12 +75,12 @@ date.extend({
 
 ### Example 2
 
-In the parser, modify `MMM` token to ignore case:
+Add `MMMMM` token to the parser. This token ignores case:
 
 ```javascript
-date.parse('Dec 25 2019', 'MMM DD YYYY'); // => December 25, 2019
-date.parse('dec 25 2019', 'MMM DD YYYY'); // => December 25, 2019
-date.parse('DEC 25 2019', 'MMM DD YYYY'); // => December 25, 2019
+date.parse('Dec 25 2019', 'MMMMM DD YYYY'); // => December 25, 2019
+date.parse('dec 25 2019', 'MMMMM DD YYYY'); // => December 25, 2019
+date.parse('DEC 25 2019', 'MMMMM DD YYYY'); // => December 25, 2019
 ```
 
 Source code example is here:
@@ -76,7 +90,7 @@ const date = require('date-and-time');
 
 date.extend({
   parser: {
-    MMM: function (str) {
+    MMMMM: function (str) {
       const mmm = this.res.MMM.map(m => m.toLowerCase());
       const result = this.find(mmm, str.toLowerCase());
       result.value++;
@@ -86,4 +100,8 @@ date.extend({
 });
 ```
 
-Modifying the parser may be a bit difficult. Refer to the library source code to grasp the default behavior.
+Extending the parser may be a bit difficult. Refer to the library source code to grasp the default behavior.
+
+## Caveats
+
+Note that switching locales or applying plugins after extending the library will be cleared all extensions. In such cases, you need to extend the library again.

package/LOCALE.md

@@ -1,10 +1,18 @@
 # Locale
 
-The `format()` outputs month, day of week, and meridiem (am / pm) in English, and the `parse()` assumes the passed date string is in English. Here it describes how to use other languages in these functions.
+By default, `format()` outputs month, day of week, and meridiem (AM / PM) in English, and functions such as `parse()` assume that a passed date time string is in English. Here it describes how to use other languages in these functions.
 
 ## Usage
 
-To support `ES Modules` in the next version, the locale switching method has changed and then the old method has been deprecated.
+- ES Modules:
+
+```javascript
+import date from 'date-and-time';
+import es from 'date-and-time/locale/es';
+
+date.locale(es);    // Spanish
+date.format(new Date(), 'dddd D MMMM'); // => 'lunes 11 enero
+```
 
 - CommonJS:
 
@@ -16,20 +24,20 @@ date.locale(fr);    // French
 date.format(new Date(), 'dddd D MMMM'); // => 'lundi 11 janvier'
 ```
 
-- ES Modules (with transpile):
+- ES Modules for the browser:
 
-```javascript
-import date from 'date-and-time';
-import it from 'date-and-time/locale/it';
+```html
+<script type="module">
+import date from '/path/to/date-and-time.es.min.js';
+import it from '/path/to/date-and-time/locale/it.es.js';
 
 date.locale(it);    // Italian
 date.format(new Date(), 'dddd D MMMM'); // => 'Lunedì 11 gennaio'
+</script>
 ```
 
 - Older browser:
 
-When in older browser, pass the locale string as before. (no changes)
-
 ```html
 <script src="/path/to/date-and-time.min.js"></script>
 <script src="/path/to/locale/zh-cn.js"></script>
@@ -42,9 +50,9 @@ date.format(new Date(), 'MMMD日dddd');  // => '1月11日星期一'
 
 ### NOTE
 
-- You have to import (or require) in advance the all locale modules that you are going to switch to.
+- 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`.
 - The locale will be actually switched after executing the `locale()`.
-- You can also change the locale back to English by loading the `en` module:
+- You can also change the locale back to English by importing `en` locale:
 
 ```javascript
 import en from 'date-and-time/locale/en';
@@ -52,30 +60,6 @@ import en from 'date-and-time/locale/en';
 date.locale(en);
 ```
 
-### FYI
-
-The following (old) methods are deprecated. In the next version it won't be able to use them.
-
-- CommonJS:
-
-```javascript
-const date = require('date-and-time');
-require('date-and-time/locale/fr');
-
-date.locale('fr');  // French
-date.format(new Date(), 'dddd D MMMM'); // => 'lundi 11 janvier'
-```
-
-- ES Modules (with transpile):
-
-```javascript
-import date from 'date-and-time';
-import 'date-and-time/locale/it';
-
-date.locale('it');  // Italian
-date.format(new Date(), 'dddd D MMMM'); // => 'Lunedì 11 gennaio'
-```
-
 ## Supported locale List
 
 At this time, it supports the following locales:
@@ -100,6 +84,7 @@ Indonesian (id)
 Italian (it)
 Japanese (ja)
 Javanese (jv)
+Kinyarwanda (rw)
 Korean (ko)
 Persian (fa)
 Polish (pl)