ts-http-status-utils 🛠️ 💻 🧰

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

RequestMethod.GET;

// Return "GET"

RequestMethod.POST;

// Return "POST"

StatusCode

StatusCode.CONTINUE;

// Return 100

StatusCode.OK;

// Return 200

StatusPhrase

StatusPhrase.PROCESSING;

// Return "Processing"

StatusPhrase.MOVED_PERMANENTLY;

// Return "Moved Permanently"

StatusDescription

StatusDescription.CREATED;

// 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

StatusLabel.CREATED;

// Return "CREATED"

StatusLabel.ALREADY_REPORTED;

// Return "ALREADY_REPORTED"

Available functions

getStatusPhraseByCode, getStatusDescriptionByCode, makeHttpResponsesDictionary

getStatusPhraseByCode

getStatusPhraseByCode(StatusCode.PROXY_AUTHENTICATION_REQUIRED);

// Return "Proxy Authentication Required"

getStatusDescriptionByCode

getStatusDescriptionByCode(StatusCode.BAD_GATEWAY);

// 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

{
'100': {
    code: 100,
    phrase: 'Continue',
    description: 'This interim response indicates that the client should continue the request or ignore the response if the request is already finished.'
},
'101': {
    code: 101,
    phrase: 'Switching Protocols',
    description: 'This code is sent in response to an Upgrade request header from the client and indicates the protocol the server is switching to.'
},
    ...

'511': {
    code: 511,
    phrase: 'Network Authentication Required',
    description: 'Indicates that the client needs to authenticate to gain network access.'
}

const dictionary = makeHttpResponsesDictionary();

dictionary[StatusCode.OK];

/**
return
    '200': {
        code: 200,
        phrase: 'OK',
        description: 'The request succeeded. The result meaning of `success` depends on the HTTP method.'
    }
* /

How to use in a real project

import {
  StatusCode,
  getStatusPhraseByCode,
  RequestMethod,
  getStatusDescriptionByCode,
} from "ts-http-status-utils";

export const lambdaHandler = async (
  event: APIGatewayProxyEvent,
  context: Context
): Promise<APIGatewayProxyResult> => {
  try {
    // RequestMethod enum
    if (event.httpMethod !== RequestMethod.GET) {
      // getStatusPhraseByCode and getStatusDescriptionByCode util functions & StatusCode.METHOD_NOT_ALLOWED
      logError({
        method: event.httpMethod,
        statusCode: StatusCode.METHOD_NOT_ALLOWED,
        statusPhrase: getStatusPhraseByCode(StatusCode.METHOD_NOT_ALLOWED),
        statusDescription: getStatusDescriptionByCode(
          StatusCode.METHOD_NOT_ALLOWED
        ),
      });

      return {
        // StatusCode enum
        statusCode: StatusCode.METHOD_NOT_ALLOWED,
        headers: {},
        body: JSON.stringify({
          // getStatusPhraseByCode util function
          message: getStatusPhraseByCode(StatusCode.METHOD_NOT_ALLOWED),
        }),
      };
    }

    return {
      // StatusCode enum
      statusCode: StatusCode.OK,
      // getStatusPhraseByCode util function
      body: JSON.stringify({
        message: `${getStatusPhraseByCode(
          StatusCode.OK
        )} - Response from lambda`,
      }),
    };
  } catch (error) {
    // getStatusPhraseByCode and getStatusDescriptionByCode util functions
    logError({
      method: event.httpMethod,
      statusCode: error.statusCode,
      statusPhrase: getStatusPhraseByCode(error.statusCode),
      statusDescription: getStatusDescriptionByCode(error.statusCode),
    });

    return {
      statusCode: error.statusCode,
      body: JSON.stringify({
        message:
          error instanceof Error ? error.stack : JSON.stringify(error, null, 2),
      }),
    };
  }
};

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