@wordpress/date - npm Package Compare versions

Comparing version 3.8.0 to 3.9.0

build-module/index.js

@@ -9,3 +9,6 @@ /**
 
-var WP_ZONE = 'WP'; // Changes made here will likely need to be made in `lib/client-assets.php` as
+var WP_ZONE = 'WP'; // This regular expression tests positive for UTC offsets as described in ISO 8601.
+// See: https://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC
+
+var VALID_UTC_OFFSET = /^[+-][0-1][0-9](:?[0-9][0-9])?$/; // Changes made here will likely need to be made in `lib/client-assets.php` as
 // well because it uses the `setSettings()` function to change these settings.
@@ -281,6 +284,6 @@
  *
- * @param {string}                           dateFormat PHP-style formatting string.
- *                                                      See php.net/date.
- * @param {(Date|string|Moment|null)}        dateValue  Date object or string,
- *                                                      parsable by moment.js.
+ * @param {string}                  dateFormat PHP-style formatting string.
+ *                                             See php.net/date.
+ * @param {Date|string|Moment|null} dateValue  Date object or string,
+ *                                             parsable by moment.js.
  *
@@ -325,10 +328,16 @@ * @return {string} Formatted date.
 /**
- * Formats a date (like `date()` in PHP), in the site's timezone.
+ * Formats a date (like `date()` in PHP).
  *
- * @param {string}                           dateFormat PHP-style formatting string.
- *                                                      See php.net/date.
- * @param {(Date|string|Moment|null)}        dateValue  Date object or string,
- *                                                      parsable by moment.js.
+ * @param {string}                  dateFormat PHP-style formatting string.
+ *                                             See php.net/date.
+ * @param {Date|string|Moment|null} dateValue  Date object or string, parsable
+ *                                             by moment.js.
+ * @param {string|number|null}      timezone   Timezone to output result in or a
+ *                                             UTC offset. Defaults to timezone from
+ *                                             site.
  *
- * @return {string} Formatted date.
+ * @see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+ * @see https://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC
+ *
+ * @return {string} Formatted date in English.
  */
@@ -338,4 +347,4 @@
   var dateValue = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : new Date();
-  var offset = settings.timezone.offset * HOUR_IN_MINUTES;
-  var dateMoment = momentLib(dateValue).utcOffset(offset, true);
+  var timezone = arguments.length > 2 ? arguments[2] : undefined;
+  var dateMoment = buildMoment(dateValue, timezone);
   return format(dateFormat, dateMoment);
@@ -346,8 +355,8 @@ }
  *
- * @param {string}                           dateFormat PHP-style formatting string.
- *                                                      See php.net/date.
- * @param {(Date|string|Moment|null)}        dateValue  Date object or string,
- *                                                      parsable by moment.js.
+ * @param {string}                  dateFormat PHP-style formatting string.
+ *                                             See php.net/date.
+ * @param {Date|string|Moment|null} dateValue  Date object or string,
+ *                                             parsable by moment.js.
  *
- * @return {string} Formatted date.
+ * @return {string} Formatted date in English.
  */
@@ -361,11 +370,20 @@
 /**
- * Formats a date (like `date_i18n()` in PHP).
+ * Formats a date (like `wp_date()` in PHP), translating it into site's locale.
  *
- * @param {string}                           dateFormat PHP-style formatting string.
- *                                                      See php.net/date.
- * @param {(Date|string|Moment|null)}        dateValue  Date object or string,
- *                                                      parsable by moment.js.
- * @param {boolean}                          gmt        True for GMT/UTC, false for
- *                                                      site's timezone.
+ * Backward Compatibility Notice: if `timezone` is set to `true`, the function
+ * behaves like `gmdateI18n`.
  *
+ * @param {string}                     dateFormat PHP-style formatting string.
+ *                                                See php.net/date.
+ * @param {Date|string|Moment|null}    dateValue  Date object or string, parsable by
+ *                                                moment.js.
+ * @param {string|number|boolean|null} timezone   Timezone to output result in or a
+ *                                                UTC offset. Defaults to timezone from
+ *                                                site. Notice: `boolean` is effectively
+ *                                                deprecated, but still supported for
+ *                                                backward compatibility reasons.
+ *
+ * @see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+ * @see https://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC
+ *
  * @return {string} Formatted date.
@@ -376,13 +394,35 @@ */
   var dateValue = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : new Date();
-  var gmt = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : false;
-  // Defaults.
-  var offset = gmt ? 0 : settings.timezone.offset * HOUR_IN_MINUTES; // Convert to moment object.
+  var timezone = arguments.length > 2 ? arguments[2] : undefined;
 
-  var dateMoment = momentLib(dateValue).utcOffset(offset, true); // Set the locale.
+  if (true === timezone) {
+    return gmdateI18n(dateFormat, dateValue);
+  }
 
-  dateMoment.locale(settings.l10n.locale); // Format and return.
+  if (false === timezone) {
+    timezone = undefined;
+  }
 
