date-fns-format

---

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.

---