@fr0st/datetime 5.0.0

package/package.json

@@ -0,0 +1,51 @@
+{
+    "name": "@fr0st/datetime",
+    "version": "5.0.0",
+    "description": "FrostDateTime is a free, open-source date manipulation library for JavaScript.",
+    "keywords": [
+        "date",
+        "time",
+        "datetime",
+        "timezone",
+        "locale",
+        "localization",
+        "icu",
+        "parse",
+        "format"
+    ],
+    "homepage": "https://github.com/elusivecodes/FrostDateTime",
+    "bugs": {
+        "url": "https://github.com/elusivecodes/FrostDateTime/issues",
+        "email": "elusivecodes@gmail.com"
+    },
+    "main": "src/index.js",
+    "type": "module",
+    "files": [
+        "/LICENSE",
+        "/README.md",
+        "src"
+    ],
+    "scripts": {
+        "build": "npm run js-compile && npm run js-minify",
+        "js-compile": "rollup src/index.js --file dist/frost-datetime.js --format iife --sourcemap --name DateTime",
+        "js-lint": "eslint --ext .js .",
+        "js-minify": "terser --compress passes=2 --mangle --source-map \"content=dist/frost-datetime.js.map\" --output dist/frost-datetime.min.js dist/frost-datetime.js",
+        "test": "mocha --recursive",
+        "locales": "php generate-locales.php > src/formatter/locales.js"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/elusivecodes/FrostDateTime.git"
+    },
+    "author": "Elusive <elusivecodes@gmail.com>",
+    "license": "MIT",
+    "private": false,
+    "devDependencies": {
+        "eslint": "^8.30.0",
+        "eslint-config-google": "^0.14.0",
+        "filepath": "^1.1.0",
+        "mocha": "^10.2.0",
+        "rollup": "^3.7.5",
+        "terser": "^5.16.1"
+    }
+}

package/src/date-time.js

