18 KiB
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 |