{"id":43255961,"url":"https://github.com/iamgerwin/http-code-responses","last_synced_at":"2026-02-01T13:33:09.930Z","repository":{"id":320817892,"uuid":"1083448424","full_name":"iamgerwin/http-code-responses","owner":"iamgerwin","description":null,"archived":false,"fork":false,"pushed_at":"2025-10-26T03:27:21.000Z","size":18017,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-26T05:33:56.711Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iamgerwin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-26T03:16:30.000Z","updated_at":"2025-10-26T03:27:25.000Z","dependencies_parsed_at":"2025-10-26T05:34:16.750Z","dependency_job_id":"33155621-bf44-48f2-80b3-723a87735ec8","html_url":"https://github.com/iamgerwin/http-code-responses","commit_stats":null,"previous_names":["iamgerwin/http-code-responses"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/iamgerwin/http-code-responses","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamgerwin%2Fhttp-code-responses","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamgerwin%2Fhttp-code-responses/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamgerwin%2Fhttp-code-responses/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamgerwin%2Fhttp-code-responses/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iamgerwin","download_url":"https://codeload.github.com/iamgerwin/http-code-responses/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamgerwin%2Fhttp-code-responses/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28979126,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-01T12:13:08.691Z","status":"ssl_error","status_checked_at":"2026-02-01T12:13:08.356Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-01T13:33:08.670Z","updated_at":"2026-02-01T13:33:09.745Z","avatar_url":"https://github.com/iamgerwin.png","language":"TypeScript","readme":"\u003cdiv align=\"center\"\u003e\n\n# 🚀 http-code-responses\n\n**Readable HTTP status code constants with reason phrases and helpers**\n\n[![npm version](https://img.shields.io/npm/v/http-code-responses?style=flat-square\u0026color=blue)](https://www.npmjs.com/package/http-code-responses)\n[![npm downloads](https://img.shields.io/npm/dm/http-code-responses?style=flat-square\u0026color=green)](https://www.npmjs.com/package/http-code-responses)\n[![CI](https://img.shields.io/github/actions/workflow/status/iamgerwin/http-code-responses/ci.yml?style=flat-square\u0026label=CI)](https://github.com/iamgerwin/http-code-responses/actions/workflows/ci.yml)\n[![codecov](https://img.shields.io/codecov/c/github/iamgerwin/http-code-responses?style=flat-square\u0026token=)](https://codecov.io/gh/iamgerwin/http-code-responses)\n[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue?style=flat-square)](https://www.typescriptlang.org/)\n[![bundle size](https://img.shields.io/bundlephobia/minzip/http-code-responses?style=flat-square)](https://bundlephobia.com/package/http-code-responses)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE)\n\n[Features](#-features) • [Installation](#-installation) • [Usage](#-usage) • [API](#-api) • [Roadmap](#-roadmap) • [Contributing](#-contributing)\n\n\u003c/div\u003e\n\n---\n\n## ✨ Features\n\n- ✅ **Concise constants** for every standard HTTP status code\n- 📝 **Reason phrases** mapped to each code (e.g., `404` → `\"Not Found\"`)\n- 🪶 **Tiny footprint** - zero runtime dependencies\n- 📦 **Universal** - ESM + CJS + TypeScript types\n- 🔍 **Type-safe** - Full TypeScript support with autocomplete\n- 🎯 **Familiar naming** - Inspired by Symfony HttpFoundation's Response constants\n- ⚡ **Tree-shakeable** - Only bundle what you use\n- 🧪 **Well-tested** - 100% code coverage\n\n## 📦 Installation\n\n```bash\n# npm\nnpm install http-code-responses\n\n# pnpm\npnpm add http-code-responses\n\n# yarn\nyarn add http-code-responses\n\n# bun\nbun add http-code-responses\n```\n\n## 🚀 Usage\n\n### JavaScript (ESM)\n\n```javascript path=null start=null\nimport { StatusCodes, ReasonPhrases, getReasonPhrase } from 'http-code-responses'\n\n// Express.js example\napp.get('/health', (req, res) =\u003e {\n  res.status(StatusCodes.OK).send('ok')\n})\n\n// Get reason phrases\nconsole.log(ReasonPhrases[StatusCodes.NOT_FOUND]) // \"Not Found\"\nconsole.log(getReasonPhrase(422)) // \"Unprocessable Content\"\n```\n\n### JavaScript (CommonJS)\n\n```javascript path=null start=null\nconst { StatusCodes, ReasonPhrases, getReasonPhrase } = require('http-code-responses')\n\nres.status(StatusCodes.CREATED).json({ id })\nconsole.log(ReasonPhrases[StatusCodes.BAD_REQUEST]) // \"Bad Request\"\nconsole.log(getReasonPhrase(503)) // \"Service Unavailable\"\n```\n\n### TypeScript\n\n```typescript path=null start=null\nimport { StatusCodes, type StatusCode, type StatusName } from 'http-code-responses'\n\nfunction sendResponse(code: StatusCode) {\n  // code is type-safe with full autocomplete support\n  return { statusCode: code }\n}\n\nsendResponse(StatusCodes.NO_CONTENT)\n\nconst statusName: StatusName = 'INTERNAL_SERVER_ERROR'\n```\n\n### Framework Examples\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eExpress.js\u003c/b\u003e\u003c/summary\u003e\n\n```javascript path=null start=null\nimport express from 'express'\nimport { StatusCodes, getReasonPhrase } from 'http-code-responses'\n\nconst app = express()\n\napp.get('/api/users/:id', async (req, res) =\u003e {\n  const user = await findUser(req.params.id)\n  \n  if (!user) {\n    return res.status(StatusCodes.NOT_FOUND).json({\n      error: getReasonPhrase(StatusCodes.NOT_FOUND)\n    })\n  }\n  \n  res.status(StatusCodes.OK).json(user)\n})\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eFastify\u003c/b\u003e\u003c/summary\u003e\n\n```javascript path=null start=null\nimport Fastify from 'fastify'\nimport { StatusCodes } from 'http-code-responses'\n\nconst fastify = Fastify()\n\nfastify.get('/api/health', async (request, reply) =\u003e {\n  return reply.code(StatusCodes.OK).send({ status: 'healthy' })\n})\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eNext.js API Routes\u003c/b\u003e\u003c/summary\u003e\n\n```typescript path=null start=null\nimport { NextApiRequest, NextApiResponse } from 'next'\nimport { StatusCodes } from 'http-code-responses'\n\nexport default async function handler(\n  req: NextApiRequest,\n  res: NextApiResponse\n) {\n  if (req.method !== 'POST') {\n    return res.status(StatusCodes.METHOD_NOT_ALLOWED).json({\n      error: 'Method not allowed'\n    })\n  }\n  \n  res.status(StatusCodes.CREATED).json({ success: true })\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eHono\u003c/b\u003e\u003c/summary\u003e\n\n```typescript path=null start=null\nimport { Hono } from 'hono'\nimport { StatusCodes } from 'http-code-responses'\n\nconst app = new Hono()\n\napp.post('/api/data', async (c) =\u003e {\n  const data = await c.req.json()\n  // Process data...\n  return c.json({ success: true }, StatusCodes.CREATED)\n})\n```\n\u003c/details\u003e\n\n## 📖 API\n\n### `StatusCodes`\n\nObject with named constants for all standard HTTP status codes.\n\n```typescript path=null start=null\nStatusCodes.OK                      // 200\nStatusCodes.CREATED                 // 201\nStatusCodes.NO_CONTENT              // 204\nStatusCodes.BAD_REQUEST             // 400\nStatusCodes.UNAUTHORIZED            // 401\nStatusCodes.FORBIDDEN               // 403\nStatusCodes.NOT_FOUND               // 404\nStatusCodes.INTERNAL_SERVER_ERROR   // 500\n// ... and many more\n```\n\nAlso includes common aliases:\n- `UNPROCESSABLE_ENTITY` (422)\n- `PAYLOAD_TOO_LARGE` (413)\n- `REQUEST_URI_TOO_LONG` (414)\n\n### `ReasonPhrases`\n\n```typescript path=null start=null\nReasonPhrases: Record\u003cnumber, string\u003e\n```\n\nMaps status codes to their standard reason phrases.\n\n```typescript path=null start=null\nReasonPhrases[200] // \"OK\"\nReasonPhrases[404] // \"Not Found\"\nReasonPhrases[500] // \"Internal Server Error\"\n```\n\n### `getReasonPhrase(code: number)`\n\nReturns the reason phrase for a given status code.\n\n```typescript path=null start=null\ngetReasonPhrase(200)  // \"OK\"\ngetReasonPhrase(404)  // \"Not Found\"\ngetReasonPhrase(9999) // undefined (unknown code)\n```\n\n### `getStatusCode(name: string)`\n\nReturns the numeric code for a given constant name.\n\n```typescript path=null start=null\ngetStatusCode('OK')        // 200\ngetStatusCode('NOT_FOUND') // 404\ngetStatusCode('INVALID')   // undefined\n```\n\n### `isStatusCode(value: number)`\n\nType guard to check if a number is a known status code.\n\n```typescript path=null start=null\nif (isStatusCode(code)) {\n  // TypeScript knows code is a valid StatusCode\n  console.log(getReasonPhrase(code))\n}\n```\n\n## 🗺️ Roadmap\n\nWe're constantly improving `http-code-responses`. Here's what's on the horizon:\n\n### 🎯 Planned Features\n\n- [ ] **Status Code Categories** - Helper functions to check code types:\n  - `isInformational(code)` - 1xx codes\n  - `isSuccess(code)` - 2xx codes\n  - `isRedirection(code)` - 3xx codes\n  - `isClientError(code)` - 4xx codes\n  - `isServerError(code)` - 5xx codes\n\n- [ ] **Custom Status Codes** - Support for non-standard codes used by specific services:\n  - Cloudflare status codes (520-527)\n  - AWS-specific codes\n  - Custom enterprise codes\n\n- [ ] **Response Builders** - Convenient response object factories:\n  ```typescript\n  createErrorResponse(StatusCodes.NOT_FOUND, { details: '...' })\n  createSuccessResponse(StatusCodes.OK, data)\n  ```\n\n- [ ] **HTTP/2 \u0026 HTTP/3 Support** - Additional status codes and features specific to newer protocols\n\n- [ ] **Localization** - Reason phrases in multiple languages:\n  ```typescript\n  getReasonPhrase(404, 'es') // \"No Encontrado\"\n  getReasonPhrase(404, 'fr') // \"Non Trouvé\"\n  ```\n\n- [ ] **Status Code Recommendations** - Helper to suggest appropriate status codes:\n  ```typescript\n  suggestStatusCode({ operation: 'create', success: true }) // 201\n  suggestStatusCode({ operation: 'delete', success: true }) // 204\n  ```\n\n- [ ] **OpenAPI/Swagger Integration** - Generate OpenAPI response schemas from status codes\n\n- [ ] **Middleware Helpers** - Framework-specific middleware for common patterns:\n  - Auto-set reason phrases in response headers\n  - Status code validation\n  - Logging with status code context\n\n### 💡 Nice to Have\n\n- [ ] CLI tool for status code lookup\n- [ ] Browser extension for quick reference\n- [ ] Interactive documentation site\n- [ ] Performance benchmarks vs alternatives\n- [ ] Code generation for other languages (Python, Go, Rust)\n\n### 🚀 Recently Completed\n\n- ✅ Full TypeScript support with type guards\n- ✅ ESM + CJS dual package support\n- ✅ Zero runtime dependencies\n- ✅ 100% test coverage\n- ✅ Modern HTTP specification alignment\n\n**Want to contribute?** Check out our [Contributing Guide](#-contributing) or open an issue to discuss new features!\n\n## 🤔 Why http-code-responses?\n\n### The Problem\n\n```javascript path=null start=null\n// ❌ Magic numbers are hard to read\nres.status(422).json({ error: 'Invalid data' })\n\n// ❌ Easy to make typos\nres.status(StatusCodes.UNPROCESSABLE_ENTITTY).json(...)\n\n// ❌ Inconsistent across projects\nconst NOT_FOUND = 404 // defined in every project\n```\n\n### The Solution\n\n```javascript path=null start=null\n// ✅ Readable, typed, consistent\nimport { StatusCodes } from 'http-code-responses'\n\nres.status(StatusCodes.UNPROCESSABLE_ENTITY).json({ error: 'Invalid data' })\n```\n\n### Comparison\n\n| Feature | http-code-responses | http-status-codes | statuses |\n|---------|---------------------|-------------------|----------|\n| TypeScript Support | ✅ Full | ⚠️ Partial | ❌ No |\n| ESM + CJS | ✅ | ✅ | ✅ |\n| Reason Phrases | ✅ | ✅ | ✅ |\n| Type Guards | ✅ | ❌ | ❌ |\n| Helper Functions | ✅ | ⚠️ Limited | ✅ |\n| Bundle Size | 🪶 \u003c2KB | ~3KB | ~2KB |\n| Zero Dependencies | ✅ | ✅ | ✅ |\n| Active Maintenance | ✅ | ⚠️ Sporadic | ✅ |\n\n## 🤝 Contributing\n\nContributions are welcome! Here's how you can help:\n\n1. **Fork the repository**\n2. **Create a feature branch**: `git checkout -b feature/amazing-feature`\n3. **Make your changes** and add tests\n4. **Run tests**: `npm test`\n5. **Check types**: `npm run typecheck`\n6. **Commit your changes**: `git commit -m 'feat: add amazing feature'`\n7. **Push to the branch**: `git push origin feature/amazing-feature`\n8. **Open a Pull Request**\n\n### Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/iamgerwin/http-code-responses.git\ncd http-code-responses\n\n# Install dependencies\nnpm install\n\n# Run tests\nnpm test\n\n# Run tests in watch mode\nnpm run test:watch\n\n# Check TypeScript types\nnpm run typecheck\n\n# Build the project\nnpm run build\n```\n\n### Commit Convention\n\nWe use [Conventional Commits](https://www.conventionalcommits.org/):\n\n- `feat:` - New features\n- `fix:` - Bug fixes\n- `docs:` - Documentation changes\n- `test:` - Test changes\n- `chore:` - Tooling/config changes\n\n## 📄 License\n\nMIT License - see the [LICENSE](LICENSE) file for details.\n\n## 💖 Acknowledgments\n\n- Inspired by [Symfony HttpFoundation](https://symfony.com/doc/current/components/http_foundation.html)\n- HTTP status code specifications from [IANA](https://www.iana.org/assignments/http-status-codes/)\n- Built with [TypeScript](https://www.typescriptlang.org/), [tsup](https://tsup.egoist.dev/), and [Vitest](https://vitest.dev/)\n\n## 🔗 Related Projects\n\n- [http-status-codes](https://github.com/prettymuchbryce/http-status-codes) - Alternative HTTP status code library\n- [statuses](https://github.com/jshttp/statuses) - HTTP status utility\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Made with ❤️ by developers, for developers**\n\nIf you find this package useful, please consider giving it a ⭐ on [GitHub](https://github.com/iamgerwin/http-code-responses)!\n\n\u003c/div\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiamgerwin%2Fhttp-code-responses","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiamgerwin%2Fhttp-code-responses","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiamgerwin%2Fhttp-code-responses/lists"}