Refactor/throw messages

CHANGELOG.md

@@ -14,6 +14,7 @@ This change log follows the format documented in [Keep a CHANGELOG].
 
 - [Added `weeks` to `Duration`](https://github.com/date-fns/date-fns/pull/1592).
 - [Added `weeks` support to `add` and `sub`](https://github.com/date-fns/date-fns/pull/1592).
+- [Added details message in `throwProtectedError`](https://github.com/date-fns/date-fns/pull/1592).
 
 ## [2.9.0] - 2020-01-08
 

src/_lib/protectedTokens/index.js

@@ -9,22 +9,22 @@ export function isProtectedWeekYearToken(token) {
   return protectedWeekYearTokens.indexOf(token) !== -1
 }
 
-export function throwProtectedError(token) {
+export function throwProtectedError(token, format, input) {
   if (token === 'YYYY') {
     throw new RangeError(
-      'Use `yyyy` instead of `YYYY` for formatting years; see: https://git.io/fxCyr'
+      `Use \`yyyy\` instead of \`YYYY\` (in \`${format}\`) for formatting years to the input \`${input}\`; see: https://git.io/fxCyr`
     )
   } else if (token === 'YY') {
     throw new RangeError(
-      'Use `yy` instead of `YY` for formatting years; see: https://git.io/fxCyr'
+      `Use \`yy\` instead of \`YY\` (in \`${format}\`) for formatting years to the input \`${input}\`; see: https://git.io/fxCyr`
     )
   } else if (token === 'D') {
     throw new RangeError(
-      'Use `d` instead of `D` for formatting days of the month; see: https://git.io/fxCyr'
+      `Use \`d\` instead of \`D\` (in \`${format}\`) for formatting days of the month to the input \`${input}\`; see: https://git.io/fxCyr`
     )
   } else if (token === 'DD') {
     throw new RangeError(
-      'Use `dd` instead of `DD` for formatting days of the month; see: https://git.io/fxCyr'
+      `Use \`dd\` instead of \`DD\` (in \`${format}\`) for formatting days of the month to the input \`${input}\`; see: https://git.io/fxCyr`
     )
   }
 }

src/format/index.js

@@ -319,10 +319,10 @@ var unescapedLatinCharacterRegExp = /[a-zA-Z]/
  * @throws {RangeError} `options.locale` must contain `formatLong` property
  * @throws {RangeError} `options.weekStartsOn` must be between 0 and 6
  * @throws {RangeError} `options.firstWeekContainsDate` must be between 1 and 7
- * @throws {RangeError} use `yyyy` instead of `YYYY` for formatting years; see: https://git.io/fxCyr
- * @throws {RangeError} use `yy` instead of `YY` for formatting years; see: https://git.io/fxCyr
- * @throws {RangeError} use `d` instead of `D` for formatting days of the month; see: https://git.io/fxCyr
- * @throws {RangeError} use `dd` instead of `DD` for formatting days of the month; see: https://git.io/fxCyr
+ * @throws {RangeError} use `yyyy` instead of `YYYY` for formatting years using [format provided] to the input [input provided]; see: https://git.io/fxCyr
+ * @throws {RangeError} use `yy` instead of `YY` for formatting years using [format provided] to the input [input provided]; see: https://git.io/fxCyr
+ * @throws {RangeError} use `d` instead of `D` for formatting days of the month using [format provided] to the input [input provided]; see: https://git.io/fxCyr
+ * @throws {RangeError} use `dd` instead of `DD` for formatting days of the month using [format provided] to the input [input provided]; see: https://git.io/fxCyr
  * @throws {RangeError} format string contains an unescaped latin alphabet character
  *
  * @example
@@ -438,13 +438,13 @@ export default function format(dirtyDate, dirtyFormatStr, dirtyOptions) {
           !options.useAdditionalWeekYearTokens &&
           isProtectedWeekYearToken(substring)
         ) {
-          throwProtectedError(substring)
+          throwProtectedError(substring, dirtyFormatStr, dirtyDate)
         }
         if (
           !options.useAdditionalDayOfYearTokens &&
           isProtectedDayOfYearToken(substring)
         ) {
-          throwProtectedError(substring)
+          throwProtectedError(substring, dirtyFormatStr, dirtyDate)
         }
         return formatter(utcDate, substring, locale.localize, formatterOptions)
       }

src/format/test.js

@@ -743,7 +743,7 @@ describe('format', function() {
       assert.throws(block, RangeError)
       assert.throws(
         block,
-        /Use `d` instead of `D` for formatting days of the month; see: https:\/\/git.io\/fxCyr/
+        /(Use `d` instead of `D` \(in `yyyy-MM-D`\) for formatting days of the month to the input `Fri Apr 04 1986 10:32:55).*(`; see: https:\/\/git.io\/fxCyr)/g
       )
     })
 
@@ -759,7 +759,7 @@ describe('format', function() {
       assert.throws(block, RangeError)
       assert.throws(
         block,
-        /Use `dd` instead of `DD` for formatting days of the month; see: https:\/\/git.io\/fxCyr/
+        /(Use `dd` instead of `DD` \(in `yyyy-MM-DD`\) for formatting days of the month to the input `Fri Apr 04 1986 10:32:55).*(`; see: https:\/\/git.io\/fxCyr)/g
       )
     })
 
@@ -775,7 +775,7 @@ describe('format', function() {
       assert.throws(block, RangeError)
       assert.throws(
         block,
-        /Use `yy` instead of `YY` for formatting years; see: https:\/\/git.io\/fxCyr/
+        /(Use `yy` instead of `YY` \(in `YY-MM-dd`\) for formatting years to the input `Fri Apr 04 1986 10:32:55).*(`; see: https:\/\/git.io\/fxCyr)/g
       )
     })
 
@@ -791,7 +791,7 @@ describe('format', function() {
       assert.throws(block, RangeError)
       assert.throws(
         block,
-        /Use `yyyy` instead of `YYYY` for formatting years; see: https:\/\/git.io\/fxCyr/
+        /(Use `yyyy` instead of `YYYY` \(in `YYYY-MM-dd`\) for formatting years to the input `Fri Apr 04 1986 10:32:55).*(`; see: https:\/\/git.io\/fxCyr)/g
       )
     })
 

src/index.js.flow

@@ -539,7 +539,7 @@ declare module.exports: {
   parse: (
     dateString: string,
     formatString: string,
-    backupDate: Date | number,
+    referenceDate: Date | number,
     options?: {
       locale?: Locale,
       weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6,

src/parse/index.js

@@ -336,10 +336,10 @@ var unescapedLatinCharacterRegExp = /[a-zA-Z]/
  * @throws {RangeError} `options.weekStartsOn` must be between 0 and 6
  * @throws {RangeError} `options.firstWeekContainsDate` must be between 1 and 7
  * @throws {RangeError} `options.locale` must contain `match` property
- * @throws {RangeError} use `yyyy` instead of `YYYY` for formatting years; see: https://git.io/fxCyr
- * @throws {RangeError} use `yy` instead of `YY` for formatting years; see: https://git.io/fxCyr
- * @throws {RangeError} use `d` instead of `D` for formatting days of the month; see: https://git.io/fxCyr
- * @throws {RangeError} use `dd` instead of `DD` for formatting days of the month; see: https://git.io/fxCyr
+ * @throws {RangeError} use `yyyy` instead of `YYYY` for formatting years using [format provided] to the input [input provided]; see: https://git.io/fxCyr
+ * @throws {RangeError} use `yy` instead of `YY` for formatting years using [format provided] to the input [input provided]; see: https://git.io/fxCyr
+ * @throws {RangeError} use `d` instead of `D` for formatting days of the month using [format provided] to the input [input provided]; see: https://git.io/fxCyr
+ * @throws {RangeError} use `dd` instead of `DD` for formatting days of the month using [format provided] to the input [input provided]; see: https://git.io/fxCyr
  * @throws {RangeError} format string contains an unescaped latin alphabet character
  *
  * @example
@@ -451,13 +451,13 @@ export default function parse(
       !options.useAdditionalWeekYearTokens &&
       isProtectedWeekYearToken(token)
     ) {
-      throwProtectedError(token)
+      throwProtectedError(token, formatString, dirtyDateString)
     }
     if (
       !options.useAdditionalDayOfYearTokens &&
       isProtectedDayOfYearToken(token)
     ) {
-      throwProtectedError(token)
+      throwProtectedError(token, formatString, dirtyDateString)
     }
 
     var firstCharacter = token[0]

src/parse/test.js

@@ -1067,7 +1067,9 @@ describe('parse', function() {
     })
 
     it('allows to specify which day is the first day of the week', function() {
-      var result = parse('7th', 'eo', referenceDate, { weekStartsOn: /* Fri */ 5 })
+      var result = parse('7th', 'eo', referenceDate, {
+        weekStartsOn: /* Fri */ 5
+      })
       assert.deepEqual(result, new Date(1986, 3 /* Apr */, 10))
     })
 
@@ -1147,7 +1149,9 @@ describe('parse', function() {
     })
 
     it('allows to specify which day is the first day of the week', function() {
-      var result = parse('7th', 'co', referenceDate, { weekStartsOn: /* Fri */ 5 })
+      var result = parse('7th', 'co', referenceDate, {
+        weekStartsOn: /* Fri */ 5
+      })
       assert.deepEqual(result, new Date(1986, 3 /* Apr */, 10))
     })
 
@@ -2008,7 +2012,11 @@ describe('parse', function() {
     })
 
     it('ISO week-numbering date', function() {
-      var result = parse('2016W474T153005', "RRRR'W'IIi'T'HHmmss", referenceDate)
+      var result = parse(
+        '2016W474T153005',
+        "RRRR'W'IIi'T'HHmmss",
+        referenceDate
+      )
       assert.deepEqual(result, new Date(2016, 10 /* Nov */, 24, 15, 30, 5, 0))
     })
 
@@ -2032,7 +2040,11 @@ describe('parse', function() {
     })
 
     it('middle-endian', function() {
-      var result = parse('5 a.m. 07/02/2016', 'h aaaa MM/dd/yyyy', referenceDate)
+      var result = parse(
+        '5 a.m. 07/02/2016',
+        'h aaaa MM/dd/yyyy',
+        referenceDate
+      )
       assert.deepEqual(result, new Date(2016, 6 /* Jul */, 2, 5, 0, 0, 0))
     })
 
@@ -2430,7 +2442,7 @@ describe('parse', function() {
       assert.throws(block, RangeError)
       assert.throws(
         block,
-        /Use `d` instead of `D` for formatting days of the month; see: https:\/\/git.io\/fxCyr/
+        /Use `d` instead of `D` \(in `yyyy D`\) for formatting days of the month to the input `2016 5`; see: https:\/\/git.io\/fxCyr/
       )
     })
 
@@ -2446,7 +2458,7 @@ describe('parse', function() {
       assert.throws(block, RangeError)
       assert.throws(
         block,
-        /Use `dd` instead of `DD` for formatting days of the month; see: https:\/\/git.io\/fxCyr/
+        /Use `dd` instead of `DD` \(in `yyyy DD`\) for formatting days of the month to the input `2016 05`; see: https:\/\/git.io\/fxCyr/
       )
     })
 
@@ -2462,7 +2474,7 @@ describe('parse', function() {
       assert.throws(block, RangeError)
       assert.throws(
         block,
-        /Use `yy` instead of `YY` for formatting years; see: https:\/\/git.io\/fxCyr/
+        /Use `yy` instead of `YY` \(in `YY w`\) for formatting years to the input `16 1`; see: https:\/\/git.io\/fxCyr/
       )
     })
 
@@ -2478,7 +2490,7 @@ describe('parse', function() {
       assert.throws(block, RangeError)
       assert.throws(
         block,
-        /Use `yyyy` instead of `YYYY` for formatting years; see: https:\/\/git.io\/fxCyr/
+        /Use `yyyy` instead of `YYYY` \(in `YYYY w`\) for formatting years to the input `2016 1`; see: https:\/\/git.io\/fxCyr/
       )
     })
 

typings.d.ts

@@ -744,7 +744,7 @@ declare module 'date-fns' {
   function parse(
     dateString: string,
     formatString: string,
-    backupDate: Date | number,
+    referenceDate: Date | number,
     options?: {
       locale?: Locale
       weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6
@@ -8273,7 +8273,7 @@ declare module 'date-fns/esm' {
   function parse(
     dateString: string,
     formatString: string,
-    backupDate: Date | number,
+    referenceDate: Date | number,
     options?: {
       locale?: Locale
       weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6
@@ -18102,7 +18102,7 @@ interface dateFns {
   parse(
     dateString: string,
     formatString: string,
-    backupDate: Date | number,
+    referenceDate: Date | number,
     options?: {
       locale?: Locale
       weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6