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.
- 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.
$ npm install light-date
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!'
Returns a string with formatted date.
Type: Date
Date object, which should be used.
Type: string
String, which you want to format, for example: {yyyy}-{MM}-{dd}
or Current time: {hh}:{mm}:{ss}
.
Returns a string with formatted date. Uses Intl.DateTimeFormat()
for locale-based formatting.
Type: Date
Date object, which should be used.
Type: string
String, which you want to format, for example: {EEE}
or Era: {GGG}
.
Type: string | string[]
Default: 'en-US'
Locale(s), which will be used for formatting.
Format of the string is based on Unicode Technical Standard #35.
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 |
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 |
# 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)
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
scripts
section ofpackage.json
to 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 start
ornpm test
, Node will load the full ICU data fromnode_modules/full-icu
, and you should get correctly formatted results.The
cross-env
package is needed to support setting environment variables on Windows.
MIT © Antoni Kepinski