Custom exception handler service cookbook.

This cookbook demonstrates how to override the core `ExceptionHandler` class
with a custom service class that both logs to the console as well as sending
errors to a robust error-logginer service. This error-logging service can,
in turn, send errors to the server; or, to Software-as-a-Service (SaaS)
products like New Relic, TrackJS, and Raygun.

Author: bennadel

public/docs/_examples/cb-exception-handler/e2e-spec.ts

@@ -0,0 +1,10 @@
+/// <reference path='../_protractor/e2e.d.ts' />
+'use strict';
+// gulp run-e2e-tests --filter=cb-exception-handler
+describe('Handle exceptions', function() {
+
+  beforeAll(function () {
+      browser.get('');
+  });
+
+});

public/docs/_examples/cb-exception-handler/ts/app/app.component.ts

@@ -0,0 +1,24 @@
+// #docplaster
+// #docregion
+import { Component } from '@angular/core';
+
+// #docregion component
+@Component({
+  selector: 'my-app',
+  template:
+  `
+    <p>
+      <a (click)="throwError()">Throw an Error</a> <em>(and watch console)</em>.
+    </p>
+  `
+})
+// #docregion class
+export class AppComponent {
+  constructor() {}
+
+  public throwError() {
+    throw(new Error('No Disassemble!'));
+  }
+}
+// #enddocregion class
+// #enddocregion component

public/docs/_examples/cb-exception-handler/ts/app/app.module.ts

@@ -0,0 +1,28 @@
+// #docregion
+import { BrowserModule } from '@angular/platform-browser';
+import { ExceptionHandler } from '@angular/core';
+import { NgModule } from '@angular/core';
+
+import { AppComponent } from './app.component';
+import { CustomExceptionHandler } from './custom-exception-handler';
+import { ErrorLoggingService } from './error-logging.service';
+
+// #docregion module
+@NgModule({
+  imports: [ BrowserModule ],
+  providers: [
+    ErrorLoggingService,
+
+    // In order to override the default ExceptionHandler service, we have to provide our
+    // custom implementation as part of the application module - if we try to do this 
+    // later on, in the App component, it will be too late.
+    {
+      provide: ExceptionHandler,
+      useClass: CustomExceptionHandler
+    }
+  ],
+  declarations: [ AppComponent ],
+  bootstrap: [ AppComponent ]
+})
+export class AppModule { }
+// #enddocregion module

public/docs/_examples/cb-exception-handler/ts/app/custom-exception-handler.ts

@@ -0,0 +1,55 @@
+// #docregion
+import { ExceptionHandler } from '@angular/core';
+import { Injectable } from '@angular/core';
+
+import { ErrorLoggingService } from './error-logging.service';
+
+// #docregion class
+@Injectable()
+export class CustomExceptionHandler {
+  private errorLogggingService: ErrorLoggingService;
+
+  constructor(errorLogggingService: ErrorLoggingService) {
+    this.errorLogggingService = errorLogggingService;
+  }
+
+  // Public methods.
+
+  public call(exception: any, stackTrace?: any, reason?: string) {
+    this.logToConsole(exception, stackTrace, reason);
+
+    try {
+      // Internally, Angular wraps Error objects inside a proxy; therefore, when we
+      // send the error to the logging service, we want to try and unwrap the error 
+      // first so that we're more likely to send-over a native Error object.
+      // --
+      // CAUTION: This is NOT A DOCUMENTED BEHAVIOR - you have to look at the Angular
+      // source code in order to see that this happens.
+      this.errorLogggingService.log(this.unwrapError(exception));
+    } catch (loggingError) {
+      this.logToConsole(loggingError);
+    }
+  }
+
+  // Private methods.
+
+  private logToConsole(exception: any, stackTrace?: any, reason?: string) {
+    // Even though we are replacing the core _instance_ of the ExceptionHandler, we can
+    // still leverage the core class' static method for stringification of the error.
+    let stringified = ExceptionHandler.exceptionToString(exception, stackTrace, reason);
+
+    if (console && console.group && console.log) {
+      console.group('Custom Exception Handler');
+      console.log(stringified);
+      console.groupEnd();
+    }
+  }
+
+  private unwrapError(exception: any): any {
+    while (exception.originalException) {
+      exception = exception.originalException;
+    }
+    return(exception);
+  }
+}
+// #enddocregion class

