Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »



    Something like TIMEX3 in JavaScript.


    This should be divided into 2 libraries:

    • a generic time manipulation library, no parsing, just javascript object manipulation
    • time parsing


    npm install epic

    TODO browser version.


    There are Time and Period objects. Periods can have start and/or end times, and/or durations. Time is fuzzy. There is also the Unit object.

    The api should look something like this:

    var epic = require('epic');
        epic.annotate('I went to school the day before yesterday...')
      , 'I went to school <time>the day before yesterday</time>...'
    epic.period({hours: 12}).toInt();

    Internals of the API

    var epic = require('epic')
      , Period = epic.Period
      , Interval = epic.Interval
      , Instant = epic.Instant;
    // If you add this period to the 1st February (ISO) then you will get the 1st March.
    // If you add the same period to the 1st March you will get the 1st April.
    // But the duration added (in milliseconds) in these two cases is very different.
    var period = new Period({months: 1});
    var instant = Instant.parse('Feb 1, 2012');
    instant.toString(); // "Mar 1, 2012"
    // more complicated
    // this says the winter solstice is on Dec 21, 2012,
    // sometime between 6:00pm and 11:59pm (just made those numbers up)
    var winterSolstice = new Interval(
      new Instant('Dec 21, 2012 at 6:00pm'), 
      new Period({hours: 6}) // better name is "Duration"
    // then you could go to next years winter solstice:
    // and it should be Dec 21, 2013 from 6pm - 11:59pm

    Then some BC calculations:

    var originOfAgriculture = epic.parse('10,000 BCE');
    // which you could manually set up like this (but would have to know the internals of how BCE is handled)
    var originOfAgriculture = new Time();
    originOfAgriculture.subtract(new Period({years: 2012})).subtract(new Period({years: 10000}));
    // there should be better ways to do this.


    // 1 million years ago
    var mya = new Time({years: -1000000});
    var mya = new Time(new Period({years: -1000000}));
    // periods can have start and end dates, or they don't have to.
    var triassicPeriod = new Period(new Time({years: -(250 * 1000000)}, new Time({years: -(200 * 1000000)});
    triassicPeriod.startTime.add(new Period({years: 10}));
    var triassicPeriod = new Period(new Time(-250), new Time(-200), new Unit('mya'));
    var triassicPeriod = new Period(new Time(-250, new Unit('ma')), new Time(200, new Unit('ma')));
    // maybe "unit" specifies the default operator or something
    var triassicPeriod = new Period(new Time(-250, 'mya'), new Time(-200, 'mya'));
    var extinction = new Time(65, 'mya');
    // how many years after the triassic period?
    var periodBetween = new Period(triassicPeriod.endTime, extinction);
    var millionYearsAfter = periodBetween.duration('ma'); // 200 - 65 = 135 ma
    var yearsAfter = periodBetween.duration('years'); // 200 - 65 = 135 ma

    This should print the date in a standard format that can be saved to a database. Some ideas are: (TODO)

    Ways of expressing time.

    John left by the time he left
    John left by the time he ate
    John ate by the time he left
    John left by the time he ate
    April is usually wet. generic
    I was born on a Tuesday. indefinite
    I had swimming classes on every Tuesday in 1999. gapped interval
    Winter 1999 was extremely severe. vague
    We got married about three years ago. approximate
    The first three days of every month are always the busiest. set of intervals
    The movie is two hours long. unanchored interval
    She left five days after he came back. event-dependant
    Category Examples
    Adverbs simultaneously, currently, lately, today, yesterday, tomorrow
    a lot, always, ever, frequently, hardly ever, never, normally, occasionally,
    often, frequently, rarely, sometimes, usually, hourly, daily, weekly or
    on Monday, at 5 o'clock, for one hour, in January, over many years,
    during the weekend, after the meeting, before 8pm, between 11am and
    1pm, by Monday morning, since 1978, until January 2006, from 1939 to
    1945, within one hour, following the meeting
    five months ago, five months hence, five months on, the whole night
    Other Adverbial Phrases: later than ever before, at least five years, all spring, on Tuesday at noon
    Adverbial Clause: when she saw the snake, as soon as I have any news
    Noun Phrase coming weeks, a beautiful morning, cold winters
    John visited his parents twice in two years.
    John learnt Japanese for half an hour every morning for a month.
    John washed cars from morning till night from June till August.
    John had arrived on Tuesday at noon.
    On Tuesday, John had arrived at noon.
    Last week, John had arrived 3 days ago.
    John had arrived at noon on Tuesday.
    John had arrived 3 days ago last week.
    Category Lexical Triggers Non-Triggers
    Noun minute, afternoon, midnight, day,
    night, weekend, month, summer,
    season, quarter, year, decade, cen-
    tury, millennium, era, semester, fu-
    ture, past, time, period, point
    instant, jiy, episode, occasion,
    tenure, timetable, reign, light year,
    megawatt hour, lifetime, history
    Adjective recent, former, current, future, past,
    daily, monthly, biannual, semian-
    nual, daytime, daylong, onetime,
    ago, preseason, short-term, long-
    early, ahead, next, subsequent, fre-
    quent, perpetual, later, contempo-
    rary, simultaneous, preceding, pre-
    vious, existing, modern
    Adverb currently, lately, hourly, daily,
    monthly, ago (+ adverbial forms of
    adjective triggers)
    earlier, immediately, instantly,
    forthwith, meanwhile, heretofore,
    previously, next, beforehand, fol-
    lowing, later, soon, sooner, shortly,
    eventually, occasionally, once, still,
    again, timely, whenever
    now, today, yesterday, tomorrow
    Number 3, three, third, sixties
    Proper name Monday, January, New Year's Eve,
    Washing's Birthday, Solstice
    Pronouns that, then, it (only pronouns that
    co-refer with a markable expression)
    Time patterns 8:00, 12/02/2000, 1994, 1960s
    that cold day the next day late last night
    earlier that year next summer recent decades
    numerous Saturdays more than a month no less than 60 days
    just a year ago only one hour long its own future
    the countrys future just a year ago only one hour long
    five years old a few weeks later hours earlier
    five days after he came back three decades ago the second-best quarter ever
    months of renewed hostility a historic day for the European enterprise
    nearly four decades of experience
    Perhaps in the next two weeks.
    How 'bout the afternoon of Monday the ninth?
    Okay, how 'bout Tuesday March the sixteenth sometime after twelve o'clock pm?
    9th Sep. 1987
    an hour and 30 minutes
    Tuesday and Thursday
    Wednesday or Friday
    4 o'clock
    next month
    exactly one minute ago
    the 2nd Sunday in May
    Wednesday from 3pm to 5pm
    in the past 3 years
    every 2 minutes and 30 seconds
    from 3pm to 5pm
    the rest of the year
    sometime between 3pm and 5pm
    other than Wednesday
    less than 1 hour and 30 minutes
    sometime before Sept. 9, 1987
    sometime in 1987
    January to March and May 2007
    8am, except Mondays 9 am
    the following month
    the second Tuesday after Easter
    two consecutive Sundays
    three Mondays
    all Mondays in every May
    all Mondays in any May
    any Monday in every May
    the courses when the student has free time
    We met in July last year
    On Monday and Tuesday
    three months earlier
    from 3pm to 6pm
    They are leaving on vacation two weeks from next Tuesday.
    A major earthquake struck Los Angeles three years ago today.
    This year’s summer was unusually hot.
    Bacon tutored an English student some Thursdays in 1998.
    She spent the following twelve years in various health care positions around Minnesota.
    Ash Wednesday
    Easter Sunday
    Christmas Day
    Adnan Pachachi, a onetime foreign minister who returned to Iraq on May 6 after 33 years in exile...
    Yeah. I'm leaving on Monday and coming back on the thirtieth, so um


    • Fully specified temporal expressions, which provide all the information necessary in order to identify the point or period of time they are referring to; e.g., June 11, 1989, or the Summer of 2002.
    • Underspecified temporal expressions, which require the use of some contextual infor- mation in order to interpret the point in time they are referring to; e.g., early in the morning, Monday, in recent days, few days ago, two weeks from next Tuesday, next September, the current month, last year, a decade ago.
    • Durations, such as: three months and two years.
    • DANTE is a rule-based system that consists of two main processing modules: a recognizer and an interpreter. The recognizer finds occurrences of temporal expressionsin documents, determines their full extents in text, and analyses their local meaning to generate their LTIMEX values. Then, for each recognized temporal expression the interpreter determines its global semantic value.
    • SUTIME is a rule-based temporal tagger built on regular expression patterns. Temporal expressions are bounded in their complexity, so many of them can be captured using finite automata. As shown by systems such as FASTUS (Hobbs et al., 1997), a cascade of finite automata can be very effective at extracting information from text. With SUTIME, we follow a similar staged strategy of (i) building up patterns over individual words to find numerical expressions; then (ii) using patterns over words and numerical expressions to find simple temporal expressions; and finally (iii) forming composite patterns over the discovered temporal expressions.




    • Currently, the standard temporal annotation scheme is TimeML which includes a specification of the TIMEX3 standard.
      • Explicit, absolute, or self-contained: These can be directly translated to a particular granularity date/time.
      • Implicit, relative, or context-dependent: These need the document creation time (deictic) or a previously mentioned temporal reference/anchoring (anaphoric) to obtain a explicit date/time.
      • Durative: Describing a bounded interval (or duration) that is not inherently anchored to a timeline.
      • Set or frequency: Regularly recurring times, such as “every Christmas” or “each Tuesday”.
      • Vague: generic mentions like “recently” or “today” in “today’s fashions”; see TIDES standard Section 4.6 (Ferro et al., 2005).



    • timex / timexes
    • temporal expressions
    • Timex Normalisation Taxonomy
    • "natural language" morphological corpus independent filetype:pdf
    • DANTE (Detection and Normalisation of Temporal Expressions)




    npm i epic

    Downloadsweekly downloads








    last publish


    • avatar