Ninja Pirate Mutants

    @woocommerce/date
    TypeScript icon, indicating that this package has built-in type declarations

    4.2.0 • Public • Published

    Date

    A collection of utilities to display and work with date values.

    Installation

    Install the module

    pnpm install @woocommerce/date --save

    This package assumes that your code will run in an ES2015+ environment. If you're using an environment that has limited or no support for ES2015+ such as lower versions of IE then using core-js or @babel/polyfill will add support for these methods. Learn more about it in Babel docs.

    Usage

    The date package makes use of the global window.wcSettings.timeZone. If a timezone is set, the current and last periods will be converted from your browser's timezone to the store timezone. If none is set, these periods will be based on your browser's timezone.

    Functions

    appendTimestampstring

    Adds timestamp to a string date.

    getDateValueDateValue

    Get a DateValue object for a period described by a period, compare value, and start/end dates, for custom dates.

    getDateParamsFromQueryMemoizedObject

    Memoized internal logic of getDateParamsFromQuery().

    getDateParamsFromQueryDateParams

    Add default date-related parameters to a query object

    getCurrentDatesMemoizedObject

    Memoized internal logic of getCurrentDates().

    getCurrentDatesObject

    Get Date Value Objects for a primary and secondary date range

    getDateDifferenceInDaysnumber

    Calculates the date difference between two dates. Used in calculating a matching date for previous period.

    getPreviousDateObject

    Get the previous date for either the previous period of year.

    toMoment(format, str)Object | null

    Convert a string to Moment object

    getRangeLabel(after, before)string

    Given two dates, derive a string representation

    getStoreTimeZoneMoment()string

    Gets the current time in the store time zone if set.

    getLastPeriod(period, compare)DateValue

    Get a DateValue object for a period prior to the current period.

    getCurrentPeriod(period, compare)DateValue

    Get a DateValue object for a curent period. The period begins on the first day of the period, and ends on the current day.

    getAllowedIntervalsForQuery(query, defaultDateRange)Array

    Returns the allowed selectable intervals for a specific query.

    getIntervalForQuery(query, defaultDateRange)string

    Returns the current interval to use.

    getChartTypeForQuery(query)string

    Returns the current chart type to use.

    getDateFormatsForInterval(interval, [ticks], [option])string

    Returns date formats for the current interval.

    getDateFormatsForIntervalD3(interval, [ticks])string

    Returns d3 date formats for the current interval. See https://github.com/d3/d3-time-format for chart formats.

    getDateFormatsForIntervalPhp(interval, [ticks])string

    Returns php date formats for the current interval. See see https://www.php.net/manual/en/datetime.format.php.

    loadLocaleData(config)

    Gutenberg's moment instance is loaded with i18n values, which are PHP date formats, ie 'LLL: "F j, Y g:i a"'. Override those with translations of moment style js formats.

    validateDateInputForRange(type, value, [before], [after], format)Object

    Validate text input supplied for a date range.

    Typedefs

    DateValue : Object

    DateValue Object

    DateParams : Object

    DateParams Object

    validatedDate : Object

    appendTimestamp ⇒ string

    Adds timestamp to a string date.

    Kind: global constant Returns: string - - String date with timestamp attached.

    Param Type Description
    date moment.Moment Date as a moment object.
    timeOfDay string Either start, now or end of the day.

    getDateValue ⇒ DateValue

    Get a DateValue object for a period described by a period, compare value, and start/end dates, for custom dates.

    Kind: global constant Returns: DateValue - - DateValue data about the selected period

    Param Type Description
    period string the chosen period
    compare string previous_period or previous_year
    [after] Object after date if custom period
    [before] Object before date if custom period

    getDateParamsFromQueryMemoized ⇒ Object

    Memoized internal logic of getDateParamsFromQuery().

    Kind: global constant Returns: Object - - date parameters derived from query parameters with added defaults

    Param Type Description
    period string period value, ie last_week
    compare string compare value, ie previous_year
    after string date in iso date format, ie 2018-07-03
    before string date in iso date format, ie 2018-07-03
    defaultDateRange string the store's default date range

    getDateParamsFromQuery ⇒ DateParams

    Add default date-related parameters to a query object

    Kind: global constant Returns: DateParams - - date parameters derived from query parameters with added defaults

    Param Type Description
    query Object query object
    query.period string period value, ie last_week
    query.compare string compare value, ie previous_year
    query.after string date in iso date format, ie 2018-07-03
    query.before string date in iso date format, ie 2018-07-03
    defaultDateRange string the store's default date range

    getCurrentDatesMemoized ⇒ Object

    Memoized internal logic of getCurrentDates().

    Kind: global constant Returns: Object - - Primary and secondary DateValue objects

    Param Type Description
    period string period value, ie last_week
    compare string compare value, ie previous_year
    primaryStart Object primary query start DateTime, in Moment instance.
    primaryEnd Object primary query start DateTime, in Moment instance.
    secondaryStart Object primary query start DateTime, in Moment instance.
    secondaryEnd Object primary query start DateTime, in Moment instance.

    getCurrentDates ⇒ Object

    Get Date Value Objects for a primary and secondary date range

    Kind: global constant Returns: Object - - Primary and secondary DateValue objects

    Param Type Description
    query Object query object
    query.period string period value, ie last_week
    query.compare string compare value, ie previous_year
    query.after string date in iso date format, ie 2018-07-03
    query.before string date in iso date format, ie 2018-07-03
    defaultDateRange string the store's default date range

    getDateDifferenceInDays ⇒ number

    Calculates the date difference between two dates. Used in calculating a matching date for previous period.

    Kind: global constant Returns: number - - Difference in days.

    Param Type Description
    date string Date to compare
    date2 string Seconary date to compare

    getPreviousDate ⇒ Object

    Get the previous date for either the previous period of year.

    Kind: global constant Returns: Object - - Calculated date

    Param Type Description
    date string Base date
    date1 string primary start
    date2 string secondary start
    compare string previous_period or previous_year
    interval string interval

    toMoment(format, str) ⇒ Object | null

    Convert a string to Moment object

    Kind: global function Returns: Object | null - - Moment object representing given string

    Param Type Description
    format string localized date string format
    str string date string

    getRangeLabel(after, before) ⇒ string

    Given two dates, derive a string representation

    Kind: global function Returns: string - - text value for the supplied date range

    Param Type Description
    after Object start date
    before Object end date

    getStoreTimeZoneMoment() ⇒ string

    Gets the current time in the store time zone if set.

    Kind: global function Returns: string - - Datetime string.

    getLastPeriod(period, compare) ⇒ DateValue

    Get a DateValue object for a period prior to the current period.

    Kind: global function Returns: DateValue - - DateValue data about the selected period

    Param Type Description
    period string the chosen period
    compare string previous_period or previous_year

    getCurrentPeriod(period, compare) ⇒ DateValue

    Get a DateValue object for a curent period. The period begins on the first day of the period, and ends on the current day.

    Kind: global function Returns: DateValue - - DateValue data about the selected period

    Param Type Description
    period string the chosen period
    compare string previous_period or previous_year

    getAllowedIntervalsForQuery(query, defaultDateRange) ⇒ Array

    Returns the allowed selectable intervals for a specific query.

    Kind: global function Returns: Array - Array containing allowed intervals.

    Param Type Description
    query Object Current query
    defaultDateRange string the store's default date range

    getIntervalForQuery(query, defaultDateRange) ⇒ string

    Returns the current interval to use.

    Kind: global function Returns: string - Current interval.

    Param Type Description
    query Object Current query
    defaultDateRange string the store's default date range

    getChartTypeForQuery(query) ⇒ string

    Returns the current chart type to use.

    Kind: global function Returns: string - Current chart type.

    Param Type Description
    query Object Current query
    query.chartType string

    getDateFormatsForInterval(interval, [ticks], [option]) ⇒ string

    Returns date formats for the current interval.

    Kind: global function Returns: string - Current interval.

    Param Type Description
    interval string Interval to get date formats for.
    [ticks] number Number of ticks the axis will have.
    [option] Object Options
    [option.type] string Date format type, d3 or php, defaults to d3.

    getDateFormatsForIntervalD3(interval, [ticks]) ⇒ string

    Returns d3 date formats for the current interval. See https://github.com/d3/d3-time-format for chart formats.

    Kind: global function Returns: string - Current interval.

    Param Type Description
    interval string Interval to get date formats for.
    [ticks] number Number of ticks the axis will have.

    getDateFormatsForIntervalPhp(interval, [ticks]) ⇒ string

    Returns php date formats for the current interval. See see https://www.php.net/manual/en/datetime.format.php.

    Kind: global function Returns: string - Current interval.

    Param Type Description
    interval string Interval to get date formats for.
    [ticks] number Number of ticks the axis will have.

    loadLocaleData(config)

    Gutenberg's moment instance is loaded with i18n values, which are PHP date formats, ie 'LLL: "F j, Y g:i a"'. Override those with translations of moment style js formats.

    Kind: global function

    Param Type Description
    config Object Locale config object, from store settings.
    config.userLocale string
    config.weekdaysShort Array

    validateDateInputForRange(type, value, [before], [after], format) ⇒ Object

    Validate text input supplied for a date range.

    Kind: global function Returns: Object - validatedDate - validated date object

    Param Type Description
    type string Designate beginning or end of range, eg before or after.
    value string User input value
    [before] Object | null If already designated, the before date parameter
    [after] Object | null If already designated, the after date parameter
    format string The expected date format in a user's locale

    DateValue : Object

    DateValue Object

    Kind: global typedef Properties

    Name Type Description
    label string The translated value of the period.
    range string The human readable value of a date range.
    after moment.Moment Start of the date range.
    before moment.Moment End of the date range.

    DateParams : Object

    DateParams Object

    Kind: global typedef

    Param Type Description
    after moment.Moment | null If the period supplied is "custom", this is the after date
    before moment.Moment | null If the period supplied is "custom", this is the before date

    Properties

    Name Type Description
    period string period value, ie last_week
    compare string compare valuer, ie previous_year

    validatedDate : Object

    Kind: global typedef Properties

    Name Type Description
    date Object | null A resulting Moment date object or null, if invalid
    error string An optional error message if date is invalid

    Install

    npm i @woocommerce/date

    DownloadsWeekly Downloads

    2,150

    Version

    4.2.0

    License

    GPL-3.0-or-later

    Unpacked Size

    401 kB

    Total Files

    20

    Last publish

    Collaborators

    • chihsuan
    • rjchow
    • zhongruige
    • ~woocommerce
    • adrianduffell
    • octaedro
    • psealock
    • mikejolley
    • albertjuhe
    • nerrad
    • obliviousharmony
    • dygerati
    • louwie17
    • ilyasfoo
    • mattsherman
    • joshuatf
    • moon.kyong