ts-http-status-utils :hammer_and_wrench: :computer: :toolbox:

HTTP status code declarations, status phrases, descriptions and util functions

Motivation

Working on different projects dealing with microservices or different responses from distributed APIs I noticed that some developers used to default failed responses to Http code 500 - Internal Server Error instead of an appropriate Http code making the debug process harder and misleading depending how you implement logging tools.

Taking advantage of TypeScript and Docstrings, this library helps developers to handle and understand HTTP responses easily as well making it easy to build, integrate or debug microservices or APIs.

How to use

---

Available enums

RequestMethod, StatusCode, StatusPhrase, StatusDescription, StatusLabel

RequestMethod

1RequestMethod.GET;
2
3// Return "GET"
4
5RequestMethod.POST;
6
7// Return "POST"

StatusCode

1StatusCode.CONTINUE;
2
3// Return 100
4
5StatusCode.OK;
6
7// Return 200

StatusPhrase

1StatusPhrase.PROCESSING;
2
3// Return "Processing"
4
5StatusPhrase.MOVED_PERMANENTLY;
6
7// Return "Moved Permanently"

StatusDescription

1StatusDescription.CREATED;
2
3// Return "The request succeeded, and a new resource was created as a result. This is typically the response sent after POST requests, or some PUT requests."

StatusLabel

1StatusLabel.CREATED;
2
3// Return "CREATED"
4
5StatusLabel.ALREADY_REPORTED;
6
7// Return "ALREADY_REPORTED"

Available functions

getStatusPhraseByCode, getStatusDescriptionByCode, makeHttpResponsesDictionary

getStatusPhraseByCode

1getStatusPhraseByCode(StatusCode.PROXY_AUTHENTICATION_REQUIRED);
2
3// Return "Proxy Authentication Required"

getStatusDescriptionByCode

1getStatusDescriptionByCode(StatusCode.BAD_GATEWAY);
2
3// Return "This error response means that the server, while working as a gateway to get a response needed to handle the request, got an invalid response."

makeHttpResponsesDictionary

Create a dictionary containing all HTTP responses

1{
2'100': {
3    code: 100,
4    phrase: 'Continue',
5    description: 'This interim response indicates that the client should continue the request or ignore the response if the request is already finished.'
6},
7'101': {
8    code: 101,
9    phrase: 'Switching Protocols',
10    description: 'This code is sent in response to an Upgrade request header from the client and indicates the protocol the server is switching to.'
11},
12    ...
13
14'511': {
15    code: 511,
16    phrase: 'Network Authentication Required',
17    description: 'Indicates that the client needs to authenticate to gain network access.'
18}

1
2const dictionary = makeHttpResponsesDictionary();
3
4dictionary[StatusCode.OK];
5
6/**
7return
8    '200': {
9        code: 200,
10        phrase: 'OK',
11        description: 'The request succeeded. The result meaning of `success` depends on the HTTP method.'
12    }
13* /
14

How to use in a real project

1import {
2  StatusCode,
3  getStatusPhraseByCode,
4  RequestMethod,
5  getStatusDescriptionByCode,
6} from "ts-http-status-utils";
7
8export const lambdaHandler = async (
9  event: APIGatewayProxyEvent,
10  context: Context
11): Promise<APIGatewayProxyResult> => {
12  try {
13    // RequestMethod enum
14    if (event.httpMethod !== RequestMethod.GET) {
15      // getStatusPhraseByCode and getStatusDescriptionByCode util functions & StatusCode.METHOD_NOT_ALLOWED
16      logError({
17        method: event.httpMethod,
18        statusCode: StatusCode.METHOD_NOT_ALLOWED,
19        statusPhrase: getStatusPhraseByCode(StatusCode.METHOD_NOT_ALLOWED),
20        statusDescription: getStatusDescriptionByCode(
21          StatusCode.METHOD_NOT_ALLOWED
22        ),
23      });
24
25      return {
26        // StatusCode enum
27        statusCode: StatusCode.METHOD_NOT_ALLOWED,
28        headers: {},
29        body: JSON.stringify({
30          // getStatusPhraseByCode util function
31          message: getStatusPhraseByCode(StatusCode.METHOD_NOT_ALLOWED),
32        }),
33      };
34    }
35
36    return {
37      // StatusCode enum
38      statusCode: StatusCode.OK,
39      // getStatusPhraseByCode util function
40      body: JSON.stringify({
41        message: `${getStatusPhraseByCode(
42          StatusCode.OK
43        )} - Response from lambda`,
44      }),
45    };
46  } catch (error) {
47    // getStatusPhraseByCode and getStatusDescriptionByCode util functions
48    logError({
49      method: event.httpMethod,
50      statusCode: error.statusCode,
51      statusPhrase: getStatusPhraseByCode(error.statusCode),
52      statusDescription: getStatusDescriptionByCode(error.statusCode),
53    });
54
55    return {
56      statusCode: error.statusCode,
57      body: JSON.stringify({
58        message:
59          error instanceof Error ? error.stack : JSON.stringify(error, null, 2),
60      }),
61    };
62  }
63};

Resources

https://developer.mozilla.org/en-US/docs/Web/HTTP/Status

https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods

https://datatracker.ietf.org/doc/html/rfc7231