derhuerst/parse-human-relative-time

Parse human relative time strings like "next Tuesday 3pm".

parse-human-relative-time

Yet another package to parse human relative time strings like "next Tuesday 3pm" and apply them to a date+time.

Installation

npm install parse-human-relative-time

Usage

When using luxon, note that it currently always follows ISO weekdays (0 = Monday) instead of the locale.

Luxon integration

const {DateTime} = require('luxon')
const parseHumanRelativeTime = require('parse-human-relative-time')(DateTime)

// Europe/Berlin switched to DST at 31st of March at 2am.
const tz = 'Europe/Berlin'
const dt = DateTime.fromISO('2019-03-31T01:59+01:00').setZone(tz)

parseHumanRelativeTime('in 2 minutes', dt)
.toISO({suppressSeconds: true, suppressMilliseconds: true})
// 2019-03-31T03:01+02:00

date-fns integration

const dateFns = require('date-fns')
const parseHumanRelative = require('parse-human-relative-time/date-fns')(dateFns)
const {format} = require('date-fns-tz')

// Europe/Berlin switched to DST at 31st of March at 2am.
const withoutDST = new Date('2019-03-31T01:59+01:00')
const timeZone = 'Europe/Berlin'

const withDST = parseHumanRelative('in 2 minutes', withoutDST)
format(withDST, 'HH:mm zz', {timeZone})
// 03:01 GMT+2

Lexing into instructions

const lexHumanRelativeTime = require('parse-human-relative-time/lex')

lexHumanRelativeTime('next tuesday 5pm')

[
	// next tuesday
	['startOfWeek'],
	['addWeeks', 1],
	['setDay', 2],

	// 12:01 am
	['setHours', 17],
	['setMinutes', 0],
	['setSeconds', 0],
	['setMilliseconds', 0]
]

Why yet another package?

Other packages don't handle time zones correctly, because they

• mess up timezones (e.g. parse-messy-time),
• parse to relative milliseconds, in some DST cases (e.g. parse-relative-time & timestring),
• require or even monkey-patch a specific date/time library (e.g. relative-time-parser).

Some actually do it right, but don't support a lot of expressions, e.g. relative-time-expression.

This package parses a human relative time string (e.g. next Tuesday 2pm) into a set of manipulation instructions and applies them to a Date using Luxon or date-fns. It therefore separates parsing and manipulation, letting the date/time lib handle the complex topic of time zones.

Contributing

If you have a question or need support using parse-human-relative-time, please double-check your code and setup first. If you think you have found a bug or want to propose a feature, refer to the issues page.

parse-human-relative-time's Issues

write a Luxon integration

Luxon is a well-known date/time lin with good time zome & i18n support.

To integrate it as parse-human-relative-time/luxon, we'd have translate all date-fns-based instructions of used to Luxon method calls.

Also, it would be good to change the tests to cover the integration as well, e.g. with a list of input -> expected output.

Unable to define weekStartsOn parameter

Some countries might start the week on another day, which can be configured in date-fns weekStartsOn parameter.

Unfortunately, this cannot be passed over here due to fixed lexing:

parse-human-relative-time/date-fns.js

Line 18 in 1fd2193

res = dateFns[cmd](res, ...args)

Can we figure a way, a solution, how to support such a parameter?

parse "last week"

How can we parse "last week" with this library best?

I mean, point to beginning of last week best. Pick "last Monday" instead?

No default export found in imported module "date-fns".

Nice library, thanks!

Unfortunately cannot do your date-fns example in ES6

import dateFns from "date-fns";

Because it has no default export. Any workarounds?

parse "last month"

Similar to "last week" (the other ticket), how can we parse "last month" best?

To point at the beginning and end of last month somehow.