date-and-time 0.12.0 → 0.14.2

package/LOCALE.md

@@ -1,39 +1,41 @@
 # 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>
 ```
@@ -41,12 +43,42 @@ 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.
-- 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)

package/PLUGINS.md

@@ -1,37 +1,40 @@
 # Plugins
 
-As this library is oriented toward minimalism, it may seem like a lack of functionality. We think plugin is the most realistic solution for solving such dissatisfaction. By importing the plugins, you could extend the functionality of this library, mainly the formatter and the parser.
-
+As this library is oriented toward minimalism, it may seem like a lack of functionality. We think plugin is the most realistic solution for solving such dissatisfaction. By importing the plugins, you can extend the functionality of this library, mainly the formatter and the parser.
 
 ## 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>
@@ -40,22 +43,82 @@ 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
+  - It adds day of week notation to the parser.
+
 - meridiem
   - It extends `A` token.
 
+- microsecond
+  - It adds microsecond notation to the parser.
+
 - ordinal
   - It adds ordinal notation of date to the formatter.
 
+- timespan
+  - It adds `timeSpan()` function to the library.
+
 - two-digit-year
   - It adds two-digit year notation to the parser.
 
 ## Plugin Details
 
+### day-of-week
+
+It adds `dddd`, `ddd` and `dd` tokens to the parser. While these meanings are as follows, in fact they don't make sense because day of week doesn't include information to determine a date:
+
+| token | meaning                  | examples of acceptable form | added or modified |
+|:------|:-------------------------|:----------------------------|:------------------|
+| dddd  | day of week (long)       | Friday, Sunday              | ✔                 |
+| ddd   | day of week (short)      | Fri, Sun                    | ✔                 |
+| dd    | day of week (very short) | Fr, Su                      | ✔                 |
+
+```javascript
+const date = require('date-and-time');
+// Import "day-of-week" plugin.
+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);
+
+// You can write like this.
+date.parse('Thursday, March 05, 2020', 'dddd, MMMM, D YYYY');
+// You can also write like this, but it is not versatile because length of day of week are variant.
+date.parse('Thursday, March 05, 2020', '        , MMMM, D YYYY');
+date.parse('Friday, March 06, 2020', '      , MMMM, D YYYY');
+```
+
 ### meridiem
 
-It adds `AA`, `a` and `aa` token to the formatter. These meanings are as follows:
+It adds `AA`, `a` and `aa` tokens to the formatter. These meanings are as follows:
 
 | token | meaning                            | examples of output | added or modified |
 |:------|:-----------------------------------|:-------------------|:------------------|
@@ -73,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'
@@ -93,23 +156,53 @@ date.parse('12:34 pm', 'hh:mm A');      // => Jan 1 1970 12:34:00
 date.parse('12:34 p.m.', 'hh:mm A');    // => Jan 1 1970 12:34:00
 ```
 
+### microsecond
+
+It adds `SSSSSS`, `SSSSS` and `SSSS` tokens to the parser. Thease meanings are as follows:
+
+| token  | meaning                       | examples of output | added or modified |
+|:-------|:------------------------------|:-------------------|:------------------|
+| SSSSSS | microsecond (high accuracy)   | 753123, 022113     | ✔                 |
+| SSSSS  | microsecond (middle accuracy) | 75312, 02211       | ✔                 |
+| SSSS   | microsecond (low accuracy)    | 7531, 0221         | ✔                 |
+| SSS    | millisecond (high accuracy)   | 753, 022           |                   |
+| SS     | millisecond (middle accuracy) | 75, 02             |                   |
+| S      | millisecond (low accuracy)    | 7, 0               |                   |
+
+```javascript
+const date = require('date-and-time');
+// Import "microsecond" plugin.
+const microsecond = require('date-and-time/plugin/microsecond');
+
+// Apply "microsecond" plugin to `date-and-time`.
+date.plugin(microsecond);
+
+// A date object in JavaScript supports `millisecond` (ms):
+date.parse('12:34:56.123', 'HH:mm:ss.SSS');
+
+// 4 or more digits number sometimes seen is not `millisecond`, probably `microsecond` (μs):
+date.parse('12:34:56.123456', 'HH:mm:ss.SSSSSS');
+
+// 123456µs will be rounded to 123ms.
+```
+
 ### ordinal
 
 It adds `DDD` token to the formatter. This meaning is as follows:
 
 | token | meaning                  | examples of output  | added or modified |
 |:------|:-------------------------|:--------------------|:------------------|
-| D     | date                     | 1, 2, 3, 31         |                   |
-| DD    | date with zero-padding   | 01, 02, 03, 31      |                   |
 | DDD   | ordinal notation of date | 1st, 2nd, 3rd, 31th | ✔                 |
+| DD    | date with zero-padding   | 01, 02, 03, 31      |                   |
+| D     | date                     | 1, 2, 3, 31         |                   |
 
 ```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
@@ -119,6 +212,54 @@ date.format(new Date(), 'MMM DD YYYY');   // => Jan 01 2019
 date.format(new Date(), 'MMM DDD YYYY');  // => Jan 1st 2019
 ```
 
+### timespan
+
+It adds `timeSpan()` function to the library. This function is similar to the `subtract()`, but this can display a formatted elapsed time between two date objects:
+
+```javascript
+const date = require('date-and-time');
+// Import "timespan" plugin.
+const timespan = require('date-and-time/plugin/timespan');
+
+// Apply "timespan" plugin to `date-and-time`.
+date.plugin(timespan);
+
+const now = new Date(2020, 2, 5, 1, 2, 3, 4);
+const new_years_day = new Date(2020, 0, 1);
+
+date.timeSpan(now, new_years_day).toDays('D HH:mm:ss.SSS'); // => '64 01:02:03.004'
+date.timeSpan(now, new_years_day).toHours('H [hours] m [minutes] s [seconds]');  // => '1537 hours 2 minutes 3 seconds'
+date.timeSpan(now, new_years_day).toMinutes('mmmmmmmmmm [minutes]');  // => '0000092222 minutes'
+```
+
+The `timeSpan()` returns an object that has some functions as with the `subtract()`:
+
+| function       | description             |
+|:---------------|:------------------------|
+| toDays         | Outputs as dates        |
+| toHours        | Outputs as hours        |
+| toMinutes      | Outputs as minutes      |
+| toSeconds      | Outputs as seconds      |
+| toMilliseconds | Outputs as milliseconds |
+
+Available tokens in those functions and their meanings are as follows:
+
+| function       | available tokens |
+|:---------------|:-----------------|
+| toDays         | D, H, m, s, S    |
+| toHours        | H, m, s, S       |
+| toMinutes      | m, s, S          |
+| toSeconds      | s, S             |
+| toMilliseconds | S                |
+
+| token | meaning     |
+|:------|:------------|
+| D     | date        |
+| H     | 24-hour     |
+| m     | minute      |
+| s     | second      |
+| S     | millisecond |
+
 ### two-digit-year
 
 It adds `YY` token to the parser and also changes behavior of `Y` token. These meanings are as follows:
@@ -134,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