Relative dates

Have you ever needed a convenient way to specify a date relative to the current time, or a specific time of the current day? Like, for example, if you're working with data that is intrinsicly linked to data and you want to create fixtures? And it's kind of a hassle. Well, this library might be able to help.

What if instead of an date string, you could do something like this instead?

"date:now +3 hours";

Well, that's what this library lets you do. The RelativeDate class accepts these relative time strings and serializes to an ISO8601 date string, perfect for sending across the network in a standard way! The objects can be serialized manually using the .toString() or .toJSON() methods, or you can let it serialize implicitly when stringifying an object that contains this object.

const obj = {
  date: new RelativeDate("date:today 07:32:-0"),
};

console.log(JSON.stringify(obj));

// output:
//   {"date":"2026-03-07T07:32:00.000Z"}

[!NOTE]
The serialized string comes from the native Javascript Date type. Therefore, it is always in the UTC timezone and also includes milliseconds.

Time strings

Relative time strings must follow a particular format, and must always start with either:

1. date:now
2. date:today

Now-based strings

By default, a now string is relative to the moment it is serialized, down to the millisecond.

date:now

However, sometimes you might need the time to be the start of the current hour or minute. To do that, you add a little more to the time string:

date:now:hour
date:now:minute

Today-based strings

Sometimes you might need times that are at specific times of day. For example, data that is always updated at 6pm. In those cases, you're less interested in the current time and are more interested in the current date. To accomplish this, use this format:

date:today HH:mm:+h

Today-based strings MUST include a time of day in 24-hour format, where the hour and minute are two-digits with leading zeros if necessary. Furthermore, the time must include a UTC offset in the form of +h or -h. This describes the number of hours from UTC.

[!NOTE]
UTC offset is required. Use +0 or -0 for UTC.

[!NOTE]
In case you're used to working with ISO8601 date strings, be mindful that in proxy relative date strings, the UTC offset is separated from the time with a colon.

So for a day period starting at 6am today, you can represent that this way:

date:today 06:00:-0

Or, perhaps, 7:30pm in central daylight time (CDT; 5 hours behind UTC most of the year, or 6 hours behind during "standard time"):

date:today 19:30:-5

Time adjustments

Here's the relative part! All relative date strings can include adjustments. These are positive or negative integer amounts of time to adjust by. For example:

date:now +3 hours
date:now -4 minutes
date:today 06:00:-6 +3 days

The adjustments are a single value. If you need to adjust by multiple units, you'll need to convert to the smallest unit. For example, 1.5 hours becomes 90 minutes instead. Supported units are:

• d/day/days
• h/hour/hours
• m/minute/minutes
• s/second/seconds

Credit

I originally created this library for the National Weather Service.

Contributing

As an original work of the US Government, the initial code is not subject to copyright. In the spirit of public domain software, this repo also explicitly adopts the CC0 statement. Contributors agree that their contributions are committed to the public domain, and in jurisdictions that do not have public domain, are otherwise bound to the terms of the CC0 license.