# text-to-time > Text To Time evaluates free-form, unstructured text to a timestamp. Latest version **1.2.0** (published 2019-01-12) · MIT license · 0 weekly downloads ## Install ```sh npm install text-to-time pnpm add text-to-time yarn add text-to-time bun add text-to-time ``` ## Health **Score 15/100 (F)** — status: abandoned. Positive: no vulnerabilities. Warnings: low downloads; no types; no esm support. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 1.2.0 | | Published | 2019-01-12 | | First published | 2018-08-04 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | CommonJS | | Dependencies | 3 | | Unpacked size | 38.7 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 1 | | Author | Velizar Kacharov | | Maintainers | vkacharov | | Keywords | text to time, text, time, evaluate, parse, date, before, after | ## Links - npm: https://www.npmjs.com/package/text-to-time - Repository: https://github.com/vkacharov/text-to-time - Homepage: https://github.com/vkacharov/text-to-time#readme - Issues: https://github.com/vkacharov/text-to-time/issues - npm.io page: https://npm.io/package/text-to-time ## Dependencies (3) - [moment](https://npm.io/package/moment.md) ^2.22.2 - [moment-timezone](https://npm.io/package/moment-timezone.md) ^0.5.21 - [words-to-numbers](https://npm.io/package/words-to-numbers.md) ^1.5.1 ## Alternatives - [@js-joda/timezone](https://npm.io/package/@js-joda/timezone.md) — 383.4K weekly downloads - [chartjs-adapter-moment](https://npm.io/package/chartjs-adapter-moment.md) — 210.8K weekly downloads - [strftime](https://npm.io/package/strftime.md) — 171.2K weekly downloads - [vue-flatpickr-component](https://npm.io/package/vue-flatpickr-component.md) — 115.8K weekly downloads - [timepicker](https://npm.io/package/timepicker.md) — 51.0K weekly downloads ## Recent versions - 1.2.0 (latest) — 2019-01-12 - 1.1.0 — 2018-09-01 - 1.0.1 — 2018-08-15 - 1.0.0 — 2018-08-14 - 0.0.3 — 2018-08-12 - 0.0.2 — 2018-08-05 - 0.0.1 — 2018-08-04 ## README # 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 ```javascript const t3 = require('text-to-time'); let callback = (err, evaluated) => { if (err) { console.error(err); } else { console.log(evaluated); } }; t3().evaluate('now', callback); ``` `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`. ```javascript t3().evaluate('now', callback); // { timestamp: 1533335400000, now: 1533420000000, timeZone: 'UTC' } t3().evaluate('yesterday', callback); // { timestamp: 1533333600000, now: 1533420000000, timeZone: 'UTC' } t3().evaluate('tomorrow', callback); // { timestamp: 1533506400000, now: 1533420000000, timeZone: 'UTC' } ``` ### .now() Use `now()` to change the current time related to which the expression is evaluated. ```javascript t3().evaluate('yesterday', callback); // { timestamp: 1533333600000, now: 1533420000000, timeZone: 'UTC' } let someDifferentNow = 1533335400000; // 2017-08-09 12:15:00 UTC t3().now(someDifferentNow).evaluate('yesterday', callback); // { timestamp: 1502194500000, now: 1502280900000, timeZone: 'UTC' } ``` ## Absolute time Text to Time evaluates expressions describing precise point in time. It supports all kinds of expressions. ```javascript t3().evaluate('2018-08-01 at 13:22:10', callback); // { timestamp: 1533043330000, now: 1533420000000, timeZone: 'UTC' } t3().evaluate('3:25:00 AM on 08/22/2018', callback); // { timestamp: 1534821900000, now: 1533420000000, timeZone: 'UTC' } t3().evaluate('3:25:00 AM on 17 June 2018', callback); // { 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. ```javascript t3().evaluate('today at 4', callback); // { timestamp: 1533355200000, now: 1533420000000, timeZone: 'UTC' } t3().timeZone('America/New_York').evaluate('today at 4', callback); // { timestamp: 1533369600000, now: 1533420000000, timeZone: 'America/New_York' } ``` ## Time operations Text to Time calculates time operations like *ago*, *before*, *after*, *at*, *on*, *past*. ```javascript t3().evaluate('3 days ago', callback); // { timestamp: 1533160800000, now: 1533420000000, timeZone: 'UTC' } t3().evaluate('15 minutes before tomorrow at 1 PM', callback); // { timestamp: 1533473100000, now: 1533420000000, timeZone: 'UTC' } t3().evaluate('quarter to 11 PM on 04.08.2018', callback); // { timestamp: 1533336300000, now: 1533420000000, timeZone: 'UTC' } t3().evaluate('3 hours after now', callback); // { timestamp: 1533430800000, now: 1533420000000, timeZone: 'UTC' } t3().evaluate('half past 3 AM on 22.08.2018', callback); // { timestamp: 1534822200000, now: 1533420000000, timeZone: 'UTC' } t3().evaluate('5 days and 5 hours from yesterday', callback); // { timestamp: 1533783600000, now: 1533420000000, timeZone: 'UTC' } t3().evaluate('3 hours before 01 August 2018 at 13:00', callback); // { 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 ```javascript t3().dateFormat('DD/MM/YYYY').evaluate('01/08/2018 at 16:00:00', callback); // { timestamp: 1533139200000, now: 1533420000000, timeZone: 'UTC' } t3().dateFormat('D MMM YYYY').evaluate('1 August 2018 at 16:00:00', callback); // { timestamp: 1533139200000, now: 1533420000000, timeZone: 'UTC' } t3().dateFormat('the day of DD and the month of MMM in the year YYYY') .evaluate('the day of 01 and the month of August in the year 2018 at 16:00:00', callback); // { 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 --- _Source: https://npm.io/package/text-to-time · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._