Skip to content

⏰ Blazing fast & lightweight (157 bytes) date formatting for Node.js and the browser.

License

Notifications You must be signed in to change notification settings

xxczaki/light-date

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

71 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Light Date ⏰

Blazing fast & lightweight (180 bytes) date formatting for Node.js and the browser.

Build Status Coverage Status XO code style minified size

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.

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

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:

  1. npm install --save cross-env full-icu

  2. Update the scripts section of package.json to set the environment variable NODE_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 or npm test, Node will load the full ICU data from node_modules/full-icu, and you should get correctly formatted results.

    The cross-env package is needed to support setting environment variables on Windows.

License

MIT © Antoni Kepinski

About

⏰ Blazing fast & lightweight (157 bytes) date formatting for Node.js and the browser.

Resources

License

Stars

Watchers

Forks

Packages

No packages published