Added toString() to temporal types

It returns ISO strings for every temporal type except DateTime with
time zone ID. Later is formatted to an ISO date-time and time zone ID is
appended in square brackets. Ideally driver would also include offset
but there is no way to get it without a third-party library. Offset
might be included in future.

Author: lutovich

src/v1/internal/temporal-util.js

@@ -169,6 +169,86 @@ export function epochDayToCypherDate(epochDay) {
   return new CypherDate(year, month, day);
 }
 
+/**
+ * Format given duration to an ISO 8601 string.
+ * @param {Integer|number} months the number of months.
+ * @param {Integer|number} days the number of days.
+ * @param {Integer|number} seconds the number of seconds.
+ * @param {Integer|number} nanoseconds the number of nanoseconds.
+ * @return {string} ISO string that represents given duration.
+ */
+export function durationToIsoString(months, days, seconds, nanoseconds) {
+  const monthsString = formatNumber(months);
+  const daysString = formatNumber(days);
+  const secondsString = formatNumber(seconds);
+  const nanosecondsString = formatNumber(nanoseconds, 9);
+  return `P${monthsString}M${daysString}DT${secondsString}.${nanosecondsString}S`;
+}
+
+/**
+ * Formats given time to an ISO 8601 string.
+ * @param {Integer|number} hour the hour value.
+ * @param {Integer|number} minute the minute value.
+ * @param {Integer|number} second the second value.
+ * @param {Integer|number} nanosecond the nanosecond value.
+ * @return {string} ISO string that represents given time.
+ */
+export function timeToIsoString(hour, minute, second, nanosecond) {
+  const hourString = formatNumber(hour, 2);
+  const minuteString = formatNumber(minute, 2);
+  const secondString = formatNumber(second, 2);
+  const nanosecondString = formatNumber(nanosecond, 9);
+  return `${hourString}:${minuteString}:${secondString}.${nanosecondString}`;
+}
+
+/**
+ * Formats given time zone offset in seconds to string representation like '±HH:MM', '±HH:MM:SS' or 'Z' for UTC.
+ * @param {Integer|number} offsetSeconds the offset in seconds.
+ * @return {string} ISO string that represents given offset.
+ */
+export function timeZoneOffsetToIsoString(offsetSeconds) {
+  offsetSeconds = int(offsetSeconds);
+  if (offsetSeconds.equals(0)) {
+    return 'Z';
+  }
+
+  const isNegative = offsetSeconds.isNegative();
+  if (isNegative) {
+    offsetSeconds = offsetSeconds.multiply(-1);
+  }
+  const signPrefix = isNegative ? '-' : '+';
+
+  const hours = formatNumber(offsetSeconds.div(SECONDS_PER_HOUR), 2);
+  const minutes = formatNumber(offsetSeconds.div(SECONDS_PER_MINUTE).modulo(MINUTES_PER_HOUR), 2);
+  let secondsValue = offsetSeconds.modulo(SECONDS_PER_MINUTE);
+  const seconds = secondsValue.equals(0) ? null : formatNumber(secondsValue, 2);
+
+  return seconds ? `${signPrefix}${hours}:${minutes}:${seconds}` : `${signPrefix}${hours}:${minutes}`;
+}
+
+/**
+ * Formats given date to an ISO 8601 string.
+ * @param {Integer|number} year the date year.
+ * @param {Integer|number} month the date month.
+ * @param {Integer|number} day the date day.
+ * @return {string} ISO string that represents given date.
+ */
+export function dateToIsoString(year, month, day) {
+  year = int(year);
+  const isNegative = year.isNegative();
+  if (isNegative) {
+    year = year.multiply(-1);
+  }
+  let yearString = year.toString().padStart(4, '0');
+  if (isNegative) {
+    yearString = '-' + yearString;
+  }
+
+  const monthString = formatNumber(month, 2);
+  const dayString = formatNumber(day, 2);
+  return `${yearString}-${monthString}-${dayString}`;
+}
+
 /**
  * Converts given cypher local time into a single integer representing this same time in seconds of the day. Nanoseconds are skipped.
  * @param {CypherLocalTime} localTime the time to convert.
@@ -231,3 +311,13 @@ function floorMod(x, y) {
 
   return x.subtract(floorDiv(x, y).multiply(y));
 }
+
+/**
+ * @param {Integer|number} 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, stringLength = undefined) {
+  const result = int(num).toString();
+  return stringLength ? result.padStart(stringLength, '0') : result;
+}

src/v1/temporal-types.js

@@ -17,6 +17,8 @@
  * limitations under the License.
  */
 
+import {dateToIsoString, durationToIsoString, timeToIsoString, timeZoneOffsetToIsoString} from './internal/temporal-util';
+
 const IDENTIFIER_PROPERTY_ATTRIBUTES = {
   value: true,
   enumerable: false,
@@ -51,6 +53,10 @@ export class CypherDuration {
     this.nanoseconds = nanoseconds;
     Object.freeze(this);
   }
+
+  toString() {
+    return durationToIsoString(this.months, this.days, this.seconds, this.nanoseconds);
+  }
 }
 
 Object.defineProperty(CypherDuration.prototype, CYPHER_DURATION_IDENTIFIER_PROPERTY, IDENTIFIER_PROPERTY_ATTRIBUTES);
@@ -84,6 +90,10 @@ export class CypherLocalTime {
     this.nanosecond = nanosecond;
     Object.freeze(this);
   }
+
+  toString() {
+    return timeToIsoString(this.hour, this.minute, this.second, this.nanosecond);
+  }
 }
 
 Object.defineProperty(CypherLocalTime.prototype, CYPHER_LOCAL_TIME_IDENTIFIER_PROPERTY, IDENTIFIER_PROPERTY_ATTRIBUTES);
