DEV Community: Juan Oliú

A Practical Approach to Error Handling in Express.js

Juan Oliú — Mon, 18 Sep 2023 13:41:03 +0000

Motivation

In the intricate world of software development, errors are inevitable. They emerge from various sources: unforeseen edge cases, unexpected user inputs, or even overlooked developer mistakes. While it's impossible to predict every potential error, how we handle these errors can make a significant difference in the user experience and the maintainability of our projects.

In my experience with Node.js and Express, I've noticed that projects often face challenges in two main areas: pinpointing all possible error scenarios for a feature and handling those exceptions. While the skill level of developers is a factor, it's common in multiple projects to encounter similar error scenarios. Identifying these recurring patterns can help in creating standardized methods for error management.

In this article, I'll share my approach to error management, inspired by my experiences and the practices I've adopted in recent Node.js projects with Express. Furthermore, I'll delve into how GraphQL, particularly Apollo GraphQL, has influenced my perspective on error handling in RESTful applications.

GraphQL inspiration

From now on I have to say that I am a big fan of Apollo GraphQL, I love how the paradigm defines an API in the form of a resource graph, the way in which that conditions the architecture of the server and among other things I really like the way on how it handles errors. Let's stop at this last point and discuss this before continuing with error handling in Express.

In GraphQL, and therefore in Apollo, the philosophy of error handling differs from the traditional approach based on HTTP status messages. There are some reasons why Apollo and other GraphQL servers do not primarily rely on HTTP status codes to convey details about errors

More Detailed Responses: GraphQL allows a response to include both data and errors. That is, part of your query could fail while other parts could succeed. In an HTTP-based approach, you would have to choose a single status code to represent the entire response, which wouldn't capture the mixed nature of the GraphQL response.
Nature of GraphQL Operations: A single GraphQL request can include multiple operations affecting different areas of your schema. If one of these operations fails and another succeeds, what HTTP status code should you return? GraphQL solves this problem by providing field-level errors.
Granularity: With GraphQL, you can specify errors at the field level, allowing you to provide very specific information about which part of the query failed and why. This granularity would be lost if relying solely on general HTTP status codes.
Client Interoperability: GraphQL clients, like Apollo Client, expect to handle errors in the standardized GraphQL format and not through HTTP status codes. This allows clients to handle errors in a more uniform and detailed manner.
Flexibility and Customization: While GraphQL has a standardized format for errors, it is also flexible. You can add additional fields to your errors (such as "code" or "context") to convey more information to clients based on the needs of your application.

First of all, let's not lose sight of the fact that GraphQL and Rest API obey different paradigms, which makes it unnatural or rather a very bad practice to model errors in the same way. Even so, I have to say that of all these advantages there are some very interesting ones that I felt I could rescue for a server with a Rest API.

On one hand, I really like the idea of loading data along with the error message, perhaps not for the response itself but to send to an error tracking platform in the event of some types of exceptions, we will talk about this later.

On the other hand, I find the interoperability that we could generate with the client interesting by defining errors in a more personalized way following certain standards. That is, we should not use the http status so much but rather a more descriptive error code and at the same time be able to define something that allows us to group them into more abstract categories.

Pay attention to the built-in error codes defined by Apollo server:

Built-in error codes

CODE	DESCRIPTION
`GRAPHQL_PARSE_FAILED`	The GraphQL operation string contains a syntax error.
`GRAPHQL_VALIDATION_FAILED`	The GraphQL operation is not valid against the server's schema.
`BAD_USER_INPUT`	The GraphQL operation includes an invalid value for a field argument.
`PERSISTED_QUERY_NOT_FOUND`	A client sent the hash of a query string to execute via automatic persisted queries, but the query was not in the APQ cache.
`PERSISTED_QUERY_NOT_SUPPORTED`	A client sent the hash of a query string to execute via automatic persisted queries, but the server has disabled APQ.
`OPERATION_RESOLUTION_FAILURE`	The request was parsed successfully and is valid against the server's schema, but the server couldn't resolve which operation to run.
	This occurs when a request containing multiple named operations doesn't specify which operation to run (i.e.,operationName), or if the named operation isn't included in the request.
`BAD_REQUEST`	An error occurred before your server could attempt to parse the given GraphQL operation.
`INTERNAL_SERVER_ERROR`	An unspecified error occurred.
	When Apollo Server formats an error in a response, it sets the code extension to this value if no other code is set.

