https://github.com/dirheimerb/date-fns-format
Format options for date-fns
https://github.com/dirheimerb/date-fns-format
date-fns format
Last synced: about 1 year ago
JSON representation
Format options for date-fns
- Host: GitHub
- URL: https://github.com/dirheimerb/date-fns-format
- Owner: dirheimerb
- Created: 2024-04-29T13:50:10.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-04-29T14:01:46.000Z (about 2 years ago)
- Last Synced: 2025-02-01T07:28:59.563Z (over 1 year ago)
- Topics: date-fns, format
- Language: TypeScript
- Homepage: https://github.com/dirheimerb/#readme.md
- Size: 87.9 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
---
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:
```bash
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:
```typescript
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:
```typescript
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](https://date-fns.org/docs/getISOWeekYear)
and [getWeekYear](https://date-fns.org/docs/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](https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md)
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](https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md)
@typeParam DateType - The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like [`UTCDate`](https://github.com/date-fns/utc).
@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](https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md)
@throws use `yy` instead of `YY` for formatting years using [format provided] to the input [input provided]; see: [unicodeTokens](https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md)
@throws use `d` instead of `D` for formatting days of the month using [format provided] to the input [input provided]; see: [unicodeTokens](https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md)
@throws use `dd` instead of `DD` for formatting days of the month using [format provided] to the input [input provided]; see: [unicodeTokens](https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md)
@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
```js
// 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.
---