public/docs/_examples/cb-exception-handler/ts/app/error-logging.service.ts

@@ -0,0 +1,54 @@
+// #docplaster
+// #docregion
+import { Injectable } from '@angular/core';
+
+// #docregion class
+@Injectable()
+export class ErrorLoggingService {
+  constructor() {}
+
+  // Public methods.
+
+  public log(error: any) {
+    // Internal tracking.
+    this.sendToConsole(error);
+    this.sendToServer(error);
+
+    // Software-as-a-Service (SaaS) tracking.
+    this.sendToNewRelic(error);
+    this.sendToRaygun(error);
+    this.sendToRollbar(error);
+    this.sendToTrackJs(error);
+  }
+
+  // Private methods.
+
+  private sendToConsole(error: any) {
+    if (console && console.group && console.error) {
+      console.group('Error Logging Service');
+      console.error(error);
+      console.groupEnd();
+    }
+  }
+
+  private sendToRollbar(error: any) {
+    // Example: Rollbar.error(error);
+  }
+
+  private sendToNewRelic(error: any) {
+    // Example: newrelic.noticeError(error);
+  }
+
+  private sendToRaygun(error: any) {
+    // Example: Raygun.send(error);
+  }
+
+  private sendToServer(error: any) {
+    // ... use http service to send error to your own server.
+  }
+
+  private sendToTrackJs(error: any) {
+    // Example: trackJs.track(error);
+  }
+}
+// #enddocregion class

public/docs/_examples/cb-exception-handler/ts/app/main.ts

@@ -0,0 +1,7 @@
+/* tslint:disable */
+// #docregion
+import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
+
+import { AppModule } from './app.module';
+
+platformBrowserDynamic().bootstrapModule(AppModule);

public/docs/_examples/cb-exception-handler/ts/example-config.json

@@ -0,0 +1,43 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+
+  <title>
+    Custom Exception Handler Service
+  </title>
+
+  <!-- #docregion style -->
+  <link rel="stylesheet" type="text/css" href="styles.css">
+  <link rel="stylesheet" type="text/css" href="sample.css">
+  <!-- #enddocregion style -->
+
+    <!-- Polyfill(s) for older browsers -->
+    <script src="node_modules/core-js/client/shim.min.js"></script>
+
+    <script src="node_modules/zone.js/dist/zone.js"></script>
+    <script src="node_modules/reflect-metadata/Reflect.js"></script>
+    <script src="node_modules/systemjs/dist/system.src.js"></script>
+
+    <script src="systemjs.config.js"></script>
+    <script>
+      System.import('app')
+        .then(function() {
+          console.info('System.js loaded your application module.')
+        })
+        .catch(function(err) {
+          console.error(err); 
+        });
+    </script>
+  </head>
+<body>
+
+  <h1>
+    Custom Exception Handler Service
+  </h1>
+
+  <my-app>Loading app...</my-app>
+
+</body>
+</html>

public/docs/_examples/cb-exception-handler/ts/index.html

@@ -0,0 +1,9 @@
+{
+	"description": "Custom Exception Handler In Angular 2",
+	"files": [
+		"!**/*.d.ts",  
+		"!**/*.js",
+		"!**/*.[1].*"
+	],
+	"tags": [ "cookbook" ]
+}

public/docs/_examples/cb-exception-handler/ts/plnkr.json

@@ -0,0 +1,5 @@
+a {
+  color: #369 ;
+  cursor: pointer ;
+  text-decoration: underline ;
+}