Date: 2024-04-29 Title: Date Format Utility with date-fns

Date Format Utility with date-fns

Introduction

This document describes the use of the DateFormat enum in conjunction with date-fns to standardize date formatting across a JavaScript/TypeScript project. By encapsulating commonly used date format strings into an enum, we enhance code readability, maintainability, and reduce the risk of typos and inconsistencies.

Overview

The DateFormat enum includes a comprehensive list of date format options that can be used with the date-fns library to format dates. This approach standardizes date formatting throughout the application and ensures consistency across different parts of the application.

Installation

First, ensure that you have date-fns installed in your project. If not, you can add it by running:

npm install date-fns

Usage

Here’s how to use the DateFormat enum in your project:

Basic Usage

Import the enum and the format function from date-fns wherever you need to format dates:

import { format } from 'date-fns';
import { DateFormat } from 'date-fns-format';

const today = new Date();
const formattedDate = format(today, DateFormat.YearFourDigits);
console.log('Formatted Year:', formattedDate);

Advanced Usage

You can use the enum in more complex scenarios such as components or services where multiple date formats are required:

import { format } from 'date-fns';
import { DateFormat } from './path/to/DateFormat';

const logFormattedDates = (date: Date) => {
    console.log('Full Date:', format(date, DateFormat.LongLocalizedDate));
    console.log('Month:', format(date, DateFormat.MonthFull));
    console.log('Weekday:', format(date, DateFormat.DayOfWeekFull));
}

Benefits

-Consistency*: Using the enum ensures that date formats are consistent throughout the application. -Maintenance*: Easy to update and maintain date formats in one location. -Readability*: More readable codebase with clear references to date formats instead of raw strings.

Conclusion

Using the DateFormat enum with date-fns enhances your project's date handling by providing a clear, maintainable method for dealing with date formats. This method reduces errors and improves the development experience.

Table Display

