Turn all temporal types into flat objects

Previously some temporal types were modeled as a combination of other
temporal types. For example `Time` contained an instance of `LocalTime`
and an offset in seconds. This made constructors more complicated and
getters needed to access nested properties. For example `Time.hour`
would need to be accessed as `Time.localTime.hour`.

This commit makes `Time`, `LocalDateTime`, `DateTimeWithZoneOffset`
and `DateTimeWithZoneId` contain primitive properties and not use
other temporal types as building blocks. Also made all properties of
spatial and temporal types readonly in TypeScript declarations.

Author: lutovich

src/v1/internal/packstream-v2.js

@@ -24,22 +24,22 @@ import {
   DateTimeWithZoneId,
   DateTimeWithZoneOffset,
   Duration,
-  Time,
   isDate,
   isDateTimeWithZoneId,
   isDateTimeWithZoneOffset,
   isDuration,
   isLocalDateTime,
   isLocalTime,
-  isTime
+  isTime,
+  Time
 } from '../temporal-types';
 import {int} from '../integer';
 import {
   dateToEpochDay,
-  localDateTimeToEpochSecond,
-  localTimeToNanoOfDay,
   epochDayToDate,
   epochSecondAndNanoToLocalDateTime,
+  localDateTimeToEpochSecond,
+  localTimeToNanoOfDay,
   nanoOfDayToLocalTime
 } from '../internal/temporal-util';
 
@@ -143,6 +143,12 @@ export class Unpacker extends v1.Unpacker {
   }
 }
 
