Text to Time
Evaluates free-form, unstructured text to a timestamp. Capable of calculating time expressions like 'before', 'after', 'ago', and so on. Returns an object containing the timestamp calcuated from the text.
Possible use cases:
- Regular date and time parsing
- Extracting and calculating dates from unstructured text
- Skills for speech-enable asistents like Alexa or Google Home
To install, use
npm install text-to-time
Usage
Let's start with the basics
const t3 = ;let { if err console; else console; };;
evaluate()
is the main function of Text to Time. It takes in the text and a callback function. The callback argument evaluated
is the result of the evaluation in the following format:
{
timestamp: the timestamp evaluated from the expression,
now: the current timestamp, for relative expressions,
timeZone: the time zone used to evaluate the expression
}
Relative expressions
Text to Time evaluates expressions relative to the current time. Let's assume the current moment is 2018-08-04 22:00:00 UTC
.
;// { timestamp: 1533335400000, now: 1533420000000, timeZone: 'UTC' } ;// { timestamp: 1533333600000, now: 1533420000000, timeZone: 'UTC' } ;// { timestamp: 1533506400000, now: 1533420000000, timeZone: 'UTC' }
.now()
Use now()
to change the current time related to which the expression is evaluated.
;// { timestamp: 1533333600000, now: 1533420000000, timeZone: 'UTC' } let someDifferentNow = 1533335400000; // 2017-08-09 12:15:00 UTC ; // { timestamp: 1502194500000, now: 1502280900000, timeZone: 'UTC' }
Absolute time
Text to Time evaluates expressions describing precise point in time. It supports all kinds of expressions.
;// { timestamp: 1533043330000, now: 1533420000000, timeZone: 'UTC' } ;// { timestamp: 1534821900000, now: 1533420000000, timeZone: 'UTC' } ;// { timestamp: 1529119500000, now: 1533420000000, timeZone: 'UTC' }
Because they define absolute point in time now()
is not used in these expressions.
.timeZone()
Use .timeZone()
to set the time zone of the expression.
;// { timestamp: 1533355200000, now: 1533420000000, timeZone: 'UTC' } ;// { timestamp: 1533369600000, now: 1533420000000, timeZone: 'America/New_York' }
Time operations
Text to Time calculates time operations like ago, before, after, at, on, past.
;// { timestamp: 1533160800000, now: 1533420000000, timeZone: 'UTC' } ;// { timestamp: 1533473100000, now: 1533420000000, timeZone: 'UTC' } ;// { timestamp: 1533336300000, now: 1533420000000, timeZone: 'UTC' } ;// { timestamp: 1533430800000, now: 1533420000000, timeZone: 'UTC' } ;// { timestamp: 1534822200000, now: 1533420000000, timeZone: 'UTC' } ;// { timestamp: 1533783600000, now: 1533420000000, timeZone: 'UTC' } ;// { timestamp: 1533031200000, now: 1533420000000, timeZone: 'UTC' }
Date resolution
Text to Time is cabable of auto-resolving dates in different formats, if the date format is not explicitly set. The following dates will all be resolved to 22 August 2018
. If the year is omitted, Text to Time defaults to the current year.
- 2018-08-22
- 22 August 2018
- 22 August
- 22.08.2018
- 22.08
- 08.22.2018
- 08.22
- 08/22/2018
- 08/22
- 22/08/2018
- 22/08
Text to Time implies the date and the month depending on their value.
.dateFormat()
Use .dateFormat()
to explicitly set the date format. The date format can be any text containing the date format placeholders.
Placeholder | Meaning | Example |
---|---|---|
D | 1 or 2 digit day | 1, 3, 12, 23 |
DD | 2 digit day | 01, 03, 12, 23 |
M | 1 or 2 digit month | 1, 3, 10, 12 |
MM | 2 digit month | 01, 03, 10, 12 |
MMM | month name, case insensitive | January, march |
YYYY | 4 digit year | 1986, 2018 |
For example
;// { timestamp: 1533139200000, now: 1533420000000, timeZone: 'UTC' } ;// { timestamp: 1533139200000, now: 1533420000000, timeZone: 'UTC' } ;// { timestamp: 1533139200000, now: 1533420000000, timeZone: 'UTC' }
Fuzzy matching
Text to Time is capable of evaluating incomplete words and mixed text-and-numbers expressions. For example, the all of the following are equivalent to 1 day and 2 hours before 19 February 2018 at 10:30 AM
- one day and two hours before nineteen February two thousand eighteen at ten thirty AM
- 1 day and 2 hours before 19 Feb 2018 at 10 30 AM
- 1 d and 2 h before nineteenth February 2018 at 10 thirty AM