# http-status-toolkit : A Lightweight, TypeScript-Friendly Alternative to http-status-codes

In my backend projects, I got tired of constantly writing raw status code numbers like:

```ts
res.status(200)
res.status(404)
```

It works — but it's not expressive. And honestly, it makes code harder to read and maintain over time. Like many developers, I wanted something cleaner, more intuitive, and easier to understand at a glance.

So I looked into existing solutions.

---

## 🚫 First I Tried `http-status-codes`

[`http-status-codes`](https://www.npmjs.com/package/http-status-codes) is a well-known package. With it, you can write:

```ts
import { StatusCodes } from "http-status-codes";
res.status(StatusCodes.OK);
```

Much better than hardcoded numbers — but it came with a few drawbacks:

- ❌ No ESM support  
- ❌ No localization  
- ❌ No detailed reason phrases  
- ❌ Separate type definitions (`@types/http-status-codes`)  
- ❌ Slightly bloated — 12+ KB minified

It didn’t quite solve my problems. So I kept looking.

---

## 😐 Then I Tried `http-status`

[`http-status`](https://www.npmjs.com/package/http-status) is another popular choice. It *does* support both CommonJS and ESM out of the box — nice. But it still had some limitations:

- ❌ No localization or i18n support  
- ❌ Only short, generic messages  
- ❌ No detailed descriptions for each code  
- ❌ Lacks modern TypeScript typings  
- ❌ Not tree-shakable  

So again — better than nothing, but not enough.

---

## ✅ So I Built `http-status-toolkit`

I created [`http-status-toolkit`](https://www.npmjs.com/package/http-status-toolkit) to solve all of the above. It’s modern, lightweight, and built for **real-world developer needs**.

Here’s what it offers:

- ✅ **TypeScript-first** with full type safety and autocompletion  
- ✅ **ESM and CommonJS support**  
- ✅ **Short + detailed** human-readable messages  
- ✅ **Localization support** in 10+ languages  
- ✅ **Tree-shakable** and subpath exportable  
- ✅ Built with [tsup](https://github.com/egoist/tsup) for clean, modern builds  
- ✅ Extremely lightweight: **~4.1 KB minified / ~2.2 KB gzipped**

---

## 🧪 Example Usage

```ts
import { StatusCodes, getStatusMessage } from "http-status-toolkit";

console.log(StatusCodes.OK); 
// 200

console.log(getStatusMessage(StatusCodes.NOT_FOUND)); 
// "Not Found"

// Detailed message
import DetailedMessages from "http-status-toolkit/messages-detailed";
console.log(getStatusMessage(StatusCodes.NOT_FOUND, { variant: DetailedMessages }));
// "Not Found: The requested resource could not be found but may be available in the future."

// Localized message (Bengali)
import BengaliMessages from 'http-status-toolkit/messages-bn';
console.log(getStatusMessage(StatusCodes.NOT_FOUND, { variant: BengaliMessages }));
// Output: (Not Found message in Bengali)

```

---

## 📊 Feature Comparison

| Feature                    | `http-status-codes` | `http-status` | `http-status-toolkit` |
|---------------------------|----------------------|----------------|------------------------|
| ESM Support               | ❌ No                | ✅ Yes         | ✅ Yes                 |
| CommonJS Support          | ✅ Yes               | ✅ Yes         | ✅ Yes                 |
| TypeScript Support        | ❌ (via @types)      | ✅ Partial     | ✅ Full                |
| Localization              | ❌ No                | ❌ No          | ✅ Yes (10+ languages) |
| Short Messages            | ✅ Yes               | ✅ Yes         | ✅ Yes                 |
| Detailed Messages         | ❌ No                | ❌ No          | ✅ Yes                 |
| Tree-shakable             | ❌ No                | ❌ No          | ✅ Yes                 |
| Minified Bundle Size      | ~12.2 KB             | ~21.1 KB       | ✅ ~4.1 KB             |
| Gzipped Bundle Size       | ~3.6 KB              | ~7.4 KB        | ✅ ~2.2 KB             |

> 📦 **Bundle size is based on [Bundlephobia](https://bundlephobia.com/)**

---

## 💡 Why It Matters

`http-status-toolkit` improves:

- **Readability**: No more `res.status(403)` — use `StatusCodes.FORBIDDEN`  
- **Clarity**: Choose between short, detailed, or localized messages  
- **Internationalization**: Easily display meaningful error responses in your users' languages  
- **Developer Experience**: Clean API, tree-shakable, and TypeScript-native

---

## 🧭 Want to Explore?

- 🔗 [View on npm](https://www.npmjs.com/package/http-status-toolkit)  
- 💻 [View source on GitHub](https://github.com/dev-rashedin/http-status-toolkit)  
- 🌐 [Visit my portfolio](https://www.rashedin.dev)

---

Built with ❤️ and TypeScript by [Rashedin Islam](https://www.rashedin.dev)  
If you find it useful, consider giving it a ⭐ on GitHub.