Merge branch 'develop'

LOCALE.md

@@ -1,52 +1,84 @@
 # Locale
 
-Month, day of week, and meridiem (am / pm) the `format()` outputs are usually in English, and the `parse()` also assumes that a passed date string is English.
+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.
 
 ## Usage
 
-If you would like to use any other language in these functions, switch as follows:
+To support `ES Modules` in the next version, the locale switching method has changed and then the old method has been deprecated.
 
-- Node.js:
+- CommonJS:
 
 ```javascript
 const date = require('date-and-time');
-require('date-and-time/locale/fr');
+const fr = require('date-and-time/locale/fr');
 
-date.locale('fr');  // French
+date.locale(fr);    // French
 date.format(new Date(), 'dddd D MMMM'); // => 'lundi 11 janvier'
 ```
 
-- With a transpiler:
+- ES Modules (with transpile):
 
 ```javascript
 import date from 'date-and-time';
-import 'date-and-time/locale/it';
+import it from 'date-and-time/locale/it';
 
-date.locale('it');  // Italian
+date.locale(it);    // Italian
 date.format(new Date(), 'dddd D MMMM'); // => 'Lunedì 11 gennaio'
 ```
 
-- With an older browser:
+- 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>
 
 <script>
-date.locale('zh-cn');  // Chinese
+date.locale('zh-cn');   // Chinese
 date.format(new Date(), 'MMMD日dddd');  // => '1月11日星期一'
 </script>
 ```
 
 ### NOTE
 
 - You have to import (or require) in advance the all locale modules that you are going to switch to.
-- The locale will be actually switched after executing `locale('xx')`.
-- You could return the locale to English by executing `locale ('en')`.
+- The locale will be actually switched after executing the `locale()`.
+- You can also change the locale back to English by loading the `en` module:
+
+```javascript
+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 List
+## Supported locale List
 
-For now, it supports the following languages:  
+At this time, it supports the following locales:
 
 ```text
 Arabic (ar)

PLUGINS.md

@@ -4,33 +4,37 @@ As this library is oriented toward minimalism, it may seem like a lack of functi
 
 ## Usage
 
-- Node.js:
+To support `ES Modules` in the next version, the importing method has changed and then the old method has been deprecated.
+
+- CommonJS:
 
 ```javascript
 const date = require('date-and-time');
-// Import a plugin "foobar".
-require('date-and-time/plugin/foobar');
+// Import the plugin "foobar".
+const foobar = require('date-and-time/plugin/foobar');
 
 // Apply the plugin to "date-and-time".
-date.plugin('foobar');
+date.plugin(foobar);
 ```
 
-- With a transpiler:
+- ES Modules (with transpile):
 
 ```javascript
 import date from 'date-and-time';
-// Import a plugin "foobar".
-import 'date-and-time/plugin/foobar';
+// Import the plugin "foobar".
+import foobar from 'date-and-time/plugin/foobar';
 
 // Apply the plugin to "date-and-time".
-date.plugin('foobar');
+date.plugin(foobar);
 ```
 
-- The browser:
+- Older browser:
+
+When in older browser, pass the plugin name as before. (no changes)
 
 ```html
 <script src="/path/to/date-and-time.min.js"></script>
-<!-- Import a plugin "foobar". -->
+<!-- Import the plugin "foobar". -->
 <script src="/path/to/plugin/foobar.js"></script>
 
 <script>
@@ -39,6 +43,32 @@ date.plugin('foobar');
 </script>
 ```
 
+### 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');
+// Import the plugin "foobar".
+require('date-and-time/plugin/foobar');
+
+// Apply the plugin to "date-and-time".
+date.plugin('foobar');
+```
+
+- ES Modules (with transpile):
+
+```javascript
+import date from 'date-and-time';
+// Import the plugin "foobar".
+import 'date-and-time/plugin/foobar';
+
+// Apply the plugin to "date-and-time".
+date.plugin('foobar');
+```
+
 ## Plugin List
 
 - day-of-week
@@ -74,10 +104,10 @@ It adds `dddd`, `ddd` and `dd` tokens to the parser. While these meanings are as
 ```javascript
 const date = require('date-and-time');
 // Import "day-of-week" plugin.
-require('date-and-time/plugin/day-of-week');
+const day_of_week = require('date-and-time/plugin/day-of-week');
 
 // Apply "day-of-week" plugin to `date-and-time`.
-date.plugin('day-of-week');
+date.plugin(day_of_week);
 
 // You can write like this.
 date.parse('Thursday, March 05, 2020', 'dddd, MMMM, D YYYY');
@@ -106,10 +136,10 @@ It also extends `A` token of the parser as follows:
 ```javascript
 const date = require('date-and-time');
 // Import "meridiem" plugin.
-require('date-and-time/plugin/meridiem');
+const meridiem = require('date-and-time/plugin/meridiem');
 
 // Apply "medidiem" plugin to `date-and-time`.
-date.plugin('meridiem');
+date.plugin(meridiem);
 
 // This is default behavior of the formatter.
 date.format(new Date(), 'hh:mm A');     // => '12:34 PM'
