Documentation updates

README.md

@@ -12,11 +12,15 @@ such as '-0200' or '+04:00', but not IANA time zone names.
 
 **Note:** `date-fns` is a peer dependency of this library.
 
+If you find this library useful, why not
+
+<a href="https://www.buymeacoffee.com/marnusw" target="_blank"><img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" alt="Buy Me A Coffee" style="height: 41px !important;width: 174px !important;box-shadow: 0px 3px 2px 0px rgba(190, 190, 190, 0.5) !important;-webkit-box-shadow: 0px 3px 2px 0px rgba(190, 190, 190, 0.5) !important;" ></a>
+
 ## Table of Contents
 
 - [Overview](#overview)
 - [Date and time zone formatting](#date-and-time-zone-formatting)
-  - [`formatAsZonedTime`](#formataszonedtime) - Formats a date in the provided time zone,
+  - [`formatInTimeZone`](#formataszonedtime) - Formats a date in the provided time zone,
     regardless of the system time zone
 - [Time zone offset helpers](#time-zone-offset-helpers)
   - [`zonedTimeToUtc`](#zonedtimetoutc) - Given a date and any time zone, returns a `Date` with the equivalent UTC time
@@ -48,7 +52,7 @@ common time zone related use cases.
 
 ## Date and time zone formatting
 
-### `formatAsZonedTime`
+### `formatInTimeZone`
 
 This function takes a `Date` instance in the system's local time or an ISO8601 string, and
 an IANA time zone name or offset string. It then formats this date in the target time zone
@@ -62,24 +66,27 @@ It supports the same format tokens as `date-fns/format`, and adds full support f
 Unlike `date-fns/format`, the `z..zzzz`, `x..xxxxx`, `X..XXXXX` and `O..OOO` tokens will all
 print the formatted value of the provided time zone rather than the system time zone.
 
+An invalid date or time zone input will result in an `Invalid Date` passed to `date-fns/format`,
+which will throw a `RangeError`.
+
 For most use cases this is the only function from this library you will need.
 
 ```javascript
-import { formatAsZonedTime } from 'date-fns-tz'
+import { formatInTimeZone } from 'date-fns-tz'
 
 const date = new Date('2014-10-25T10:46:20Z')
 
-formatAsZonedTime(date, 'America/New_York', 'yyyy-MM-dd HH:mm:ssXXX') // 2014-10-25 06:46:20-04:00
-formatAsZonedTime(date, 'America/New_York', 'yyyy-MM-dd HH:mm:ss zzz') // 2014-10-25 06:46:20 EST
-formatAsZonedTime(date, 'Europe/Paris', 'yyyy-MM-dd HH:mm:ss zzz') // 2014-10-25 10:46:20 GMT+2
+formatInTimeZone(date, 'America/New_York', 'yyyy-MM-dd HH:mm:ssXXX') // 2014-10-25 06:46:20-04:00
+formatInTimeZone(date, 'America/New_York', 'yyyy-MM-dd HH:mm:ss zzz') // 2014-10-25 06:46:20 EST
+formatInTimeZone(date, 'Europe/Paris', 'yyyy-MM-dd HH:mm:ss zzz') // 2014-10-25 10:46:20 GMT+2
 
 // The time zone name is generated by the Intl API which works best when a locale is also provided
 import enGB from 'date-fns/locale/en-GB'
 
-formatAsZonedTime(parisDate, 'Europe/Paris', 'yyyy-MM-dd HH:mm:ss zzz', { locale: enGB })
+formatInTimeZone(parisDate, 'Europe/Paris', 'yyyy-MM-dd HH:mm:ss zzz', { locale: enGB })
 // 2014-10-25 10:46:20 CEST
 
-formatAsZonedTime(parisDate, 'Europe/Paris', 'yyyy-MM-dd HH:mm:ss zzzz', { locale: enGB })
+formatInTimeZone(parisDate, 'Europe/Paris', 'yyyy-MM-dd HH:mm:ss zzzz', { locale: enGB })
 // 2014-10-25 10:46:20 Central European Summer Time
 ```
 
@@ -95,6 +102,7 @@ this local time should be shown when accessing the site from anywhere in the wor
 ### `zonedTimeToUtc`
 
 Given a date and any time zone, returns a `Date` with the equivalent UTC time.
+An invalid date string or time zone will result in an `Invalid Date`.
 
 ```ts
 zonedTimeToUtc(date: Date|Number|String, timeZone: String): Date
@@ -120,6 +128,7 @@ postToServer(utcDate.toISOString(), timeZone) // post 2014-06-25T17:00:00.000Z,
 ### `utcToZonedTime`
 
 Returns a `Date` which will format as the local time of any time zone from a specific UTC time.
+An invalid date string or time zone will result in an `Invalid Date`.
 
 ```js
 utcToZonedTime(date: Date|Number|String, timeZone: String): Date
@@ -155,6 +164,8 @@ For time zones where daylight savings time is applicable a `Date` should be pass
 the second parameter to ensure the offset correctly accounts for DST at that time of
 year. When omitted, the current date is used.
 
+For invalid time zones, `NaN` is returned.
+
 ```javascript
 import { getTimezoneOffset } from 'date-fns-tz'
 
@@ -172,7 +183,7 @@ const result = getTimezoneOffset('America/New_York', new Date(2016, 6, 1))
 
 ### `format`
 
-The `format` function exported from this library is used under the hood by `formatAsZonedTime`
+The `format` function exported from this library is used under the hood by `formatInTimeZone`
 and extends `date-fns/format` with full time zone support for:
 
 - The `z..zzz` Unicode tokens: _short specific non-location format_
@@ -188,12 +199,14 @@ zone (if provided, see below) rather than the system time zone.
 Since a JavaScript `Date` instance cannot convey the time zone information to the `format` function
 it is necessary to pass the `timeZone` value as an option on the third argument of `format`.
 
+Similar to `date-fns/format`, when an invalid date or time zone is used a `RangeError` is thrown.
+
 To format a date showing time for a specific time zone other than the system time zone, the
-`format` function can be combined with `utcToZonedTime`. This is what `formatAsZonedTime` does
+`format` function can be combined with `utcToZonedTime`. This is what `formatInTimeZone` does
 internally. _To clarify, the `format` function will never change the underlying date, it must be
 changed to a zoned time before passing it to `format`._
 
-In most cases there is no need to use `format` rather than `formatAsZonedTime`. The only time
+In most cases there is no need to use `format` rather than `formatInTimeZone`. The only time
 this makes sense is when `utcToZonedTime` has been applied to a date once, and you want to
 format it multiple times to different outputs.
 
@@ -229,6 +242,8 @@ format(parisDate, 'yyyy-MM-dd HH:mm:ss zzzz', {
 The `toDate` function can be used to parse a `Date` from a string containing a date and time
 representing time in any time zone by providing an IANA time zone name on the `timeZone` option.
 
+An invalid date string or time zone will result in an `Invalid Date`.
+
 ```javascript
 import { toDate, format } from 'date-fns-tz'