Forem: Matt Vaughn

Enterprise Web Development - Why so hard?

Matt Vaughn — Sun, 03 Jul 2022 22:35:30 +0000

I have noticed a trend in several enterprise-level projects during the last few years. I think software engineering teams, mostly in the web application space, are having difficulties delivering high-quality and reliable solutions. I know we have smart people - however, I think we are getting in our own way. We think that some of these processes like Agile Scrum/Kan Ban, ScrumBan or whatever is the golden ticket to success.

I think the process is failing our people (developers). Agile principles seem to be far removed from our current/modern approach within large enterprise teams. I guarantee for most teams it is "process over people" and not "people over process". Do we really value working software over process? Especially troublesome, is the hand-off from product teams to developers - our user stories are horrible. Are user stories the right way to organize work and describe what needs to be done?

Is Web Development Really this Difficult?

It is the year 2022 - have you wondered why web development or creating web applications is so difficult? You would think that after a couple of strong decades of web application development along with the tools and processes available today – that we should be better, faster, and more effective in our application development.

But this is not the case. Even though we have better tools and process, there’s still a missing element from web application development. It is up front design for the front end. We have amazing tools, frameworks, platforms - like Angular from Google. What we really need is a workflow that includes architecture along with analysis and design.

What do I mean by this? Architecture has a lot of different meanings in software. So, let’s break it down using what we know about its origin. Throughout the millennia of time, humans have built amazing structures that have lasted for centuries or thousands of years. How did this happen? The Eiffel tower in Paris, the pyramids in Egypt, the Arc de Triomphe in France, and even the beautiful modern skyscrapers that are built today. All have one thing in common. What is that?

Before any of these projects were executed, I mean before someone started building and constructing them there were phases that included analysis and design. What do I mean by analysis and design? It is going through the thought process of what you are going to build, why you need it, who is it for, where will it be used, when will it be used and why will they use it or find it beneficial? It is going through the thought process of answering all of these questions to fully understand what it is that you will be building.

Who, what, why, when, and where?

Additionally, it will also include the consideration and the selection of the tools and materials that will be used to complete the solution. Why am I talking about all these different ideas and things that are done in the architecture of these amazing structures?

It is because software today is very similar. Software is very complex, but we still need to answer the same questions to understand how the solution will solve the problem. Our teams need more or better analysis and design "aspects" added to the SDLC - Agile Scrum/Kan Ban doesn't disallow these exercises/tasks. However, the guidance on when to do analysis/design, who is involved, and what are the assets/artifacts from these meetings is not very clear. This is because there should be different disciplines involved, perhaps at different times. None the less, we need to figure this out. You shouldn't have to ask for permission to do analysis and design work for a feature - just like you shouldn't need permission to write unit tests for your code. You just do it because it is the right to do.

In my opinion, you should not be able to create a user story unless there were analysis and design performed for the feature by the different disciplines? No Mockup-Driven-Development allowed here.

Let's Build Now Mentality

There seems to be this unspoken desire to start development as soon as possible. Even before you fully understand what it is that you are building. It is interesting to me that we can spend thousands to millions of dollars on software projects that fully do not solve the problem. This is because no one stopped to do proper analysis and design before they started writing code.

When did this start to be the normal process of developing software? Nowhere else in our lives or non-programming lives do we do this. When we embark on some project or even a small project like organizing a picnic or a barbecue on a Sunday afternoon. We do some thought and planning. We know who’s going to be there and we know what kind of food we want to serve and what it is going to take to execute and deliver that Sunday afternoon so that everyone enjoys it.

We normally do these things in our every day lives. However when it comes to software development for some reason we throw common sense out the window. We think things just happen. I’ve heard some teams say that they use an emerging architecture approach. That means they don’t have one and whatever happens is the architecture. This is horrible! This is not architecture and it certainly does not include much design, effort, or thinking.

I think some people do more planning for an afternoon barbecue than they do for multi-million dollar software projects. You are asked to build something from scratch, something new, something that’s never been done before and you need to figure it out. What are you going to do?

But also important, what tools and materials are you going to use?

I Want Shiny and New - The Latest and the Greatest

Who doesn't want to use the coolest new toys on the market? Who doesn't like shiny and new? For many things this is OK or even desired. For enterprise application though, you need to take a step back and a deep breath.

Shiny and new is not always your best option. Just saying.

The selection of tools and materials is almost as important as figuring out the what, who, why, when and where of something. This is because it will impact the execution of your solution. And it will also determine how your users will work with the solution. And it also has a huge impact on how long your solution will last. Think about some of the structures that have been built over mankind‘s history. The things that are still around are made of materials that last. Or, they are structures that are well-maintained over a long period of time. This means that someone knows how to maintain and take care of the solution long after it has been built and released for general use.

One thing to consider when you’re selecting your tools and materials is to determine what the community or worldwide support is for these tools. Say for example this is a new shiny new web framework. Does this framework have the backing of a large company? Is it supported? Does it have great documentation so that your developers will understand how to use it properly? Are there good or great reference examples of using this framework? Are there conferences or online tutorials, or training courses, or books that show or demonstrate the capabilities? Is it supported by the community?

Are there meet ups? Are there local or international conferences that include the application framework or tools?

The reason why I’m asking all of these questions is that you need to have tools and materials that are well received, respected and supported by the community. This means that there will be resources to build out your solution and/or maintain it in the long term future.

Foundation

You really need a strong foundation. Recently, I was fortunate enough to travel to France and to see the Eiffel tower. The structure of the Eiffel tower is amazing. But one of the first things that you really notice when you get up close to the Eiffel tower is it foundation. The four corners of the footings are huge and massive and they’re made out of material that looks like stone and it’s going to last and it doesn’t move.

It is the same with any technical solution. You need to have a strong foundation. This means that you have to have some planning so you know what your foundation is. You need to have an architecture - one that fits the solution that you’re going to build and one that can be executed by your developers. If you choose materials and tools as well as an architecture that no one has experience with then you will not have a successful outcome. You might get close but it’s not gonna be of the quality that you need or want.

More information about Angular Architecture at https://www.AngularArchitecture.com:

book

guides

podcast

blog

Therefore the selection of your tools and materials also has to consider the resources or the people who will be building the solution. These are the developers, the software engineers, the Devops individuals, and the database administrators, all of these individuals will have to have some experience or capability to learn how to use the tools and materials effectively and efficiently.

You can’t just pick the best materials or the best tools; as well as the best architecture and hope that you’re going to have a great product. It really is the people. The people your developers are the ones that will build and execute on the design of your solution. Your people are the most important aspect of any software project. As people, software engineers or developers we tend to get very excited at the very beginning of a project. We are very anxious to deliver and to show how good we are and that you chose the right people to do this job.

Process Over People

Does anyone remember software development before all of these product owners, scrum masters, project managers, delivery managers, or other stakeholders got so involved in the software process?

Software development today seems like it is approached with a factory-like mentality. Developers are just these workers that put pieces together. Developers create software like it is an assembly line of a auto factory?

What in the world does assembly line manufacturing (SCRUM) have to do with software?

What do I mean by this? They approach software is if we are building widgets in a factory. It is really that simple, isn't it? That it is so easy to monitor the production and the time it takes to build software parts and pieces; and assemble them into a set of working features. They want to be able to estimate how much time it will take to build components or features. They want to plan and estimate continuously. They want to create pretty reports so that they can deliver these to stakeholders or investors to show that, “We we are on time!”. All of this, with the expectation that we will deliver on time even with all of these interruptions and focus on process over people. it is ridiculous!

I cannot imagine that the builders of the pyramids had Kan Ban boards or scrum masters. Or that they had sprint planning meetings and planning poker! I'm not against good process - just process over people. And by people, I mean developers. Developers are the ones executing work and delivering the product. Everyone else is just support - some of them only checking off boxes on a large todo list.

Here is an example.

In Real Life...

On a recent project, we are charged with building out a new platform of new products and services for the company. This is the beginning of a total rewrite of a suite of applications that the company has acquired or developed over the last 10 years.

Currently, there has been about 15 months of development on this project. We have had at least four different scrum masters. We have had four different architectural direction changes. We have also had three changes in VP-Level management of the project and technical leadership.

I was able to set up the development environment, the infrastructure of the application, and also the architecture that would be used to implement each of the features. All of this was in place before we started working on the first feature. Would this be enough though?

However, the focus was on building the shiny features that would impress our investment stakeholders. These features had other dependencies. Why is this a problem? Well it means that we cannot fully create this feature without the other dependencies. We would have to come back to this feature and refactor so that it works when these other features are put into place later.

Do we do this in real life? Do we completely remodel a kitchen in our home? And then afterwards decide that it would be a good idea to now add plumbing and running water?

Why is this a problem? Well 15 months later we just finished implementing security for this application. We now have roles and permissions that we can use in these features. However, roles and permissions are an integral part of the entire application's feature set. Therefore it should’ve been the first feature that we worked on. This feature is not as shiny and cool though. Agile Scrum is based on the auto industry manufacturing mentality - would they build cars without engines and then decide to put the engine in after the paint job? I wonder what they do?

The amount of rework as well as the amount of time to have discussions of re-factoring features that should’ve been built correctly in the first place is inexcusable.

The main reason why we worked on these other features was to show stakeholders and investors that we could actually build out the new features on the new platform. They scheduled regular meetings to showcase these features to the stakeholders and investors.

So I guess building application features without the proper foundation is OK in this new modern way of developing applications? Yes of course there is a business aspect to software development. However, what is happening is that we are putting the wrong things in a higher priority than actually building working software.

Evidently, working software and our people is a lower priority than providing a smoke and mirror progress meeting to stakeholders and investors. This is a "dog and pony show" for our product team. It gives valuable insight to their stakeholders that the product team is delivering on their commitment and promise. Really?

I remember years ago using agile methodologies, developers would demonstrate or show actual working software to our stakeholders. This would be software that we wouldn’t have to go back to and refactor to make it work when the other features were implemented. Please do not confuse this with integration tasks. This is absolutely a doing the implementation of features in the wrong order or sequence problem.

I did mention that the software dependencies should be developed and implemented in a specific sequence. If you follow this approach, you will find that the dependency that you require will be there and the implementation of the next feature will be much easier. I think this is common sense. However, I wonder why we still were not able to build the features in the correct sequence. I have heard the excuse, “We will do better next time.”

The product team really is serving their master: the stakeholders and investors. And, from a business standpoint this makes total sense to me. However the product team should not dictate from a technology standpoint how software should be delivered and executed. The product team should be able to define who is going to use the product? When will they use it? Where will the product be used? What are the absolute required features for the product? Why is this product needed and what purpose will it serve? In our process over people and factory widget development mentality, the product team thinks that they are an effective part of the SDLC process. During this project the product team could not accurately estimate when features or larger milestones would be complete. This was due to the fact that many of the features were missing required parts and pieces. Instead, they asked for sizing of stories and team velocity calculations. However, this would not be helpful because the current set of stories were incomplete and lacked many details. Therefore the estimates could not be accurate.

The scrum masters on the project were somewhat pleased that they had a set of stories to put into a sprint. However, how would they know that the stories were complete and had enough detail to be executed. Therefore, when sprints completed and many stories were not done there was panic and concern. Now we are trying to figure out why the sprint failed? Why could we not complete all of the story points in our sprint? Obviously, the developers are not working hard enough, right?

How About More Process Here?

Well, maybe the answer is that we need more Sprint grooming and planning. If we do this our Sprint will be successful, right? Grooming stories that are incomplete and lack detail is a very time-consuming and tedious process. Sometimes, we would have up to 20 or 25 people in these sprint grooming meetings. Most of the people there did not participate or comment during these discussions. Think of the man hours of money that just goes down the drain when you have this many people in a meeting not really doing anything.

Imagine a world, where the right people at the right time could sit down and talk through these features and determine the requirements to make it happen? We could actually create a story or a set of stories that represents the work to be executed. Instead we get a single, vague story with a pretty picture along with a lot of assumptions.

The solution here is to have the right people collaborate and do enough analysis and design required to understand the problem and to create the stories to execute work. This should be part of any team's SDLC process or workflow. However after 15 months, it is still impossible to get this type of meeting scheduled or the right people talking to each other. What you get is a few team members and a lot less man hours required to create the stories. This is way more efficient. Now if you do a Sprint grooming on a set of stories the work will be minimal and there will be no time wasted.

But We Are Doing Analysis and "Design", Aren't We?

Mockup-Driven-Development creates more chaos than solutions.

On this project specifically, the product team also goes beyond their scope of work. They also engage and interact with a UI/UX team to create mockups. Typically, mockups are part of the analysis and design phase of a project. However, they do these exercises and have discussions without including the different disciplines from our technology team. What do I mean by this? Well, if you had software architects, engineers, quality assurance engineers, database or data analysts involved, we would be able to provide different points of view during these discussions. Interestingly, the UI/UX developers would have a more complete picture (i.e., data, business rules, validations, messages, notifications, workflows, etc.) to base their UI/UX designs and mockups on. Wouldn't that be wonderful? The requirements would be much more detailed for the developers to execute.

UI mockups is just one artifact from a single discipline that is part of a set of artifacts from many disciplines in a collaborative SDLC process. Where does Agile or this process-over-people mentality address these meetings for analysis and design? There is not story or card to apply time to it - so it must not exist or be valuable. Do we think that the designs and workflows to manufacture an automobile just happened because some product owner had an idea?

Instead, we get user stories with, ”…as a user, I would like to blank, so that I can blank.” These user stories include a pretty picture of the UI mock-up that is associated with the story. In the beginning the product team thought that this was enough to build software! The stories were not organized or grouped nor categorized. The stories lacked relevant detail for the developers. The stories were not in a specific sequence, nor did they indicate any of the dependencies that were required. The stories did not include business rules or data requirements. If the user story included a web form, there were no details on the form validation requirements. There was no discussion about backend APIs to support the feature. There is no information about even if the data existed or was available or if we had the correct data objects that we could actually use in our backend.

