@fr0st/datetime 6.0.1 → 7.0.0

package/src/factory.js

@@ -2,48 +2,57 @@
  * DateTime Factory
  */
 
-const data = {};
+const data = new Map();
 
 /**
- * Get values from cache (or generate if they don't exist).
+ * Clears all cached formatter and locale values.
+ */
+export function clearDataCache() {
+    data.clear();
+};
+
+/**
+ * Gets a cached value, creating it on first access.
+ * @template T
  * @param {string} key The key for the values.
- * @param {function} callback The callback to generate the values.
- * @return {array} The cached values.
+ * @param {() => T} callback The callback to generate the values.
+ * @return {T} The cached value.
  */
 export function getData(key, callback) {
-    if (!(key in data)) {
-        data[key] = callback();
+    if (!data.has(key)) {
+        data.set(key, callback());
     }
 
-    return data[key];
+    return data.get(key);
 };
 
 /**
- * Create a new date formatter for a timeZone.
- * @param {string} timeZone The timeZone.
- * @param {object} options The options for the formatter.
- * @return {Intl.DateTimeFormat} A new DateTimeFormat object.
+ * Creates a date formatter for a time zone.
+ * @param {string} timeZone The time zone.
+ * @return {Intl.DateTimeFormat} The formatter instance.
  */
 export function getDateFormatter(timeZone) {
     return getData(
         `dateFormatter.${timeZone}`,
-        (_) => makeFormatter('en', {
+        () => makeFormatter('en', {
             timeZone,
             hourCycle: 'h23',
+            era: 'short',
             year: 'numeric',
             month: 'numeric',
             day: 'numeric',
             hour: 'numeric',
             minute: 'numeric',
+            second: 'numeric',
+            fractionalSecondDigits: 3,
         }),
     );
 };
 
 /**
- * Create a new relative formatter for a locale.
+ * Creates a relative-time formatter for a locale.
  * @param {string} locale The locale.
- * @param {object} options The options for the formatter.
- * @return {Intl.RelativeTimeFormat} A new RelativeTimeFormat object.
+ * @return {Intl.RelativeTimeFormat|null} The formatter instance, or null when unsupported.
  */
 export function getRelativeFormatter(locale) {
     if (!('RelativeTimeFormat' in Intl)) {
@@ -52,7 +61,7 @@ export function getRelativeFormatter(locale) {
 
     return getData(
         `relativeFormatter.${locale}`,
-        (_) => new Intl.RelativeTimeFormat(locale, {
+        () => new Intl.RelativeTimeFormat(locale, {
             numeric: 'auto',
             style: 'long',
         }),
@@ -60,14 +69,15 @@ export function getRelativeFormatter(locale) {
 };
 
 /**
- * Create a new formatter for a locale.
+ * Creates a formatter for a locale.
  * @param {string} locale The locale.
- * @param {object} options The options for the formatter.
- * @return {Intl.DateTimeFormat} A new DateTimeFormat object.
+ * @param {Intl.DateTimeFormatOptions} options The options for the formatter.
+ * @return {Intl.DateTimeFormat} The formatter instance.
  */
 export function makeFormatter(locale, options) {
     return new Intl.DateTimeFormat(locale, {
         timeZone: 'UTC',
         ...options,
+        calendar: 'gregory',
     });
 };

package/src/formatter/format.js

@@ -2,11 +2,11 @@ import { getRelativeFormatter, makeFormatter } from './../factory.js';
 import { getDayPeriods, getDays, getEras, getMonths, getNumbers } from './values.js';
 
 /**
- * Format a day as a locale string.
+ * Formats a day as a locale string.
  * @param {string} locale The locale.
  * @param {number} day The day to format (0-6).
  * @param {string} [type=long] The formatting type.
- * @param {Boolean} [standalone=true] Whether the value is standalone.
+ * @param {boolean} [standalone=true] Whether the value is standalone.
  * @return {string} The formatted string.
  */
 export function formatDay(locale, day, type = 'long', standalone = true) {
@@ -14,9 +14,9 @@ export function formatDay(locale, day, type = 'long', standalone = true) {
 };
 
 /**
- * Format a day period as a locale string.
+ * Formats a day period as a locale string.
  * @param {string} locale The locale.
- * @param {number} period The period to format (0-1).
+ * @param {number} period The day-period index to format. (0-1)
  * @param {string} [type=long] The formatting type.
  * @return {string} The formatted string.
  */
@@ -25,9 +25,9 @@ export function formatDayPeriod(locale, period, type = 'long') {
 };
 
 /**
- * Format an era as a locale string.
+ * Formats an era as a locale string.
  * @param {string} locale The locale.
- * @param {number} era The period to format (0-1).
+ * @param {number} era The era index to format. (0-1)
  * @param {string} [type=long] The formatting type.
  * @return {string} The formatted string.
  */
@@ -36,11 +36,11 @@ export function formatEra(locale, era, type = 'long') {
 };
 
 /**
- * Format a month as a locale string.
+ * Formats a month as a locale string.
  * @param {string} locale The locale.
  * @param {number} month The month to format (1-12).
  * @param {string} [type=long] The formatting type.
- * @param {Boolean} [standalone=true] Whether the value is standalone.
+ * @param {boolean} [standalone=true] Whether the value is standalone.
  * @return {string} The formatted string.
  */
 export function formatMonth(locale, month, type = 'long', standalone = true) {
@@ -48,7 +48,7 @@ export function formatMonth(locale, month, type = 'long', standalone = true) {
 };
 
 /**
- * Format a number as a locale number string.
+ * Formats a number as a locale number string.
  * @param {string} locale The locale.
  * @param {number} number The number to format.
  * @param {number} [padding=0] The amount of padding to use.
@@ -57,43 +57,52 @@ export function formatMonth(locale, month, type = 'long', standalone = true) {
 export function formatNumber(locale, number, padding = 0) {
     const numbers = getNumbers(locale);
     return `${number}`
-        .padStart(padding, 0)
+        .padStart(padding, '0')
         .replace(/\d/g, (match) => numbers[match]);
 };
 
 /**
- * Format a number to an offset string.
+ * Formats a number to an offset string.
  * @param {number} offset The offset to format.
- * @param {Boolean} [useColon=true] Whether to use a colon seperator.
- * @param {Boolean} [optionalMinutes=false] Whether minutes are optional.
+ * @param {boolean} [useColon=true] Whether to use a colon separator.
+ * @param {boolean} [optionalMinutes=false] Whether minutes are optional.
+ * @param {boolean} [includeSeconds=true] Whether seconds are included.
  * @return {string} The formatted offset string.
  */
-export function formatOffset(offset, useColon = true, optionalMinutes = false) {
-    const hours = Math.abs(
-        (offset / 60) | 0,
-    );
-    const minutes = Math.abs(offset % 60);
+export function formatOffset(offset, useColon = true, optionalMinutes = false, includeSeconds = true) {
+    const absoluteSeconds = Math.abs(offset * 60);
+    const totalSeconds = Math.round(absoluteSeconds);
+    const precision = Number.EPSILON * Math.max(1, absoluteSeconds);
+    const roundingError = Math.abs(absoluteSeconds - totalSeconds);
+    if (!Number.isFinite(absoluteSeconds) || roundingError > precision || totalSeconds >= 86400) {
+        throw new Error('Invalid time zone offset supplied');
+    }
 
+    const hours = Math.floor(totalSeconds / 3600);
+    const minutes = Math.floor(totalSeconds % 3600 / 60);
+    const seconds = totalSeconds % 60;
     const sign = offset > 0 ?
         '-' :
         '+';
-    const hourString = `${hours}`.padStart(2, 0);
-    const minuteString = minutes || !optionalMinutes ?
-        `${minutes}`.padStart(2, 0) :
-        '';
-    const colon = useColon && minuteString ?
-        ':' :
-        '';
+    const parts = [`${hours}`.padStart(2, '0')];
+
+    if (!optionalMinutes || minutes || seconds) {
+        parts.push(`${minutes}`.padStart(2, '0'));
+    }
+
+    if (includeSeconds && seconds) {
+        parts.push(`${seconds}`.padStart(2, '0'));
+    }
 
-    return `${sign}${hourString}${colon}${minuteString}`;
+    return sign + parts.join(useColon ? ':' : '');
 };
 
 /**
- * Format a relative duration as a locale string.
+ * Formats a relative duration as a locale string.
  * @param {string} locale The locale.
  * @param {number} amount The amount of duration.
  * @param {string} unit The time unit.
- * @returns {string} The relative duration.
+ * @return {string} The relative duration.
  */
 export function formatRelative(locale, amount, unit) {
     const relativeFormatter = getRelativeFormatter(locale);
@@ -106,7 +115,7 @@ export function formatRelative(locale, amount, unit) {
 };
 
 /**
- * Format a time zone as a locale string.
+ * Formats a time zone as a locale string.
  * @param {string} locale The locale.
  * @param {number} timestamp The timestamp to use.
  * @param {string} timeZone The time zone to format.

package/src/formatter/locale.js

@@ -0,0 +1,80 @@
+import { getData } from './../factory.js';
+import { minDaysInFirstWeek, weekStart } from './locales.js';
+
+/**
+ * Gets a locale value from generated data.
+ * @param {object} data The generated locale data.
+ * @param {string[]} candidates The locale candidates.
+ * @param {number} fallback The fallback value.
+ * @return {number} The locale value.
+ */
+function generatedValue(data, candidates, fallback) {
+    for (const candidate of candidates) {
+        for (const [value, valueLocales] of Object.entries(data)) {
+            if (valueLocales.includes(candidate)) {
+                return parseInt(value, 10);
+            }
+        }
+    }
+
+    return fallback;
+}
+
+/**
+ * Gets generated-data candidates for a locale.
+ * @param {Intl.Locale} locale The locale.
+ * @return {string[]} The locale candidates.
+ */
+function localeCandidates(locale) {
+    const localeName = locale.toString().split('-x-', 1)[0];
+    const regionOverride = localeName.match(
+        /-u-(?:[a-z0-9]{2,8}-)*rg-([a-z]{2}|\d{3})zzzz(?:-|$)/i,
+    );
+    const region = regionOverride?.[1] || locale.region;
+
+    return [
+        [locale.language, locale.script, region],
+        [locale.language, region],
+        [locale.language, locale.script],
+        [locale.language],
+    ].map((parts) =>
+        parts
+            .filter((part) => !!part)
+            .join('-')
+            .toLowerCase(),
+    );
+}
+
+/**
+ * Gets week information for a locale.
+ * @param {string} locale The locale.
+ * @return {{firstDay: number, minimalDays: number}} The week information.
+ */
+export function getWeekInfo(locale) {
+    return getData(
+        `weekInfo.${locale}`,
+        () => {
+            const localeData = new Intl.Locale(locale);
+            const runtimeInfo = localeData.getWeekInfo?.() || localeData.weekInfo || {};
+
+            let { firstDay = null, minimalDays = null } = runtimeInfo;
+
+            const candidates = firstDay && minimalDays ?
+                [] :
+                localeCandidates(localeData);
+
+            if (!firstDay) {
+                const phpFirstDay = generatedValue(weekStart, candidates, 2);
+
+                // IntlCalendar numbers Sunday as 1; Intl.Locale numbers it as 7.
+                firstDay = phpFirstDay === 1 ? 7 : phpFirstDay - 1;
+            }
+
+            if (!minimalDays) {
+                minimalDays = generatedValue(minDaysInFirstWeek, candidates, 1);
+            }
+
+            return { firstDay, minimalDays };
+        },
+    );
+};

package/src/formatter/locales.js

@@ -1,2 +1,2 @@
-export const weekStart = { '1': ['af', 'am', 'ar-il', 'ar-sa', 'ar-ye', 'as', 'bn', 'bo', 'brx', 'ccp', 'ceb', 'chr', 'dav', 'dz', 'ebu', 'en', 'fil', 'gu', 'guz', 'haw', 'he', 'hi', 'id', 'ii', 'ja', 'jv', 'kam', 'ki', 'kln', 'km', 'kn', 'ko', 'kok', 'ks', 'lkt', 'lo', 'luo', 'luy', 'mas', 'mer', 'mgh', 'ml', 'mr', 'mt', 'my', 'nd', 'ne', 'om', 'or', 'pa', 'ps-pk', 'pt', 'qu', 'saq', 'sd', 'seh', 'sn', 'ta', 'te', 'th', 'ti', 'ug', 'ur', 'xh', 'yue', 'zh', 'zu'], '7': ['ar', 'ckb', 'en-ae', 'en-sd', 'fa', 'kab', 'lrc', 'mzn', 'ps'] };
-export const minDaysInFirstWeek = { '4': ['ast', 'bg', 'br', 'ca', 'ce', 'cs', 'cy', 'da', 'de', 'dsb', 'el', 'en-at', 'en-be', 'en-ch', 'en-de', 'en-dk', 'en-fi', 'en-fj', 'en-gb', 'en-gg', 'en-gi', 'en-ie', 'en-im', 'en-je', 'en-nl', 'en-se', 'es', 'et', 'eu', 'fi', 'fo', 'fr', 'fur', 'fy', 'ga', 'gd', 'gl', 'gsw', 'gv', 'hsb', 'hu', 'is', 'it', 'ksh', 'kw', 'lb', 'lt', 'nb', 'nds', 'nl', 'nn', 'os-ru', 'pl', 'pt-ch', 'pt-lu', 'pt-pt', 'rm', 'ru', 'sah', 'se', 'sk', 'smn', 'sv', 'tt', 'wae'] };
+export const weekStart = { '1': ['af', 'am', 'ar-il', 'ar-sa', 'ar-ye', 'as', 'bn', 'bo', 'brx', 'ccp', 'ceb', 'chr', 'dav', 'doi', 'dz', 'ebu', 'en', 'es-br', 'es-bz', 'es-co', 'es-do', 'es-gt', 'es-hn', 'es-mx', 'es-ni', 'es-pa', 'es-pe', 'es-ph', 'es-pr', 'es-py', 'es-sv', 'es-us', 'es-ve', 'fil', 'fr-ca', 'gu', 'guz', 'haw', 'he', 'hi', 'id', 'ii', 'ja', 'jv', 'kam', 'ki', 'kln', 'km', 'kn', 'ko', 'kok', 'ks', 'lkt', 'lo', 'luo', 'luy', 'mai', 'mas', 'mer', 'mgh', 'ml', 'mni', 'mr', 'ms-id', 'ms-sg', 'mt', 'my', 'nd', 'ne', 'om', 'or', 'pa', 'ps-pk', 'pt', 'qu', 'sa', 'saq', 'sat', 'sd', 'seh', 'sn', 'so-et', 'so-ke', 'su', 'sw-ke', 'ta', 'te', 'teo-ke', 'th', 'ti', 'ug', 'ur', 'xh', 'yue', 'zh', 'zu'], '2': ['af-na', 'ar-001', 'ar-eh', 'ar-er', 'ar-km', 'ar-lb', 'ar-ma', 'ar-mr', 'ar-ps', 'ar-so', 'ar-ss', 'ar-td', 'ar-tn', 'en-001', 'en-150', 'en-ai', 'en-at', 'en-au', 'en-bb', 'en-be', 'en-bi', 'en-bm', 'en-cc', 'en-ch', 'en-ck', 'en-cm', 'en-cx', 'en-cy', 'en-de', 'en-dg', 'en-dk', 'en-er', 'en-fi', 'en-fj', 'en-fk', 'en-fm', 'en-gb', 'en-gd', 'en-gg', 'en-gh', 'en-gi', 'en-gm', 'en-gy', 'en-ie', 'en-im', 'en-io', 'en-je', 'en-ki', 'en-kn', 'en-ky', 'en-lc', 'en-lr', 'en-ls', 'en-mg', 'en-mp', 'en-ms', 'en-mu', 'en-mw', 'en-my', 'en-na', 'en-nf', 'en-ng', 'en-nl', 'en-nr', 'en-nu', 'en-nz', 'en-pg', 'en-pn', 'en-pw', 'en-rw', 'en-sb', 'en-sc', 'en-se', 'en-sh', 'en-si', 'en-sl', 'en-ss', 'en-sx', 'en-sz', 'en-tc', 'en-tk', 'en-to', 'en-tv', 'en-tz', 'en-ug', 'en-vc', 'en-vg', 'en-vu', 'en-zm', 'ko-kp', 'mas-tz', 'pt-ao', 'pt-ch', 'pt-cv', 'pt-gq', 'pt-gw', 'pt-lu', 'pt-st', 'pt-tl', 'qu-bo', 'qu-ec', 'ta-lk', 'ta-my', 'ti-er'], '7': ['ar', 'ckb', 'en-ae', 'en-sd', 'fa', 'fr-dj', 'fr-dz', 'fr-sy', 'kab', 'lrc', 'mzn', 'ps', 'so-dj', 'uz-arab', 'uz-arab-af'] };
+export const minDaysInFirstWeek = { '4': ['ast', 'bg', 'br', 'ca', 'ce', 'cs', 'cy', 'da', 'de', 'dsb', 'el', 'en-at', 'en-be', 'en-ch', 'en-de', 'en-dk', 'en-fi', 'en-fj', 'en-gb', 'en-gg', 'en-gi', 'en-ie', 'en-im', 'en-je', 'en-nl', 'en-se', 'es', 'et', 'eu', 'fi', 'fo', 'fr', 'fur', 'fy', 'ga', 'gd', 'gl', 'gsw', 'gv', 'hsb', 'hu', 'is', 'it', 'ksh', 'kw', 'lb', 'lt', 'nb', 'nl', 'nn', 'no', 'os-ru', 'pl', 'pt-ch', 'pt-lu', 'pt-pt', 'rm', 'ru', 'sah', 'sc', 'se', 'sk', 'smn', 'sv', 'tt', 'wae'], '1': ['da-gl', 'el-cy', 'es-419', 'es-ar', 'es-bo', 'es-br', 'es-bz', 'es-cl', 'es-co', 'es-cr', 'es-cu', 'es-do', 'es-ea', 'es-ec', 'es-gq', 'es-gt', 'es-hn', 'es-ic', 'es-mx', 'es-ni', 'es-pa', 'es-pe', 'es-ph', 'es-pr', 'es-py', 'es-sv', 'es-us', 'es-uy', 'es-ve', 'fr-bf', 'fr-bi', 'fr-bj', 'fr-bl', 'fr-ca', 'fr-cd', 'fr-cf', 'fr-cg', 'fr-ci', 'fr-cm', 'fr-dj', 'fr-dz', 'fr-ga', 'fr-gn', 'fr-gq', 'fr-ht', 'fr-km', 'fr-ma', 'fr-mf', 'fr-mg', 'fr-ml', 'fr-mr', 'fr-mu', 'fr-nc', 'fr-ne', 'fr-pf', 'fr-pm', 'fr-rw', 'fr-sc', 'fr-sn', 'fr-sy', 'fr-td', 'fr-tg', 'fr-tn', 'fr-vu', 'fr-wf', 'fr-yt', 'nl-aw', 'nl-bq', 'nl-cw', 'nl-sr', 'nl-sx', 'ru-by', 'ru-kg', 'ru-kz', 'ru-md', 'ru-ua'] };

package/src/formatter/parse.js

@@ -1,21 +1,24 @@
-import { getDayPeriods, getDays, getEras, getMonths, getNumbers } from './values.js';
 import { weekDay } from './utility.js';
+import { getDayPeriods, getDays, getEras, getMonths, getNumbers } from './values.js';
 
 /**
- * Parse a day from a locale string.
+ * Parses a day from a locale string.
  * @param {string} locale The locale.
  * @param {string} value The value to parse.
  * @param {string} [type=long] The formatting type.
- * @param {Boolean} [standalone=true] Whether the value is standalone.
- * @return {number} The day number (0-6).
+ * @param {boolean} [standalone=true] Whether the value is standalone.
+ * @return {number} The local day of the week (1-7).
  */
 export function parseDay(locale, value, type = 'long', standalone = true) {
-    const day = getDays(locale, type, standalone).indexOf(value) || 7;
+    const day = getDays(locale, type, standalone).indexOf(value);
+    if (day === -1) {
+        throw new Error(`Unmatched day string in DateTime string: ${value}`);
+    }
     return weekDay(locale, day);
 };
 
 /**
- * Parse a day period from a locale string.
+ * Parses a day period from a locale string.
  * @param {string} locale The locale.
  * @param {string} value The value to parse.
  * @param {string} [type=long] The formatting type.
@@ -26,7 +29,7 @@ export function parseDayPeriod(locale, value, type = 'long') {
 };
 
 /**
- * Parse an era from a locale string.
+ * Parses an era from a locale string.
  * @param {string} locale The locale.
  * @param {string} value The value to parse.
  * @param {string} [type=long] The formatting type.
@@ -37,11 +40,11 @@ export function parseEra(locale, value, type = 'long') {
 };
 
 /**
- * Parse a month from a locale string.
+ * Parses a month from a locale string.
  * @param {string} locale The locale.
  * @param {string} value The value to parse.
  * @param {string} [type=long] The formatting type.
- * @param {Boolean} [standalone=true] Whether the value is standalone.
+ * @param {boolean} [standalone=true] Whether the value is standalone.
  * @return {number} The month number (1-12).
  */
 export function parseMonth(locale, value, type = 'long', standalone = true) {
@@ -49,14 +52,25 @@ export function parseMonth(locale, value, type = 'long', standalone = true) {
 };
 
 /**
- * Parse a number from a locale number string.
+ * Parses locale digits into an ASCII digit string.
+ * @param {string} locale The locale.
+ * @param {string} value The value to parse.
+ * @return {string} The parsed ASCII digit string.
+ */
+export function parseNumberString(locale, value) {
+    const numbers = getNumbers(locale);
+    return Array.from(value, (digit) => numbers.indexOf(digit)).join('');
+};
+
+/**
+ * Parses a number from a locale number string.
  * @param {string} locale The locale.
  * @param {string} value The value to parse.
  * @return {number} The parsed number.
  */
 export function parseNumber(locale, value) {
-    const numbers = getNumbers(locale);
     return parseInt(
-        `${value}`.replace(/./g, (match) => numbers.indexOf(match)),
+        parseNumberString(locale, value),
+        10,
     );
 };