Let's leave aside those that apply to GraphQL concepts and emphasize in the others. Take a look at them BAD_USER_INPUT, BAD_REQUEST and INTERNAL_SERVER_ERROR, this kind of level of abstraction is something we can use for categorizing errors in a Rest API server.

Let's stick with this idea. In the next section, we'll discuss the different types of errors we can generate to replicate a somewhat similar behavior.

Custom Error Classes

Custom error classes can help standardize error responses and provide better context for debugging and the the frontend present exceptions to the final user.

Let's start with the following class:

HttpError Class

The HttpError class serves as the base class for your custom error hierarchy. It encapsulates key error attributes and behaviors.

class HttpError extends Error {
  constructor(status, name, message, extra) {
    super(message);
    this.status = status;
    this.name = name;
    this.extra = extra;
  }
}

Let's define a set of classes to group different types of errors based on their nature. Among other things, they will all share a code as a common property to identify them. The code should be descriptive enough for a developer to understand what it refers to; by convention, we will write it in UPPER_CASE. Note that I mentioned it should be descriptive enough for a developer, not the end user. Please never use the error message from a server response as a message for the end user. The right approach would be to process it and generate one that better fits the language and context an average user would understand. Let's never lose sight of the fact that developers and users don't speak, and shouldn't speak, the same language; we operate in different contexts. Something similar happens between frontend and backend.

Returning to our custom error classes, these are the ones we will initially use. Please take this as a suggestion and not as a golden rule.

Custom Error Classes

These classes extend the HttpError class to represent specific error types, providing predefined error codes, names, and messages.

class UserInputError extends HttpError {
  constructor(message, extra) {
    super(400, "Bad Request", message, extra);
  }
}

class AuthenticationError extends HttpError {
  constructor(message, extra) {
    super(401, "Unauthorized", message, extra);
  }
}

class ForbiddenError extends HttpError {
  constructor(message, extra) {
    super(403, "Forbidden", message, extra);
  }
}

class NotFoundError extends HttpError {
  constructor(message, extra) {
    super(404, "Not Found", message, extra);
  }
}

class InternalServerError extends HttpError {
  constructor(message, extra) {
    super(500, "Internal Server Error", message, extra);
  }
}

Descriptions:

UserInputError: This error class is used to indicate that the user's input or request is invalid. It corresponds to the HTTP status code 400 (Bad Request). It's typically triggered when the user submits data that doesn't meet the required criteria.
AuthenticationError: This error class represents authentication failures. It's used when a user's credentials are invalid or missing, and corresponds to the HTTP status code 401 (Unauthorized).
ForbiddenError: This error class signifies that the user's request is valid but they don't have the necessary permissions to access the requested resource. It maps to the HTTP status code 403 (Forbidden).
NotFoundError: When the requested resource is not found on the server, the NotFoundError class is employed. This corresponds to the HTTP status code 404 (Not Found).
InternalServerError: This error class is a catch-all for unexpected server errors that occur during the request processing. It corresponds to the HTTP status code 500 (Internal Server Error).

As you can see, this covers the more generic error cases and leads us to a simple way of cataloging the errors.

Naturally, one might wonder, now that we have our error classes, how do we use them? Fortunately, we can make use of Express middlewares for this purpose.

Error handling within a middleware

We will define our own middleware to capture errors and present them appropriately in the response, as well as trigger the necessary actions should the situation warrant it.

Before doing so, let us remember that we consider it pertinent to make a brief mention of what Express middlewares are. I have to assume that many of the readers might not know them, and for those who do, a review never hurts.

Express middleware functions

Middleware functions are functions that have access to the request object (req), the response object (res), and the next middleware function in the application’s request-response cycle. The next middleware function is commonly denoted by a variable named next.

Middleware functions can perform the following tasks:

Execute any code. This allows you to add any functionality or processing you want to occur during the request-response cycle.
Make changes to the request and the response objects. This can be useful for things like parsing request bodies, setting response headers, etc.
End the request-response cycle. If a middleware function does not call next(), the cycle will be terminated, and the response will be sent to the client.
Call the next middleware function in the stack. If a middleware function does not end the request-response cycle, it must call next() to pass control to the next middleware function. Otherwise, the request will be left hanging.

Types of Middleware:

