compromise-dates

v3.7.0

Published

2 months ago

plugin for nlp-compromise

Downloads

43,529

0High
0Medium
0Low

spencermountain

This library is an earnest attempt to get date information out of text, in a clear way -

import nlp from 'compromise'
import datePlugin from 'compromise-dates'
nlp.plugin(datePlugin)

let doc = nlp('the second monday of february')
doc.dates().get()[0]
/*
  { start: '2021-02-08T00:00:00.000Z', end: '2021-02-08T23:59:59.999Z'}
*/

Things it does well:

| explicit-dates | ----------------------------------- | march 2nd | 2 march | tues march 2 | march the second | on the 2nd | tuesday the 2nd | numeric-da | 2020/03/02 | 2020-03-02 | 03-02-2020 | 03/02 | 2020.08.13 | named-date | today | tomorrow | christmas eve | easter | q1 | times: | 2pm | 2:12pm | 2:12 | 02:12:00 | two oclock | before 1 | noon | at night | in the morning | tomorrow evening | timezones: | eastern time | est | peru time | ..in beirut | GMT+9 | -4h | Canada/Eastern | relative | this march | this week | this sunday | next april | this past year | second week of march | last weekend of march | last spring | the saturday after next | punted | in seven weeks | two days after june 6th | 2 weeks from now | 2 weeks after june | 2 years, 4 | a week and a half before | a week friday | start/end: | end of the week | start of next year | middle of q2 last year | date-range | between june and july | from today to next haloween | aug 1 - aug 31 | 22-23 February | today to next friday | during june | aug to june 1999 | before [2019] | by march | after february | repeating- | any wednesday | any day in June | any wednesday this week | weekends in July | every weekday | description | Start | End | | :-----------------------------------: | ---------------: | ---------------: | | | March 2, 12:00am | March 2, 11:59pm | | | '' | '' | | | '' | '' | | natural-language number | '' | '' | | implicit months | '' | '' | | date-reckoning | '' | '' | tes: | | | iso formats | '' | '' | | | '' | '' | | british formats | '' | '' | | | '' | '' | | alt-ISO | '' | '' | s: | | | | - | - | | | '' | '' | | calendar-holidays | Dec 24, 12:00am | Dec 24, 11:59pm | | astronomical holidays | -depends- | - | | | Jan 1, 12:00am | Mar 31, 11:59pm | | | | | '' | '' | | | '' | '' | | | '' | '' | | weird iso-times | '' | '' | | written formats | '' | '' | | | '' | '' | | | '' | '' | | informal daytimes | '' | '' | | | '' | '' | | | '' | '' | | | | informal zone support | '' | '' | | TZ shorthands | '' | '' | | | '' | '' | | by location | '' | '' | | by UTC/GMT offset | '' | '' | | '' | '' | '' | | IANA codes | '' | '' | durations: | | | | '' | '' | | | '' | '' | | | '' | '' | | | '' | '' | | | '' | '' | | | '' | '' | | | '' | '' | | | '' | '' | | | '' | '' | dates: | | | now+duration | '' | '' | | date+duration | '' | '' | | | '' | '' | | | '' | '' | months, and 5 days ago | complex durations | '' | '' | | written-out numbers | '' | '' | | idiom format | '' | '' | | | | up-against the ending | '' | '' | | lean-toward starting | '' | '' | | rough-center calculation | '' | '' | s: | | | explicit ranges | '' | '' | | | '' | '' | | dash-ranges | '' | '' | | | '' | '' | | | '' | '' | | | '' | '' | | shared range info | '' | '' | | up-to a date | '' | '' | | | '' | '' | | date-to-infinity | '' | '' | intervals: | | | n-repeating dates | | | repeating-date in range | June 1 ... | .. June 30 | | | '' | '' | | more-complex interval | '' | '' | until February | interval until date | '' | '' |

Things it does awkwardly:

| hmmm, | description | Start | End | | ------------------------ | :--------------------------------------------: | :-----: | :---: | | middle of 2019/June | tries to find the sorta-center | June 15 | '' | | good friday 2025 | tries to reckon astronomically-set holidays | '' | '' | | Oct 22 1975 2am in PST | historical DST changes (assumes current dates) | '' | '' |

Things it doesn't do:

| 😓, | description | Start | End | | ------------------------------------------- | :----------------------: | :-----: | :---: | | not this Saturday, but the Saturday after | self-reference logic | '' | '' | | 3 years ago tomorrow | folksy short-hand | '' | '' | | 2100 | military time formats | '' | '' | | may 97 | 'bare' 2-digit years | '' | '' |

API

.dates() - find dates like June 8th or 03/03/18
- .dates().get() - simple start/end json result
- .dates().json() - overloaded output with date metadata
- .dates().format('') - convert the dates to specific formats
- .dates().isBefore(iso) - return only dates occuring before given date
- .dates().isAfter(iso) - return only dates occuring after given date
- .dates().isSame(unit, iso) - return only dates within a given year, month, date
.durations() - 2 weeks or 5mins
- .durations().get() - return simple json for duration
- .durations().json() - overloaded output with duration metadata
.times() - 4:30pm or half past five
- .durations().get() - return simple json for times
- .times().json() - overloaded output with time metadata

Configuration:

.dates() accepts an optional object, that lets you set the context for the date parsing.

