diff --git a/packages/core/src/temporal-types.ts b/packages/core/src/temporal-types.ts index 7ea533506..4e638cd1f 100644 --- a/packages/core/src/temporal-types.ts +++ b/packages/core/src/temporal-types.ts @@ -352,15 +352,35 @@ export class Date { /** * 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 { + 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 { verifyStandardDateAndNanos(standardDate) return new Date( @@ -370,14 +390,33 @@ export class Date { ) } + /** + * 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 { + 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 { diff --git a/packages/core/test/temporal-types.test.ts b/packages/core/test/temporal-types.test.ts index 4341be584..4ffe8c00f 100644 --- a/packages/core/test/temporal-types.test.ts +++ b/packages/core/test/temporal-types.test.ts @@ -24,18 +24,8 @@ 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({ @@ -43,10 +33,10 @@ describe('Date', () => { 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', () => { diff --git a/packages/neo4j-driver-deno/lib/core/temporal-types.ts b/packages/neo4j-driver-deno/lib/core/temporal-types.ts index fbc48dd35..5907ebd5c 100644 --- a/packages/neo4j-driver-deno/lib/core/temporal-types.ts +++ b/packages/neo4j-driver-deno/lib/core/temporal-types.ts @@ -352,15 +352,35 @@ export class Date { /** * 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 { + 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 { verifyStandardDateAndNanos(standardDate) return new Date( @@ -370,14 +390,33 @@ export class Date { ) } + /** + * 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 { + 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 {