Light Date :alarm_clock:

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

import {format, localeFormat} from 'light-date';

const date = new Date();

format(date, `Current date: ${localeFormat(date, '{MMMM}')} {dd}, {yyyy}`);

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"

License

MIT © Antoni Kepinski