Application-level middleware: This binds middleware to the app object using app.use() and app.METHOD(), where METHOD is the HTTP method.

   app.use(function (req, res, next) {
     console.log("Time:", Date.now());
     next();
   });

Router-level middleware: This works in the same way as application-level middleware, but it's bound to an instance of express.Router().

   const router = express.Router();
   router.use(function (req, res, next) {
     console.log("Time:", Date.now());
     next();
   });

Error-handling middleware: This is used to handle errors in Express apps. Error-handling middleware always takes four arguments. You must provide four arguments to identify it as an error-handling middleware function.

   app.use(function (err, req, res, next) {
     console.error(err.stack);
     res.status(500).send("Something broke!");
   });

Built-in middleware: Express has a few built-in middleware functions, such as express.static to serve static files.

   app.use(express.static("public"));

Third-party middleware: There are many third-party middleware modules available, like body-parser for parsing request bodies, morgan for logging, cors for handling CORS, etc.

   const bodyParser = require("body-parser");
   app.use(bodyParser.json());

Using Middleware:

To use a middleware, you typically call app.use(). The order in which middleware is defined matters, as they are executed sequentially. For example, if you place a logging middleware above a route, the logging will occur before the route's logic is executed. If you place it below, the logging will occur after.

Example:

Here's a simple example to illustrate middleware in action:

const express = require("express");
const app = express();

// Middleware 1: Logging
app.use((req, res, next) => {
  console.log("Middleware 1: Logging request details");
  next();
});

// Middleware 2: Add a property to the request
app.use((req, res, next) => {
  req.sampleProperty = "Hello from Middleware 2";
  next();
});

// Route handler
app.get("/", (req, res) => {
  res.send(req.sampleProperty); // This will send 'Hello from Middleware 2'
});

app.listen(3000, () => {
  console.log("Server started on port 3000");
});

In this example, when a request is made to the root route (/), both middleware functions are executed in order, followed by the route handler.

In summary, middleware in Express.js provides a powerful way to add functionality and handle various aspects of the request-response cycle. By chaining middleware functions, you can build complex and efficient web applications.

Let us pay special attention to the third case because it is the one that we will define below.

Custom Middlewares for Error Handling

We will use 2. The first will be responsible for triggering special actions given some error cases, such as in the event of an internal server error we would like to log it and report it to an error-tracking platform. At the same time, it will also be in charge of wrapping any error that it intercepts whose class is not part of any of the ones we defined.

The second middleware is only responsible for generating the request message from the error instance. Here it is important to have defined our "abstract class" HttpError.

`errorConverter` Middleware

const errorConverter = (
  error: Error | HttpError | ValidateError,
  _req: Request,
  _res: Response,
  next: NextFunction
) => {
  if (error instanceof InternalServerError) {
    logError(error.name, error.extra);
  }
  if (error instanceof ForbiddenError) {
    if (error.extra) logError(error.name, error.extra);
  }
  if (error instanceof HttpError) {
    if (error.extra) logError(error.name, error.extra);
    next(error);
  } else if (error instanceof ValidateError) {
    next(new UserInputError(formatFields(error.fields)));
  } else {
    next(new InternalServerError(error.message));
  }
};

`errorHandler` Middleware

const errorHandler = (
  error: HttpError,
  _req: Request,
  res: Response,
  _next: NextFunction
) => {
  res.status(error.status).send({
    status: error.status,
    message: error.message,
    name: error.name,
  });
};

Logger module

As you may have noticed within the errorConverter module, I used a logError function. Normally I like defining in my projects a module in charge of centralizing all log functions in charge of reporting all the exceptions or warns as well as error-tracking platforms reports.

Of course it is not something you have to do but it is something I strongly recommend. I'll leave an example not so different from the ones I have used lately that has already integration with Sentry:

import * as Sentry from "@sentry/node";
import { Event } from "@sentry/types";

import { environment } from "../common/environment";

export type Extra = Record<string, unknown>;

enum Severity {
  Debug = "debug",
  Error = "error",
  Fatal = "fatal",
  Info = "info",
  Log = "log",
  Warning = "warning",
}

