@fr0st/datetime 5.0.2 → 5.1.1

package/README.md

@@ -44,7 +44,7 @@ import DateTime from '@fr0st/datetime';
 ## Date Creation
 
 - `dateString` is a string representing the date, and will default to the current timestamp.
-- `options` is an object containing properties to define the new date.
+- `options` is an object containing options for creating the new date.
     - `timeZone` is a string representing the time zone of the date, and will default to the system time zone.
     - `locale` is a string representing the locale of the date, and will default to the system locale.
 
@@ -55,7 +55,7 @@ const dateTime = new DateTime(dateString, options);
 **From Array**
 
 - `dateArray` is an array containing the year, month, date, hours, minutes, seconds and milliseconds.
-- `options` is an object containing properties to define the new date.
+- `options` is an object containing options for creating the new date.
     - `timeZone` is a string representing the time zone of the date, and will default to the system time zone.
     - `locale` is a string representing the locale of the date, and will default to the system locale.
 
@@ -68,7 +68,7 @@ The month and date in the `dateArray` will default to 1 if not set. The hours, m
 **From Date**
 
 - `dateObj` is a native JS *Date* object.
-- `options` is an object containing properties to define the new date.
+- `options` is an object containing options for creating the new date.
     - `timeZone` is a string representing the time zone of the date, and will default to the system time zone.
     - `locale` is a string representing the locale of the date, and will default to the system locale.
 
@@ -82,7 +82,7 @@ If you wish to parse a date string and you know the exact format, you can use th
 
 - `formatString` is a string containing the format you wish to use for parsing.
 - `dateString` is a string representing the date you are parsing.
-- `options` is an object containing properties to define the new date.
+- `options` is an object containing options for creating the new date.
     - `timeZone` is a string representing the time zone of the date, and will default to the system time zone.
     - `locale` is a string representing the locale of the date, and will default to the system locale.
 
@@ -97,7 +97,7 @@ const dateTime = DateTime.fromFormat(formatString, dateString, options);
 **From ISO String**
 
 - `dateString` is a string representing the date you are parsing.
-- `options` is an object containing properties to define the new date.
+- `options` is an object containing options for creating the new date.
     - `timeZone` is a string representing the time zone of the date, and will default to the system time zone.
     - `locale` is a string representing the locale of the date, and will default to English.
 
@@ -114,7 +114,7 @@ const dateTime = DateTime.fromISOString(dateString, options);
 **From Timestamp**
 
 - `timestamp` is the number of seconds since the UNIX epoch.
-- `options` is an object containing properties to define the new date.
+- `options` is an object containing options for creating the new date.
     - `timeZone` is a string representing the time zone of the date, and will default to the system time zone.
     - `locale` is a string representing the locale of the date, and will default to the system locale.
 
@@ -124,7 +124,7 @@ const dateTime = DateTime.fromTimestamp(timestamp, options);
 
 **Now**
 
-- `options` is an object containing properties to define the new date.
+- `options` is an object containing options for creating the new date.
     - `timeZone` is a string representing the time zone of the date, and will default to the system time zone.
     - `locale` is a string representing the locale of the date, and will default to the system locale.
 
@@ -694,22 +694,23 @@ const daysInYear = dateTime.daysInYear();
 Get the difference between two Dates.
 
 - `other` is the *DateTime* object to compare to.
-- `timeUnit` is a string representing the unit of time to return, and can be one of either "*year*", "*month*", "*week*", "*day*", "*hour*", "*minute*" or "*second*", or their pluralized versions.
-- `relative` is a boolean indicating whether to return the relative difference, and will default to *true*.
+- `options` is an object containing options for how to compare the dates.
+    - `timeUnit` is a string representing the unit of time to return, and can be one of either "*year*", "*month*", "*week*", "*day*", "*hour*", "*minute*" or "*second*", or their pluralized versions.
+    - `relative` is a boolean indicating whether to return the relative difference, and will default to *true*.
 
 If the `timeUnit` is omitted, this method will return the difference in milliseconds.
 
 ```javascript
-const diff = dateTime.diff(other, timeUnit, relative);
+const diff = dateTime.diff(other, options);
 ```
 
 If `relative` is *true* (default) the value returned will be the difference in the specified `timeUnit`, ignoring less significant values.
 
 ```javascript
-DateTime.fromFormat('yyyy-MM-dd', '2019-01-01').diff(DateTime.fromFormat('yyyy-MM-dd', '2018-12-31'), 'years', true); // 1
-DateTime.fromFormat('yyyy-MM-dd', '2019-01-01').diff(DateTime.fromFormat('yyyy-MM-dd', '2018-12-31'), 'years', false); // 0
-DateTime.fromFormat('yyyy-MM-dd', '2019-01-01').diff(DateTime.fromFormat('yyyy-MM-dd', '2017-12-31'), 'years', true); // 2
-DateTime.fromFormat('yyyy-MM-dd', '2019-01-01').diff(DateTime.fromFormat('yyyy-MM-dd', '2017-12-31'), 'years', false); // 1
+DateTime.fromFormat('yyyy-MM-dd', '2019-01-01').diff(DateTime.fromFormat('yyyy-MM-dd', '2018-12-31'), { timeUnit: 'years', relative: true }); // 1
+DateTime.fromFormat('yyyy-MM-dd', '2019-01-01').diff(DateTime.fromFormat('yyyy-MM-dd', '2018-12-31'), { timeUnit: 'years', relative: false }); // 0
+DateTime.fromFormat('yyyy-MM-dd', '2019-01-01').diff(DateTime.fromFormat('yyyy-MM-dd', '2017-12-31'), { timeUnit: 'years', relative: true }); // 2
+DateTime.fromFormat('yyyy-MM-dd', '2019-01-01').diff(DateTime.fromFormat('yyyy-MM-dd', '2017-12-31'), { timeUnit: 'years', relative: false }); // 1
 ```
 
 **Era**
