Utility Functions

/**
 * Returns the reason phrase for the given status code.
 * If the given status code does not exist, an error is thrown.
 *
 * @param statusCode - The HTTP status code (number or string)
 * @returns The associated reason phrase (e.g. "Bad Request", "OK")
 * @throws Error if status code does not exist
 */
function getReasonPhrase(statusCode: number | string): string;

import { getReasonPhrase, StatusCodes } from "http-status-codes";

// Convert status codes to reason phrases
const okPhrase = getReasonPhrase(200);
// Returns: "OK"

const notFoundPhrase = getReasonPhrase(StatusCodes.NOT_FOUND);
// Returns: "Not Found"

const serverErrorPhrase = getReasonPhrase("500");
// Returns: "Internal Server Error"

// Error handling in Express.js
app.use((err, req, res, next) => {
  const statusCode = err.statusCode || 500;
  res.status(statusCode).json({
    error: getReasonPhrase(statusCode),
    message: err.message
  });
});

// API response builder
const buildResponse = (code: number, data?: any) => ({
  statusCode: code,
  statusText: getReasonPhrase(code),
  data: data || null
});

// Error handling with try-catch
try {
  const phrase = getReasonPhrase(999); // Invalid status code
} catch (error) {
  console.error(error.message); // "Status code does not exist: 999"
}

/**
 * Returns the status code for the given reason phrase.
 * If the given reason phrase does not exist, an error is thrown.
 *
 * @param reasonPhrase - The HTTP reason phrase (e.g. "Bad Request", "OK")
 * @returns The associated status code (number)
 * @throws Error if reason phrase does not exist
 */
function getStatusCode(reasonPhrase: string): number;

import { getStatusCode, ReasonPhrases } from "http-status-codes";

// Convert reason phrases to status codes
const okCode = getStatusCode("OK");
// Returns: 200

const notFoundCode = getStatusCode(ReasonPhrases.NOT_FOUND);
// Returns: 404

const serverErrorCode = getStatusCode("Internal Server Error");
// Returns: 500

// Dynamic status code lookup from user input
const handleHttpStatus = (statusText: string) => {
  try {
    const code = getStatusCode(statusText);
    return `Status: ${code} ${statusText}`;
  } catch (error) {
    return `Invalid status text: ${statusText}`;
  }
};

// Configuration-driven status handling
const errorMappings = {
  "validation_failed": getStatusCode("Bad Request"),
  "not_authenticated": getStatusCode("Unauthorized"), 
  "access_denied": getStatusCode("Forbidden"),
  "resource_missing": getStatusCode("Not Found")
};

// Reverse lookup from text-based configurations
const configStatus = "Internal Server Error";
response.status(getStatusCode(configStatus));

// Error handling with try-catch
try {
  const code = getStatusCode("Invalid Phrase");
} catch (error) {
  console.error(error.message); // "Reason phrase does not exist: Invalid Phrase"
}

getReasonPhrase

/**
 * @deprecated Use getReasonPhrase instead
 * 
 * Returns the reason phrase for the given status code.
 * If the given status code does not exist, undefined is returned.
 *
 * @param statusCode - The HTTP status code (number or string)
 * @returns The associated reason phrase (e.g. "Bad Request", "OK")
 */
const getStatusText: typeof getReasonPhrase;

import { getStatusText } from "http-status-codes";

// Legacy usage (deprecated - use getReasonPhrase instead)
const phrase = getStatusText(200);
// Returns: "OK"

// Migration path
// Old: getStatusText(statusCode)
// New: getReasonPhrase(statusCode)

// Throws Error for non-existent status codes
try {
  getReasonPhrase(999);
} catch (error) {
  console.log(error.message); // "Status code does not exist: 999"
}

try {
  getReasonPhrase("invalid");
} catch (error) {
  console.log(error.message); // "Status code does not exist: invalid"
}

// Throws Error for non-existent reason phrases
try {
  getStatusCode("Invalid Status");
} catch (error) {
  console.log(error.message); // "Reason phrase does not exist: Invalid Status"
}

try {
  getStatusCode("");
} catch (error) {
  console.log(error.message); // "Reason phrase does not exist: "
}

// getReasonPhrase accepts both number and string
getReasonPhrase(200);        // ✓ number
getReasonPhrase("200");      // ✓ string
getReasonPhrase(StatusCodes.OK); // ✓ enum value

// getStatusCode requires exact string matches
getStatusCode("OK");                    // ✓ exact match
getStatusCode("ok");                    // ✗ case-sensitive
getStatusCode(" OK ");                  // ✗ whitespace-sensitive  
getStatusCode(ReasonPhrases.OK);        // ✓ enum value