Merge pull request #528 from iamkun/dev

D2M

README.md

@@ -112,7 +112,6 @@ Please give us a 💖 star 💖 to support us. Thank you.
 And thank you to all our backers! 🙏
 <a href="https://opencollective.com/dayjs#backers" target="_blank"><img src="https://opencollective.com/dayjs/contributors.svg?width=890" /></a>
 
-
 ## License
 
-Day.js is licensed under a [MIT  License](./LICENSE).
+Day.js is licensed under a [MIT License](./LICENSE).

docs/en/API-reference.md

@@ -39,16 +39,15 @@ The `Dayjs` object is immutable, that is, all API operations that change the `Da
     - [UTC offset (minutes) `.utcOffset()`](#utc-offset-minutes-utcoffset)
     - [Days in the Month `.daysInMonth()`](#days-in-the-month-daysinmonth)
     - [As Javascript Date `.toDate()`](#as-javascript-date-todate)
-    - [As Array `.toArray()`](#as-array-toarray)
     - [As JSON `.toJSON()`](#as-json-tojson)
     - [As ISO 8601 String `.toISOString()`](#as-iso-8601-string-toisostring)
-    - [As Object `.toObject()`](#as-object-toobject)
     - [As String `.toString()`](#as-string-tostring)
   - [Query](#query)
     - [Is Before `.isBefore(compared: Dayjs, unit?: string)`](#is-before-isbeforecompared-dayjs-unit-string)
     - [Is Same `.isSame(compared: Dayjs, unit?: string)`](#is-same-issamecompared-dayjs-unit-string)
     - [Is After `.isAfter(compared: Dayjs, unit?: string)`](#is-after-isaftercompared-dayjs-unit-string)
     - [Is a Dayjs `.isDayjs()`](#is-a-dayjs-isdayjscompared-any)
+  - [UTC](#utc)
   - [Plugin APIs](#plugin-apis)
     - [RelativeTime](#relativetime)
     - [IsLeapYear](#isleapyear)
@@ -57,10 +56,12 @@ The `Dayjs` object is immutable, that is, all API operations that change the `Da
     - [IsSameOrBefore](#issameorbefore)
     - [IsBetween](#isbetween)
     - [QuarterOfYear](#quarterofyear)
+    - [ToArray](#toarray)
+    - [ToObject](#toobject)
 
 ## Parsing
 
-### Constructor `dayjs(existing?: string | number | Date | Dayjs)`
+### Constructor `dayjs(dateType?: string | number | Date | Dayjs)`
 
 Calling it without parameters returns a fresh `Dayjs` object with the current date and time.
 
@@ -124,66 +125,74 @@ dayjs().isValid()
 
 ### Year `.year()`
 
-Returns a `number` representing the `Dayjs`'s year.
+Gets or sets the year.
 
 ```js
 dayjs().year()
+dayjs().year(2000)
 ```
 
 ### Month `.month()`
 
-Returns a `number` representing the `Dayjs`'s month. Starts at 0
+Gets or sets the month. Starts at 0
 
 ```js
 dayjs().month()
+dayjs().month(0)
 ```
 
 ### Day of the Month `.date()`
 
-Returns a `number` representing the `Dayjs`'s day of the month. Starts at 1
+Gets or sets the day of the month. Starts at 1
 
 ```js
 dayjs().date()
+dayjs().date(1)
 ```
 
 ### Day of the Week `.day()`
 
-Returns a `number` representing the `Dayjs`'s day of the week. Starts on Sunday with 0
+Gets or sets the day of the week. Starts on Sunday with 0
 
 ```js
 dayjs().day()
+dayjs().day(0)
 ```
 
 ### Hour `.hour()`
 
-Returns a `number` representing the `Dayjs`'s hour.
+Gets or sets the hour.
 
 ```js
 dayjs().hour()
+dayjs().hour(12)
 ```
 
 ### Minute `.minute()`
 
-Returns a `number` representing the `Dayjs`'s minute.
+Gets or sets the minute.
 
 ```js
 dayjs().minute()
+dayjs().minute(59)
 ```
 
 ### Second `.second()`
 
-Returns a `number` representing the `Dayjs`'s second.
+Gets or sets the second.
 
 ```js
 dayjs().second()
+dayjs().second(1)
 ```
 
 ### Millisecond `.millisecond()`
 
-Returns a `number` representing the `Dayjs`'s millisecond.
+Gets or sets the millisecond.
 
 ```js
 dayjs().millisecond()
+dayjs().millisecond(1)
 ```
 
 ### Set `.set(unit: string, value: number)`
@@ -353,14 +362,6 @@ Returns a copy of the native `Date` object parsed from the `Dayjs` object.
 dayjs('2019-01-25').toDate()
 ```
 
-### As Array `.toArray()`
-
-Returns an `array` that mirrors the parameters from new Date().
-
-```js
-dayjs('2019-01-25').toArray() // [ 2019, 0, 25, 0, 0, 0, 0 ]
-```
-
 ### As JSON `.toJSON()`
 
 Returns the `Dayjs` formatted in an ISO8601 `string`.
@@ -377,21 +378,6 @@ Returns the `Dayjs` formatted in an ISO8601 `string`.
 dayjs('2019-01-25').toISOString() // '2019-01-25T02:00:00.000Z'
 ```
 
-### As Object `.toObject()`
-
-Returns an `object` with the date's properties.
-
-```js
-dayjs('2019-01-25').toObject()
-/* { years: 2019,
-     months: 0,
-     date: 25,
-     hours: 0,
-     minutes: 0,
-     seconds: 0,
-     milliseconds: 0 } */
-```
-
 ### As String `.toString()`
 
 Returns a `string` representation of the date.
@@ -444,6 +430,10 @@ The operator `instanceof` works equally well:
 dayjs() instanceof dayjs // true
 ```
 
+## UTC
+
+If you want to parse or display in UTC, you can use `.utc` `.local` `.isUTC` with plugin [`UTC`](./Plugin.md#utc)
+
 ## Plugin APIs
 
 ### RelativeTime
@@ -487,3 +477,15 @@ plugin [`IsBetween`](./Plugin.md#isbetween)
 `.quarter` to get quarter of the year
 
 plugin [`QuarterOfYear`](./Plugin.md#quarterofyear)
+
+### ToArray
+
+`.toArray` to return an `array` that mirrors the parameters
+
+plugin [`ToArray`](./Plugin.md#toarray)
+
+### ToObject
+
+`.toObject` to return an `object` with the date's properties.
+
+plugin [`ToObject`](./Plugin.md#toobject)

docs/en/Plugin.md

@@ -44,6 +44,52 @@ dayjs.extend(AdvancedFormat) // use plugin
 
 ## List of official plugins
 
+### UTC
+
+- UTC adds `.utc` `.local` `.isUTC` APIs to parse or display in UTC.
+
+```javascript
+import utc from 'dayjs/plugin/utc'
+
+dayjs.extend(utc)
+
+// default local time
+dayjs().format() //2019-03-06T17:11:55+08:00
+// UTC mode
+dayjs.utc().format() // 2019-03-06T09:11:55Z
+dayjs()
+  .utc()
+  .format() // 2019-03-06T09:11:55Z
+// While in UTC mode, all display methods will display in UTC time instead of local time.
+// And all getters and setters will internally use the Date#getUTC* and Date#setUTC* methods instead of the Date#get* and Date#set* methods.
+dayjs.utc().isUTC() // true
+dayjs
+  .utc()
+  .local()
+  .format() //2019-03-06T17:11:55+08:00
+dayjs.utc('2018-01-01', 'YYYY-MM-DD') // with CustomParseFormat plugin
+```
+
+By default, Day.js parses and displays in local time.
+
+If you want to parse or display in UTC, you can use `dayjs.utc()` instead of `dayjs()`.
+
+#### dayjs.utc `dayjs.utc(dateType?: string | number | Date | Dayjs, format? string)`
+
+Returns a `Dayjs` object in UTC mode.
+
+#### Use UTC time `.utc()`
+
+Returns a cloned `Dayjs` object with a flag to use UTC time.
+
+#### Use local time `.local()`
+
+Returns a cloned `Dayjs` object with a flag to use local time.
+
+#### isUTC mode `.isUTC()`
+
+Returns a `boolean` indicating current `Dayjs` object is in UTC mode or not.
+
 ### AdvancedFormat
 
 - AdvancedFormat extends `dayjs().format` API to supply more format options.
@@ -293,6 +339,38 @@ dayjs('2018 Enero 15', 'YYYY MMMM DD', 'es')
 | `ZZ`   | -0500            | Compact offset from UTC, 2-digits |
 | `A`    | AM PM            | Post or ante meridiem, upper-case |
 | `a`    | am pm            | Post or ante meridiem, lower-case |
+| `Do`   | 1st... 31st      | Day of Month with ordinal         |
+
+### ToArray
+
+- ToArray add `.toArray()` API to return an `array` that mirrors the parameters
+
+```javascript
+import toArray from 'dayjs/plugin/toArray'
+
+dayjs.extend(toArray)
+
+dayjs('2019-01-25').toArray() // [ 2019, 0, 25, 0, 0, 0, 0 ]
+```
+
+### ToObject
+
+- ToObject add `.toObject()` API to return an `object` with the date's properties.
+
+```javascript
+import toObject from 'dayjs/plugin/toObject'
+
+dayjs.extend(toObject)
+
+dayjs('2019-01-25').toObject()
+/* { years: 2019,
+     months: 0,
+     date: 25,
+     hours: 0,
+     minutes: 0,
+     seconds: 0,
+     milliseconds: 0 } */
+```
 
 ## Customize