date-fns-format

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.

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.

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

npm install date-fns

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

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);

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));
}

-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.

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.

Accepted patterns:

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"

Specify your project's license here, if applicable.

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