+  var dateMoment = buildMoment(dateValue, timezone);
+  dateMoment.locale(settings.l10n.locale);
   return format(dateFormat, dateMoment);
 }
 /**
+ * Formats a date (like `wp_date()` in PHP), translating it into site's locale
+ * and using the UTC timezone.
+ *
+ * @param {string}                  dateFormat PHP-style formatting string.
+ *                                             See php.net/date.
+ * @param {Date|string|Moment|null} dateValue  Date object or string,
+ *                                             parsable by moment.js.
+ *
+ * @return {string} Formatted date.
+ */
+
+export function gmdateI18n(dateFormat) {
+  var dateValue = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : new Date();
+  var dateMoment = momentLib(dateValue).utc();
+  dateMoment.locale(settings.l10n.locale);
+  return format(dateFormat, dateMoment);
+}
+/**
  * Check whether a date is considered in the future according to the WordPress settings.
@@ -415,3 +455,53 @@ *
 }
+/**
+ * Creates a moment instance using the given timezone or, if none is provided, using global settings.
+ *
+ * @param {Date|string|Moment|null} dateValue Date object or string, parsable
+ *                                            by moment.js.
+ * @param {string|number|null}      timezone  Timezone to output result in or a
+ *                                            UTC offset. Defaults to timezone from
+ *                                            site.
+ *
+ * @see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+ * @see https://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC
+ *
+ * @return {Moment} a moment instance.
+ */
+
+function buildMoment(dateValue) {
+  var timezone = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : '';
+  var dateMoment = momentLib(dateValue);
+
+  if (timezone && !isUTCOffset(timezone)) {
+    return dateMoment.tz(timezone);
+  }
+
+  if (timezone && isUTCOffset(timezone)) {
+    return dateMoment.utcOffset(timezone);
+  }
+
+  if (settings.timezone.string) {
+    return dateMoment.tz(settings.timezone.string);
+  }
+
+  return dateMoment.utcOffset(settings.timezone.offset);
+}
+/**
+ * Returns whether a certain UTC offset is valid or not.
+ *
+ * @param {number|string} offset a UTC offset.
+ *
+ * @return {boolean} whether a certain UTC offset is valid or not.
+ */
+
+
+function isUTCOffset(offset) {
+  if ('number' === typeof offset) {
+    return true;
+  }
+
+  return VALID_UTC_OFFSET.test(offset);
+}
+
 setupWPTimezone();
 //# sourceMappingURL=index.js.map

build/index.js

@@ -14,2 +14,3 @@ "use strict";
 exports.dateI18n = dateI18n;
+exports.gmdateI18n = gmdateI18n;
 exports.isInTheFuture = isInTheFuture;
@@ -29,3 +30,6 @@ exports.getDate = getDate;
 /** @typedef {import('moment').Moment} Moment */
-var WP_ZONE = 'WP'; // Changes made here will likely need to be made in `lib/client-assets.php` as
+var WP_ZONE = 'WP'; // This regular expression tests positive for UTC offsets as described in ISO 8601.
+// See: https://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC
+
+var VALID_UTC_OFFSET = /^[+-][0-1][0-9](:?[0-9][0-9])?$/; // Changes made here will likely need to be made in `lib/client-assets.php` as
 // well because it uses the `setSettings()` function to change these settings.
@@ -305,6 +309,6 @@
  *
- * @param {string}                           dateFormat PHP-style formatting string.
- *                                                      See php.net/date.
- * @param {(Date|string|Moment|null)}        dateValue  Date object or string,
- *                                                      parsable by moment.js.
+ * @param {string}                  dateFormat PHP-style formatting string.
+ *                                             See php.net/date.
+ * @param {Date|string|Moment|null} dateValue  Date object or string,
+ *                                             parsable by moment.js.
  *
@@ -349,10 +353,16 @@ * @return {string} Formatted date.
 /**
- * Formats a date (like `date()` in PHP), in the site's timezone.
+ * Formats a date (like `date()` in PHP).
  *
- * @param {string}                           dateFormat PHP-style formatting string.
- *                                                      See php.net/date.
- * @param {(Date|string|Moment|null)}        dateValue  Date object or string,
- *                                                      parsable by moment.js.
+ * @param {string}                  dateFormat PHP-style formatting string.
+ *                                             See php.net/date.
+ * @param {Date|string|Moment|null} dateValue  Date object or string, parsable
+ *                                             by moment.js.
+ * @param {string|number|null}      timezone   Timezone to output result in or a
+ *                                             UTC offset. Defaults to timezone from
+ *                                             site.
  *
- * @return {string} Formatted date.
+ * @see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+ * @see https://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC
+ *
+ * @return {string} Formatted date in English.
  */
@@ -363,4 +373,4 @@
   var dateValue = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : new Date();
-  var offset = settings.timezone.offset * HOUR_IN_MINUTES;
-  var dateMoment = (0, _moment.default)(dateValue).utcOffset(offset, true);
+  var timezone = arguments.length > 2 ? arguments[2] : undefined;
+  var dateMoment = buildMoment(dateValue, timezone);
   return format(dateFormat, dateMoment);
