3.0.2 • Public • Published


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

npm version ISC-licensed minimum Node.js version support me via GitHub Sponsors chat with me on Twitter


npm install parse-human-relative-time


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
	['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

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.


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.

Package Sidebar


npm i parse-human-relative-time

Weekly Downloads






Unpacked Size

33.8 kB

Total Files


Last publish


  • derhuerst