Part of the JSBits suite.
For NodeJS and JS bundlers:
npm i @jsbits/add-months# oryarn add @jsbits/add-months
addMonths in the browser:
- ES5 compatible browser
- NodeJS v4.2 or later
addMonths(startdate, count, [asUTC]) ⇒
Returns a date occurring
count months after
startdate or, if
negative, the date occurring
count months before
startdateis not a Date or number that can be converted to a valid date, returns a new Date instance with an invalid date.
countis evaluated as zero, returns a new Date instance with the the same value as
If there is an overflow in the day, the date is adjusted to the last valid day of the expected month.
The third parameter is optional and indicates if the date is UTC. It is necessary to differentiate UTC dates from locals and avoid errors due to the Daylight Saving Time (DST).
This function does not change the original date.
||Number of months to add or subtract|
Date - A new, adjusted Date instance.
// Helper for creating a local date based on a string// can increment above one yearaddMonthstoDate'2017-01-08', 15 // ⇒ 2018-04-08 06:00:00// decrement worksaddMonthstoDate'2017-01-01', -1 // ⇒ 2016-12-01 06:00:00// avoids day overflowaddMonthstoDate'2017-01-31', 1 // ⇒ 2017-02-28 06:00:00// can handle leap yearsaddMonthstoDate'2016-01-31', 1 // ⇒ 2016-02-29 06:00:00// with the third parameter, date is handled as UTCaddMonthsnew Date'2015-01-01T05:00:00Z', 1, true // ⇒ 2015-02-01 05:00:00Z// it accepts numericals parametersaddMonths1541898143424, 1 // ⇒ 2018-12-11 01:02:23// returns an Invalid Date (i.e. NaN) for other types,// to avoid undesired conversions to the current date.addMonthsfalse, 1 // ⇒ NaN
If you prefer, you can inject addMonths into the
Date.prototype by requiring 'proto' or by loading the IIFE from 'proto.js' in the browser:
The new functionality is exposed in separate methods, with an API similar to other methods of the
addMonthsfor local dates
addUTCMonthsfor UTC dates
Both methods receive the number of months to add or subtract and update the value of the object directly.
The returned value is the number of milliseconds between 1 January 1970 00:00:00 UTC and the updated date, or
NaN if the date is invalid. The
asUTC flag is not necessary.
Date.prototype.addMonths.call with other type than
Date generates a TypeError.
This example shows the behavior of both methods using the same date instance:
// this is using ESM syntax, but you can use require()// helpersshowLocdate // ⇒ Wed Jan 30 2019 20:00:00 GMT-0600 (CST)showResdate.addMonths1 // ⇒ 1551405600000showLocdate // ⇒ Thu Feb 28 2019 20:00:00 GMT-0600 (CST)showUTCdate // ⇒ 2019-03-01T02:00:00.000ZshowResdate.addUTCMonths1 // ⇒ 1554084000000showUTCdate // ⇒ 2019-04-01T02:00:00.000Z
Note about DST
For local dates, the time offset may change if the resulting date has DST activation different from the original.
For example, if a GMT-0600 zone changes to GMT-0500 between May and October, the following will shift the time offset preserving the hour:
The same dates in UTC, which has no time offset, show the change:
console.logorigin.toISOString // ⇒ 2018-01-20T22:00:00.000Zconsole.logresult.toISOString // ⇒ 2018-07-20T21:00:00.000Z
The same happens if you apply a
setMonth(6) to that date, which is correct and generally expected, just keep it in mind if you handle UTC dates based on local dates.
Date from String
Avoid creating dates with strings, it is inconsistent.
From Date at MDN:
Note: parsing of date strings with the
Date.parse, they are equivalent) is strongly discouraged due to browser differences and inconsistencies. Support for RFC 2822 format strings is by convention only. Support for ISO 8601 formats differs in that date-only strings (e.g. "1970-01-01") are treated as UTC, not local.
Even node 6 has problems with this. Do not use it except with the UTC ISO-8601 format.
All the JSBits functions works in strict mode and are compatible with:
- ES5 browsers, through the jQuery
$.jsbitsobject or the global
- ESM Bundlers, like webpack and Rollup.
- ES modules for modern browsers or NodeJS with the
- CommonJS modules of NodeJS, jspm, and others.
- Babel and TypeScript, through ES Module Interop.
Please see the Distribution Formats in the JSBits README to know about all the variants.
Support my Work
I'm a full-stack developer with more than 20 year of experience and I try to share most of my work for free and help others, but this takes a significant amount of time and effort so, if you like my work, please consider...
Of course, feedback, PRs, and stars are also welcome 🙃
Thanks for your support!
The MIT License.