I wonder if there is a magical data fairy that came out at night and sprinkled magic data dust on the story to make it happen.

If you are wondering why this team could not just have simple discussions for these details in advance you’re asking the right question. It was brought up many times. There were samples of stories that included the correct information. However, the product team decided that they could do all of the analysis and design by themselves; and they made an attempt to provide this level of detail. However, they still did not include the different disciplines from across the development team. This is the problem. You need to have representation from each of the disciplines on your development team. There’s no way that a product owner/team can know or understand the technical details and technical requirements for technical execution.

A team will always know more and have more capabilities than a single team member or small subset of a team.

And therefore it was completely unacceptable for the product team to expect that our developers could actually execute and deliver the stories that they put into this backlog. They thought they did an excellent job. They thought they provided all of the necessary information that we would need to build out such a new platform. However, software is much more complex especially in this modern world. Our company has different disciplines within our technology team. We have the correct and right people to be involved in these preliminary discussions. In these discussions, we can go through different exercises or collaborative discussions to add detail and color to the requirements or features under consideration. We can also, at this time, help them to prioritize work items so that the correct things are done first. Then we eliminate the dependencies of the features by doing them in a correct and proper order.

It is as if software development has turned into a drive-through experience. That we can just pull up to some speaker and make an order for a cheeseburger, no pickle and a medium french fry. And just pull up and get a bag of software with exactly everything we ordered. It is as if there is an army of software engineers and technical individuals behind the scenes creating the software based on the ticket or order from a drive-through. The expectation from the product team is that we deliver exactly what the pretty picture looks like, however without the proper tools and details it would be impossible to deliver this feature and also do it in a timely manner.

Please pull up to spot #1, and we will bring your software out to you when it is ready!

Build Something Now, Or Else...

Sometimes software engineers are overachievers and they might over promise and many times under deliver. However I think it’s best to keep a balanced view over the amount of completed work that is expected. Especially when the project or solution is brand new and no one has ever built a solution like this before. The entire team should focus on the milestones of the project - not the individual battles (i.e., Sprints). Battles are lost at times, but become important to the overall success of the solution. I'm not comparing software development to war - just a comparison to keep the perspective real.

Developers do not need Scrum Masters or Product Owners going ballistic when all of the stories didn't get finished within a Sprint. It's a sprint - it is not putting a screw or bolt on something in a factory production line. If it was so easy, there wouldn't be a shortage of developer resources.

Software is more difficult than that, isn't it.

Some people feel that greenfield projects are difficult. This is because there is nothing like it nor a reference that can be used to guide the implementation or development of a very unique brand new solution. Personally, I prefer starting a new project without defects or technical debt, it just feels good.

Sometimes what you need though are experienced developers, perhaps some who have worked in many different disciplines or different domains. And they will recognize and see things that are familiar to them or similar to some other aspect or part of something they’ve developed before. This is where their intuition and their experience can really pay dividends. They will quickly understand new concepts and figure out how these things will fit in work together.

It is essential to start with your technical leadership team first. You need to have strong technical leadership that includes solution architecture and software application architecture. These are individuals that have the years of experience to guide and direct a team. They will also can foresee problems or issues with certain aspects of a project. Rely on these individuals heavily because they have seen many things and some of them have even forgot more than some other developers even know at that point in their career. Their intuition and their opinions really matter. So pay attention!

You also need to plan the execution of the work. The sequence and order of things to be built make a difference. So it is not enough to define the stories and what the requirements are. You have to know and understand how they work together and in what order and sequence you need to implement them. Plan the execution. On this topic, product owners provide valuable information for our user stories. However it is a developer that will use the information in the story to execute the work. Therefore, it is essential that the story includes technical details. The technical details can only come from technical disciplines within your team. Therefore you need to have someone involved in the technical aspects of a user story. There may be several user stories that target different technical disciplines or expertise. These also need to be detailed out so that the developer knows exactly what is required. This is not telling them how to do it. It is giving them the correct information so that they can execute the story and deliver the expected result. Sometimes a developer will need to create a proof of concept or have a spike story that enables them to fully understand the problem and the different solutions available for the problem.

Conclusion

Sometimes you need to slow down to go faster. Take the necessary time to understand the problem. Plan your execution. Take time to select your tools and materials. Work with your product teams to create an effective SDLC workflow. Communicate. Collaborate. Make the people the most important development assets - not the process. Processes come and go over the years. We all want to enjoy our work as software developers - it should be fun.

Do the right things, at the right time, with the right people, for the right people.

Angular ErrorHandler - To Handle or Not to Handle?

Matt Vaughn — Sat, 18 Apr 2020 22:46:37 +0000

Please visit AngularArchitecture.com to sign-up for podcast notifications and other Angular resources.

This is what you get off-the-shelf. The ErrorHandler documentation on angular.io indicates that the default behavior is to print error messages to the console. This is fine for initial development. However, when the application goes to production, good luck trying to get access to the console of all the users of your application.

The application is running in the wild. Anything can happen and will. It is not a question if an error will happen, it more like when errors happen, right? Therefore, if the application is important to your business and users, you will want to know some valuable information about the error:

When and where do errors happen?
What kinds of error is it?
What is the origin of the error?
What information is contained in the error?
What does the user need to know, if anything?
What do we want to know about the error?
Where can I view error information about my application.

What is an Error?

An error indicates a problem that was not expected. The origin or source of the error may or may not be in your control.

Exceptions are a type of error that is expected or might be known to occur. Think about the scenario of a person attempting to retrieve cash from an ATM. If their balance is in the negative, the ATM will provide a message (exception) that there are no funds available. This article is mainly focused on errors from the application's perspective.

However, most web applications are going to make some HTTP calls. An HTTP call has the possibility of returning an error response. The reason for this most of the time fits into the category of a true error. The cause of the error response, in this case, is not related to the application's back end API or application.

Some application APIs will return an error status code as part of the API response. This provides some indication as to the type of error. However, since the origin is the actual application's API, the response will most likely return a well-known response in a specified schema or format that will the application to handle it accordingly. For example, if the application makes a call to the CreateAccount API, it might return an error status code and a list of messages that indicate the reason for the error/failure.

User name is already taken.
The password must contain a number and a special character.

Now, that we can expect an error condition from our application's API, we must be able to handle this specific type of error in the application.

External Errors/Exceptions

The Angular platform provides a mechanism to override and implement a custom ErrorHandler for your application. The default behavior of the default ErrorHandler is to write the messages to the browser console. Great for development and debugging. Not so good when the application is deployed to production.

/**
 * Provides a hook for centralized exception handling.
 *
 * The default implementation of `ErrorHandler` prints error messages to the `console`. To
 * intercept error handling, write a custom exception handler that replaces this default as
 * appropriate for your app.
 *
 * @usageNotes
 * ### Example
 *
 * 
 * class MyErrorHandler implements ErrorHandler {
 *   handleError(error) {
 *     // do something with the exception
 *   }
 * }
 *
 * @NgModule({
 *   providers: [{provide: ErrorHandler, useClass: MyErrorHandler}]
 * })
 * class MyModule {}
 * 
 */
export declare class ErrorHandler {
    handleError(error: any): void;
}
export declare function wrappedError(message: string, originalError: any): Error;

Angular Error Handling, Logging, and Notification

Here are some things to consider when implementing an Error Handling strategy for your application.

Error Handling

Determine where error handling should take place in the application - responsibility?
Single source of error handling?
What do you do with the error details and source?
Do you deliver a generic error message, "Oops!"?
How do you handle different types of errors?
- HttpClient use Observables
- Application
- 3rd-party library
- API/Server

Error Notification

Determine if the end-user should be notified of the error.
Are there any specific messages that need to be shown to the user?
Should application/system administrators be notified - how?

Error Logging (Tracking)

Determine what is required for logging/tracking.
Need to understand the context of the error.
Do not log too little, you require relevant and contextual information.
When did it occur? Where? Who? What?

Custom Error Classes

instanceOf
extending Error Classes
adding rich meta data

Error Sources

We can categorize error sources in (3) groups.

External
Internal
Application

External Errors

External errors are external from the running application. In our case, they are external to our Angular application running in a client browser. These occur on servers or APIs outside of our application's runtime environment. Server errors happen while attempting to process the request or during processing on the server.

database connection errors
database errors
application exceptions
application not available

Server

Most Angular applications use some kind of back end API(s) or server to perform additional application processing. Even if the Angular application is serverless - meaning that it doesn't have its specific server associated with the application, the application may use several APIs and functions that are hosted by other providers (think: APIs for MailChimp, Contentful, Firebase, Medium, etc.).

Regardless of the source of these external errors, an Angular application will need to handle them gracefully.

500 Errors

The server failed to fulfill a request.

Response status codes beginning with the digit "5" indicate cases in which the server
is aware that it has encountered an error or is otherwise incapable of performing the
request. Except when responding to a HEAD request, the server should include an entity
containing an explanation of the error situation, and indicate whether it is a
temporary or permanent condition. Likewise, user agents should display any included
entity to the user. These response codes apply to any request method.

Here is an example of some of the types of 500 Server Errors that can happen.

500 Internal Server Error > A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.[62]
501 Not Implemented > The server either does not recognize the request method, or it cannot fulfill the request. Usually, this implies future availability (e.g., a new feature of a web-service API).[63]
502 Bad Gateway > The server was acting as a gateway or proxy and received an invalid response from the upstream server.[64]
503 Service Unavailable > The server is currently unavailable (because it is overloaded or down for maintenance). Generally, this is a temporary state.[65]

Internal Errors

An internal error origin is from the application's API. These types of error, as mentioned previously, will most like use a specific HTTP error status code. However, it will also include a detailed response in a known format to allow the consumer of the API to handle the response. Even though the HTTP status code is an error code, the application should

Security and/or a permission issue.
Business rule violation(s).
Data validation exception(s).

Server

400 Errors

This class of status code is intended for situations in which the error seems to have been caused by the client. Except when responding to a HEAD 
request, the server should include an entity containing an explanation of the error situation, and whether it is a temporary or permanent condition. These status codes apply to any request method. User agents should display any included entity to the user.

Client (Browser) - JavaScript

JavaScript has an Error object that all errors in JavaScript derive from. The standard available properties for an error are as follows:

columnNumber
fileName
lineNumber
message
name
stack

This is the information that we see in the Console of the browser's developer tools. These types of errors are usually unexpected

Here is a list of specialized types of errors that can occur.

Application Errors

Applications can also be the source of errors. These types of errors cause the current application flow to redirect to a registered provider for Handling the error. Developers, coders, and software engineers will not write perfect code. There are inputs, outputs, processing of information, algorithms, calculations, and other things that happen during the runtime of an application that it is impossible to anticipate all things.

Therefore, errors happen and we will see them in the following cases:

Business Rule Violations
Data Validation Errors
Application Exceptions

Error Handling

Regardless of the origination of an error, an Angular application needs to handle the error. Angular has an ErrorHandler that is provided to the application when the application is initialized. This ErrorHandler will eventually catch and handle all thrown errors.

import {ERROR_ORIGINAL_ERROR, getDebugContext, getErrorLogger, getOriginalError} from './errors';

export class ErrorHandler {
  /**
   * @internal
   */
  _console: Console = console;

  handleError(error: any): void {
    const originalError = this._findOriginalError(error);
    const context = this._findContext(error);
    // Note: Browser consoles show the place from where console.error was called.
    // We can use this to give users additional information about the error.
    const errorLogger = getErrorLogger(error);

    errorLogger(this._console, `ERROR`, error);
    if (originalError) {
      errorLogger(this._console, `ORIGINAL ERROR`, originalError);
    }
    if (context) {
      errorLogger(this._console, 'ERROR CONTEXT', context);
    }
  }

  /** @internal */
  _findContext(error: any): any {
    if (error) {
      return getDebugContext(error) ? getDebugContext(error) :
                                      this._findContext(getOriginalError(error));
    }

    return null;
  }

  /** @internal */
  _findOriginalError(error: Error): any {
    let e = getOriginalError(error);
    while (e && getOriginalError(e)) {
      e = getOriginalError(e);
    }

    return e;
  }
}

export function wrappedError(message: string, originalError: any): Error {
  const msg = `${message} caused by: ${originalError instanceof Error ? originalError.message: originalError }`;
  const error = Error(msg);
  (error as any)[ERROR_ORIGINAL_ERROR] = originalError;
  return error;
}

The actual code for the Angular ErrorHandler contains comments and an example.

Provides a hook for centralized exception handling. The default implementation of ErrorHandler prints error messages to the console. To intercept error handling, write a custom exception handler that replaces this default as appropriate for your app.

The code sample provided shows that we can create our class that implements the ErrorHandler interface. A custom handler will need to override and provide a concrete implementation of the handleError() method.

class MyErrorHandler implements ErrorHandler {
  handleError(error) {
    // do something with the exception
  }
}

To allow a specific NgModule to use the custom Error Handler, use the providers configuration and the useClass property with the type of the new ErrorHandler.

Typically, you would provide the ErrorHandler for the entire application in the AppModule. However, each module can have its handler scoped at the module level.

@NgModule({
  providers: [{provide: ErrorHandler, useClass: MyErrorHandler}]
})
class MyModule {}

Errors from the Dark Side:: The Back End

Many times, the error is from the Back End of the application - the Web API. If an error occurs on the back end, you will typically get a 400 or 500 status code from the server. However, during the processing of an HTTP request, it is also possible to get an error. These errors may be connection related or an error in the processing of the HTTP request or the response. There is a lot of opportunities for things to go wrong.

For example, if you use HttpClient you can call the request() method. Using the rxjs pipe(), you can also use the catchError() which will return an HttpErrorResponse to be handled.

execute<T>(requestOptions: HttpRequestOptions): Observable<HttpResponse<ApiResponse<T>>> {
    try {
      return this.httpClient.request<T>(
        requestOptions.requestMethod.toString(),
        requestOptions.requestUrl,
        {
          headers: requestOptions.headers,
          observe: requestOptions.observe,
          params: requestOptions.params,
          reportProgress: requestOptions.reportProgress,
          withCredentials: requestOptions.withCredentials
        }
      ).pipe(
        catchError((errorResponse: any) => {
          return this.handleError(errorResponse);
        })
      );
    } catch (error) {
      this.handleError(error);
    }
  }

