Error

[olavoasantos]

@micra/error

Status

Type: Contract, Library
Start Date: 2022/03/14
Champion(s): @olavoasantos
Author(s): @olavoasantos
Epic: #7
Repository: https://github.com/micrajs/error
Issues: Project: error
Milestone: v0.1.0

Summary

This interface describes a standardized error interface. This allows different types of Micra applications (e.g. back-end API, front-end clients, mobile apps, ...) to consistently communicate and handle errors.

Motivation

Having a consistent way to communicate errors across applications makes the code more consistent and easier to handle. Moreover, this allows us to enforce well-established conventions in the community by following a standard (RFC 7807) rather than a completely custom design.

Description

• Contract

Create custom errors

To create custom error while maintaining consistency, Micra should provide an extensible class that enforces the standard interface.

Example

import {MicraError} from '@micra/error';

export class MissingContainerError extends MicraError {
  statusCode = 500;

  constructor() {
    super(`Service container not defined`);
    Object.setPrototypeOf(this, MissingContainerError.prototype);
  }

  serialize(): Micra.ErrorMessage[] {
    return [
      {
        status: this.statusCode,
        title: 'Missing container',
        detail: this.message,
      },
    ];
  }
}

Identifying and handling errors

While running Micra's application, we should have a clean and easy way to identify errors that adopt the standards. It is Micra's responsibility to provide an API for that.

Example

import {isMicraError} from '@micra/error';

try {
  handleRequest(req, res, next);
} catch (e: unknown) {
  if (isMicraError(e)) {
    throw new Response(JSON.stringify({errors: e.serialize()}), {
      status: e.statusCode,
    });
  }
}

API

Micra's Error class

// Node.js/JavaScript Error class
interface GlobalError {
    name: string;
    message: string;
    stack?: string;
}

interface Error extends GlobalError {
  /**
   * The HTTP status code generated by the origin server for this occurrence of the problem.
   */
  statusCode: number;

  /**
   * Method used to serialize the errors to a list of JSON objects.
   */
  serialize(): ErrorMessage[];
}

Error response payloads

Error responses should have a standard structure while still allowing extensibility. The usage of custom payload design can be tempting but comes with the cost of predictability and structure that is less tested. Based on this, Micra's error payload should follow patterns already accepted by the community enforcing, for example, the standard described by RFC 7807.

interface ErrorResponsePayload {
  errors: ErrorMessage[];
}

interface ErrorMessage {
  /**
   * A human-readable explanation specific to this occurrence of the problem.
   */
  detail?: string;

  /**
   * An optional object containing more specific information about the error.
   */
  extra?: Record<string, unknown>;

  /**
   * A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
   */
  instance?: string;

  /**
   * The HTTP status code generated by the origin server for this occurrence of the problem.
   */
  status: number;

  /**
   * A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization (e.g. using proactive content negotiation)
   */
  title: string;

  /**
   * A URI reference that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML).  When this member is not present, its value is assumed to be "about:blank".
   */
  type?: string;
}

Comparison

• TODO...

Drawbacks

TODO...

Alternatives

TODO...

Implementations

TODO...

Q&A

How to identify a Micra.Error?

How to create custom errors while maintaining consistency?