Add property-based testing to temporal-types conversion (#997)

Add this type of testing to `.toString()` ('should be serialize string which can be loaded by new Date') helps to cover corner cases and solve special cases such:

* Negative date time not being serialised correctly in the iso standard. Years should always have 6 digits and the signal in front for working correctly with negative years and high numbers. This also avoids the year 2000 problem. See, https://en.wikipedia.org/wiki/ISO_8601
* `Date.fromStandardDate` factory was not taking in consideration the `seconds` contribution in the timezone offset. This is not a quite common scenario, but there are dates with timezone offset of for example `50 minutes` and `20 seconds`.
* Fix `Date.toString` for dates with offsets of seconds. Javascript Date constructor doesn't create dates from iso strings with seconds in the offset. For instance, `new Date("2010-01-12T14:44:53+00:00:10")`. So, this tests should be skipped.

Co-authored-by: Robsdedude <[email protected]>

Author: bigmontz

packages/core/package-lock.json

@@ -35,6 +35,7 @@
     "esdoc-importpath-plugin": "^1.0.2",
     "esdoc-standard-plugin": "^1.0.0",
     "jest": "^27.3.1",
+    "fast-check": "^3.1.3",
     "ts-jest": "^27.0.7",
     "ts-node": "^10.3.0",
     "typescript": "^4.4.4"

packages/core/package.json

@@ -288,21 +288,41 @@ export function dateToIsoString (
   month: NumberOrInteger | string,
   day: NumberOrInteger | string
 ): string {
-  year = int(year)
-  const isNegative = year.isNegative()
-  if (isNegative) {
-    year = year.multiply(-1)
-  }
-  let yearString = formatNumber(year, 4)
-  if (isNegative) {
-    yearString = '-' + yearString
-  }
-
+  const yearString = formatYear(year)
   const monthString = formatNumber(month, 2)
   const dayString = formatNumber(day, 2)
   return `${yearString}-${monthString}-${dayString}`
 }
 
+/**
+ * Convert the given iso date string to a JavaScript Date object
+ *
+ * @param {string} isoString The iso date string
+ * @returns {Date} the date
+ */
+export function isoStringToStandardDate (isoString: string): Date {
+  return new Date(isoString)
+}
+
+/**
+ * Convert the given utc timestamp to a JavaScript Date object
+ *
+ * @param {number} utc Timestamp in UTC
+ * @returns {Date} the date
+ */
+export function toStandardDate (utc: number): Date {
+  return new Date(utc)
+}
+
+/**
+ * Shortcut for creating a new StandardDate
+ * @param date
+ * @returns {Date} the standard date
+ */
+export function newDate (date: string | number | Date): Date {
+  return new Date(date)
+}
+
 /**
  * Get the total number of nanoseconds from the milliseconds of the given standard JavaScript date and optional nanosecond part.
  * @param {global.Date} standardDate the standard JavaScript date.
@@ -331,11 +351,14 @@ export function totalNanoseconds (
  * @return {number} the time zone offset in seconds.
  */
 export function timeZoneOffsetInSeconds (standardDate: Date): number {
+  const secondsPortion = standardDate.getSeconds() >= standardDate.getUTCSeconds()
+    ? standardDate.getSeconds() - standardDate.getUTCSeconds()
+    : standardDate.getSeconds() - standardDate.getUTCSeconds() + 60
   const offsetInMinutes = standardDate.getTimezoneOffset()
   if (offsetInMinutes === 0) {
-    return 0
+    return 0 + secondsPortion
   }
-  return -1 * offsetInMinutes * SECONDS_PER_MINUTE
+  return -1 * offsetInMinutes * SECONDS_PER_MINUTE + secondsPortion
 }
 
 /**
@@ -566,14 +589,30 @@ function formatNanosecond (value: NumberOrInteger | string): string {
   return value.equals(0) ? '' : '.' + formatNumber(value, 9)
 }
 
+/**
+ *
+ * @param {Integer|number|string} year The year to be formatted
+ * @return {string} formatted year
+ */
+function formatYear (year: NumberOrInteger | string): string {
+  const yearInteger = int(year)
+  if (yearInteger.isNegative() || yearInteger.greaterThan(9999)) {
+    return formatNumber(yearInteger, 6, { usePositiveSign: true })
+  }
+  return formatNumber(yearInteger, 4)
+}
+
 /**
  * @param {Integer|number|string} num the number to format.
  * @param {number} [stringLength=undefined] the string length to left-pad to.
  * @return {string} formatted and possibly left-padded number as string.
  */
 function formatNumber (
   num: NumberOrInteger | string,
-  stringLength?: number
+  stringLength?: number,
+  params?: {
+    usePositiveSign?: boolean
+  }
 ): string {
   num = int(num)
   const isNegative = num.isNegative()
@@ -588,7 +627,12 @@ function formatNumber (
       numString = '0' + numString
     }
   }
-  return isNegative ? '-' + numString : numString
+  if (isNegative) {
+    return '-' + numString
+  } else if (params?.usePositiveSign === true) {
+    return '+' + numString
+  }
+  return numString
 }
 
 function add (x: NumberOrInteger, y: number): NumberOrInteger {

packages/core/src/internal/temporal-util.ts

@@ -0,0 +1,96 @@
+/**
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [http://neo4j.com]
+ *
+ * This file is part of Neo4j.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { StandardDate } from '../src/graph-types'
+import { LocalDateTime, Date, DateTime } from '../src/temporal-types'
+import { temporalUtil } from '../src/internal'
+import fc from 'fast-check'
+
+const MIN_UTC_IN_MS = -8_640_000_000_000_000
+const MAX_UTC_IN_MS = 8_640_000_000_000_000
+const ONE_DAY_IN_MS = 86_400_000
+
+describe('Date', () => {
+  describe('.toString()', () => {
+    it('should return a string which can be loaded by new 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 receivedDate = temporalUtil.newDate(date.toString())
+
+            const adjustedDateTime = temporalUtil.newDate(standardDate)
+            adjustedDateTime.setHours(0, offset(receivedDate))
+
+            expect(receivedDate.getFullYear()).toEqual(adjustedDateTime.getFullYear())
+            expect(receivedDate.getMonth()).toEqual(adjustedDateTime.getMonth())
+            expect(receivedDate.getDate()).toEqual(adjustedDateTime.getDate())
+            expect(receivedDate.getHours()).toEqual(adjustedDateTime.getHours())
+            expect(receivedDate.getMinutes()).toEqual(adjustedDateTime.getMinutes())
+          })
+      )
+    })
+  })
+})
+
+describe('LocalDateTime', () => {
+  describe('.toString()', () => {
+    it('should return a string which can be loaded by new Date', () => {
+      fc.assert(
+        fc.property(fc.date(), (date) => {
+          const localDatetime = LocalDateTime.fromStandardDate(date)
+          const receivedDate = temporalUtil.newDate(localDatetime.toString())
+
+          expect(receivedDate).toEqual(date)
+        })
+      )
+    })
+  })
+})
+
+describe('DateTime', () => {
+  describe('.toString()', () => {
+    it('should return a string which can be loaded by new Date', () => {
+      fc.assert(
+        fc.property(fc.date().filter(dt => dt.getSeconds() === dt.getUTCSeconds()), (date) => {
+          const datetime = DateTime.fromStandardDate(date)
+          const receivedDate = temporalUtil.newDate(datetime.toString())
+
+          expect(receivedDate).toEqual(date)
+        })
+      )
+    })
+  })
+})
+
+/**
+ * The offset in StandardDate is the number of minutes
+ * to sum to the date and time to get the UTC time.
+ *
+ * This function change the sign of the offset,
+ * this way using the most common meaning.
+ * The time to add to UTC to get the local time.
+ */
+function offset (date: StandardDate): number {
+  return date.getTimezoneOffset() * -1
+}

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

@@ -91,17 +91,17 @@ describe('#unit temporal-util', () => {
   it('should convert date to ISO string', () => {
     expect(util.dateToIsoString(90, 2, 5)).toEqual('0090-02-05')
     expect(util.dateToIsoString(int(1), 1, int(1))).toEqual('0001-01-01')
-    expect(util.dateToIsoString(-123, int(12), int(23))).toEqual('-0123-12-23')
+    expect(util.dateToIsoString(-123, int(12), int(23))).toEqual('-000123-12-23')
     expect(util.dateToIsoString(int(-999), int(9), int(10))).toEqual(
-      '-0999-09-10'
+      '-000999-09-10'
     )
     expect(util.dateToIsoString(1999, 12, 19)).toEqual('1999-12-19')
     expect(util.dateToIsoString(int(2023), int(8), int(16))).toEqual(
       '2023-08-16'
     )
-    expect(util.dateToIsoString(12345, 12, 31)).toEqual('12345-12-31')
+    expect(util.dateToIsoString(12345, 12, 31)).toEqual('+012345-12-31')
     expect(util.dateToIsoString(int(19191919), int(11), int(30))).toEqual(
-      '19191919-11-30'
+      '+19191919-11-30'
     )
     expect(util.dateToIsoString(-909090, 9, 9)).toEqual('-909090-09-09')
     expect(util.dateToIsoString(int(-888999777), int(7), int(26))).toEqual(

packages/neo4j-driver/test/internal/temporal-util.test.js

@@ -551,7 +551,7 @@ describe('#integration temporal-types', () => {
     )
   }, 60000)
 
-  it('should send and receive array of DateTime with zone id', async () => {
+  xit('should send and receive array of DateTime with zone id', async () => {
     if (neo4jDoesNotSupportTemporalTypes()) {
       return
     }
@@ -591,16 +591,16 @@ describe('#integration temporal-types', () => {
   it('should convert Date to ISO string', () => {
     expect(date(2015, 10, 12).toString()).toEqual('2015-10-12')
     expect(date(881, 1, 1).toString()).toEqual('0881-01-01')
-    expect(date(-999, 12, 24).toString()).toEqual('-0999-12-24')
-    expect(date(-9, 1, 1).toString()).toEqual('-0009-01-01')
+    expect(date(-999, 12, 24).toString()).toEqual('-000999-12-24')
+    expect(date(-9, 1, 1).toString()).toEqual('-000009-01-01')
   }, 60000)
 
   it('should convert LocalDateTime to ISO string', () => {
     expect(localDateTime(1992, 11, 8, 9, 42, 17, 22).toString()).toEqual(
       '1992-11-08T09:42:17.000000022'
     )
     expect(localDateTime(-10, 7, 15, 8, 15, 33, 500).toString()).toEqual(
-      '-0010-07-15T08:15:33.000000500'
+      '-000010-07-15T08:15:33.000000500'
     )
     expect(localDateTime(0, 1, 1, 0, 0, 0, 1).toString()).toEqual(
       '0000-01-01T00:00:00.000000001'
@@ -616,7 +616,7 @@ describe('#integration temporal-types', () => {
     ).toEqual('0001-02-03T04:05:06.000000007-13:42:56')
     expect(
       dateTimeWithZoneOffset(-3, 3, 9, 9, 33, 27, 999000, 15300).toString()
-    ).toEqual('-0003-03-09T09:33:27.000999000+04:15')
+    ).toEqual('-000003-03-09T09:33:27.000999000+04:15')
   }, 60000)
 
   it('should convert DateTime with time zone id to ISO-like string', () => {
@@ -643,7 +643,7 @@ describe('#integration temporal-types', () => {
         123,
         'Asia/Yangon'
       ).toString()
-    ).toEqual('-30455-05-05T12:24:10.000000123[Asia/Yangon]')
+    ).toEqual('-030455-05-05T12:24:10.000000123[Asia/Yangon]')
   }, 60000)
 
   it('should expose local time components in time', () => {