The HttpErrorResponse contains details to determine the source of the error. Was it from the server/http or from within the application. This will help you to determine what type of information to provide the user, if any. At a minimum, you could log this information to help monitor the health of the application and determine if any improvements should be made.

HttpErrorResponse: A response that represents an error or failure, either from a non-successful HTTP status - an error while executing the request, or some other failure which occurred during the
parsing of the response.

I updated the signature of the handleError() method to include either type of Error or HttpErrorResponse - this will allow for specialized handling based on the type of error.

protected handleError(error: Error | HttpErrorResponse): Observable<any> {
  if(error.error instanceof ErrorEvent)  {
    // A client-side or network error occurred. Handle it accordingly.
  } else {
      // The API returned an unsuccessful response.
  }
  // handler returns an RxJS ErrorObservable with a user-friendly error message. Consumers of the service expect service methods to return an Observable of some kind, even a "bad" one.
  // return throwError(error);
  return throwError(`Hey, you got my chocolate in your peanut butter.`);
}

Notice that the HttpErrorResponse type implements Error. Therefore, it contains information about the HTTP Request and also error information, like the stack trace if available.

class HttpErrorResponse extends HttpResponseBase implements Error {
  constructor(init: {...})
  get name: 'HttpErrorResponse'
  get message: string
  get error: any | null
  get ok: false

  // inherited from common/http/HttpResponseBase
  constructor(init: {...}, defaultStatus: number = 200, defaultStatusText: string = 'OK')
  get headers: HttpHeaders
  get status: number
  get statusText: string
  get url: string | null
  get ok: boolean
  get type: HttpEventType.Response | HttpEventType.ResponseHeader
}

The abstract base class for the HttpResponse provides the structure for other HTTP Response classes:

HttpErrorResponse
HttpHeaderResponse
HttpResponse

abstract class HttpResponseBase {
  constructor(init: {...}, defaultStatus: number = 200, defaultStatusText: string = 'OK')
  get headers: HttpHeaders
  get status: number
  get statusText: string
  get url: string | null
  get ok: boolean
  get type: HttpEventType.Response | HttpEventType.ResponseHeader
}

Custom Error Handler

Create a new class for the custom ErrorHandler.

ng generate class myErrorHandler --project=error-handling --spec=false

import { ErrorHandler } from "@angular/core";

export class MyErrorHandler implements ErrorHandler {
    handleError(error: any): void {
        throw new Error("Method not implemented.");
    }
}

Add a reference to the library module. We will need to import HttpClientModule. This will give us access to the ErrorHandler interface that we will need to implement.

import { NgModule } from '@angular/core';
import { CommonModule } from '@angular/common';
import { HttpClientModule } from '@angular/common/http';
@NgModule({
  imports: [
    CommonModule,
    HttpClientModule
  ]
})
export class ErrorHandlingModule {}

Implement the interface.

import { ErrorHandler } from '@angular/core';
import { Observable } from 'rxjs';
import { HttpErrorResponse } from '@angular/common/http';

export class MyErrorHandler implements ErrorHandler {
    handleError(error: Error | HttpErrorResponse): Observable<any> {
        throw new Error('Method not implemented.');
    }
}

The following implementation is doing a few things as a sample implementation.

uses a configuration service (injected); use to provide information on how to handle writing error events
uses a logging service (injected); used to allow the error handler to log information to a target

import { Injectable, ErrorHandler } from '@angular/core';
import { HttpErrorResponse } from '@angular/common/http';
import { noop } from 'rxjs';

import { ConfigurationService, ErrorHandlingConfig, IConfiguration, IErrorHandingConfig } from '@tc/configuration';
import { LoggingService, Severity } from '@tc/logging';

@Injectable({
  providedIn: 'root'
})
export class ErrorHandlingService extends ErrorHandler {
  serviceName = 'ErrorHandlingService';
  errorHandlingConfig: IErrorHandingConfig;
  hasSettings: boolean;

  constructor(private config: ConfigurationService, private loggingService: LoggingService) {
    super();

    this.init();
  }

  init() {
    // Use to provide default settings for error handling processing.
    this.errorHandlingConfig = new ErrorHandlingConfig('ErrorHandler', true);
    this.loggingService.log(this.serviceName, Severity.Warning, `Application [ErrorHandler] is using default settings`);

    // subscribe and use settings from the [ConfigurationService] when available.
    this.config.settings$.subscribe(settings => this.handleSettings(settings));
  }

  handleSettings(settings: IConfiguration) {
    this.errorHandlingConfig = settings.errorHandling;
    this.hasSettings = true;
    this.loggingService.log(this.errorHandlingConfig.name, Severity.Information, `Application [ErrorHandler] using configuration settings.`);
  }

  handleError(error: Error | HttpErrorResponse): any {
    if (this.errorHandlingConfig.includeDefaultErrorHandling) {
      // use the [super] call to keep default error handling functionality --> console;
      super.handleError(error);
    }

    if (this.hasSettings) {
      // A. HANDLE ERRORS FROM HTTP
      if (error instanceof HttpErrorResponse) {
        if (error.error instanceof ErrorEvent) {
          // A.1: A client-side or network error occurred. Handle it accordingly.
          const formattedError = `${error.name}; ${error.message}`;
          this.loggingService.log(this.errorHandlingConfig.name, Severity.Error, `${formattedError}`);
        } else {
          // A.2: The API returned an unsuccessful response (i.e., 400, 401, 403, etc.).
          /**
           * The [HttpService] should return a response that is consumable by the caller
           * of the API. The response should include relevant information and error messages
           * in a format that is known and consumable by the caller of the API.
           */
          noop();
        }
      } else {
        // B. HANDLE A GENERALIZED ERROR FROM THE APPLICATION/CLIENT;
        const formattedError = `${error.name}; ${error.message}}`;
        this.loggingService.log(this.errorHandlingConfig.name, Severity.Error, `${formattedError}`, error.stack ? error.stack : null);
      }
    }
  }
}

One Error Handler for Different Types of Errors

A1: HttpErrorResponse & ErrorEvent Handling

The signature of the handleError method can be either of (2) types: Error or HttpErrorResponse. One of the first things to do is to determine if the origin of the error is an HttpErrorResponse or not. If it is of types HttpErrorResponse and ErrorEvent, then it is either an application/client or network related error. Therefore, we will write this error to the application log.

A2: HttpErrorResponse Handling (No Handling Required)

If it is of type HttpErrorResponse only, then the origin is most likely the application's API/application back end. Therefore, the application should be able to handle the response (event though it is in an error state), because the response should be in a well-known API response format. There is no additional processing by the ErrorHandler for these types of errors.

An API response should be well-defined and known to the consumers of the API. A typical response either success or failure should contain a common set of properties. The following is an example of a schema that can be used to provide response information to the application.

IsSuccess: A boolean value used to indicate if the result of the request is a success or not. This should be set to false if the HTTP status code is an error status.
Message: A general message regarding the request (i.e., "Successfully created a new account.").
StatusCode: A valid HTTP status code.
Timestamp: A value indicating the date and time of the response.

export abstract class ApiResponse<T> {
    IsSuccess: boolean;
    Message: string;
    StatusCode: number;
    Timestamp: Date;
  }

A success response will extend from the abstract base class ApiResponse<T>. The Data payload will be in a known and defined type. The JSON data payload should map to a specific model by the application.

import { ApiResponse } from './api-response';

/**
 * Use to define a successful API response. A successful response will
 * most likely include a payload of data (i.e., use the Data property). 
 */
export class SuccessApiResponse<T> extends ApiResponse<T> {
  Data: T;
}

A failure* response will also extend from the abstract base class ApiResponse<T>. Instead of having a Data payload, it will have a list of ApiErrorMessage items to provide additional information to the application. This may include a message that could be displayable to the user.

import { ApiResponse } from './api-response';
import { ApiErrorMessage } from './api-error-message';

/**
 * Use to provide error information from an API. You can also 
 * use this class to create a response with errors while doing
 * error handling.
 * 
 * Errors: is a list om [ApiErrorMessage] items that contain specific
 * errors for the specified request. 
 */
export class ErrorApiResponse<T> extends ApiResponse<T> {
  Errors: ApiErrorMessage[] = [];
}

The specified error message items should also be well-defined and known by the application.

export class ApiErrorMessage {
    id?: string;
    statusCode?: string;
    message: string;
    isDisplayable: boolean;

    /**
     * Use to create a new [ApiErrorMessage]
     * @param message The error from the API.
     * @param displayable Use to indicate if the error should be displayed to the user.
     * @param id An optional identifier for the error.
     * @param statusCode An optional status code for the specified error.
     */
    constructor(message: string, displayable: boolean, id: string | null, statusCode: string | null) {
      this.message = message;
      this.isDisplayable = displayable;
      if (id) {
        this.id = id;
      }
      if (statusCode) {
        this.statusCode = statusCode;
      }
    }
  }

B: General Error from the Application/Browser Client

This type of error requires handling (i.e., logging to a centralized repository and/or console log). These are most likely errors that should be monitored and reviewed by stakeholders of the application.

  handleError(error: Error | HttpErrorResponse): any {
    if (this.errorHandlingConfig.includeDefaultErrorHandling) {
      // use the [super] call to keep default error handling functionality --> console;
      super.handleError(error);
    }

    if (this.hasSettings) {
      // A. HANDLE ERRORS FROM HTTP
      if (error instanceof HttpErrorResponse) {
        if (error.error instanceof ErrorEvent) {
          // A.1: A client-side or network error occurred. Handle it accordingly.
          const formattedError = `${error.name}; ${error.message}`;
          this.loggingService.log(this.errorHandlingConfig.name, Severity.Error, `${formattedError}`);
        } else {
          // A.2: The API returned an unsuccessful response (i.e., 400, 401, 403, etc.).
          /**
           * The [HttpService] should return a response that is consumable by the caller
           * of the API. The response should include relevant information and error messages
           * in a format that is known and consumable by the caller of the API.
           */
          noop();
        }
      } else {
        // B. HANDLE A GENERALIZED ERROR FROM THE APPLICATION/CLIENT;
        const formattedError = `${error.name}; ${error.message}}`;
        this.loggingService.log(this.errorHandlingConfig.name, Severity.Error, `${formattedError}`, error.stack ? error.stack : null);
      }
    }
  }

To use MyErrorHandler as the error handler (instead of Angular's default), update the application's AppModule with a provider item that uses the new class.

import { BrowserModule } from '@angular/platform-browser';
import { NgModule, ErrorHandler } from '@angular/core';

import { AppComponent } from './app.component';
import { NxModule } from '@nrwl/nx';
import { RouterModule } from '@angular/router';
import { MyErrorHandler } from '@my/error-handling';

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    NxModule.forRoot(),
    RouterModule.forRoot([], { initialNavigation: 'enabled' })
  ],
  providers: [
    {
      provide: ErrorHandler,
      useClass: MyErrorHandler
    }
  ],
  bootstrap: [AppComponent]
})
export class AppModule {}

References

Resources

Cross-Cutting Concerns in Angular

Matt Vaughn — Wed, 04 Dec 2019 16:57:22 +0000

Angular Architecture: A book on applying enterprise patterns and practices in Angular. This sample chapter talks about cross-cutting concerns:

what they are

benefits

how to implement your own

how to provide configuration to a cross-cutting concern

See the book on Leanpub.com - Angular Architecture by Matt Vaughn

What is a cross-cutting concern?

It is a concern that crosses the boundaries of your application layers and domain verticals. They are typically agnostic to domain features of the application. They provide useful features to applications like configuration, logging, and error handling. Most applications have requirements to log application events, handle errors and log those errors to a centralized repository. This allows administrators to monitor the health of the application.

A typical cross-cutting concern is something that is not specific to the domain of your application. For example, if you are building a learning management system that include features for authors, students, courses, and videos - it would be something so generic, yet functional, that is used within all or quite a few domain features.

For example, instead of implementing logging directly within an application, we can abstract and separate the cross-cutting concern from the application. I recommend implementing these as library projects. This allows other applications and libraries within an Angular Workspace to use the specified cross-cutting concern library.

Cross-cutting concerns are like many of the infrastructure items that are often not thought about, discussed, or included in the early architectural decisions. Let's say your company has spent 2 or more years of development on a specific project - the current project doesn't have any centralized error handling or logging of information, events, or even errors. How can you quantify that the application is working properly? How will you know if there is a problem with the latest build or deployment? This may seem like an extreme example. However, as a consultant I have seen this very scenario more than once.

It is easier to determine what cross-cutting concerns the application requires early and most likely before a single line of domain feature code is written. I like to think of cross-cutting concerns as required infrastructure concerns that provide value during the development, maintenance, and runtime of the application.

These concerns are like the electrical, plumbing, and air systems that are part of a home. Each room of a house has a specific concern and set of features - however, most likely each of the rooms require one if not all of the infrastructure elements listed above. If someone built a new home and these cross-cutting concerns were not addressed before construction, where and how would they be put in retroactively? The home would be an odd mess. We normally follow convention in many parts of our lives, in building homes and other things. Do not let the excitement of building out the features of a new application outweigh the importance of having a good foundation for your application which includes cross-cutting concerns.

Pro Tip: The minimal cross-cutting concerns for an enterprise Angular application are logging and error handling. I cannot stress the value and importance of these (2) concerns. If there are any issues in your code, you know early if you log and handle errors.

Identify Candidates for Reuse

A good rule to follow when developing applications is to identify candidates to share with multiple applications or libraries. Implement these candidates as stand-alone library projects. The Angular Workspace with library projects gives us the ability to share and reuse code effectively. Consider it thoughtful development when you think through the solutions with this level of detail.