const logToSentry = (level: Severity, message: string, extra?: Extra) => {
  if (environment.isDevelopment) {
    const optionalArgs = extra ? [extra] : [];
    if (level === Severity.Error) {
      console.error(message, ...optionalArgs);
      return;
    }
    if (level === Severity.Warning) {
      console.warn(message, ...optionalArgs);
      return;
    }

    console.log(message, ...optionalArgs);
    return;
  }

  const event: Partial<Event> = {
    extra,
    level,
    message,
  };
  try {
    Sentry.captureEvent(event);
  } catch (error) {
    console.error("Could not log to Sentry", message, extra, error);
  }
};

export const logFatal = (title: string, details?: Extra) => {
  logToSentry(Severity.Fatal, title, details);
};

export const logError = (title: string, details?: Extra) => {
  logToSentry(Severity.Error, title, details);
};

export const logWarning = (title: string, details?: Extra) => {
  logToSentry(Severity.Warning, title, details);
};

export const logInfo = (title: string, details?: Extra) => {
  logToSentry(Severity.Info, title, details);
};

Conclusion

Error handling is an indispensable aspect of building robust and user-friendly applications. In the realm of Node.js with Express, it's not just about catching errors, but also about understanding, categorizing, and appropriately responding to them. Drawing inspiration from GraphQL's detailed and granular error handling, we can adopt a more structured approach in our RESTful APIs. By defining custom error classes, we not only standardize error responses but also provide a clearer context for debugging and user feedback.

Furthermore, the use of Express middlewares offers a seamless way to intercept and process these errors. This ensures that our application remains resilient, even when faced with unexpected issues. Integrating logging mechanisms, such as Sentry, further enhances our ability to monitor and address potential pitfalls in real-time.

In essence, a well-thought-out error handling strategy is akin to a safety net for our applications. It ensures that when things go awry, the impact is minimal, the feedback is clear, and the path to resolution is well-defined. As developers, it's our duty to ensure that our applications not only function but also fail gracefully. Through the techniques discussed in this post, we can take a significant step towards achieving that goal.

Special mention

I want to give a big shoutout to @joaguirrem. The ideas behind this system started when we worked on a project together about a year and a half ago. If anyone deserves a pat on the back for this, it's him. Building software is a team effort, and it's always great to work with talented folks like Joaquin. They make the work better and the journey more enjoyable.

TypeScript Type Guards: An Introduction to Writing Safer Code

Juan Oliú — Sun, 03 Sep 2023 19:33:22 +0000

In a recent project, I was tasked with creating an endpoint that would parse and process files generated by the firmware of a device from a trained neural network.

The device would send a JSON file through a REST API inside a Node.js backend using a multi-part algorithm. Up until that point, the task seemed straightforward.

But as I began working on the logic, I realized it would be tricky to assume that the function responsible for processing the input would always receive the expected input.

That's when I started exploring the potential of TypeScript type guards, which would help me ensure the input's expected shape and avoid runtime errors.

Limitations of Static Type Checking

TypeScript enables you to perform static type-checking validations in compile time. This works very well as long as we are dealing with functions that accept inputs whose values have resulted from evaluating expressions within the application's scope.

Now, what happens when we receive certain values that come from beyond the border of our system? Think of it as the result of database queries, requests to external APIs, and Bluetooth communications with other devices to name a few. In these scenarios, we should never assume anything about what the incoming data will be like because if we do, we would be generating a bias that could lead to unexpected behavior within the system.

So what do we do in these situations? Should we leave it to faith and watch it fail if the input type is not the one we expected? Thankfully, TypeScript offers us very powerful tools to perform type validation at runtime for these scenarios.

Any type behavior and potential issues

Taking into account what I stated above, let's suppose I don't want to assume anything from the parsing function's input. How should I type it then? One could easily be inclined to want to use an any type.

Is there a problem with it? Pay attention to what happens when we want to access a property of an any type. First, let's take a look at this:

class Dog {
  name: string;
  constructor(name: string) {
    this.name = name;
  }

  bark() {
    console.log("Woof woof");
  }
}

class Fish {
  name: string;
  constructor(name: string) {
    this.name = name;
  }

  swim() {
    console.log("Splash splash");
  }
}

const scooby = new Dog("Scooby Doo");
const nemo = new Fish("Nemo");

scooby.bark();
nemo.swim();
nemo.bark(); // ❌ Property 'bark' does not exist on type 'Fish'.

If we try to call the bark fn from a Fish instance we will clearly get an exception since the class Fish does not bark.