Accepted patterns: | Unit | Pattern | Result examples | Notes | | ------------------------------- | -------- | --------------------------------- | ----- | | Era | G..GGG | AD, BC | | | | GGGG | Anno Domini, Before Christ | 2 | | | GGGGG | A, B | | | Calendar year | y | 44, 1, 1900, 2017 | 5 | | | yo | 44th, 1st, 0th, 17th | 5,7 | | | yy | 44, 01, 00, 17 | 5 | | | yyy | 044, 001, 1900, 2017 | 5 | | | yyyy | 0044, 0001, 1900, 2017 | 5 | | | yyyyy | ... | 3,5 | | Local week-numbering year | Y | 44, 1, 1900, 2017 | 5 | | | Yo | 44th, 1st, 1900th, 2017th | 5,7 | | | YY | 44, 01, 00, 17 | 5,8 | | | YYY | 044, 001, 1900, 2017 | 5 | | | YYYY | 0044, 0001, 1900, 2017 | 5,8 | | | YYYYY | ... | 3,5 | | ISO week-numbering year | R | -43, 0, 1, 1900, 2017 | 5,7 | | | RR | -43, 00, 01, 1900, 2017 | 5,7 | | | RRR | -043, 000, 001, 1900, 2017 | 5,7 | | | RRRR | -0043, 0000, 0001, 1900, 2017 | 5,7 | | | RRRRR | ... | 3,5,7 | | Extended year | u | -43, 0, 1, 1900, 2017 | 5 | | | uu | -43, 01, 1900, 2017 | 5 | | | uuu | -043, 001, 1900, 2017 | 5 | | | uuuu | -0043, 0001, 1900, 2017 | 5 | | | uuuuu | ... | 3,5 | | Quarter (formatting) | Q | 1, 2, 3, 4 | | | | Qo | 1st, 2nd, 3rd, 4th | 7 | | | QQ | 01, 02, 03, 04 | | | | QQQ | Q1, Q2, Q3, Q4 | | | | QQQQ | 1st quarter, 2nd quarter, ... | 2 | | | QQQQQ | 1, 2, 3, 4 | 4 | | Quarter (stand-alone) | q | 1, 2, 3, 4 | | | | qo | 1st, 2nd, 3rd, 4th | 7 | | | qq | 01, 02, 03, 04 | | | | qqq | Q1, Q2, Q3, Q4 | | | | qqqq | 1st quarter, 2nd quarter, ... | 2 | | | qqqqq | 1, 2, 3, 4 | 4 | | Month (formatting) | M | 1, 2, ..., 12 | | | | Mo | 1st, 2nd, ..., 12th | 7 | | | MM | 01, 02, ..., 12 | | | | MMM | Jan, Feb, ..., Dec | | | | MMMM | January, February, ..., December | 2 | | | MMMMM | J, F, ..., D | | | Month (stand-alone) | L | 1, 2, ..., 12 | | | | Lo | 1st, 2nd, ..., 12th | 7 | | | LL | 01, 02, ..., 12 | | | | LLL | Jan, Feb, ..., Dec | | | | LLLL | January, February, ..., December | 2 | | | LLLLL | J, F, ..., D | | | Local week of year | w | 1, 2, ..., 53 | | | | wo | 1st, 2nd, ..., 53th | 7 | | | ww | 01, 02, ..., 53 | | | ISO week of year | I | 1, 2, ..., 53 | 7 | | | Io | 1st, 2nd, ..., 53th | 7 | | | II | 01, 02, ..., 53 | 7 | | Day of month | d | 1, 2, ..., 31 | | | | do | 1st, 2nd, ..., 31st | 7 | | | dd | 01, 02, ..., 31 | | | Day of year | D | 1, 2, ..., 365, 366 | 9 | | | Do | 1st, 2nd, ..., 365th, 366th | 7 | | | DD | 01, 02, ..., 365, 366 | 9 | | | DDD | 001, 002, ..., 365, 366 | | | | DDDD | ... | 3 | | Day of week (formatting) | E..EEE | Mon, Tue, Wed, ..., Sun | | | | EEEE | Monday, Tuesday, ..., Sunday | 2 | | | EEEEE | M, T, W, T, F, S, S | | | | EEEEEE | Mo, Tu, We, Th, Fr, Sa, Su | | | ISO day of week (formatting) | i | 1, 2, 3, ..., 7 | 7 | | | io | 1st, 2nd, ..., 7th | 7 | | | ii | 01, 02, ..., 07 | 7 | | | iii | Mon, Tue, Wed, ..., Sun | 7 | | | iiii | Monday, Tuesday, ..., Sunday | 2,7 | | | iiiii | M, T, W, T, F, S, S | 7 | | | iiiiii | Mo, Tu, We, Th, Fr, Sa, Su | 7 | | Local day of week (formatting) | e | 2, 3, 4, ..., 1 | | | | eo | 2nd, 3rd, ..., 1st | 7 | | | ee | 02, 03, ..., 01 | | | | eee | Mon, Tue, Wed, ..., Sun | | | | eeee | Monday, Tuesday, ..., Sunday | 2 | | | eeeee | M, T, W, T, F, S, S | | | | eeeeee | Mo, Tu, We, Th, Fr, Sa, Su | | | Local day of week (stand-alone) | c | 2, 3, 4, ..., 1 | | | | co | 2nd, 3rd, ..., 1st | 7 | | | cc | 02, 03, ..., 01 | | | | ccc | Mon, Tue, Wed, ..., Sun | | | | cccc | Monday, Tuesday, ..., Sunday | 2 | | | ccccc | M, T, W, T, F, S, S | | | | cccccc | Mo, Tu, We, Th, Fr, Sa, Su | | | AM, PM | a..aa | AM, PM | | | | aaa | am, pm | | | | aaaa | a.m., p.m. | 2 | | | aaaaa | a, p | | | AM, PM, noon, midnight | b..bb | AM, PM, noon, midnight | | | | bbb | am, pm, noon, midnight | | | | bbbb | a.m., p.m., noon, midnight | 2 | | | bbbbb | a, p, n, mi | | | Flexible day period | B..BBB | at night, in the morning, ... | | | | BBBB | at night, in the morning, ... | 2 | | | BBBBB | at night, in the morning, ... | | | Hour [1-12] | h | 1, 2, ..., 11, 12 | | | | ho | 1st, 2nd, ..., 11th, 12th | 7 | | | hh | 01, 02, ..., 11, 12 | | | Hour [0-23] | H | 0, 1, 2, ..., 23 | | | | Ho | 0th, 1st, 2nd, ..., 23rd | 7 | | | HH | 00, 01, 02, ..., 23 | | | Hour [0-11] | K | 1, 2, ..., 11, 0 | | | | Ko | 1st, 2nd, ..., 11th, 0th | 7 | | | KK | 01, 02, ..., 11, 00 | | | Hour [1-24] | k | 24, 1, 2, ..., 23 | | | | ko | 24th, 1st, 2nd, ..., 23rd | 7 | | | kk | 24, 01, 02, ..., 23 | | | Minute | m | 0, 1, ..., 59 | | | | mo | 0th, 1st, ..., 59th | 7 | | | mm | 00, 01, ..., 59 | | | Second | s | 0, 1, ..., 59 | | | | so | 0th, 1st, ..., 59th | 7 | | | ss | 00, 01, ..., 59 | | | Fraction of second | S | 0, 1, ..., 9 | | | | SS | 00, 01, ..., 99 | | | | SSS | 000, 001, ..., 999 | | | | SSSS | ... | 3 | | Timezone (ISO-8601 w/ Z) | X | -08, +0530, Z | | | | XX | -0800, +0530, Z | | | | XXX | -08:00, +05:30, Z | | | | XXXX | -0800, +0530, Z, +123456 | 2 | | | XXXXX | -08:00, +05:30, Z, +12:34:56 | | | Timezone (ISO-8601 w/o Z) | x | -08, +0530, +00 | | | | xx | -0800, +0530, +0000 | | | | xxx | -08:00, +05:30, +00:00 | 2 | | | xxxx | -0800, +0530, +0000, +123456 | | | | xxxxx | -08:00, +05:30, +00:00, +12:34:56 | | | Timezone (GMT) | O...OOO | GMT-8, GMT+5:30, GMT+0 | | | | OOOO | GMT-08:00, GMT+05:30, GMT+00:00 | 2 | | Timezone (specific non-locat.) | z...zzz | GMT-8, GMT+5:30, GMT+0 | 6 | | | zzzz | GMT-08:00, GMT+05:30, GMT+00:00 | 2,6 | | Seconds timestamp | t | 512969520 | 7 | | | tt | ... | 3,7 | | Milliseconds timestamp | T | 512969520900 | 7 | | | TT | ... | 3,7 | | Long localized date | P | 04/29/1453 | 7 | | | PP | Apr 29, 1453 | 7 | | | PPP | April 29th, 1453 | 7 | | | PPPP | Friday, April 29th, 1453 | 2,7 | | Long localized time | p | 12:00 AM | 7 | | | pp | 12:00:00 AM | 7 | | | ppp | 12:00:00 AM GMT+2 | 7 | | | pppp | 12:00:00 AM GMT+02:00 | 2,7 | | Combination of date and time | Pp | 04/29/1453, 12:00 AM | 7 | | | PPpp | Apr 29, 1453, 12:00:00 AM | 7 | | | PPPppp | April 29th, 1453 at ... | 7 | | | PPPPpppp | Friday, April 29th, 1453 at ... | 2,7 |

