dayjs-parser

A comprehensive and extensible date parsing plugin for dayjs. It allows passing a wide variety of date formats to dayjs(). Most locales are supported automatically.

It uses any-date-parser for parsing date strings.

Motivation
Installation
Usage
Recognized Formats
Adding Custom Formats
Locale Support
Sister Packages
Unit Testing
Contributing

Motivation

The APIs I consume have a lot of different date formats
I want to create REST APIs that accept all major formats
I want to handle user-input dates
I want to support dates in other languages according to JavaScript's new Intl global object

Installation

npm install dayjs dayjs-parser

Usage

OPTION 1: Use a single import

const dayjs = require('dayjs-parser/dayjs');

const date1 = dayjs('March 5th, 2016 at 7:05pm');
const date2 = dayjs('9 days ago');
const date3 = dayjs('2016-03-05 23:59:59 CST');

OPTION 2: Register as a regular dayjs plugin

const dayjs = require('dayjs');
const parserPlugin = require('dayjs-parser');

dayjs.extend(parserPlugin);

const date1 = dayjs('Wed Jan 19 2022 17:52:46');
const date2 = dayjs('in 2 weeks');
const date3 = dayjs('2016-03-05T23:59:59.000Z');

Recognized Formats

24 hour time
12 hour time
timezone offsets
timezone abbreviations
year month day
year monthname day
month day year
monthname day year
day month year
day monthname year
+/-/ago periods
now/today/yesterday/tomorrow
Twitter

dayjs-parser relies on any-date-format which supports even more formats. See the exhaustive list.

Adding Custom Formats

See any-date-format's instructions.

Example:

const parser = require('dayjs-parser');

parser.addFormat(
	new parser.Format({
		matcher: /^Q([1-4]) (\d{4})$/,
		handler: function ([, quarter, year]) {
			const monthByQuarter = { 1: 1, 2: 4, 3: 7, 4: 10 };
			const month = monthByQuarter[quarter];
			return { year, month };
		},
	})
);

Locale Support

Locales are supported by first setting the global locale:

const parserPlugin = require('dayjs-parser');
dayjs.extend(parserPlugin);
dayjs.locale('fr');

const date = dayjs('15 septembre 2015');

See the Dayjs docs on locales

Sister Packages

Standalone Parser: any-date-format
Luxon: luxon-parser
Moment: moment-parseplus

Unit Testing

dayjs-parser has 100% code coverage.

To run tests, run npm test
To check coverage, run npm run coverage

Unit tests require a global install of full-icu and dayjs. The test runner will attempt to install these if absent.

Contributing

Contributions are welcome. Please open a GitHub ticket for bugs or feature requests. Please make a pull request for any fixes or new code you'd like to be incorporated.

perpil / dayjs-parser