+/**
+ * Pack given 2D or 3D point.
+ * @param {Point} point the point value to pack.
+ * @param {Packer} packer the packer to use.
+ * @param {function} onError the error callback.
+ */
 function packPoint(point, packer, onError) {
   const is2DPoint = point.z === null || point.z === undefined;
   if (is2DPoint) {
@@ -152,6 +158,12 @@ function packPoint(point, packer, onError) {
   }
 }
 
+/**
+ * Pack given 2D point.
+ * @param {Point} point the point value to pack.
+ * @param {Packer} packer the packer to use.
+ * @param {function} onError the error callback.
+ */
 function packPoint2D(point, packer, onError) {
   const packableStructFields = [
     packer.packable(int(point.srid), onError),
@@ -161,6 +173,12 @@ function packPoint2D(point, packer, onError) {
   packer.packStruct(POINT_2D, packableStructFields, onError);
 }
 
+/**
+ * Pack given 3D point.
+ * @param {Point} point the point value to pack.
+ * @param {Packer} packer the packer to use.
+ * @param {function} onError the error callback.
+ */
 function packPoint3D(point, packer, onError) {
   const packableStructFields = [
     packer.packable(int(point.srid), onError),
@@ -171,6 +189,13 @@ function packPoint3D(point, packer, onError) {
   packer.packStruct(POINT_3D, packableStructFields, onError);
 }
 
+/**
+ * Unpack 2D point value using the given unpacker.
+ * @param {Unpacker} unpacker the unpacker to use.
+ * @param {number} structSize the retrieved struct size.
+ * @param {BaseBuffer} buffer the buffer to unpack from.
+ * @return {Point} the unpacked 2D point value.
+ */
 function unpackPoint2D(unpacker, structSize, buffer) {
   unpacker._verifyStructSize('Point2D', POINT_2D_STRUCT_SIZE, structSize);
 
@@ -182,6 +207,13 @@ function unpackPoint2D(unpacker, structSize, buffer) {
   );
 }
 
+/**
+ * Unpack 3D point value using the given unpacker.
+ * @param {Unpacker} unpacker the unpacker to use.
+ * @param {number} structSize the retrieved struct size.
+ * @param {BaseBuffer} buffer the buffer to unpack from.
+ * @return {Point} the unpacked 3D point value.
+ */
 function unpackPoint3D(unpacker, structSize, buffer) {
   unpacker._verifyStructSize('Point3D', POINT_3D_STRUCT_SIZE, structSize);
 
@@ -193,6 +225,12 @@ function unpackPoint3D(unpacker, structSize, buffer) {
   );
 }
 
+/**
+ * Pack given duration.
+ * @param {Duration} value the duration value to pack.
+ * @param {Packer} packer the packer to use.
+ * @param {function} onError the error callback.
+ */
 function packDuration(value, packer, onError) {
   const months = int(value.months);
   const days = int(value.days);
@@ -208,6 +246,13 @@ function packDuration(value, packer, onError) {
   packer.packStruct(DURATION, packableStructFields, onError);
 }
 
+/**
+ * Unpack duration value using the given unpacker.
+ * @param {Unpacker} unpacker the unpacker to use.
+ * @param {number} structSize the retrieved struct size.
+ * @param {BaseBuffer} buffer the buffer to unpack from.
+ * @return {Duration} the unpacked duration value.
+ */
 function unpackDuration(unpacker, structSize, buffer) {
   unpacker._verifyStructSize('Duration', DURATION_STRUCT_SIZE, structSize);
 
@@ -219,15 +264,28 @@ function unpackDuration(unpacker, structSize, buffer) {
   return new Duration(months, days, seconds, nanoseconds);
 }
 
+/**
+ * Pack given local time.
+ * @param {LocalTime} value the local time value to pack.
+ * @param {Packer} packer the packer to use.
+ * @param {function} onError the error callback.
+ */
 function packLocalTime(value, packer, onError) {
-  const nanoOfDay = localTimeToNanoOfDay(value);
+  const nanoOfDay = localTimeToNanoOfDay(value.hour, value.minute, value.second, value.nanosecond);
 
   const packableStructFields = [
     packer.packable(nanoOfDay, onError)
   ];
   packer.packStruct(LOCAL_TIME, packableStructFields, onError);
 }
 
+/**
+ * Unpack local time value using the given unpacker.
+ * @param {Unpacker} unpacker the unpacker to use.
+ * @param {number} structSize the retrieved struct size.
+ * @param {BaseBuffer} buffer the buffer to unpack from.
+ * @return {LocalTime} the unpacked local time value.
+ */
 function unpackLocalTime(unpacker, structSize, buffer) {
   unpacker._verifyStructSize('LocalTime', LOCAL_TIME_STRUCT_SIZE, structSize);
 
@@ -242,7 +300,7 @@ function unpackLocalTime(unpacker, structSize, buffer) {
  * @param {function} onError the error callback.
  */
 function packTime(value, packer, onError) {
-  const nanoOfDay = localTimeToNanoOfDay(value.localTime);
+  const nanoOfDay = localTimeToNanoOfDay(value.hour, value.minute, value.second, value.nanosecond);
   const offsetSeconds = int(value.offsetSeconds);
 
   const packableStructFields = [
@@ -266,7 +324,7 @@ function unpackTime(unpacker, structSize, buffer) {
   const offsetSeconds = unpacker.unpack(buffer);
 
   const localTime = nanoOfDayToLocalTime(nanoOfDay);
-  return new Time(localTime, offsetSeconds);
+  return new Time(localTime.hour, localTime.minute, localTime.second, localTime.nanosecond, offsetSeconds);
 }
 
 /**
@@ -276,7 +334,7 @@ function unpackTime(unpacker, structSize, buffer) {
  * @param {function} onError the error callback.
  */
 function packDate(value, packer, onError) {
-  const epochDay = dateToEpochDay(value);
+  const epochDay = dateToEpochDay(value.year, value.month, value.day);
 
   const packableStructFields = [
     packer.packable(epochDay, onError)
@@ -305,8 +363,8 @@ function unpackDate(unpacker, structSize, buffer) {
  * @param {function} onError the error callback.
  */
 function packLocalDateTime(value, packer, onError) {
-  const epochSecond = localDateTimeToEpochSecond(value);
-  const nano = int(value.localTime.nanosecond);
+  const epochSecond = localDateTimeToEpochSecond(value.year, value.month, value.day, value.hour, value.minute, value.second, value.nanosecond);
+  const nano = int(value.nanosecond);
 
   const packableStructFields = [
     packer.packable(epochSecond, onError),
@@ -338,8 +396,8 @@ function unpackLocalDateTime(unpacker, structSize, buffer) {
  * @param {function} onError the error callback.
  */
 function packDateTimeWithZoneOffset(value, packer, onError) {
-  const epochSecond = localDateTimeToEpochSecond(value.localDateTime);
-  const nano = int(value.localDateTime.localTime.nanosecond);
+  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 packableStructFields = [
@@ -365,7 +423,8 @@ function unpackDateTimeWithZoneOffset(unpacker, structSize, buffer) {
   const offsetSeconds = unpacker.unpack(buffer);
 
   const localDateTime = epochSecondAndNanoToLocalDateTime(epochSecond, nano);
-  return new DateTimeWithZoneOffset(localDateTime, offsetSeconds);
+  return new DateTimeWithZoneOffset(localDateTime.year, localDateTime.month, localDateTime.day, localDateTime.hour,
+    localDateTime.minute, localDateTime.second, localDateTime.nanosecond, offsetSeconds);
 }
 
 /**
@@ -375,8 +434,8 @@ function unpackDateTimeWithZoneOffset(unpacker, structSize, buffer) {
  * @param {function} onError the error callback.
  */
 function packDateTimeWithZoneId(value, packer, onError) {
-  const epochSecond = localDateTimeToEpochSecond(value.localDateTime);
-  const nano = int(value.localDateTime.localTime.nanosecond);
+  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 packableStructFields = [
@@ -402,5 +461,6 @@ function unpackDateTimeWithZoneId(unpacker, structSize, buffer) {
   const zoneId = unpacker.unpack(buffer);
 
   const localDateTime = epochSecondAndNanoToLocalDateTime(epochSecond, nano);
-  return new DateTimeWithZoneId(localDateTime, zoneId);
+  return new DateTimeWithZoneId(localDateTime.year, localDateTime.month, localDateTime.day, localDateTime.hour,
+    localDateTime.minute, localDateTime.second, localDateTime.nanosecond, zoneId);
 }

src/v1/internal/temporal-util.js

@@ -43,14 +43,17 @@ const SECONDS_PER_DAY = 86400;
 
 /**
  * Converts given local time into a single integer representing this same time in nanoseconds of the day.
- * @param {LocalTime} localTime the time to convert.
+ * @param {Integer|number|string} hour the hour of the local time to convert.
+ * @param {Integer|number|string} minute the minute of the local time to convert.
+ * @param {Integer|number|string} second the second of the local time to convert.
+ * @param {Integer|number|string} nanosecond the nanosecond of the local time to convert.
  * @return {Integer} nanoseconds representing the given local time.
  */
-export function localTimeToNanoOfDay(localTime) {
-  const hour = int(localTime.hour);
-  const minute = int(localTime.minute);
-  const second = int(localTime.second);
-  const nanosecond = int(localTime.nanosecond);
+export function localTimeToNanoOfDay(hour, minute, second, nanosecond) {
+  hour = int(hour);
+  minute = int(minute);
+  second = int(second);
+  nanosecond = int(nanosecond);
 
   let totalNanos = hour.multiply(NANOS_PER_HOUR);
   totalNanos = totalNanos.add(minute.multiply(NANOS_PER_MINUTE));
@@ -80,15 +83,18 @@ export function nanoOfDayToLocalTime(nanoOfDay) {
 
 /**
  * Converts given local date time into a single integer representing this same time in epoch seconds UTC.
- * @param {LocalDateTime} localDateTime the local date time value to convert.
+ * @param {Integer|number|string} year the year of the local date-time to convert.
+ * @param {Integer|number|string} month the month of the local date-time to convert.
+ * @param {Integer|number|string} day the day of the local date-time to convert.
+ * @param {Integer|number|string} hour the hour of the local date-time to convert.
+ * @param {Integer|number|string} minute the minute of the local date-time to convert.
+ * @param {Integer|number|string} second the second of the local date-time to convert.
+ * @param {Integer|number|string} nanosecond the nanosecond of the local date-time to convert.
  * @return {Integer} epoch second in UTC representing the given local date time.
  */
-export function localDateTimeToEpochSecond(localDateTime) {
-  const localDate = localDateTime.localDate;
-  const localTime = localDateTime.localTime;
-
-  const epochDay = dateToEpochDay(localDate);
-  const localTimeSeconds = localTimeToSecondOfDay(localTime);
+export function localDateTimeToEpochSecond(year, month, day, hour, minute, second, nanosecond) {
+  const epochDay = dateToEpochDay(year, month, day);
+  const localTimeSeconds = localTimeToSecondOfDay(hour, minute, second);
   return epochDay.multiply(SECONDS_PER_DAY).add(localTimeSeconds);
 }
 
@@ -105,18 +111,20 @@ export function epochSecondAndNanoToLocalDateTime(epochSecond, nano) {
 
   const localDate = epochDayToDate(epochDay);
   const localTime = nanoOfDayToLocalTime(nanoOfDay);
-  return new LocalDateTime(localDate, localTime);
+  return new LocalDateTime(localDate.year, localDate.month, localDate.day, localTime.hour, localTime.minute, localTime.second, localTime.nanosecond);
 }
 
 /**
  * Converts given local date into a single integer representing it's epoch day.
- * @param {Date} date the date to convert.
+ * @param {Integer|number|string} year the year of the local date to convert.
+ * @param {Integer|number|string} month the month of the local date to convert.
+ * @param {Integer|number|string} day the day of the local date to convert.
  * @return {Integer} epoch day representing the given date.
  */
-export function dateToEpochDay(date) {
-  const year = int(date.year);
-  const month = int(date.month);
-  const day = int(date.day);
+export function dateToEpochDay(year, month, day) {
+  year = int(year);
+  month = int(month);
+  day = int(day);
 
   let epochDay = year.multiply(365);
 
@@ -171,10 +179,10 @@ export function epochDayToDate(epochDay) {
 
 /**
  * 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.
+ * @param {Integer|number|string} months the number of months.
+ * @param {Integer|number|string} days the number of days.
+ * @param {Integer|number|string} seconds the number of seconds.
+ * @param {Integer|number|string} nanoseconds the number of nanoseconds.
  * @return {string} ISO string that represents given duration.
  */
 export function durationToIsoString(months, days, seconds, nanoseconds) {
@@ -187,10 +195,10 @@ export function durationToIsoString(months, days, seconds, nanoseconds) {
 
 /**
  * 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.
+ * @param {Integer|number|string} hour the hour value.
+ * @param {Integer|number|string} minute the minute value.
+ * @param {Integer|number|string} second the second value.
+ * @param {Integer|number|string} nanosecond the nanosecond value.
  * @return {string} ISO string that represents given time.
  */
 export function timeToIsoString(hour, minute, second, nanosecond) {
@@ -203,7 +211,7 @@ export function timeToIsoString(hour, minute, second, nanosecond) {
 
 /**
  * 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.
+ * @param {Integer|number|string} offsetSeconds the offset in seconds.
  * @return {string} ISO string that represents given offset.
  */
 export function timeZoneOffsetToIsoString(offsetSeconds) {
@@ -228,9 +236,9 @@ export function timeZoneOffsetToIsoString(offsetSeconds) {
 
 /**
  * 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.
+ * @param {Integer|number|string} year the date year.
+ * @param {Integer|number|string} month the date month.
+ * @param {Integer|number|string} day the date day.
  * @return {string} ISO string that represents given date.
  */
 export function dateToIsoString(year, month, day) {
@@ -251,20 +259,21 @@ export function dateToIsoString(year, month, day) {
 
 /**
  * Converts given local time into a single integer representing this same time in seconds of the day. Nanoseconds are skipped.
- * @param {LocalTime} localTime the time to convert.
+ * @param {Integer|number|string} hour the hour of the local time.
+ * @param {Integer|number|string} minute the minute of the local time.
+ * @param {Integer|number|string} second the second of the local time.
  * @return {Integer} seconds representing the given local time.
  */
-function localTimeToSecondOfDay(localTime) {
-  const hour = int(localTime.hour);
-  const minute = int(localTime.minute);
-  const second = int(localTime.second);
+function localTimeToSecondOfDay(hour, minute, second) {
+  hour = int(hour);
+  minute = int(minute);
+  second = int(second);
 
   let totalSeconds = hour.multiply(SECONDS_PER_HOUR);
   totalSeconds = totalSeconds.add(minute.multiply(SECONDS_PER_MINUTE));
   return totalSeconds.add(second);
 }
 
-
 /**
  * Check if given year is a leap year. Uses algorithm described here {@link https://en.wikipedia.org/wiki/Leap_year#Algorithm}.
  * @param {Integer|number|string} year the year to check. Will be converted to {@link Integer} for all calculations.
@@ -313,7 +322,7 @@ function floorMod(x, y) {
 }
 
 /**
- * @param {Integer|number} num the number to format.
+ * @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.
  */