@vasugrover/http-status

@vasugrover/http-status provides a robust, type-safe, and up-to-date collection of HTTP status codes and their corresponding phrases for use in TypeScript and JavaScript projects. It is designed for reliability, maintainability, and seamless integration into modern web applications and APIs.

Overview

This package offers:

• TypeScript-first design: All status codes and phrases are strictly typed for safety and editor support.
• Comprehensive coverage: Includes all standard HTTP status codes (100–599) as defined by IETF RFCs.
• Automated updates: Status codes and phrases are kept current with upstream sources via a dedicated update script.
• Zero runtime dependencies: Lightweight and suitable for any project size.
• Framework compatibility: Usable with any JavaScript or TypeScript framework or library.

Installation

Bun is the recommended and primary package manager for this project. To install:

bun install @vasugrover/http-status

For compatibility, you may also use npm, yarn, or pnpm, but all documentation and scripts assume Bun as the default.

Usage

The package exposes two main modules:

• codes: Numeric HTTP status code constants (e.g., codes.OK = 200)
• phrases: String HTTP status phrase constants (e.g., phrases.OK = "OK")

Importing Codes and Phrases

import { codes, phrases } from "@vasugrover/http-status";

// Example usage
const status = codes.NOT_FOUND; // 404
const message = phrases.NOT_FOUND; // "Not Found"

Individual Imports

import { OK, NOT_FOUND } from "@vasugrover/http-status/codes";
import { OK as OK_PHRASE } from "@vasugrover/http-status/phrases";

console.log(OK); // 200
console.log(OK_PHRASE); // "OK"

Example: API Integration

With Hono

import { codes, phrases } from "@vasugrover/http-status";
import { Hono } from "hono";

const app = new Hono();

app.get("/users/:id", async (c) => {
  const user = await findUser(c.req.param("id"));
  if (!user) {
    return c.json({ error: phrases.NOT_FOUND }, codes.NOT_FOUND);
  }
  return c.json(user, codes.OK);
});

app.post("/users", async (c) => {
  const body = await c.req.json();
  const newUser = await createUser(body);
  return c.json({ data: newUser, message: phrases.CREATED }, codes.CREATED);
});

With React Router

import { codes, phrases } from "@vasugrover/http-status";
import { json } from "react-router";

export async function loader({ params }) {
  const data = await fetchData(params.id);
  if (!data) {
    throw json({ message: phrases.NOT_FOUND }, { status: codes.NOT_FOUND });
  }
  return json(data, { status: codes.OK });
}

export async function action({ request }) {
  const formData = await request.formData();
  try {
    const result = await processData(formData);
    return json(result, { status: codes.CREATED });
  } catch (error) {
    return json({ error: phrases.INTERNAL_SERVER_ERROR }, { status: codes.INTERNAL_SERVER_ERROR });
  }
}

Response Helper Example

import { codes, phrases } from "@vasugrover/http-status";

export const apiResponse = {
  success: <T>(data: T) => ({
    status: codes.OK,
    data,
    message: phrases.OK,
  }),
  created: <T>(data: T) => ({
    status: codes.CREATED,
    data,
    message: phrases.CREATED,
  }),
  notFound: (resource: string) => ({
    status: codes.NOT_FOUND,
    error: `${resource} ${phrases.NOT_FOUND.toLowerCase()}`,
  }),
  badRequest: (message: string) => ({
    status: codes.BAD_REQUEST,
    error: message,
  }),
  serverError: (message?: string) => ({
    status: codes.INTERNAL_SERVER_ERROR,
    error: message || phrases.INTERNAL_SERVER_ERROR,
  }),
};

API Reference

Exports

• codes: All HTTP status code constants (e.g., codes.OK = 200)
• phrases: All HTTP status phrase constants (e.g., phrases.OK = "OK")

Status Codes Coverage

All standard HTTP status codes from 100 to 599 are included, based on the official IETF RFC specifications. Data is sourced from prettymuchbryce/http-status-codes.

TypeScript Support

All exports are fully typed for maximum safety and IntelliSense in compatible editors.

Updating Status Codes

To keep status codes and phrases current with upstream changes, use the automated update script. Bun is required for all maintenance tasks.

Automated Update

Run the following command to fetch and regenerate status code data:

bun run update

This will fetch the latest upstream codes and regenerate the relevant files. Always run the following after updating:

bun run typecheck
bun run lint
bun run build

Manual Update

For advanced or manual updates, refer to the maintenance documentation or scripts in the repository.

Contributing

Contributions are welcome. Please review the contribution guidelines before submitting changes. Ensure that:

1. All changes are backward compatible
2. TypeScript types are updated as needed
3. Documentation is kept current
4. All checks pass using Bun (bun run typecheck, bun run lint, bun run build)

License

This project is licensed under the MIT License. See the LICENSE file for details.

Repository

• GitHub: https://github.com/itsvasugrover/http-status
• Issues: https://github.com/itsvasugrover/http-status/issues

Support

For questions or support, please open an issue on the GitHub repository.