@wordpress/date 5.29.1-next.f34ab90e9.0 → 5.30.1-next.836ecdcae.0

package/src/{index.js → index.ts}

@@ -1,6 +1,7 @@
 /**
  * External dependencies
  */
+import type { Moment } from 'moment';
 import momentLib from 'moment';
 import 'moment-timezone/moment-timezone';
 import 'moment-timezone/moment-timezone-utils';
@@ -9,54 +10,12 @@ import 'moment-timezone/moment-timezone-utils';
  * WordPress dependencies
  */
 import deprecated from '@wordpress/deprecated';
-
-/** @typedef {import('moment').Moment} Moment */
-/** @typedef {import('moment').LocaleSpecification} MomentLocaleSpecification */
-
 /**
- * @typedef MeridiemConfig
- * @property {string} am Lowercase AM.
- * @property {string} AM Uppercase AM.
- * @property {string} pm Lowercase PM.
- * @property {string} PM Uppercase PM.
+ * Internal dependencies
  */
+import type { DateSettings } from './types';
 
-/**
- * @typedef FormatsConfig
- * @property {string} time                Time format.
- * @property {string} date                Date format.
- * @property {string} datetime            Datetime format.
- * @property {string} datetimeAbbreviated Abbreviated datetime format.
- */
-
-/**
- * @typedef TimezoneConfig
- * @property {string} offset          Offset setting.
- * @property {string} offsetFormatted Offset setting with decimals formatted to minutes.
- * @property {string} string          The timezone as a string (e.g., `'America/Los_Angeles'`).
- * @property {string} abbr            Abbreviation for the timezone.
- */
-
-/* eslint-disable jsdoc/valid-types */
-/**
- * @typedef L10nSettings
- * @property {string}                                     locale        Moment locale.
- * @property {MomentLocaleSpecification['months']}        months        Locale months.
- * @property {MomentLocaleSpecification['monthsShort']}   monthsShort   Locale months short.
- * @property {MomentLocaleSpecification['weekdays']}      weekdays      Locale weekdays.
- * @property {MomentLocaleSpecification['weekdaysShort']} weekdaysShort Locale weekdays short.
- * @property {MeridiemConfig}                             meridiem      Meridiem config.
- * @property {MomentLocaleSpecification['relativeTime']}  relative      Relative time config.
- * @property {0|1|2|3|4|5|6}                              startOfWeek   Day that the week starts on.
- */
-/* eslint-enable jsdoc/valid-types */
-
-/**
- * @typedef DateSettings
- * @property {L10nSettings}   l10n     Localization settings.
- * @property {FormatsConfig}  formats  Date/time formats config.
- * @property {TimezoneConfig} timezone Timezone settings.
- */
+export * from './types';
 
 const WP_ZONE = 'WP';
 
@@ -66,8 +25,7 @@ const VALID_UTC_OFFSET = /^[+-][0-1][0-9](:?[0-9][0-9])?$/;
 
 // Changes made here will likely need to be synced with Core in the file
 // src/wp-includes/script-loader.php in `wp_default_packages_inline_scripts()`.