@@ -0,0 +1,213 @@
+import { getOffset } from './helpers.js';
+import { config, dateStringTimeZoneRegExp, offsetRegExp } from './vars.js';
+import { formatOffset } from './formatter/format.js';
+
+/**
+ * DateTime class
+ * @class
+ */
+export default class DateTime {
+    #date;
+    #timeZone;
+    #locale;
+    #offset = 0;
+    #dynamicTz;
+
+    /**
+     * New DateTime constructor.
+     * @param {string|number|null} [date] The date or timestamp to parse.
+     * @param {object} [options] Options for the new DateTime.
+     * @param {string} [options.timeZone] The timeZone to use.
+     * @param {string} [options.locale] The locale to use.
+     */
+    constructor(date = null, options = {}) {
+        let timestamp;
+        let adjustOffset = false;
+
+        if (date === null) {
+            timestamp = Date.now();
+        } else if (!isNaN(parseInt(date)) && isFinite(date)) {
+            timestamp = date;
+        } else if (date === `${date}`) {
+            timestamp = Date.parse(date);
+
+            if (isNaN(timestamp)) {
+                throw new Error('Invalid date string supplied');
+            }
+
+            if (!date.match(dateStringTimeZoneRegExp)) {
+                timestamp -= new Date()
+                    .getTimezoneOffset() *
+                    60000;
+            }
+
+            adjustOffset = true;
+        } else {
+            throw new Error('Invalid date supplied');
+        }
+
+        this.#date = new Date(timestamp);
+        this.#dynamicTz = false;
+        this.isValid = true;
+
+        let timeZone = options.timeZone;
+
+        if (!timeZone) {
+            timeZone = config.defaultTimeZone;
+        }
+
+        if (['Z', 'GMT'].includes(timeZone)) {
+            timeZone = 'UTC';
+        }
+
+        const match = timeZone.match(offsetRegExp);
+        if (match) {
+            this.#offset = match[2] * 60 + parseInt(match[4] || 0);
+            if (this.#offset && match[1] === '+') {
+                this.#offset *= -1;
+            }
+
+            if (this.#offset) {
+                this.#timeZone = formatOffset(this.#offset);
+            } else {
+                this.#dynamicTz = true;
+                this.#timeZone = 'UTC';
+            }
+        } else {
+            this.#dynamicTz = true;
+            this.#timeZone = timeZone;
+        }
+
+        if (this.#dynamicTz) {
+            this.#offset = getOffset(this);
+        }
+
+        if (adjustOffset && this.#offset) {
+            const oldOffset = this.#offset;
+
+            this.#date.setTime(this.getTime() + this.#offset * 60000);
+
+            if (this.#dynamicTz) {
+                this.#offset = getOffset(this);
+
+                // compensate for DST transitions
+                if (oldOffset !== this.#offset) {
+                    this.#date.setTime(this.getTime() - ((oldOffset - offset) * 60000));
+                }
+            }
+        }
+
+        if (!('locale' in options)) {
+            options.locale = config.defaultLocale;
+        }
+
+        this.#locale = options.locale;
+    }
+
+    /**
+     * Get the name of the current locale.
+     * @return {string} The name of the current locale.
+     */
+    getLocale() {
+        return this.#locale;
+    }
+
+    /**
+     * Get the number of milliseconds since the UNIX epoch.
+     * @return {number} The number of milliseconds since the UNIX epoch.
+     */
+    getTime() {
+        return this.#date.getTime();
+    }
+
+    /**
+     * Get the name of the current timeZone.
+     * @return {string} The name of the current timeZone.
+     */
+    getTimeZone() {
+        return this.#timeZone;
+    }
+
+    /**
+     * Get the UTC offset (in minutes) of the current timeZone.
+     * @return {number} The UTC offset (in minutes) of the current timeZone.
+     */
+    getTimeZoneOffset() {
+        return this.#offset;
+    }
+
+    /**
+     * Determine if the timeZone is dynamic.
+     * @return {Boolean} TRUE if the timeZone is dynamic, otherwise FALSE.
+     */
+    isDynamicTimeZone() {
+        return this.#dynamicTz;
+    }
+
+    /**
+     * Set the current locale.
+     * @param {string} locale The name of the timeZone.
+     * @return {DateTime} The DateTime object.
+     */
+    setLocale(locale) {
+        return new DateTime(this.getTime(), {
+            locale,
+            timeZone: this.#timeZone,
+        });
+    }
+
+    /**
+     * Set the number of milliseconds since the UNIX epoch.
+     * @param {number} time The number of milliseconds since the UNIX epoch.
+     * @return {DateTime} The DateTime object.
+     */
+    setTime(time) {
+        return new DateTime(time, {
+            locale: this.#locale,
+            timeZone: this.#timeZone,
+        });
+    }
+
+    /**
+     * Set the current timeZone.
+     * @param {string} timeZone The name of the timeZone.
+     * @return {DateTime} The DateTime object.
+     */
+    setTimeZone(timeZone) {
+        return new DateTime(this.getTime(), {
+            locale: this.#locale,
+            timeZone,
+        });
+    }
+
+    /**
+     * Set the current UTC offset.
+     * @param {number} offset The UTC offset (in minutes).
+     * @return {DateTime} The DateTime object.
+     */
+    setTimeZoneOffset(offset) {
+        return new DateTime(this.getTime(), {
+            locale: this.#locale,
+            timeZone: formatOffset(offset),
+        });
+    }
+
+    /**
+     * Get the number of milliseconds since the UNIX epoch.
+     * @return {number} The number of milliseconds since the UNIX epoch.
+     */
+    valueOf() {
+        return this.getTime();
+    }
+
+    /**
+     * Return a primitive value of the DateTime.
+     * @param {string} hint The type hint.
+     * @return {string|number}
+     */
+    [Symbol.toPrimitive](hint) {
+        return hint === 'number' ?
+            this.valueOf() :
+            this.toString();
+    }
+}

package/src/factory.js