Notes:

1. "Formatting" units (e.g. formatting quarter) in the default en-US locale are the same as "stand-alone" units, but are different in some languages. "Formatting" units are declined according to the rules of the language in the context of a date. "Stand-alone" units are always nominative singular:

   format(new Date(2017, 10, 6), 'do LLLL', {locale: cs}) //=> '6. listopad'

   format(new Date(2017, 10, 6), 'do MMMM', {locale: cs}) //=> '6. listopadu'

2. Any sequence of the identical letters is a pattern, unless it is escaped by the single quote characters (see below). If the sequence is longer than listed in table (e.g. EEEEEEEEEEE) the output will be the same as default pattern for this unit, usually the longest one (in case of ISO weekdays, EEEE). Default patterns for units are marked with "2" in the last column of the table.

   format(new Date(2017, 10, 6), 'MMM') //=> 'Nov'

   format(new Date(2017, 10, 6), 'MMMM') //=> 'November'

   format(new Date(2017, 10, 6), 'MMMMM') //=> 'N'

   format(new Date(2017, 10, 6), 'MMMMMM') //=> 'November'

   format(new Date(2017, 10, 6), 'MMMMMMM') //=> 'November'

3. Some patterns could be unlimited length (such as yyyyyyyy). The output will be padded with zeros to match the length of the pattern.

   format(new Date(2017, 10, 6), 'yyyyyyyy') //=> '00002017'

