Light Date ⏰
Blazing fast & lightweight (180 bytes) date formatting for Node.js and the browser.
This module aims to provide super fast and easy way to format dates, while also staying lightweight.
Highlights
- Small. 174 bytes (minified and gzipped). No dependencies. Size Limit controls the size.
- Fast. See the benchmarks.
- Compliant. Follows Unicode Technical Standard #35.
- Well tested. To make sure it handles various use cases correctly.
- Portable. Works pretty much everywhere.
- Written in TypeScript.
Install
$ npm install light-date
Usage
import {format} from 'light-date';
const date = new Date('5/1/2020, 4:30:09 PM');
format(date, 'The date is {MM}/{dd}/{yyyy}!'); //=> 'The date is 05/01/2020!'API
format(date, exp)
Returns a string with formatted date.
date
Type: Date
Date object, which should be used.
exp
Type: string
String, which you want to format, for example: {yyyy}-{MM}-{dd} or Current time: {hh}:{mm}:{ss}.
localeFormat(date, exp, locale?)
Returns a string with formatted date. Uses Intl.DateTimeFormat() for locale-based formatting.
date
Type: Date
Date object, which should be used.
exp
Type: string
String, which you want to format, for example: {EEE} or Era: {GGG}.
locale
Type: string | string[]
Default: 'en-US'
Locale(s), which will be used for formatting.
Patterns
Format of the string is based on Unicode Technical Standard #35.
format
Use this API for simple, most common formatting:
| Unit | Pattern | Result examples |
|---|---|---|
| Calendar year | {yy} |
44, 01, 00, 17 |
{yyyy} |
0044, 0001, 1900, 2020 | |
| Month | {MM} |
01, 02, ..., 12 |
| Day | {dd} |
01, 02, ..., 31 |
| Hour | {HH} |
00, 01, 02, ..., 23 |
| Minute | {mm} |
00, 01, ..., 59 |
| Second | {ss} |
00, 01, ..., 59 |
| Millisecond | {SSS} |
000, 0001, ..., 999 |
localeFormat
Use this API for locale-based formatting:
| Unit | Pattern | Result examples |
|---|---|---|
| Month | {MMM} |
Jan, Feb, ..., Dec |
{MMMM} |
January, February, ..., December | |
{MMMMM} |
J, F, ..., D | |
| Day of week | {E..EEE} |
Mon, Tue, Wed, ..., Sun |
{EEEE} |
Monday, Tuesday, ..., Sunday | |
{EEEEE} |
M, T, W, T, F, S, S |
Benchmarks
# Node.js v12.18.3
light-date x 1,465,394 ops/sec ±0.17% (96 runs sampled)
date-format x 835,649 ops/sec ±0.20% (96 runs sampled)
moment x 650,721 ops/sec ±2.13% (90 runs sampled)
date-fns lightFormat x 459,170 ops/sec ±0.19% (97 runs sampled)
date-fns format x 345,845 ops/sec ±4.30% (90 runs sampled)
dayjs x 281,183 ops/sec ±0.57% (96 runs sampled)
FAQ
How to use format and localeFormat on one string?
import {format, localeFormat} from 'light-date';
const date = new Date();
format(date, `Current date: ${localeFormat(date, '{MMMM}')} {dd}, {yyyy}`);How to escape pattern-reserved sequences?
Add a backslash before the opening curly bracket:
import {format} from 'light-date';
format(new Date(), "I'm escaped: \\{yyyy} but I'm not: {yyyy}");
//=> "I'm espaced: {yyyy} but I'm not: 2020"To avoid having to escape backslashes, use String.raw:
format(new Date(), String.raw`I'm escaped: \{yyyy} but I'm not: {yyyy}`;
//=> "I'm espaced: {yyyy} but I'm not: 2020"Why doesn't localeFormat work correctly with some locales in Node?
Before version 13, Node is shipped with limited ICU data (= localization data).
Because of this, using certain locales with localeFormat may produce incorrect results in Node up to version 12.
You can either use Node 13+ or install full ICU data manually:
-
npm install --save cross-env full-icu -
Update the
scriptssection ofpackage.jsonto set the environment variableNODE_ICU_DATA. For example:{ "scripts": { // Before "start": "index.js", "test": "react-scripts test", // After "start": "cross-env NODE_ICU_DATA=node_modules/full-icu index.js", "test": "cross-env NODE_ICU_DATA=node_modules/full-icu react-scripts test" } }
This way, when you run
npm startornpm test, Node will load the full ICU data fromnode_modules/full-icu, and you should get correctly formatted results.The
cross-envpackage is needed to support setting environment variables on Windows.
License
MIT © Antoni Kepinski