@fr0st/datetime 8.0.0 → 8.0.2

package/src/factory.js

@@ -16,7 +16,7 @@ export function clearDataCache() {
  * @template T
  * @param {string} key The key for the values.
  * @param {() => T} callback The callback to generate the values.
- * @return {T} The cached value.
+ * @returns {T} The cached value.
  */
 export function getData(key, callback) {
     if (!data.has(key)) {
@@ -29,7 +29,7 @@ export function getData(key, callback) {
 /**
  * Creates a date formatter for a time zone.
  * @param {string} timeZone The time zone.
- * @return {Intl.DateTimeFormat} The formatter instance.
+ * @returns {Intl.DateTimeFormat} The formatter instance.
  */
 export function getDateFormatter(timeZone) {
     return getData(
@@ -52,7 +52,7 @@ export function getDateFormatter(timeZone) {
 /**
  * Creates a relative-time formatter for a locale.
  * @param {string} locale The locale.
- * @return {Intl.RelativeTimeFormat|null} The formatter instance, or null when unsupported.
+ * @returns {Intl.RelativeTimeFormat|null} The formatter instance, or null when unsupported.
  */
 export function getRelativeFormatter(locale) {
     if (!('RelativeTimeFormat' in Intl)) {
@@ -72,7 +72,7 @@ export function getRelativeFormatter(locale) {
  * Creates a formatter for a locale.
  * @param {string} locale The locale.
  * @param {Intl.DateTimeFormatOptions} options The options for the formatter.
- * @return {Intl.DateTimeFormat} The formatter instance.
+ * @returns {Intl.DateTimeFormat} The formatter instance.
  */
 export function makeFormatter(locale, options) {
     return new Intl.DateTimeFormat(locale, {

package/src/formatter/format.js

@@ -5,9 +5,9 @@ import { getDayPeriods, getDays, getEras, getMonths, getNumbers } from './values
  * 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 {string} [type='long'] The formatting type.
  * @param {boolean} [standalone=true] Whether the value is standalone.
- * @return {string} The formatted string.
+ * @returns {string} The formatted string.
  */
 export function formatDay(locale, day, type = 'long', standalone = true) {
     return getDays(locale, type, standalone)[day];
@@ -17,8 +17,8 @@ export function formatDay(locale, day, type = 'long', standalone = true) {
  * Formats a day period as a locale string.
  * @param {string} locale The locale.
  * @param {number} period The day-period index to format. (0-1)
- * @param {string} [type=long] The formatting type.
- * @return {string} The formatted string.
+ * @param {string} [type='long'] The formatting type.
+ * @returns {string} The formatted string.
  */
 export function formatDayPeriod(locale, period, type = 'long') {
     return getDayPeriods(locale, type)[period];
@@ -28,8 +28,8 @@ export function formatDayPeriod(locale, period, type = 'long') {
  * Formats an era as a locale string.
  * @param {string} locale The locale.
  * @param {number} era The era index to format. (0-1)
- * @param {string} [type=long] The formatting type.
- * @return {string} The formatted string.
+ * @param {string} [type='long'] The formatting type.
+ * @returns {string} The formatted string.
  */
 export function formatEra(locale, era, type = 'long') {
     return getEras(locale, type)[era];
@@ -39,9 +39,9 @@ export function formatEra(locale, era, type = 'long') {
  * 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 {string} [type='long'] The formatting type.
  * @param {boolean} [standalone=true] Whether the value is standalone.
- * @return {string} The formatted string.
+ * @returns {string} The formatted string.
  */
 export function formatMonth(locale, month, type = 'long', standalone = true) {
     return getMonths(locale, type, standalone)[month - 1];
@@ -52,7 +52,7 @@ export function formatMonth(locale, month, type = 'long', standalone = true) {
  * @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.
+ * @returns {string} The formatted string.
  */
 export function formatNumber(locale, number, padding = 0) {
     const numbers = getNumbers(locale);
@@ -67,7 +67,7 @@ export function formatNumber(locale, number, padding = 0) {
  * @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.
+ * @returns {string} The formatted offset string.
  */
 export function formatOffset(offset, useColon = true, optionalMinutes = false, includeSeconds = true) {
     const absoluteSeconds = Math.abs(offset * 60);
@@ -102,7 +102,7 @@ export function formatOffset(offset, useColon = true, optionalMinutes = false, i
  * @param {string} locale The locale.
  * @param {number} amount The amount of duration.
  * @param {string} unit The time unit.
- * @return {string} The relative duration.
+ * @returns {string} The relative duration.
  */
 export function formatRelative(locale, amount, unit) {
     const relativeFormatter = getRelativeFormatter(locale);
@@ -119,8 +119,8 @@ export function formatRelative(locale, amount, unit) {
  * @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.
+ * @param {string} [type='long'] The formatting type.
+ * @returns {string} The formatted string.
  */
 export function formatTimeZoneName(locale, timestamp, timeZone, type = 'long') {
     return makeFormatter(locale, { second: 'numeric', timeZone, timeZoneName: type })

package/src/formatter/locale.js

@@ -6,7 +6,7 @@ import { minDaysInFirstWeek, weekStart } from './locales.js';
  * @param {object} data The generated locale data.
  * @param {string[]} candidates The locale candidates.
  * @param {number} fallback The fallback value.
- * @return {number} The locale value.
+ * @returns {number} The locale value.
  */
 function generatedValue(data, candidates, fallback) {
     for (const candidate of candidates) {
@@ -23,7 +23,7 @@ function generatedValue(data, candidates, fallback) {
 /**
  * Gets generated-data candidates for a locale.
  * @param {Intl.Locale} locale The locale.
- * @return {string[]} The locale candidates.
+ * @returns {string[]} The locale candidates.
  */
 function localeCandidates(locale) {
     const localeName = locale.toString().split('-x-', 1)[0];
@@ -48,7 +48,7 @@ function localeCandidates(locale) {
 /**
  * Gets week information for a locale.
  * @param {string} locale The locale.
- * @return {{firstDay: number, minimalDays: number}} The week information.
+ * @returns {{firstDay: number, minimalDays: number}} The week information.
  */
 export function getWeekInfo(locale) {
     return getData(

package/src/formatter/parse.js

@@ -5,9 +5,9 @@ import { getDayPeriods, getDays, getEras, getMonths, getNumbers } from './values
  * 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 {string} [type='long'] The formatting type.
  * @param {boolean} [standalone=true] Whether the value is standalone.
- * @return {number} The local day of the week (1-7).
+ * @returns {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);
@@ -21,8 +21,8 @@ export function parseDay(locale, value, type = 'long', standalone = true) {
  * 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.
- * @return {number} The day period (0-1).
+ * @param {string} [type='long'] The formatting type.
+ * @returns {number} The day period (0-1).
  */
 export function parseDayPeriod(locale, value, type = 'long') {
     return getDayPeriods(locale, type).indexOf(value);
@@ -32,8 +32,8 @@ export function parseDayPeriod(locale, value, type = 'long') {
  * 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.
- * @return {number} The era (0-1).
+ * @param {string} [type='long'] The formatting type.
+ * @returns {number} The era (0-1).
  */
 export function parseEra(locale, value, type = 'long') {
     return getEras(locale, type).indexOf(value);
@@ -43,9 +43,9 @@ export function parseEra(locale, value, type = 'long') {
  * 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 {string} [type='long'] The formatting type.
  * @param {boolean} [standalone=true] Whether the value is standalone.
- * @return {number} The month number (1-12).
+ * @returns {number} The month number (1-12).
  */
 export function parseMonth(locale, value, type = 'long', standalone = true) {
     return getMonths(locale, type, standalone).indexOf(value) + 1;
@@ -55,7 +55,7 @@ export function parseMonth(locale, value, type = 'long', standalone = true) {
  * 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.
+ * @returns {string} The parsed ASCII digit string.
  */
 export function parseNumberString(locale, value) {
     const numbers = getNumbers(locale);
@@ -66,7 +66,7 @@ export function parseNumberString(locale, value) {
  * 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.
+ * @returns {number} The parsed number.
  */
 export function parseNumber(locale, value) {
     return parseInt(

package/src/formatter/utility.js

@@ -4,7 +4,7 @@ import { numberRegExp } from './values.js';
 /**
  * Decodes a quoted ICU format literal.
  * @param {string} literal The literal to decode.
- * @return {string} The decoded literal.
+ * @returns {string} The decoded literal.
  */
 export function decodeLiteral(literal) {
     return literal === `''` ?
@@ -15,7 +15,7 @@ export function decodeLiteral(literal) {
 /**
  * Gets the formatting type from the component token length.
  * @param {number} length The component token length.
- * @return {string} The formatting type.
+ * @returns {string} The formatting type.
  */
 export function getType(length) {
     switch (length) {
@@ -35,7 +35,7 @@ export function getType(length) {
  * @param {number} length The token length.
  * @param {string} locale The parsing locale.
  * @param {boolean} previousNumeric Whether the previous token was an adjacent numeric token.
- * @return {{numeric: boolean, source: string}} The token RegExp data.
+ * @returns {{numeric: boolean, source: string}} The token RegExp data.
  */
 export function getTokenRegExp(source, nextSource, length, locale, previousNumeric) {
     const numberSource = numberRegExp(locale);
@@ -53,7 +53,7 @@ export function getTokenRegExp(source, nextSource, length, locale, previousNumer
 /**
  * Gets the locale's minimum days in the first week of the year.
  * @param {string} locale The locale.
- * @return {number} The minimum day count.
+ * @returns {number} The minimum day count.
  */
 export function minimumDays(locale) {
     return getWeekInfo(locale).minimalDays;
@@ -63,7 +63,7 @@ export function minimumDays(locale) {
  * Converts a Sunday-based day-of-week value to the locale's week numbering.
  * @param {string} locale The locale.
  * @param {number} day The day of the week. (0 = Sunday, 6 = Saturday)
- * @return {number} The local day of the week.
+ * @returns {number} The local day of the week.
  */
 export function weekDay(locale, day) {
     return (7 + parseInt(day, 10) - (getWeekInfo(locale).firstDay % 7)) % 7 + 1;

package/src/formatter/values.js

@@ -8,8 +8,8 @@ import { valuesRegExp } from './../helpers.js';
 /**
  * Gets cached localized day-period labels.
  * @param {string} locale The locale.
- * @param {string} [type=long] The formatting type.
- * @return {string[]} The localized day-period labels.
+ * @param {string} [type='long'] The formatting type.
+ * @returns {string[]} The localized day-period labels.
  */
 export function getDayPeriods(locale, type = 'long') {
     return getData(
@@ -30,9 +30,9 @@ export function getDayPeriods(locale, type = 'long') {
 /**
  * Gets cached localized weekday labels.
  * @param {string} locale The locale.
- * @param {string} [type=long] The formatting type.
+ * @param {string} [type='long'] The formatting type.
  * @param {boolean} [standalone=true] Whether the values are standalone.
- * @return {string[]} The localized weekday labels.
+ * @returns {string[]} The localized weekday labels.
  */
 export function getDays(locale, type = 'long', standalone = true) {
     return getData(
@@ -62,8 +62,8 @@ export function getDays(locale, type = 'long', standalone = true) {
 /**
  * Gets cached localized era labels.
  * @param {string} locale The locale.
- * @param {string} [type=long] The formatting type.
- * @return {string[]} The localized era labels.
+ * @param {string} [type='long'] The formatting type.
+ * @returns {string[]} The localized era labels.
  */
 export function getEras(locale, type = 'long') {
     return getData(
@@ -84,9 +84,9 @@ export function getEras(locale, type = 'long') {
 /**
  * Gets cached localized month labels.
  * @param {string} locale The locale.
- * @param {string} [type=long] The formatting type.
+ * @param {string} [type='long'] The formatting type.
  * @param {boolean} [standalone=true] Whether the values are standalone.
- * @return {string[]} The localized month labels.
+ * @returns {string[]} The localized month labels.
  */
 export function getMonths(locale, type = 'long', standalone = true) {
     return getData(
@@ -116,7 +116,7 @@ export function getMonths(locale, type = 'long', standalone = true) {
 /**
  * Gets cached localized digit glyphs.
  * @param {string} locale The locale.
- * @return {string[]} The localized digit glyphs.
+ * @returns {string[]} The localized digit glyphs.
  */
 export function getNumbers(locale) {
     return getData(
@@ -136,7 +136,7 @@ export function getNumbers(locale) {
  * 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.
+ * @returns {string} The number values RegExp.
  */
 export function numberRegExp(locale, length = null) {
     const quantifier = length === null ?

package/src/helpers.js

@@ -10,7 +10,7 @@ import { diffMethods, thresholds } from './vars.js';
 /**
  * Escapes a string for safe use inside a RegExp source.
  * @param {string} value The string to escape.
- * @return {string} The escaped string.
+ * @returns {string} The escaped string.
  */
 function escapeRegExp(value) {
     return value.replace(/[|\\{}()[\]^$+*?.-]/g, '\\$&');
@@ -19,7 +19,7 @@ function escapeRegExp(value) {
 /**
  * Gets a stable day number from a DateTime's local calendar fields.
  * @param {DateTime} date The DateTime.
- * @return {number} The local calendar day number.
+ * @returns {number} The local calendar day number.
  */
 function calendarDay(date) {
     const calendarDate = new Date(0);
@@ -34,7 +34,7 @@ function calendarDay(date) {
  * @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.
+ * @returns {number} The difference between the dates in the given time unit.
  */
 export function calculateDiff(date, other, timeUnit, relative = true) {
     other = other.withTimeZone(date.getTimeZone());
@@ -147,7 +147,7 @@ export function calculateDiff(date, other, timeUnit, relative = true) {
  * 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.
+ * @returns {string} The values RegExp.
  */
 export function valuesRegExp(values) {
     return values.slice()
@@ -163,7 +163,7 @@ export function valuesRegExp(values) {
  * @param {number} amount The amount to compensate.
  * @param {boolean} [compensate=true] Whether to compensate the amount.
  * @param {number} [compensation=1] The compensation offset.
- * @return {number} The compensated amount.
+ * @returns {number} The compensated amount.
  */
 function compensateDiff(date, other, amount, compensate = true, compensation = 1) {
     if (amount > 0) {
@@ -187,7 +187,7 @@ function compensateDiff(date, other, amount, compensate = true, compensation = 1
  * Gets the biggest difference between two dates.
  * @param {DateTime} date The DateTime.
  * @param {DateTime} [other] The DateTime to compare to.
- * @return {[number, string]} The biggest difference (amount and time unit).
+ * @returns {[number, string]} The biggest difference (amount and time unit).
  */
 export function getBiggestDiff(date, other) {
     let lastResult;
@@ -219,7 +219,7 @@ export function getBiggestDiff(date, other) {
 /**
  * Gets the offset for a DateTime.
  * @param {DateTime} date The DateTime.
- * @return {number} The offset.
+ * @returns {number} The offset.
  */
 export function getOffset(date) {
     const timeZone = date.getTimeZone();
@@ -259,7 +259,7 @@ export function getOffset(date) {
 /**
  * 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).
+ * @returns {number} The number of milliseconds since the UNIX epoch (offset to timeZone).
  */
 export function getOffsetTime(date) {
     return date.getTime() - (date.getTimeZoneOffset() * 60000);
@@ -284,7 +284,7 @@ export function parseCompare(formatString, dateString) {
 /**
  * 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.
+ * @returns {number|null} The timestamp, or null if the shape is not supported.
  */
 export function parseLocalTimestamp(dateString) {
     const match =
@@ -314,7 +314,7 @@ export function parseLocalTimestamp(dateString) {
 
 /**
  * Generates methods for parsing a date.
- * @return {Record<string, {get: Function, set: Function}>} An object containing date parsing methods.
+ * @returns {Record<string, {get: Function, set: Function}>} An object containing date parsing methods.
  */
 export function parseFactory() {
     let isPM = false;
@@ -421,7 +421,7 @@ export function parseFactory() {
  * @param {DateTime} date The DateTime.
  * @param {number} time The number of milliseconds since the UNIX epoch (offset to timeZone).
  * @param {number} [direction=1] The direction to resolve a gap.
- * @return {DateTime} A new DateTime instance.
+ * @returns {DateTime} A new DateTime instance.
  */
 export function setOffsetTime(date, time, direction = 1) {
     const newDate = date.withTime(