npm package: @mgwalker/relative-date
Description: Define strings representing relative dates that are then serialized into ISO8601 strings on-demand
Author: Greg Walker
Latest version: 1.0.0

# 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?

```js
"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.

```js
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](https://weather.gov).

## 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](./LICENSE.md).