3.0.0 • 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

    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


    npm install parse-human-relative-time


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

    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.


    npm i parse-human-relative-time

    DownloadsWeekly Downloads






    Unpacked Size

    33.7 kB

    Total Files


    Last publish


    • derhuerst