Putting reusable code in their own libraries is a great organizational strategy. It provides a single source of truth for the specific feature. If the feature needs an enhancement or improvement due to a defect, then you have one place to make that change and then all of the other applications or libraries benefit. This eliminates the need to go to many different applications or many different areas within an application to fix something that should have been implemented as a reusable library.

Pro Tip: Some or just enough analysis, design, and planning can make a difference of success or failure. Look back at some failed projects or features to determine if a little more preparation could have made a difference.

It is interesting to think that setting up a new development environment could have so much code and features without a single line of the domain application code. I have found over the years that most applications, if not all of them, require these very common cross-cutting concerns. Therefore, implementing them as reusable libraries makes a lot of sense. It is more efficient and effective in terms of managing your code, improving the code, and allowing other applications and libraries to share the code.

Creating reusable libraries in the Angular Workspace is a relatively new topic. The Angular Workspace is now a capability since version 6 of Angular. If you or your team are not taking advantage of the Angular Workspace by creating reusable libraries, then you are missing out on one of the biggest game-changers in Angular and web development. These are new capabilities that many web development teams have not had the luxury. Using cross-cutting concern libraries simplifies the implementation of your domain code. The code is much cleaner, the signatures of constructors and methods are specific to the domain and do not include any cross-cutting concern items.

Separate early and often. Do not implement things that should be shared directly in an application project.

I take advantage of a configuration library that provides or pushes configuration to each of the cross-cutting concerns during runtime. Many of these cross-cutting concern libraries contain services that can be injected into your application (i.e., services or components). Thus, we get the ability to use dependency injection and to have the ability to use these cross-cutting concerns very easily throughout our Angular application projects.

The reason why I bring up these cross-cutting concerns when we are talking about implementing a feature module is that every feature module requires these things. Therefore, it is very important that the architect or team lead take the time to define the patterns (recipes) for implementing cross-cutting concerns in feature modules. The architect determines and demonstrates how each feature module service or component logs information, how they handle errors, and how they provide information back to the user. The team lead or architect is also responsible for establishing the different layers of the application within a feature module. They define how each layer communicates with other layers within the feature module.

It may seem odd to a teammate to see so much defined upfront. Some team members may not understand why everything needs to be defined upfront before developing the feature module. However, if the patterns, practices, and recipes to create each of the feature module elements are well defined, there is more consistency in the implementation. Therefore the code is more consistent and maintainable throughout the lifetime of the application. I have seen entire codebases for large applications to have such consistency; that you cannot tell which team member implemented what part of the code.

Remember that any application that is deployed to production is an application that requires maintenance.

I have heard some developers say that with so much structure, planning, and design - that it inhibits innovation and creativity. This is not true. To truly innovate and be creative a person needs a full-understanding and knowledge of how something works, not superficial knowledge. This type of understanding also requires experience over time or at least a strong analysis of the domain. With this level of understanding and knowledge a developer can truly be creative and innovative. Without it, it is just guesswork with getting lucky occasionally. Do not confuse the occasional success as full understanding and knowledge of how something works if you didn't do a good-enough analysis of the domain item.

It is not sufficient to know how to write code and compile it. You need to understand the domain of the application along with its concerns, why it is important and beneficial, who uses it, the business rules and workflow. This takes discipline and commitment.

Putting thought, design and a plan in place early allows for easier maintenance and extensibility later. For example I propose that services and components should all extend from a base class. This base class provides the structure and opportunity to provide common elements, features, methods, and properties that all components or services can share. It is an excellent extensibility point.

Logging

Before we write any domain code for the feature we might want to think about how are we going to handle logging or writing information about events that happen in the application. It is important for the developers of the application to know when and where and also in what sequence things take place when business logic is executed. Therefore our application requires a logging service so that we can persist this information.

The simplest way to do this in Angular is to create a service that can be injected into our components and services. This service at the minimum logs information to the console of the application browser or Visual Studio Code environment. This allows you to see information about events, errors, and details about the application during development.

Use the following CLI command to create a new library project within your Angular Workspace. This allows other projects to use the features of the logging module/service.

ng g library logging --publishable

LoggingService

The following LoggingService is a typical implementation that I use to provide the capture of log events for an application. It only does a few things.

retrieves configuration for logging from the configuration service
uses a logEntries\$ Observable to publish log events
the log() method is used by consumers of the LoggingService to add a new log event

Note: the logging service requires some configuration. Please see the Configuration section for more information on how to provide configuration to cross-cutting concern modules and services.

import { Injectable, Optional } from "@angular/core";

import { Severity } from "./severity.enum";
import { IConfiguration } from "@angularlicious/configuration";
import { ConfigurationService } from "@angularlicious/configuration";
import { LogEntry } from "./log-entry";
import { ReplaySubject, Observable } from "rxjs";
import { ILogEntry } from "./i-log-entry";
import { LoggingConfig } from "@angularlicious/configuration";
import { Guid } from "guid-typescript";
import { take } from "rxjs/operators";

@Injectable()
export class LoggingService {
  serviceName = "LoggingService";
  source: string;
  severity: Severity;
  message: string;
  timestamp: Date = new Date();
  applicationName: string;
  version: string;
  isProduction: boolean;
  config: LoggingConfig;
  id: Guid = Guid.create();

  private logEntriesSubject: ReplaySubject<ILogEntry> = new ReplaySubject<
    ILogEntry
  >(1);
  logEntries$: Observable<ILogEntry> = this.logEntriesSubject.asObservable();

  /**
   * The [LoggingService] constructor.
   */
  constructor(@Optional() public configService: ConfigurationService) {
    this.log(
      this.serviceName,
      Severity.Information,
      `Starting logging service [${this.id.toString()}] at: ${this.timestamp}`
    );
    this.initializeService(configService);
  }

  /**
   * Use to initialize the logging service. Retrieves
   * application configuration settings.
   *
   * @param configService contains the configuration settings for the application
   */
  private initializeService(configService: ConfigurationService) {
    if (configService) {
      this.configService.settings$
        .pipe(take(1))
        .subscribe(settings => this.handleSettings(settings));
    }
  }

  /**
   * Use to handle settings from the configuration service.
   * @param settings
   */
  handleSettings(settings: IConfiguration) {
    if (settings) {
      this.config = settings.loggingConfig;

      this.applicationName =
        this.config && this.config.applicationName
          ? this.config.applicationName
          : "Angular";
      this.version =
        this.config && this.config.version ? this.config.version : "0.0.0";
      this.isProduction =
        this.config && this.config.isProduction
          ? this.config.isProduction
          : false;
    }
  }

  /**
   * Use this method to send a log message with severity and source information
   * to the application's logger.
   *
   * If the application environment mode is [Production], the information will
   * be sent to a centralized repository.
   *
   * @param source
   * @param severity
   * @param message
   */
  log(source: string, severity: Severity, message: string, tags?: string[]) {
    this.source = `${this.applicationName}.${source}`;
    this.severity = severity;
    this.message = message;
    this.timestamp = new Date(Date.now());

    if (tags) {
      tags.push(`LoggerId:${this.id.toString()}`);
    } else {
      tags = [`LoggerId:${this.id.toString()}`];
    }

    const logEntry = new LogEntry(
      this.applicationName,
      this.source,
      this.severity,
      this.message,
      tags
    );
    this.logEntriesSubject.next(logEntry);
  }
}

Log Entry Items

Notice that there is no code in the LoggingService to actually log or write an event to a repository or to the application console. The logging service publishes log entries using an Observable. This allows a separation of concerns to capture log entries and the actual mechanism to write them. How and where to write a log entry is up to you. All we need is a log writer that is responsible for logging events to a console or a Web API. This log writer subscribes to the logEntries\$ Observable and then write new log events from the data stream of new log items. The application creates log items and the LoggingService just publishes them.

Here is the ILogEntry interface that provides the definition of a log entry.

import { Severity } from "./severity.enum";

export interface ILogEntry {
  source: string;
  application: string;
  severity: Severity;
  message: string;
  timestamp: Date;
  tags?: string[];
}

When you create a new log entry, you can define the Severity level of the log item. The Severity allows you to designate the level of the log entry. During development, you may want to be verbose in your logging and log all entries. You might have a different strategy for production deployments. For example, you may only want to log entries that are Warning or Error designation only. You can add logic to your writers that log information based on the environment and the severity level of the log entry.

I'll use the Severity.Information enum option to define log entries throughout the application to see a sequence of events and operations. I rely on these to show and display information relevant to the specific operation and feature. Here is an example of an informational log entry.

this.loggingService.log(
  this.componentName,
  Severity.Information,
  `Preparing to load the provider(s) for authentication.`
);

Here is a sample Severity enum that includes some options that may be useful for your implementation.

export enum Severity {
  Information = 1,
  Warning = 2,
  Error = 3,
  Critical = 4,
  Debug = 5
}

Log Entry Writer

So far, we've created a logging service that captures log events from an application. However, these log entries are not very useful unless we can view and monitor the log events. We can create a helper for this cross-cutting concern to actually write the log entries. Now we have to determine the destination of the log entries.

The easiest destination is the application console. Use the CLI to create a ConsoleWriter service in the Logging library project. Below is an example of a console writer. This implementation is a little unique. Notice that the service extends a LogWriter class. This LogWriter is a TypeScript abstract class that provides the structure and implementation details to implement any number of log writers for the application.

Remember that a log writer only needs to subscribe to the LoggingService and then handle any published log entry events. The writer is a service that is decorated with @Injectable which allows it to be provided to the application when it initializes, just like any other provider. Therefore, you have some control as to what log writers you want to provide for the application.

The log writer has a LoggingService injected into the constructor.
Subscribes to the logEntries\$ Observable
handles published log events
writes the log item to the specified target (console)

import { LogWriter } from "./log-writer";
import { ILogEntry } from "../i-log-entry";
import { Severity } from "../severity.enum";
import { Injectable } from "@angular/core";
import { LoggingService } from "./../logging.service";

/**
 * Use this writer to log information to the browser console.
 */
@Injectable()
export class ConsoleWriter extends LogWriter {
  constructor(private loggingService: LoggingService) {
    super();
    this.loggingService.logEntries$.subscribe(logEntry =>
      this.handleLogEntry(logEntry)
    );
  }

  handleLogEntry(logEntry: ILogEntry) {
    this.targetEntry = logEntry;
    this.execute();
  }

  /**
   * No setup required for the console writer.
   */
  public setup(): void {}

  /**
   * Implementation of the abstract method. This will perform the
   * actual `write` action for the specified writer.
   */
  public write(): void {
    switch (this.targetEntry.severity) {
      case Severity.Debug:
        console.debug(this.targetEntry);
        break;
      case Severity.Information:
        console.info(this.targetEntry);
        break;
      case Severity.Warning:
        console.warn(this.targetEntry);
        break;
      case Severity.Error:
        console.error(this.targetEntry);
        break;
      case Severity.Critical:
        console.error(this.targetEntry);
        break;
      default:
        break;
    }
  }
}

Log Writer Abstract Class

The LogWriter is an abstract class. This means that class cannot be instantiated directly - but it can provide the overall structure for any class to become a log writer. Only classes that extend this abstract class can be initialized. Abstract classes are unique in that they can define a set of abstract members (e.g., methods, properties) that require implementation from classes that extend from them. They can also provide implementation members - these members are consumed and available by classes that extend the abstract class. So they provide abstract members like an interface but have the capability to provide implementations for any public members.

Abstract classes are useful to provide common behaviors and a structure for any sub-classes that extend from it. It is like a super base class that is extensible. They are like a miniature blueprint for a specialized class. Abstract classes are not part of the JavaScript specification - they are built into TypeScript and support many Object-Oriented design principles.

Pro Tip: Use abstract classes and the template method design pattern. It is a powerful pattern to provide a consistent implementation for performing the same operation but using a distinct implementation. Can you think of anything in Angular that uses this pattern? Wait for it...the Angular Component has a life-cycle of events and methods - same pattern.

The template method abstract class implements the ILogWriter interface which has an execute() method that requires implementation. You can name your entry point method anything you want - the important thing is that it provides a wrapper around the set of template methods.

import { ILogEntry } from "../i-log-entry";

export interface ILogWriter {
  execute(): void;
}

The execute() method is the entry point into the template method pattern for our writers. We have an entry method that is a controller for a set of methods that define the template or recipe. The recipe in this example is set of methods that provide the implementation of writing log entries. Here is the list or our methods that work together to provide this log writing capability.

setup()
validateEntry()
write()
finish()

The following is the actual template method that demonstrates the flow of the template methods. Some call this the pipeline or lifecycle of something. It is interesting to note that when you use the RxJS pipe() method, you are creating a pipeline of methods that run in a specified sequence when you add any of the RxJS operator methods within the pipe.

  execute(): void {
    this.setup();
    if (this.validateEntry()) {
      this.write();
    }
    this.finish();
  }

The LogWriter class below provides a default implementation for any classes that extend from it. The template method pattern is very extensible. You can add more methods to the template and provide a default implementation and then all other classes that extend from this abstract class now have that behavior.

The validateEntry() method provides a default validation of the information required to log an entry whether it is to the console or to a Web API. If there are no rule violations, the writer invokes the specific writer's write() method. In our current code example, it writes the entry to the application's console.

Note: I use another cross-cutting concern that provides the ability to use default and/or create custom rules for validation. I can reuse the rules-engine in services, components, business logic layers - anywhere there is a need to validate things in a consistent and reliable manner.

import { ILogWriter } from "./i-log-writer";
import {
  ValidationContext,
  IsTrue,
  IsNotNullOrUndefined,
  StringIsNotNullEmptyRange
} from "@angularlicious/rules-engine";
import { ILogEntry } from "../i-log-entry";

// @Injectable()
export abstract class LogWriter implements ILogWriter {
  hasWriter: boolean; // = false;
  targetEntry: ILogEntry;

  /**
   * Use this method to execute the write process for the
   * specified [Log Entry] item.
   *
   * Using the [template method] design pattern.
   */
  execute(): void {
    this.setup();
    if (this.validateEntry()) {
      this.write();
    }
    this.finish();
  }