@@ -371,8 +381,8 @@ }
  *
- * @param {string}                           dateFormat PHP-style formatting string.
- *                                                      See php.net/date.
- * @param {(Date|string|Moment|null)}        dateValue  Date object or string,
- *                                                      parsable by moment.js.
+ * @param {string}                  dateFormat PHP-style formatting string.
+ *                                             See php.net/date.
+ * @param {Date|string|Moment|null} dateValue  Date object or string,
+ *                                             parsable by moment.js.
  *
- * @return {string} Formatted date.
+ * @return {string} Formatted date in English.
  */
@@ -387,11 +397,20 @@
 /**
- * Formats a date (like `date_i18n()` in PHP).
+ * Formats a date (like `wp_date()` in PHP), translating it into site's locale.
  *
- * @param {string}                           dateFormat PHP-style formatting string.
- *                                                      See php.net/date.
- * @param {(Date|string|Moment|null)}        dateValue  Date object or string,
- *                                                      parsable by moment.js.
- * @param {boolean}                          gmt        True for GMT/UTC, false for
- *                                                      site's timezone.
+ * Backward Compatibility Notice: if `timezone` is set to `true`, the function
+ * behaves like `gmdateI18n`.
  *
+ * @param {string}                     dateFormat PHP-style formatting string.
+ *                                                See php.net/date.
+ * @param {Date|string|Moment|null}    dateValue  Date object or string, parsable by
+ *                                                moment.js.
+ * @param {string|number|boolean|null} timezone   Timezone to output result in or a
+ *                                                UTC offset. Defaults to timezone from
+ *                                                site. Notice: `boolean` is effectively
+ *                                                deprecated, but still supported for
+ *                                                backward compatibility reasons.
+ *
+ * @see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+ * @see https://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC
+ *
  * @return {string} Formatted date.
@@ -403,13 +422,36 @@ */
   var dateValue = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : new Date();
-  var gmt = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : false;
-  // Defaults.
-  var offset = gmt ? 0 : settings.timezone.offset * HOUR_IN_MINUTES; // Convert to moment object.
+  var timezone = arguments.length > 2 ? arguments[2] : undefined;
 
-  var dateMoment = (0, _moment.default)(dateValue).utcOffset(offset, true); // Set the locale.
+  if (true === timezone) {
+    return gmdateI18n(dateFormat, dateValue);
+  }
 
-  dateMoment.locale(settings.l10n.locale); // Format and return.
+  if (false === timezone) {
+    timezone = undefined;
+  }
 
+  var dateMoment = buildMoment(dateValue, timezone);
+  dateMoment.locale(settings.l10n.locale);
   return format(dateFormat, dateMoment);
 }
 /**
+ * Formats a date (like `wp_date()` in PHP), translating it into site's locale
+ * and using the UTC timezone.
+ *
+ * @param {string}                  dateFormat PHP-style formatting string.
+ *                                             See php.net/date.
+ * @param {Date|string|Moment|null} dateValue  Date object or string,
+ *                                             parsable by moment.js.
+ *
+ * @return {string} Formatted date.
+ */
+
+
+function gmdateI18n(dateFormat) {
+  var dateValue = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : new Date();
+  var dateMoment = (0, _moment.default)(dateValue).utc();
+  dateMoment.locale(settings.l10n.locale);
+  return format(dateFormat, dateMoment);
+}
+/**
  * Check whether a date is considered in the future according to the WordPress settings.
@@ -446,4 +488,54 @@ *
 }
+/**
+ * Creates a moment instance using the given timezone or, if none is provided, using global settings.
+ *
+ * @param {Date|string|Moment|null} dateValue Date object or string, parsable
+ *                                            by moment.js.
+ * @param {string|number|null}      timezone  Timezone to output result in or a
+ *                                            UTC offset. Defaults to timezone from
+ *                                            site.
+ *
+ * @see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+ * @see https://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC
+ *
+ * @return {Moment} a moment instance.
+ */
 
+
+function buildMoment(dateValue) {
+  var timezone = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : '';
+  var dateMoment = (0, _moment.default)(dateValue);
+
+  if (timezone && !isUTCOffset(timezone)) {
+    return dateMoment.tz(timezone);
+  }
+
+  if (timezone && isUTCOffset(timezone)) {
+    return dateMoment.utcOffset(timezone);
+  }
+
+  if (settings.timezone.string) {
+    return dateMoment.tz(settings.timezone.string);
+  }
+
+  return dateMoment.utcOffset(settings.timezone.offset);
+}
+/**
+ * Returns whether a certain UTC offset is valid or not.
+ *
+ * @param {number|string} offset a UTC offset.
+ *
+ * @return {boolean} whether a certain UTC offset is valid or not.
+ */
+
+
+function isUTCOffset(offset) {
+  if ('number' === typeof offset) {
+    return true;
+  }
+
+  return VALID_UTC_OFFSET.test(offset);
+}
+
 setupWPTimezone();
 //# sourceMappingURL=index.js.map

