Deferred: Rename `getStackHook` to `getErrorHook`

Rename `jQuery.Deferred.getStackHook` to `jQuery.Deferred.getErrorHook`
to indicate passing an error instance is usually a better choice - it
works with source maps while a raw stack generally does not.

In jQuery `3.7.0`, we'll keep both names, marking the old one as
deprecated. In jQuery `4.0.0` we'll just keep the new one. This
change implements the `4.0.0` version; PR gh-5212 implements
the `3.7.0` one.

Fixes gh-5201
Closes gh-5211
Ref gh-5212

3 files changed, 15 insertions, 12 deletions

diff --git a/src/deferred.js b/src/deferred.js
index dc4294726..0d77ac9d6 100644
--- a/src/deferred.js
+++ b/src/deferred.js
@@ -188,7 +188,7 @@ jQuery.extend( {
 
 											if ( jQuery.Deferred.exceptionHook ) {
 												jQuery.Deferred.exceptionHook( e,
-													process.stackTrace );
+													process.error );
 											}
 
 											// Support: Promises/A+ section 2.3.3.3.4.1
@@ -216,10 +216,10 @@ jQuery.extend( {
 								process();
 							} else {
 
-								// Call an optional hook to record the stack, in case of exception
+								// Call an optional hook to record the error, in case of exception
 								// since it's otherwise lost when execution goes async
-								if ( jQuery.Deferred.getStackHook ) {
-									process.stackTrace = jQuery.Deferred.getStackHook();
+								if ( jQuery.Deferred.getErrorHook ) {
+									process.error = jQuery.Deferred.getErrorHook();
 								}
 								window.setTimeout( process );
 							}
diff --git a/src/deferred/exceptionHook.js b/src/deferred/exceptionHook.js
index 0315b2ecb..a5e7b5d3c 100644
--- a/src/deferred/exceptionHook.js
+++ b/src/deferred/exceptionHook.js
@@ -6,13 +6,16 @@ import "../deferred.js";
 // warn about them ASAP rather than swallowing them by default.
 var rerrorNames = /^(Eval|Internal|Range|Reference|Syntax|Type|URI)Error$/;
 
-jQuery.Deferred.exceptionHook = function( error, stack ) {
+// If `jQuery.Deferred.getErrorHook` is defined, `asyncError` is an error
+// captured before the async barrier to get the original error cause
+// which may otherwise be hidden.
+jQuery.Deferred.exceptionHook = function( error, asyncError ) {
 
 	if ( error && rerrorNames.test( error.name ) ) {
 		window.console.warn(
 			"jQuery.Deferred exception",
 			error,
-			stack
+			asyncError
 		);
 	}
 };
diff --git a/test/unit/deferred.js b/test/unit/deferred.js
index 8a215ff99..2c791cd1c 100644
--- a/test/unit/deferred.js
+++ b/test/unit/deferred.js
@@ -602,7 +602,7 @@ QUnit.test( "jQuery.Deferred.exceptionHook", function( assert ) {
 	defer.resolve();
 } );
 
-QUnit.test( "jQuery.Deferred.exceptionHook with stack hooks", function( assert ) {
+QUnit.test( "jQuery.Deferred.exceptionHook with error hooks", function( assert ) {
 
 	assert.expect( 2 );
 
@@ -610,26 +610,26 @@ QUnit.test( "jQuery.Deferred.exceptionHook with stack hooks", function( assert )
 		defer = jQuery.Deferred(),
 		oldWarn = window.console.warn;
 
-	jQuery.Deferred.getStackHook = function() {
+	jQuery.Deferred.getErrorHook = function() {
 
 		// Default exceptionHook assumes the stack is in a form console.warn can log,
-		// but a custom getStackHook+exceptionHook pair could save a raw form and
+		// but a custom getErrorHook+exceptionHook pair could save a raw form and
 		// format it to a string only when an exception actually occurs.
 		// For the unit test we just ensure the plumbing works.
-		return "NO STACK FOR YOU";
+		return "NO ERROR FOR YOU";
 	};
 
 	window.console.warn = function() {
 		var msg = Array.prototype.join.call( arguments, " " );
 		assert.ok( /cough_up_hairball/.test( msg ), "Function mentioned: " + msg );
-		assert.ok( /NO STACK FOR YOU/.test( msg ), "Stack trace included: " + msg );
+		assert.ok( /NO ERROR FOR YOU/.test( msg ), "Error included: " + msg );
 	};
 
 	defer.then( function() {
 		jQuery.cough_up_hairball();
 	} ).then( null, function( ) {
 		window.console.warn = oldWarn;
-		delete jQuery.Deferred.getStackHook;
+		delete jQuery.Deferred.getErrorHook;
 		done();
 	} );