@@ -113,6 +123,10 @@ export class CypherTime {
     this.offsetSeconds = offsetSeconds;
     Object.freeze(this);
   }
+
+  toString() {
+    return this.localTime.toString() + timeZoneOffsetToIsoString(this.offsetSeconds);
+  }
 }
 
 Object.defineProperty(CypherTime.prototype, CYPHER_TIME_IDENTIFIER_PROPERTY, IDENTIFIER_PROPERTY_ATTRIBUTES);
@@ -144,6 +158,10 @@ export class CypherDate {
     this.day = day;
     Object.freeze(this);
   }
+
+  toString() {
+    return dateToIsoString(this.year, this.month, this.day);
+  }
 }
 
 Object.defineProperty(CypherDate.prototype, CYPHER_DATE_IDENTIFIER_PROPERTY, IDENTIFIER_PROPERTY_ATTRIBUTES);
@@ -173,6 +191,10 @@ export class CypherLocalDateTime {
     this.localTime = localTime;
     Object.freeze(this);
   }
+
+  toString() {
+    return `${this.localDate.toString()}T${this.localTime.toString()}`;
+  }
 }
 
 Object.defineProperty(CypherLocalDateTime.prototype, CYPHER_LOCAL_DATE_TIME_IDENTIFIER_PROPERTY, IDENTIFIER_PROPERTY_ATTRIBUTES);
@@ -202,6 +224,10 @@ export class CypherDateTimeWithZoneOffset {
     this.offsetSeconds = offsetSeconds;
     Object.freeze(this);
   }
+
+  toString() {
+    return this.localDateTime.toString() + timeZoneOffsetToIsoString(this.offsetSeconds);
+  }
 }
 
 Object.defineProperty(CypherDateTimeWithZoneOffset.prototype, CYPHER_DATE_TIME_WITH_ZONE_OFFSET_IDENTIFIER_PROPERTY, IDENTIFIER_PROPERTY_ATTRIBUTES);
@@ -231,6 +257,10 @@ export class CypherDateTimeWithZoneId {
     this.zoneId = zoneId;
     Object.freeze(this);
   }
+
+  toString() {
+    return `${this.localDateTime.toString()}[${this.zoneId}]`;
+  }
 }
 
 Object.defineProperty(CypherDateTimeWithZoneId.prototype, CYPHER_DATE_TIME_WITH_ZONE_ID_IDENTIFIER_PROPERTY, IDENTIFIER_PROPERTY_ATTRIBUTES);

test/v1/temporal-types.test.js

@@ -342,6 +342,50 @@ describe('temporal-types', () => {
     testSendAndReceiveRandomTemporalValues(valueGenerator, done);
   });
 
+  it('should convert Duration to ISO string', () => {
+    expect(duration(13, 62, 3, 999111999).toString()).toEqual('P13M62DT3.999111999S');
+    expect(duration(0, 0, 0, 0).toString()).toEqual('P0M0DT0.000000000S');
+    expect(duration(-1, -2, 10, 10).toString()).toEqual('P-1M-2DT10.000000010S');
+  });
+
+  it('should convert LocalTime to ISO string', () => {
+    expect(localTime(12, 19, 39, 111222333).toString()).toEqual('12:19:39.111222333');
+    expect(localTime(3, 59, 2, 17).toString()).toEqual('03:59:02.000000017');
+    expect(localTime(0, 0, 0, 0).toString()).toEqual('00:00:00.000000000');
+  });
+
+  it('should convert Time to ISO string', () => {
+    expect(time(11, 45, 22, 333222111, 9015).toString()).toEqual('11:45:22.333222111+02:30:15');
+    expect(time(23, 2, 1, 10, 0).toString()).toEqual('23:02:01.000000010Z');
+    expect(time(0, 12, 59, 0, -40500).toString()).toEqual('00:12:59.000000000-11:15');
+    expect(time(21, 59, 0, 123, -25200).toString()).toEqual('21:59:00.000000123-07:00');
+  });
+
+  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');
+  });
+
+  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');
+    expect(localDateTime(0, 0, 0, 0, 0, 0, 1).toString()).toEqual('0000-00-00T00:00:00.000000001');
+  });
+
+  it('should convert DateTime with time zone offset to ISO string', () => {
+    expect(dateTimeWithZoneOffset(2025, 9, 17, 23, 22, 21, 999888, 37800).toString()).toEqual('2025-09-17T23:22:21.000999888+10:30');
+    expect(dateTimeWithZoneOffset(1, 2, 3, 4, 5, 6, 7, -49376).toString()).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');
+  });
+
+  it('should convert DateTime with time zone id to ISO-like string', () => {
+    expect(dateTimeWithZoneId(1949, 10, 7, 6, 10, 15, 15000000, 'Europe/Zaporozhye').toString()).toEqual('1949-10-07T06:10:15.015000000[Europe/Zaporozhye]');
+    expect(dateTimeWithZoneId(-30455, 5, 5, 12, 24, 10, 123, 'Asia/Yangon').toString()).toEqual('-30455-05-05T12:24:10.000000123[Asia/Yangon]');
+    expect(dateTimeWithZoneId(248, 12, 30, 23, 59, 59, 3, 'CET').toString()).toEqual('0248-12-30T23:59:59.000000003[CET]');
+  });
+
   function testSendAndReceiveRandomTemporalValues(valueGenerator, done) {
     const asyncFunction = (index, callback) => {
       const next = () => callback();