Nerfing Powerful Megalomaniacs
    Have ideas to improve npm?Join in the discussion! »

    @shopify/dates
    TypeScript icon, indicating that this package has built-in type declarations

    0.5.8 • Public • Published

    @shopify/dates

    Build Status Build Status License: MIT npm version npm bundle size (minified + gzip)

    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. We can also assume the passed date is in the first time zone and we want to calculate it in the second time zone.

    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); //'2018-06-01T02:00:00.000Z'

    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

    isLessThanOneWeekAway

    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 after the "now" date.

    import {isLessThanOneWeekAway} from '@shopify/dates';
    
    const moreThanOneWeekAway = new Date(Date.now() + 8 * TimeUnit.Day);
    const lessThanOneWeekAway = new Date(Date.now() + 6 * TimeUnit.Day);
    
    isLessThanOneWeekAway(moreThanOneWeekAway); // false
    isLessThanOneWeekAway(lessThanOneWeekAway); // 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

    isLessThanOneYearAway

    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 after the "now" date.

    import {isLessThanOneYearAway} from '@shopify/dates';
    
    const moreThanOneYearAway = new Date(Date.now() + 53 * TimeUnit.Week);
    const lessThanOneYearAway = new Date(Date.now() + 51 * TimeUnit.Week);
    
    isLessThanOneYearAway(moreThanOneYearAway); // false
    isLessThanOneYearAway(lessThanOneYearAway); // 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. We can also assume the passed date is in the second time zone and we want to calculate it back in the first time zone.

    import {unapplyTimeZoneOffset} from '@shopify/dates';
    
    const date = new Date('2018-06-01Z14:00');
    const timeZone1 = 'Australia/Perth';
    const timeZone2 = 'America/Toronto';
    
    const newDate = unapplyTimeZoneOffset(date, timeZone1, timeZone2); //2018-06-02T02:00:00.000Z

    Keywords

    none

    Install

    npm i @shopify/dates

    DownloadsWeekly Downloads

    79,590

    Version

    0.5.8

    License

    MIT

    Unpacked Size

    174 kB

    Total Files

    204

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar