@vizia/date-ranges

Date Ranges

Computes an exact ISO startDate and endDate from the dates set by a UI date-picker. These values should be used as request parameters for any source API. When data is received, formatting will still need to be handled according to the context's timezone (see @vizia/transform-dates for more info).

Philosophy

• The input startDate and endDate values must be ISO date-times in UTC. The input endDate must be exclusive (i.e. query up until that point in time).
• This always outputs a fixed date-range with UTC offset, even if a timezone has been provided (the UTC output is still equivalent to the local time of the given timezone). There is the option to remove the time information (i.e. time and offset) with includeTime=false, but this should only be used with APIs that do not accept a date-time. In this case, it is recommended that you set timezone='Etc/UTC' to avoid any skewed time calculations based on hour offsets.
• By default, the output end-date is exclusive. This means data will be requested up until that point, but does not include anything equal to, or afterwards. When concerned with date-times, this is the most intuitive approach. However, some APIs that do not accept times/timezones treat the end-date as inclusive (i.e. up until the end of that day). This can be set by providing inclusiveEndDate=true (NB: This will implicity set includeTime=false).
• Rolling date durations include the partial time-unit that has been specified. The end-date is always set to now, while, by default (see snapDates), the start-date will be treated as follows:
  • dateDuration='P1D' → start of the day.
  • dateDuration='P2D' → start of yesterday.
  • dateDuration='P1M' → start of the month.
  • dateDuration='P2M' → start of last month.

Date UI input

Currently, date-ranges are set by a UI date picker, providing either:

• A fixed start-date (startDate) and a fixed end-date (endDate).
• A fixed start-date (startDate) and no end-date (it is expected to be rolling).
• A rolling date duration (dateDuration, or the deprecated rollingDateRangeValue).

Fixed dates

A start-date and end-date are selected using a date-picker. These should be ISO date-time strings in UTC (e.g. 2018-01-01T00:00:00). This module shifts the intended time to the provided timezone.

From date

A start-date is selected using a date-picker, as above. The absent end-date should be treated like a rolling end-date up to now.

Date duration

A 'rolling' time period has been selected. This is a moving duration window with which the component requests data (relative to the execution time).

NB: Providing a rollingDateRangeValue has been deprecated in favour of an ISO duration string (dateDuration), so that more granular time-ranges can be set (e.g. 3 hours).

Usage

const getDateRange = require('@vizia/date-ranges');

It requires either:

• Fixed mode – An ISO startDate and endDate.
• From mode – An ISO startDate.
• Rolling mode – An ISO duration string, dateDuration. Backwards compatibility exists for a rollingDateRangeValue (deprecated in favour of dateDuration).

See Options for more info.

Examples

Using fixed dates for a time-series graph with day breakdown

const dateRange = getDateRange({
    startDate: '2018-01-01T00:00:00.000+00:00',
    endDate: '2018-01-08T00:00:00.000+00:00',
    timezone: 'Europe/London'
});
// {startDate: '2018-01-01T00:00:00.000+00:00', endDate: '2018-01-08T00:00:00.000+00:00'}

Transposes output dates to the UTC equivalent of the folder timezone (London is in UTC+0 within this date-range).

const dateRange = getDateRange({
    startDate: '2018-06-01T00:00:00.000+00:00',
    endDate: '2018-06-08T00:00:00.000+00:00',
    timezone: 'Europe/London'
});
// { startDate: '2018-05-31T23:00:00.000+00:00', endDate: '2018-06-07T23:00:00.000+00:00' }

Transposes output dates to the UTC equivalent of the folder timezone (London is in UTC+1 within this date-range).

const dateRange = getDateRange({
    startDate: '2018-01-01T00:00:00.000+00:00',
    endDate: '2018-01-08T00:00:00.000+00:00',
    timezone: 'America/New_York'
});
// { startDate: '2018-01-01T05:00:00.000+00:00', endDate: '2018-01-08T05:00:00.000+00:00' }

Transposes output dates to the UTC equivalent of the folder timezone.

Using fixed dates for a time-series graph with hour breakdown

const dateRange = getDateRange({
    startDate: '2018-01-01T09:30:00.000+00:00',
    endDate: '2018-01-02T09:00:00.000+00:00',
    snapDates: 'hour',
    timezone: 'Europe/London'
});
// { startDate: '2018-01-01T09:00:00.000+00:00', endDate: '2018-01-02T09:00:00.000+00:00' }

