From e6e5371c76c20895af79d7d1ffbc39d5db6c04da Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Go=C5=82e=CC=A8biowski-Owczarek?= Date: Tue, 15 Apr 2025 12:53:54 +0200 Subject: [PATCH] All: Create pages for `jQuery.Deferred.{getErrorHook,exceptionHook}` Also, create a page for the now deprecated `jQuery.Deferred.getStackHook`. Fixes gh-1221 Fixes gh-1246 --- categories.xml | 6 ++++ entries/jQuery.Deferred.exceptionHook.xml | 34 +++++++++++++++++++++++ entries/jQuery.Deferred.getErrorHook.xml | 29 +++++++++++++++++++ entries/jQuery.Deferred.getStackHook.xml | 30 ++++++++++++++++++++ 4 files changed, 99 insertions(+) create mode 100644 entries/jQuery.Deferred.exceptionHook.xml create mode 100644 entries/jQuery.Deferred.getErrorHook.xml create mode 100644 entries/jQuery.Deferred.getStackHook.xml diff --git a/categories.xml b/categories.xml index 8dc523ec..0f7d4df1 100644 --- a/categories.xml +++ b/categories.xml @@ -108,6 +108,12 @@

For more information, see the Release Notes/Changelog at https://blog.jquery.com/2020/04/10/jquery-3-5-0-released/

]]> + + All the aspects of the API that were deprecated in the corresponding version of jQuery.

+

For more information, see the Release Notes/Changelog at https://blog.jquery.com/2023/05/11/jquery-3-7-0-released-staying-in-order/

+ ]]> + diff --git a/entries/jQuery.Deferred.exceptionHook.xml b/entries/jQuery.Deferred.exceptionHook.xml new file mode 100644 index 00000000..30c1ae5f --- /dev/null +++ b/entries/jQuery.Deferred.exceptionHook.xml @@ -0,0 +1,34 @@ + + + jQuery.Deferred.exceptionHook() + + 3.0 + + Handle errors produced by Deferreds. + +

This API is called every time an error is thrown inside Deferreds. By default, it only warns about errors that are more likely to be programmer errors than errors thrown due to application logic. This includes errors like SyntaxError or ReferenceError.

+

If you want, you can redefine the API to handle errors the way you like. The function accepts two parameters - the first one is an error thrown and the second, optional one is a "fake" error created before the handler is called so that a stack trace from before an async barrier is available. This second error is only provided if jQuery.Deferred.getErrorHook is defined; see the docs for that API for more details.

+

Example

+
+ + + + diff --git a/entries/jQuery.Deferred.getErrorHook.xml b/entries/jQuery.Deferred.getErrorHook.xml new file mode 100644 index 00000000..c68189df --- /dev/null +++ b/entries/jQuery.Deferred.getErrorHook.xml @@ -0,0 +1,29 @@ + + + jQuery.Deferred.getErrorHook() + + 3.7 + + Return an Error instance with a defined stack. + +
+

Note: This API is not defined by default. It may be provided by the user and jQuery will then use it internally.

+
+

When jQuery.Deferred.getErrorHook is defined, it extends the jQuery.Deferred features added in jQuery 3.0 to include an error captured before the async barrier whenever a Deferred throws an exception. This makes it easier to find programming errors that occur inside Deferreds. You can find an example implementation you can copy-paste below, or you can use jquery-deferred-reporter plugin.

+ 

+jQuery.Deferred.getErrorHook = function() {
+  try {
+    throw new Error( "Exception in jQuery.Deferred" );
+  } catch ( err ) {
+    return err;
+  }
+};
+
+

When defined, an error returned by this API is passed to jQuery.Deferred.exceptionHook as the second parameter.

+

Why does this API exist?

+

Prior to jQuery 3.0, Deferreds would simply terminate and the browser would generate a message on the console if an exception occurred such as attempting to call an undefined method as a function (e.g., myobject.missingFunction()). As of version 3.0, jQuery.Deferred follows the Promise/A+ specification when you use the .then method. The spec requires all errors to be trapped by the Promise, which prevents console errors from being logged. If the user has forgotten to add a handler for rejected promises, this can result in the error being silently swallowed with no notification at all!

+

The native Promise object as implemented in the browser tracks Promise rejections and reports problems on the console. However, doing the same type of reporting in the JavaScript world is much more difficult. jQuery itself is unable to use the native Promise because jQuery.Deferred implements a superset of Promise that requires additional features for methods like .done or .fail, and because Promise is not implemented on all the platforms that jQuery supports.

+ + + + diff --git a/entries/jQuery.Deferred.getStackHook.xml b/entries/jQuery.Deferred.getStackHook.xml new file mode 100644 index 00000000..e4044da8 --- /dev/null +++ b/entries/jQuery.Deferred.getStackHook.xml @@ -0,0 +1,30 @@ + + + jQuery.Deferred.getStackHook() + + 3.0 + + Return an Error instance with a defined stack. + +
+

Note: This API has been deprecated in jQuery 3.7; please use the jQuery.Deferred.getErrorHook method instead.

+
+
+

Note: This API is not defined by default. It may be provided by the user and jQuery will then use it internally.

+
+

See jQuery.Deferred.getErrorHook for the context why this API was created. Initially, we advised users to assign to it a function returning an error stack:

+ 

+jQuery.Deferred.getStackHook = function() {
+  try {
+    throw new Error( "Exception in jQuery.Deferred" );
+  } catch ( err ) {
+    return err.stack; // stack property returned here
+  }
+};
+
+

However, when such a stack is then logged by jQuery from inside of jQuery.Deferred.exceptionHook, the browser won't apply source maps. Therefore, we changed the recommendation to return the full error object itself. To make it clearer, the API was also renamed.

+ + + + +