@shopify/dates
Lightweight date operations library.
Installation
$ yarn add @shopify/dates
Usage
This library exports helpers that allow apps to easily work with dates and timezones.
Optional time zone parameters that are omitted are inferred as local.
applyTimeZoneOffset
Takes in a date object and two optional time zone string parameters. Returns a new date object with the offset between the time zones added to it.
import {applyTimeZoneOffset} from '@shopify/dates';
const date = new Date('2018-06-01Z14:00');
const timeZone1 = 'Australia/Perth';
const timeZone2 = 'America/Toronto';
const newDate = applyTimeZoneOffset(date, timeZone1, timeZone2);
getDateTimeParts
Takes in a date object and an optional time zone string parameter. Returns an object with functions to get the year, month, day, weekday, hour, minute and second of the provided date.
import {getDateTimeParts} from '@shopify/dates';
const date = new Date('2018-06-01Z14:00');
const timeZone = 'Australia/Perth';
const dateTimeParts = getDateTimeParts(date, timeZone);
const year = dateTimeParts.year();
const month = dateTimeParts.month();
const day = dateTimeParts.day();
const weekday = dateTimeParts.weekday();
const hour = dateTimeParts.hour();
const minute = dateTimeParts.minute();
const second = dateTimeParts.second();
getTimeZoneOffset
Takes in a date object and two optional time zone string parameters. Returns a number representing the offset between the two provided time zones in minutes.
import {getTimeZoneOffset} from '@shopify/dates';
const date = new Date('2018-06-01Z14:00');
const timeZone1 = 'America/Toronto';
const timeZone2 = 'Australia/Perth';
const timeZoneOffset = getTimeZoneOffset(date, timeZone1, timeZone2);
isFutureDate
Takes in a date object and an optional now date object to compare against (defaulting to a new date object). Returns a boolean indicating whether or not the first date is in the future.
import {isFutureDate} from '@shopify/dates';
const now = new Date('2018-01-01Z00:00');
const date = new Date('2018-01-02Z23:59');
const futureDay = isFutureDate(date, now);
isLessThanOneDayAgo
Takes in a date object and an optional "now" date object (that defaults to new Date()
). Returns a boolean indicating whether or not the date is less than one day before the "now" date.
import {isLessThanOneDayAgo} from '@shopify/dates';
const moreThanOneDayAgo = new Date('2018-01-01Z00:00');
const lessThanOneDayAgo = new Date(Date.now() - 23 * TimeUnit.Hour);
isLessThanOneDayAgo(moreThanOneDayAgo);
isLessThanOneDayAgo(lessThanOneDayAgo);
isLessThanOneHourAgo
Takes in a date object and an optional "now" date object (that defaults to new Date()
). Returns a boolean indicating whether or not the date is less than one hour before the "now" date.
import {isLessThanOneHourAgo} from '@shopify/dates';
const moreThanOneHourAgo = new Date('2018-01-01Z00:00');
const lessThanOneHourAgo = new Date(Date.now() - 59 * TimeUnit.Minute);
isLessThanOneHourAgo(moreThanOneHourAgo);
isLessThanOneHourAgo(lessThanOneHourAgo);
isLessThanOneMinuteAgo
Takes in a date object and an optional "now" date object (that defaults to new Date()
). Returns a boolean indicating whether or not the date is less than one minute before the "now" date.
import {isLessThanOneMinuteAgo} from '@shopify/dates';
const moreThanOneMinuteAgo = new Date('2018-01-01Z00:00');
const lessThanOneMinuteAgo = new Date(Date.now() - 59 * TimeUnit.Second);
isLessThanOneMinuteAgo(moreThanOneMinuteAgo);
isLessThanOneMinuteAgo(lessThanOneMinuteAgo);
isLessThanOneWeekAgo
Takes in a date object and an optional "now" date object (that defaults to new Date()
). Returns a boolean indicating whether or not the date is less than one week before the "now" date.
import {isLessThanOneWeekAgo} from '@shopify/dates';
const moreThanOneWeekAgo = new Date('2018-01-01Z00:00');
const lessThanOneWeekAgo = new Date(Date.now() - 6 * TimeUnit.Day);
isLessThanOneWeekAgo(moreThanOneWeekAgo);
isLessThanOneWeekAgo(lessThanOneWeekAgo);
isLessThanOneYearAgo
Takes in a date object and an optional "now" date object (that defaults to new Date()
). Returns a boolean indicating whether or not the date is less than one year before the "now" date.
import {isLessThanOneYearAgo} from '@shopify/dates';
const moreThanOneYearAgo = new Date('2018-01-01Z00:00');
const lessThanOneYearAgo = new Date(Date.now() - 51 * TimeUnit.Week);
isLessThanOneYearAgo(moreThanOneYearAgo);
isLessThanOneYearAgo(lessThanOneYearAgo);
isSameDay
Takes in two date objects and an optional time zone string parameter. Returns a boolean indicating whether or not these two dates are in the same day.
import {isSameDay} from '@shopify/dates';
const date1 = '2018-01-01Z00:00';
const date2 = '2018-01-02Z23:59';
const timeZone = 'America/Toronto';
const sameDay = isSameDay(date1, date2, timeZone);
isSameMonth
Takes in two date objects and an optional time zone string parameter. Returns a boolean indicating whether or not these two dates are in the same month.
import {isSameMonth} from '@shopify/dates';
const date1 = '2018-01-01Z00:00';
const date2 = '2018-01-02Z23:59';
const timeZone = 'America/Toronto';
const sameMonth = isSameMonth(date1, date2, timeZone);
isSameYear
Takes in two date objects and an optional time zone string parameter. Returns a boolean indicating whether or not these two dates are in the same year.
import {isSameYear} from '@shopify/dates';
const date1 = '2018-01-01Z00:00';
const date2 = '2018-01-02Z23:59';
const timeZone = 'America/Toronto';
const sameYear = isSameYear(date1, date2, timeZone);
isToday
Takes in a date object and an optional time zone string parameter. Returns a boolean indicating whether or not this date is today.
import {isToday} from '@shopify/dates';
const date = '2018-01-01Z00:00';
const timeZone = 'America/Toronto';
const today = isToday(date, timeZone);
isTomorrow
Takes in a date object and an optional time zone string parameter. Returns a boolean indicating whether or not this date is tomorrow.
import {isTomorrow} from '@shopify/dates';
const date = '2018-01-01Z00:00';
const timeZone = 'America/Toronto';
const tomorrow = isTomorrow(date, timeZone);
isYesterday
Takes in a date object and an optional time zone string parameter. Returns a boolean indicating whether or not this date is yesterday.
import {isYesterday} from '@shopify/dates';
const date = '2018-01-01Z00:00';
const timeZone = 'America/Toronto';
const yesterday = isYesterday(date, timeZone);
mapDeprecatedTimezones
Takes in a time zone string parameter. Returns a time zone string corresponding to the equivalent, non-deprecated time zone string.
import {mapDeprecatedTimezones} from '@shopify/dates';
const deprecatedTimeZone = 'Cuba';
const correctTimeZone = mapDeprecatedTimezones(deprecatedTimeZone);
parseDateString
Takes in a date string and an optional time zone string parameter. Returns a date object with the format '2018-05-28T12:30:00+00:00' (yyyy-mm-ddThh:mm:ss+00:00, where '+00:00' represents the time zone offset)
import {parseDateString} from '@shopify/dates';
const date = '2018-01-01Z00:00';
const timeZone = 'UTC';
const parsed = parseDateString(date, timeZone);
parseDateStringParts
Takes in a date string. Returns parsed parts from that date string.
import {parseDateStringParts} from '@shopify/dates';
const date = '2018-05-28T12:30:00.123+05:30';
const {
year,
month,
day,
hour,
minute,
second,
millisecond,
timeZoneOffset,
sign,
timeZoneHour,
timeZoneMinute,
} = parseDateStringParts(date);
unapplyTimeZoneOffset
Takes in a date object and two optional time zone string parameters. Returns a new date object with the offset between the time zones subtracted from it.
import {unapplyTimeZoneOffset} from '@shopify/dates';
const date = new Date('2018-06-01Z14:00');
const timeZone = 'Australia/Perth';
const newDate = unapplyTimeZoneOffset(date, offset);