parse-human-relative-time

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

!ISC-licensed
!minimum Node.js version

Installation

``shell
npm install parse-human-relative-time
`

Usage

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

$3

`js
import {createParseHumanRelativeTime} from 'parse-human-relative-time/luxon.js'
import {DateTime} from 'luxon'
const parseHumanRelativeTime = createParseHumanRelativeTime(DateTime)

// Europe/Berlin switched to DST on the 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
`

$3

`js
import {TZDate} from 'date-fns-tz'
import {createParseHumanRelativeTime} from 'parse-human-relative-time/date-fns.js'
import * as dateFns from 'date-fns'
const parseHumanRelativeTime = createParseHumanRelativeTime(dateFns)

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

const withDST = parseHumanRelativeTime('in 2 minutes', withoutDST)
dateFns.format(withDST, 'HH:mm zz')
// 03:01 GMT+2
``

$3

`js
import {parseHumanRelativeTime} from 'parse-human-relative-time'

parseHumanRelativeTime('next tuesday 5pm')
`

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

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

Why yet another package?

Most 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.