-/** @type {DateSettings} */
-let settings = {
+let settings: DateSettings = {
 	l10n: {
 		locale: 'en',
 		months: [
@@ -139,9 +97,9 @@ let settings = {
 /**
  * Adds a locale to moment, using the format supplied by `wp_localize_script()`.
  *
- * @param {DateSettings} dateSettings Settings, including locale data.
+ * @param dateSettings Settings, including locale data.
  */
-export function setSettings( dateSettings ) {
+export function setSettings( dateSettings: DateSettings ) {
 	settings = dateSettings;
 
 	setupWPTimezone();
@@ -259,31 +217,25 @@ function setupWPTimezone() {
 // Date constants.
 /**
  * Number of seconds in one minute.
- *
- * @type {number}
  */
 const MINUTE_IN_SECONDS = 60;
 /**
  * Number of minutes in one hour.
- *
- * @type {number}
  */
 const HOUR_IN_MINUTES = 60;
 /**
  * Number of seconds in one hour.
- *
- * @type {number}
  */
 const HOUR_IN_SECONDS = 60 * MINUTE_IN_SECONDS;
 
 /**
  * Map of PHP formats to Moment.js formats.
  *
- * These are used internally by {@link wp.date.format}, and are either
+ * These are used internally by {@link format}, and are either
  * a string representing the corresponding Moment.js format code, or a
  * function which returns the formatted string.
  *
- * This should only be used through {@link wp.date.format}, not
+ * This should only be used through {@link format}, not
  * directly.
  */
 const formatMap = {
@@ -297,11 +249,11 @@ const formatMap = {
 	/**
 	 * Gets the ordinal suffix.
 	 *
-	 * @param {Moment} momentDate Moment instance.
+	 * @param momentDate Moment instance.
 	 *
-	 * @return {string} Formatted date.
+	 * @return Formatted date.
 	 */
-	S( momentDate ) {
+	S( momentDate: Moment ) {
 		// Do - D.
 		const num = momentDate.format( 'D' );
 		const withOrdinal = momentDate.format( 'Do' );
@@ -312,11 +264,11 @@ const formatMap = {
 	/**
 	 * Gets the day of the year (zero-indexed).
 	 *
-	 * @param {Moment} momentDate Moment instance.
+	 * @param momentDate Moment instance.
 	 *
-	 * @return {string} Formatted date.
+	 * @return Formatted date.
 	 */
-	z( momentDate ) {
+	z( momentDate: Moment ) {
 		// DDD - 1.
 		return ( parseInt( momentDate.format( 'DDD' ), 10 ) - 1 ).toString();
 	},
@@ -332,11 +284,11 @@ const formatMap = {
 	/**
 	 * Gets the days in the month.
 	 *
-	 * @param {Moment} momentDate Moment instance.
+	 * @param momentDate Moment instance.
 	 *
-	 * @return {number} Formatted date.
+	 * @return Formatted date.
 	 */
-	t( momentDate ) {
+	t( momentDate: Moment ) {
 		return momentDate.daysInMonth();
 	},
 
@@ -344,11 +296,11 @@ const formatMap = {
 	/**
 	 * Gets whether the current year is a leap year.
 	 *
-	 * @param {Moment} momentDate Moment instance.
+	 * @param momentDate Moment instance.
 	 *
-	 * @return {string} Formatted date.
+	 * @return Formatted date.
 	 */
-	L( momentDate ) {
+	L( momentDate: Moment ) {
 		return momentDate.isLeapYear() ? '1' : '0';
 	},
 	o: 'GGGG',
@@ -361,11 +313,11 @@ const formatMap = {
 	/**
 	 * Gets the current time in Swatch Internet Time (.beats).
 	 *
-	 * @param {Moment} momentDate Moment instance.
+	 * @param momentDate Moment instance.
 	 *
-	 * @return {number} Formatted date.
+	 * @return Formatted date.
 	 */
-	B( momentDate ) {
+	B( momentDate: Moment ) {
 		const timezoned = momentLib( momentDate ).utcOffset( 60 );
 		const seconds = parseInt( timezoned.format( 's' ), 10 ),
 			minutes = parseInt( timezoned.format( 'm' ), 10 ),
@@ -393,11 +345,11 @@ const formatMap = {
 	/**
 	 * Gets whether the timezone is in DST currently.
 	 *
-	 * @param {Moment} momentDate Moment instance.
+	 * @param momentDate Moment instance.
 	 *
-	 * @return {string} Formatted date.
+	 * @return Formatted date.
 	 */
-	I( momentDate ) {
+	I( momentDate: Moment ) {
 		return momentDate.isDST() ? '1' : '0';
 	},
 	O: 'ZZ',
@@ -406,11 +358,11 @@ const formatMap = {
 	/**
 	 * Gets the timezone offset in seconds.
 	 *
-	 * @param {Moment} momentDate Moment instance.
+	 * @param momentDate Moment instance.
 	 *
-	 * @return {number} Formatted date.
+	 * @return Formatted date.
 	 */
-	Z( momentDate ) {
+	Z( momentDate: Moment ) {
 		// Timezone offset in seconds.
 		const offset = momentDate.format( 'Z' );
 		const sign = offset[ 0 ] === '-' ? -1 : 1;
@@ -429,11 +381,11 @@ const formatMap = {
 	/**
 	 * Formats the date as RFC2822.
 	 *
-	 * @param {Moment} momentDate Moment instance.
+	 * @param momentDate Moment instance.
 	 *
-	 * @return {string} Formatted date.
+	 * @return Formatted date.
 	 */
-	r( momentDate ) {
+	r( momentDate: Moment ) {
 		return momentDate
 			.locale( 'en' )
 			.format( 'ddd, DD MMM YYYY HH:mm:ss ZZ' );
@@ -444,14 +396,17 @@ const formatMap = {
 /**
  * Formats a date. Does not alter the date's timezone.
  *
- * @param {string}                             dateFormat PHP-style formatting string.
- *                                                        See [php.net/date](https://www.php.net/manual/en/function.date.php).
- * @param {Moment | Date | string | undefined} dateValue  Date object or string,
- *                                                        parsable by moment.js.
+ * @param dateFormat PHP-style formatting string.
+ *                   See [php.net/date](https://www.php.net/manual/en/function.date.php).
+ * @param dateValue  Date object or string,
+ *                   parsable by moment.js.
  *
- * @return {string} Formatted date.
+ * @return Formatted date.
  */
-export function format( dateFormat, dateValue = new Date() ) {
+export function format(
+	dateFormat: string,
+	dateValue: Moment | Date | string | number = new Date()
+) {
 	let i, char;
 	const newFormat = [];
 	const momentDate = momentLib( dateValue );
@@ -465,8 +420,7 @@ export function format( dateFormat, dateValue = new Date() ) {
 			continue;
 		}
 		if ( char in formatMap ) {
-			const formatter =
-				formatMap[ /** @type {keyof formatMap} */ ( char ) ];
+			const formatter = formatMap[ char as keyof typeof formatMap ];
 			if ( typeof formatter !== 'string' ) {
 				// If the format is a function, call it.
 				newFormat.push( '[' + formatter( momentDate ) + ']' );
@@ -486,20 +440,24 @@ export function format( dateFormat, dateValue = new Date() ) {
 /**
  * Formats a date (like `date()` in PHP).
  *
- * @param {string}                             dateFormat PHP-style formatting string.
- *                                                        See [php.net/date](https://www.php.net/manual/en/function.date.php).
- * @param {Moment | Date | string | undefined} dateValue  Date object or string, parsable
- *                                                        by moment.js.
- * @param {string | number | undefined}        timezone   Timezone to output result in or a
- *                                                        UTC offset. Defaults to timezone from
- *                                                        site.
+ * @param  dateFormat PHP-style formatting string.
+ *                    See [php.net/date](https://www.php.net/manual/en/function.date.php).
+ * @param  dateValue  Date object or string, parsable
+ *                    by moment.js.
+ * @param  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 {string} Formatted date in English.
  */
-export function date( dateFormat, dateValue = new Date(), timezone ) {
+export function date(
+	dateFormat: string,
+	dateValue: Moment | Date | string | number = new Date(),
+	timezone?: string
+) {
 	const dateMoment = buildMoment( dateValue, timezone );
 	return format( dateFormat, dateMoment );
 }
@@ -507,14 +465,17 @@ export function date( dateFormat, dateValue = new Date(), timezone ) {
 /**
  * Formats a date (like `date()` in PHP), in the UTC timezone.
  *
- * @param {string}                             dateFormat PHP-style formatting string.
- *                                                        See [php.net/date](https://www.php.net/manual/en/function.date.php).
- * @param {Moment | Date | string | undefined} dateValue  Date object or string,
- *                                                        parsable by moment.js.
+ * @param dateFormat PHP-style formatting string.
+ *                   See [php.net/date](https://www.php.net/manual/en/function.date.php).
+ * @param dateValue  Date object or string,
+ *                   parsable by moment.js.
  *
- * @return {string} Formatted date in English.
+ * @return Formatted date in English.
  */
-export function gmdate( dateFormat, dateValue = new Date() ) {
+export function gmdate(
+	dateFormat: string,
+	dateValue: Moment | Date | string | number = new Date()
+) {
 	const dateMoment = momentLib( dateValue ).utc();
 	return format( dateFormat, dateMoment );
 }
@@ -525,22 +486,26 @@ export function gmdate( dateFormat, dateValue = new Date() ) {
  * 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](https://www.php.net/manual/en/function.date.php).
- * @param {Moment | Date | string | undefined}     dateValue  Date object or string, parsable by
- *                                                            moment.js.
- * @param {string | number | boolean | undefined=} 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.
+ * @param dateFormat PHP-style formatting string.
+ *                   See [php.net/date](https://www.php.net/manual/en/function.date.php).
+ * @param dateValue  Date object or string, parsable by
+ *                   moment.js.
+ * @param 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.
+ * @return  Formatted date.
  */
-export function dateI18n( dateFormat, dateValue = new Date(), timezone ) {
+export function dateI18n(
+	dateFormat: string,
+	dateValue: Moment | Date | string | number = new Date(),
+	timezone?: string | number | boolean
+) {
 	if ( true === timezone ) {
 		return gmdateI18n( dateFormat, dateValue );
 	}
@@ -558,14 +523,17 @@ export function dateI18n( dateFormat, dateValue = new Date(), timezone ) {
  * 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](https://www.php.net/manual/en/function.date.php).
- * @param {Moment | Date | string | undefined} dateValue  Date object or string,
- *                                                        parsable by moment.js.
+ * @param dateFormat PHP-style formatting string.
+ *                   See [php.net/date](https://www.php.net/manual/en/function.date.php).
+ * @param dateValue  Date object or string,
+ *                   parsable by moment.js.
  *
- * @return {string} Formatted date.
+ * @return Formatted date.
  */
-export function gmdateI18n( dateFormat, dateValue = new Date() ) {
+export function gmdateI18n(
+	dateFormat: string,
+	dateValue: Moment | Date | string | number = new Date()
+) {
 	const dateMoment = momentLib( dateValue ).utc();
 	dateMoment.locale( settings.l10n.locale );
 	return format( dateFormat, dateMoment );
@@ -574,11 +542,11 @@ export function gmdateI18n( dateFormat, dateValue = new Date() ) {
 /**
  * Check whether a date is considered in the future according to the WordPress settings.
  *
- * @param {string} dateValue Date String or Date object in the Defined WP Timezone.
+ * @param dateValue Date String or Date object in the Defined WP Timezone.
  *
- * @return {boolean} Is in the future.
+ * @return Is in the future.
  */
-export function isInTheFuture( dateValue ) {
+export function isInTheFuture( dateValue: Date | string | number ) {
 	const now = momentLib.tz( WP_ZONE );
 	const momentObject = momentLib.tz( dateValue, WP_ZONE );
 
@@ -588,11 +556,11 @@ export function isInTheFuture( dateValue ) {
 /**
  * Create and return a JavaScript Date Object from a date string in the WP timezone.
  *
- * @param {?string} dateString Date formatted in the WP timezone.
+ * @param dateString Date formatted in the WP timezone.
  *
- * @return {Date} Date
+ * @return  Date
  */
-export function getDate( dateString ) {
+export function getDate( dateString?: string | null ) {
 	if ( ! dateString ) {
 		return momentLib.tz( WP_ZONE ).toDate();
 	}
@@ -603,12 +571,15 @@ export function getDate( dateString ) {
 /**
  * Returns a human-readable time difference between two dates, like human_time_diff() in PHP.
  *
- * @param {Moment | Date | string}             from From date, in the WP timezone.
- * @param {Moment | Date | string | undefined} to   To date, formatted in the WP timezone.
+ * @param from From date, in the WP timezone.
+ * @param to   To date, formatted in the WP timezone.
  *
- * @return {string} Human-readable time difference.
+ * @return Human-readable time difference.
  */
-export function humanTimeDiff( from, to ) {
+export function humanTimeDiff(
+	from: Moment | Date | string | number,
+	to?: Moment | Date | string | number
+) {
 	const fromMoment = momentLib.tz( from, WP_ZONE );
 	const toMoment = to ? momentLib.tz( to, WP_ZONE ) : momentLib.tz( WP_ZONE );
 	return fromMoment.from( toMoment );
@@ -617,23 +588,26 @@ export function humanTimeDiff( from, to ) {
 /**
  * Creates a moment instance using the given timezone or, if none is provided, using global settings.
  *
- * @param {Moment | Date | string | undefined} dateValue Date object or string, parsable
- *                                                       by moment.js.
- * @param {string | number | undefined}        timezone  Timezone to output result in or a
- *                                                       UTC offset. Defaults to timezone from
- *                                                       site.
+ * @param dateValue Date object or string, parsable
+ *                  by moment.js.
+ * @param 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.
+ * @return A moment instance.
  */
-function buildMoment( dateValue, timezone = '' ) {
+function buildMoment(
+	dateValue?: Moment | Date | string | number,
+	timezone: string | number = ''
+) {
 	const dateMoment = momentLib( dateValue );
 
 	if ( timezone && ! isUTCOffset( timezone ) ) {
 		// The ! isUTCOffset() check guarantees that timezone is a string.
-		return dateMoment.tz( /** @type {string} */ ( timezone ) );
+		return dateMoment.tz( timezone as string );
 	}
 
 	if ( timezone && isUTCOffset( timezone ) ) {
@@ -650,11 +624,11 @@ function buildMoment( dateValue, timezone = '' ) {
 /**
  * Returns whether a certain UTC offset is valid or not.
  *
- * @param {number|string} offset a UTC offset.
+ * @param offset a UTC offset.
  *
- * @return {boolean} whether a certain UTC offset is valid or not.
+ * @return  whether a certain UTC offset is valid or not.
  */
-function isUTCOffset( offset ) {
+function isUTCOffset( offset: number | string ) {
 	if ( 'number' === typeof offset ) {
 		return true;
 	}

package/src/types.ts

@@ -0,0 +1,138 @@
+/**
+ * External dependencies
+ */
+import type { LocaleSpecification as MomentLocaleSpecification } from 'moment';
+
+export type MeridiemConfig = {
+	/**
+	 * Lowercase AM.
+	 */
+	am: string;
+
+	/**
+	 * Uppercase AM.
+	 */
+	AM: string;
+
+	/**
+	 * Lowercase PM.
+	 */
+	pm: string;
+
+	/**
+	 * Uppercase PM.
+	 */
+	PM: string;
+};
+
+export type FormatsConfig = {
+	/**
+	 * Time format.
+	 */
+	time: string;
+
+	/**
+	 * Date format.
+	 */
+	date: string;
+
+	/**
+	 * Datetime format.
+	 */
+	datetime: string;
+
+	/**
+	 * Abbreviated datetime format.
+	 */
+	datetimeAbbreviated: string;
+};
+
+export type TimezoneConfig = {
+	/**
+	 * Offset setting.
+	 */
+	offset: string;
+
+	/**
+	 * Offset setting with decimals formatted to minutes.
+	 */
+	offsetFormatted: string;
+
+	/**
+	 * The timezone as a string (e.g., `'America/Los_Angeles'`).
+	 */
+	string: string;
+
+	/**
+	 * Abbreviation for the timezone.
+	 */
+	abbr: string;
+};
+
+export type L10nSettings = {
+	/**
+	 * Moment locale.
+	 */
+	locale: string;
+
+	/**
+	 * Locale months.
+	 *
+	 * @example
+	 * ['January', 'February', ... ]
+	 */
+	months: MomentLocaleSpecification[ 'months' ];
+
+	/**
+	 * Locale months short.
+	 *
+	 * @example
+	 * ['Jan', 'Feb', ... ]
+	 */
+	monthsShort: MomentLocaleSpecification[ 'monthsShort' ];
+
+	/**
+	 * Locale weekdays.
+	 *
+	 * @example
+	 * ['Sunday', 'Monday', ... ]
+	 */
+	weekdays: MomentLocaleSpecification[ 'weekdays' ];
+
+	/**
+	 * Locale weekdays short.
+	 */
+	weekdaysShort: MomentLocaleSpecification[ 'weekdaysShort' ];
+
+	/**
+	 * Meridiem config.
+	 */
+	meridiem: MeridiemConfig;
+
+	/**
+	 * Relative time config.
+	 */
+	relative: MomentLocaleSpecification[ 'relativeTime' ];
+
+	/**
+	 * Day that the week starts on.
+	 */
+	startOfWeek: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+};
+
+export type DateSettings = {
+	/**
+	 * Localization settings.
+	 */
+	l10n: L10nSettings;
+
+	/**
+	 * Date/time formats config.
+	 */
+	formats: FormatsConfig;
+
+	/**
+	 * Timezone settings.
+	 */
+	timezone: TimezoneConfig;
+};