@@ -727,12 +728,13 @@ const era = dateTime.era(type);
 Get the relative difference between two Dates in a human readable format using the current locale.
 
 - `other` is the *DateTime* object to compare to.
-- `timeUnit` is a string representing the unit of time to return, and can be one of either "*year*", "*month*", "*week*", "*day*", "*hour*", "*minute*" or "*second*", or their pluralized versions.
+- `options` is an object containing options for how to compare the dates.
+    - `timeUnit` is a string representing the unit of time to return, and can be one of either "*year*", "*month*", "*week*", "*day*", "*hour*", "*minute*" or "*second*", or their pluralized versions.
 
 If the `timeUnit` is omitted, this method will use the (relative) most significant non-zero value.
 
 ```javascript
-const diff = dateTime.humanDiff(other, timeUnit);
+const diff = dateTime.humanDiff(other, options);
 ```
 
 The most significant non-zero value is determined where the unit of time has a non-relative difference, or the next relative difference value is greater than or equal to the unit of time.
@@ -751,10 +753,11 @@ DateTime.fromFormat('yyyy-MM-dd', '2019-01-01').humanDiff(DateTime.fromFormat('y
 Return *true* if the *DateTime* is after another date.
 
 - `other` is the *DateTime* object to compare to.
-- `granularity` is a string specifying the level of granularity to use when comparing the dates, and can be one of either "*year*", "*month*", "*day*", "*hour*", "*minute*" or "*second*".
+- `options` is an object containing options for how to compare the dates.
+    - `granularity` is a string specifying the level of granularity to use when comparing the dates, and can be one of either "*year*", "*month*", "*day*", "*hour*", "*minute*" or "*second*".
 
 ```javascript
-const isAfter = dateTime.isAfter(other, granularity);
+const isAfter = dateTime.isAfter(other, options);
 ```
 
 If a `granularity` is not specified, this method will compare the dates in milliseconds.
@@ -764,10 +767,11 @@ If a `granularity` is not specified, this method will compare the dates in milli
 Return *true* if the *DateTime* is before another date.
 
 - `other` is the *DateTime* object to compare to.
-- `granularity` is a string specifying the level of granularity to use when comparing the dates, and can be one of either "*year*", "*month*", "*day*", "*hour*", "*minute*" or "*second*".
+- `options` is an object containing options for how to compare the dates.
+    - `granularity` is a string specifying the level of granularity to use when comparing the dates, and can be one of either "*year*", "*month*", "*day*", "*hour*", "*minute*" or "*second*".
 
 ```javascript
-const isBefore = dateTime.isBefore(other, granularity);
+const isBefore = dateTime.isBefore(other, options);
 ```
 
 If a `granularity` is not specified, this method will compare the dates in milliseconds.
@@ -778,10 +782,11 @@ Return *true* if the *DateTime* is between two other dates.
 
 - `start` is the starting *DateTime* object to compare to.
 - `end` is the ending *DateTime* object to compare to.
-- `granularity` is a string specifying the level of granularity to use when comparing the dates, and can be one of either "*year*", "*month*", "*day*", "*hour*", "*minute*" or "*second*".
+- `options` is an object containing options for how to compare the dates.
+    - `granularity` is a string specifying the level of granularity to use when comparing the dates, and can be one of either "*year*", "*month*", "*day*", "*hour*", "*minute*" or "*second*".
 
 ```javascript
-const isBetween = dateTime.isBetween(start, end, granularity);
+const isBetween = dateTime.isBetween(start, end, options);
 ```
 
 If a `granularity` is not specified, this method will compare the dates in milliseconds.
@@ -807,10 +812,11 @@ const isLeapYear = dateTime.isLeapYear();
 Return *true* if the *DateTime* is the same as another date.
 
 - `other` is the *DateTime* object to compare to.
-- `granularity` is a string specifying the level of granularity to use when comparing the dates, and can be one of either "*year*", "*month*", "*day*", "*hour*", "*minute*" or "*second*".
+- `options` is an object containing options for how to compare the dates.
+    - `granularity` is a string specifying the level of granularity to use when comparing the dates, and can be one of either "*year*", "*month*", "*day*", "*hour*", "*minute*" or "*second*".
 
 ```javascript
-const isSame = dateTime.isSame(other, granularity);
+const isSame = dateTime.isSame(other, options);
 ```
 
 If a `granularity` is not specified, this method will compare the dates in milliseconds.
@@ -820,10 +826,11 @@ If a `granularity` is not specified, this method will compare the dates in milli
 Return *true* if the *DateTime* is the same or after another date.
 
 - `other` is the *DateTime* object to compare to.
-- `granularity` is a string specifying the level of granularity to use when comparing the dates, and can be one of either "*year*", "*month*", "*day*", "*hour*", "*minute*" or "*second*".
+- `options` is an object containing options for how to compare the dates.
+    - `granularity` is a string specifying the level of granularity to use when comparing the dates, and can be one of either "*year*", "*month*", "*day*", "*hour*", "*minute*" or "*second*".
 
 ```javascript
-const isSameOrAfter = dateTime.isSameOrAfter(other, granularity);
+const isSameOrAfter = dateTime.isSameOrAfter(other, options);
 ```
 
 If a `granularity` is not specified, this method will compare the dates in milliseconds.
@@ -833,10 +840,11 @@ If a `granularity` is not specified, this method will compare the dates in milli
 Return *true* if the *DateTime* is the same or before another date.
 
 - `other` is the *DateTime* object to compare to.
-- `granularity` is a string specifying the level of granularity to use when comparing the dates, and can be one of either "*year*", "*month*", "*day*", "*hour*", "*minute*" or "*second*".
+- `options` is an object containing options for how to compare the dates.
+    - `granularity` is a string specifying the level of granularity to use when comparing the dates, and can be one of either "*year*", "*month*", "*day*", "*hour*", "*minute*" or "*second*".
 
 ```javascript
-const isSameOrBefore = dateTime.isSameOrBefore(other, granularity);
+const isSameOrBefore = dateTime.isSameOrBefore(other, options);
 ```
 
 If a `granularity` is not specified, this method will compare the dates in milliseconds.
@@ -910,15 +918,15 @@ const daysInYear = DateTime.daysInYear(year);
 Get the default locale.
 
 ```javascript
-locale = DateTime.getDefaultLocale();
+const locale = DateTime.getDefaultLocale();
 ```
 
-**Set Default Time Zone**
+**Get Default Time Zone**
 
 Get the default time zone.
 
 ```javascript
-timeZone = DateTime.getDefaultTimeZone();
+const timeZone = DateTime.getDefaultTimeZone();
 ```
 
 **Is Leap Year?**

package/dist/frost-datetime.js

@@ -161,12 +161,12 @@
     function getBiggestDiff(date, other) {
         let lastResult;
         for (const timeUnit of ['year', 'month', 'week', 'day', 'hour', 'minute', 'second']) {
-            const relativeDiff = date.diff(other, timeUnit);
+            const relativeDiff = date.diff(other, { timeUnit });
             if (lastResult && thresholds[timeUnit] && Math.abs(relativeDiff) >= thresholds[timeUnit]) {
                 return lastResult;
             }
 
-            const actualDiff = date.diff(other, timeUnit, false);
+            const actualDiff = date.diff(other, { timeUnit, relative: false });
             if (actualDiff) {
                 return [relativeDiff, timeUnit];
             }
@@ -2553,11 +2553,12 @@
     /**
      * Get the difference between this and another Date.
      * @param {DateTime} [other] The date to compare to.
-     * @param {string} [timeUnit] The unit of time.
-     * @param {Boolean} [relative=true] Whether to use the relative difference.
+     * @param {object} [options] The options for comparing the dates.
+     * @param {string} [options.timeUnit] The unit of time.
+     * @param {Boolean} [options.relative=true] Whether to use the relative difference.
      * @return {number} The difference.
      */
-    function diff(other, timeUnit, relative = true) {
+    function diff(other, { timeUnit, relative = true } = {}) {
         if (!other) {
             other = new this.constructor;
         }
@@ -2695,10 +2696,11 @@
     /**
      * Get the difference between this and another Date in human readable form.
      * @param {DateTime} [other] The date to compare to.
-     * @param {string} [timeUnit] The unit of time.
+     * @param {object} [options] The options for comparing the dates.
+     * @param {string} [options.timeUnit] The unit of time.
      * @return {string} The difference in human readable form.
      */
-    function humanDiff(other, timeUnit) {
+    function humanDiff(other, { timeUnit } = {}) {
         const relativeFormatter = getRelativeFormatter(this.getLocale());
 
         if (!relativeFormatter) {
@@ -2711,7 +2713,7 @@
 
         let amount;
         if (timeUnit) {
-            amount = this.diff(other, timeUnit);
+            amount = this.diff(other, { timeUnit });
         } else {
             [amount, timeUnit] = getBiggestDiff(this, other);
         }
@@ -2721,30 +2723,33 @@
     /**
      * Determine whether this DateTime is after another date (optionally to a granularity).
      * @param {DateTime} [other] The date to compare to.
-     * @param {string} [granularity] The level of granularity to use for comparison.
+     * @param {object} [options] The options for comparing the dates.
+     * @param {string} [options.granularity] The level of granularity to use for comparison.
      * @return {Boolean} TRUE if this DateTime is after the other date, otherwise FALSE.
      */
-    function isAfter(other, granularity) {
-        return this.diff(other, granularity) > 0;
+    function isAfter(other, { granularity } = {}) {
+        return this.diff(other, { timeUnit: granularity }) > 0;
     }
     /**
      * Determine whether this DateTime is before another date (optionally to a granularity).
      * @param {DateTime} [other] The date to compare to.
-     * @param {string} [granularity] The level of granularity to use for comparison.
+     * @param {object} [options] The options for comparing the dates.
+     * @param {string} [options.granularity] The level of granularity to use for comparison.
      * @return {Boolean} TRUE if this DateTime is before the other date, otherwise FALSE.
      */
-    function isBefore(other, granularity) {
-        return this.diff(other, granularity) < 0;
+    function isBefore(other, { granularity } = {}) {
+        return this.diff(other, { timeUnit: granularity }) < 0;
     }
     /**
      * Determine whether this DateTime is between two other dates (optionally to a granularity).
      * @param {DateTime} [start] The first date to compare to.
      * @param {DateTime} [end] The second date to compare to.
-     * @param {string} [granularity] The level of granularity to use for comparison.
+     * @param {object} [options] The options for comparing the dates.
+     * @param {string} [options.granularity] The level of granularity to use for comparison.
      * @return {Boolean} TRUE if this DateTime is between the other dates, otherwise FALSE.
      */
-    function isBetween(start, end, granularity) {
-        return this.diff(start, granularity) > 0 && this.diff(end, granularity) < 0;
+    function isBetween(start, end, { granularity } = {}) {
+        return this.diff(start, { timeUnit: granularity }) > 0 && this.diff(end, { timeUnit: granularity }) < 0;
     }
     /**
      * Return true if the DateTime is in daylight savings.
@@ -2777,29 +2782,32 @@
     /**
      * Determine whether this DateTime is the same as another date (optionally to a granularity).
      * @param {DateTime} [other] The date to compare to.
-     * @param {string} [granularity] The level of granularity to use for comparison.
+     * @param {object} [options] The options for comparing the dates.
+     * @param {string} [options.granularity] The level of granularity to use for comparison.
      * @return {Boolean} TRUE if this DateTime is the same as the other date, otherwise FALSE.
      */
-    function isSame(other, granularity) {
-        return this.diff(other, granularity) === 0;
+    function isSame(other, { granularity } = {}) {
+        return this.diff(other, { timeUnit: granularity }) === 0;
     }
     /**
      * Determine whether this DateTime is the same or after another date (optionally to a granularity).
      * @param {DateTime} [other] The date to compare to.
-     * @param {string} [granularity] The level of granularity to use for comparison.
+     * @param {object} [options] The options for comparing the dates.
+     * @param {string} [options.granularity] The level of granularity to use for comparison.
      * @return {Boolean} TRUE if this DateTime is the same or after the other date, otherwise FALSE.
      */
-    function isSameOrAfter(other, granularity) {
-        return this.diff(other, granularity) >= 0;
+    function isSameOrAfter(other, { granularity } = {}) {
+        return this.diff(other, { timeUnit: granularity }) >= 0;
     }
     /**
      * Determine whether this DateTime is the same or before another date.
      * @param {DateTime} other The date to compare to.
-     * @param {string} [granularity] The level of granularity to use for comparison.
+     * @param {object} [options] The options for comparing the dates.
+     * @param {string} [options.granularity] The level of granularity to use for comparison.
      * @return {Boolean} TRUE if this DateTime is the same or before the other date, otherwise FALSE.
      */
-    function isSameOrBefore(other, granularity) {
-        return this.diff(other, granularity) <= 0;
+    function isSameOrBefore(other, { granularity } = {}) {
+        return this.diff(other, { timeUnit: granularity }) <= 0;
     }
     /**
      * Get the name of the month in current timeZone.