diff options
Diffstat (limited to 'date-fns/src/intlFormat/index.ts')
-rw-r--r-- | date-fns/src/intlFormat/index.ts | 116 |
1 files changed, 116 insertions, 0 deletions
diff --git a/date-fns/src/intlFormat/index.ts b/date-fns/src/intlFormat/index.ts new file mode 100644 index 0000000..908a23b --- /dev/null +++ b/date-fns/src/intlFormat/index.ts @@ -0,0 +1,116 @@ +import requiredArgs from '../_lib/requiredArgs/index' + +type Locale = Intl.ResolvedDateTimeFormatOptions['locale'] +type FormatOptions = Intl.DateTimeFormatOptions +type LocaleOptions = { locale: Locale | Locale[] } + +export default function intlFormat(date: Date): string +export default function intlFormat( + date: Date, + localeOptions: LocaleOptions +): string +export default function intlFormat( + date: Date, + formatOptions: FormatOptions +): string +export default function intlFormat( + date: Date, + formatOptions: FormatOptions, + localeOptions: LocaleOptions +): string + +/** + * @name intlFormat + * @category Common Helpers + * @summary Format the date with Intl.DateTimeFormat (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat). + * + * @description + * Return the formatted date string in the given format. + * The method uses [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) inside. + * formatOptions are the same as [`Intl.DateTimeFormat` options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat#using_options) + * + * > ⚠️ Please note that before Node version 13.0.0, only the locale data for en-US is available by default. + * + * @param {Date|Number} argument - the original date. + * @param {Object} [formatOptions] - an object with options. + * @param {'lookup'|'best fit'} [formatOptions.localeMatcher='best fit'] - locale selection algorithm. + * @param {'narrow'|'short'|'long'} [formatOptions.weekday] - representation the days of the week. + * @param {'narrow'|'short'|'long'} [formatOptions.era] - representation of eras. + * @param {'numeric'|'2-digit'} [formatOptions.year] - representation of years. + * @param {'numeric'|'2-digit'|'narrow'|'short'|'long'} [formatOptions.month='numeric'] - representation of month. + * @param {'numeric'|'2-digit'} [formatOptions.day='numeric'] - representation of day. + * @param {'numeric'|'2-digit'} [formatOptions.hour='numeric'] - representation of hours. + * @param {'numeric'|'2-digit'} [formatOptions.minute] - representation of minutes. + * @param {'numeric'|'2-digit'} [formatOptions.second] - representation of seconds. + * @param {'short'|'long'} [formatOptions.timeZoneName] - representation of names of time zones. + * @param {'basic'|'best fit'} [formatOptions.formatMatcher='best fit'] - format selection algorithm. + * @param {Boolean} [formatOptions.hour12] - determines whether to use 12-hour time format. + * @param {String} [formatOptions.timeZone] - the time zone to use. + * @param {Object} [localeOptions] - an object with locale. + * @param {String|String[]} [localeOptions.locale] - the locale code + * @returns {String} the formatted date string. + * @throws {TypeError} 1 argument required. + * @throws {RangeError} `date` must not be Invalid Date + * + * @example + * // Represent 10 October 2019 in German. + * // Convert the date with format's options and locale's options. + * const result = intlFormat(new Date(2019, 9, 4, 12, 30, 13, 456), { + * weekday: 'long', + * year: 'numeric', + * month: 'long', + * day: 'numeric', + * }, { + * locale: 'de-DE', + * }) + * //=> Freitag, 4. Oktober 2019 + * + * @example + * // Represent 10 October 2019. + * // Convert the date with format's options. + * const result = intlFormat.default(new Date(2019, 9, 4, 12, 30, 13, 456), { + * year: 'numeric', + * month: 'numeric', + * day: 'numeric', + * hour: 'numeric', + * }) + * //=> 10/4/2019, 12 PM + * + * @example + * // Represent 10 October 2019 in Korean. + * // Convert the date with locale's options. + * const result = intlFormat(new Date(2019, 9, 4, 12, 30, 13, 456), { + * locale: 'ko-KR', + * }) + * //=> 2019. 10. 4. + * + * @example + * // Represent 10 October 2019 in middle-endian format: + * const result = intlFormat(new Date(2019, 9, 4, 12, 30, 13, 456)) + * //=> 10/4/2019 + */ +export default function intlFormat( + date: Date, + formatOrLocale?: FormatOptions | LocaleOptions, + localeOptions?: LocaleOptions +): string { + requiredArgs(1, arguments) + + let formatOptions: FormatOptions | undefined + + if (isFormatOptions(formatOrLocale)) { + formatOptions = formatOrLocale + } else { + localeOptions = formatOrLocale + } + + return new Intl.DateTimeFormat(localeOptions?.locale, formatOptions).format( + date + ) +} + +function isFormatOptions( + opts: LocaleOptions | FormatOptions | undefined +): opts is FormatOptions { + return opts !== undefined && !('locale' in opts) +} |