@@ -0,0 +1,73 @@
+/**
+ * DateTime Factory
+ */
+
+const data = {};
+
+/**
+ * Get values from cache (or generate if they don't exist).
+ * @param {string} key The key for the values.
+ * @param {function} callback The callback to generate the values.
+ * @return {array} The cached values.
+ */
+export function getData(key, callback) {
+    if (!(key in data)) {
+        data[key] = callback();
+    }
+
+    return data[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.
+ */
+export function getDateFormatter(timeZone) {
+    return getData(
+        `dateFormatter.${timeZone}`,
+        (_) => makeFormatter('en', {
+            timeZone,
+            hourCycle: 'h23',
+            year: 'numeric',
+            month: 'numeric',
+            day: 'numeric',
+            hour: 'numeric',
+            minute: 'numeric',
+        }),
+    );
+};
+
+/**
+ * Create a new relative formatter for a locale.
+ * @param {string} locale The locale.
+ * @param {object} options The options for the formatter.
+ * @return {Intl.RelativeTimeFormat} A new RelativeTimeFormat object.
+ */
+export function getRelativeFormatter(locale) {
+    if (!('RelativeTimeFormat' in Intl)) {
+        return null;
+    }
+
+    return getData(
+        `relativeFormatter.${locale}`,
+        (_) => new Intl.RelativeTimeFormat(locale, {
+            numeric: 'auto',
+            style: 'long',
+        }),
+    );
+};
+
+/**
+ * Create a new formatter for a locale.
+ * @param {string} locale The locale.
+ * @param {object} options The options for the formatter.
+ * @return {Intl.DateTimeFormat} A new DateTimeFormat object.
+ */
+export function makeFormatter(locale, options) {
+    return new Intl.DateTimeFormat(locale, {
+        timeZone: 'UTC',
+        ...options,
+    });
+};

package/src/formatter/format.js

@@ -0,0 +1,104 @@
+import { makeFormatter } from './../factory.js';
+import { getDayPeriods, getDays, getEras, getMonths, getNumbers } from './values.js';
+
+/**
+ * Format 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.
+ * @return {string} The formatted string.
+ */
+export function formatDay(locale, day, type = 'long', standalone = true) {
+    return getDays(locale, type, standalone)[day];
+};
+
+/**
+ * Format a day period as a locale string.
+ * @param {string} locale The locale.
+ * @param {number} period The period to format (0-1).
+ * @param {string} [type=long] The formatting type.
+ * @return {string} The formatted string.
+ */
+export function formatDayPeriod(locale, period, type = 'long') {
+    return getDayPeriods(locale, type)[period];
+};
+
+/**
+ * Format an era as a locale string.
+ * @param {string} locale The locale.
+ * @param {number} era The period to format (0-1).
+ * @param {string} [type=long] The formatting type.
+ * @return {string} The formatted string.
+ */
+export function formatEra(locale, era, type = 'long') {
+    return getEras(locale, type)[era];
+};
+
+/**
+ * Format 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.
+ * @return {string} The formatted string.
+ */
+export function formatMonth(locale, month, type = 'long', standalone = true) {
+    return getMonths(locale, type, standalone)[month - 1];
+};
+
+/**
+ * Format 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.
+ * @return {string} The formatted string.
+ */
+export function formatNumber(locale, number, padding = 0) {
+    const numbers = getNumbers(locale);
+    return `${number}`
+        .padStart(padding, 0)
+        .replace(/\d/g, (match) => numbers[match]);
+};
+
+/**
+ * Format 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.
+ * @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);
+
+    const sign = offset > 0 ?
+        '-' :
+        '+';
+    const hourString = `${hours}`.padStart(2, 0);
+    const minuteString = minutes || !optionalMinutes ?
+        `${minutes}`.padStart(2, 0) :
+        '';
+    const colon = useColon && minuteString ?
+        ':' :
+        '';
+
+    return `${sign}${hourString}${colon}${minuteString}`;
+};
+
+/**
+ * Format 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.
+ * @param {string} [type=long] The formatting type.
+ * @return {string} The formatted string.
+ */
+export function formatTimeZoneName(locale, timestamp, timeZone, type = 'long') {
+    return makeFormatter(locale, { second: 'numeric', timeZone, timeZoneName: type })
+        .formatToParts(timestamp)
+        .find((part) => part.type === 'timeZoneName')
+        .value;
+};

package/src/formatter/locales.js

@@ -0,0 +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'] };

package/src/formatter/parse.js

@@ -0,0 +1,62 @@
+import { getDayPeriods, getDays, getEras, getMonths, getNumbers } from './values.js';
+import { weekDay } from './utility.js';
+
+/**
+ * Parse 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).
+ */
+export function parseDay(locale, value, type = 'long', standalone = true) {
+    const day = getDays(locale, type, standalone).indexOf(value) || 7;
+    return weekDay(locale, day);
+};
+
+/**
+ * Parse 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.
+ * @return {number} The day period (0-1).
+ */
+export function parseDayPeriod(locale, value, type = 'long') {
+    return getDayPeriods(locale, type).indexOf(value);
+};
+
+/**
+ * Parse 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.
+ * @return {number} The era (0-1).
+ */
+export function parseEra(locale, value, type = 'long') {
+    return getEras(locale, type).indexOf(value);
+};
+
+/**
+ * Parse 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.
+ * @return {number} The month number (1-12).
+ */
+export function parseMonth(locale, value, type = 'long', standalone = true) {
+    return getMonths(locale, type, standalone).indexOf(value) + 1;
+};
+
+/**
+ * Parse 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)),
+    );
+};