All notable changes to this project will be documented in this file. This project adheres to Semantic Versioning.
This change log follows the format documented in Keep a CHANGELOG.
Kudos to @kossnocorp and @Andarist for working on the release.
This release is prepared by our own @leshakoss.
This release is brought to you by @nopears, @vadimpopa and @leshakoss.
Thanks to @fturmel for working on the release.
On this release worked @tan75, @kossnocorp, @nopears, @Balastrong, @cpapazoglou, @dovca, @aliasgar55, @tomchentw, @JuanM04, @alexandresaura, @fturmel, @aezell, @andersravn, @TiagoPortfolio, @SukkaW, @Zebreus, @aviskarkc10, @maic66, @a-korzun, @Mejans, @davidspiess, @alexgul1, @matroskin062, @undecaf, @mprovenc, @jooola and @leshakoss.
Fixed long formatters in the South African English locale (en-ZA).
Fixed weekday format for formatRelative in the Portuguese locale (pt).
Fixed issue parsing months in Croatian (hr), Georgian (ka) and Serbian (sr and sr-Latn) locales.
Kudos to @tan75, @fturmel, @arcanar7, @jeffjose, @helmut-lang, @zrev2220, @jooola, @minitesh, @cowboy-bebug, @mesqueeb, @JuanM04, @zhirzh, @damon02 and @leshakoss for working on the release.
Kudos to @tan75, @hg-pyun, @07akioni, @razvanmitre, @Haqverdi, @pgcalixto, @janziemba, @fturmel, @JuanM04, @zhirzh, @seanghay, @bulutfatih, @nodeadtree, @cHaLkdusT, @a-korzun, @fishmandev, @wingclover, @Zacharias3690, @kossnocorp and @leshakoss for working on the release.
Fixed translation for quarters in format in Chinese Simplified locale (zh-CN).
Fixed regular expressions for parse in Estonian locale (er).
Fixed the format of zeros in formatDuration in Czech locale (cs).
Fixed constants not having proper TypeScript and Flow types.
Fixed eachMinuteOfInterval not handling intervals less than a minute correctly.
Thanks to @kossnocorp, @leshakoss, @tan75, @gaplo, @AbdAllahAbdElFattah13, @fturmel, @kentaro84207, @V-Gutierrez, @atefBB, @jhonatanmacazana, @zhirzh, @Haqverdi, @mandaputtra, @micnic and @rikkalo for working on the release.
This release is brought to you by @kossnocorp, @gierschv, @fturmel, @redbmk, @mprovenc, @artyom-ivanov and @tan75.
Kudos to Sasha Koss, Lucas Silva, Jan Ziemba, Anastasia Kobzar, Deepak Gupta, Jonas L, Kentaro Suzuki, Koussay Haj Kacem, fturmel, Tan75 and Adriaan Callaerts for working on the release.
Used 1 instead of ein for German formatDuration to make it consistent with other locales and formats. (#2505)
Made Norwegian formatDuration consistent with other locales by using numeric representation instead of written. (#2469)
Use the word "sekunda" instead of "vteřina" for second in the Czech locale.
Made Flemish short date format corresponds to the Flemish government.
Added roundingMethod option to differenceInHours, differenceInMinutes, differenceInQuarters, differenceInSeconds and differenceInWeeks with trunc as the default method. (#2555)
Thanks to Liam Tait, fturmel, Takuya Uehara, Branislav Lazic, Seyyed Morteza Moosavi, Felipe Armoni, Sasha Koss, Michael Mok, Tan75 and Maxim Topciu for working on the release.
Added a new clamp function that allows to bound a date to an interval.
Allowed passing undefined in the duration to add and sub functions.
Thanks to Sasha Koss for working on the release.
Sasha Koss, Lucas Silva, Lay, jwbth, fturmel, Tan75 and Anastasia Kobzar worked on this release.
daysToWeekshoursToMillisecondshoursToMinuteshoursToSecondsmillisecondsToHoursmillisecondsToMinutesmillisecondsToSecondsminutesToHoursminutesToMillisecondsminutesToSecondsmonthsToQuartersmonthsToYearsquartersToMonthsquartersToYearssecondsToHourssecondsToMillisecondssecondsToMinutesweeksToDaysyearsToMonthsyearsToQuartersThis release is brought to you by Maxim Topciu.
Kudos to Aleksei Korzun, Maxim Topciu, Jonas L, Mohammad ali Ali panah and Tan75 for working on the release.
Thanks to Sasha Koss for working on the release.
This release is brought to you by Aleksei Korzun, Tan75, Rubens Mariuzzo, Christoph Stenglein and Clément Tamisier.
Kudos to fturmel for working on the release.
Kudos to Maxim Topciu for working on the release.
This release is brought to you by Sasha Koss and Tan75.
isDate Flow typings that we broke in v2.20.0.This release is brought to you by Sasha Koss, Maxim Topciu, tu4mo, Tan75, Ardit Dine, Carl Rosell, Roman Mahotskyi, Mateusz Krzak, fgottschalk, Anastasia Kobzar, Bilguun Ochirbat, Lesha Koss, YuLe and guyroberts21.
Made formatDistanceStrict and formatDistanceToNowStrict always return 1 year instead of 12 months. (#2388)
Fixed nextDay, nextMonday and nextTuesday missing in exports and type definitions. (#2325)
Tan75 worked on this release.
Assigned the correct firstWeekContainsDate value (4) for the French locale. (#2148)
Fixed a bug in differenceInMonths and intervalToDuration that occurs when dealing with the 28th of February. (#2255)
Thanks to Tan75 and Lesha Koss.
Kudos to @shaykav, @davidgape89, @rikkalo, @tan75, @talgautb, @owenl131, @kylesezhi, @inigoiparragirre, @gius, @Endeauvirr and @frankyston.
Fixed differenceInMonths for edge cases, such as the end of February dates.
Fixed formatDuration week translation in pt and pt-BR locales.
Made Japanese locale to use the correct value for the start of the week.
Fixed the short and medium date formats in the Czech locale.
Added intlFormat a lightweight formatting function that uses Intl API. Eventually, it will become the default formatting function, so it's highly recommended for new code.
Added an ability to format lowercase am/pm with aaa and bbb tokens.
Kudos to @aleksaps, @leedriscoll and @BanForFun for pull-requests!
formatRelative.Kudos to @jvpelt, @piotrl, @yotamofek, @dwaxweiler, @leedriscoll and @bradevans for working on the release. Also thanks to @PascalHonegger, @pickfire, @TheJaredWilcurt, @SidKH and @nfantone for improving the documentation.
1 minute and 2 days.formatRFC3339 formatting timezone offset with minutes.formatDurationThanks to @belgamo, @Matsuuu, @Imballinst, @arsnyder16, @pankajupadhyay29, @DCBN, @leedriscoll, @gottsohn, @mukuljainx and @dtriana for working on the release. Also kudos to @KidkArolis, @imgx64, @fjc0k, @wmonk, @djD-REK, @dandv, @psimk and @brimworks for improving the documentation.
addBusinessDays when input date is a weekend day.parseISO not returning Invalid Date on incorrect string when there are spaces in it.es round-tripping dates with Wednesday.d/EEEE ordering in tokens like PPPPP.fr-CH locale.nl-BE locale.gd locale.en-NZ locale.isMatch function.Kudos to @julamb, @JacobSoderblom, @justingrant, @dragunoff, @jmate0321, @gbhasha, @rasck, @AlbertoPdRF, @sebastianhaberey and @giogonzo for working on the release!
add, addDays and addMonths.formatDistance strings in the Hungarian locale.formatLong in the Spanish locale.formatRelative in the Italian locale.eachQuarterOfInterval.eu) locale.en-IN) locale.eachHourOfInterval.Thanks to @JorenVos, @developergouli, @rhlowe and @justingrant for working on the release!
Kudos to @leshakoss, @skyuplam, @so99ynoodles, @dkozickis, @belgamo, @akgondber, @dcousens and @BoomDev for working on the release!
setDay with weekStartsOn != 0.Kudos to @oakhan3, @Mukhammadali, @altrim, @leepowellcouk, @amatzon, @bryanMt, @kalekseev, @eugene-platov and @tjrobinson for working on the release.
differenceInYears causing incorrect results when the left date is a leap day.parseISO to work correctly around time shift dates.format to work correctly with GMT-0752/GMT-0456 and similar timezones.getDay typings to return 0|1|2|3|4|5|6 instead of number.ordinalNumber function behavior.formatRelative depending on if it's a current week or not.weeks to Duration.weeks support to add and sub.throwProtectedError.Thanks to @mborgbrant, @saintplay, @mrenty, @kibertoad, @levibuzolic, @Anshuman71, @talgautb, @filipjuza, @tobyzerner, @emil9453, @fintara, @pascaliske, @rramiachraf, @marnusw and @Imballinst for working on the release.
formatISO.eachMonthOfInterval and eachYearOfInterval.inclusive option to `areIntervalsOverlapping.isExists function that checks if the given date is exists.add function to add seconds, minutes, hours, weeks, years in single call.sub function, the opposite of add.Duration type used in add and sub.Locale type optional.Locale type.Locale type.parseJSON.parseJSON.Thanks to @Imballinst for the bug fix!
Kudos to @NaridaL, @Zyten, @Imballinst, @leshakoss and @Neorth for working on the release.
formatISO, formatISO9075, formatRFC3339, and formatRFC7231 functions.Thanks to @mzgajner, @NaridaL, @Zyten, @leshakoss, @fintara, @kpr-hellofresh for contributing to the release.
parseISO in Firefox caused by differences in getTimezoneOffset.parseJSON to accept strings without trailing 'Z' symbol and with up to 6 digits in the milliseconds' field.Kudos to @marnusw, @cdrikd and @rogyvoje for working on the release!
parseJSON - lightweight function (just 411 B) that parses dates formatted with toJSON.subBusinessDays function.Thanks to @mitchellbutler for the bug fix!
Kudos to @dkozickis, @drugoi, @kranthilakum, @102, @gpetrioli and @JulienMalige for making the release happen.
Interval and Locale types from Flow typings.Thanks to @mrclayman for reporting the issue and @leshakoss for fixing it.
This release is brought to you by these amazing people: @lovelovedokidoki, @alexigityan, @kalekseev and @andybangs. You rock!
parseISO.Huge thanks to @lovelovedokidoki who improved 8 (!) locales in an unstoppable open-source rampage and @VesterDe for fixing Slovenian locale 👏
Kudos to date-fns contributors: @mzgajner, @sibiraj-s, @mukeshmandiwal, @SneakyFish5 and @CarterLi.
set function.\n in format, lightFormat and parse.Thanks to date-fns contributors: @ManadayM, @illuminist, @visualfanatic, @vsaarinen and at last but not the least @leshakoss!
eachWeekendOfInterval skipping the first date in the supplied interval.getWeekOfMonth with options.weekStartsOn set to 1 not working for Sundays. Kudos to @waseemahmad31!If you're upgrading from v2 alpha or beta, see the pre-release changelog.
Fixed the toDate bug occurring when parsing ISO-8601 style dates (but not valid ISO format)
with a trailing Z (e.g 2012-01Z), it returned Invalid Date for FireFox/IE11 #510
Fixed differenceIn... functions returning negative zero in some cases:
#692
isDate now works properly with dates passed across iframes #754.
Fixed a few bugs that appeared in timezones with offsets that include seconds (e.g. GMT+00:57:44). See PR #789.
Fixed DST issue. See #972 and #992 for more details.
Fixed DST issue in eachDayOfInterval that caused time in the days
after DST change to have the shift as well.
Fixed bug in Galician locale caused by incorrect usage of getHours
instead of getUTCHours.
Invalid Date, NaN, etc).From now on a string should be parsed using parseISO (ISO 8601)
or parse.
In v1 we've used new Date() to parse strings, but it resulted in many
hard-to-track bugs caused by inconsistencies in different browsers.
To address that we've implemented our ISO 8601 parser but that made
library to significantly grow in size. To prevent inevitable bugs
and keep the library tiny, we made this trade-off.
See this post for more details.
```javascript // Before v2.0.0 addDays('2016-01-01', 1)
// v2.0.0 onward addDays(parseISO('2016-01-01'), 1) ```
format function
which is based on Unicode Technical Standard #35.
See this post for more details.| Unit | v2 Pattern | v1 Pattern | Result examples | | ------------------------------- | ---------- | ---------- | --------------------------------- | | Era | G..GGG | | AD, BC | | | GGGG | | Anno Domini, Before Christ | | | GGGGG | | A, B | | Calendar year | y | | 44, 1, 1900, 2017 | | | yo | | 44th, 1st, 0th, 17th | | | yy | YY | 44, 01, 00, 17 | | | yyy | | 044, 001, 1900, 2017 | | | yyyy | YYYY | 0044, 0001, 1900, 2017 | | | yyyyy | | ... | | Local week-numbering year | Y | | 44, 1, 1900, 2017 | | | Yo | | 44th, 1st, 1900th, 2017th | | | YY | | 44, 01, 00, 17 | | | YYY | | 044, 001, 1900, 2017 | | | YYYY | | 0044, 0001, 1900, 2017 | | | YYYYY | | ... | | ISO week-numbering year | R | | -43, 0, 1, 1900, 2017 | | | RR | GG | -43, 00, 01, 1900, 2017 | | | RRR | | -043, 000, 001, 1900, 2017 | | | RRRR | GGGG | -0043, 0000, 0001, 1900, 2017 | | | RRRRR | | ... | | Extended year | u | | -43, 0, 1, 1900, 2017 | | | uu | | -43, 01, 1900, 2017 | | | uuu | | -043, 001, 1900, 2017 | | | uuuu | | -0043, 0001, 1900, 2017 | | | uuuuu | | ... | | Quarter (formatting) | Q | | 1, 2, 3, 4 | | | Qo | | 1st, 2nd, 3rd, 4th | | | QQ | | 01, 02, 03, 04 | | | QQQ | | Q1, Q2, Q3, Q4 | | | QQQQ | | 1st quarter, 2nd quarter, ... | | | QQQQQ | | 1, 2, 3, 4 | | Quarter (stand-alone) | q | Q | 1, 2, 3, 4 | | | qo | Qo | 1st, 2nd, 3rd, 4th | | | qq | | 01, 02, 03, 04 | | | qqq | | Q1, Q2, Q3, Q4 | | | qqqq | | 1st quarter, 2nd quarter, ... | | | qqqqq | | 1, 2, 3, 4 | | Month (formatting) | M | | 1, 2, ..., 12 | | | Mo | | 1st, 2nd, ..., 12th | | | MM | | 01, 02, ..., 12 | | | MMM | | Jan, Feb, ..., Dec | | | MMMM | | January, February, ..., December | | | MMMMM | | J, F, ..., D | | Month (stand-alone) | L | M | 1, 2, ..., 12 | | | Lo | | 1st, 2nd, ..., 12th | | | LL | MM | 01, 02, ..., 12 | | | LLL | MMM | Jan, Feb, ..., Dec | | | LLLL | MMMM | January, February, ..., December | | | LLLLL | | J, F, ..., D | | Local week of year | w | | 1, 2, ..., 53 | | | wo | | 1st, 2nd, ..., 53th | | | ww | | 01, 02, ..., 53 | | ISO week of year | I | W | 1, 2, ..., 53 | | | Io | Wo | 1st, 2nd, ..., 53th | | | II | WW | 01, 02, ..., 53 | | Day of month | d | D | 1, 2, ..., 31 | | | do | Do | 1st, 2nd, ..., 31st | | | dd | DD | 01, 02, ..., 31 | | Day of year | D | DDD | 1, 2, ..., 365, 366 | | | Do | DDDo | 1st, 2nd, ..., 365th, 366th | | | DD | | 01, 02, ..., 365, 366 | | | DDD | DDDD | 001, 002, ..., 365, 366 | | | DDDD | | ... | | Day of week (formatting) | E..EEE | | Mon, Tue, Wed, ..., Su | | | EEEE | | Monday, Tuesday, ..., Sunday | | | EEEEE | | M, T, W, T, F, S, S | | | EEEEEE | | Mo, Tu, We, Th, Fr, Sa, Su | | ISO day of week (formatting) | i | E | 1, 2, 3, ..., 7 | | | io | do | 1st, 2nd, ..., 7th | | | ii | | 01, 02, ..., 07 | | | iii | ddd | Mon, Tue, Wed, ..., Su | | | iiii | dddd | Monday, Tuesday, ..., Sunday | | | iiiii | | M, T, W, T, F, S, S | | | iiiiii | dd | Mo, Tu, We, Th, Fr, Sa, Su | | Local day of week (formatting) | e | | 2, 3, 4, ..., 1 | | | eo | | 2nd, 3rd, ..., 1st | | | ee | | 02, 03, ..., 01 | | | eee | | Mon, Tue, Wed, ..., Su | | | eeee | | Monday, Tuesday, ..., Sunday | | | eeeee | | M, T, W, T, F, S, S | | | eeeeee | | Mo, Tu, We, Th, Fr, Sa, Su | | Local day of week (stand-alone) | c | | 2, 3, 4, ..., 1 | | | co | | 2nd, 3rd, ..., 1st | | | cc | | 02, 03, ..., 01 | | | ccc | | Mon, Tue, Wed, ..., Su | | | cccc | | Monday, Tuesday, ..., Sunday | | | ccccc | | M, T, W, T, F, S, S | | | cccccc | | Mo, Tu, We, Th, Fr, Sa, Su | | AM, PM | a..aaa | A | AM, PM | | | aaaa | aa | a.m., p.m. | | | aaaaa | | a, p | | AM, PM, noon, midnight | b..bbb | | AM, PM, noon, midnight | | | bbbb | | a.m., p.m., noon, midnight | | | bbbbb | | a, p, n, mi | | Flexible day period | B..BBB | | at night, in the morning, ... | | | BBBB | | at night, in the morning, ... | | | BBBBB | | at night, in the morning, ... | | Hour [1-12] | h | | 1, 2, ..., 11, 12 | | | ho | | 1st, 2nd, ..., 11th, 12th | | | hh | | 01, 02, ..., 11, 12 | | Hour [0-23] | H | | 0, 1, 2, ..., 23 | | | Ho | | 0th, 1st, 2nd, ..., 23rd | | | HH | | 00, 01, 02, ..., 23 | | Hour [0-11] | K | | 1, 2, ..., 11, 0 | | | Ko | | 1st, 2nd, ..., 11th, 0th | | | KK | | 1, 2, ..., 11, 0 | | Hour [1-24] | k | | 24, 1, 2, ..., 23 | | | ko | | 24th, 1st, 2nd, ..., 23rd | | | kk | | 24, 01, 02, ..., 23 | | Minute | m | | 0, 1, ..., 59 | | | mo | | 0th, 1st, ..., 59th | | | mm | | 00, 01, ..., 59 | | Second | s | | 0, 1, ..., 59 | | | so | | 0th, 1st, ..., 59th | | | ss | | 00, 01, ..., 59 | | Fraction of second | S | | 0, 1, ..., 9 | | | SS | | 00, 01, ..., 99 | | | SSS | | 000, 0001, ..., 999 | | | SSSS | | ... | | Timezone (ISO-8601 w/ Z) | X | | -08, +0530, Z | | | XX | | -0800, +0530, Z | | | XXX | | -08:00, +05:30, Z | | | XXXX | | -0800, +0530, Z, +123456 | | | XXXXX | | -08:00, +05:30, Z, +12:34:56 | | Timezone (ISO-8601 w/o Z) | x | | -08, +0530, +00 | | | xx | ZZ | -0800, +0530, +0000 | | | xxx | Z | -08:00, +05:30, +00:00 | | | xxxx | | -0800, +0530, +0000, +123456 | | | xxxxx | | -08:00, +05:30, +00:00, +12:34:56 | | Timezone (GMT) | O...OOO | | GMT-8, GMT+5:30, GMT+0 | | | OOOO | | GMT-08:00, GMT+05:30, GMT+00:00 | | Timezone (specific non-locat.) | z...zzz | | GMT-8, GMT+5:30, GMT+0 | | | zzzz | | GMT-08:00, GMT+05:30, GMT+00:00 | | Seconds timestamp | t | X | 512969520 | | | tt | | ... | | Milliseconds timestamp | T | x | 512969520900 | | | TT | | ... | | Long localized date | P | | 5/29/53 | | | PP | | May 29, 1453 | | | PPP | | May 29th, 1453 | | | PPPP | | Sunday, May 29th, 1453 | | Long localized time | p | | 12:00 AM | | | pp | | 12:00:00 AM | | | ppp | | 12:00:00 AM GMT+2 | | | pppp | | 12:00:00 AM GMT+02:00 | | Combination of date and time | Pp | | 5/29/53, 12:00 AM | | | PPpp | | May 29, 1453, 12:00 AM | | | PPPppp | | May 29th, 1453 at ... | | | PPPPpppp | | Sunday, May 29th, 1453 at ... |
Characters are now escaped using single quote symbols (') instead of square brackets.
format now throws RangeError if it encounters an unescaped latin character
that isn't a valid formatting token.
To use YY and YYYY tokens that represent week-numbering years,
you should set useAdditionalWeekYearTokens option:
javascript
format(Date.now(), 'YY', { useAdditionalWeekYearTokens: true })
//=> '86'
To use D and DD tokens which represent days of the year,
set useAdditionalDayOfYearTokens option:
javascript
format(Date.now(), 'D', { useAdditionalDayOfYearTokens: true })
//=> '364'
```javascript // Before v2.0.0 import differenceInCalendarISOYears from 'date-fns/difference_in_calendar_iso_years'
// v2.0.0 onward import differenceInCalendarISOYears from 'date-fns/differenceInCalendarISOYears' ```
```javascript // Before v2.0.0 var date1 = new Date(1989, 6 / Jul /, 10) var date2 = new Date(1987, 1 / Feb /, 11)
var minDate = min(date1, date2) var maxDate = max(date1, date2)
// v2.0.0 onward: var dates = [new Date(1989, 6 / Jul /, 10), new Date(1987, 1 / Feb /, 11)]
var minDate = min(dates) var maxDate = max(dates) ```
format required for the sake of explicitness.```javascript // Before v2.0.0 format(new Date(2016, 0, 1))
// v2.0.0 onward format(new Date(2016, 0, 1), "yyyy-MM-dd'T'HH:mm:ss.SSSxxx") ```
BREAKING renamed ISO week-numbering year helpers:
addISOYears → addISOWeekYears
differenceInCalendarISOYears → differenceInCalendarISOWeekYearsdifferenceInISOYears → differenceInISOWeekYearsendOfISOYear → endOfISOWeekYeargetISOYear → getISOWeekYearisSameISOYear → isSameISOWeekYearlastDayOfISOYear → lastDayOfISOWeekYearsetISOYear → setISOWeekYearsubISOYears → subISOWeekYearsi.e. "ISO year" renamed to "ISO week year", which is short for
ISO week-numbering year.
It makes them consistent with locale-dependent week-numbering year helpers,
e.g., startOfWeekYear.
BREAKING: functions renamed:
areRangesOverlapping → areIntervalsOverlapping
eachDay → eachDayOfIntervalgetOverlappingDaysInRanges → getOverlappingDaysInIntervalsisWithinRange → isWithinIntervalThis change was made to mirror the use of the word "interval" in standard ISO 8601:2004 terminology:
2.1.3
time interval
part of the time axis limited by two instants
Also these functions now accept an object with start and end properties
instead of two arguments as an interval. All these functions
throw RangeError if the start of the interval is after its end
or if any date in the interval is Invalid Date.
```javascript // Before v2.0.0
areRangesOverlapping( new Date(2014, 0, 10), new Date(2014, 0, 20), new Date(2014, 0, 17), new Date(2014, 0, 21) )
eachDay(new Date(2014, 0, 10), new Date(2014, 0, 20))
getOverlappingDaysInRanges( new Date(2014, 0, 10), new Date(2014, 0, 20), new Date(2014, 0, 17), new Date(2014, 0, 21) )
isWithinRange( new Date(2014, 0, 3), new Date(2014, 0, 1), new Date(2014, 0, 7) )
// v2.0.0 onward
areIntervalsOverlapping( { start: new Date(2014, 0, 10), end: new Date(2014, 0, 20) }, { start: new Date(2014, 0, 17), end: new Date(2014, 0, 21) } )
eachDayOfInterval({ start: new Date(2014, 0, 10), end: new Date(2014, 0, 20), })
getOverlappingDaysInIntervals( { start: new Date(2014, 0, 10), end: new Date(2014, 0, 20) }, { start: new Date(2014, 0, 17), end: new Date(2014, 0, 21) } )
isWithinInterval(new Date(2014, 0, 3), { start: new Date(2014, 0, 1), end: new Date(2014, 0, 7), }) ```
BREAKING: functions renamed:
distanceInWords → formatDistance
distanceInWordsStrict → formatDistanceStrictdistanceInWordsToNow → formatDistanceToNowto make them consistent with format and formatRelative.
distanceInWords and distanceInWordsStrict
is swapped to make them consistent with differenceIn... functions.```javascript // Before v2.0.0
distanceInWords( new Date(1986, 3, 4, 10, 32, 0), new Date(1986, 3, 4, 11, 32, 0), { addSuffix: true } ) //=> 'in about 1 hour'
// v2.0.0 onward
formatDistance( new Date(1986, 3, 4, 11, 32, 0), new Date(1986, 3, 4, 10, 32, 0), { addSuffix: true } ) //=> 'in about 1 hour' ```
partialMethod option in formatDistanceStrict is renamed to roundingMethod.```javascript // Before v2.0.0
distanceInWordsStrict( new Date(1986, 3, 4, 10, 32, 0), new Date(1986, 3, 4, 10, 33, 1), { partialMethod: 'ceil' } ) //=> '2 minutes'
// v2.0.0 onward
formatDistanceStrict( new Date(1986, 3, 4, 10, 33, 1), new Date(1986, 3, 4, 10, 32, 0), { roundingMethod: 'ceil' } ) //=> '2 minutes' ```
BREAKING: in formatDistanceStrict, if roundingMethod is not specified,
it now defaults to round instead of floor.
BREAKING: unit option in formatDistanceStrict now accepts one of the strings:
'second', 'minute', 'hour', 'day', 'month' or 'year' instead of 's', 'm', 'h', 'd', 'M' or 'Y'
```javascript // Before v2.0.0
distanceInWordsStrict( new Date(1986, 3, 4, 10, 32, 0), new Date(1986, 3, 4, 10, 33, 1), { unit: 'm' } )
// v2.0.0 onward
formatDistanceStrict( new Date(1986, 3, 4, 10, 33, 1), new Date(1986, 3, 4, 10, 32, 0), { unit: 'minute' } ) ```
parse that previously used to convert strings and
numbers to dates now parses only strings in an arbitrary format
specified as an argument. Use toDate to coerce numbers and parseISO
to parse ISO 8601 strings.```javascript // Before v2.0.0 parse('2016-01-01') parse(1547005581366) parse(new Date()) // Clone the date
// v2.0.0 onward parse('2016-01-01', 'yyyy-MM-dd', new Date()) parseISO('2016-01-01') toDate(1547005581366) toDate(new Date()) // Clone the date ```
BREAKING: toDate (previously parse) now doesn't accept string
arguments but only numbers and dates. toDate called with an invalid
argument will return Invalid Date.
BREAKING: new locale format. See docs/Locale. Locales renamed:
en → en-US
zh_cn → zh-CNzh_tw → zh-TW```javascript // Before v2.0.0 import locale from 'date-fns/locale/zh_cn'
// v2.0.0 onward import locale from 'date-fns/locale/zh-CN' ```
BREAKING: now closestTo and closestIndexTo don't throw an exception
when the second argument is not an array, and return Invalid Date instead.
BREAKING: now isValid doesn't throw an exception
if the first argument is not an instance of Date.
Instead, argument is converted beforehand using toDate.
Examples:
| isValid argument | Before v2.0.0 | v2.0.0 onward |
| ------------------------- | ------------- | ------------- |
| new Date() | true | true |
| new Date('2016-01-01') | true | true |
| new Date('') | false | false |
| new Date(1488370835081) | true | true |
| new Date(NaN) | false | false |
| '2016-01-01' | TypeError | false |
| '' | TypeError | false |
| 1488370835081 | TypeError | true |
| NaN | TypeError | false |
We introduce this change to make date-fns consistent with ECMAScript behavior that try to coerce arguments to the expected type (which is also the case with other date-fns functions).
BREAKING: functions now throw RangeError if optional values passed to options
are not undefined or have expected values.
This change is introduced for consistency with ECMAScript standard library which does the same.
BREAKING: format, formatDistance (previously distanceInWords) and
formatDistanceStrict (previously distanceInWordsStrict) now throw
RangeError if one of the passed arguments is invalid. It reflects behavior of
toISOString and Intl API. See #1032.
BREAKING: all functions now implicitly convert arguments by following rules:
| | date | number | string | boolean | | --------- | ------------ | ------ | ----------- | ------- | | 0 | new Date(0) | 0 | '0' | false | | '0' | Invalid Date | 0 | '0' | false | | 1 | new Date(1) | 1 | '1' | true | | '1' | Invalid Date | 1 | '1' | true | | true | Invalid Date | NaN | 'true' | true | | false | Invalid Date | NaN | 'false' | false | | null | Invalid Date | NaN | 'null' | false | | undefined | Invalid Date | NaN | 'undefined' | false | | NaN | Invalid Date | NaN | 'NaN' | false |
Notes:
Date are converted to Date using date-fns' toDate function;toInteger implementation
(see #765);String function;Boolean function.null and undefined passed to optional arguments (i.e. properties of options argument)
are ignored as if no argument was passed.
If any resulting argument is invalid (i.e. NaN for numbers and Invalid Date for dates),
an invalid value will be returned:
false for functions that return booleans (expect isValid);Invalid Date for functions that return dates;NaN for functions that return numbers.See tests and PRs #460 and #765 for exact behavior.
BREAKING: all functions now check if the passed number of arguments is less
than the number of required arguments and will throw TypeError exception if so.
BREAKING: all functions that accept numbers as arguments, now coerce
values using Number() and also round off decimals. Positive decimals are
rounded using Math.floor, decimals less than zero are rounded using
Math.ceil.
BREAKING: The Bower & UMD/CDN package versions are no longer supported.
BREAKING: null now is not a valid date. isValid(null) returns false;
toDate(null) returns an invalid date. Since toDate is used internally
by all the functions, operations over null will also return an invalid date.
See #537 for the reasoning.
toDate (previously parse) and isValid functions now accept any type
as the first argument.
Exclude docs.json from the npm package. Kudos to @hawkrives.
Functions with options (format, parse, etc.) have two FP counterparts:
one that has the options object as its first argument and one that hasn't.
The name of the former has WithOptions added to the end of its name.
In FP functions, the order of arguments is reversed.
See FP Guide for more information.
```javascript import addYears from 'date-fns/fp/addYears' import formatWithOptions from 'date-fns/fp/formatWithOptions' import eo from 'date-fns/locale/eo'
// If FP function has not received enough arguments, it returns another function const addFiveYears = addYears(5)
// Several arguments can be curried at once const dateToString = formatWithOptions({ locale: eo }, 'd MMMM yyyy')
const dates = [ new Date(2017, 0 / Jan /, 1), new Date(2017, 1 / Feb /, 11), new Date(2017, 6 / Jul /, 2), ]
const formattedDates = dates.map((date) => dateToString(addFiveYears(date))) //=> ['1 januaro 2022', '11 februaro 2022', '2 julio 2022'] ```
It allows usage with bundlers that support tree-shaking, like rollup.js and webpack:
```javascript // Without tree-shaking: import format from 'date-fns/format' import parse from 'date-fns/parse'
// With tree-shaking: import { format, parse } from 'date-fns' ```
Also, ESM functions provide default export, they can be used with TypeScript to import functions in more idiomatic way:
```typescript // Before import * as format from 'date-fns/format'
// Now import format from 'date-fns/format' ```
formatRelative function. See formatRelative
Flow typings for index.js, fp/index.js, locale/index.js, and their ESM equivalents.
See PR #558
New locale-dependent week-numbering year helpers:
getWeek
getWeekYear
setWeek
setWeekYear
startOfWeekYear
Added eachWeekOfInterval, the weekly equivalent of eachDayOfInterval
Added getUnixTime function. Kudos to @Kingwl.
New decade helpers. Thanks to @y-nk!
getDecade
startOfDecade
endOfDecade
lastDayOfDecade
New roundToNearestMinutes function. Kudos to @xkizer.
Added new function fromUnixTime. Thansk to @xkizer.
New interval, month, and year helpers to fetch a list of all Saturdays and Sundays (weekends) for a given date interval. eachWeekendOfInterval is the handler function while the other two are wrapper functions. Kudos to @laekettavong!
eachWeekendOfInterval
eachWeekendOfMonth
eachWeekendOfYear
Build-efficient lightFormat that only supports the popular subset of tokens. See #1050.
parseISO function that parses ISO 8601 strings. See #1023.
Add constants that can be imported directly from date-fns or the submodule date-fns/constants:
maxTime
minTime
New locales:
Hungarian (hu) and Lithuanian (lt) locales by @izifortune and pardoeryanair.
Added new function differenceInBusinessDays
which calculates the difference in business days. Kudos to @ThorrStevens!
Added new function addBusinessDays,
similar to addDays but ignoring weekends. Thanks to @ThorrStevens!
Fixed DST issue. See #972 and #992 for more details. This fix was backported from v2.
Fix a few bugs that appear in timezones with offsets that include seconds (e.g. GMT+00:57:44). See PR #789. This fix was backported from v2.
Fixed misspelled January in the Thai locale. Thanks to @ratchapol-an!
Added Serbian locale. Kudos to @mawi12345!
Added Belarusian locale. Kudos to @mawi12345 again!
⚠️ The release got failed.
formatDistance. (see the issue: #550; see the PR: #552)
Thanks to @giofilo!Hungarian locale (hu) (thanks to László Horváth @horvathlg)
Slovenian locale (sl) (thanks to Adam Stradovnik @Neoglyph)
Added step to eachDay function. Thanks to @BDav24.
See PR #487.
Fixed accents on weekdays in the Italian locale. See PR #481. Thanks to @albertorestifo
Fixed typo in ddd format token in Spanish language locale.
Kudos to @fjaguero.
See PR #482
Fixed DST border bug in addMilliseconds, addSeconds, addMinutes, addHours,
subMilliseconds, subSeconds, subMinutes and subHours.
See issue #465
Minor fix for Indonesian locale. Thanks to @bentinata. See PR: #458
All functions now convert all their arguments to the respective types. See PR: #443
Fixes for ordinals (1er, 2, 3, …) in French locale. Thanks to @fbonzon. See PR: #449
getTimeBulgarian locale (bg) (thanks to Nikolay Stoynov @arvigeus)
Czech locale (cs) (thanks to David Rus @davidrus)
Auto generate TypeScript and flow typings from documentation on release. Thanks to @mattlewis92. See related PRs: #355, #370
Croatian locale (hr) (thanks to Matija Marohnić @silvenon)
Thai locale (th) (thanks to Athiwat Hirunworawongkun @athivvat)
Finnish locale (fi) (thanks to Pyry-Samuli Lahti @Pyppe)
isBefore and isAfter documentation mistakes.Filipino locale (fil) (thanks to Ian De La Cruz @RIanDeLaCruz)
Danish locale (da) (kudos to Anders B. Hansen @Andersbiha)
getOverlappingDaysInRanges.Greek locale (el) (kudos to Theodoros Orfanidis @teoulas)
Slovak locale (sk) (kudos to Marek Suscak @mareksuscak)
Added yarn support. Thanks to Uladzimir Havenchyk @havenchyk. See PR: #288
Turkish locale (tr) (kudos to Alpcan Aydın @alpcanaydin)
Korean locale (ko) (thanks to Hong Chulju @angdev)
SS and SSS formats in format are now correctly displayed with leading zeros.
Thanks to Paul Dijou @pauldijou.
See PR: #330Polish locale (pl) (thanks to Mateusz Derks @ertrzyiks)
Portuguese locale (pt) (thanks to Dário Freire @dfreire)
Swedish locale (sv) (thanks to Johannes Ulén @ejulen)
French locale (fr) (thanks to Jean Dupouy @izeau)
Performance tests. See PR: #289
Fixed TypeScript and flow typings for isValid.
See PR: #310
Fixed incorrect locale tests that could potentially lead to format bugs.
Kudos to Mateusz Derks @ertrzyiks.
See related PRs: #312,
#320
Minor language fixes in the documentation. Thanks to Vedad Šoše @vedadsose (#314) and Asia @asia-t (#318)
format now returns String('Invalid Date') if the passed date is invalid.
See PR: #323
distanceInWords, distanceInWordsToNow, distanceInWordsStrict and format functions now
check if the passed locale is valid, and fallback to English locale otherwise.
See PR: #321
Internal: use a loop instead of Object.keys in buildFormattingTokensRegExp
to improve compatibility with older browsers.
See PR: #322
Italian locale (it) (thanks to Alberto Restifo @albertorestifo)
For German buildDistanceInWordsLocale, add nominative case translations (for distances without a suffix).
Kudos to Asia @asia-t.
See related PR: #295
Indonesian locale (id) (thanks to Rahmat Budiharso @rbudiharso)
Catalan locale (ca) (thanks to Guillermo Grau @guigrpa)
Chinese Traditional locale (zh_tw) (thanks to tonypai @tpai).
Dutch language locale (nl) (kudos to Jorik Tangelder @jtangelder)
distanceInWordsStrict to the list of supported functions in I18n doc.Bug in parse when it sometimes parses ISO week-numbering dates incorrectly.
See PR: #262
Bug in some functions which caused them to handle dates earlier than 100 AD incorrectly. See PR: #263
distanceInWordsStrict.
Kudos to @STRML.
See related PR: #254
TypeScript typings for all functions. Kudos to @mattlewis92. See related PR: #255
parse now can parse dates that are ISO 8601 centuries (e.g., 19 and +0019).javascript
var result = parse('19')
//=> Mon Jan 01 1900 00:00:00
parse, added ability to specify the number of additional digits
for extended year or century format (possible values are 0, 1 or 2; default is 2).javascript
parse('+002016-11-01')
parse('+02016-11-01', { additionalDigits: 1 })
parse('+2016-11-01', { additionalDigits: 0 })
Japanese language locale (ja) (thanks to Thomas Eilmsteiner @DeMuu again!)
getISODay
setISODay
Incorrectly generated docs for format.
Fixed typo in I18n doc.
YYYY and YY for years prior to 1000:
now format(new Date('0001-01-01'), 'YYYY-MM-DD') returns 0001-01-01
instead of 1-01-01.closestIndexTosetDay.Flow declarations for each function in the ".js.flow" style. Kudos to @JohnyDays. See related PRs:
format now returns the correct result for key E.
Prevent startOf..., endOf... and lastDayOf... functions
to return dates with an incorrect time when the date is modifying
into another time zone.
parse now parses years from 1 AD to 99 AD correctly.
Fix a bug in getISOWeek appearing because of a changing time zone
(e.g., when the given date is in DST and the start of the ISO year is not).
require('date-fns/name_of_function') or
import nameOfFunction from 'date-fns/name_of_function'.```javascript // Before v1.0.0 var addMonths = require('date-fns/src/add_months')
// v1.0.0 onward var addMonths = require('date-fns/add_months') ```
weekStartsAt
(i.e. endOfWeek, isSameWeek, lastDayOfWeek, setDay, startOfWeek)
now instead receive the object options with the property options.weekStartsOn
as the last argument.```javascript // Before v1.0.0 var result = endOfWeek(new Date(2014, 8, 2), 1)
// v1.0.0 onward var result = endOfWeek(new Date(2014, 8, 2), { weekStartsOn: 1 }) ```
BREAKING: remove the function getTimeSinceMidnight that was used inside
the other functions.
BREAKING: differenceInDays now returns the number of full days instead
of calendar days.
BREAKING: eachDay and isWithinRange now throw an exception
when the given range boundaries are invalid.
Faster isLeapYear.
Internal: make the documentation more verbose.
Internal: convert the tests from Chai to power-assert allowing them to run against IE8.
addISOYears
closestTo
differenceInCalendarDays
differenceInCalendarISOWeeks
differenceInCalendarISOYears
differenceInCalendarMonths
differenceInCalendarQuarters
differenceInCalendarWeeks
differenceInCalendarYears
differenceInHours
differenceInISOYears
differenceInMilliseconds
differenceInMinutes
differenceInMonths
differenceInQuarters
differenceInSeconds
differenceInWeeks
differenceInYears
distanceInWords
distanceInWordsToNow
endOfISOWeek
endOfISOYear
endOfToday
endOfTomorrow
endOfYesterday
getDaysInYear
isDate
isFriday
isMonday
isSameISOWeek
isSameISOYear
isSaturday
isSunday
isThisHour
isThisISOWeek
isThisISOYear
isThisMinute
isThisMonth
isThisQuarter
isThisSecond
isThisWeek
isThisYear
isThursday
isTomorrow
isTuesday
isValid
isWednesday
isYesterday
lastDayOfISOWeek
lastDayOfISOYear
startOfISOWeek
startOfToday
startOfTomorrow
startOfYesterday
subISOYears
Add Qo, W, Wo, WW, GG, GGGG, Z, ZZ, X, x keys to format.
Fixed a lot of bugs appearing when date is modifying into other time zone (e.g., when adding months and original date is in DST but new date is not).
Prevent instances of Date to lose milliseconds value when passed to.
parse in IE10.
setISOWeek now keeps time from original date.
Internal: reuse getDaysInMonth inside of addMonths.
differenceInDays
getTimeSinceMidnight
format now has new format key aa, which returns a.m./p.m.
as opposed to a that returns am/pm.
Complete UMD package (for Bower and CDN).
Use parse to clean date arguments in all functions.
parse now fallbacks to new Date when the argument
is not an ISO formatted date.
Internal: reuse getDaysInMonth inside of setMonth.
addQuarters
addWeeks
endOfQuarter
getDate
getDay
getDaysInMonth
getHours
getISOWeeksInYear
getMilliseconds
getMinutes
getMonth
getSeconds
getYear
isLeapYear
isSameHour
isSameMinute
isSameQuarter
isSameSecond
lastDayOfQuarter
lastDayOfWeek
max
min
setDate
setDay
setHours
setMilliseconds
setMinutes
setSeconds
startOfQuarter
subQuarters
subWeeks
format now returns a.m./p.m. instead of am/pm.
setMonth now sets last day of month if original date was last day
of longer month.
Internal: Fix code style according to ESLint.
Internal: Make tests run through all time zones.
getQuarter
setQuarter
getDayOfYear
setDayOfYear
isPast
addSeconds
subSeconds
startOfSecond
endOfSecond
startOfMinute
endOfMinute
addMilliseconds
subMilliseconds
endOfYear
addYears
subYears
lastDayOfYear
lastDayOfMonth
format now uses parse to avoid time zone bugs.setIsoWeek now sets time to the start of the day.format now behaves correctly with 12:00 am.
format now behaves correctly with ordinal numbers.
compareAsc
compareDesc
addHours
subHours
isSameDay
parse
getISOYear
setISOYear
startOfISOYear
getISOWeek
setISOWeek
addMonths now correctly behaves with February
(see #18).format function now behaves correctly with pm/am.addMinutes
subMinutes
isEqual
isBefore
isAfter
DDD formatter.isSameYearisWithinRangeformat
startOfYear
isWeekendisFutureaddDays inside of subDays.addMonths
subMonths
setMonth
setYear
isSameWeekendOfMonth.isFirstDayOfMonth
isLastDayOfMonth
isSameMonth
addDays
subDays
startOfWeek
endOfWeek
eachDay
startOfDay now sets milliseconds as well.endOfDay
startOfMonth
endOfMonth
isToday
isWeekend
startOfDay