luxon-parser

A comprehensive and extensible date parsing plugin for Luxon. It allows passing a wide variety of date formats to new functions DateTime.fromHuman() and DateTime.fromAny(). Most locales are supported automatically.

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

Table of Contents

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

Motivation

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

Installation

npm install luxon luxon-parser

Usage

const { DateTime } = require('luxon');
require('luxon-parser');

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

DateTime.fromHuman(string, options)

Create a DateTime from any given String. Equivalent to auto choosing the right from*() function:

• DateTime.fromFormat()
• DateTime.fromHTTP()
• DateTime.fromISO()
• DateTime.fromRFC2822()
• DateTime.fromSQL()
• DateTime.fromString()

DateTime.fromAny(any, options)

Create a DateTime from any given type. Equivalent to auto choosing the right from*() function:

• DateTime.now()
• DateTime.fromFormat()
• DateTime.fromHTTP()
• DateTime.fromISO()
• DateTime.fromJSDate()
• DateTime.fromMillis()
• DateTime.fromObject()
• DateTime.fromRFC2822()
• DateTime.fromSQL()
• DateTime.fromString()

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

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

Adding Custom Formats

See any-date-parser's instructions.

Example:

const parser = require('luxon-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 through a second argument:

const date = DateTime.fromAny('15 septembre 2015', { locale: 'fr' });

See the Luxon docs on locales

Sister Packages

• Standalone Parser: any-date-parser
• DayJS Parser: dayjs-parser
• Moment Parser: moment-parseplus

Unit Testing

luxon-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 luxon. 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.