range-builder

A typescript library for resolving Relative Date Format (RDF) strings into UNIX values

What is Relative Date Format?

Relative date format is a string based format that encodes a variety of range based time concepts. It provides a structured language to represent as a single string ideas such as;

• "the last 3 weeks from today"
• "this quarter"
• "from Jan 2 until now"

RDF was created to fill the need for a universal expression of relative date range concepts in a succinct manner. Every valid RDF string resolves to a pair of UNIX timestamps which indicate the start and end of the encoded range, relative to the current time.

How does it work?

An RDF string always consists of 3 or more fields, each seperated by a $ symbol. The first field indicates the handler, while the second and third field provide arguments which the handler will use to create the start and end timestamps which together represent a range.

The handler determines how the argument fields will be interpreted, while the argument fields provide either relative or absolute times that are used to resolve the final range.

RDF also provides a number of tokens that represent familiar time related concepts such as intervals of time (days, weeks, months, etc...) and now.

Handlers

Range ( $range$[start]$[end]$ )

The range handler calculates a start and end time in unix given a start and end time in unix. This handler is the most direct representation of a date range.

Examples:

• "Jan 1, 1970 00:00 until July 7 2019, 12:57:41" -> "$range$0$1562355886$"
• "July 7 2019, 12:57:41 until now" -> "$range$1562355886$now$"
• "Two weeks ago until one week ago" -> $range$now-2w$now-1w$"

Trail ( $trail$[end]$[period]$ )

The trail handler calculates a start and end time in unix given a end time and a time period. The start time is calculated as [end] - [period].

Examples:

• "The last 3 weeks" -> "$trail$now$3w$"
• "2 days before July 7 2019, 12:57:41" -> $trail$1562355886$2d$"
• "The last 5 seconds" -> "$trail$now$5$

Period ( $period$[start]$[period]$[ref (optional; defaults to 'now')]$ )

The period handler calculates a start and end date that starts at the beginning of the period occupied by ref and ends at the end of said period.

This is useful for cases such as when you want a range to reset to never represent more than a single (day/month/quarter/year).

Rollover will always occur according to the interval provided:

• x days - Period will rollover after x days, at the same time of day as the start time provided
• x weeks - Period will rollover after x weeks, on the same day of the week at the same time of day as the start time provided
• x months - Period will rollover after x months, on the same date of the month at the same time of day as the start time provided. If the date of the month is not valid (rollover is on the 30th of every 2nd month, but February only has 28 days, rollover will occur on the latest valid day of that month)
• x quarters - Period will rollover after x quarters , on the same date of the month at the same time of day as the start time provided. If the date of the month is not valid (rollover is on the 30th of every 2nd month, but February only has 28 days, rollover will occur on the latest valid day of that month). A quarter is defined to last 3 months and always start on the same date of the month, following the same rules for invalid rollover dates such as February 30th.

The period will be calculated both backwards and forwards from the provided start date, so start times in the future remain valid

Examples:

• "From the first of the month at 5:00am until now" -> "$period$1562000400$1M$"
• "From Jan 3 of the last even number year at 7:31pm until now" -> "$period$1515007860$2Y$"
• "This quarter (quarter starts Jan 1 and on the first of every 3 months at 00:00am)" -> "$period$1514764800000$1Q$"
• "Last quarter (quarter starts Jan 1 and on the first of every 3 months at 00:00am)" -> "$period$1514764800000$1Q$now-1Q$"
• "The year that a reference exactly one month ago was in" -> "$period$1514764800000$1Y$now-1m$"

Tokens

RDF exposes a set of tokens to represent common time centred concepts such as seconds, months, quarters, etc... These tokens do not directly represent a specific duration of time, but rather fluxuates based on the length of the last valid interval.

Addition is indicated with the + symbol, while subtraction is indicated with the - symbol.

Supported Tokens;

• now - The current UNIX timestamp at time of resolution
• s - Seconds
• m - Minutes
• h - Hours
• d - Days
• M - The period between the current date of this month and the month before (~30 days)
• Y - The period between the current date of this year and the year before (~365 days)
• Q - The period between the current date of this quarter and the quarter before (~91 days)

Operators

Using operators, it is possible to add or subract both absolute and token based times.

Capitalized tokens are relative to the current time and as such can not be compared using operators.

Examples:

• "2 hours before July 7 2019, 12:57:41" -> 1562355886-2h
• "2 hours after July 7 2019, 12:57:41" -> 1562355886+2h
• "Two hours longer than a quarter" -> 1Q+2h (note that the duration of a quarter depends on the given start date and current time)
• "Two hours and 15 minutes" -> 2h+15m