package.json

 {
 	"name": "@wordpress/date",
-	"version": "3.8.0",
+	"version": "3.9.0",
 	"description": "Date module for WordPress.",
@@ -24,3 +24,3 @@ "author": "The WordPress Contributors",
 	"dependencies": {
-		"@babel/runtime": "^7.8.3",
+		"@babel/runtime": "^7.9.2",
 		"moment": "^2.22.1",
@@ -32,3 +32,3 @@ "moment-timezone": "^0.5.16"
 	},
-	"gitHead": "41fc84af285da696c65c235331ee245dfe23971d"
+	"gitHead": "65dbf3a9503402ca3837090dc89d0207f7d96352"
 }

README.md

@@ -21,4 +21,9 @@ # Date
 
-Formats a date (like `date()` in PHP), in the site's timezone.
+Formats a date (like `date()` in PHP).
 
+_Related_
+
+-   <https://en.wikipedia.org/wiki/List_of_tz_database_time_zones>
+-   <https://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC>
+
 _Parameters_
@@ -28,11 +33,20 @@
 -   _dateValue_ `(Date|string|Moment|null)`: Date object or string, parsable by moment.js.
+-   _timezone_ `(string|number|null)`: Timezone to output result in or a UTC offset. Defaults to timezone from site.
 
 _Returns_
 
--   `string`: Formatted date.
+-   `string`: Formatted date in English.
 
 <a name="dateI18n" href="#dateI18n">#</a> **dateI18n**
 
-Formats a date (like `date_i18n()` in PHP).
+Formats a date (like `wp_date()` in PHP), translating it into site's locale.
 
+Backward Compatibility Notice: if `timezone` is set to `true`, the function
+behaves like `gmdateI18n`.
+
+_Related_
+
+-   <https://en.wikipedia.org/wiki/List_of_tz_database_time_zones>
+-   <https://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC>
+
 _Parameters_
@@ -42,3 +56,3 @@
 -   _dateValue_ `(Date|string|Moment|null)`: Date object or string, parsable by moment.js.
--   _gmt_ `boolean`: True for GMT/UTC, false for site's timezone.
+-   _timezone_ `(string|number|boolean|null)`: Timezone to output result in or a UTC offset. Defaults to timezone from site. Notice: `boolean` is effectively deprecated, but still supported for backward compatibility reasons.
 
@@ -85,2 +99,16 @@ _Returns_
 
+-   `string`: Formatted date in English.
+
+<a name="gmdateI18n" href="#gmdateI18n">#</a> **gmdateI18n**
+
+Formats a date (like `wp_date()` in PHP), translating it into site's locale
+and using the UTC timezone.
+
+_Parameters_
+
+-   _dateFormat_ `string`: PHP-style formatting string. See php.net/date.
+-   _dateValue_ `(Date|string|Moment|null)`: Date object or string, parsable by moment.js.
+
+_Returns_
+
 -   `string`: Formatted date.
@@ -87,0 +115,0 @@

src/index.js

@@ -12,2 +12,6 @@ /**
 
+// This regular expression tests positive for UTC offsets as described in ISO 8601.
+// See: https://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC
+const VALID_UTC_OFFSET = /^[+-][0-1][0-9](:?[0-9][0-9])?$/;
+
 // Changes made here will likely need to be made in `lib/client-assets.php` as
@@ -322,6 +326,6 @@ // well because it uses the `setSettings()` function to change these settings.
  *
- * @param {string}                           dateFormat PHP-style formatting string.
- *                                                      See php.net/date.
- * @param {(Date|string|Moment|null)}        dateValue  Date object or string,
- *                                                      parsable by moment.js.
+ * @param {string}                  dateFormat PHP-style formatting string.
+ *                                             See php.net/date.
+ * @param {Date|string|Moment|null} dateValue  Date object or string,
+ *                                             parsable by moment.js.
  *
@@ -362,14 +366,19 @@ * @return {string} Formatted date.
 /**
- * Formats a date (like `date()` in PHP), in the site's timezone.
+ * Formats a date (like `date()` in PHP).
  *
- * @param {string}                           dateFormat PHP-style formatting string.
- *                                                      See php.net/date.
- * @param {(Date|string|Moment|null)}        dateValue  Date object or string,
- *                                                      parsable by moment.js.
+ * @param {string}                  dateFormat PHP-style formatting string.
+ *                                             See php.net/date.
+ * @param {Date|string|Moment|null} dateValue  Date object or string, parsable
+ *                                             by moment.js.
+ * @param {string|number|null}      timezone   Timezone to output result in or a
+ *                                             UTC offset. Defaults to timezone from
+ *                                             site.
  *
- * @return {string} Formatted date.
+ * @see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+ * @see https://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC
+ *
+ * @return {string} Formatted date in English.
  */
