Represent Cypher DateTime with a single type

DateTime contains time zone information. It might either be an offset
in seconds (that corresponds to ±HH:MM) or the time zone id
(like 'Europe/London'). Previously driver exposed DateTime as two
different types: `DateTimeWithZoneOffset` and `DateTimeWithZoneId`.

This commit combines them into a single type:

```
class DateTime {
  year: Integer|number,
  month: Integer|number,
  day: Integer|number,
  hour: Integer|number,
  minute: Integer|number,
  second: Integer|number,
  nanosecond: Integer|number,
  timeZoneOffsetSeconds: Integer|number,
  timeZoneId: string
}
```

where either `timeZoneOffsetSeconds` or `timeZoneId` is defined. Such
single type better corresponds to the Cypher DateTime type and feels
more idiomatic to JavaScript. Shape of objects (set of their properties)
feels more important than the class/type.

Also renamed `Time.offsetSeconds` to `Time.timeZoneOffsetSeconds` to
better represent the meaning of the property.

Author: lutovich

src/v1/index.js

@@ -30,22 +30,7 @@ import {assertString, isEmptyObjectOrNull} from './internal/util';
 import urlUtil from './internal/url-util';
 import HttpDriver from './internal/http/http-driver';
 import {isPoint, Point} from './spatial-types';