Transposes output dates to the UTC equivalent of the folder timezone (London is incidentally in UTC at this point) and snaps to the start of the hour.

const dateRange = getDateRange({
    startDate: '2018-01-01T09:30:00.000+00:00',
    endDate: '2018-01-02T09:00:00.000+00:00',
    snapDates: 'hour',
    timezone: 'America/New_York'
});
// { startDate: '2018-01-01T14:00:00.000+00:00', endDate: '2018-01-02T14:00:00.000+00:00' }

Transposes output dates to the UTC equivalent of the folder timezone and snaps to the start of the hour.

Using date duration for a time-series graph with day breakdown

// Now: '2018-01-08T09:00:00.000+00:00'
const dateRange = getDateRange({
    dateDuration: 'P7D',
    timezone: 'Europe/London'
});
// { startDate: '2018-01-02T00:00:00.000+00:00', endDate: '2018-01-08T09:00:00.000+00:00' }

Outputs up to 7 days worth of data (with the current day being partial up until now).

Using date duration for a time-series graph with hour breakdown

// Now: '2018-01-08T09:30:00.000+00:00'
const dateRange = getDateRange({
    dateDuration: 'PT24H',
    timezone: 'Europe/London'
});
// { startDate: '2018-01-07T10:00:00.000+00:00', endDate: '2018-01-08T09:30:00.000+00:00' }

Outputs up to 24 hours worth of data (with the current hour being partial up until now).

Getting comparison dates for any date range options

// Now: '2018-01-28T09:00:00.000+00:00'
const dateRange = getDateRange({
    dateDuration: 'P7D',
    timezone: 'Europe/London'
});
// { startDate: '2018-01-22T00:00:00.000+00:00', endDate: '2018-01-28T09:00:00.000+00:00' }
const comparisonDateRange = getDateRange({
    dateDuration: 'P7D',
    timezone: 'Europe/London',
    comparisonRange: 'previous'
});
// { startDate: '2018-01-15T00:00:00.000+00:00', endDate: '2018-01-21T09:00:00.000+00:00' }

NB: When setting comparisonRange, the output comparison date-range may not be the same duration as the original date-range, because days/months/quarters/years all vary in length. Be careful when a breakdown is being used to bucket the dates; for example, when viewing a day breakdown for an entire month, the previous month may have a different number of days. See Luxon's math for more info.

Options

Key	Value	Default	Description
startDate	String	–	ISO date.
endDate	String	–	ISO date (requires startDate).
dateDuration	String	–	ISO duration.
rollingDateRangeValue	Number	–	Shorthand that applies {dateDuration: 'P<value>D'}. This has been deprecated in favour of dateDuration, so opt for that instead.
snapDates	String	–	Snaps output startDate and endDate to beginning of time-unit ('year', 'month', 'week', 'day', 'hour', 'minute', 'second', or 'millisecond'; also accepts pluralised equivalent). When using a dateDuration, it will default this value to be the smallest specified time-unit, e.g. with dateDuration='P1Y3M', this value will be 'month'.
offsetDates	Boolean	true	Assumes the folder timezone for the input dates. If an absolute time is required (e.g. for a specific event like the Super Bowl), set to false. This only comes into effect when not a rolling duration.
comparisonRange	String	–	Comparison range. Possible values are 'previous' (the preceding date-range, based on the difference between the computed startDate and endDate), 'previousDay', 'previousWeek', 'previousMonth', 'previousQuarter' or 'previousYear'.
timezone	String	'Etc/UTC'	Folder time-zone.
inclusiveEndDate	Boolean	false	This is to signal that the targeted API treats the end-date as inclusive. E.g. an API queried with 2018-01-01 to 2018-01-08, may yield data that includes the 8th. NB: The Brandwatch API is exclusive and this option should be left as the default.
includeTime	Boolean	true	By default, output will be format as an ISO date-time with UTC offset, which is desirable in most cases. Setting this to false should only be used if an API only accepts an ISO date, without the time information (e.g. '2018-01-01'). When inclusiveEndDate=true, this value will be overridden to false.
debug	Boolean	false	Enables logging the output of the date-processors.
dateRangesReferenceDate	String	–	Allows overriding the relative time that a dateDuration or rolling end-date is computed from. The default is now, but ATs may want deterministic results by providing a fixed date.