@woocommerce/date

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

appendTimestamp ⇒ string

Adds timestamp to a string date.

getDateValue ⇒ DateValue

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

getDateParamsFromQueryMemoized ⇒ Object

Memoized internal logic of getDateParamsFromQuery().

getDateParamsFromQuery ⇒ DateParams

Add default date-related parameters to a query object

getCurrentDatesMemoized ⇒ Object

Memoized internal logic of getCurrentDates().

getCurrentDates ⇒ Object

Get Date Value Objects for a primary and secondary date range

getDateDifferenceInDays ⇒ number

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

getPreviousDate ⇒ Object

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