  /**
   * Use to perform an setup or configuration of the [writer].
   * The [setup] method runs on all executions of the writer - and
   * is called before the [write] method.
   */
  public abstract setup(): void;

  /**
   * Use to validate the [log entry] before attempting to write
   * using the specified [log writer].
   *
   * Returns a [false] boolean to indicate the item is not valid.
   */
  public validateEntry(): boolean {
    const validationContext = new ValidationContext();
    validationContext.addRule(
      new IsTrue(
        "LogWriterExists",
        "The log writer is not configured.",
        this.hasWriter
      )
    );
    validationContext.addRule(
      new IsNotNullOrUndefined(
        "EntryIsNotNull",
        "The entry cannot be null.",
        this.targetEntry
      )
    );
    validationContext.addRule(
      new StringIsNotNullEmptyRange(
        "SourceIsRequired",
        "The entry source is not valid.",
        this.targetEntry.source,
        1,
        100
      )
    );
    validationContext.addRule(
      new StringIsNotNullEmptyRange(
        "MessageIsValid",
        "The message is required for the [Log Entry].",
        this.targetEntry.message,
        1,
        2000
      )
    );
    validationContext.addRule(
      new IsNotNullOrUndefined(
        "TimestampIsRequired",
        "The timestamp must be a valid DateTime value.",
        this.targetEntry.timestamp
      )
    );

    return validationContext.renderRules().isValid;
  }

  /**
   * Use to implement the actual write of the [Log Entry].
   */
  public abstract write(): void;

  /**
   * Use to finish the process or clean-up any resources.
   */
  public finish(): void {}
}

Centralized Log Repository

Now that we have a LoggingService and a recipe for creating log writers we can add different writers that target a different destination (i.e., Web API/database). This is where logging get interesting. When a single page application is released into production, the application runs on a web browser: the client. Any activity or events that you want to log need to be stored in a centralized repository or location. We do not have access to the browser console anymore.

Adding log events to the browser's console does not provide any insight into what the application is doing or its current health. Therefore, we need (2) things:

a centralized repository to store and persist log information
a way to view log items - which may include searching and filtering

There are several cloud-based solutions that allow you to store application log information and to use their reporting tools to view the log events. I use Loggly. Usually, the cloud-based providers have entry-level offerings that provide basic features for free or at a low cost.

The snippet below is an implementation of our LogWriter for Loggly.

configuration information is injected into the constructor (ConfigurationService)
- contains the API key for your Loggly account
- a boolean indicator to determine if the log item should be written to the console (sendConsoleErrors)
the writer subscribes to the logEntries\$ Observable in the LoggingService
- when the logging service publishes a new log entry, this writer prepares it for Loggly
the writer formats the message and pushes the new item onto the LogglyService to send the log information to the cloud-based repository

import { LogWriter } from "./log-writer";
import { ILogEntry } from "../i-log-entry";
import { ConfigurationService } from "@angularlicious/configuration";
import { Optional } from "@angular/core";
import { LogglyService } from "ngx-loggly-logger";
import { LoggingService } from "../logging.service";
import { IConfiguration, LogglyConfig } from "@angularlicious/configuration";

export class LogglyWriter extends LogWriter {
  config: LogglyConfig;

  constructor(
    @Optional() private configService: ConfigurationService,
    private loggingService: LoggingService,
    private loggly: LogglyService
  ) {
    super();
    if (this.configService && this.loggingService) {
      this.configService.settings$.subscribe(settings =>
        this.handleSettings(settings)
      );
      this.loggingService.logEntries$.subscribe(entry =>
        this.handleLogEntry(entry)
      );
    }
  }

  handleSettings(settings: IConfiguration) {
    if (settings) {
      this.config = settings.logglyConfig;
      this.hasWriter = true;
      console.log(`Initializing Loggly writer for messages.`);
    }
  }

  handleLogEntry(entry: ILogEntry) {
    if (this.hasWriter) {
      this.targetEntry = entry;
      this.execute();
    }
  }

  /**
   * This method is part of the [execute] pipeline. Do not call
   * this method outside of the context of the execution pipeline.
   *
   * Use to setup the [Loggly] writer with an [apiKey] from the
   * configuration service.
   *
   * It will use the configuration service to configure and initialize
   * and set up a new call to log the information to the writer.
   */
  public setup(): void {
    if (this.hasWriter) {
      try {
        this.loggly.push({
          logglyKey: this.config.apiKey,
          sendConsoleErrors: this.config.sendConsoleErrors
        });

        if (this.targetEntry.tags && this.targetEntry.tags.length > 0) {
          const tags = this.targetEntry.tags.join(",");
          this.loggly.push({ tag: tags });
        }
      } catch (error) {
        const message = `${this.targetEntry.application}.LogglyWriter: ${{
          ...error
        }}`;
        console.error(message);
      }
    }
  }

  /**
   * This method is part of the [execute] pipeline - it will be called if the
   * current [Log Entry] item is valid and the writer is initialized and ready.
   */
  public write(): void {
    this.loggly.push(this.formatEntry(this.targetEntry));
  }

  /**
   * Use this function to format a specified [Log Entry] item. This should be moved
   * to a specific [formatter] service that can be injected into the specified
   * writer.
   * @param logEntry
   */
  formatEntry(logEntry: ILogEntry): string {
    return `application:${logEntry.application}; source:${
      logEntry.source
    }; timestamp:${logEntry.timestamp.toUTCString()}; message:${
      logEntry.message
    }`;
  }
}

The image below shows the browser console with log events. This same information is sent to Loggly. The HTTP request contains the following payload.

{
  "text": "application:angularlicious; source:angularlicious.GuideComponent; timestamp:Sat, 16 Nov 2019 13:02:43 GMT; message:Preparing to set [Google Analytics] page view for [/custom-angular-modules].",
  "sessionId": "9e71eb86-2352-42e5-959e-8efbf60946f5"
}

You can use the Loggly website to view, filter, and search for specific log items. This is very practical when you need to determine if there are any health or diagnostic concerns for your application.

Error Handling

Another thing to be concerned about is error handling. Angular provides a default error handler.The default error handler writes events to the console on the developer tools in the browser. So we also see a relationship between error handling and logging events in our application. We can provide a custom error handler for our application that does much more than just write the event to the console.

Errors and exceptions happen. Period. There are too many factors and dependencies to prohibit any errors from happening. Therefore, they need to be handled. And systems, users, and application administrators need notifications about errors. It is better to know about an error or exception during development than after a deployment to production.

It would be an error on our part to not consider adding a custom Error Handler to your Angular Workspace. You need it. This is not one of those things that you put into the category of we'll add this later when we have time.

Here are some things to consider for your error handling scenarios.

Error Handling
- Determine where error handling should take place in the application - responsibility.
- Should there be a single source of error handling?
- What do you do with the error details and source?
- Do you deliver a generic error message, "Oops!" to the user?
- How do you handle different types of errors?
  - HttpClient
  - Application
  - 3rd-party library
  - API/Server
Error Notification
- Determine if the end-user should be notified of the error.
- Should application/system administrators be notified - how?
Error Logging (Tracking)
- Determine what is required for logging/tracking.
- Need to understand the context of the error.
- Do not log too little - need relevant information.
- When did it occur? What additional information should be included in the log message?
Custom Error Classes
- instanceOf
- extending Error Classes
- adding rich meta data

Error Sources

We can categorize error sources in (3) groups.

External
Internal
Application

External Errors

database connection errors
database errors
server exceptions
application not available

Server

Most Angular applications use some kind of back end API(s) or server to perform additional application processing. Even if the Angular application is serverless - meaning that it doesn't have its own specific server associated to the application. In this case, the Angular application may use several APIs and functions that are hosted by 3rd-party providers (think: APIs for MailChimp, Contentful, Firebase, Medium, or Google Cloud Platform, etc.).

Regardless of the source of these external errors, an Angular application needs to handle them gracefully.

500 Errors: The server failed to fulfill a request.

Response status codes in the 500-range indicate cases in which the server
is aware that it has encountered an error or is otherwise incapable of performing the
request. Except when responding to a HEAD request, the server should include an entity
containing an explanation of the error situation, and indicate whether it is a
temporary or permanent condition. Likewise, user agents should display any included
entity to the user. These response codes are applicable to any request method.

Here is an example of some of the types of 500 Server Errors that can happen.

500 Internal Server Error: A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.[62]
501 Not Implemented: The server either does not recognize the request method, or it lacks the ability to fulfill the request. Usually, this implies future availability (e.g., a new feature of a web-service API).[63]
502 Bad Gateway: The server was acting as a gateway or proxy and received an invalid response from the upstream server.[64]
503 Service Unavailable: The server is currently unavailable (because it is overloaded or down for maintenance). Generally, this is a temporary state.[65]

Internal Errors

The error may be due to invalid input provided by the request, failed business rules or failed data validation. The request may be mal-formed - and therefore, cannot be processed (wrong media-type, payload too large, invalid permissions).

400 Errors

This class of status code is intended for situations in which
the error seems to have been caused by the client. Except when responding to a HEAD
request, the server should include an entity containing an explanation of the
error situation, and whether it is a temporary or permanent condition. These status
codes are applicable to any request method. User agents should display any included
entity to the user.

Client (Browser) - JavaScript

JavaScript has an Error object that all errors in JavaScript derive from. The standard available properties for an error are as follows:

columnNumber
fileName
lineNumber
message
name
stack

This is the information that we see in the Console of the browser's developer tools. Here is a list of specialized types of errors that can occur.

Application Errors

Believe it or not, applications can also be the source of errors. These could be exceptional - meaning that they are unanticipated. However, when they do happen, the current flow of application flow is redirected to a registered provider for handling the error.

Developers, coders, and software engineers cannot write perfect code. The vast number of conditions, processing paths, algorithms, calculations, and other things that happen during the runtime of an application make it impossible to anticipate all scenarios.

Therefore, errors happen and we see them in the following cases:

Business Rule Violations
Data Validation Errors
Application Exceptions

Handle Errors in Angular

Regardless of the origination of an error, an Angular application needs the ability to handle errors. Angular has a default ErrorHandler that is provided to the application when the application is initialized. This ErrorHandler catches and handles all unanticipated errors.

Handling errors means:

handling the error gracefully
not allowing the error to disable the progress of the application
storing information about the error event in a centralized repository
providing notifications to interested parties.

It is really nice that the Angular platform includes such a feature.

/**
 * @license
 * Copyright Google Inc. All Rights Reserved.
 *
 * Use of this source code is governed by an MIT-style license that can be
 * found in the LICENSE file at https://angular.io/license
 */

import {
  ERROR_ORIGINAL_ERROR,
  getDebugContext,
  getErrorLogger,
  getOriginalError
} from "./errors";

export class ErrorHandler {
  /**
   * @internal
   */
  _console: Console = console;

  handleError(error: any): void {
    const originalError = this._findOriginalError(error);
    const context = this._findContext(error);
    // Note: Browser consoles show the place from where console.error was called.
    // We can use this to give users additional information about the error.
    const errorLogger = getErrorLogger(error);

    errorLogger(this._console, `ERROR`, error);
    if (originalError) {
      errorLogger(this._console, `ORIGINAL ERROR`, originalError);
    }
    if (context) {
      errorLogger(this._console, "ERROR CONTEXT", context);
    }
  }

  /** @internal */
  _findContext(error: any): any {
    if (error) {
      return getDebugContext(error)
        ? getDebugContext(error)
        : this._findContext(getOriginalError(error));
    }

    return null;
  }

  /** @internal */
  _findOriginalError(error: Error): any {
    let e = getOriginalError(error);
    while (e && getOriginalError(e)) {
      e = getOriginalError(e);
    }

    return e;
  }
}

export function wrappedError(message: string, originalError: any): Error {
  const msg = `${message} caused by: ${
    originalError instanceof Error ? originalError.message : originalError
  }`;
  const error = Error(msg);
  (error as any)[ERROR_ORIGINAL_ERROR] = originalError;
  return error;
}

The actual code for the Angular ErrorHandler contains comments and an example.

Provides a hook for centralized exception handling.

The default implementation of ErrorHandler prints error messages to the console. To intercept error handling, write a custom exception handler that replaces this default as appropriate for your app.

The recommendation, although embedded in a comment, is to create our own implementation of the ErrorHandler to provide more direct and customized handling of errors. The default error handler writes errors to the application's console. This is great during development. But it doesn't solve a requirement of having a centralized repository of error messages.

Angular applications are single-page applications where each application instance is on a browser. We do not have access to a user's browser when the application is published. We want a centralized repository for this information.

The code sample shows that we can create our own class that implements the ErrorHandler interface. A custom handler
needs to override and provide a concrete implementation of the handleError() method. Additionally, add the @Injectable decorator to allow the provider to participate in Angular dependency injection.

There are (2) ways to provide a singleton service for your application.

use the providedIn property, or

provide the module directly in the AppModule of the application

Since we want to override the default ErrorHandler for the Angular application, please remove the providedIn configuration

@Injectable({
  //providedIn: "root"
})
class MyErrorHandler implements ErrorHandler {
  handleError(error) {
    // do something with the exception
  }
}

Custom Error Handler

Here is a sample Error Handling service that will log error messages using a LoggingService. This implementation requires some configuration to be provided to the service. The handleError() determines the type of error and processes accordingly.

Note: If the error type is a HttpErrorResponse (i.e., response status code is 400s or 500s) type and is not an ErrorEvent (i.e., generalized JavaScript error) - there is no operation or logging performed. The HTTP service (a different cross-cutting concern) handles an error during the execution of HTTP calls. If there are HTTP errors or an HTTP response contains a known API error response body, the HTTP service will throw an Observable error to allow the consumer to handle it using the Observable pattern.

the configuration provides an includeDefaultErrorHandling boolean property to indicate if logging to the application console should be performed. Normally this is set to false during for production environment deployments.
a LoggingService is injected into the constructor to allow the service to log error information

Note: the logging service requires some configuration. Please see the Configuration section for more information on how to provide configuration to cross-cutting concern modules and services.