Now let's see what happens by slightly changing the variables declaration.

const nemo: any = new Fish("Nemo");

nemo.swim();
nemo.bark(); // ✅ None compile errors.

// On execution:
// ❌ [ERR]: "Executed JavaScript Failed:"
// ❌ [ERR]: nemo.bark is not a function

Since the beginning, we knew this was destined to happen. But why is this so? Just as we inferred it, TypeScript's compiler should have been able to do it too.

Let's go to the definition of the any type:

TypeScript also has a special type, any, that you can use whenever you don’t want a particular value to cause type-checking errors.

When a value is of type any, you can access any properties of it (which will in turn be of type any), call it like a function, assign it to (or from) a value of any type, or pretty much anything else that’s syntactically legal.

As we can notice, the any type is intended to be used when you desire to avoid static type checking on variables. With this in mind, we should avoid using this type in almost all scenarios.

So if the any type doesn't work for typing something we have no information about, is there another type that allows us to do this?

The `unkonwn` type

In Typesscript 3.0 the unkonwn type was introduced. You can think of it as the type-safe counterpart of the any type. How? Although we use both of them to type those values we know nothing about, the main difference is that unknown is much more restrictive in the sense that any property you want to access or almost any kind of operator you want to use it with, will result in a compiler error.

Taking the previous case as a reference:

const nemo: unknown = new Fish("Nemo");

nemo.swim(); // ❌ 'nemo' is of type 'unknown'.
nemo.bark(); // ❌ 'nemo' is of type 'unknown'.

The obvious thing would be to ask ourselves: if something of the unknown type is not allowed to use operators of any kind or access its properties, what’s the point of using it?

This gives us the ground to introduce the type guards.

Introduction to `type guards`

People often confuse a dynamically typed language with the absence of types.

Are there types in Javascript? Of course there are, if you have any doubts, evacuate them right now by opening the console of your browser and executing a simple sentence:

var x = 5;
typeof x; // 'number'

If Javascript provides operators to perform type validations, it would be interesting if it could make some assumptions regarding the type of a variable within certain flows. Type guards along the unknown type can be used for these scenarios.

Let's see it in action:

// Without using type guards
function isOdd(x: unknown) {
  return x % 2 === 0; // ❌ 'x' is of type 'unknown'
}

// Using type guards
function isOdd(x: unknown) {
  if (typeof x !== "number") return false;

  return x % 2 === 0; // ✅ None compile errors.
}

We just found a way of restricting the type of a given variable. In TypeScript we can identify five different ways to use type guards:

The instanceof keyword
The typeof keyword
The in keyword
Equality narrowing type guard
Custom type guard with predicate

I won't be analyzing the first 4, but feel free to access the documentation, where they are explained in detail. Let's emphasize the ‘Custom’ ones with a predicate.

Custom type guards

Although there will be scenarios in which we cannot make any inference in the lexical and syntactic analysis, a series of additional guidelines may allow us to unequivocally distinguish if something is of a particular type.

A clear example would be the enum values. Suppose we had an enumeration to define the different sizes of a popcorn package and we wanted to evaluate if for a given value, for example coming from an external API call, we would need to evaluate if it is indeed a Popcorn's enum value.

How do we do it? TypeScript enables us to turn any predicate function into a custom type guard through the use of the is operator.

export enum PopCornSize {
  Small = "Small",
  Medium = "Medium",
  Large = "Large",
}

const isPopCornSize = (size: unknown): size is PopCornSize =>
  Object.values(PopCornSize).includes(size as PopCornSize);

This is more than clear that to prove something is a member of an enumeration. You just have to check if its value matches any of the values of the enum.****

Wrapping it all together through an example

Let's summarize everything we've cover up until now through a simplified, real-life case:

We have a machine for medical use that monitors a patient's heart pressure and how much they are moving.

The heart rate is measured in BPS while the movement is measured through various types of sensors, generating a discrete value that can be either 0, 1, or 2 which correspond to "LOW", "MEDIUM" and "HIGH" respectively.

This machine records these metrics periodically and generates a JSON with the report of the traces on-demand. Each one, along with its value, is recorded as a timestamp in epoch with the time at which it was recorded.

The format is as described below:

