Skip to content

Commit e6e5371

Browse files
mgolmgol
committed
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
1 parent ebb139a commit e6e5371

4 files changed

+99
-0
lines changed

Diff for: ‎categories.xml

+6
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,12 @@
108108
<p>For more information, see the Release Notes/Changelog at <a href="https://blog.jquery.com/2020/04/10/jquery-3-5-0-released/">https://blog.jquery.com/2020/04/10/jquery-3-5-0-released/</a></p>
109109
]]></desc>
110110
</category>
111+
<category name="Deprecated 3.7" slug="deprecated-3.7">
112+
<desc><![CDATA[
113+
<p>All the aspects of the API that were deprecated in the corresponding version of jQuery.</p>
114+
<p>For more information, see the Release Notes/Changelog at <a href="https://blog.jquery.com/2023/05/11/jquery-3-7-0-released-staying-in-order/">https://blog.jquery.com/2023/05/11/jquery-3-7-0-released-staying-in-order/</a></p>
115+
]]></desc>
116+
</category>
111117
</category>
112118
<category name="Dimensions" slug="dimensions">
113119
<desc><![CDATA[These methods are used to get and set the CSS dimensions for the various properties.]]></desc>

Diff for: ‎entries/jQuery.Deferred.exceptionHook.xml

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
<?xml version="1.0"?>
2+
<entry type="method" name="jQuery.Deferred.exceptionHook" return="Error">
3+
<title>jQuery.Deferred.exceptionHook()</title>
4+
<signature>
5+
<added>3.0</added>
6+
</signature>
7+
<desc>Handle errors produced by Deferreds.</desc>
8+
<longdesc>
9+
<p>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 <code>SyntaxError</code> or <code>ReferenceError</code>.</p>
10+
<p>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 <a href="/jQuery.Deferred.getErrorHook/"><code>jQuery.Deferred.getErrorHook</code></a> is defined; see the docs for that API for more details.</p>
11+
<h3>Example</h3>
12+
<pre><code><![CDATA[
13+
// These usually indicate a programmer mistake during development,
14+
// warn about them ASAP rather than swallowing them by default.
15+
var rerrorNames = /^(Eval|Internal|Range|Reference|Syntax|Type|URI)Error$/;
16+
17+
// If `jQuery.Deferred.getErrorHook` is defined, `asyncError` is an error
18+
// captured before the async barrier to get the original error cause
19+
// which may otherwise be hidden.
20+
jQuery.Deferred.exceptionHook = function( error, asyncError ) {
21+
22+
if ( error && rerrorNames.test( error.name ) ) {
23+
MyLoggingLibrary.log(
24+
"jQuery.Deferred exception",
25+
error,
26+
asyncError
27+
);
28+
}
29+
};
30+
]]></code></pre>
31+
</longdesc>
32+
<category slug="deferred-object"/>
33+
<category slug="version/3.0"/>
34+
</entry>

Diff for: ‎entries/jQuery.Deferred.getErrorHook.xml

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
<?xml version="1.0"?>
2+
<entry type="method" name="jQuery.Deferred.getErrorHook" return="Error">
3+
<title>jQuery.Deferred.getErrorHook()</title>
4+
<signature>
5+
<added>3.7</added>
6+
</signature>
7+
<desc>Return an Error instance with a defined stack.</desc>
8+
<longdesc>
9+
<div class="warning">
10+
<p>Note: This API is not defined by default. It may be provided by the user and jQuery will then use it internally.</p>
11+
</div>
12+
<p>When <code>jQuery.Deferred.getErrorHook</code> is defined, it extends the <code>jQuery.Deferred</code> 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 <a href="https://github.com/dmethvin/jquery-deferred-reporter">jquery-deferred-reporter</a> plugin.</p>
13+
<pre><code>
14+
jQuery.Deferred.getErrorHook = function() {
15+
try {
16+
throw new Error( "Exception in jQuery.Deferred" );
17+
} catch ( err ) {
18+
return err;
19+
}
20+
};
21+
</code></pre>
22+
<p>When defined, an error returned by this API is passed to <a href="/jQuery.Deferred.exceptionHook/"><code>jQuery.Deferred.exceptionHook</code></a> as the second parameter.</p>
23+
<h4>Why does this API exist?</h4>
24+
<p>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., <code>myobject.missingFunction()</code>). As of version 3.0, <code>jQuery.Deferred</code> follows the Promise/A+ specification when you use the <code>.then</code> 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!</p>
25+
<p>The native <code>Promise</code> 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 <code>.done</code> or <code>.fail</code>, and because Promise is not implemented on all the platforms that jQuery supports.</p>
26+
</longdesc>
27+
<category slug="deferred-object"/>
28+
<category slug="version/3.7"/>
29+
</entry>

Diff for: ‎entries/jQuery.Deferred.getStackHook.xml

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
<?xml version="1.0"?>
2+
<entry type="method" name="jQuery.Deferred.getStackHook" return="Error" deprecated="3.7" removed="4.0">
3+
<title>jQuery.Deferred.getStackHook()</title>
4+
<signature>
5+
<added>3.0</added>
6+
</signature>
7+
<desc>Return an Error instance with a defined stack.</desc>
8+
<longdesc>
9+
<div class="warning">
10+
<p>Note: This API has been deprecated in jQuery 3.7; please use the <a href="/jQuery.Deferred.getErrorHook/"><code>jQuery.Deferred.getErrorHook</code></a> method instead.</p>
11+
</div>
12+
<div class="warning">
13+
<p>Note: This API is not defined by default. It may be provided by the user and jQuery will then use it internally.</p>
14+
</div>
15+
<p>See <a href="/jQuery.Deferred.getErrorHook/"><code>jQuery.Deferred.getErrorHook</code></a> for the context why this API was created. Initially, we advised users to assign to it a function returning an error stack:</p>
16+
<pre><code>
17+
jQuery.Deferred.getStackHook = function() {
18+
try {
19+
throw new Error( "Exception in jQuery.Deferred" );
20+
} catch ( err ) {
21+
return err.stack; // stack property returned here
22+
}
23+
};
24+
</code></pre>
25+
<p>However, when such a stack is then logged by jQuery from inside of <a href="/jQuery.Deferred.exceptionHook/"><code>jQuery.Deferred.exceptionHook</code></a>, 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.</p>
26+
</longdesc>
27+
<category slug="deferred-object"/>
28+
<category slug="version/3.0"/>
29+
<category slug="deprecated/deprecated-3.7"/>
30+
</entry>

0 commit comments

Comments
 (0)