Merge pull request #92 from knowledgecode/develop

Develop

Author: knowledgecode

PLUGINS.md

@@ -76,7 +76,7 @@ date.plugin('foobar');
   - It adds `timeSpan()` function that calculates the difference of two dates to the library.
 
 - [timezone](#timezone)
-  - It adds `formatTZ()`, `parseTZ()` and `transformTZ()` that support `IANA time zone names` to the library.
+  - It adds `formatTZ()`, `parseTZ()`, `transformTZ()`, `addYearsTZ()`, `addMonthsTZ()` and `addDaysTZ()` that support `IANA time zone names` to the library.
 
 - [two-digit-year](#two-digit-year)
   - It adds two-digit year notation to the parser.
@@ -290,7 +290,7 @@ In these functions can be available some tokens to format the calculation result
 
 ### timezone
 
-It adds `formatTZ()`, `parseTZ()` and `transformTZ()` that support `IANA time zone names` (`America/Los_Angeles`, `Asia/Tokyo`, and so on) to the library.
+It adds `formatTZ()`, `parseTZ()`, `transformTZ()`, `addYearsTZ()`, `addMonthsTZ()` and `addDaysTZ()` that support `IANA time zone names` (`America/Los_Angeles`, `Asia/Tokyo`, and so on) to the library.
 
 #### formatTZ(dateObj, arg[, timeZone])
 
@@ -299,7 +299,7 @@ It adds `formatTZ()`, `parseTZ()` and `transformTZ()` that support `IANA time zo
 - @param {**string**} [timeZone] - Output as this time zone
 - @returns {**string**} A formatted string
 
-`formatTZ()` is upward compatible with `format()`. Tokens available for `arg` are the same as those for `format()`. If `timeZone` is omitted, this function assumes `timeZone` to be a local time zone and outputs a string. This means that the result is the same as when `format()` is used.
+`formatTZ()` is upward compatible with `format()`. Tokens available for `arg` are the same as those for `format()`. If `timeZone` is omitted, this function assumes `timeZone` to be the local time zone and outputs a string. This means that the result is the same as when `format()` is used.
 
 #### parseTZ(dateString, arg[, timeZone])
 
@@ -308,7 +308,7 @@ It adds `formatTZ()`, `parseTZ()` and `transformTZ()` that support `IANA time zo
 - @param {**string**} [timeZone] - Input as this time zone
 - @returns {**Date**} A Date object
 
-`parseTZ()` is upward compatible with `parse()`. Tokens available for `arg` are the same as those for `parse()`. `timeZone` in this function is used as supplemental information. if `dateString` contains a time zone offset value (i.e. -0800, +0900), `timeZone` is not be used. If `dateString` doesn't contain a time zone offset value and `timeZone` is omitted, this function assumes `timeZone` to be a local time zone. This means that the result is the same as when `parse()` is used.
+`parseTZ()` is upward compatible with `parse()`. Tokens available for `arg` are the same as those for `parse()`. `timeZone` in this function is used as supplemental information. if `dateString` contains a time zone offset value (i.e. -0800, +0900), `timeZone` is not be used. If `dateString` doesn't contain a time zone offset value and `timeZone` is omitted, this function assumes `timeZone` to be the local time zone. This means that the result is the same as when `parse()` is used.
 
 #### transformTZ(dateString, arg1, arg2[, timeZone])
 
@@ -318,7 +318,34 @@ It adds `formatTZ()`, `parseTZ()` and `transformTZ()` that support `IANA time zo
 - @param {**string**} [timeZone] - Output as this time zone
 - @returns {**string**} A formatted string
 
-`transformTZ()` is upward compatible with `transform()`. `dateString` must itself contain a time zone offset value (i.e. -0800, +0900), otherwise this function assumes it is a local time zone. Tokens available for `arg1` are the same as those for `parse()`, also tokens available for `arg2` are the same as those for `format()`. `timeZone` is a `IANA time zone names`, which is required to output a new formatted string. If it is omitted, this function assumes `timeZone` to be a local time zone. This means that the result is the same as when `transform()` is used.
+`transformTZ()` is upward compatible with `transform()`. `dateString` must itself contain a time zone offset value (i.e. -0800, +0900), otherwise this function assumes it is the local time zone. Tokens available for `arg1` are the same as those for `parse()`, also tokens available for `arg2` are the same as those for `format()`. `timeZone` is a `IANA time zone names`, which is required to output a new formatted string. If it is omitted, this function assumes `timeZone` to be the local time zone. This means that the result is the same as when `transform()` is used.
+
+#### addYearsTZ(dateObj, years[, timeZone])
+
+- @param {**Date**} dateObj - A Date object
+- @param {**number**} years - The number of years to add
+- @param {**string**} [timeZone] - The time zone to use for the calculation
+- @returns {**Date**} The Date object after adding the specified number of years
+
+`addYearsTZ()` can calculate adding years in the specified time zone regardless of the execution environment.
+
+#### addMonthsTZ(dateObj, months[, timeZone])
+
+- @param {**Date**} dateObj - A Date object
+- @param {**number**} months - The number of months to add
+- @param {**string**} [timeZone] - The time zone to use for the calculation
+- @returns {**Date**} The Date object after adding the specified number of months
+
+`addMonthsTZ()` can calculate adding months in the specified time zone regardless of the execution environment.
+
+#### addDaysTZ(dateObj, days[, timeZone])
+
+- @param {**Date**} dateObj - A Date object
+- @param {**number**} days - The number of days to add
+- @param {**string**} [timeZone] - The time zone to use for the calculation
+- @returns {**Date**} The Date object after adding the specified number of days
+
+`addDaysTZ()` can calculate adding days in the specified time zone regardless of the execution environment.
 
 ```javascript
 const date = require('date-and-time');

README.md

@@ -25,16 +25,17 @@ npm i date-and-time
 
 ## Recent Changes
 
+- 3.5.0
+  - Added `addYearsTZ()`, `addMonthsTZ()`, and `addDaysTZ()` to the `timezone` plugin.
+  - Revised the approach to adding time and removed the third parameter from `addHours()`, `addMinutes()`, `addSeconds()`, and `addMilliseconds()`.
+
 - 3.4.1
   - Fixed an issue where `formatTZ()` would output 0:00 as 24:00 in 24-hour format in Node.js.
 
 - 3.4.0
   - Added `zz` (time zone name) and `z` (time zone name abbreviation) tokens to the `timezone` plugin.
   - Fixed an issue where token extensions by other plugins were not reflected in functions provided by the `timezone` plugin.
 
-- 3.3.0
-  - Refactored `format()`, `isValid()`, and `preparse()`, further improved performance.
-
 ## Usage
 
 - ES Modules:
@@ -98,16 +99,16 @@ import date from '/path/to/date-and-time.es.min.js';
 - [addDays](#adddaysdateobj-days-utc)
   - Adding days
 
-- [addHours](#addhoursdateobj-hours-utc)
+- [addHours](#addhoursdateobj-hours)
   - Adding hours
 
-- [addMinutes](#addminutesdateobj-minutes-utc)
+- [addMinutes](#addminutesdateobj-minutes)
   - Adding minutes
 
-- [addSeconds](#addsecondsdateobj-seconds-utc)
+- [addSeconds](#addsecondsdateobj-seconds)
   - Adding seconds
 
-- [addMilliseconds](#addmillisecondsdateobj-milliseconds-utc)
+- [addMilliseconds](#addmillisecondsdateobj-milliseconds)
   - Adding milliseconds
 
 - [subtract](#subtractdate1-date2)
@@ -434,11 +435,11 @@ date.transform('13:05', 'HH:mm', 'hh:mm A');
 ### addYears(dateObj, years[, utc])
 
 - @param {**Date**} dateObj - A Date object
-- @param {**number**} years - Number of years to add
-- @param {**boolean**} [utc] - Calculates as UTC `Added in: v3.0.0`
-- @returns {**Date**} The Date object after adding the value
+- @param {**number**} years - The number of years to add
+- @param {**boolean**} [utc] - If true, calculates the date in UTC `Added in: v3.0.0`
+- @returns {**Date**} The Date object after adding the specified number of years
 
-Adds years to the date object.
+Adds years to a date object. Subtraction is also possible by specifying a negative value. If the third parameter is false or omitted, this function calculates based on the system's default time zone. If you need to obtain calculation results based on a specific time zone regardless of the execution system, consider using the `addYearsTZ()`, which allows you to specify a time zone name as the third parameter. See [PLUGINS.md](./PLUGINS.md) for details.
 
 ```javascript
 const now = new Date();
@@ -456,11 +457,11 @@ const next_next_year = date.addYears(next_year, 1, true);   // => Feb 28 2022
 ### addMonths(dateObj, months[, utc])
 
 - @param {**Date**} dateObj - A Date object
-- @param {**number**} months - Number of months to add
-- @param {**boolean**} [utc] - Calculates as UTC `Added in: v3.0.0`
-- @returns {**Date**} The Date object after adding the value
+- @param {**number**} months - The number of months to add
+- @param {**boolean**} [utc] - If true, calculates the date in UTC `Added in: v3.0.0`
+- @returns {**Date**} The Date object after adding the specified number of months
 
-Adds months to the date object.
+Adds months to a date object. Subtraction is also possible by specifying a negative value. If the third parameter is false or omitted, this function calculates based on the system's default time zone. If you need to obtain calculation results based on a specific time zone regardless of the execution system, consider using the `addMonthsTZ()`, which allows you to specify a time zone name as the third parameter. See [PLUGINS.md](./PLUGINS.md) for details.
 
 ```javascript
 const now = new Date();
@@ -478,57 +479,67 @@ const next_next_month = date.addMonths(next_month, 1, true);    // => Mar 28 202
 ### addDays(dateObj, days[, utc])
 
 - @param {**Date**} dateObj - A Date object
-- @param {**number**} days - Number of days to add
-- @param {**boolean**} [utc] - Calculates as UTC `Added in: v3.0.0`
-- @returns {**Date**} The Date object after adding the value
+- @param {**number**} days - The number of days to add
+- @param {**boolean**} [utc] - If true, calculates the date in UTC `Added in: v3.0.0`
+- @returns {**Date**} The Date object after adding the specified number of days
+
+Adds days to a date object. Subtraction is also possible by specifying a negative value. If the third parameter is false or omitted, this function calculates based on the system's default time zone. If you need to obtain calculation results based on a specific time zone regardless of the execution system, consider using the `addDaysTZ()`, which allows you to specify a time zone name as the third parameter. See [PLUGINS.md](./PLUGINS.md) for details.
 
 ```javascript
 const now = new Date();
 const yesterday = date.addDays(now, -1);
 ```
 
-### addHours(dateObj, hours[, utc])
+### addHours(dateObj, hours)
 
 - @param {**Date**} dateObj - A Date object
-- @param {**number**} hours - Number of hours to add
-- @param {**boolean**} [utc] - Calculates as UTC `Added in: v3.0.0`
-- @returns {**Date**} The Date object after adding the value
+- @param {**number**} hours - The number of hours to add
+- ~~@param {**boolean**} [utc] - If true, calculates the date in UTC `Added in: v3.0.0`~~ `Removed in: v3.5.0`
+- @returns {**Date**} The Date object after adding the specified number of hours
+
+Adds hours to a date object. Subtraction is also possible by specifying a negative value. The third parameter was deprecated in version 3.5.0. Regardless of what is specified for this parameter, the calculation results will not change.
 
 ```javascript
 const now = new Date();
 const an_hour_ago = date.addHours(now, -1);
 ```
 
-### addMinutes(dateObj, minutes[, utc])
+### addMinutes(dateObj, minutes)
 
 - @param {**Date**} dateObj - A Date object
-- @param {**number**} minutes - Number of minutes to add
-- @param {**boolean**} [utc] - Calculates as UTC `Added in: v3.0.0`
-- @returns {**Date**} The Date object after adding the value
+- @param {**number**} minutes - The number of minutes to add
+- ~~@param {**boolean**} [utc] - If true, calculates the date in UTC `Added in: v3.0.0`~~ `Removed in: v3.5.0`
+- @returns {**Date**} The Date object after adding the specified number of minutes
+
+Adds minutes to a date object. Subtraction is also possible by specifying a negative value. The third parameter was deprecated in version 3.5.0. Regardless of what is specified for this parameter, the calculation results will not change.
 
 ```javascript
 const now = new Date();
 const two_minutes_later = date.addMinutes(now, 2);
 ```
 
-### addSeconds(dateObj, seconds[, utc])
+### addSeconds(dateObj, seconds)
 
 - @param {**Date**} dateObj - A Date object
-- @param {**number**} seconds - Number of seconds to add
-- @param {**boolean**} [utc] - Calculates as UTC `Added in: v3.0.0`
-- @returns {**Date**} The Date object after adding the value
+- @param {**number**} seconds - The number of seconds to add
+- ~~@param {**boolean**} [utc] - If true, calculates the date in UTC `Added in: v3.0.0`~~ `Removed in: v3.5.0`
+- @returns {**Date**} The Date object after adding the specified number of seconds
+
+Adds seconds to a date object. Subtraction is also possible by specifying a negative value. The third parameter was deprecated in version 3.5.0. Regardless of what is specified for this parameter, the calculation results will not change.
 
 ```javascript
 const now = new Date();
 const three_seconds_ago = date.addSeconds(now, -3);
 ```
 
-### addMilliseconds(dateObj, milliseconds[, utc])
+### addMilliseconds(dateObj, milliseconds)
 
 - @param {**Date**} dateObj - A Date object
-- @param {**number**} milliseconds - Number of milliseconds to add
-- @param {**boolean**} [utc] - Calculates as UTC `Added in: v3.0.0`
-- @returns {**Date**} The Date object after adding the value
+- @param {**number**} milliseconds - The number of milliseconds to add
+- ~~@param {**boolean**} [utc] - If true, calculates the date in UTC `Added in: v3.0.0`~~ `Removed in: v3.5.0`
+- @returns {**Date**} The Date object after adding the specified number of milliseconds
+
+Adds milliseconds to a date object. Subtraction is also possible by specifying a negative value. The third parameter was deprecated in version 3.5.0. Regardless of what is specified for this parameter, the calculation results will not change.
 
 ```javascript
 const now = new Date();

date-and-time.d.ts

@@ -153,63 +153,95 @@ export function transform(dateString: string, compiledObj1: string[], compiledOb
 /**
  * Adding years
  * @param dateObj - A Date object
- * @param years - Number of years to add
- * @param [utc] - Calculates as UTC
- * @returns The Date object after adding the value
+ * @param years - The number of years to add
+ * @param [utc] - If true, calculates the date in UTC
+ * @returns The Date object after adding the specified number of years
  */
 export function addYears(dateObj: Date, years: number, utc?: boolean): Date;
 
 /**
  * Adding months
  * @param dateObj - A Date object
- * @param months - Number of months to add
- * @param [utc] - Calculates as UTC
- * @returns The Date object after adding the value
+ * @param months - The number of months to add
+ * @param [utc] - If true, calculates the date in UTC
+ * @returns The Date object after adding the specified number of months
  */
 export function addMonths(dateObj: Date, months: number, utc?: boolean): Date;
 
 /**
  * Adding days
  * @param dateObj - A Date object
- * @param days - Number of days to add
- * @param [utc] - Calculates as UTC
- * @returns The Date object after adding the value
+ * @param days - The number of days to add
+ * @param [utc] - If true, calculates the date in UTC
+ * @returns The Date object after adding the specified number of days
  */
 export function addDays(dateObj: Date, days: number, utc?: boolean): Date;
 
 /**
  * Adding hours
  * @param dateObj - A Date object
- * @param hours - Number of hours to add
- * @param [utc] - Calculates as UTC
- * @returns The Date object after adding the value
+ * @param hours - The number of hours to add
+ * @returns The Date object after adding the specified number of hours
+ */
+export function addHours(dateObj: Date, hours: number): Date;
+
+/**
+ * @deprecated The `utc` parameter is ignored. The function always returns the same result regardless of this value.
+ * @param dateObj - A Date object
+ * @param hours - The number of hours to add
+ * @param [utc] - If true, calculates the date in UTC
+ * @returns The Date object after adding the specified number of hours
  */
 export function addHours(dateObj: Date, hours: number, utc?: boolean): Date;
 
 /**
  * Adding minutes
  * @param dateObj - A Date object
- * @param minutes - Number of minutes to add
- * @param [utc] - Calculates as UTC
- * @returns The Date object after adding the value
+ * @param minutes - The number of minutes to add
+ * @returns The Date object after adding the specified number of minutes
+ */
+export function addMinutes(dateObj: Date, minutes: number): Date;
+
+/**
+ * @deprecated The `utc` parameter is ignored. The function always returns the same result regardless of this value.
+ * @param dateObj - A Date object
+ * @param minutes - The number of minutes to add
+ * @param [utc] - If true, calculates the date in UTC
+ * @returns The Date object after adding the specified number of minutes
  */
 export function addMinutes(dateObj: Date, minutes: number, utc?: boolean): Date;
 
 /**
  * Adding seconds
  * @param dateObj - A Date object
- * @param seconds - Number of seconds to add
- * @param [utc] - Calculates as UTC
- * @returns The Date object after adding the value
+ * @param seconds - The number of seconds to add
+ * @returns The Date object after adding the specified number of seconds
+ */
+export function addSeconds(dateObj: Date, seconds: number): Date;
+
+/**
+ * @deprecated The `utc` parameter is ignored. The function always returns the same result regardless of this value.
+ * @param dateObj - A Date object
+ * @param seconds - The number of seconds to add
+ * @param [utc] - If true, calculates the date in UTC
+ * @returns The Date object after adding the specified number of seconds
  */
 export function addSeconds(dateObj: Date, seconds: number, utc?: boolean): Date;
 
 /**
  * Adding milliseconds
  * @param dateObj - A Date object
- * @param milliseconds - Number of milliseconds to add
- * @param [utc] - Calculates as UTC
- * @returns The Date object after adding the value
+ * @param milliseconds - The number of milliseconds to add
+ * @returns The Date object after adding the specified number of milliseconds
+ */
+export function addMilliseconds(dateObj: Date, milliseconds: number): Date;
+
+/**
+ * @deprecated The `utc` parameter is ignored. The function always returns the same result regardless of this value.
+ * @param dateObj - A Date object
+ * @param milliseconds - The number of milliseconds to add
+ * @param [utc] - If true, calculates the date in UTC
+ * @returns The Date object after adding the specified number of milliseconds
  */
 export function addMilliseconds(dateObj: Date, milliseconds: number, utc?: boolean): Date;