4. QQQQQ and qqqqq could be not strictly numerical in some locales. These tokens represent the shortest form of the quarter.

5. The main difference between y and u patterns are B.C. years:

   | Year | y | u | | ---- | --- | --- | | AC 1 | 1 | 1 | | BC 1 | 1 | 0 | | BC 2 | 2 | -1 |

   Also yy always returns the last two digits of a year, while uu pads single digit years to 2 characters and returns other years unchanged:

   | Year | yy | uu | | ---- | ---- | ---- | | 1 | 01 | 01 | | 14 | 14 | 14 | | 376 | 76 | 376 | | 1453 | 53 | 1453 |

   The same difference is true for local and ISO week-numbering years (Y and R), except local week-numbering years are dependent on options.weekStartsOn and options.firstWeekContainsDate (compare getISOWeekYear and getWeekYear).

6. Specific non-location timezones are currently unavailable in date-fns, so right now these tokens fall back to GMT timezones.

7. These patterns are not in the Unicode Technical Standard #35:

   • i: ISO day of week
   • I: ISO week of year
   • R: ISO week-numbering year
   • t: seconds timestamp
   • T: milliseconds timestamp
   • o: ordinal number modifier
   • P: long localized date
   • p: long localized time

8. YY and YYYY tokens represent week-numbering years but they are often confused with years. You should enable options.useAdditionalWeekYearTokens to use them. See: unicodeTokens

9. D and DD tokens represent days of the year but they are often confused with days of the month. You should enable options.useAdditionalDayOfYearTokens to use them. See: unicodeTokens

@typeParam DateType - The Date type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like UTCDate.

@param date - The original date @param format - The string of tokens @param options - An object with options

@returns The formatted date string

@throws date must not be Invalid Date @throws options.locale must contain localize property @throws options.locale must contain formatLong property @throws use yyyy instead of YYYY for formatting years using [format provided] to the input [input provided]; see: unicodeTokens @throws use yy instead of YY for formatting years using [format provided] to the input [input provided]; see: unicodeTokens @throws use d instead of D for formatting days of the month using [format provided] to the input [input provided]; see: unicodeTokens @throws use dd instead of DD for formatting days of the month using [format provided] to the input [input provided]; see: unicodeTokens @throws format string contains an unescaped latin alphabet character

@example // Represent 11 February 2014 in middle-endian format: const result = format(new Date(2014, 1, 11), 'MM/dd/yyyy') //=> '02/11/2014'

@example // Represent 2 July 2014 in Esperanto: import { eoLocale } from 'date-fns/locale/eo' const result = format(new Date(2014, 6, 2), "do 'de' MMMM yyyy", { locale: eoLocale }) //=> '2-a de julio 2014'

@example

// Escape string by single quote characters:
const result = format(new Date(2014, 6, 2, 15), "h 'o''clock'")
//=> "3 o'clock"

License

Specify your project's license here, if applicable.

Deployment

Include additional sections if necessary, detailing deployment processes, additional configurations, or contributions guidelines, depending on the complexity and usage of your project.