What is chrono-node?
chrono-node is a natural language date parser in JavaScript. It can parse dates from various date formats and natural language text, making it useful for applications that need to understand and manipulate dates from user input.
What are chrono-node's main functionalities?
Parsing Dates from Natural Language
This feature allows you to parse dates from natural language text. In this example, the text 'Let's meet on Tuesday' is parsed to a Date object representing the next Tuesday.
const chrono = require('chrono-node');
const result = chrono.parseDate('Let's meet on Tuesday');
console.log(result);
Parsing Dates with Specific Time
This feature allows you to parse dates that include specific times. The text 'The event is at 5 PM on 20th October' is parsed to a Date object representing the specified date and time.
const chrono = require('chrono-node');
const result = chrono.parseDate('The event is at 5 PM on 20th October');
console.log(result);
Parsing Relative Dates
This feature allows you to parse relative dates. The text '2 days from now' is parsed to a Date object representing the date two days from the current date.
const chrono = require('chrono-node');
const result = chrono.parseDate('2 days from now');
console.log(result);
Customizing Parsers
This feature allows you to customize the parsers used by chrono-node. In this example, a custom parser is created and used to parse the text 'next Friday'.
const chrono = require('chrono-node');
const customParser = new chrono.Chrono();
customParser.parsers.push(new chrono.Parser());
const result = customParser.parseDate('next Friday');
console.log(result);
Other packages similar to chrono-node
date-fns
date-fns is a modern JavaScript date utility library that provides comprehensive, yet simple, functions for working with dates. Unlike chrono-node, which focuses on natural language parsing, date-fns offers a wide range of date manipulation and formatting functions.
moment
Moment.js is a widely-used library for parsing, validating, manipulating, and formatting dates. While it does not focus on natural language parsing like chrono-node, it provides extensive functionality for handling dates and times in JavaScript.
luxon
Luxon is a modern JavaScript library for working with dates and times, created by one of the Moment.js developers. It offers a more modern API and better support for internationalization compared to Moment.js, but like Moment.js, it does not specialize in natural language parsing.
Chrono
A natural language date parser in Javascript, designed for extracting date information from any given text.
Chrono supports most date and time formats, such as :
- Today, Tomorrow, Yesterday, Last Friday, etc
- 17 August 2013 - 19 August 2013
- This Friday from 13:00 - 16.00
- 5 days ago
- Sat Aug 17 2013 18:40:39 GMT+0900 (JST)
- 2014-11-30T08:15:30-05:30
Node.js
npm install chrono-node
Browser
<script src="https://rawgithub.com/wanasit/chrono/master/chrono.min.js"></script>
Browserify
Chrono's modules are linked and packaged using Browserify on src/chrono.js
. By default, chrono.js
file exports chrono
object as a window global.
browserify src/chrono.js --s chrono -o chrono.js
USAGE
Simply pass a string to function chrono.parseDate
or chrono.parse
.
> var chrono = require('chrono-node')
> chrono.parseDate('An appointment on Sep 12-13')
Fri Sep 12 2014 12:00:00 GMT-0500 (CDT)
> chrono.parse('An appointment on Sep 12-13');
[ { index: 18,
text: 'Sep 12-13',
tags: { ENMonthNameMiddleEndianParser: true },
start:
{ knownValues: [Object],
impliedValues: [Object] },
end:
{ knownValues: [Object],
impliedValues: [Object] } } ]
Reference Date
Today's "Friday" is different from last month's "Friday".
The meaning of the referenced dates depends on when they are mentioned.
Chrono lets you define a reference date using chrono.parse(text, ref)
and chrono.parseDate(text, ref)
.
> chrono.parseDate('Friday', new Date(2012,7,23));
Fri Aug 24 2012 12:00:00 GMT+0700 (ICT)
> chrono.parseDate('Friday', new Date(2012,7,1));
Fri Aug 03 2012 12:00:00 GMT+0700 (ICT)
Detailed Parsed Results
The function chrono.parse
returns detailed parsing results as objects of class chrono.ParsedResult
.
var results = chrono.parse('I have an appointment tomorrow from 10 to 11 AM')
results[0].index
results[0].text
results[0].ref
results[0].start.date()
results[0].end.date()
ParsedResult
start
The parsed date components as a ParsedComponents objectend
Similar to start
but can be null.index
The location within the input text of this resulttext
The text this result that appears in the inputref
The reference date of this result
ParsedComponents
A group of found date and time components (year, month, hour, etc). ParsedComponents objects consist of knownValues
and impliedValues
.
assign(component, value)
Set known value to the componentimply(component, value)
Set implied value to the componentget(component)
Get known or implied value for the componentisCertain(component)
return true if the value of the component is known.date()
Create a javascript Date
Customize Chrono
Chrono’s extraction pipeline are mainly separated into 'parse' and ‘refine’ phases. During parsing, ‘parsers’ (Parser
) are used to extract patterns from the input text. The parsed results (ParsedResult) are the combined, sorted, then refine using ‘refiners’ (Refiner
). In the refining phase, the results can be combined, filtered-out, or attached with additional information.
Parser
Parser is a module for low-level pattern-based parsing. Ideally, each parser should be designed to handle a single specific date format. User can add new type of parsers for supporting new date formats or languages.
var christmasParser = new chrono.Parser();
christmasParser.pattern = function () { return /Christmas/i }
christmasParser.extract = function(text, ref, match, opt) {
return new chrono.ParsedResult({
ref: ref,
text: match[0],
index: match.index,
start: {
day: 25,
month: 12,
}
});
}
var custom = new chrono.Chrono();
custom.parsers.push(christmasParser);
custom.parseDate("I'll arrive at 2.30AM on Christmas night")
To create a custom parser, override pattern
and extract
methods on an object of class chrono.Parser
.
- The
pattern
method must return RegExp
object of searching pattern. - The
extract
method will be called with the
match object when the pattern is found. This function must create and return a result (or null to skip).
Refiner
Refiner is a heigher level module for improving or manipurating the results. User can add a new type of refiner to customize Chrono's results or to add some custom logic to Chrono.
var guessPMRefiner = new chrono.Refiner();
guessPMRefiner.refine = function(text, results, opt) {
results.forEach(function (result) {
if (!result.start.isCertain('meridiem')
&& result.start.get('hour') >= 1 && result.start.get('hour') < 4) {
result.start.assign('meridiem', 1);
result.start.assign('hour', result.start.get('hour') + 12);
}
});
return results;
}
var custom = new chrono.Chrono();
custom.refiners.push(guessPMRefiner);
custom.parseDate("This is at 2.30");
custom.parseDate("This is at 2.30 AM");