-import {
-  Date,
-  DateTimeWithZoneId,
-  DateTimeWithZoneOffset,
-  Duration,
-  isDate,
-  isDateTimeWithZoneId,
-  isDateTimeWithZoneOffset,
-  isDuration,
-  isLocalDateTime,
-  isLocalTime,
-  isTime,
-  LocalDateTime,
-  LocalTime,
-  Time
-} from './temporal-types';
+import {Date, DateTime, Duration, isDate, isDateTime, isDuration, isLocalDateTime, isLocalTime, isTime, LocalDateTime, LocalTime, Time} from './temporal-types';
 
 /**
  * @property {function(username: string, password: string, realm: ?string)} basic the function to create a
@@ -225,8 +210,7 @@ const types = {
   Record,
   Point,
   Date,
-  DateTimeWithZoneId,
-  DateTimeWithZoneOffset,
+  DateTime,
   Duration,
   LocalDateTime,
   LocalTime,
@@ -275,8 +259,7 @@ const forExport = {
   Point,
   isPoint,
   Date,
-  DateTimeWithZoneId,
-  DateTimeWithZoneOffset,
+  DateTime,
   Duration,
   LocalDateTime,
   LocalTime,
@@ -286,8 +269,7 @@ const forExport = {
   isTime,
   isDate,
   isLocalDateTime,
-  isDateTimeWithZoneOffset,
-  isDateTimeWithZoneId
+  isDateTime
 };
 
 export {
@@ -303,8 +285,7 @@ export {
   Point,
   isPoint,
   Date,
-  DateTimeWithZoneId,
-  DateTimeWithZoneOffset,
+  DateTime,
   Duration,
   LocalDateTime,
   LocalTime,
@@ -314,7 +295,6 @@ export {
   isTime,
   isDate,
   isLocalDateTime,
-  isDateTimeWithZoneOffset,
-  isDateTimeWithZoneId
+  isDateTime
 };
 export default forExport;

src/v1/internal/packstream-v2.js

@@ -19,20 +19,7 @@
 
 import * as v1 from './packstream-v1';
 import {isPoint, Point} from '../spatial-types';
-import {
-  Date,
-  DateTimeWithZoneId,
-  DateTimeWithZoneOffset,
-  Duration,
-  isDate,
-  isDateTimeWithZoneId,
-  isDateTimeWithZoneOffset,
-  isDuration,
-  isLocalDateTime,
-  isLocalTime,
-  isTime,
-  Time
-} from '../temporal-types';
+import {Date, DateTime, Duration, isDate, isDateTime, isDuration, isLocalDateTime, isLocalTime, isTime, Time} from '../temporal-types';
 import {int} from '../integer';
 import {
   dateToEpochDay,
@@ -97,10 +84,8 @@ export class Packer extends v1.Packer {
       return () => packDate(obj, this, onError);
     } else if (isLocalDateTime(obj)) {
       return () => packLocalDateTime(obj, this, onError);
-    } else if (isDateTimeWithZoneOffset(obj)) {
-      return () => packDateTimeWithZoneOffset(obj, this, onError);
-    } else if (isDateTimeWithZoneId(obj)) {
-      return () => packDateTimeWithZoneId(obj, this, onError);
+    } else if (isDateTime(obj)) {
+      return () => packDateTime(obj, this, onError);
     } else {
       return super.packable(obj, onError);
     }
@@ -301,7 +286,7 @@ function unpackLocalTime(unpacker, structSize, buffer) {
  */
 function packTime(value, packer, onError) {
   const nanoOfDay = localTimeToNanoOfDay(value.hour, value.minute, value.second, value.nanosecond);
-  const offsetSeconds = int(value.offsetSeconds);
+  const offsetSeconds = int(value.timeZoneOffsetSeconds);
 
   const packableStructFields = [
     packer.packable(nanoOfDay, onError),
@@ -389,21 +374,35 @@ function unpackLocalDateTime(unpacker, structSize, buffer) {
   return epochSecondAndNanoToLocalDateTime(epochSecond, nano);
 }
 
+/**
+ * Pack given date time.
+ * @param {DateTime} value the date time value to pack.
+ * @param {Packer} packer the packer to use.
+ * @param {function} onError the error callback.
+ */
+function packDateTime(value, packer, onError) {
+  if (value.timeZoneId) {
+    packDateTimeWithZoneId(value, packer, onError);
+  } else {
+    packDateTimeWithZoneOffset(value, packer, onError);
+  }
+}
+
 /**
  * Pack given date time with zone offset.
- * @param {DateTimeWithZoneOffset} value the date time value to pack.
+ * @param {DateTime} value the date time value to pack.
  * @param {Packer} packer the packer to use.
  * @param {function} onError the error callback.
  */
 function packDateTimeWithZoneOffset(value, packer, onError) {
   const epochSecond = localDateTimeToEpochSecond(value.year, value.month, value.day, value.hour, value.minute, value.second, value.nanosecond);
   const nano = int(value.nanosecond);
-  const offsetSeconds = int(value.offsetSeconds);
+  const timeZoneOffsetSeconds = int(value.timeZoneOffsetSeconds);
 
   const packableStructFields = [
     packer.packable(epochSecond, onError),
     packer.packable(nano, onError),
-    packer.packable(offsetSeconds, onError)
+    packer.packable(timeZoneOffsetSeconds, onError)
   ];
   packer.packStruct(DATE_TIME_WITH_ZONE_OFFSET, packableStructFields, onError);
 }
@@ -413,35 +412,35 @@ function packDateTimeWithZoneOffset(value, packer, onError) {
  * @param {Unpacker} unpacker the unpacker to use.
  * @param {number} structSize the retrieved struct size.
  * @param {BaseBuffer} buffer the buffer to unpack from.
- * @return {DateTimeWithZoneOffset} the unpacked date time with zone offset value.
+ * @return {DateTime} the unpacked date time with zone offset value.
  */
 function unpackDateTimeWithZoneOffset(unpacker, structSize, buffer) {
   unpacker._verifyStructSize('DateTimeWithZoneOffset', DATE_TIME_WITH_ZONE_OFFSET_STRUCT_SIZE, structSize);
 
   const epochSecond = unpacker.unpack(buffer);
   const nano = unpacker.unpack(buffer);
-  const offsetSeconds = unpacker.unpack(buffer);
+  const timeZoneOffsetSeconds = unpacker.unpack(buffer);
 
   const localDateTime = epochSecondAndNanoToLocalDateTime(epochSecond, nano);
-  return new DateTimeWithZoneOffset(localDateTime.year, localDateTime.month, localDateTime.day, localDateTime.hour,
-    localDateTime.minute, localDateTime.second, localDateTime.nanosecond, offsetSeconds);
+  return new DateTime(localDateTime.year, localDateTime.month, localDateTime.day, localDateTime.hour,
+    localDateTime.minute, localDateTime.second, localDateTime.nanosecond, timeZoneOffsetSeconds, null);
 }
 
 /**
  * Pack given date time with zone id.
- * @param {DateTimeWithZoneId} value the date time value to pack.
+ * @param {DateTime} value the date time value to pack.
  * @param {Packer} packer the packer to use.
  * @param {function} onError the error callback.
  */
 function packDateTimeWithZoneId(value, packer, onError) {
   const epochSecond = localDateTimeToEpochSecond(value.year, value.month, value.day, value.hour, value.minute, value.second, value.nanosecond);
   const nano = int(value.nanosecond);
-  const zoneId = value.zoneId;
+  const timeZoneId = value.timeZoneId;
 
   const packableStructFields = [
     packer.packable(epochSecond, onError),
     packer.packable(nano, onError),
-    packer.packable(zoneId, onError)
+    packer.packable(timeZoneId, onError)
   ];
   packer.packStruct(DATE_TIME_WITH_ZONE_ID, packableStructFields, onError);
 }
@@ -451,16 +450,16 @@ function packDateTimeWithZoneId(value, packer, onError) {
  * @param {Unpacker} unpacker the unpacker to use.
  * @param {number} structSize the retrieved struct size.
  * @param {BaseBuffer} buffer the buffer to unpack from.
- * @return {DateTimeWithZoneId} the unpacked date time with zone id value.
+ * @return {DateTime} the unpacked date time with zone id value.
  */
 function unpackDateTimeWithZoneId(unpacker, structSize, buffer) {
   unpacker._verifyStructSize('DateTimeWithZoneId', DATE_TIME_WITH_ZONE_ID_STRUCT_SIZE, structSize);
 
   const epochSecond = unpacker.unpack(buffer);
   const nano = unpacker.unpack(buffer);
-  const zoneId = unpacker.unpack(buffer);
+  const timeZoneId = unpacker.unpack(buffer);
 
   const localDateTime = epochSecondAndNanoToLocalDateTime(epochSecond, nano);
-  return new DateTimeWithZoneId(localDateTime.year, localDateTime.month, localDateTime.day, localDateTime.hour,
-    localDateTime.minute, localDateTime.second, localDateTime.nanosecond, zoneId);
+  return new DateTime(localDateTime.year, localDateTime.month, localDateTime.day, localDateTime.hour,
+    localDateTime.minute, localDateTime.second, localDateTime.nanosecond, null, timeZoneId);
 }

src/v1/temporal-types.js

@@ -18,6 +18,7 @@
  */
 
 import {dateToIsoString, durationToIsoString, timeToIsoString, timeZoneOffsetToIsoString} from './internal/temporal-util';
+import {newError} from './error';
 
 const IDENTIFIER_PROPERTY_ATTRIBUTES = {
   value: true,
@@ -30,8 +31,7 @@ const LOCAL_TIME_IDENTIFIER_PROPERTY = '__isLocalTime__';
 const TIME_IDENTIFIER_PROPERTY = '__isTime__';
 const DATE_IDENTIFIER_PROPERTY = '__isDate__';
 const LOCAL_DATE_TIME_IDENTIFIER_PROPERTY = '__isLocalDateTime__';
-const DATE_TIME_WITH_ZONE_OFFSET_IDENTIFIER_PROPERTY = '__isDateTimeWithZoneOffset__';
-const DATE_TIME_WITH_ZONE_ID_IDENTIFIER_PROPERTY = '__isDateTimeWithZoneId__';
+const DATE_TIME_IDENTIFIER_PROPERTY = '__isDateTime__';
 
 /**
  * Represents an ISO 8601 duration. Contains both date-based values (years, months, days) and time-based values (seconds, nanoseconds).
@@ -119,19 +119,19 @@ export class Time {
    * @param {Integer|number} minute the minute for the new local time.
    * @param {Integer|number} second the second for the new local time.
    * @param {Integer|number} nanosecond the nanosecond for the new local time.
-   * @param {Integer|number} offsetSeconds the time zone offset in seconds.
+   * @param {Integer|number} timeZoneOffsetSeconds the time zone offset in seconds.
    */
-  constructor(hour, minute, second, nanosecond, offsetSeconds) {
+  constructor(hour, minute, second, nanosecond, timeZoneOffsetSeconds) {
     this.hour = hour;
     this.minute = minute;
     this.second = second;
     this.nanosecond = nanosecond;
-    this.offsetSeconds = offsetSeconds;
+    this.timeZoneOffsetSeconds = timeZoneOffsetSeconds;
     Object.freeze(this);
   }
 
   toString() {
-    return timeToIsoString(this.hour, this.minute, this.second, this.nanosecond) + timeZoneOffsetToIsoString(this.offsetSeconds);
+    return timeToIsoString(this.hour, this.minute, this.second, this.nanosecond) + timeZoneOffsetToIsoString(this.timeZoneOffsetSeconds);
   }
 }
 
@@ -226,93 +226,54 @@ export function isLocalDateTime(obj) {
 
 /**
  * Represents an instant capturing the date, the time and the timezone identifier.
- * Created <code>DateTimeWithZoneOffset</code> objects are frozen with {@link Object#freeze()} in constructor and thus immutable.
+ * Created <code>DateTime</code> objects are frozen with {@link Object#freeze()} in constructor and thus immutable.
  */
-export class DateTimeWithZoneOffset {
+export class DateTime {
 
   /**
    * @constructor
-   * @param {Integer|number} year the year for the new local date.
-   * @param {Integer|number} month the month for the new local date.
-   * @param {Integer|number} day the day for the new local date.
-   * @param {Integer|number} hour the hour for the new local time.
-   * @param {Integer|number} minute the minute for the new local time.
-   * @param {Integer|number} second the second for the new local time.
-   * @param {Integer|number} nanosecond the nanosecond for the new local time.
-   * @param {Integer|number} offsetSeconds the timezone offset in seconds for the new timezone-aware date-time.
+   * @param {Integer|number} year the year for the new date-time.
+   * @param {Integer|number} month the month for the new date-time.
+   * @param {Integer|number} day the day for the new date-time.
+   * @param {Integer|number} hour the hour for the new date-time.
+   * @param {Integer|number} minute the minute for the new date-time.
+   * @param {Integer|number} second the second for the new date-time.
+   * @param {Integer|number} nanosecond the nanosecond for the new date-time.
+   * @param {Integer|number|null} timeZoneOffsetSeconds the total time zone offset in seconds for the new date-time. Either this argument or <code>timeZoneId</code> should be defined.
+   * @param {string|null} timeZoneId the time zone id for the new date-time. Either this argument or <code>timeZoneOffsetSeconds</code> should be defined.
    */
-  constructor(year, month, day, hour, minute, second, nanosecond, offsetSeconds) {
+  constructor(year, month, day, hour, minute, second, nanosecond, timeZoneOffsetSeconds, timeZoneId) {
     this.year = year;
     this.month = month;
     this.day = day;
     this.hour = hour;
     this.minute = minute;
     this.second = second;
     this.nanosecond = nanosecond;
-    this.offsetSeconds = offsetSeconds;
-    Object.freeze(this);
-  }
 
-  toString() {
-    return localDateTimeToString(this.year, this.month, this.day, this.hour, this.minute, this.second, this.nanosecond) +
-      timeZoneOffsetToIsoString(this.offsetSeconds);
-  }
-}
-
-Object.defineProperty(DateTimeWithZoneOffset.prototype, DATE_TIME_WITH_ZONE_OFFSET_IDENTIFIER_PROPERTY, IDENTIFIER_PROPERTY_ATTRIBUTES);
-
-/**
- * Test if given object is an instance of {@link DateTimeWithZoneOffset} class.
- * @param {object} obj the object to test.
- * @return {boolean} <code>true</code> if given object is a {@link DateTimeWithZoneOffset}, <code>false</code> otherwise.
- */
-export function isDateTimeWithZoneOffset(obj) {
-  return hasIdentifierProperty(obj, DATE_TIME_WITH_ZONE_OFFSET_IDENTIFIER_PROPERTY);
-}
-
-/**
- * Represents an instant capturing the date, the time and the timezone identifier.
- * Created <code>DateTimeWithZoneId</code> objects are frozen with {@link Object#freeze()} in constructor and thus immutable.
- */
-export class DateTimeWithZoneId {
+    const [offset, id] = verifyTimeZoneArguments(timeZoneOffsetSeconds, timeZoneId);
+    this.timeZoneOffsetSeconds = offset;
+    this.timeZoneId = id;
 
-  /**
-   * @constructor
-   * @param {Integer|number} year the year for the new local date.
-   * @param {Integer|number} month the month for the new local date.
-   * @param {Integer|number} day the day for the new local date.
-   * @param {Integer|number} hour the hour for the new local time.
-   * @param {Integer|number} minute the minute for the new local time.
-   * @param {Integer|number} second the second for the new local time.
-   * @param {Integer|number} nanosecond the nanosecond for the new local time.
-   * @param {string} zoneId the timezone identifier for the new timezone-aware date-time.
-   */
-  constructor(year, month, day, hour, minute, second, nanosecond, zoneId) {
-    this.year = year;
-    this.month = month;
-    this.day = day;
-    this.hour = hour;
-    this.minute = minute;
-    this.second = second;
-    this.nanosecond = nanosecond;
-    this.zoneId = zoneId;
     Object.freeze(this);
   }
 
   toString() {
-    return localDateTimeToString(this.year, this.month, this.day, this.hour, this.minute, this.second, this.nanosecond) + `[${this.zoneId}]`;
+    const localDateTimeStr = localDateTimeToString(this.year, this.month, this.day, this.hour, this.minute, this.second, this.nanosecond);
+    const timeZoneStr = this.timeZoneId ? `[${this.timeZoneId}]` : timeZoneOffsetToIsoString(this.timeZoneOffsetSeconds);
+    return localDateTimeStr + timeZoneStr;
   }
 }
 
-Object.defineProperty(DateTimeWithZoneId.prototype, DATE_TIME_WITH_ZONE_ID_IDENTIFIER_PROPERTY, IDENTIFIER_PROPERTY_ATTRIBUTES);
+Object.defineProperty(DateTime.prototype, DATE_TIME_IDENTIFIER_PROPERTY, IDENTIFIER_PROPERTY_ATTRIBUTES);
 
 /**
- * Test if given object is an instance of {@link DateTimeWithZoneId} class.
+ * Test if given object is an instance of {@link DateTime} class.
  * @param {object} obj the object to test.
- * @return {boolean} <code>true</code> if given object is a {@link DateTimeWithZoneId}, <code>false</code> otherwise.
+ * @return {boolean} <code>true</code> if given object is a {@link DateTime}, <code>false</code> otherwise.
  */
-export function isDateTimeWithZoneId(obj) {
-  return hasIdentifierProperty(obj, DATE_TIME_WITH_ZONE_ID_IDENTIFIER_PROPERTY);
+export function isDateTime(obj) {
+  return hasIdentifierProperty(obj, DATE_TIME_IDENTIFIER_PROPERTY);
 }
 
 function hasIdentifierProperty(obj, property) {
@@ -322,3 +283,18 @@ function hasIdentifierProperty(obj, property) {
 function localDateTimeToString(year, month, day, hour, minute, second, nanosecond) {
   return dateToIsoString(year, month, day) + 'T' + timeToIsoString(hour, minute, second, nanosecond);
 }
+
+function verifyTimeZoneArguments(timeZoneOffsetSeconds, timeZoneId) {
+  const offsetDefined = timeZoneOffsetSeconds || timeZoneOffsetSeconds === 0;
+  const idDefined = timeZoneId && timeZoneId !== '';
+
+  if (offsetDefined && !idDefined) {
+    return [timeZoneOffsetSeconds, null];
+  } else if (!offsetDefined && idDefined) {
+    return [null, timeZoneId];
+  } else if (offsetDefined && idDefined) {
+    throw newError(`Unable to create DateTime with both time zone offset and id. Please specify either of them. Given offset: ${timeZoneOffsetSeconds} and id: ${timeZoneId}`);
+  } else {
+    throw newError(`Unable to create DateTime without either time zone offset or id. Please specify either of them. Given offset: ${timeZoneOffsetSeconds} and id: ${timeZoneId}`);
+  }
+}