{
  "log_uuid": 141,
  "version": 0,
  "user_metrics": [
    { "ts": 1673550600, "evt": 1, "val": 63 },
    { "ts": 1673550600, "evt": 2, "val": 1 },
    { "ts": 1673550630, "evt": 1, "val": 71 },
    { "ts": 1673550630, "evt": 2, "val": 0 },
    { "ts": 1673550660, "evt": 1, "val": 69 },
    { "ts": 1673550660, "evt": 2, "val": 2 },
    { "ts": 1673550690, "evt": 1, "val": 66 }
  ]
}

While the expected data format may be documented, there is still a risk of receiving unexpected data or experiencing malfunctions if the firmware team makes changes without proper notification.

How can we confirm that the file is indeed a JSON file? To ensure its integrity, let's begin by performing a validation check.

export const parseSleepSession = (file: Express.Multer.File): SleepSession => {
  const fileStr = file.buffer.toString();

  if (typeof fileStr !== "string") {
    throw new ForbiddenError("INVALID_JSON_FILE", { file: file.buffer });
  }

  const rawJson = JSON.parse(fileStr) as unknown;

  if (
    rawJson === null ||
    typeof rawJson !== "object" ||
    Array.isArray(rawJson)
  ) {
    throw new ForbiddenError("INVALID_JSON_FILE", { rawJson });
  }
};

It's important to note that if anything in the JSON file doesn't match our expected format, the program will immediately return an exception with an error code and log it along with the file. While the logging process itself may not be noticeable, it's crucial for debugging purposes. Personally, I like to configure a middleware that captures exceptions and, depending on certain circumstances, reports them to a platform such as Sentry.

Now that we know that the file is JSON, let's continue by validating the first two fields. Given the concepts we covered earlier this should be trivial by now.

const id = (rawJson as RawSleepMetrics).log_uuid as unknown;
const version = (rawJson as RawSleepMetrics).version as unknown;
const userMetricsRaw = (rawJson as RawSleepMetrics).user_metrics as unknown;

if (typeof id !== "number") {
  throw new ForbiddenError("INVALID_ID", { id, rawJson });
}

if (typeof version !== "number") {
  throw new ForbiddenError("INVALID_VERSION", { rawJson, version });
}

The typeof operator is a type guard, so it will be enough to validate that they are numeric fields. Keep in mind that we will limit ourselves to validating the correctness of the document format. The fact that the identifier might already exist for a previously parsed file or any other type of validation that refers to the business logic will escape the scope of these validations.

Let's continue with the user_metrics array. Let's validate that the field exists and that it really is an array.

const userMetricsRaw = (rawJson as RawSleepMetrics).user_metrics as unknown;

if (isNil(userMetricsRaw)) {
  throw new ForbiddenError("USERMETRICS_MISSING", { rawJson });
}

if (!Array.isArray(userMetricsRaw)) {
  throw new ForbiddenError("USERMETRICS_NOT_AN_ARRAY", {
    rawJson,
    userMetricsRaw,
  });
}

The statements in the block above translates to the following:

A property exists with that key.
Its value is not null.
The value is an array.

Simple, right? Let's continue with the content of user_metrics.

const activityScore: ActivityScoreRegistry[] = [];
const heartRateMonitor: HeartRateMonitorRegistry[] = [];

userMetricsRaw.forEach((currMetric: unknown) => {
  if (
    currMetric === null ||
    typeof currMetric !== "object" ||
    Array.isArray(currMetric)
  ) {
    throw new ForbiddenError("USER_METRIC_INVALID", { currMetric, rawJson });
  }

  const timestampEpoch = (currMetric as RawMetricRecord).ts as unknown;
  const metric = (currMetric as RawMetricRecord).evt as unknown;
  const value = (currMetric as RawMetricRecord).val as unknown;
});

Let's start by validating that the timestamp is indeed a date. This can be tricky for a number of reasons. First, by epoch we usually refer to the count of seconds elapsed from January 1, 1970 to date, although some languages define it as the count of milliseconds (between them JS).

On the other hand, the JS Date class allows you to pass an epoch to the constructor as a way to initialize an instance. The cheat of JS that comes from the fact that it was created under the paradigm that nothing should be broken on the web is that if we were to happen to it something that was not a valid epoch, far from returning an exception, what would happen is that it would return a value, numeric NaN. With which the validation will look a bit peculiar, but we will come to something like this:

if (typeof timestampEpoch !== "number") {
  throw new ForbiddenError("INVALID_TIMESTAMP", { rawJson, timestampEpoch });
}

