light-date
Version:
Blazing fast & lightweight (180 bytes) date formatting for Node.js and the browser.
162 lines (105 loc) • 5 kB
Markdown
# Light Date :alarm_clock:
> Blazing fast & lightweight (180 bytes) date formatting for Node.js and the browser.
[](https://github.com/xxczaki/light-date/actions?query=workflow%3ACI)
[](https://coveralls.io/github/xxczaki/light-date?branch=master)
[](https://github.com/xojs/xo)
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](https://github.com/ai/size-limit) controls the size.
* **Fast.** See the [benchmarks](#benchmarks).
* **Compliant.** Follows [Unicode Technical Standard #35](https://www.unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table).
* **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
```js
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()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/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](https://www.unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table).
##### [`format`](#formatdate-exp)
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`](#localeformatdate-exp-locale)
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
<details>
<summary>How to use <code>format</code> and <code>localeFormat</code> on one string?</summary>
```ts
import {format, localeFormat} from 'light-date';
const date = new Date();
format(date, `Current date: ${localeFormat(date, '{MMMM}')} {dd}, {yyyy}`);
```
</details>
<details>
<summary>How to escape pattern-reserved sequences?</summary>
Add a backslash before the opening curly bracket:
```ts
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`:
```ts
format(new Date(), String.raw`I'm escaped: \{yyyy} but I'm not: {yyyy}`;
//=> "I'm espaced: {yyyy} but I'm not: 2020"
```
</details>
## License
MIT © [Antoni Kepinski](https://kepinski.me)