date-token-format
TypeScript icon, indicating that this package has built-in type declarations

0.5.1 • Public • Published

Date Token Format

A tiny (~4kB before gzip), locale-aware format function for dates, using unicode date tokens to format the returned string along with localized preset formats.

Test coverage Minimised code size Types included License: ISC

Usage

yarn add date-token-format
import { format, Presets } from "date-token-format"

The format method takes a Date object and returns a formatted date string.

format(
  date: Date | string,
  format?: Intl.DateTimeFormatOptions | string,
  locale?: string,
  timeZoneName?: 'short' | 'long'
)

The date can be either a valid JavaScript date object or a string that can be parsed into a date, such as 2021-08-07.

The format can be a Preset format or a string containing one or more unicode tokens. It also accepts a DateTimeFormat options object.

The optional locale string is a ISO 639-1-compatible locale code such as en-US or fr.

An optional timeZoneName sets whether to show time zone name, either as short or long.

Examples

// Using preset formats

const date = new Date('2021-08-27T12:34:56')

format(date)
//=> 8/27/2021

format(date, Presets.DATETIME_FULL, 'en-US')
//=> Friday, August 27, 2021, 12:34 PM

format(date, Presets.DATETIME_FULL, 'ja-JP')
//=> 2021 年 8 月 7 日土曜日 12:34

// Using format strings

format(date, 'EEEE', 'en-US')
//=> Friday

format(date, 'EEEE', 'de')
//=> Freitag

format(date, 'EEEE') // No locale, defaults to browser's langauge setting
//=> Friday

// Timezone name

format(date, 'h:mm', 'en-US', 'short')
// => 2:34 PM GMT-5

format(date, 'h:mm', 'en-US', 'long')
// => 2:34 PM Eastern Standard Time

Date / Time Formats

As well as formatting tokens, you can also specify date and time formats. These will adapt to the given locale, based on locale and browser interpretation.

const date = new Date('2021-08-27T12:34:56')
import { format, Presets } from 'date-token-format'
format(date, Presets.DATE_SHORT, 'en-US')
//=> 8/27/2021
Preset Output (en-US) Output (ja-JP)
DATE_SHORT 8/27/2021 2021/8/7
DATE_MEDIUM Aug 7, 2021 2021 年 8 月 7 日
DATE_LONG August 7, 2021 2021 年 8 月 7 日
DATE_FULL Saturday, August 7, 2021 2021 年 8 月 7 日土曜日
TIME 2:04 AM 午前 2:04
TIME_WITH_SECONDS 2:04:06 AM 午前 2:04:06
TIME_LONG 2:04:06.789 AM 午前 2:04:06.789
TIME_24 02:04 2:04
TIME_24_WITH_SECONDS 02:04:06 2:04:06
TIME_24_LONG 02:04:06.789 2:04:06.789
DATETIME_SHORT 8/7/2021, 2:04 AM 2021/8/7 2:04
DATETIME_SHORT_WITH_SECONDS 8/7/2021, 2:04:06 AM 2021/8/7 2:04:06
DATETIME_MEDIUM Aug 7, 2021, 2:04 AM 2021 年 8 月 7 日 2:04
DATETIME_MEDIUM_WITH_SECONDS Aug 7, 2021, 2:04:06 AM 2021 年 8 月 7 日 2:04:06
DATETIME_LONG August 7, 2021, 2:04 AM 2021 年 8 月 7 日 2:04
DATETIME_LONG_WITH_SECONDS August 7, 2021, 2:04:06 AM 2021 年 8 月 7 日 2:04:06
DATETIME_FULL Saturday, August 7, 2021, 2:04 AM 2021 年 8 月 7 日土曜日 2:04
DATETIME_FULL_WITH_SECONDS Saturday, August 7, 2021, 2:04:06 AM 2021 年 8 月 7 日土曜日 2:04:06

Unicode tokens

The following options, based on unicode date field symbols can be used to generate a locale-based formatted string.

Category Token Output (en-US) Output (ja-JP)
Year yyyy 2021 2021 年
yy 21 21 年
Month MMMM August 8 月
MMM Aug 8 月
MM 08 08 月
M 8 8 月
Day (numeric) dd 07 07 日
d 7 7 日
Week day EEEE Friday 金曜日
EEE Fri
EE F
Hour (24) HH 08 08 時
H 08 08 時
Hour (12) h 8 AM 午前 8 時
Minute mm 03 03
m 3 3
Second ss 06 06
s 6 6
Fractional second SSS 789 789
SS 78 78
S 7 7
AM/PM a AM 午前

Showing Time Zone (optional)

If you want to add a time zone string to the result, set the optional timeZoneName value to short or long.

By default no time zone is shown.

format(date, 'h:mm', 'en-US', 'short')
// => 2:34 PM GMT-5

format(date, 'h:mm', 'en-US', 'long')
// => 2:34 PM Eastern Standard Time

Browser support

Chrome 24+ IE 11 Edge 11 Safari 10+ Firefox 29+

This utility uses the toLocaleString method to provide locale support. This means all locales are supported via the browser without the need for any extra locale configuration.

It is widely supported across all modern and many not-so-modern browsers.

To ensure better browser support, options such as dateStyle and timeStyle are avoided in favour of more specific options.

Limitations

As this utility makes use of toLocaleString, it is not able to support as many options as you might find in libraries such as date-fns, such as international support for ordinals.

Be aware of potential clashing token letters. For example, if you use s in your format, it will be converted into seconds. This version does not yet include a method for excluding parts of format strings from being processed.

ISC License

Copyright 2021 Donovan Hutchinson

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Package Sidebar

Install

npm i date-token-format

Weekly Downloads

1

Version

0.5.1

License

ISC

Unpacked Size

28 kB

Total Files

26

Last publish

Collaborators

  • donovanhutchinson