-export function date( dateFormat, dateValue = new Date() ) {
-	const offset = settings.timezone.offset * HOUR_IN_MINUTES;
-	const dateMoment = momentLib( dateValue ).utcOffset( offset, true );
+export function date( dateFormat, dateValue = new Date(), timezone ) {
+	const dateMoment = buildMoment( dateValue, timezone );
 	return format( dateFormat, dateMoment );
@@ -381,8 +390,8 @@ }
  *
- * @param {string}                           dateFormat PHP-style formatting string.
- *                                                      See php.net/date.
- * @param {(Date|string|Moment|null)}        dateValue  Date object or string,
- *                                                      parsable by moment.js.
+ * @param {string}                  dateFormat PHP-style formatting string.
+ *                                             See php.net/date.
+ * @param {Date|string|Moment|null} dateValue  Date object or string,
+ *                                             parsable by moment.js.
  *
- * @return {string} Formatted date.
+ * @return {string} Formatted date in English.
  */
@@ -395,22 +404,33 @@ export function gmdate( dateFormat, dateValue = new Date() ) {
 /**
- * Formats a date (like `date_i18n()` in PHP).
+ * Formats a date (like `wp_date()` in PHP), translating it into site's locale.
  *
- * @param {string}                           dateFormat PHP-style formatting string.
- *                                                      See php.net/date.
- * @param {(Date|string|Moment|null)}        dateValue  Date object or string,
- *                                                      parsable by moment.js.
- * @param {boolean}                          gmt        True for GMT/UTC, false for
- *                                                      site's timezone.
+ * Backward Compatibility Notice: if `timezone` is set to `true`, the function
+ * behaves like `gmdateI18n`.
  *
+ * @param {string}                     dateFormat PHP-style formatting string.
+ *                                                See php.net/date.
+ * @param {Date|string|Moment|null}    dateValue  Date object or string, parsable by
+ *                                                moment.js.
+ * @param {string|number|boolean|null} timezone   Timezone to output result in or a
+ *                                                UTC offset. Defaults to timezone from
+ *                                                site. Notice: `boolean` is effectively
+ *                                                deprecated, but still supported for
+ *                                                backward compatibility reasons.
+ *
+ * @see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+ * @see https://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC
+ *
  * @return {string} Formatted date.
  */
-export function dateI18n( dateFormat, dateValue = new Date(), gmt = false ) {
-	// Defaults.
-	const offset = gmt ? 0 : settings.timezone.offset * HOUR_IN_MINUTES;
-	// Convert to moment object.
-	const dateMoment = momentLib( dateValue ).utcOffset( offset, true );
+export function dateI18n( dateFormat, dateValue = new Date(), timezone ) {
+	if ( true === timezone ) {
+		return gmdateI18n( dateFormat, dateValue );
+	}
 
-	// Set the locale.
+	if ( false === timezone ) {
+		timezone = undefined;
+	}
+
+	const dateMoment = buildMoment( dateValue, timezone );
 	dateMoment.locale( settings.l10n.locale );
-	// Format and return.
 	return format( dateFormat, dateMoment );
@@ -420,2 +440,19 @@ }
 /**
+ * Formats a date (like `wp_date()` in PHP), translating it into site's locale
+ * and using the UTC timezone.
+ *
+ * @param {string}                  dateFormat PHP-style formatting string.
+ *                                             See php.net/date.
+ * @param {Date|string|Moment|null} dateValue  Date object or string,
+ *                                             parsable by moment.js.
+ *
+ * @return {string} Formatted date.
+ */
+export function gmdateI18n( dateFormat, dateValue = new Date() ) {
+	const dateMoment = momentLib( dateValue ).utc();
+	dateMoment.locale( settings.l10n.locale );
+	return format( dateFormat, dateMoment );
+}
+
+/**
  * Check whether a date is considered in the future according to the WordPress settings.
@@ -449,2 +486,49 @@ *
 
+/**
+ * Creates a moment instance using the given timezone or, if none is provided, using global settings.
+ *
+ * @param {Date|string|Moment|null} dateValue Date object or string, parsable
+ *                                            by moment.js.
+ * @param {string|number|null}      timezone  Timezone to output result in or a
+ *                                            UTC offset. Defaults to timezone from
+ *                                            site.
+ *
+ * @see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+ * @see https://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC
+ *
+ * @return {Moment} a moment instance.
+ */
+function buildMoment( dateValue, timezone = '' ) {
+	const dateMoment = momentLib( dateValue );
+
+	if ( timezone && ! isUTCOffset( timezone ) ) {
+		return dateMoment.tz( timezone );
+	}
+
+	if ( timezone && isUTCOffset( timezone ) ) {
+		return dateMoment.utcOffset( timezone );
+	}
+
+	if ( settings.timezone.string ) {
+		return dateMoment.tz( settings.timezone.string );
+	}
+
+	return dateMoment.utcOffset( settings.timezone.offset );
+}
+
+/**
+ * Returns whether a certain UTC offset is valid or not.
+ *
+ * @param {number|string} offset a UTC offset.
+ *
+ * @return {boolean} whether a certain UTC offset is valid or not.
+ */
+function isUTCOffset( offset ) {
+	if ( 'number' === typeof offset ) {
+		return true;
+	}
+
+	return VALID_UTC_OFFSET.test( offset );
+}
+
 setupWPTimezone();

src/test/index.js

@@ -5,6 +5,10 @@ /**
 import {
+	__experimentalGetSettings,
+	date as dateNoI18n,
+	dateI18n,
+	getDate,
+	gmdate,
+	gmdateI18n,
 	isInTheFuture,
-	getDate,
 	setSettings,
-	__experimentalGetSettings,
 } from '../';
@@ -20,3 +24,3 @@
 
-	it( 'should return true if the date is in the past', () => {
+	it( 'should return false if the date is in the past', () => {
 		// Create a Date object 1 minute in the past.
@@ -49,2 +53,429 @@ const date = new Date( Number( getDate() ) - 1000 * 60 );
 
+describe( 'Function date', () => {
+	it( 'should format date in English, ignoring locale settings', () => {
+		const settings = __experimentalGetSettings();
+
+		// Simulate different locale
+		const l10n = settings.l10n;
+		setSettings( {
+			...settings,
+			l10n: {
+				...l10n,
+				locale: 'es',
+				months: l10n.months.map( ( month ) => `es_${ month }` ),
+				monthsShort: l10n.monthsShort.map(
+					( month ) => `es_${ month }`
+				),
+				weekdays: l10n.weekdays.map( ( weekday ) => `es_${ weekday }` ),
+				weekdaysShort: l10n.weekdaysShort.map(
+					( weekday ) => `es_${ weekday }`
+				),
+			},
+		} );
+
+		// Check
+		const formattedDate = dateNoI18n(
+			'F M l D',
+			'2019-06-18T11:00:00.000Z'
+		);
+		expect( formattedDate ).toBe( 'June Jun Tuesday Tue' );
+
+		// Restore default settings
+		setSettings( settings );
+	} );
+
+	it( 'should format date into a date that uses site’s timezone, if no timezone was provided and there’s a site timezone set', () => {
+		const settings = __experimentalGetSettings();
+
+		// Simulate different timezone
+		setSettings( {
+			...settings,
+			timezone: { offset: -4, string: 'America/New_York' },
+		} );
+
+		// Check
+		const winterFormattedDate = dateNoI18n(
+			'Y-m-d H:i',
+			'2019-01-18T11:00:00.000Z'
+		);
+		expect( winterFormattedDate ).toBe( '2019-01-18 06:00' );
+
+		const summerFormattedDate = dateNoI18n(
+			'Y-m-d H:i',
+			'2019-06-18T11:00:00.000Z'
+		);
+		expect( summerFormattedDate ).toBe( '2019-06-18 07:00' );
+
+		// Restore default settings
+		setSettings( settings );
+	} );
+
+	it( 'should format date into a date that uses site’s UTC offset setting, if no timezone was provided and there isn’t a timezone set in the site', () => {
+		const settings = __experimentalGetSettings();
+
+		// Simulate different timezone
+		setSettings( {
+			...settings,
+			timezone: { offset: -4, string: '' },
+		} );
+
+		// Check
+		const winterFormattedDate = dateNoI18n(
+			'Y-m-d H:i',
+			'2019-01-18T11:00:00.000Z'
+		);
+		expect( winterFormattedDate ).toBe( '2019-01-18 07:00' );
+
+		const summerFormattedDate = dateNoI18n(
+			'Y-m-d H:i',
+			'2019-06-18T11:00:00.000Z'
+		);
+		expect( summerFormattedDate ).toBe( '2019-06-18 07:00' );
+
+		// Restore default settings
+		setSettings( settings );
+	} );
+
+	it( 'should format date into a date that uses the given timezone, if said timezone is valid', () => {
+		const settings = __experimentalGetSettings();
+
+		// Simulate different timezone
+		setSettings( {
+			...settings,
+			timezone: { offset: -4, string: 'America/New_York' },
+		} );
+
+		// Check
+		const formattedDate = dateNoI18n(
+			'Y-m-d H:i',
+			'2019-06-18T11:00:00.000Z',
+			'Asia/Macau'
+		);
+		expect( formattedDate ).toBe( '2019-06-18 19:00' );
+
+		// Restore default settings
+		setSettings( settings );
+	} );
+
+	it( 'should format date into a date that uses the given UTC offset, if given timezone is actually a UTC offset', () => {
+		const settings = __experimentalGetSettings();
+
+		// Simulate different timezone
+		setSettings( {
+			...settings,
+			timezone: { offset: -4, string: 'America/New_York' },
+		} );
+
+		// Check
+		let formattedDate;
+		formattedDate = dateNoI18n(
+			'Y-m-d H:i',
+			'2019-06-18T11:00:00.000Z',
+			'+08:00'
+		);
+		expect( formattedDate ).toBe( '2019-06-18 19:00' );
+
+		formattedDate = dateNoI18n(
+			'Y-m-d H:i',
+			'2019-06-18T11:00:00.000Z',
+			8
+		);
+		expect( formattedDate ).toBe( '2019-06-18 19:00' );
+
+		formattedDate = dateNoI18n(
+			'Y-m-d H:i',
+			'2019-06-18T11:00:00.000Z',
+			480
+		);
+		expect( formattedDate ).toBe( '2019-06-18 19:00' );
+
+		// Restore default settings
+		setSettings( settings );
+	} );
+} );
+
+describe( 'Function gmdate', () => {
+	it( 'should format date in English, ignoring locale settings', () => {
+		const settings = __experimentalGetSettings();
+
+		// Simulate different locale
+		const l10n = settings.l10n;
+		setSettings( {
+			...settings,
+			l10n: {
+				...l10n,
+				locale: 'es',
+				months: l10n.months.map( ( month ) => `es_${ month }` ),
+				monthsShort: l10n.monthsShort.map(
+					( month ) => `es_${ month }`
+				),
+				weekdays: l10n.weekdays.map( ( weekday ) => `es_${ weekday }` ),
+				weekdaysShort: l10n.weekdaysShort.map(
+					( weekday ) => `es_${ weekday }`
+				),
+			},
+		} );
+
+		// Check
+		const formattedDate = gmdate( 'F M l D', '2019-06-18T11:00:00.000Z' );
+		expect( formattedDate ).toBe( 'June Jun Tuesday Tue' );
+
+		// Restore default settings
+		setSettings( settings );
+	} );
+
+	it( 'should format date into a UTC date', () => {
+		const settings = __experimentalGetSettings();
+
+		// Simulate different timezone
+		setSettings( {
+			...settings,
+			timezone: { offset: -4, string: 'America/New_York' },
+		} );
+
+		// Check
+		const formattedDate = gmdate( 'Y-m-d H:i', '2019-06-18T11:00:00.000Z' );
+		expect( formattedDate ).toBe( '2019-06-18 11:00' );
+
+		// Restore default settings
+		setSettings( settings );
+	} );
+} );
+
+describe( 'Function dateI18n', () => {
+	it( 'should format date using locale settings', () => {
+		const settings = __experimentalGetSettings();
+
+		// Simulate different locale
+		const l10n = settings.l10n;
+		setSettings( {
+			...settings,
+			l10n: {
+				...l10n,
+				locale: 'es',
+				months: l10n.months.map( ( month ) => `es_${ month }` ),
+				monthsShort: l10n.monthsShort.map(
+					( month ) => `es_${ month }`
+				),
+				weekdays: l10n.weekdays.map( ( weekday ) => `es_${ weekday }` ),
+				weekdaysShort: l10n.weekdaysShort.map(
+					( weekday ) => `es_${ weekday }`
+				),
+			},
+		} );
+
+		// Check
+		const formattedDate = dateI18n(
+			'F M l D',
+			'2019-06-18T11:00:00.000Z',
+			true
+		);
+		expect( formattedDate ).toBe( 'es_June es_Jun es_Tuesday es_Tue' );
+
+		// Restore default settings
+		setSettings( settings );
+	} );
+
+	it( 'should format date into a date that uses site’s timezone, if no timezone was provided and there’s a site timezone set', () => {
+		const settings = __experimentalGetSettings();
+
+		// Simulate different timezone
+		setSettings( {
+			...settings,
+			timezone: { offset: -4, string: 'America/New_York' },
+		} );
+
+		// Check
+		const winterFormattedDate = dateI18n(
+			'Y-m-d H:i',
+			'2019-01-18T11:00:00.000Z'
+		);
+		expect( winterFormattedDate ).toBe( '2019-01-18 06:00' );
+
+		const summerFormattedDate = dateI18n(
+			'Y-m-d H:i',
+			'2019-06-18T11:00:00.000Z'
+		);
+		expect( summerFormattedDate ).toBe( '2019-06-18 07:00' );
+
+		// Restore default settings
+		setSettings( settings );
+	} );
+
+	it( 'should format date into a date that uses site’s UTC offset setting, if no timezone was provided and there isn’t a timezone set in the site', () => {
+		const settings = __experimentalGetSettings();
+
+		// Simulate different timezone
+		setSettings( {
+			...settings,
+			timezone: { offset: -4, string: '' },
+		} );
+
+		// Check
+		const winterFormattedDate = dateI18n(
+			'Y-m-d H:i',
+			'2019-01-18T11:00:00.000Z'
+		);
+		expect( winterFormattedDate ).toBe( '2019-01-18 07:00' );
+
+		const summerFormattedDate = dateI18n(
+			'Y-m-d H:i',
+			'2019-06-18T11:00:00.000Z'
+		);
+		expect( summerFormattedDate ).toBe( '2019-06-18 07:00' );
+
+		// Restore default settings
+		setSettings( settings );
+	} );
+
+	it( 'should format date into a date that uses the given timezone, if said timezone is valid', () => {
+		const settings = __experimentalGetSettings();
+
+		// Simulate different timezone
+		setSettings( {
+			...settings,
+			timezone: { offset: -4, string: 'America/New_York' },
+		} );
+
+		// Check
+		const formattedDate = dateI18n(
+			'Y-m-d H:i',
+			'2019-06-18T11:00:00.000Z',
+			'Asia/Macau'
+		);
+		expect( formattedDate ).toBe( '2019-06-18 19:00' );
+
+		// Restore default settings
+		setSettings( settings );
+	} );
+
+	it( 'should format date into a date that uses the given UTC offset, if given timezone is actually a UTC offset', () => {
+		const settings = __experimentalGetSettings();
+
+		// Simulate different timezone
+		setSettings( {
+			...settings,
+			timezone: { offset: -4, string: 'America/New_York' },
+		} );
+
+		// Check
+		let formattedDate;
+		formattedDate = dateI18n(
+			'Y-m-d H:i',
+			'2019-06-18T11:00:00.000Z',
+			'+08:00'
+		);
+		expect( formattedDate ).toBe( '2019-06-18 19:00' );
+
+		formattedDate = dateI18n( 'Y-m-d H:i', '2019-06-18T11:00:00.000Z', 8 );
+		expect( formattedDate ).toBe( '2019-06-18 19:00' );
+
+		formattedDate = dateI18n(
+			'Y-m-d H:i',
+			'2019-06-18T11:00:00.000Z',
+			480
+		);
+		expect( formattedDate ).toBe( '2019-06-18 19:00' );
+
+		// Restore default settings
+		setSettings( settings );
+	} );
+
+	it( 'should format date into a UTC date if `gmt` is set to `true`', () => {
+		const settings = __experimentalGetSettings();
+
+		// Simulate different timezone
+		setSettings( {
+			...settings,
+			timezone: { offset: -4, string: 'America/New_York' },
+		} );
+
+		// Check
+		const formattedDate = dateI18n(
+			'Y-m-d H:i',
+			'2019-06-18T11:00:00.000Z',
+			true
+		);
+		expect( formattedDate ).toBe( '2019-06-18 11:00' );
+
+		// Restore default settings
+		setSettings( settings );
+	} );
+
+	it( 'should format date into a date that uses site’s timezone if `gmt` is set to `false`', () => {
+		const settings = __experimentalGetSettings();
+
+		// Simulate different timezone
+		setSettings( {
+			...settings,
+			timezone: { offset: -4, string: 'America/New_York' },
+		} );
+
+		// Check
+		const formattedDate = dateI18n(
+			'Y-m-d H:i',
+			'2019-06-18T11:00:00.000Z',
+			false
+		);
+		expect( formattedDate ).toBe( '2019-06-18 07:00' );
+
+		// Restore default settings
+		setSettings( settings );
+	} );
+} );
+
+describe( 'Function gmdateI18n', () => {
+	it( 'should format date using locale settings', () => {
+		const settings = __experimentalGetSettings();
+
+		// Simulate different locale
+		const l10n = settings.l10n;
+		setSettings( {
+			...settings,
+			l10n: {
+				...l10n,
+				locale: 'es',
+				months: l10n.months.map( ( month ) => `es_${ month }` ),
+				monthsShort: l10n.monthsShort.map(
+					( month ) => `es_${ month }`
+				),
+				weekdays: l10n.weekdays.map( ( weekday ) => `es_${ weekday }` ),
+				weekdaysShort: l10n.weekdaysShort.map(
+					( weekday ) => `es_${ weekday }`
+				),
+			},
+		} );
+
+		// Check
+		const formattedDate = gmdateI18n(
+			'F M l D',
+			'2019-06-18T11:00:00.000Z'
+		);
+		expect( formattedDate ).toBe( 'es_June es_Jun es_Tuesday es_Tue' );
+
+		// Restore default settings
+		setSettings( settings );
+	} );
+
+	it( 'should format date into a UTC date', () => {
+		const settings = __experimentalGetSettings();
+
+		// Simulate different timezone
+		setSettings( {
+			...settings,
+			timezone: { offset: -4, string: 'America/New_York' },
+		} );
+
+		// Check
+		const formattedDate = gmdateI18n(
+			'Y-m-d H:i',
+			'2019-06-18T11:00:00.000Z'
+		);
+		expect( formattedDate ).toBe( '2019-06-18 11:00' );
+
+		// Restore default settings
+		setSettings( settings );
+	} );
+} );
+
 describe( 'Moment.js Localization', () => {
@@ -51,0 +482,0 @@ it( 'should change the relative time strings', () => {

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

131229

increased by28.51%

Lines of code

1831

increased by47.78%

Number of lines in readme file

136

increased by25.93%

Dependency changes

• Updated@babel/runtime@^7.9.2