work-in-progress

rule-based interpreter for natural-language date-forms.

an opinionated-but-configurable mash-up of spacetime and compromise

you've been warned!

IF YOU DARE:

npm install half-past

Usage:

var nlp = require('compromise')
var halfPast = require('half-past')
//apply plugin
nlp.plugin(halfPast)

let context = {
  // what 'today', or 'now' is
  now: '2018-09-10T17:28:32.140Z', // defaults to Date.now()
  // our assumed timezone, unless given
  timezone: 'Canada/Eastern',
  // set our calendar assumptions
  days: {
    start: '8:00am', // colloquial start/end of a day
    end: '6:00pm',
  },
  weeks: {
    start: 'monday', // some disagree.
    end: 'friday'
  },
  casual:{ // amount of time returned in 'after June 5th', etc.
    weeks:2
  },
  holidays: {
    'may day': '2018-06-01', // throws-away year info
  },
  // seasons: [ // defaults to northern-hemisphere (sorry!)
  //   '2018-03-01', //spring
  //   '2019-01-01', //summer
  //   '2019-04-01', //winter
  //   '2019-07-01', //fall
  // ],
  // quarters: [
  //   '2018-01-01', //q1
  //   '2019-04-01', //q2
  //   '2019-07-01', //q3
  //   '2019-09-01', //q4
  // ],
  // semesters: [ // https://en.wikipedia.org/wiki/Academic_term
  //   '2018-09-01',
  //   '2019-01-01',
  //   '2019-04-01',
  // ],
}

let result=halfPast(nlp('june 1st'), context)
/*
[{
  start:SpacetimeObject, //you can call .format('iso') or anything you want
  end:SpacetimeObject,
  precision:'day',
  interval:{
    unit:'month',
    amount:3
  },
}]
*/
console.log(result[0].start.format('iso'))
// 2018-06-01T11:18:58.040-04:00

How it works

half-past understands natural language date-forms using the following classification:

Single dates:

[two days after]  [the end of]    [next]    [thursday]  [at 2pm]   [EST]
   'shift'          'section'    'relative'    'unit'    'time'   'timezone'

[6 hours before]  [the start of]  [this]  [quarter]

Combined dates

these single-dates can be interpreted as two dates, that share information

between [date] and [date]
[date] to [date]
before [date]
after [date]
in [date]

See also

• Sugarjs - by Andrew Plummer
• Chrono - by Wanasit Tanakitrungruang
• Datejs - by Geoffrey McGill

Other languages

• Clojure - Duckling - by Facebook
• Java - Natty - by Joe Stelmach
• Go - When - by Oleg Lebedev
• Python - dateparser - by ScrapingHub

There are also some excellent commercial services for date-parsing, which we've omitted here.

MIT