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