@curveball/http-errors

HTTP Errors
===========

This package contains a list of standard HTTP exceptions for Typescript. They
can be emitted from a Node.js web application written in for example [Koa][2]
or [Curveball][1], or they can be re-used in a HTTP client.

This package exists because I often find myself re-writing errors such as:

``typescript
class NotFound extends Error {
const httpStatus = 404;
}
`

Instead of doing this over an over again for every client and server-sideproject,
it made more sense to be to create 1 generic package that I can re-use for every
project I'm working on.

I had trouble finding something similar on NPM, so I hope this is useful to
others.

This package has 0 dependencies and is not a part of any frameworks. Someone
could use this package and integrate it into their own frameworks as a
middleware.

The hope is that as long as this package is independent, it could be used by
library authors to throw generic errors with HTTP error information.


Installation
------------

npm install @curveball/http-errors


Getting started
---------------

After installing the NPM package, you can very easily reference all the
exceptions contained within:

`typescript
import { NotFound, Forbidden } from '@curveball/http-errors';

throw new NotFound('Article not found');
`

This also works fine with plain javascript:

`javascript
const { NotFound, Forbidden } = require('@curveball/http-errors');
throw new Forbidden('You\'re not allowed to update this article');
`


The library also ships with a simple utility function to see if _any_ error has
HTTP error information:

`typescript
import { isHttpError } from '@curveball/http-errors';

const myError = new Error('Custom error');
myError.httpStatus = 500;

console.log(isHttpError(myError));
`

The idea is that as long as libraries follow this pattern, they don't need to
depend on this library but they can be used automatically by middlewares.


Built-in Error classes such as NotFound, Unauthorized, all have a title
property with the default HTTP error string.

`typescript
const myError = new MethodNotAllowed('I can\'t believe youi\'ve done this');
console.log(myError.title); // Emits "Method Not Allowed"
`

It also has a utility function to see if something was a Client or Server error:

`typescript
import { BadRequest, isServerError, isClientError } from '@curveball/http-errors';

const myError = new BadRequest('I didn\'t understand it');
console.log(isClientError(e)); // true
console.log(isServerError(e)); // false
`

Lastly, a few HTTP responses require or suggest including extra HTTP headers with
more information about the error. For example, the 405 Method Not Allowed
response should include an Allow header, and the 503 Service Unavailable
should have a Retry-After header. The built-in error classes include support
these:

`typescript
import { MethodNotAllowed, ServiceUnavailable } from '@curveball/http-errors';

try {
throw new MethodNotAllowed('Not allowed', ['GET', 'PUT']);
} catch (e) {
console.log(e.allow);
}

try {
throw new ServiceUnavailable('Not open on sundays', 3600*24);
} catch (e) {
console.log(e.retryAfter);
}
`

Lastly, it the package has an interface that makes it easier to work with the
application/problem+json format, as defined in [RFC9457][3]. The interface
has type, title, detail and instance properties, which makes it easier
to write a generic interface that emits this JSON error format.

API
---

`typescript
export function isHttpError(e: Error): e is HttpError;
export function isHttpProblem(e: Error): e is HttpProblem;
export function isClientError(e: Error): boolean;
export function isServerError(e: Error): boolean;

export interface HttpError extends Error {
httpStatus: number;
}

export interface HttpProblem extends HttpError {

type: string | null;
title: string;
detail: string | null;
instance: string | null;

}

export class HttpErrorBase extends Error implements HttpProblem {

type: string | null = null;
httpStatus: number = 500;
title: string = 'Internal Server Error';
detail: string|null = null;
instance: string | null = null;

constructor(detail: string|null = null) { }

}

export class BadRequest extends HttpErrorBase { }

type AuthenticateChallenge = string | string[];

export class Unauthorized extends HttpErrorBase {
wwwAuthenticate: AuthenticateChallenge;
constructor(detail: string|null = null, wwwAuthenticate?: AuthenticateChallenge) {}
}

export class PaymentRequired extends HttpErrorBase {}
export class Forbidden extends HttpErrorBase {}
export class NotFound extends HttpErrorBase {}

export class MethodNotAllowed extends HttpErrorBase {
allow: string[]
constructor(detail: string|null = null, allow?: string[]) {}
}

export class NotAcceptable extends HttpErrorBase {}

export class ProxyAuthenticationRequired extends HttpErrorBase {
proxyAuthenticate: AuthenticateChallenge;
constructor(detail: string|null = null, proxyAuthenticate?: AuthenticateChallenge) {}
}

export class RequestTimeout extends HttpErrorBase {}
export class Conflict extends HttpErrorBase {}
export class Gone extends HttpErrorBase {}
export class LengthRequired extends HttpErrorBase {}
export class PreconditionFailed extends HttpErrorBase {}

export class ContentTooLarge extends HttpErrorBase {
retryAfter: number | null;
constructor(detail: string|null = null, retryAfter: number|null = null) {}
}

export class UriTooLong extends HttpErrorBase { }
export class UnsupportedMediaType extends HttpErrorBase {}
export class RangeNotSatisfiable extends HttpErrorBase {}
export class ExpectationFailed extends HttpErrorBase {}
export class MisdirectedRequest extends HttpErrorBase {}
export class UnprocessableContent extends HttpErrorBase {}
export class Locked extends HttpErrorBase {}
export class FailedDependency extends HttpErrorBase {}
export class TooEarly extends HttpErrorBase {}
export class UpgradeRequired extends HttpErrorBase {}
export class PreconditionRequired extends HttpErrorBase {}

export class TooManyRequests extends HttpErrorBase {
retryAfter: number | null;
constructor(detail: string|null = null, retryAfter: number|null = null) {}
}

export class RequestHeaderFieldsTooLarge extends HttpErrorBase {}
export class UnavailableForLegalReasons extends HttpErrorBase {}
export class InternalServerError extends HttpErrorBase {}
export class NotImplemented extends HttpErrorBase {}
export class BadGateway extends HttpErrorBase {}

export class ServiceUnavailable extends HttpErrorBase {
retryAfter: number | null;
constructor(detail: string|null = null, retryAfter: number|null = null) {}
}

export class GatewayTimeout extends HttpErrorBase {}
export class HttpVersionNotSupported extends HttpErrorBase {}
export class VariantAlsoNegotiates extends HttpErrorBase {}
export class UnsufficientStorage extends HttpErrorBase {}
export class LoopDetected extends HttpErrorBase {}
export class NetworkAuthenticationRequired extends HttpErrorBase {}
``

...

[1]: https://github.com/curveball/
[2]: http://koajs.com/
[3]: https://tools.ietf.org/html/rfc9457