@fr0st/datetime 6.1.1 → 8.0.0

package/src/formatter/values.js

@@ -1,19 +1,20 @@
 import { getData, makeFormatter } from './../factory.js';
+import { valuesRegExp } from './../helpers.js';
 
 /**
- * DateFormatter Values
+ * Formatter value caches.
  */
 
 /**
- * Get cached day period values.
+ * Gets cached localized day-period labels.
  * @param {string} locale The locale.
  * @param {string} [type=long] The formatting type.
- * @return {array} The cached values.
+ * @return {string[]} The localized day-period labels.
  */
 export function getDayPeriods(locale, type = 'long') {
     return getData(
         `periods.${locale}.${type}`,
-        (_) => {
+        () => {
             const dayPeriodFormatter = makeFormatter(locale, { hour: 'numeric', hourCycle: 'h11' });
             return new Array(2)
                 .fill()
@@ -27,16 +28,16 @@ export function getDayPeriods(locale, type = 'long') {
 };
 
 /**
- * Get cached day values.
+ * Gets cached localized weekday labels.
  * @param {string} locale The locale.
  * @param {string} [type=long] The formatting type.
- * @param {Boolean} [standalone=true] Whether the values are standalone.
- * @return {array} The cached values.
+ * @param {boolean} [standalone=true] Whether the values are standalone.
+ * @return {string[]} The localized weekday labels.
  */
 export function getDays(locale, type = 'long', standalone = true) {
     return getData(
         `days.${locale}.${type}.${standalone}`,
-        (_) => {
+        () => {
             if (standalone) {
                 const dayFormatter = makeFormatter(locale, { weekday: type });
                 return new Array(7)
@@ -59,15 +60,15 @@ export function getDays(locale, type = 'long', standalone = true) {
 };
 
 /**
- * Get cached era values.
+ * Gets cached localized era labels.
  * @param {string} locale The locale.
  * @param {string} [type=long] The formatting type.
- * @return {array} The cached values.
+ * @return {string[]} The localized era labels.
  */
 export function getEras(locale, type = 'long') {
     return getData(
         `eras.${locale}.${type}`,
-        (_) => {
+        () => {
             const eraFormatter = makeFormatter(locale, { era: type });
             return new Array(2)
                 .fill()
@@ -81,16 +82,16 @@ export function getEras(locale, type = 'long') {
 };
 
 /**
- * Get cached month values.
+ * Gets cached localized month labels.
  * @param {string} locale The locale.
  * @param {string} [type=long] The formatting type.
- * @param {Boolean} [standalone=true] Whether the values are standalone.
- * @return {array} The cached values.
+ * @param {boolean} [standalone=true] Whether the values are standalone.
+ * @return {string[]} The localized month labels.
  */
 export function getMonths(locale, type = 'long', standalone = true) {
     return getData(
         `months.${locale}.${type}.${standalone}`,
-        (_) => {
+        () => {
             if (standalone) {
                 const monthFormatter = makeFormatter(locale, { month: type });
                 return new Array(12)
@@ -113,14 +114,14 @@ export function getMonths(locale, type = 'long', standalone = true) {
 };
 
 /**
- * Get cached number values.
+ * Gets cached localized digit glyphs.
  * @param {string} locale The locale.
- * @return {array} The cached values.
+ * @return {string[]} The localized digit glyphs.
  */
 export function getNumbers(locale) {
     return getData(
         `numbers.${locale}`,
-        (_) => {
+        () => {
             const numberFormatter = makeFormatter(locale, { minute: 'numeric' });
             return new Array(10)
                 .fill()
@@ -132,11 +133,14 @@ export function getNumbers(locale) {
 };
 
 /**
- * Get the RegExp for the number values.
+ * Gets the RegExp for the number values.
  * @param {string} locale The locale.
+ * @param {number|null} [length=null] The exact number of digits to match.
  * @return {string} The number values RegExp.
  */
-export function numberRegExp(locale) {
-    const numbers = getNumbers(locale).join('|');
-    return `(?:${numbers})+`;
+export function numberRegExp(locale, length = null) {
+    const quantifier = length === null ?
+        '+' :
+        `{${length}}`;
+    return `(?:${valuesRegExp(getNumbers(locale))})${quantifier}`;
 };

package/src/helpers.js

@@ -1,18 +1,49 @@
 import { getDateFormatter } from './factory.js';
 import { diffMethods, thresholds } from './vars.js';
 
+/** @typedef {import('./date-time.js').default} DateTime */
+
 /**
  * DateTime Helpers
  */
 
+/**
+ * Escapes a string for safe use inside a RegExp source.
+ * @param {string} value The string to escape.
+ * @return {string} The escaped string.
+ */
+function escapeRegExp(value) {
+    return value.replace(/[|\\{}()[\]^$+*?.-]/g, '\\$&');
+}
+
+/**
+ * Gets a stable day number from a DateTime's local calendar fields.
+ * @param {DateTime} date The DateTime.
+ * @return {number} The local calendar day number.
+ */
+function calendarDay(date) {
+    const calendarDate = new Date(0);
+    calendarDate.setUTCFullYear(date.getYear(), date.getMonth() - 1, date.getDate());
+
+    return calendarDate.getTime() / 86400000;
+}
+
+/**
+ * Calculates the difference between two dates in a given time unit.
+ * @param {DateTime} date The base DateTime.
+ * @param {DateTime} other The DateTime to compare to.
+ * @param {'year' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second'} timeUnit The time unit to compare in.
+ * @param {boolean} [relative=true] Whether to use relative boundaries when calculating the difference.
+ * @return {number} The difference between the dates in the given time unit.
+ */
 export function calculateDiff(date, other, timeUnit, relative = true) {
-    other = other.setTimeZone(date.getTimeZone());
+    other = other.withTimeZone(date.getTimeZone());
 
     switch (timeUnit) {
         case 'year':
             return compensateDiff(
                 date,
-                other.setYear(
+                other.withYear(
                     date.getYear(),
                 ),
                 date.getYear() - other.getYear(),
@@ -22,7 +53,7 @@ export function calculateDiff(date, other, timeUnit, relative = true) {
         case 'month':
             return compensateDiff(
                 date,
-                other.setYear(
+                other.withYear(
                     date.getYear(),
                     date.getMonth(),
                 ),
@@ -31,9 +62,19 @@ export function calculateDiff(date, other, timeUnit, relative = true) {
                 -1,
             );
         case 'week':
+            if (relative) {
+                const dateWeek = date.startOfWeek();
+                const otherWeek = other.withLocale(date.getLocale()).startOfWeek();
+
+                return (
+                    calendarDay(dateWeek) -
+                    calendarDay(otherWeek)
+                ) / 7;
+            }
+
             return compensateDiff(
                 date,
-                other.setWeekYear(
+                other.withWeekYear(
                     date.getWeekYear(),
                     date.getWeek(),
                 ),
@@ -41,9 +82,13 @@ export function calculateDiff(date, other, timeUnit, relative = true) {
                 relative,
             );
         case 'day':
+            if (relative) {
+                return calendarDay(date) - calendarDay(other);
+            }
+
             return compensateDiff(
                 date,
-                other.setYear(
+                other.withYear(
                     date.getYear(),
                     date.getMonth(),
                     date.getDate(),
@@ -54,11 +99,11 @@ export function calculateDiff(date, other, timeUnit, relative = true) {
         case 'hour':
             return compensateDiff(
                 date,
-                other.setYear(
+                other.withYear(
                     date.getYear(),
                     date.getMonth(),
                     date.getDate(),
-                ).setHours(
+                ).withHours(
                     date.getHours(),
                 ),
                 (date - other) / 3600000,
@@ -67,11 +112,11 @@ export function calculateDiff(date, other, timeUnit, relative = true) {
         case 'minute':
             return compensateDiff(
                 date,
-                other.setYear(
+                other.withYear(
                     date.getYear(),
                     date.getMonth(),
                     date.getDate(),
-                ).setHours(
+                ).withHours(
                     date.getHours(),
                     date.getMinutes(),
                 ),
@@ -81,11 +126,11 @@ export function calculateDiff(date, other, timeUnit, relative = true) {
         case 'second':
             return compensateDiff(
                 date,
-                other.setYear(
+                other.withYear(
                     date.getYear(),
                     date.getMonth(),
                     date.getDate(),
-                ).setHours(
+                ).withHours(
                     date.getHours(),
                     date.getMinutes(),
                     date.getSeconds(),
@@ -99,11 +144,24 @@ export function calculateDiff(date, other, timeUnit, relative = true) {
 };
 
 /**
- * Compensate the difference between two dates.
+ * Gets the RegExp for a list of string values.
+ * Longer values are matched first to avoid prefix collisions.
+ * @param {string[]} values The values to include in the RegExp.
+ * @return {string} The values RegExp.
+ */
+export function valuesRegExp(values) {
+    return values.slice()
+        .sort((a, b) => b.length - a.length)
+        .map((value) => escapeRegExp(`${value}`))
+        .join('|');
+};
+
+/**
+ * Compensates the difference between two dates.
  * @param {DateTime} date The DateTime.
  * @param {DateTime} other The DateTime to compare to.
  * @param {number} amount The amount to compensate.
- * @param {Boolean} [compensate=true] Whether to compensate the amount.
+ * @param {boolean} [compensate=true] Whether to compensate the amount.
  * @param {number} [compensation=1] The compensation offset.
  * @return {number} The compensated amount.
  */
@@ -126,10 +184,10 @@ function compensateDiff(date, other, amount, compensate = true, compensation = 1
 };
 
 /**
- * Get the biggest difference between two dates.
+ * Gets the biggest difference between two dates.
  * @param {DateTime} date The DateTime.
  * @param {DateTime} [other] The DateTime to compare to.
- * @return {array} The biggest difference (amount and time unit).
+ * @return {[number, string]} The biggest difference (amount and time unit).
  */
 export function getBiggestDiff(date, other) {
     let lastResult;
@@ -159,7 +217,7 @@ export function getBiggestDiff(date, other) {
 };
 
 /**
- * Get the offset for a DateTime.
+ * Gets the offset for a DateTime.
  * @param {DateTime} date The DateTime.
  * @return {number} The offset.
  */
@@ -170,14 +228,36 @@ export function getOffset(date) {
         return 0;
     }
 
-    const utcString = getDateFormatter('UTC').format(date);
-    const localString = getDateFormatter(timeZone).format(date);
+    const values = Object.fromEntries(
+        getDateFormatter(timeZone)
+            .formatToParts(date)
+            .filter((part) => part.type !== 'literal')
+            .map(({ type, value }) => [type, value]),
+    );
+
+    let year = parseInt(values.year, 10);
+    if (values.era === 'BC') {
+        year = 1 - year;
+    }
 
-    return (new Date(utcString) - new Date(localString)) / 60000;
+    const localDate = new Date(0);
+    localDate.setUTCFullYear(
+        year,
+        parseInt(values.month, 10) - 1,
+        parseInt(values.day, 10),
+    );
+    const localTime = localDate.setUTCHours(
+        parseInt(values.hour, 10),
+        parseInt(values.minute, 10),
+        parseInt(values.second, 10),
+        parseInt(values.fractionalSecond, 10),
+    );
+
+    return (date.getTime() - localTime) / 60000;
 };
 
 /**
- * Get the number of milliseconds since the UNIX epoch (offset to timeZone).
+ * Gets the number of milliseconds since the UNIX epoch (offset to timeZone).
  * @param {DateTime} date The DateTime.
  * @return {number} The number of milliseconds since the UNIX epoch (offset to timeZone).
  */
@@ -186,7 +266,7 @@ export function getOffsetTime(date) {
 };
 
 /**
- * Compare a literal format string with a date string.
+ * Compares a literal format string with a date string.
  * @param {string} formatString The literal format string.
  * @param {string} dateString The date string.
  */
@@ -202,8 +282,39 @@ export function parseCompare(formatString, dateString) {
 };
 
 /**
- * Generate methods for parsing a date.
- * @return {object} An object containing date parsing methods.
+ * Parses a supported unzoned ISO string as a neutral wall-clock timestamp.
+ * @param {string} dateString The date string to parse.
+ * @return {number|null} The timestamp, or null if the shape is not supported.
+ */
+export function parseLocalTimestamp(dateString) {
+    const match =
+        dateString.match(/^(\d{4})(?:-(\d{2})(?:-(\d{2}))?)?$/) ||
+        dateString.match(/^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.(\d+))?)?$/);
+
+    if (!match) {
+        return null;
+    }
+
+    const [
+        , year,
+        month = 1,
+        day = 1,
+        hours = 0,
+        minutes = 0,
+        seconds = 0,
+        fraction = '',
+    ] = match;
+    const date = new Date(0);
+
+    date.setUTCFullYear(year, month - 1, day);
+    date.setUTCHours(hours, minutes, seconds, fraction.padEnd(3, '0').substring(0, 3));
+
+    return date.getTime();
+};
+
+/**
+ * Generates methods for parsing a date.
+ * @return {Record<string, {get: Function, set: Function}>} An object containing date parsing methods.
  */
 export function parseFactory() {
     let isPM = false;
@@ -212,7 +323,7 @@ export function parseFactory() {
     return {
         date: {
             get: (datetime) => datetime.getDate(),
-            set: (datetime, value) => datetime.setDate(value),
+            set: (datetime, value) => datetime.withDate(value),
         },
         dayPeriod: {
             get: (datetime) => datetime.getHours() < 12 ? 0 : 1,
@@ -222,18 +333,18 @@ export function parseFactory() {
                 if (lastAM) {
                     hours += datetime.getHours();
                 }
-                return datetime.setHours(hours);
+                return datetime.withHours(hours);
             },
         },
         dayOfYear: {
             get: (datetime) => datetime.getDayOfYear(),
-            set: (datetime, value) => datetime.setDayOfYear(value),
+            set: (datetime, value) => datetime.withDayOfYear(value),
         },
         era: {
-            get: (datetime) => datetime.getYear() < 1 ? 0 : 1,
+            get: (datetime) => datetime.getYear() < 0 ? 0 : 1,
             set: (datetime, value) => {
                 const offset = value ? 1 : -1;
-                return datetime.setYear(
+                return datetime.withYear(
                     datetime.getYear() * offset,
                 );
             },
@@ -245,84 +356,99 @@ export function parseFactory() {
                     value += 12;
                 }
                 lastAM = true;
-                return datetime.setHours(value);
+                return datetime.withHours(value);
             },
         },
         hours24: {
             get: (datetime) => datetime.getHours(),
             set: (datetime, value) => {
                 lastAM = false;
-                return datetime.setHours(value);
+                return datetime.withHours(value);
             },
         },
         milliseconds: {
             get: (datetime) => datetime.getMilliseconds(),
-            set: (datetime, value) => datetime.setMilliseconds(value),
+            set: (datetime, value) => datetime.withMilliseconds(value),
         },
         minutes: {
             get: (datetime) => datetime.getMinutes(),
-            set: (datetime, value) => datetime.setMinutes(value),
+            set: (datetime, value) => datetime.withMinutes(value),
         },
         month: {
             get: (datetime) => datetime.getMonth(),
-            set: (datetime, value) => datetime.setMonth(value),
+            set: (datetime, value) => datetime.withMonth(value),
         },
         quarter: {
             get: (datetime) => datetime.getQuarter(),
-            set: (datetime, value) => datetime.setQuarter(value),
+            set: (datetime, value) => datetime.withQuarter(value),
         },
         seconds: {
             get: (datetime) => datetime.getSeconds(),
-            set: (datetime, value) => datetime.setSeconds(value),
+            set: (datetime, value) => datetime.withSeconds(value),
         },
         week: {
             get: (datetime) => datetime.getWeek(),
-            set: (datetime, value) => datetime.setWeek(value),
+            set: (datetime, value) => datetime.withWeek(value),
         },
         weekDay: {
             get: (datetime) => datetime.getWeekDay(),
-            set: (datetime, value) => datetime.setWeekDay(value),
+            set: (datetime, value) => datetime.withWeekDay(value),
         },
         weekDayInMonth: {
             get: (datetime) => datetime.getWeekDayInMonth(),
-            set: (datetime, value) => datetime.setWeekDayInMonth(value),
+            set: (datetime, value) => datetime.withWeekDayInMonth(value),
         },
         weekOfMonth: {
             get: (datetime) => datetime.getWeekOfMonth(),
-            set: (datetime, value) => datetime.setWeekOfMonth(value),
+            set: (datetime, value) => datetime.withWeekOfMonth(value),
         },
         weekYear: {
             get: (datetime) => datetime.getWeekYear(),
-            set: (datetime, value) => datetime.setWeekYear(value),
+            set: (datetime, value) => datetime.withWeekYear(value),
         },
         year: {
             get: (datetime) => {
                 const year = datetime.getYear();
                 return Math.abs(year);
             },
-            set: (datetime, value) => datetime.setYear(value),
+            set: (datetime, value) => datetime.withYear(value),
         },
     };
 };
 
 /**
- * Set the number of milliseconds since the UNIX epoch (offset to timeZone).
+ * Sets the number of milliseconds since the UNIX epoch (offset to timeZone).
  * @param {DateTime} date The DateTime.
  * @param {number} time The number of milliseconds since the UNIX epoch (offset to timeZone).
- * @return {DateTime} The DateTime object.
+ * @param {number} [direction=1] The direction to resolve a gap.
+ * @return {DateTime} A new DateTime instance.
  */
-export function setOffsetTime(date, time) {
-    const oldOffset = date.getTimeZoneOffset();
+export function setOffsetTime(date, time, direction = 1) {
+    const newDate = date.withTime(
+        time + (date.getTimeZoneOffset() * 60000),
+    );
+    const newOffsetTime = getOffsetTime(newDate);
 
-    const newTime = time + (oldOffset * 60000);
-    const newDate = date.setTime(newTime);
+    if (newOffsetTime === time) {
+        return newDate;
+    }
 
-    const offset = newDate.getTimeZoneOffset();
+    const adjustedDate = date.withTime(
+        time + (newDate.getTimeZoneOffset() * 60000),
+    );
+    const adjustedOffsetTime = getOffsetTime(adjustedDate);
 
-    if (oldOffset === offset) {
-        return newDate;
+    if (adjustedOffsetTime === time) {
+        return adjustedDate;
+    }
+
+    if (direction < 0) {
+        return newOffsetTime < adjustedOffsetTime ?
+            newDate :
+            adjustedDate;
     }
 
-    // compensate for DST transitions
-    return newDate.setTime(newTime - ((oldOffset - offset) * 60000));
+    return newOffsetTime > adjustedOffsetTime ?
+        newDate :
+        adjustedDate;
 };