|
1 | 1 | /** |
2 | | - * Handles uncaught exceptions thrown in AngularTS expressions. |
| 2 | + * Unified exception handler used throughout AngularTS. |
3 | 3 | * |
4 | | - * By default, this service delegates to `$log.error()`, logging the exception to the browser console. |
5 | | - * You can override this behavior to provide custom exception handling—such as reporting errors |
6 | | - * to a backend server, or altering the log level used. |
| 4 | + * This service receives uncaught exceptions from both synchronous and asynchronous operations. |
| 5 | + * Its purpose is to provide a central point through which the framework |
| 6 | + * surfaces errors. |
7 | 7 | * |
8 | | - * ## Default Behavior |
| 8 | + * By default, `$exceptionHandler` simply rethrows the exception. This ensures fail-fast |
| 9 | + * behavior, making errors visible immediately in development and in unit tests. |
| 10 | + * Applications may override this service to introduce custom error handling. |
9 | 11 | * |
10 | | - * Uncaught exceptions within AngularTS expressions are intercepted and passed to this service. |
11 | | - * The default implementation logs the error using `$log.error(exception, cause)`. |
12 | | - * |
13 | | - * ## Custom Implementation |
14 | | - * |
15 | | - * You can override the default `$exceptionHandler` by providing your own factory. This allows you to: |
16 | | - * - Log errors to a remote server |
17 | | - * - Change the log level (e.g., from `error` to `warn`) |
18 | | - * - Trigger custom error-handling workflows |
19 | | - * |
20 | | - * ### Example: Overriding `$exceptionHandler` |
| 12 | + * ### Example: Custom `$exceptionHandler` |
21 | 13 | * |
22 | 14 | * ```js |
23 | 15 | * angular |
24 | | - * .module('exceptionOverwrite', []) |
25 | | - * .factory('$exceptionHandler', ['$log', 'logErrorsToBackend', function($log, logErrorsToBackend) { |
26 | | - * return function myExceptionHandler(exception, cause) { |
27 | | - * logErrorsToBackend(exception, cause); |
28 | | - * $log.warn(exception, cause); // Use warn instead of error |
| 16 | + * .module('app') |
| 17 | + * .factory('$exceptionHandler', function(myLogger) { |
| 18 | + * return function handleError(error) { |
| 19 | + * myLogger.capture(error); |
| 20 | + * // Rethrow to preserve fail-fast behavior: |
| 21 | + * throw error; |
29 | 22 | * }; |
30 | | - * }]); |
| 23 | + * }); |
31 | 24 | * ``` |
32 | | - * - You may also manually invoke the exception handler: |
| 25 | + * |
| 26 | + * IMPORTANT: custom implementation should always rethrow the error as the framework assumes that `$exceptionHandler` always does the throwing. |
| 27 | + * |
| 28 | + * ### Manual Invocation |
| 29 | + * |
| 30 | + * You can invoke the exception handler directly when catching errors in your own code: |
33 | 31 | * |
34 | 32 | * ```js |
35 | 33 | * try { |
36 | | - * // Some code that might throw |
37 | | - * } catch (e) { |
38 | | - * $exceptionHandler(e, 'optional context'); |
| 34 | + * riskyOperation(); |
| 35 | + * } catch (err) { |
| 36 | + * $exceptionHandler(err); |
39 | 37 | * } |
40 | 38 | * ``` |
41 | 39 | * |
42 | 40 | * @see {@link angular.ErrorHandler AngularTS ErrorHandler} |
43 | 41 | */ |
44 | | -/** @typedef {import('../log/interface.ts').LogService} LogService */ |
45 | | -/** @typedef {import("./interface.ts").ErrorHandler} ErrorHandler */ |
46 | 42 | /** |
47 | | - * Provider for `$exceptionHandler` service. Delegates uncaught exceptions to `$log.error()` by default. |
48 | | - * Can be overridden to implement custom error-handling logic. |
| 43 | + * Provider for the `$exceptionHandler` service. |
| 44 | + * |
| 45 | + * The default implementation rethrows exceptions, enabling strict fail-fast behavior. |
| 46 | + * Applications may replace the handler via by setting `errorHandler`property or by providing their own |
| 47 | + * `$exceptionHandler` factory. |
49 | 48 | */ |
50 | 49 | export class ExceptionHandlerProvider { |
51 | | - /** @type {LogService} */ |
52 | | - log: LogService; |
53 | | - /** @type {ErrorHandler} */ |
54 | | - errorHandler: ErrorHandler; |
55 | | - $get: (string | (($log: LogService) => ErrorHandler))[]; |
| 50 | + /** @type {ng.ExceptionHandlerService} */ |
| 51 | + errorHandler: ng.ExceptionHandlerService; |
| 52 | + /** |
| 53 | + * @returns {ng.ExceptionHandlerService} |
| 54 | + */ |
| 55 | + $get(): ng.ExceptionHandlerService; |
56 | 56 | } |
57 | | -export type LogService = import("../log/interface.ts").LogService; |
58 | | -export type ErrorHandler = import("./interface.ts").ErrorHandler; |
0 commit comments