1 | # v2 Upgrade Guide
|
2 |
|
3 | ## Common changes
|
4 |
|
5 | ### Camel case naming schema
|
6 |
|
7 | Function submodules now use camelCase naming schema:
|
8 |
|
9 | ```javascript
|
10 | // Before v2.0.0
|
11 | import differenceInCalendarISOYears from 'date-fns/difference_in_calendar_iso_years'
|
12 |
|
13 | // v2.0.0 onward
|
14 | import differenceInCalendarISOYears from 'date-fns/differenceInCalendarISOYears'
|
15 | ```
|
16 |
|
17 | ### New formatting tokens
|
18 |
|
19 | Starting with v2 `format` and `parse` uses [Unicode tokens].
|
20 |
|
21 | See [Unicode Tokens doc](./unicodeTokens.md) for more details.
|
22 |
|
23 | ### String arguments
|
24 |
|
25 | Functions now don't accept strings as arguments. Strings should
|
26 | be parsed using `parseISO` (ISO 8601) or `parse`.
|
27 |
|
28 | See [this post](https://blog.date-fns.org/post/we-cut-date-fns-v2-minimal-build-size-down-to-300-bytes-and-now-its-the-smallest-date-library-18f2nvh2z0yal) for more details.
|
29 |
|
30 | ```javascript
|
31 | // Before v2.0.0
|
32 | addDays('2016-01-01', 1)
|
33 |
|
34 | // v2.0.0 onward
|
35 | addDays(parseISO('2016-01-01'), 1)
|
36 | ```
|
37 |
|
38 | ### Arguments conversion
|
39 |
|
40 | All functions now implicitly convert arguments by following rules:
|
41 |
|
42 | | | date | number | string | boolean |
|
43 | | --------- | ------------ | ------ | ----------- | ------- |
|
44 | | 0 | new Date(0) | 0 | '0' | false |
|
45 | | '0' | Invalid Date | 0 | '0' | false |
|
46 | | 1 | new Date(1) | 1 | '1' | true |
|
47 | | '1' | Invalid Date | 1 | '1' | true |
|
48 | | true | Invalid Date | NaN | 'true' | true |
|
49 | | false | Invalid Date | NaN | 'false' | false |
|
50 | | null | Invalid Date | NaN | 'null' | false |
|
51 | | undefined | Invalid Date | NaN | 'undefined' | false |
|
52 | | NaN | Invalid Date | NaN | 'NaN' | false |
|
53 |
|
54 | Notes:
|
55 |
|
56 | - as before, arguments expected to be `Date` are converted to `Date` using _date-fns'_ `toDate` function;
|
57 | - arguments expected to be numbers are converted to integer numbers using our custom `toInteger` implementation
|
58 | (see [#765](https://github.com/date-fns/date-fns/pull/765));
|
59 | - arguments expected to be strings are converted to strings using JavaScript's `String` function;
|
60 | - arguments expected to be booleans are converted to boolean using JavaScript's `Boolean` function.
|
61 |
|
62 | `null` and `undefined` passed to optional arguments (i.e. properties of `options` argument)
|
63 | are ignored as if no argument was passed.
|
64 |
|
65 | If any argument is invalid (i.e. `NaN` for numbers and `Invalid Date` for dates),
|
66 | an invalid value will be returned:
|
67 |
|
68 | - `false` for functions that return booleans (expect `isValid`);
|
69 | - `Invalid Date` for functions that return dates;
|
70 | - `NaN` for functions that return numbers;
|
71 | - and `String('Invalid Date')` for functions that return strings.
|
72 |
|
73 | See tests and PRs [#460](https://github.com/date-fns/date-fns/pull/460) and
|
74 | [#765](https://github.com/date-fns/date-fns/pull/765) for exact behavior.
|
75 |
|
76 | ### `null`
|
77 |
|
78 | `null` now is not a valid date. `isValid(null)` returns `false`;
|
79 | `toDate(null)` returns an invalid date. Since `toDate` is used internally
|
80 | by all the functions, operations over `null` will also return an invalid date.
|
81 | [See #537](https://github.com/date-fns/date-fns/issues/537) for the reasoning.
|
82 |
|
83 | ### `RangeError`
|
84 |
|
85 | Functions now throw `RangeError` if optional values passed to `options`
|
86 | are not `undefined` or have expected values.
|
87 | This change is introduced for consistency with ECMAScript standard library which does the same.
|
88 |
|
89 | ### `TypeError`
|
90 |
|
91 | All functions now check if the passed number of arguments is less
|
92 | than the number of required arguments and throw `TypeError` exception if so.
|
93 |
|
94 | ### UMD/CDN
|
95 |
|
96 | The Bower & UMD/CDN package versions are no longer supported.
|
97 |
|
98 | ### New locale format
|
99 |
|
100 | See [docs/Locale](https://date-fns.org/docs/Locale).
|
101 |
|
102 | Locales renamed:
|
103 |
|
104 | - `en` → `en-US`
|
105 | - `zh_cn` → `zh-CN`
|
106 | - `zh_tw` → `zh-TW`
|
107 |
|
108 | ```javascript
|
109 | // Before v2.0.0
|
110 | import locale from 'date-fns/locale/zh_cn'
|
111 |
|
112 | // v2.0.0 onward
|
113 | import locale from 'date-fns/locale/zh-CN'
|
114 | ```
|
115 |
|
116 | [unicode tokens]: https://www.unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table
|