@shopify/dates

@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);

formatDate

Takes in a date object and two additional parameters, the locale and an optional options object. Returns a new date string with the applied locale and options.

import {formatDate} from '@shopify/dates';

const date = new Date('2020-02-18Z14:00');
const locales = 'en';
const options = {
  timeZone: 'America/New_York',
  hour: 'numeric',
};

const newDate = formatDate(date, locales, options); // 9 AM

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); // false
isLessThanOneDayAgo(lessThanOneDayAgo); // true

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); // false
isLessThanOneHourAgo(lessThanOneHourAgo); // true

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); // false
isLessThanOneMinuteAgo(lessThanOneMinuteAgo); // true

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); // false
isLessThanOneWeekAgo(lessThanOneWeekAgo); // true

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); // false
isLessThanOneYearAgo(lessThanOneYearAgo); // true

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); // In this case, returns 'America/Havana'

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);