@Injectable({
  providedIn: "root"
})
export class ErrorHandlingService extends ErrorHandler {
  serviceName = "ErrorHandlingService";
  config: ErrorHandlingConfig;
  hasSettings: boolean;

  constructor(
    private configService: ConfigurationService,
    private loggingService: LoggingService
  ) {
    super();

    this.init();
  }

  init() {
    this.config = new ErrorHandlingConfig();
    this.config = {
      applicationName: "Angular",
      includeDefaultErrorHandling: true
    };
    this.config.applicationName = "ErrorHandlerService";
    this.config.includeDefaultErrorHandling = false;
    console.warn(`Application [ErrorHandler] is using default settings`);

    this.configService.settings$
      .pipe(take(1))
      .subscribe(settings => this.handleSettings(settings));
  }

  handleSettings(settings: IConfiguration) {
    if (settings && settings.errorHandlingConfig) {
      this.config = settings.errorHandlingConfig;
      this.hasSettings = true;

      this.loggingService.log(
        this.config.applicationName,
        Severity.Information,
        `Application [ErrorHandler] using configuration settings.`
      );
    }
  }

  /**
   * Use to handle generalized [Error] items or errors from HTTP/Web
   * APIs [HttpErrorResponse].
   *
   * @param error
   */
  handleError(error: Error | HttpErrorResponse): any {
    if (this.config.includeDefaultErrorHandling) {
      // use the [super] call to keep default error handling functionality --> console;
      super.handleError(error);
    }

    if (this.hasSettings) {
      // A. HANDLE ERRORS FROM HTTP
      if (error instanceof HttpErrorResponse) {
        if (error.error instanceof ErrorEvent) {
          // A.1: A client-side or network error occurred. Handle it accordingly.
          const formattedError = `${error.name}; ${error.message}`;
          this.loggingService.log(
            this.config.applicationName,
            Severity.Error,
            `${formattedError}`
          );
        } else {
          // A.2: The API returned an unsuccessful response (i.e., 400, 401, 403, etc.).
          /**
           * The [HttpService] should return a response that is consumable by the caller
           * of the API. The response should include relevant information and error messages
           * in a format that is known and consumable by the caller of the API.
           */
          noop();
        }
      } else {
        // B. HANDLE A GENERALIZED ERROR FROM THE APPLICATION/CLIENT;
        const formattedError = `${error.name}; ${error.message}`;
        this.loggingService.log(
          this.config.applicationName,
          Severity.Error,
          `${formattedError}`
        );
      }
    }
  }
}

There is a lot of logic in the handleError() method. First, it will use the configuration information to determine if it should log the event using the default base class. This will essentially log the item to the browser console.

if (this.config.includeDefaultErrorHandling) {
  // use the [super] call to keep default error handling functionality --> console;
  super.handleError(error);
}

Next, there is a check to determine the type of error to handle. There are (2) possible sources and the processing paths are different based on the type.

A. HANDLE ERRORS FROM HTTP

B. HANDLE A GENERALIZED ERROR FROM THE APPLICATION/CLIENT;

A. HANDLE ERRORS FROM HTTP

If the source of the error is from an HTTP operation, the error could originate from JavaScript while preparing the request or when handling the response. We can check the error to determine if it is an instanceof ErrorEvent. This type of error is most-likely unanticipated and should be logged.

if (error.error instanceof ErrorEvent)

The second type of HTTP error is based on the HTTP Status Code of the HTTP response. If the status code is in the 400 or 500 categories, the response is considered to be in an error state. However, since we are most likely working with the application's Web API, we want to defer to the processing logic of our HTTP service (See the Handle HTTP Errors section). There are a few reasons for this.

the web API could be sending a valid response - it just has a specified status code that indicates an error of some sort
the web API may include and probably should include a payload that provides information about the specified request and any error messages. See API Response Schema/Model section.
- perhaps sending a list of validation error messages
- or, it may be a failed business rule
- the consumer of the web API did not receive a successful response and needs to provide information to the user about the status of the request.
the consumer of the web API response is expecting an Observable event to handle and process
- the HTTP service can return the response with the payload that includes the error information as an Observable (application validation or business rule failure)
- if the web API response payload is not known (server error), the HTTP service can wrap a generic error message in a response format that the consumer is expecting and return it as an Observable.

In this scenario, we will do nothing and allow the HTTP service to handle the error.

// A.2: The API returned an unsuccessful response (i.e., 400, 401, 403, etc.).
/**
 * The [HttpService] should return a response that is consumable by the caller
 * of the API. The response should include relevant information and error messages
 * in a format that is known and consumable by the caller of the API.
 */
noop();

B. HANDLE A GENERALIZED ERROR FROM THE APPLICATION/CLIENT

This is truly an unexpected JavaScript error of type Error. We want the application's custom Error Handler to handle the error by creating a new log event item with a severity status of Error.

const formattedError = `${error.name}; ${error.message}`;
  this.loggingService.log(
    this.config.applicationName,
    Severity.Error,
    `${formattedError}`
  );

Provide Custom Error Handler

Provide the custom error handler in the applications root module AppModule, use the providers configuration and the useClass property with the type of the new ErrorHandler. This basically injects our custom class into the application as the new default error handler provider. Providing it at the root level of the application makes the MyErrorHandler globally available to the entire application.

@NgModule({
  providers: [
    {
      provide: ErrorHandler,
      useClass: MyErrorHandler
    }
  ]
})
class AppModule {}

The Angular ErrorHandler is initialized very early in the application's load life cycle. Therefore, you need to initialize a custom provider early.

Error Handling References

Configuration

Most Angular applications that require configuration will take advantage of the environment constant where you can set application-wide configuration items for each of the environments. Angular provides a fileReplacement mechanism to assist in this regard. Therefore, we have a convenient mechanism to provide an environment-specific configuration for an application.

We can take advantage of the same pattern and create a configuration for our cross-cutting concern providers (i.e., services) that need an environment and application-specific configuration.

Provide Configuration to Cross-Cutting Concern Libraries

Library projects cannot reference or import anything from an application project. If this was possible it would immediately create a circular dependency for the cross-cutting libraries. Therefore, we need a way for a library to get configuration information during the runtime of an application instance.

Define the Configuration

Create a constant that provides the structure for your configuration. In this example, an interface defines the members of the configuration container. Notice that each of the cross-cutting concerns that need configuration has its own definition (schema/interface) - and it should specific to the environment as well.

logging
error handling
loggly log writer (cloud-based) repository for log items

Each cross-cutting library (module) that needs configuration has a corresponding interface to define the specific configuration members of that item. This separation of concerns keeps things organized and reduces the chance of using the wrong configuration.

import { ILoggingConfig } from './config/i-logging-config';
import { IErrorHandingConfig } from './config/i-error-handling-config';
import { ILogglyConfig } from './config/i-loggly-config';

export interface IConfiguration {
  applicationName: string;
  loggingConfig: ILoggingConfig;
  errorHandlingConfig: IErrorHandingConfig;
  logglyConfig: ILogglyConfig;
}

The TypeScript const contains a concrete implementation for the application configuration.

import {
  IConfiguration,
} from '@angularlicious/configuration';
import {} from '@angularlicious/error-handling';

export const AppConfig: IConfiguration = {
  applicationName: 'Angularlicious.LMS',
  loggingConfig: {
    applicationName: 'Angularlicious.LMS',
    isProduction: false,
  },
  errorHandlingConfig: {
    applicationName: 'Angularlicious.LMS',
    includeDefaultErrorHandling: true,
  },
  logglyConfig: {
    applicationName: 'Angularlicious.LMS',
    apiKey: '11111111-1111-1111-1111-111111111111',
    sendConsoleErrors: true,
  };
}

Transform the Configuration (File Replace)

Most of the time, there are subtle differences between development and production environments. Some enterprise applications may have additional environments. We can use the configuration node in the architect|build section (see: angular.json file) to configure any file replacements that the configuration requires. The fileReplacements is an array of {replace, with} items.

Note: The build configuration for all of the workspace projects is in the angular.json file. Find the specific project and update the configuration|production|fileReplacements section.

"configurations": {
  "production": {
    "fileReplacements": [
      {
        "replace": "apps/lms-admin/src/environments/environment.ts",
        "with": "apps/lms-admin/src/environments/environment.prod.ts"
      },
        {
          "replace": "apps/lms-admin/src/assets/app-config.ts",
          "with": "apps/lms-admin/src/assets/app-config.production.ts"
        }
    ],
  }
}

Load the Configuration

Angular applications take advantage of dependency injection to share instances of providers. A provider may be a service, class, or value that is loaded into an injector. We also need to provide the configuration which is currently a TypeScript Object Literal, essentially an object with data. Each Angular application contains a single root injector that is responsible for injecting all things provided at the root-level.

It is recommended that providers are added to the root-level injector by default if at all possible. This is exactly what needs to happen for the application's configuration and cross-cutting concern services (i.e., logging, error handling, etc.). The application only needs a single instance of these providers.

A root-level injector implies that there can be other levels or branches of injectors within an application. For example, when a module is lazy-loaded a new injector is created for that module. This impacts the use of providers from a shared module. It is a common practice to create a shared module to group related things together; as well as provide a set of services. When a lazy-loaded module would like to use the items provided by a shared module it has no way of accessing those items. Why? It is because they are scoped to the shared module at this time. However, if we could just provide those items from a shared module to the root-level injector.

In this example, the shared module to configures and provides all of the cross-cutting providers (i.e., services like configuration, error handling, logging, and log writers). When the lazy-loaded module requires a provider with the same Key as one that is loaded in the root-level injector, you would think by default that the lazy-loaded module would get the provider from the root-level injector. This is not the case! What? The lazy-loaded module has its own injector and will initialize its own set of providers required by the module that have the same key/name. But there is another, way that is.

Note: You may need to create a unique identifier or timestamp for these providers if you want to see that they are actually different instances than the singletons contained in the root-level injector of the application.

In some cases, there may not be any side effects of this behavior. However, if you are expecting all modules lazy-loaded or not to use the same provider (i.e., as a singleton) instance throughout the application we have to do something a little different.

Learn more about Shared Modules and Dependency Injection at Rangle.io.

We will not add items to the providers array in the shared @NgModule decorator because this will basically provide them using an injector that is specific to the shared module and not the application's root-level injector. Instead, a static forRoot() is created to allow a consumer of this shared module and its providers to basically push the providers to the root-level injector by calling this method.

To provide items from a shared module to the root-level injector, use the forRoot() static method when importing the module in the AppModule. Learn more about Sharing the Same Dependency at Rangle.io. Now that the providers (all of our cross-cutting concern services) are contained in the root-level injector of the application, they will also be available to all lazy-loaded modules - magic!

@NgModule({
  imports: [
    CrossCuttingModule.forRoot(),
    SharedModule,
    SiteModule,
    AppRoutingModule,
    BrowserAnimationsModule,
  ],
  declarations: [AppComponent, AdminLayoutComponent],
  exports: [],
  providers: [],
  bootstrap: [AppComponent],
})
export class AppModule {}

The return object of the forRoot() method is an object literal that returns the shared module and all of its providers - including the ones that require some special handling with the APP_INITIALIZER.

/**
 * The factory function to initialize the logging service and writer for the
 * application.
 *
 * @param loggingService
 * @param consoleWriter
 */
export function initializeLogWriter(consoleWriter: ConsoleWriter) {
  console.log(`Initializing [Console Writer] from [AppModule]`);
  return () => {
    return consoleWriter;
  };
}
@NgModule({
  declarations: [],
  imports: [
    CommonModule,
    ErrorHandlingModule,
    LoggingModule,
    ConfigurationModule.forRoot({ config: AppConfig }),
    SecurityModule,
  ],
  providers: [
    // DO NOT ADD PROVIDERS HERE WHEN USING [SHARED] MODULES; USE forRoot();
  ],
})
export class CrossCuttingModule {
  static forRoot(): ModuleWithProviders {
    return {
      ngModule: CrossCuttingModule,
      providers: [
        ConfigurationService,
        LoggingService,
        ConsoleWriter,
        LogglyWriter,
        {
          provide: APP_INITIALIZER,
          useFactory: initializeLogWriter,
          deps: [LoggingService, ConsoleWriter, LogglyWriter],
          multi: true,
        },
        {
          provide: ErrorHandler,
          useClass: ErrorHandlingService,
          deps: [ConfigurationService, LoggingService],
        },
        AuthenticationService,
      ],
    };
  }
}

Push the Configuration

There is now a mechanism to define the configuration and to load providers at the root-level injector of the application. There is one last step to this entire process. We still need to get the configuration to each provider that has a configuration concern. Leverage the capabilities of Angular and RxJS to push the configuration when it is available.

In the CrossCuttingModule, the import of the ConfigurationModule calls the forRoot() method to provide the configuration to the module. What does this mean? It basically does what we were doing for the shared module - it provides the configuration to the root-level dependency injector. Now the configuration is available to the application.

}
@NgModule({
  declarations: [],
  imports: [
    CommonModule,
    ErrorHandlingModule,
    LoggingModule,
    ConfigurationModule.forRoot({ config: AppConfig }),
    SecurityModule,
  ],
  providers: [
    // DO NOT ADD PROVIDERS HERE WHEN USING [SHARED] MODULES; USE forRoot();
  ],
})

The ConfigureContext is provided to the application with the AppConfig that contains all of the required configuration information. Now that the configuration is provided and available to access, the ConfigurationService can use the configuration.

import { NgModule, ModuleWithProviders } from '@angular/core';
import { CommonModule } from '@angular/common';
import { ConfigurationContext } from './configuration-context';

@NgModule({
  imports: [CommonModule],
})
export class ConfigurationModule {
  static forRoot(configContext: ConfigurationContext): ModuleWithProviders {
    console.log(`Preparing to handle configuration context.`);
    return {
      ngModule: ConfigurationModule,
      providers: [
        {
          provide: ConfigurationContext,
          useValue: configContext,
        },
      ],
    };
  }
}