@@ -142,10 +172,10 @@ It adds `SSSSSS`, `SSSSS` and `SSSS` tokens to the parser. Thease meanings are a
 ```javascript
 const date = require('date-and-time');
 // Import "microsecond" plugin.
-require('date-and-time/plugin/microsecond');
+const microsecond = require('date-and-time/plugin/microsecond');
 
 // Apply "microsecond" plugin to `date-and-time`.
-date.plugin('microsecond');
+date.plugin(microsecond);
 
 // A date object in JavaScript supports `millisecond` (ms):
 date.parse('12:34:56.123', 'HH:mm:ss.SSS');
@@ -169,10 +199,10 @@ It adds `DDD` token to the formatter. This meaning is as follows:
 ```javascript
 const date = require('date-and-time');
 // Import "ordinal" plugin.
-require('date-and-time/plugin/ordinal');
+const ordinal = require('date-and-time/plugin/ordinal');
 
 // Apply "ordinal" plugin to `date-and-time`.
-date.plugin('ordinal');
+date.plugin(ordinal);
 
 // These are default behavior of the formatter.
 date.format(new Date(), 'MMM D YYYY');    // => Jan 1 2019
@@ -189,10 +219,10 @@ It adds `timeSpan()` function to the library. This function is similar to the `s
 ```javascript
 const date = require('date-and-time');
 // Import "timespan" plugin.
-require('date-and-time/plugin/timespan');
+const timespan = require('date-and-time/plugin/timespan');
 
 // Apply "timespan" plugin to `date-and-time`.
-date.plugin('timespan');
+date.plugin(timespan);
 
 const now = new Date(2020, 2, 5, 1, 2, 3, 4);
 const new_years_day = new Date(2020, 0, 1);
@@ -245,14 +275,14 @@ It adds `YY` token to the parser and also changes behavior of `Y` token. These m
 ```javascript
 const date = require('date-and-time');
 // Import "two-digit-year" plugin.
-require('date-and-time/plugin/two-digit-year');
+const two_digit_year = require('date-and-time/plugin/two-digit-year');
 
 // These are default behavior of the parser.
 date.parse('Dec 25 69', 'MMM D YY');      // => Invalid Date
 date.parse('Dec 25 70', 'MMM D Y');       // => 70 AD (ancient times)
 
 // Apply "two-digit-year" plugin to `date-and-time`.
-date.plugin('two-digit-year');
+date.plugin(two_digit_year);
 
 // These convert the year 69 or earlier to 2000s, the year 70 or later to 1900s.
 date.parse('Dec 25 69', 'MMM D YY');      // => Dec 25 2069

README.md

@@ -32,6 +32,24 @@ npm install date-and-time --save
 
 ## Recent Changes
 
+- 0.14.0
+  - **Feature Freeze**
+
+    We decided to freeze the feature with this version (except the following). The next will be 1.0.0.
+
+  - 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.
+
+  - Added `transform()` function to transform the format of a date string. When changing the format, in the past 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.
+
+  ```javascript
+  // 3/8/2020 => 8/3/2020
+  date.transform('3/8/2020', 'D/M/YYYY', 'M/D/YYYY');
+
+  // in the past
+  const today = date.parse('3/8/2020', 'D/M/YYYY');
+  date.format(today, 'M/D/YYYY');   // => '8/3/2020'
+  ```
+
 - 0.13.0
   - The `format()` now supports a compiled formatString.
 
@@ -99,31 +117,6 @@ npm install date-and-time --save
     | a     | meridiem (lowercase)               | am, pm     |         |
     | aa    | meridiem (lowercase with ellipsis) | a.m., p.m. |         |
 
-- 0.11.0
-  - Added `compile()` function that precompiling a date-time string for the parser. If you need to process many date-time string with one format, you can get results faster than before by precompiling the format string with this function.
-
-  ```javascript
-  // We have passed a string format at the 2nd parameter each time when calling the parse() function.
-  date.parse('Mar 22 2019 2:54:21 PM', 'MMM D YYYY h:m:s A');
-  date.parse('Jul 27 2019 4:15:24 AM', 'MMM D YYYY h:m:s A');
-  date.parse('Dec 25 2019 3:51:11 AM', 'MMM D YYYY h:m:s A');
-
-  // You can precompile the string format.
-  const pattern = date.compile('MMM D YYYY h:m:s A');
-
-  // The parse() will be able to finish faster than passing the format string each time.
-  date.parse('Mar 22 2019 2:54:21 PM', pattern);
-  date.parse('Jul 27 2019 4:15:24 AM', pattern);
-  date.parse('Dec 25 2019 3:51:11 AM', pattern);
-  ```
-
-  ```javascript
-  const pattern = date.compile('MMM D YYYY h:m:s A');
-
-  // The isValid() will also too.
-  date.isValid('Mar 22 2019 2:54:21 PM', pattern);
-  ```
-
 ## Usage
 
 - Node.js:
@@ -431,6 +424,25 @@ const result = date.preparse('2015/01/02 23:14:05', 'YYYY/MM/DD HH:mm:ss');
 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
+
+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.
+
+```javascript
+// 3/8/2020 => 8/3/2020
+date.transform('3/8/2020', 'D/M/YYYY', 'M/D/YYYY');
+
+// 13:05 => 01:05 PM
+date.transform('13:05', 'HH:mm', 'hh:mm A');
+```
+
 ### addYears(dateObj, years)
 
 - Adding years.

bower.json

@@ -1,7 +1,7 @@
 {
   "name": "date-and-time",
   "description": "A Minimalist DateTime utility for Node.js and the browser",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "main": "date-and-time.js",
   "moduleType": [
     "amd",