const context = {
  timezone: 'Canada/Eastern', //the default timezone is 'ETC/UTC'
  today: '2020-02-20', //the implicit, or reference day/year
  punt: { weeks: 2 }, // the implied duration to use for 'after june 2nd'
  dayStart: '8:00am',
  dayEnd: '5:30pm',
  dmy : false //assume british-format dates, when unclear
}

nlp('in two days').dates(context).get()
/*
  [{ start: '2020-02-22T08:00:00.000+5:00', end: '2020-02-22T17:30:00.000+5:00' }]
*/

Opinions:

Start of week:

By default, weeks start on a Monday, and 'next week' will run from Monday morning to Sunday night. This can be configued in spacetime, but right now we are not passing-through this config.

Implied durations:

'after October' returns a range starting Nov 1st, and ending 2-weeks after, by default. This can be configured by setting punt param in the context object:

doc.dates({ punt: { month: 1 } })

Future bias:

'May 7th' will prefer a May 7th in the future.

The parser will return a past-date though, in the current-month:

// from march 2nd
nlp('feb 30th').dates({ today: '2021-02-01' }).get()

This/Next/Last:

named-weeks or months eg 'this/next/last week' are mostly straight-forward.

This monday

A bare 'monday' will always refer to itself, or the upcoming monday.

Saying 'this monday' on monday, is itself.
Saying 'this monday' on tuesday , is next week.

Likewise, 'this june' in June, is itself. 'this june' in any other month, is the nearest June in the future.

Future versions of this library could look at sentence-tense to help disambiguate these dates - 'i paid on monday' vs 'i will pay on monday'.

Last monday

If it's Tuesday, 'last monday' will not mean yesterday.

Saying 'last monday' on a tuesday will be -1 week.
Saying 'a week ago monday' will also work.
Saying 'this past monday' will return yesterday.

For reference, Wit.ai & chronic libraries both return yesterday. Natty and SugarJs returns -1 week, like we do.

'last X' can be less than 7 days backward, if it crosses a week starting-point:

Saying 'last friday' on a monday will be only a few days back.

Next Friday

If it's Tuesday, 'next wednesday' will not be tomorrow. It will be a week after tomorrow.

Saying 'next wednesday' on a tuesday, will be +1 week.
Saying 'a week wednesday' will also be +1 week.
Saying 'this coming wednesday' will be tomorrow.

For reference, Wit.ai, chronic, and Natty libraries all return tomorrow. SugarJs returns +1 week, like we do.

Nth Week:

The first week of a month, or a year is the first week with a thursday in it. This is a weird, but widely-held standard. I believe it's a military formalism. It cannot be (easily) configued. This means that the start-date for first week of January may be a Monday in December, etc.

As expected, first monday of January will always be in January.

British/American ambiguity:

by default, we use the same interpretation of dates as javascript does - we assume 01/02/2020 is Jan 2nd, (US-version) but allow 13/01/2020 to be Jan 13th (UK-version).

if you want to co-erce an interpretation of 02/03/1999, you can set it with the dmy:true option:

nlp('02/03/1999').dates().get() //February 3
nlp('02/03/1999').dates({dmy:true}).get() // March 2

ISO dates, (like 1999-03-02) are unaffected by the change.

Seasons:

By default, 'this summer' will return June 1 - Sept 1, which is northern hemisphere ISO. Configuring the default hemisphere should be possible in the future.

Day times:

There are some hardcoded times for 'lunch time' and others, but mainly, a day begins at 12:00am and ends at 11:59pm - the last millisecond of the day.

Invalid dates:

compromise will tag anything that looks like a date, but not validate the dates until they are parsed.

'january 34th 2020' will return Jan 31 2020.
'tomorrow at 2:62pm' will return just return 'tomorrow'.
'6th week of february will return the 2nd week of march.
Setting an hour that's skipped, or repeated by a DST change will return the closest valid time to the DST change.

Inclusive/exclusive ranges:

'between january and march' will include all of march. This is usually pretty-ambiguous normally.

Date greediness:

This library makes no assumptions about the input text, and is careful to avoid false-positive dates. If you know your text is a date, you can crank-up the date-tagger with a compromise-plugin, like so:

nlp.extend(function (Doc, world) {
  // ambiguous words
  world.addWords({
    weds: 'WeekDay',
    wed: 'WeekDay',
    sat: 'WeekDay',
    sun: 'WeekDay',
  })
  world.postProcess(doc => {
    // tag '2nd quarter' as a date
    doc.match('#Ordinal quarter').tag('#Date')
    // tag '2/2' as a date (not a fraction)
    doc.match('/[0-9]{1,2}/[0-9]{1,2}/').tag('#Date')
  })
})

Misc:

'thursday the 16th' - will set to the 16th, even if it's not thursday
'in a few hours/years' - in 2 hours/years
'jan 5th 2008 to Jan 6th the following year' - date-range explicit references
assume 'half past 5' is 5pm

About:

Parsing dates, times, durations, and intervals from natural language can be a solved-problem.

A rule-based, community open-source library - one based on simple NLP - is the best way to build a natural language date parser - commercial, or otherwise - for the frontend, or the backend.

The match-syntax is effective and easy, javascript is prevailing, and the more people who contribute, the better.