The ConfigurationContext is injected into the constructor of the ConfigurationService. The service will now take advantage of publishing the configuration via a readonly Observable. Notice that the Observable settings$ accessibility is read-only. Consumers of the configuration are not allowed to publish any changes to the configuration. Changes are published once when the configuration is available using the ReplaySubject of 1.

private settings: Subject<IConfiguration> = new ReplaySubject<IConfiguration>(1);
public readonly settings$: Observable<IConfiguration> = this.settings.asObservable();

The ConfigurationService is a humble service but its job is very important. Its job is to act as a mediator between the application and the providers to push the configuration to any providers that subscribe to the settings$ Observable.

Note: the ConfigurationService pushes the configuration to the subscribers. This is the Angular way. There is no need for each provider to retrieve its own configuration - the dependency injection pattern is to provide what is asked for and to not allow consumers to create or provide their own dependencies.

import { Injectable, Optional } from '@angular/core';
import { Subject, ReplaySubject, Observable } from 'rxjs';
import { IConfiguration } from './i-configuration';
import { ConfigurationContext } from './configuration-context';

@Injectable({
  providedIn: 'root',
})
export class ConfigurationService {
  private settings: Subject<IConfiguration> = new ReplaySubject<IConfiguration>(1);
  public readonly settings$: Observable<IConfiguration> = this.settings.asObservable();

  constructor(@Optional() context: ConfigurationContext) {
    if (context) {
      this.settings.next(context.config);
    }
  }
}

Configuration Summary

The configuration is a very important aspect of an enterprise application. The more that we make use of libraries and cross-cutting concerns - the more important it is to have the capability to provide configuration to different parts of the application. These may also include core domain libraries that contain application-specific business logic for that specified domain. Therefore, create a reliable, consistent, and repeatable way to:

define configuration schema/interface for a specific concern
create a concrete configuration based on the interface
push the configuration to any subscribers
provide the configuration and cross-cutting concerns to the root-level dependency injector

API Response Schema/Model

Many applications communicate with 3rd-party APIs or the application's own API hosted on a server. Therefore, one main aspect of the application is the ability to make HTTP requests and to properly handle the HTTP response. I think it is important to define a schema for the HTTP response. A schema is a contract between the client and back end Web APIs. This works when you are building the back end Web APIs to support the application and can coordinate what the shape or schema of the response will look like.

This response schema should include an indicator of success. An API scheme should also include a payload property that contains the data returned by the back end server. If the API has any messages that it would like to provide to the user or the consuming application, it should provide these in a message list in the API response schema.

Having a well defined and well-known API schema is very important for the consuming application to handle and process the responses from the back end server. It allows the client application to have a consistent and reliable format and mechanism for processing the response of any API request.

Why Define an API Response

It might seem like an added layer of complexity at the moment. Or, it may seem like it isn't that important. You may be satisfied with making an HTTP/Web API call and dealing with everything in an optimistic mindset as if there will never be any errors in the processing of a request.

The truth is that error will happen. Not all requests are successful and return the payload of data. Additionally, if something goes wrong would it be nice to have the capability to display information to the user to let them know what happened or what they may do to correct the problem.

To put it into perspective, I recently worked on a web form that literally had 6 different formats for various responses (i.e., asynchronous validators and form submission). Displaying any relevant information to the user was an exercise in chaos. The original implementation just displayed the word Error without any other information for the user. Very sad! By the way, this application contains about 150 HTTP/Web API calls and each one of them is a snowflake (i.e., each request has a different implementation on handling the response and any errors). Many of the responses came back as a success, status code 200/OK, but only contained cryptic error messages. This is confusing and unnecessary with little design and planning. Keep it consistent by the plan.

Pro Tip: Define an API Response that is reliable. It will save you hours of frustration during development - and it will allow for a consistent mechanism to communicate information with the users. It supports consistent error handling and processing of HTTP requests.

A Base Response

The ApiResponse<T> is an abstract class that provides the basic structure for any HTTP response. This is one that I am currently using. However, I recommend that you work with the Web API developers and agree upon a response schema. There are quite a few styles for a response schema. Please do some research and determine what is most appropriate for you application and context.

is an abstract class to allow for a success and error type response sub-classes
uses Generics to allow you to indicate the expected type for the model/entity
IsSuccess to indicate if the response is successful or not; seems arbitrary at the moment, but is very useful in determining the processing path of the response if it contains any error messages
Timestamp: use to indicate the date and time the response was issued by the server

export abstract class ApiResponse<T> {
  IsSuccess: boolean;
  Message: string;
  StatusCode: number;
  Timestamp: Date;
}

Success API Response

It is likely that most of the responses you get from your application's Web API are successful and return with a payload of data. The SuccessApiResponse<T> class just extends the base class so that it also has common information - no matter if it is successful or not.

contains a Data property of type T to allow the client to indicate what the data payload type should be.
contains a list of ApiMessage items to allow the Web API to return any information useful to the application or to display to the user.

import { ApiResponse } from './api-response';
import { ApiMessage } from './api-message';

/**
 * Use to define a successful API response. A successful response will
 * most likely include a payload of data (i.e., use the Data property).
 */
export class SuccessApiResponse<T> extends ApiResponse<T> {
  Data: T;
  Messages: ApiMessage[];
}

Error API Response

In the unlikely event, the application's Web API returns an error or failure response it should be in a well-defined format to allow the application to process it and retrieve any messages from the response.

Note that this response does not contain a Data property. The expected payload is not available or provided by the API when the operation is in an error state.

You get a list of messages that provide valuable information to the application and also to the user. If you need a consistent mechanism to provide information to the user from the back end of your application this is the way to do it.

import { ApiResponse } from './api-response';
import { ApiMessage } from './api-message';

/**
 * Use to provide error information from an API. You can also
 * use this class to create a response with errors while doing
 * error handling.
 *
 * Errors: is a list om [ApiErrorMessage] items that contain specific
 * errors for the specified request.
 */
export class ErrorApiResponse<T> extends ApiResponse<T> {
  Errors: ApiMessage[] = [];
}

API Messages

This is the equivalent of two tin cups and a string that attaches them together - it is a way to communicate a message from one end of the application to the other end (client). If the application's Web API needs to communicate any information to the application and/or the user of the application it needs a message.

This is a message format that is generic enough to provide messages that are informational, warning, or indicate an error of some sort.

contains an ApiMessageSeverity enum property to indicate the level of severity
use the isDisplayable boolean indicator to determine whether the message is intended for the user or not

import { ApiMessageSeverity } from './api-message-severity.enum';

export class ApiMessage {
  id?: string;
  message: string;
  severity: ApiMessageSeverity;
  isDisplayable: boolean;

  /**
   * Use to create a new [ApiErrorMessage]
   * @param message The error from the API.
   * @param displayable Use to indicate if the error should be displayed to the user.
   * @param id An optional identifier for the error.
   */
  constructor(message: string, displayable: boolean, id: string | null) {
    this.message = message;
    this.isDisplayable = displayable;
    if (id) {
      this.id = id;
    }
  }
}

The ApiMessageSeverity is useful if you need to style or format the display of the information based on the severity level. It is nice to be able to provide error messages, but it also a nice feature to provide messages that informative to the user.

export enum ApiMessageSeverity {
  Information = 'Information',
  Warning = 'Warning',
  Error = 'Error',
}

HTTP Service

Most applications require the use of Web APIs or a dedicated back end to retrieve and persist information. If the application makes HTTP requests and processes HTTP responses to provide useful data or information, it will need to use the Angular HttpClient. In my experience, I have seen many different (i.e., how) implementations of the HttpClient to perform HTTP related concerns. Also, where these operations are implemented is interesting - never in the same place.

Pro Tip: When using a layered architecture determine where and how to implement HTTP requests. It should be consistent throughout all of the domain verticals and/or specified layer of the domain item. This is definitely one item where variance, deviation from acceptable patterns/recipes, and chaos could make an application virtually unmaintainable. The long-term effects of snowflake implementations is a pile of technical debt that is not easy to overcome. The best thing to do is to eliminate technical debt with proper planning and implementation.

Each domain section will have its own HTTP service that is specific to the API operations that is requires. However, the way or mechanism to construct, execute and handle an HTTP request should be consistent and maintainable. Therefore, make use of a library project to create a new cross-cutting concern for HTTP-related things.

Goal: To enable HTTP/Web API calls to be constructed, managed, and executed using a repeatable and reliable mechanism. Most if not all HTTP requests should be constructed using the same pattern/recipe. There should be little or no reason to not use such a mechanism. When you want to extend or add new features - there will be a single location to make such changes. The current application I'm working on has over 150 variations of processing HTTP requests.

HTTP Service Responsibilities

The HTTP Service has some basic responsibilities and concerns.

create the HTTP request options
- set the request method (i.e., post, get, put, etc.)
- add header information to the request if required
- set the target URL for the request
- include an optional body payload
execute the request
handle any errors

The following HttpService class is basically using and wrapping some concerns using the HttpClient from @angular/common/http. It may seem trivial at first to create such a class. Consider, where HTTP calls should be made within your application - location matters. Consider how they are implemented and really who or what should have the responsbility or concern. When you think about it, an HTTP call is one of the last tasks you perform within an application for a specific operation. The request is executed and the application has to wait for some kind of response.

Create a new HttpService library project and service with the Angular CLI:

ng g library httpService
ng g service httpService --project=http-service

The sample class below is only doing a few things. Mostly, creating the options for an HTTP request. The options is a container for the information required to execute an HTTP request. The execute<T>() makes use of the Angular HttpClient. Unless you practice the mystical art of optimistic programming, there will be errors and exceptions during HTTP operations - please do not ignore these, but handle them.

createOptions(): a primary method to construct HTTP options using a specific recipe
createHeader: a helper method to add header information to the HTTP options. Modify to suite your needs
execute<T>(): a primary method of the service to wrap the HttpClient request
handleError(): use to handle errors when they happen

import { Injectable } from '@angular/core';
import { HttpRequestMethod } from './http-request-methods.enum';
import {
  HttpHeaders,
  HttpClient,
  HttpResponse,
  HttpErrorResponse,
} from '@angular/common/http';
import { HttpRequestOptions } from './http-request-options';
import { Observable, throwError } from 'rxjs';
import { catchError, retry } from 'rxjs/operators';
import { ApiResponse } from '@angularlicious/foundation';
import { ErrorApiResponse } from '@angularlicious/foundation';
import { ApiErrorMessage } from '@angularlicious/foundation';

@Injectable()
// { providedIn: 'root', }
export class HttpService {
  constructor(private httpClient: HttpClient) {}

  /**
   * Use to create [options] for the API request.
   * @param method Use to indicate the HttpRequest verb to target.
   * @param headers Use to provide any [HttpHeaders] with the request.
   * @param url Use to indicate the target URL for the API request.
   * @param body Use to provide a JSON object with the payload for the request.
   * @param withCredentials Use to indicate if request will include credentials (cookies), default value is [true].
   */
  createOptions(
    method: HttpRequestMethod,
    headers: HttpHeaders,
    url: string,
    body: any,
    withCredentials: boolean = true
  ): HttpRequestOptions {
    let options: HttpRequestOptions;
    options = new HttpRequestOptions();
    options.requestMethod = method;
    options.headers = headers;
    options.requestUrl = url;
    options.body = body;
    options.withCredentials = withCredentials;
    return options;
  }

  /**
   * Use to create a new [HttpHeaders] object for the HTTP/API request.
   */
  createHeader(): HttpHeaders {
    let headers = new HttpHeaders();
    headers = headers.set('Content-Type', 'application/json');
    return headers;
  }

  /**
   * Use to execute an HTTP request using the specified options in the [HttpRequestOptions].
   * @param requestOptions
   */
  execute<T>(requestOptions: HttpRequestOptions): Observable<ApiResponse<T>> {
    console.log(
      `Preparing to perform request to: ${requestOptions.requestUrl}`
    );
    return this.httpClient
      .request<T>(
        requestOptions.requestMethod.toString(),
        requestOptions.requestUrl,
        {
          body: requestOptions.body,
          headers: requestOptions.headers,
          reportProgress: requestOptions.reportProgress,
          observe: requestOptions.observe,
          params: requestOptions.params,
          responseType: requestOptions.responseType,
          withCredentials: requestOptions.withCredentials,
        }
      )
      .pipe(
        retry(1),
        catchError((errorResponse: any) => {
          return this.handleError(errorResponse);
        })
      );
  }

  /**
   * Use to handle errors during HTTP/Web API operations. The caller expects
   * an Observable response - this method will either return the response from
   * the server or a new [ErrorApiResponse] as an Observable for the client to
   * handle.
   *
   * @param error The error from the HTTP response.
   */
  protected handleError(error: HttpErrorResponse): Observable<any> {
    const apiErrorResponse = new ErrorApiResponse();
    apiErrorResponse.IsSuccess = false;
    apiErrorResponse.Timestamp = new Date(Date.now());
    apiErrorResponse.Message = 'Unexpected HTTP error.';

    if (error.error instanceof ErrorEvent) {
      // A client-side or network error occurred. Handle it accordingly.
      apiErrorResponse.Errors.push(
        new ApiErrorMessage(
          `A client-side or network error occurred. Handle it accordingly.`,
          true,
          null
        )
      );
      return throwError(apiErrorResponse);
    } else {
      // The API returned an unsuccessful response.
      if (error instanceof ErrorApiResponse) {
        // A known error response format from the API/Server; rethrow this response.
        return throwError(error);
      } else {
        // An unhandled error/exception - may not want to lead/display this information to an end-user.
        // TODO: MIGHT WANT TO LOG THE INFORMATION FROM error.error;
        apiErrorResponse.Errors.push(
          new ApiErrorMessage(
            `The API returned an unsuccessful response. ${error.status}: ${error.statusText}. ${error.message}`,
            false,
            null
          )
        );
        return throwError(apiErrorResponse);
      }
    }
  }
}

Using the HTTP Service

