diff -r 3d4e9c994f10 -r a86126ab1dd4 wp/wp-includes/js/heartbeat.js --- a/wp/wp-includes/js/heartbeat.js Tue Oct 22 16:11:46 2019 +0200 +++ b/wp/wp-includes/js/heartbeat.js Tue Dec 15 13:49:49 2020 +0100 @@ -34,7 +34,7 @@ * * @since 3.6.0 * - * @returns {Object} An instance of the Heartbeat class. + * @return {Object} An instance of the Heartbeat class. * @constructor */ var Heartbeat = function() { @@ -62,13 +62,13 @@ // Connect interval (in seconds). mainInterval: 60, - // Used when the interval is set to 5 sec. temporarily. + // Used when the interval is set to 5 seconds temporarily. tempInterval: 0, // Used when the interval is reset. originalInterval: 0, - // Used to limit the number of AJAX requests. + // Used to limit the number of Ajax requests. minimalInterval: 0, // Used together with tempInterval. @@ -89,7 +89,7 @@ // Whether the current browser window is in focus and the user is active. hasFocus: true, - // Timestamp, last time the user was active. Checked every 30 sec. + // Timestamp, last time the user was active. Checked every 30 seconds. userActivity: 0, // Flag whether events tracking user activity were set. @@ -106,11 +106,10 @@ /** * Sets local variables and events, then starts the heartbeat. * + * @since 3.8.0 * @access private * - * @since 3.8.0 - * - * @returns {void} + * @return {void} */ function initialize() { var options, hidden, visibilityState, visibilitychange; @@ -133,9 +132,8 @@ } /* - * The interval can be from 15 to 120 sec. and can be set temporarily to 5 sec. - * It can be set in the initial options or changed later through JS and/or - * through PHP. + * The interval can be from 15 to 120 seconds and can be set temporarily to 5 seconds. + * It can be set in the initial options or changed later through JS and/or through PHP. */ if ( options.interval ) { settings.mainInterval = options.interval; @@ -148,12 +146,12 @@ } /* - * Used to limit the number of AJAX requests. Overrides all other intervals if - * they are shorter. Needed for some hosts that cannot handle frequent requests - * and the user may exceed the allocated server CPU time, etc. The minimal - * interval can be up to 600 sec. however setting it to longer than 120 sec. - * will limit or disable some of the functionality (like post locks). Once set - * at initialization, minimalInterval cannot be changed/overridden. + * Used to limit the number of Ajax requests. Overrides all other intervals + * if they are shorter. Needed for some hosts that cannot handle frequent requests + * and the user may exceed the allocated server CPU time, etc. The minimal interval + * can be up to 600 seconds, however setting it to longer than 120 seconds + * will limit or disable some of the functionality (like post locks). + * Once set at initialization, minimalInterval cannot be changed/overridden. */ if ( options.minimalInterval ) { options.minimalInterval = parseInt( options.minimalInterval, 10 ); @@ -189,11 +187,11 @@ hidden = 'hidden'; visibilitychange = 'visibilitychange'; visibilityState = 'visibilityState'; - } else if ( typeof document.msHidden !== 'undefined' ) { // IE10 + } else if ( typeof document.msHidden !== 'undefined' ) { // IE10. hidden = 'msHidden'; visibilitychange = 'msvisibilitychange'; visibilityState = 'msVisibilityState'; - } else if ( typeof document.webkitHidden !== 'undefined' ) { // Android + } else if ( typeof document.webkitHidden !== 'undefined' ) { // Android. hidden = 'webkitHidden'; visibilitychange = 'webkitvisibilitychange'; visibilityState = 'webkitVisibilityState'; @@ -245,11 +243,10 @@ /** * Returns the current time according to the browser. * + * @since 3.6.0 * @access private * - * @since 3.6.0 - * - * @returns {number} Returns the current time. + * @return {number} Returns the current time. */ function time() { return (new Date()).getTime(); @@ -258,11 +255,10 @@ /** * Checks if the iframe is from the same origin. * + * @since 3.6.0 * @access private * - * @since 3.6.0 - * - * @returns {boolean} Returns whether or not the iframe is from the same origin. + * @return {boolean} Returns whether or not the iframe is from the same origin. */ function isLocalFrame( frame ) { var origin, src = frame.src; @@ -291,11 +287,10 @@ /** * Checks if the document's focus has changed. * + * @since 4.1.0 * @access private * - * @since 4.1.0 - * - * @returns {void} + * @return {void} */ function checkFocus() { if ( settings.hasFocus && ! document.hasFocus() ) { @@ -308,15 +303,14 @@ /** * Sets error state and fires an event on XHR errors or timeout. * + * @since 3.8.0 * @access private * - * @since 3.8.0 - * * @param {string} error The error type passed from the XHR. * @param {number} status The HTTP status code passed from jqXHR * (200, 404, 500, etc.). * - * @returns {void} + * @return {void} */ function setErrorState( error, status ) { var trigger; @@ -327,7 +321,7 @@ // Do nothing. break; case 'timeout': - // No response for 30 sec. + // No response for 30 seconds. trigger = true; break; case 'error': @@ -359,11 +353,10 @@ /** * Clears the error state and fires an event if there is a connection error. * + * @since 3.8.0 * @access private * - * @since 3.8.0 - * - * @returns {void} + * @return {void} */ function clearErrorState() { // Has connected successfully. @@ -380,11 +373,10 @@ /** * Gathers the data and connects to the server. * + * @since 3.6.0 * @access private * - * @since 3.6.0 - * - * @returns {void} + * @return {void} */ function connect() { var ajaxData, heartbeatData; @@ -421,7 +413,7 @@ settings.xhr = $.ajax({ url: settings.url, type: 'post', - timeout: 30000, // throw an error if not completed after 30 sec. + timeout: 30000, // Throw an error if not completed after 30 seconds. data: ajaxData, dataType: 'json' }).always( function() { @@ -442,7 +434,7 @@ wp.hooks.doAction( 'heartbeat.nonces-expired' ); } - // Change the interval from PHP + // Change the interval from PHP. if ( response.heartbeat_interval ) { newInterval = response.heartbeat_interval; delete response.heartbeat_interval; @@ -464,7 +456,7 @@ $document.trigger( 'heartbeat-tick', [response, textStatus, jqXHR] ); wp.hooks.doAction( 'heartbeat.tick', response, textStatus, jqXHR ); - // Do this last. Can trigger the next XHR if connection time > 5 sec. and newInterval == 'fast'. + // Do this last. Can trigger the next XHR if connection time > 5 seconds and newInterval == 'fast'. if ( newInterval ) { interval( newInterval ); } @@ -480,11 +472,10 @@ * * Fires immediately if the connection time is longer than the interval. * + * @since 3.8.0 * @access private * - * @since 3.8.0 - * - * @returns {void} + * @return {void} */ function scheduleNextTick() { var delta = time() - settings.lastTick, @@ -495,7 +486,7 @@ } if ( ! settings.hasFocus ) { - interval = 120000; // 120 sec. Post locks expire after 150 sec. + interval = 120000; // 120 seconds. Post locks expire after 150 seconds. } else if ( settings.countdown > 0 && settings.tempInterval ) { interval = settings.tempInterval; settings.countdown--; @@ -526,11 +517,10 @@ /** * Sets the internal state when the browser window becomes hidden or loses focus. * + * @since 3.6.0 * @access private * - * @since 3.6.0 - * - * @returns {void} + * @return {void} */ function blurred() { settings.hasFocus = false; @@ -539,16 +529,15 @@ /** * Sets the internal state when the browser window becomes visible or is in focus. * + * @since 3.6.0 * @access private * - * @since 3.6.0 - * - * @returns {void} + * @return {void} */ function focused() { settings.userActivity = time(); - // Resume if suspended + // Resume if suspended. settings.suspend = false; if ( ! settings.hasFocus ) { @@ -560,11 +549,10 @@ /** * Runs when the user becomes active after a period of inactivity. * + * @since 3.6.0 * @access private * - * @since 3.6.0 - * - * @returns {void} + * @return {void} */ function userIsActive() { settings.userActivityEvents = false; @@ -582,26 +570,25 @@ /** * Checks for user activity. * - * Runs every 30 sec. Sets 'hasFocus = true' if user is active and the window is - * in the background. Sets 'hasFocus = false' if the user has been inactive - * (no mouse or keyboard activity) for 5 min. even when the window has focus. + * Runs every 30 seconds. Sets 'hasFocus = true' if user is active and the window + * is in the background. Sets 'hasFocus = false' if the user has been inactive + * (no mouse or keyboard activity) for 5 minutes even when the window has focus. * + * @since 3.8.0 * @access private * - * @since 3.8.0 - * - * @returns {void} + * @return {void} */ function checkUserActivity() { var lastActive = settings.userActivity ? time() - settings.userActivity : 0; - // Throttle down when no mouse or keyboard activity for 5 min. + // Throttle down when no mouse or keyboard activity for 5 minutes. if ( lastActive > 300000 && settings.hasFocus ) { blurred(); } - // Suspend after 10 min. of inactivity when suspending is enabled. - // Always suspend after 60 min. of inactivity. This will release the post lock, etc. + // Suspend after 10 minutes of inactivity when suspending is enabled. + // Always suspend after 60 minutes of inactivity. This will release the post lock, etc. if ( ( settings.suspendEnabled && lastActive > 600000 ) || lastActive > 3600000 ) { settings.suspend = true; } @@ -632,7 +619,7 @@ * @since 3.6.0 * @memberOf wp.heartbeat.prototype * - * @returns {boolean} True if the window or the user is active. + * @return {boolean} True if the window or the user is active. */ function hasFocus() { return settings.hasFocus; @@ -645,7 +632,7 @@ * * @memberOf wp.heartbeat.prototype * - * @returns {boolean} True if a connection error was found. + * @return {boolean} True if a connection error was found. */ function hasConnectionError() { return settings.connectionError; @@ -661,7 +648,7 @@ * * @memberOf wp.heartbeat.prototype * - * @returns {void} + * @return {void} */ function connectNow() { settings.lastTick = 0; @@ -672,15 +659,15 @@ * Disables suspending. * * Should be used only when Heartbeat is performing critical tasks like - * autosave, post-locking, etc. Using this on many screens may overload the - * user's hosting account if several browser windows/tabs are left open for a - * long time. + * autosave, post-locking, etc. Using this on many screens may overload + * the user's hosting account if several browser windows/tabs are left open + * for a long time. * * @since 3.8.0 * * @memberOf wp.heartbeat.prototype * - * @returns {void} + * @return {void} */ function disableSuspend() { settings.suspendEnabled = false; @@ -691,19 +678,19 @@ * * When setting to 'fast' or 5, the interval is 5 seconds for the next 30 ticks * (for 2 minutes and 30 seconds) by default. In this case the number of 'ticks' - * can be passed as second argument. If the window doesn't have focus, the - * interval slows down to 2 min. + * can be passed as second argument. If the window doesn't have focus, + * the interval slows down to 2 minutes. * * @since 3.6.0 * * @memberOf wp.heartbeat.prototype * - * @param {string|number} speed Interval: 'fast' or 5, 15, 30, 60, 120. Fast - * equals 5. + * @param {string|number} speed Interval: 'fast' or 5, 15, 30, 60, 120. + * Fast equals 5. * @param {string} ticks Tells how many ticks before the interval reverts * back. Used with speed = 'fast' or 5. * - * @returns {number} Current interval in seconds. + * @return {number} Current interval in seconds. */ function interval( speed, ticks ) { var newInterval, @@ -728,7 +715,7 @@ newInterval = 120000; break; case 'long-polling': - // Allow long polling, (experimental) + // Allow long polling (experimental). settings.mainInterval = 0; return 0; default: @@ -751,9 +738,11 @@ settings.mainInterval = newInterval; } - // Change the next connection time if new interval has been set. - // Will connect immediately if the time since the last connection - // is greater than the new interval. + /* + * Change the next connection time if new interval has been set. + * Will connect immediately if the time since the last connection + * is greater than the new interval. + */ if ( newInterval !== oldInterval ) { scheduleNextTick(); } @@ -784,7 +773,7 @@ * @param {*} data The data to send. * @param {boolean} noOverwrite Whether to overwrite existing data in the queue. * - * @returns {boolean} True if the data was queued. + * @return {boolean} True if the data was queued. */ function enqueue( handle, data, noOverwrite ) { if ( handle ) { @@ -805,7 +794,7 @@ * * @param {string} handle The handle for the data. * - * @returns {boolean} True if the data is queued with this handle. + * @return {boolean} True if the data is queued with this handle. */ function isQueued( handle ) { if ( handle ) { @@ -822,7 +811,7 @@ * * @param {string} handle The handle for the data. * - * @returns {void} + * @return {void} */ function dequeue( handle ) { if ( handle ) { @@ -839,7 +828,7 @@ * * @param {string} handle The handle for the data. * - * @returns {*} The data or undefined. + * @return {*} The data or undefined. */ function getQueuedItem( handle ) { if ( handle ) {