A natural language parser for dates, times, and durations

A tiny utility library with no dependencies that parses natural language dates, times, and intervals to either a Date instance or a numerical value in milliseconds. Here are some examples of possible inputs:

• two weeks ago
• 1 day ago
• in 2 hours and 5 minutes
• in a month
• 2018-01-01T00:00:00.000Z

Installation

npm i --save time-speak
Copy

Usage

Import the parse function call it with a string containing a natural language representation of either a time in the future, past, or a duration. The return value is a timestamp in milliseconds if the input is a duration, otherwise it is a Date instance.

import { parse } from 'time-speak'

const pastDate = parse('2 days and 4 hours ago')
const pastDateWithNumberWords = parse('two days and four hours ago')
const futureDate = parse('in 4 hours')
const durationMS = parse('6 months')

console.log({
  pastDateWithNumberWords,    // 2023-12-19T13:02:39.768Z
  pastDate,                   // 2023-12-19T13:02:39.768Z
  futureDate,                 // 2023-12-21T21:02:39.768Z
  durationMS                  // 15552000000
})
Copy

API Reference

The standalone JSDoc reference can be found in DOCUMENTATION.md

Classes

InvalidInputError

Error thrown when the input cannot be parsed to a date or duration. It optionally accepts a detail parameter that can be used to provide more information about why parsing failed.

Members

TimeUnit

A mapping of time units to their millisecond values.

TimeUnitPlural

A mapping of plural time units to their singular counterparts.

Functions

parse(input) ⇒

Parses a string into a Date or number of milliseconds. The string can describe the date in natural language (e.g. "tomorrow", "in 2 hours and 3 minutes", "a month ago", etc.) or be a valid date string (e.g. "2018-01-01").

InvalidInputError

Error thrown when the input cannot be parsed to a date or duration. It optionally accepts a detail parameter that can be used to provide more information about why parsing failed.

Kind: global class
Access: public

• InvalidInputError
  • new InvalidInputError(input, detail)
  • ._input
  • ._detail
  • .detail ⇒
  • .input ⇒

new InvalidInputError(input, detail)

Create a new InvalidInputError instance with the given input, optionally providing a detail parameter to describe why parsing failed. The detail parameter will be included in the error message if provided.

Param	Description
input	The input that could not be parsed
detail	A more detailed description of the error

invalidInputError._input

The input that could not be parsed.

Kind: instance property of InvalidInputError

invalidInputError._detail

An optional detailed description of the reason why parsing failed.

Kind: instance property of InvalidInputError

invalidInputError.detail ⇒

Get the detail explaining why parsing failed. If no detail was provided, it will return an empty string.

Kind: instance property of InvalidInputError
Returns: The detail string.

invalidInputError.input ⇒

Get the original input that could not be parsed.

Kind: instance property of InvalidInputError
Returns: The input string.

TimeUnit

A mapping of time units to their millisecond values.

Kind: global variable

TimeUnitPlural

A mapping of plural time units to their singular counterparts.

Kind: global variable

parse(input) ⇒

Parses a string into a Date or number of milliseconds. The string can describe the date in natural language (e.g. "tomorrow", "in 2 hours and 3 minutes", "a month ago", etc.) or be a valid date string (e.g. "2018-01-01").

Kind: global function
Returns: The parsed date or number of milliseconds.
Throws:

• InvalidInputError This exception is thrown if the input is invalid.

Access: public

Param	Description
input	The string to parse.

Example
Here are some example invocations:

const ... = parse('1 day ago')
const ... = parse('three days ago')
const ... = parse('in 2 hours and 3 minutes')
const ... = parse('a month')
const ... = parse('2018-01-01')
const ... = parse('2018-01-01T00:00:00.000Z')
Copy

Example
Here are some example invocations that throw an exception:

parse('in 2 hours and 3 minutes ago')
parse('a month in the past')
Copy

Release History

See CHANGELOG.md for more information.

License

Distributed under the MIT license. See LICENSE.md for more information.

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request