If the processing of business rules and/or data validation goes well in the business layer of the application the next task to follow is typically an HTTP request to either retrieve, save, or update some information. Each domain vertical probably has a distinct set of Web API calls. Create a new service to handle the specific HTTP requests. An @Injectable service for HTTP calls is injected into a business provider within the specific domain service. A service of this type could also be the recipient of configuration information that includes base URL or other information required to execute the request.

The sample domain-specific HTTP service below contains an injected HttpService. The LoggingService cross-cutting concern is also available for this service. Reusing code creates such a good feeling, right? There are only a few things to do to perform an HTTP operation:

configure the URL endpoint for the request
setup the options for the request (uses the URL)
execute the request using the new HttpService.

Note the simplicity in the following example of an application's HTTP service for the ThingsToDo domain feature. Consistent code is maintainable code - it is also easier to identify any deviations early.

import { Injectable, Inject } from '@angular/core';
import { Observable } from 'rxjs';
import { HttpClient } from '@angular/common/http';

import { ApiResponse, ServiceBase } from '@tc/foundation';
import { HttpService, HttpRequestMethod } from '@tc/http-service';
import { LoggingService } from '@tc/logging';
import { IThingsToDoHttpService } from './i-things-to-do-http.service';

@Injectable({
  providedIn: 'root',
})
export class ThingsToDoHttpService extends ServiceBase
  implements IThingsToDoHttpService {
  baseUrl = 'http://mybackend.com/api/';
  noCredentials = false;
  credentialsRequired = true;

  constructor(
    @Inject(HttpService) public httpService: HttpService,
    public loggingService: LoggingService
  ) {
    super(loggingService, 'ThingsToDoHttpService');
  }

  RetrieveThingsToDo<T>(): Observable<ApiResponse<T>> {
    const requestUrl = this.baseUrl.concat('things');
    const options = this.httpService.createOptions(
      HttpRequestMethod.get,
      this.httpService.createHeader(),
      requestUrl,
      null,
      this.noCredentials
    );
    return this.httpService.execute<T>(options);
  }
}

The use and implementation of an interface IThingsToDoHttpService are totally optional. There may be a case to use such a feature during initial development when the real API is not available or online.

import { Observable } from 'rxjs';
import { ApiResponse } from '@tc/foundation';

export interface IThingsToDoHttpService {
  /**
   * Use to retrieve things to do.
   */
  RetrieveThingsToDo<T>(): Observable<ApiResponse<T>>;
}

An interface-based approach allows you to create a fake HTTP service to provide an implementation that returns fake data. There are many different approaches to using and creating fake data from an API. Interfaces may make the implementation a little easier.

import { Injectable } from '@angular/core';

import { Observable, of, BehaviorSubject, throwError } from 'rxjs';
import { ThingToDo } from '../models/thingToDo.model';
import { IThingsToDoHttpService } from './i-things-to-do-http.service';

import {
  ApiResponse,
  ServiceBase,
  SuccessApiResponse,
  ErrorApiResponse,
  ApiErrorMessage,
} from '@angularlicious/foundation';
export class ThingsToDoFakeHttpService implements IThingsToDoHttpService {
  things: ThingToDo[] = [];

  RetrieveThingsToDo<T>(): Observable<ApiResponse<T>> {
    const response = new SuccessApiResponse();
    response.IsSuccess = true;
    response.Message = 'Successfully processed request for things.';
    response.Timestamp = new Date(Date.now());
    response.Data = this.loadThings();

    const subject: BehaviorSubject<any> = new BehaviorSubject(response);
    return subject.asObservable();
  }

  loadThings() {
    this.things = [];
    this.things.push(
      new ThingToDo(
        1,
        'Denver Taco Festival',
        'RiNo',
        'Eat tacos with your friends and some many Chihuahuas.'
      )
    );
    this.things.push(
      new ThingToDo(
        2,
        'Smooth Jazz Concert',
        'Arvada, CO',
        'Listen to Kenny G play his favorites.'
      )
    );

    return this.things;
  }
}

The feature module can provide the correct HTTP service based on the environment of the application runtime. The sample below demonstrates providing a service with the useClass and a ternary operator to determine which service to load: fake or real?

@NgModule({
  declarations: [VisitorIndexComponent, ThingsToDoComponent],
  imports: [
    CommonModule,
    SharedModule,
    SiteComponentsModule,
    VisitorRoutingModule,
  ],
  providers: [
    // ThingsToDoService, // NOT PROVIDED HERE, EACH COMPONENT REQUIRES A DISTINCT INSTANCE
    ThingsToDoBusiness,
    {
      provide: 'IThingsToDoHttpService',
      useClass: environment.production
        ? ThingsToDoHttpService
        : ThingsToDoFakeHttpService,
    },
  ],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class VisitorModule {}

Handle HTTP Errors

Errors fall into the category of when and not if. It is only a matter of time and circumstance that there will be an error during the operation of an HTTP request. Handling errors is a common practice and discipline in programming. We can hope that errors never occur- however, hope is never a good strategy for most things in life. A little preparation and forward-thinking will make the application safer.

Many times, the error is from the back end of an application - the Web API. If an error occurs on the back end, you typically get a 400 or 500 status code from the server. However, during the processing of an HTTP request, it is possible to get an error related to the processing of the HTTP request or the response. Basically, there is a lot of opportunity for things to go wrong.

Note: This is a specialized handling of errors to use the Observable pattern while performing HTTP operations.

Do not be tempted to use HttpClient calls directly in your application components. We need a more reliable, consistent, and maintainable mechanism to handle errors while performing actions that use HTTP and Observables. It is also not an ideal situation to display raw error information to users.

For example, when using HttpClient you can call the request() method. Using the RxJs pipe() you can also use the catchError() which returns an HttpErrorResponse to be handled. Handling an error in a single location (not in the component Observable response) allows for greater control - it is also contained in a single location. I know this from experience, A current project that I joined after almost 3 years of development has approximately 200 variations of making HTTP calls and handling responses. The number of variations of error handling in this code is mind-boggling considering that only 2 developers implemented the API calls. Therefore, please consider the following principles in regard to error handling.

single-responsibility
DRY: don't repeat yourself
separation of concerns

Pro Tip: There are many ways to handle errors. Some of the implementation details may be specific
to the technology. Become familiar with error and exception handling practices.

Here are the goals for handling the error:

inspection: proactively expect exceptions and provide a mechanism to catch them

interpretation: provide some information local to the error that gives meaning and context to the error

resolution: catch and handle unexpected errors or exceptions; provide information to user or application that > helps mitigate or resolve an issue

The sample code below expects that there may be an error while processing the request. If an HTTP error happens, it will attempt to retry the operation at least once with retry(1) in the Observable pipeline. If there continues, it will be caught with the catchError() RxJS pipeline operation and handled. Handling HTTP errors is a specialized process because the process needs to determine the source of the error to engage the proper handling path. More information about Handling HTTP Errors.

execute<T>(requestOptions: HttpRequestOptions): Observable<HttpResponse<ApiResponse<T>>> {
    try {
      return this.httpClient.request<T>(
        requestOptions.requestMethod.toString(),
        requestOptions.requestUrl,
        {
          headers: requestOptions.headers,
          observe: requestOptions.observe,
          params: requestOptions.params,
          reportProgress: requestOptions.reportProgress,
          withCredentials: requestOptions.withCredentials
        }
      ).pipe(
        retry(1)
        catchError((errorResponse: any) => {
          return this.handleError(errorResponse);
        })
      );
    } catch (error) {
      this.handleError(error);
    }
  }

The HttpErrorResponse contains details to determine the source of the error. Was it from the server/http or from within the application. This helps us to determine what type of information to provide the user if any. At a minimum, you could log this information to help monitor the health of the application and determine if any improvements should be made.

I updated the signature of the handleError() method to include either type of Error or type of HttpErrorResponse - this allows for specialized handling based on the type of error.

protected handleError(error: Error | HttpErrorResponse): Observable<any> {
  if(error.error instanceof ErrorEvent)  {
    // A client-side or network error occurred. Handle it accordingly.
  } else {
      // The API returned an unsuccessful response.
  }
  // handler returns an RxJS ErrorObservable with a user-friendly error message.
  // Consumers of the service expect service methods to return an Observable of
  // some kind, even a "bad" one.
  //
  // return throwError(error);
  return throwError(`Hey, you got my chocolate in your peanut butter.`);
}

Notice that the HttpErrorResponse type implements Error. Therefore, it contains information about the HTTP Request and also error information. These classes are already part of the Angular error handling eco-system. We can leverage the use of these types to create a more robust error handling flow for our applications.

class HttpErrorResponse extends HttpResponseBase implements Error {
  constructor(init: {...})
  get name: 'HttpErrorResponse'
  get message: string
  get error: any | null
  get ok: false

  // inherited from common/http/HttpResponseBase
  constructor(init: {...}, defaultStatus: number = 200, defaultStatusText: string = 'OK')
  get headers: HttpHeaders
  get status: number
  get statusText: string
  get url: string | null
  get ok: boolean
  get type: HttpEventType.Response | HttpEventType.ResponseHeader
}

The abstract base class for the HttpResponse provides the structure for other HTTP Response classes:

HttpErrorResponse
HttpHeaderResponse
HttpResponse

abstract class HttpResponseBase {
  constructor(init: {...}, defaultStatus: number = 200, defaultStatusText: string = 'OK')
  get headers: HttpHeaders
  get status: number
  get statusText: string
  get url: string | null
  get ok: boolean
  get type: HttpEventType.Response | HttpEventType.ResponseHeader
}

HTTP Error Processing

As mentioned previously, processing HTTP errors during Web API operations involve Observables. We will use the RxJS catchError() and then handle the error. The source of the error may be from the status code of the HTTP response or it may be a more generalized JavaScript error while attempting to send the request or handle the response. Therefore, we will need to determine the source of the error.

The handleError() implementation will determine what to do with the response. If the HTTP response status code is in an error state and the body of the response is in the expected ErrorApiResponse format, we can simply use the RxJS throwError() and send it on its way for handling by the consumer of the API.

If the error doesn't contain a body in our expected format, we can wrap the error information into the expected format (generic message) and send it forward.

import { Injectable } from "@angular/core";
import { HttpRequestMethod } from "./http-request-methods.enum";
import {
  HttpHeaders,
  HttpClient,
  HttpResponse,
  HttpErrorResponse
} from "@angular/common/http";
import { HttpRequestOptions } from "./http-request-options";
import { Observable, throwError } from "rxjs";
import { catchError, retry } from "rxjs/operators";
import { ApiResponse } from "@angularlicious/foundation";
import { ErrorApiResponse } from "@angularlicious/foundation";
import { ApiErrorMessage } from "@angularlicious/foundation";

@Injectable()
// { providedIn: 'root', }
export class HttpService {
  constructor(private httpClient: HttpClient) {}

  /**
   * Use to create [options] for the API request.
   * @param method Use to indicate the HttpRequest verb to target.
   * @param headers Use to provide any [HttpHeaders] with the request.
   * @param url Use to indicate the target URL for the API request.
   * @param body Use to provide a JSON object with the payload for the request.
   * @param withCredentials Use to indicate if request will include credentials (cookies), default value is [true].
   */
  createOptions(
    method: HttpRequestMethod,
    headers: HttpHeaders,
    url: string,
    body: any,
    withCredentials: boolean = true
  ): HttpRequestOptions {
    let options: HttpRequestOptions;
    options = new HttpRequestOptions();
    options.requestMethod = method;
    options.headers = headers;
    options.requestUrl = url;
    options.body = body;
    options.withCredentials = withCredentials;
    return options;
  }

  /**
   * Use to create a new [HttpHeaders] object for the HTTP/API request.
   */
  createHeader(): HttpHeaders {
    let headers = new HttpHeaders();
    headers = headers.set("Content-Type", "application/json");
    return headers;
  }

  /**
   * Use to execute an HTTP request using the specified options in the [HttpRequestOptions].
   * @param requestOptions
   */
  execute<T>(requestOptions: HttpRequestOptions): Observable<ApiResponse<T>> {
    console.log(
      `Preparing to perform request to: ${requestOptions.requestUrl}`
    );
    return this.httpClient
      .request<T>(
        requestOptions.requestMethod.toString(),
        requestOptions.requestUrl,
        {
          body: requestOptions.body,
          headers: requestOptions.headers,
          reportProgress: requestOptions.reportProgress,
          observe: requestOptions.observe,
          params: requestOptions.params,
          responseType: requestOptions.responseType,
          withCredentials: requestOptions.withCredentials
        }
      )
      .pipe(
        retry(1),
        catchError((errorResponse: any) => {
          return this.handleError(errorResponse);
        })
      );
  }

  /**
   * Use to handle errors during HTTP/Web API operations. The caller expects
   * an Observable response - this method will either return the response from
   * the server or a new [ErrorApiResponse] as an Observable for the client to
   * handle.
   *
   * @param error The error from the HTTP response.
   */
  protected handleError(error: HttpErrorResponse): Observable<any> {
    const apiErrorResponse = new ErrorApiResponse();
    apiErrorResponse.IsSuccess = false;
    apiErrorResponse.Timestamp = new Date(Date.now());
    apiErrorResponse.Message = "Unexpected HTTP error.";

    if (error.error instanceof ErrorEvent) {
      // A client-side or network error occurred. Handle it accordingly.
      apiErrorResponse.Errors.push(
        new ApiErrorMessage(
          `A client-side or network error occurred. Handle it accordingly.`,
          true,
          null,
          null
        )
      );
      return throwError(apiErrorResponse);
    } else {
      // The API returned an unsuccessful response.
      if (error instanceof ErrorApiResponse) {
        // A known error response format from the API/Server; rethrow this response.
        return throwError(error);
      } else {
        // An unhandled error/exception - may not want to lead/display this information to an end-user.
        // TODO: MIGHT WANT TO LOG THE INFORMATION FROM error.error;
        apiErrorResponse.Errors.push(
          new ApiErrorMessage(
            `The API returned an unsuccessful response. ${error.status}: ${error.statusText}. ${error.message}`,
            false,
            null,
            error.status.toString()
          )
        );
        return throwError(apiErrorResponse);
      }
    }
  }
}