@aemforms/af-formatters 0.22.23 → 0.22.26

package/lib/esm/date/DateParser.js

@@ -1,26 +1,34 @@
 /*************************************************************************
-* ADOBE CONFIDENTIAL
-* ___________________
-*
-* Copyright 2022 Adobe
-* All Rights Reserved.
-*
-* NOTICE: All information contained herein is, and remains
-* the property of Adobe and its suppliers, if any. The intellectual
-* and technical concepts contained herein are proprietary to Adobe
-* and its suppliers and are protected by all applicable intellectual
-* property laws, including trade secret and copyright laws.
-* Dissemination of this information or reproduction of this material
-* is strictly forbidden unless prior written permission is obtained
-* from Adobe.
-
-* Adobe permits you to use and modify this file solely in accordance with
-* the terms of the Adobe license agreement accompanying it.
-*************************************************************************/
-
-import { ShorthandStyles, parseDateTimeSkeleton } from './SkeletonParser.js';
+ * ADOBE CONFIDENTIAL
+ * ___________________
+ *
+ *  Copyright 2022 Adobe
+ *  All Rights Reserved.
+ *
+ * NOTICE:  All information contained herein is, and remains
+ * the property of Adobe and its suppliers, if any. The intellectual
+ * and technical concepts contained herein are proprietary to Adobe
+ * and its suppliers and are protected by all applicable intellectual
+ * property laws, including trade secret and copyright laws.
+ * Dissemination of this information or reproduction of this material
+ * is strictly forbidden unless prior written permission is obtained
+ * from Adobe.
+ **************************************************************************/
+/**
+ * Credit: https://git.corp.adobe.com/dc/dfl/blob/master/src/patterns/dates.js
+ */
+// Test Japanese full/half width character support
 
+import {parseDateTimeSkeleton, ShorthandStyles} from './SkeletonParser.js';
+
+// get the localized month names resulting from a given pattern
 const twelveMonths = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11].map(m => new Date(2000, m, 1));
