Replace unclear fromStandardDate() (#1290)

fromStandardDate() has been deprecated and split into clarified functions fromStandardDateLocal() and fromStandardDateUTC()

Author: MaxAake

packages/core/src/temporal-types.ts

@@ -352,15 +352,35 @@ export class Date<T extends NumberOrInteger = Integer> {
 
   /**
    * Create a {@link Date} object from the given standard JavaScript `Date`.
-   * Hour, minute, second, millisecond and time zone offset components of the given date are ignored.
+   * Hour, minute, second and millisecond components of the given date are ignored.
    *
-   * NOTE: the function {@link toStandardDate} and {@link fromStandardDate} are not inverses of one another. {@link fromStandardDate} takes the Day, Month and Year in local time from the supplies JavaScript Date object, while {@link toStandardDate} creates a new JavaScript Date object at midnight UTC. This incongruity will be rectified in 6.0
+   * NOTE: the function {@link toStandardDate} and {@link fromStandardDate} are not inverses of one another. {@link fromStandardDate} takes the Day, Month and Year in local time from the supplied JavaScript Date object, while {@link toStandardDate} creates a new JavaScript Date object at midnight UTC. This incongruity will be rectified in 6.0
    * If your timezone has a negative offset from UTC, creating a JavaScript Date at midnight UTC and converting it with {@link fromStandardDate} will result in a Date for the day before.
    *
    * @param {global.Date} standardDate - The standard JavaScript date to convert.
    * @return {Date} New Date.
+   * @deprecated use {@link fromStandardDateLocal} which is a drop in replacement, or {@link fromStandardDateUTC} which takes the Year, Month and Date from UTC rather than Local time
    */
   static fromStandardDate (standardDate: StandardDate): Date<number> {
+    return this.fromStandardDateLocal(standardDate)
+  }
+
+  /**
+   * Create a {@link Date} object from the given standard JavaScript `Date` using the Year, Month and Date in Local Time.
+   * Hour, minute, second and millisecond components of the given date are ignored.
+   *
+   * NOTE: this function and {@link toStandardDate} are not inverses of one another.
+   * This takes the Day, Month and Year in local time from the supplied JavaScript Date object, while {@link toStandardDate} creates a new JavaScript Date object at midnight UTC.
+   * For a more global approach, use {@link fromStandardDateUTC}, which reads the date in UTC time.
+   *
+   * @example
+   * fromStandardDateLocal(new Date("2010-10-10T00:00:00")) // Will create a date at 2010-10-10 as JS Dates are created at local time by default
+   * fromStandardDateLocal(new Date("2010-10-10T00:00:00Z")) // This may cause issues as this date is created at UTC with the trailing "Z"
+   *
+   * @param {global.Date} standardDate - The standard JavaScript date to convert.
+   * @return {Date} New Date.
+   */
+  static fromStandardDateLocal (standardDate: StandardDate): Date<number> {
     verifyStandardDateAndNanos(standardDate)
 
     return new Date(
@@ -370,14 +390,33 @@ export class Date<T extends NumberOrInteger = Integer> {
     )
   }
 
+  /**
+   * Create a {@link Date} object from the given standard JavaScript `Date` using the Year, Month and Date in UTC time.
+   * Hour, minute, second and millisecond components of the given date are ignored.
+   *
+   * @example
+   * fromStandardDateUTC(new Date("2010-10-10T00:00:00")) // This may cause issues as JS Dates are created at local time by default
+   * fromStandardDateUTC(new Date("2010-10-10T00:00:00Z")) // Will create a date at 2010-10-10 as this date is created at UTC with the trailing "Z"
+   *
+   * @param {global.Date} standardDate - The standard JavaScript date to convert.
+   * @return {Date} New Date.
+   */
+  static fromStandardDateUTC (standardDate: StandardDate): Date<number> {
+    verifyStandardDateAndNanos(standardDate)
+
+    return new Date(
+      standardDate.getUTCFullYear(),
+      standardDate.getUTCMonth() + 1,
+      standardDate.getUTCDate()
+    )
+  }
+
   /**
    * Convert date to standard JavaScript `Date`.
    *
    * The time component of the returned `Date` is set to midnight
    * and the time zone is set to UTC.
    *
-   * NOTE: the function {@link toStandardDate} and {@link fromStandardDate} are not inverses of one another. {@link fromStandardDate} takes the Day, Month and Year in local time from the supplies JavaScript Date object, while {@link toStandardDate} creates a new JavaScript Date object at midnight UTC. This incongruity will be rectified in 6.0
-   *
    * @returns {StandardDate} Standard JavaScript `Date` at `00:00:00.000` UTC.
    */
   toStandardDate (): StandardDate {

packages/core/test/temporal-types.test.ts

@@ -24,29 +24,19 @@ const MAX_UTC_IN_MS = 8_640_000_000_000_000
 const ONE_DAY_IN_MS = 86_400_000
 
 describe('Date', () => {
-  describe('.toStandardDate()', () => {
-    it('should convert to a standard date', () => {
-      const localDatetime = new Date(2020, 3, 2)
-
-      const standardDate = localDatetime.toStandardDate()
-
-      expect(standardDate.getUTCFullYear()).toEqual(localDatetime.year)
-      expect(standardDate.getUTCMonth()).toEqual(localDatetime.month - 1)
-      expect(standardDate.getUTCDate()).toEqual(localDatetime.day)
-    })
-
-    it('should be the reverse operation of fromStandardDate but losing time information', () => {
+  describe('.fromStandardDateLocal()', () => {
+    it('should create a date from the zoned date on a JS Date.', () => {
       fc.assert(
         fc.property(
           fc.date({
             max: temporalUtil.newDate(MAX_UTC_IN_MS - ONE_DAY_IN_MS),
             min: temporalUtil.newDate(MIN_UTC_IN_MS + ONE_DAY_IN_MS)
           }),
           standardDate => {
-            const date = Date.fromStandardDate(standardDate)
+            const date = Date.fromStandardDateLocal(standardDate)
             const receivedDate = date.toStandardDate()
 
-            expect(receivedDate.getUTCFullYear()).toEqual(standardDate.getFullYear()) // Date converts from local time but to UTC
+            expect(receivedDate.getUTCFullYear()).toEqual(standardDate.getFullYear())
             expect(receivedDate.getUTCMonth()).toEqual(standardDate.getMonth())
             expect(receivedDate.getUTCDate()).toEqual(standardDate.getDate())
             expect(receivedDate.getUTCHours()).toEqual(0)
@@ -55,6 +45,38 @@ describe('Date', () => {
       )
     })
   })
+  describe('.fromStandardDateUTC()', () => {
+    it('should be the reverse operation of toStandardDateUTC but losing time information', () => {
+      fc.assert(
+        fc.property(
+          fc.date({
+            max: temporalUtil.newDate(MAX_UTC_IN_MS - ONE_DAY_IN_MS),
+            min: temporalUtil.newDate(MIN_UTC_IN_MS + ONE_DAY_IN_MS)
+          }),
+          standardDate => {
+            const date = Date.fromStandardDateUTC(standardDate)
+            const receivedDate = date.toStandardDate()
+
+            expect(receivedDate.getUTCFullYear()).toEqual(standardDate.getUTCFullYear())
+            expect(receivedDate.getUTCMonth()).toEqual(standardDate.getUTCMonth())
+            expect(receivedDate.getUTCDate()).toEqual(standardDate.getUTCDate())
+            expect(receivedDate.getUTCHours()).toEqual(0)
+            expect(receivedDate.getUTCMinutes()).toEqual(0)
+          })
+      )
+    })
+  })
+  describe('.toStandardDate()', () => {
+    it('should convert to a standard date', () => {
+      const localDatetime = new Date(2020, 3, 2)
+
+      const standardDate = localDatetime.toStandardDate()
+
+      expect(standardDate.getUTCFullYear()).toEqual(localDatetime.year)
+      expect(standardDate.getUTCMonth()).toEqual(localDatetime.month - 1)
+      expect(standardDate.getUTCDate()).toEqual(localDatetime.day)
+    })
+  })
 })
 
 describe('LocalDateTime', () => {