feat: Add support for Interval (#2192)

* feat(spanner): add support for interval * skip interval tests only in emulator * Addressed PR comments * Added tests for null and undefined values * fixed lint failure --------- Co-authored-by: Sagar Agarwal <sagarwaal@google.com>

Author: sagarwaal

src/codec.ts

@@ -394,6 +394,323 @@ export class PGOid extends WrappedNumber {
  }
 }
 
+/**
+ * @typedef Interval
+ * @see Spanner.interval
+ */
+export class Interval {
+ private months: number;
+ private days: number;
+ private nanoseconds: bigint;
+
+ // Regex to parse ISO8601 duration format: P[n]Y[n]M[n]DT[n]H[n]M[n][.fffffffff]S
+ // Only seconds can be fractional, and can have at most 9 digits after decimal point.
+ // Both '.' and ',' are considered valid decimal point.
+ private static readonly ISO8601_PATTERN: RegExp =
+ /^P(?!$)(-?\d+Y)?(-?\d+M)?(-?\d+D)?(T(?=-?[.,]?\d)(-?\d+H)?(-?\d+M)?(-?(((\d+)([.,]\d{1,9})?)|([.,]\d{1,9}))S)?)?$/;
+
+ static readonly MONTHS_PER_YEAR: number = 12;
+ static readonly DAYS_PER_MONTH: number = 30;
+ static readonly HOURS_PER_DAY: number = 24;
+ static readonly MINUTES_PER_HOUR: number = 60;
+ static readonly SECONDS_PER_MINUTE: number = 60;
+ static readonly SECONDS_PER_HOUR: number =
+ Interval.MINUTES_PER_HOUR * Interval.SECONDS_PER_MINUTE;
+ static readonly MILLISECONDS_PER_SECOND: number = 1000;
+ static readonly MICROSECONDS_PER_MILLISECOND: number = 1000;
+ static readonly NANOSECONDS_PER_MICROSECOND: number = 1000;
+ static readonly NANOSECONDS_PER_MILLISECOND: number =
+ Interval.MICROSECONDS_PER_MILLISECOND *
+ Interval.NANOSECONDS_PER_MICROSECOND;
+ static readonly NANOSECONDS_PER_SECOND: number =
+ Interval.MILLISECONDS_PER_SECOND *
+ Interval.MICROSECONDS_PER_MILLISECOND *
+ Interval.NANOSECONDS_PER_MICROSECOND;
+ static readonly NANOSECONDS_PER_DAY: bigint =
+ BigInt(Interval.HOURS_PER_DAY) *
+ BigInt(Interval.SECONDS_PER_HOUR) *
+ BigInt(Interval.NANOSECONDS_PER_SECOND);
+ static readonly NANOSECONDS_PER_MONTH: bigint =
+ BigInt(Interval.DAYS_PER_MONTH) * Interval.NANOSECONDS_PER_DAY;
+ static readonly ZERO: Interval = new Interval(0, 0, BigInt(0));
+
+ /**
+ * @param months months part of the `Interval`
+ * @param days days part of the `Interval`
+ * @param nanoseconds nanoseconds part of the `Interval`
+ */
+ constructor(months: number, days: number, nanoseconds: bigint) {
+ if (!is.integer(months)) {
+ throw new GoogleError(
+ `Invalid months: ${months}, months should be an integral value`
+ );
+ }
+
+ if (!is.integer(days)) {
+ throw new GoogleError(
+ `Invalid days: ${days}, days should be an integral value`
+ );
+ }
+
+ if (is.null(nanoseconds) || is.undefined(nanoseconds)) {
+ throw new GoogleError(
+ `Invalid nanoseconds: ${nanoseconds}, nanoseconds should be a valid bigint value`
+ );
+ }
+
+ this.months = months;
+ this.days = days;
+ this.nanoseconds = nanoseconds;
+ }
+
+ /**
+ * @returns months part of the `Interval`.
+ */
+ getMonths(): number {
+ return this.months;
+ }
+
+ /**
+ * @returns days part of the `Interval`.
+ */
+ getDays(): number {
+ return this.days;
+ }
+
+ /**
+ * @returns nanoseconds part of the `Interval`.
+ */
+ getNanoseconds(): bigint {
+ return this.nanoseconds;
+ }
+
+ /**
+ * Constructs an `Interval` with specified months.
+ */
+ static fromMonths(months: number): Interval {
+ return new Interval(months, 0, BigInt(0));
+ }
+
+ /**
+ * Constructs an `Interval` with specified days.
+ */
+ static fromDays(days: number): Interval {
+ return new Interval(0, days, BigInt(0));
+ }
+
+ /**
+ * Constructs an `Interval` with specified seconds.
+ */
+ static fromSeconds(seconds: number): Interval {
+ if (!is.integer(seconds)) {
+ throw new GoogleError(
+ `Invalid seconds: ${seconds}, seconds should be an integral value`
+ );
+ }
+ return new Interval(
+ 0,
+ 0,
+ BigInt(Interval.NANOSECONDS_PER_SECOND) * BigInt(seconds)
+ );
+ }
+
+ /**
+ * Constructs an `Interval` with specified milliseconds.
+ */
+ static fromMilliseconds(milliseconds: number): Interval {
+ if (!is.integer(milliseconds)) {
+ throw new GoogleError(
+ `Invalid milliseconds: ${milliseconds}, milliseconds should be an integral value`
+ );
+ }
+ return new Interval(
+ 0,
+ 0,
+ BigInt(Interval.NANOSECONDS_PER_MILLISECOND) * BigInt(milliseconds)
+ );
+ }
+
+ /**
+ * Constructs an `Interval` with specified microseconds.
+ */
+ static fromMicroseconds(microseconds: number): Interval {
+ if (!is.integer(microseconds)) {
+ throw new GoogleError(
+ `Invalid microseconds: ${microseconds}, microseconds should be an integral value`
+ );
+ }
+ return new Interval(
+ 0,
+ 0,
+ BigInt(Interval.NANOSECONDS_PER_MICROSECOND) * BigInt(microseconds)
+ );
+ }
+
+ /**
+ * Constructs an `Interval` with specified nanoseconds.
+ */
+ static fromNanoseconds(nanoseconds: bigint): Interval {
+ return new Interval(0, 0, nanoseconds);
+ }
+
+ /**
+ * Constructs an Interval from ISO8601 duration format: `P[n]Y[n]M[n]DT[n]H[n]M[n][.fffffffff]S`.
+ * Only seconds can be fractional, and can have at most 9 digits after decimal point.
+ * Both '.' and ',' are considered valid decimal point.
+ */
+ static fromISO8601(isoString: string): Interval {
+ const matcher = Interval.ISO8601_PATTERN.exec(isoString);
+ if (!matcher) {
+ throw new GoogleError(`Invalid ISO8601 duration string: ${isoString}`);
+ }
+
+ const getNullOrDefault = (groupIdx: number): string =>
+ matcher[groupIdx] === undefined ? '0' : matcher[groupIdx];
+ const years: number = parseInt(getNullOrDefault(1).replace('Y', ''));
+ const months: number = parseInt(getNullOrDefault(2).replace('M', ''));
+ const days: number = parseInt(getNullOrDefault(3).replace('D', ''));
+ const hours: number = parseInt(getNullOrDefault(5).replace('H', ''));
+ const minutes: number = parseInt(getNullOrDefault(6).replace('M', ''));
+ const seconds: Big = Big(
+ getNullOrDefault(7).replace('S', '').replace(',', '.')
+ );
+
+ const totalMonths: number = Big(years)
+ .mul(Big(Interval.MONTHS_PER_YEAR))
+ .add(Big(months))
+ .toNumber();
+ if (!Number.isSafeInteger(totalMonths)) {
+ throw new GoogleError(
+ 'Total months is outside of the range of safe integer'
+ );
+ }
+
+ const totalNanoseconds = BigInt(
+ seconds
+ .add(
+ Big((BigInt(hours) * BigInt(Interval.SECONDS_PER_HOUR)).toString())
+ )
+ .add(
+ Big(
+ (BigInt(minutes) * BigInt(Interval.SECONDS_PER_MINUTE)).toString()
+ )
+ )
+ .mul(Big(this.NANOSECONDS_PER_SECOND))
+ .toString()
+ );
+
+ return new Interval(totalMonths, days, totalNanoseconds);
+ }
+
+ /**
+ * @returns string representation of Interval in ISO8601 duration format: `P[n]Y[n]M[n]DT[n]H[n]M[n][.fffffffff]S`
+ */
+ toISO8601(): string {
+ if (this.equals(Interval.ZERO)) {
+ return 'P0Y';
+ }
+
+ // months part is normalized to years and months.
+ let result = 'P';
+ if (this.months !== 0) {
+ const years_part: number = Math.trunc(
+ this.months / Interval.MONTHS_PER_YEAR
+ );
+ const months_part: number =
+ this.months - years_part * Interval.MONTHS_PER_YEAR;
+ if (years_part !== 0) {
+ result += `${years_part}Y`;
+ }
+ if (months_part !== 0) {
+ result += `${months_part}M`;
+ }
+ }
+
+ if (this.days !== 0) {
+ result += `${this.days}D`;
+ }
+
+ // Nanoseconds part is normalized to hours, minutes and nanoseconds.
+ if (this.nanoseconds !== BigInt(0)) {
+ result += 'T';
+ let nanoseconds: bigint = this.nanoseconds;
+ const hours_part: bigint =
+ nanoseconds /
+ BigInt(Interval.NANOSECONDS_PER_SECOND * Interval.SECONDS_PER_HOUR);
+ nanoseconds =
+ nanoseconds -
+ hours_part *
+ BigInt(Interval.NANOSECONDS_PER_SECOND * Interval.SECONDS_PER_HOUR);
+
+ const minutes_part: bigint =
+ nanoseconds /
+ BigInt(Interval.NANOSECONDS_PER_SECOND * Interval.SECONDS_PER_MINUTE);
+ nanoseconds =
+ nanoseconds -
+ minutes_part *
+ BigInt(Interval.NANOSECONDS_PER_SECOND * Interval.SECONDS_PER_MINUTE);
+ const zero_bigint = BigInt(0);
+ if (hours_part !== zero_bigint) {
+ result += `${hours_part}H`;
+ }
+
+ if (minutes_part !== zero_bigint) {
+ result += `${minutes_part}M`;
+ }
+
+ let sign = '';
+ if (nanoseconds < zero_bigint) {
+ sign = '-';
+ nanoseconds = -nanoseconds;
+ }
+
+ // Nanoseconds are converted to seconds and fractional part.
+ const seconds_part: bigint =
+ nanoseconds / BigInt(Interval.NANOSECONDS_PER_SECOND);
+ nanoseconds =
+ nanoseconds - seconds_part * BigInt(Interval.NANOSECONDS_PER_SECOND);
+ if (seconds_part !== zero_bigint || nanoseconds !== zero_bigint) {
+ result += `${sign}${seconds_part}`;
+ if (nanoseconds !== zero_bigint) {
+ // Fractional part is kept in a group of 3
+ // For e.g.: PT0.5S will be normalized to PT0.500S
+ result += `.${nanoseconds
+ .toString()
+ .padStart(9, '0')
+ .replace(/(0{3})+$/, '')}`;
+ }
+ result += 'S';
+ }
+ }
+
+ return result;
+ }
+
+ equals(other: Interval): boolean {
+ if (!other) {
+ return false;
+ }
+
+ return (
+ this.months === other.months &&
+ this.days === other.days &&
+ this.nanoseconds === other.nanoseconds
+ );
+ }
+
+ valueOf(): Interval {
+ return this;
+ }
+
+ /**
+ * @returns JSON representation for Interval.
+ * Interval is represented in ISO8601 duration format string in JSON.
+ */
+ toJSON(): string {
+ return this.toISO8601().toString();
+ }
+}
+
 /**
  * @typedef JSONOptions
  * @property {boolean} [wrapNumbers=false] Indicates if the numbers should be
@@ -581,6 +898,10 @@ function decode(
  }
  decoded = JSON.parse(decoded);
  break;
+ case spannerClient.spanner.v1.TypeCode.INTERVAL:
+ case 'INTERVAL':
+ decoded = Interval.fromISO8601(decoded);
+ break;
  case spannerClient.spanner.v1.TypeCode.ARRAY:
  case 'ARRAY':
  decoded = decoded.map(value => {
@@ -677,6 +998,10 @@ function encodeValue(value: Value): Value {
  return value.toString();
  }
 
+ if (value instanceof Interval) {
+ return value.toISO8601();
+ }
+
  if (is.object(value)) {
  return JSON.stringify(value);
  }
@@ -707,6 +1032,7 @@ const TypeCode: {
  bytes: 'BYTES',
  json: 'JSON',
  jsonb: 'JSON',
+ interval: 'INTERVAL',
  proto: 'PROTO',
  enum: 'ENUM',
  array: 'ARRAY',
@@ -745,6 +1071,7 @@ interface FieldType extends Type {
  * - string
  * - bytes
  * - json
+ * - interval
  * - proto
  * - enum
  * - timestamp
@@ -802,6 +1129,10 @@ function getType(value: Value): Type {
  return {type: 'pgOid'};
  }
 
+ if (value instanceof Interval) {
+ return {type: 'interval'};
+ }
+
  if (value instanceof ProtoMessage) {
  return {type: 'proto', fullName: value.fullName};
  }
@@ -978,6 +1309,7 @@ export const codec = {
  ProtoMessage,
  ProtoEnum,
  PGOid,
+ Interval,
  convertFieldsToJson,
  decode,
  encode,