+
+/**
+ * returns the name of all the months for a given locale and given Date Format Settings
+ * @param locale {string}
+ * @param options {string} instance of Intl.DateTimeFormatOptions
+ */
 function monthNames(locale, options) {
     return twelveMonths.map(month => {
         const parts = new Intl.DateTimeFormat(locale, options).formatToParts(month);
@@ -28,17 +36,32 @@ function monthNames(locale, options) {
         return m && m.value;
     });
 }
+
+/**
+ * return an array of digits used by a given locale
+ * @param locale {string}
+ */
 function digitChars(locale) {
     return new Intl.NumberFormat(locale, {style:'decimal', useGrouping:false})
         .format(9876543210)
         .split('')
         .reverse();
 }
+
+/**
+ * returns the calendar name used in a given locale
+ * @param locale {string}
+ */
 function calendarName(locale) {
     const parts = new Intl.DateTimeFormat(locale, {era:'short'}).formatToParts(new Date());
     const era = parts.find(p => p.type === 'era')?.value;
     return era === 'هـ' ? 'islamic' : 'gregory';
 }
+
+/**
+ * returns the representation of the time of day for a given language
+ * @param language {string}
+ */
 function getDayPeriod(language) {
     const morning = new Date(2000, 1, 1, 1, 1, 1);
     const afternoon = new Date(2000, 1, 1, 16, 1, 1);
@@ -51,7 +74,13 @@ function getDayPeriod(language) {
         fn: (period, obj) => obj.hour += (period === pm.value) ? 12 : 0
     };
 }
-function offsetMS(dateObj, timeZone) {
+
+/**
+ * get the offset in MS, given a date and timezone
+ * @param dateObj {Date}
+ * @param timeZone {string}
+ */
+export function offsetMS(dateObj, timeZone) {
     let tzOffset;
     try {
         tzOffset = new Intl.DateTimeFormat('en-US', {timeZone, timeZoneName: 'longOffset'}).format(dateObj);
@@ -60,12 +89,13 @@ function offsetMS(dateObj, timeZone) {
     }
     const offset = /GMT([+\-−])?(\d{1,2}):?(\d{0,2})?/.exec(tzOffset);
     if (!offset) return 0;
-    const [sign, hours, minutes] = offset.slice(1);
-    const nHours = isNaN(parseInt(hours)) ? 0 : parseInt(hours);
-    const nMinutes = isNaN(parseInt(minutes)) ? 0 : parseInt(minutes);
+    const [sign, hours, minutes] = offset.slice(1)
+    const nHours = isNaN(parseInt(hours)) ? 0 : parseInt(hours)
+    const nMinutes = isNaN(parseInt(minutes)) ? 0 : parseInt(minutes)
     const result = ((nHours  * 60) + nMinutes) * 60 * 1000;
     return sign === '-' ? - result : result;
 }
+
 function getTimezoneOffsetFrom(otherTimezone) {
     var date = new Date();
     function objFromStr(str) {
@@ -80,29 +110,65 @@ function getTimezoneOffsetFrom(otherTimezone) {
     var other = objFromStr(str);
     str = date.toLocaleString('en-US', { day: 'numeric', hour: 'numeric', minute: 'numeric', hourCycle: 'h23' });
     var myLocale = objFromStr(str);
-    var otherOffset = (other.day * 24 * 60) + (other.hour * 60) + (other.minute);
-    var myLocaleOffset = (myLocale.day * 24 * 60) + (myLocale.hour * 60) + (myLocale.minute);
+    var otherOffset = (other.day * 24 * 60) + (other.hour * 60) + (other.minute); // utc date + otherTimezoneDifference
+    var myLocaleOffset = (myLocale.day * 24 * 60) + (myLocale.hour * 60) + (myLocale.minute);  // utc date + myTimeZoneDifference
+    // (utc date + otherZoneDifference) - (utc date + myZoneDifference) - (-1 * myTimeZoneDifference)
     return otherOffset - myLocaleOffset - date.getTimezoneOffset();
 }
-function offsetMSFallback(dateObj, timezone) {
-    const timezoneOffset = getTimezoneOffsetFrom(timezone);
+
+export function offsetMSFallback(dateObj, timezone) {
+    //const defaultOffset = dateObj.getTimezoneOffset();
+    const timezoneOffset = getTimezoneOffsetFrom(timezone)
     return timezoneOffset * 60 * 1000;
 }
-function adjustTimeZone(dateObj, timeZone) {
+
+/**
+ * adjust from the default JavaScript timezone to the default timezone
+ * @param dateObj {Date}
+ * @param timeZone {string}
+ */
+export function adjustTimeZone(dateObj, timeZone) {
     if (dateObj === null) return null;
+    // const defaultOffset = new Intl.DateTimeFormat('en-US', { timeZoneName: 'longOffset'}).format(dateObj);
     let baseDate = dateObj.getTime() - dateObj.getTimezoneOffset() * 60 * 1000;
     const offset = offsetMS(dateObj, timeZone);
-    offsetMSFallback(dateObj, timeZone);
+    const fallBackOffset = offsetMSFallback(dateObj, timeZone);
     baseDate += - offset;
+
+
+    // get the offset for the default JS environment
+    // return days since the epoch
     return new Date(baseDate);
 }
-function datetimeToNumber(dateObj) {
+
+/**
+ * Our script object model treats dates as numbers where the integer portion is days since the epoch,
+ * the fractional portion is the number hours in the day
+ * @param dateObj {Date}
+ * @returns {number}
+ */
+export function datetimeToNumber(dateObj) {
     if (dateObj === null) return 0;
+    // return days since the epoch
     return dateObj.getTime() / ( 1000 * 60 * 60 * 24 );
 }
-function numberToDatetime(num) {
+
+/**
+ * Our script object model treats dates as numbers where the integer portion is days since the epoch,
+ * the fractional portion is the number hours in the day
+ * @param num
+ * @returns {Date}
+ */
+export function numberToDatetime(num) {
     return new Date(Math.round(num * 1000 * 60 * 60 * 24));
 }
+
+/**
+ * in some cases, DateTimeFormat doesn't respect the 'numeric' vs. '2-digit' setting
+ * for time values. The function corrects that
+ * @param formattedParts instance of Intl.DateTimeFormatPart[]
+ * @param parsed
+ */
 function fixDigits(formattedParts, parsed) {
     ['hour', 'minute', 'second'].forEach(type => {
         const defn = formattedParts.find(f => f.type === type);
@@ -112,29 +178,55 @@ function fixDigits(formattedParts, parsed) {
         if (fmt === 'numeric' && defn.value.length === 2 && defn.value.charAt(0) === '0') defn.value = defn.value.slice(1);
     });
 }
+
 function fixYear(formattedParts, parsed) {
+    // two digit years are handled differently in DateTimeFormat. 00 becomes 1900
+    // providing a two digit year 0010 gets formatted to 10 and when parsed becomes 1910
+    // Hence we need to pad the year with 0 as required by the skeleton and mentioned in
+    // unicode. https://www.unicode.org/reports/tr35/tr35-dates.html#dfst-year
     const defn = formattedParts.find(f => f.type === 'year');
     if (!defn) return;
+    // eslint-disable-next-line no-unused-vars
     const chars = parsed.find(pair => pair[0] === 'year')[2];
     while(defn.value.length < chars) {
         defn.value = `0${defn.value}`;
     }
 }
+
+/**
+ *
+ * @param dateValue {Date}
+ * @param language {string}
+ * @param skeleton {string}
+ * @param timeZone {string}
+ * @returns {T}
+ */
 function formatDateToParts(dateValue, language, skeleton, timeZone) {
+    // DateTimeFormat renames some of the options in its formatted output
+    //@ts-ignore
     const mappings = key => ({
         hour12: 'dayPeriod',
         fractionalSecondDigits: 'fractionalSecond',
     })[key] || key;
+
+    // produces an array of name/value pairs of skeleton parts
     const allParameters = parseDateTimeSkeleton(skeleton, language);
     allParameters.push(['timeZone', timeZone]);
+
     const parsed = allParameters.filter(p => !p[0].startsWith('x-'));
     const nonStandard = allParameters.filter(p => p[0].startsWith('x-'));
+    // reduce to a set of options that can be used to format
     const options = Object.fromEntries(parsed);
     delete options.literal;
+
     const df = new Intl.DateTimeFormat(language, options);
+    // formattedParts will have all the pieces we need for our date -- but not in the correct order
     const formattedParts = df.formatToParts(dateValue);
+
     fixDigits(formattedParts, allParameters);
     fixYear(formattedParts, parsed);
+    // iterate through the original parsed components and use its ordering and literals,
+    // and add  the formatted pieces
     return parsed.reduce((result, cur) => {
         if (cur[0] === 'literal') result.push(cur);
         else {
@@ -144,25 +236,37 @@ function formatDateToParts(dateValue, language, skeleton, timeZone) {
                 const category = tz[0];
                 if (category === 'Z') {
                     if (tz.length < 4) {
+                        // handle 'Z', 'ZZ', 'ZZZ' Time Zone: ISO8601 basic hms? / RFC 822
                         v.value = v.value.replace(/(GMT|:)/g, '');
                         if (v.value === '') v.value = '+0000';
                     } else if (tz.length === 5) {
+                        // 'ZZZZZ' Time Zone: ISO8601 extended hms?
                         if (v.value === 'GMT') v.value = 'Z';
                         else v.value = v.value.replace(/GMT/, '');
                     }
                 }
                 if (category === 'X' || category === 'x') {
                     if (tz.length === 1) {
+                        // 'X' ISO8601 basic hm?, with Z for 0
+                        // -08, +0530, Z
+                        // 'x' ISO8601 basic hm?, without Z for 0
                         v.value = v.value.replace(/(GMT|:(00)?)/g, '');
                     }
                     if (tz.length === 2) {
+                        // 'XX' ISO8601 basic hm, with Z
+                        // -0800, Z
+                        // 'xx' ISO8601 basic hm, without Z
                         v.value = v.value.replace(/(GMT|:)/g, '');
                     }
                     if (tz.length === 3) {
+                        // 'XXX' ISO8601 extended hm, with Z
+                        // -08:00, Z
+                        // 'xxx' ISO8601 extended hm, without Z
                         v.value = v.value.replace(/GMT/g, '');
                     }
                     if (category === 'X' && v.value === '') v.value = 'Z';
                 } else if (tz === 'O') {
+                    // eliminate 'GMT', leading and trailing zeros
                     v.value = v.value.replace(/GMT/g, '').replace(/0(\d+):/, '$1:').replace(/:00/, '');
                     if (v.value === '') v.value = '+0';
                 }
@@ -172,28 +276,41 @@ function formatDateToParts(dateValue, language, skeleton, timeZone) {
         return result;
     }, []);
 }
-function formatDate(dateValue, language, skeleton, timeZone) {
-    if (skeleton.startsWith('date|')) {
-        skeleton = skeleton.split('|')[1];
-    }
+
+/**
+ *
+ * @param dateValue {Date}
+ * @param language {string}
+ * @param skeleton {string}
+ * @param timeZone {string}
+ */
+export function formatDate(dateValue, language, skeleton, timeZone) {
     if (ShorthandStyles.find(type => skeleton.includes(type))) {
         const options = {timeZone};
+        // the skeleton could have two keywords -- one for date, one for time
         const parts = skeleton.split(/\s/).filter(s => s.length);
         if (ShorthandStyles.indexOf(parts[0]) > -1) {
-            options.dateStyle = parts[0];
+            options.dateStyle = parts[0]
         }
         if (parts.length > 1 && ShorthandStyles.indexOf(parts[1]) > -1) {
-            options.timeStyle = parts[1];
+            options.timeStyle = parts[1]
         }
         return new Intl.DateTimeFormat(language, options).format(dateValue);
     }
     const parts = formatDateToParts(dateValue, language, skeleton, timeZone);
     return parts.map(p => p[1]).join('');
 }
-function parseDate(dateString, language, skeleton, timeZone, bUseUTC = false) {
-    if (skeleton.startsWith('date|')) {
-        skeleton = skeleton.split('|')[1];
-    }
+
+/**
+ *
+ * @param dateString {string}
+ * @param language {string}
+ * @param skeleton {string}
+ * @param timeZone {string}
+ */
+export function parseDate(dateString, language, skeleton, timeZone, bUseUTC = false) {
+    // start by getting all the localized parts of a date/time picture:
+    // digits, calendar name
     const lookups = [];
     const regexParts = [];
     const calendar = calendarName(language);
@@ -204,11 +321,13 @@ function parseDate(dateString, language, skeleton, timeZone, bUseUTC = false) {
     let hourCycle = 'h12';
     let _bUseUTC = bUseUTC;
     let _setFullYear = false;
+    // functions to process the results of the regex match
     const isSeparator = str => str.length === 1 &&  ':-/.'.includes(str);
     const monthNumber = str => getNumber(str) - 1;
     const getNumber = str => str.split('').reduce((total, digit) => (total * 10) + digits.indexOf(digit), 0);
     const yearNumber = templateDigits => str => {
         let year = getNumber(str);
+        //todo: align with AF
         year = year < 100 && templateDigits === 2 ? year + 2000 : year;
         if (calendar === 'islamic') year = Math.ceil(year * 0.97 + 622);
         if (templateDigits > 2 && year < 100) {
@@ -217,51 +336,67 @@ function parseDate(dateString, language, skeleton, timeZone, bUseUTC = false) {
         return year;
     };
     const monthLookup = list => month => list.indexOf(month);
+
     const parsed = parseDateTimeSkeleton(skeleton, language);
     const months = monthNames(language, Object.fromEntries(parsed));
+    // build up a regex expression that identifies each option in the skeleton
+    // We build two parallel structures:
+    // 1. the regex expression that will extract parts of the date/time
+    // 2. a lookup array that will convert the matched results into date/time values
     parsed.forEach(([option, value, len]) => {
+        // use a generic regex pattern for all single-character separator literals.
+        // Then we'll be forgiving when it comes to separators: / vs - vs : etc
         if (option === 'literal') {
             if (isSeparator(value)) regexParts.push(`[^${digits[0]}-${digits[9]}]`);
             else regexParts.push(value);
+
         } else if (option === 'month' && ['numeric', '2-digit'].includes(value)) {
             regexParts.push(twoDigit);
             lookups.push(['month', monthNumber]);
+
         } else if (option === 'month' && ['formatted', 'long', 'short', 'narrow'].includes(value)) {
             regexParts.push(`(${months.join('|')})`);
             lookups.push(['month', monthLookup(months)]);
+
         } else if (['day', 'minute', 'second'].includes(option)) {
             if (option === 'minute' || option === 'second') {
-                _bUseUTC = false;
+                _bUseUTC = false
             }
             regexParts.push(twoDigit);
             lookups.push([option, getNumber]);
+
         } else if (option === 'fractionalSecondDigits') {
-            _bUseUTC = false;
+            _bUseUTC = false
             regexParts.push(threeDigit);
             lookups.push([option, (v, obj) => obj.fractionalSecondDigits + getNumber(v)]);
+
         } else if (option === 'hour') {
-            _bUseUTC = false;
+            _bUseUTC = false
             regexParts.push(twoDigit);
             lookups.push([option, (v, obj) => obj.hour + getNumber(v)]);
         } else if (option === 'year') {
             regexParts.push('numeric' === value ? fourDigit : twoDigit);
             lookups.push(['year', yearNumber(len)]);
         } else if (option === 'dayPeriod') {
-            _bUseUTC = false;
+            _bUseUTC = false
             const dayPeriod = getDayPeriod(language);
             if (dayPeriod) {
                 regexParts.push(dayPeriod.regex);
                 lookups.push(['hour', dayPeriod.fn]);
             }
+            // Any other part that we don't need, we'll just add a non-greedy consumption
         } else if (option === 'hourCycle') {
-            _bUseUTC = false;
+            _bUseUTC = false
             hourCycle = value;
         } else if (option === 'x-timeZoneName') {
-            _bUseUTC = false;
+            _bUseUTC = false
+            // we handle only the GMT offset picture
             regexParts.push('(?:GMT|UTC|Z)?([+\\-−0-9]{0,3}:?[0-9]{0,2})');
             lookups.push([option, (v, obj) => {
                 _bUseUTC = true;
+                // v could be undefined if we're on GMT time
                 if (!v) return;
+                // replace the unicode minus, then extract hours [and minutes]
                 const timeParts = v.replace(/−/, '-').match(/([+\-\d]{2,3}):?(\d{0,2})/);
                 const hours = timeParts[1] * 1;
                 obj.hour -= hours;
@@ -269,14 +404,17 @@ function parseDate(dateString, language, skeleton, timeZone, bUseUTC = false) {
                 obj.minute -= (hours < 0) ? - mins : mins;
             }]);
         } else if (option !== 'timeZoneName') {
-            _bUseUTC = false;
+            _bUseUTC = false
             regexParts.push('.+?');
         }
+
         return regexParts;
     }, []);
     const regex = new RegExp(regexParts.join(''));
     const match = dateString.match(regex);
     if (match === null) return dateString;
+
+    // now loop through all the matched pieces and build up an object we'll use to create a Date object
     const dateObj = {year: 1972, month: 0, day: 1, hour: 0, minute: 0, second: 0, fractionalSecondDigits: 0};
     match.slice(1).forEach((m, index) => {
         const [element, func] = lookups[index];
@@ -313,8 +451,7 @@ function parseDate(dateString, language, skeleton, timeZone, bUseUTC = false) {
     }
     return timeZone == null ? jsDate : adjustTimeZone(jsDate, timeZone);
 }
-function parseDefaultDate(dateString, language, bUseUTC) {
+
+export function parseDefaultDate(dateString, language, bUseUTC) {
     return parseDate(dateString, language, 'short', null, false);
 }
-
-export { adjustTimeZone, datetimeToNumber, formatDate, numberToDatetime, offsetMS, offsetMSFallback, parseDate, parseDefaultDate };