ambroseus/light-date

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

Light Date ⏰

Blazing fast & lightweight (157 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. 157 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?

Heading

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

const date = new Date();

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

License

MIT © Antoni Kepinski