if (!isEpochInSeconds(timestampEpoch)) {
  throw new ForbiddenError("INVALID_TIMESTAMP_NOT_IN_EPOCH_SECONDS", {
    rawJson,
    timestampEpoch,
  });
}

const timestamp = new Date(timestampEpoch * 1000);
if (isNaN(timestamp.getTime()))
  return new ForbiddenError("INVALID_TIMESTAMP", { rawJson, timestamp });

Moving on, in the JSON we can see that a field is sent indicating what type of metric it is. If you ask me, it isn't the best choice for the JSON structure. Personally, I would have sent two separate lists with the values of ‘movement’ and ‘heart rate’, but hey, it is what it is.

There are two types of metrics, so we could clearly interpret this as a list. Now, how do we validate an enumeration? We will have to resort to creating a custom-type guard.

enum Metric {
  ActivityScore = 2,
  HeartRateMonitor = 1,
}

const isMetric = (m: unknown): m is Metric =>
  Object.values(Metric).includes(m as Metric);

if (!isMetric(metric)) {
  throw new ForbiddenError("INVALID_METRIC_ENUM", { metric, rawJson });
}

if (typeof value !== "number") {
  throw new ForbiddenError("INVALID_METRIC_VALUE", { rawJson, value });
}

Now that we have parsed the enumeration, the rest should be as easy as checking what type of metric it is and performing validations, which should be simple at this point.

if (metric === Metric.ActivityScore) {
  if (value < ACTIVITY_SCORE_LOWER_LEVEL) {
    throw new ForbiddenError("INVALID_ACTIVITY_SCORE_BELOW_RANGE", {
      rawJson,
      value,
    });
  }

  if (ACTIVITY_SCORE_UPPER_LEVEL < value) {
    throw new ForbiddenError("INVALID_ACTIVITY_SCORE_ABOVE_RANGE", {
      rawJson,
      value,
    });
  }

  activityScore.push(entry);
}

if (metric === Metric.HeartRateMonitor) {
  if (value < HEART_RATE_LOWER_LEVEL) {
    throw new ForbiddenError("INVALID_HEART_RATE_BELOW_RANGE", {
      rawJson,
      value,
    });
  }

  if (HEART_RATE_UPPER_LEVEL < value) {
    throw new ForbiddenError("INVALID_HEART_RATE_ABOVE_RANGE", {
      rawJson,
      value,
    });
  }

  heartRateMonitor.push(entry);
}

With this, our parser is covered. Now we can confirm that all necessary validations are being carried out to guarantee that the JSON is coming in the expected format. Note that we should perform this type of validation whenever we interact with systems that are beyond our reach (be it a database, API, etc.).

It is interesting to appreciate how type guards, among other things, allow us to dynamically perform type validations and the ease that the language provides us to use them.

Conclusion

Sometimes, in our eagerness to have a high level of predictability, we may make the mistake of wanting to type things like requests to an API or queries to a database.

The mistake of falling into these types of scenarios lies in not understanding that those entities coming from elements declared outside of the scope require to be treated in very different ways from those within.

When conceiving what type of structures the information coming from outside will have, confidence will not be enough in the sense that we will never have any control over those domains.

As we covered in this post, the most idiomatic approach is to avoid making assumptions and instead perform the necessary validations at the boundary. This enables us to take necessary actions in catastrophic scenarios where the received data does not comply with the expected format. By doing so, we can trigger alerts at an early stage and avoid potential errors that may be difficult to detect.

DEV Community: Juan Oliú

A Practical Approach to Error Handling in Express.js

Motivation

GraphQL inspiration

Built-in error codes

Custom Error Classes

HttpError Class

Custom Error Classes

Descriptions:

Error handling within a middleware

Express middleware functions

Types of Middleware:

Using Middleware:

Example:

Custom Middlewares for Error Handling

errorConverter Middleware

errorHandler Middleware

Logger module

Conclusion

Special mention

TypeScript Type Guards: An Introduction to Writing Safer Code

Limitations of Static Type Checking

Any type behavior and potential issues

The unkonwn type

Introduction to type guards

Custom type guards

Wrapping it all together through an example

Conclusion

`errorConverter` Middleware

`errorHandler` Middleware

The `unkonwn` type

Introduction to `type guards`