feat: 🚀 Initialized Repo

Author: Mohamed Johnson [SNT DSI/DAC/DIM/DS]

.gitignore

@@ -0,0 +1,2 @@
+node_modules
+yarn.lock

README

@@ -0,0 +1,118 @@
+# http-errors-plus
+
+> The next-generation HTTP error system for JavaScript & TypeScript — designed for modern DX, structured observability, and future-proof error handling.
+
+---
+
+## ⚡ Why http-errors-plus?
+
+`http-errors` served us well — but it’s stuck in a CommonJS world with stringly-typed messages and zero structure and inspired me to do this.
+
+**http-errors-plus** gives you:
+
+✅ Fully ESM-ready and works in both JS and TS  
+✅ Named constants like `NOT_FOUND`, `BAD_REQUEST`, etc.  
+✅ Overrideable metadata: `detail`, `path`, `traceId`, `requestId`, etc.  
+✅ Drop-in `generateError()` utility  
+✅ Strong IntelliSense via JSDoc  
+✅ `HttpError` class with `.toJSON()` and APM-ready structure
+
+---
+
+## 🚀 Installation
+
+```bash
+yarn add http-errors-plus
+```
+
+---
+
+## 🧑‍💻 Usage
+
+### Import and Use Named Constants
+```js
+import { BASE_HTTP_ERRORS, generateError } from 'http-errors-plus';
+
+const { NOT_FOUND } = BASE_HTTP_ERRORS;
+
+throw generateError(NOT_FOUND, {
+  detail: 'User with ID 42 not found',
+  path: '/api/users/42',
+  requestId: 'req-xyz-123',
+});
+```
+
+### Output
+```json
+{
+  "status": 404,
+  "code": "NOT_FOUND",
+  "message": "Not Found",
+  "detail": "User with ID 42 not found",
+  "path": "/api/users/42",
+  "timestamp": "2025-05-17T12:00:00Z",
+  "requestId": "req-xyz-123"
+}
+```
+
+---
+
+## 📦 Exported API
+
+### ✅ Constants
+```js
+BASE_HTTP_ERRORS.NOT_FOUND      // { status: 404, code: 'NOT_FOUND', message: 'Not Found' }
+BASE_HTTP_ERRORS.BAD_REQUEST    // { status: 400, code: 'BAD_REQUEST', message: 'Bad Request' }
+// ... all standard HTTP codes covered
+```
+
+### ✅ generateError(base, overrides?)
+Creates a new error object based on a constant.
+
+```js
+const error = generateError(BASE_HTTP_ERRORS.CONFLICT, {
+  detail: 'Email already exists',
+  requestId: 'abc123',
+});
+```
+
+### ✅ HttpError Class
+```js
+new HttpError(403, {
+  code: 'FORBIDDEN',
+  message: 'Access denied',
+  detail: 'Only admins can access this resource.',
+})
+```
+
+---
+
+## 🔍 Coming Soon
+- `isHttpError()` type guard
+- RFC 7807 `.toProblemJSON()` support
+- Built-in middleware for Express/Fastify
+- Auto-i18n key support
+
+---
+
+## 💡 Philosophy
+HTTP errors should be:
+- Human-readable
+- Machine-parseable
+- Developer-first
+- Easy to maintain and override
+
+---
+
+## 🧠 Inspiration
+Built as a modern successor to `http-errors` and `statuses`, with a fresh take on API dev ergonomics.
+
+---
+
+## 🪪 License
+MIT — Use it, ship it, improve it.
+
+---
+
+## ✨ Author
+Made by Mohamed Johnson. 🧠 Powered by clarity, DX obsession, and no chill mode.

index.js

@@ -0,0 +1,9 @@
+// import { BASE_HTTP_ERRORS } from './constants.js';
+// import { HttpError } from './http-error.js';
+// import { generateError } from './generateError.js';
+
+import { BASE_HTTP_ERRORS } from "./src/constants/index.js";
+import { generateError } from "./utils/generateError.js";
+import { HttpError } from "./utils/http-error.js";
+
+export { HttpError, generateError, BASE_HTTP_ERRORS };

package.json

@@ -0,0 +1,73 @@
+{
+  "name": "http-errors-plus",
+  "version": "1.0.0",
+  "description": "Next-gen HTTP error handling for modern JavaScript and TypeScript apps — structured, overrideable, and developer-focused.",
+  "main": "./src/index.js",
+  "exports": {
+    ".": {
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.esm.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "types": "./types/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "types",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node test/basic.test.js",
+    "lint": "echo 'linting coming soon'",
+    "build": "echo 'no build needed — pure JS'"
+  },
+  "keywords": [
+    "http",
+    "error",
+    "errors",
+    "http-errors",
+    "structured-errors",
+    "http status",
+    "api",
+    "developer-experience",
+    "observable",
+    "typescript",
+    "javascript",
+    "ESM",
+    "fastify",
+    "express"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/your-username/http-errors-plus.git"
+  },
+  "bugs": {
+    "url": "https://github.com/your-username/http-errors-plus/issues"
+  },
+  "homepage": "https://github.com/your-username/http-errors-plus#readme",
+  "author": {
+    "name": "Mohamed Johnson",
+    "email": "you@example.com",
+    "url": "https://github.com/LPIX-11"
+  },
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+    "devDependencies": {
+    "@jsdoc/salty": "^0.2.8",
+    "@types/events": "^3.0.3",
+    "@types/linkify-it": "^5.0.0",
+    "@types/node": "^22.5.4",
+    "better-docs": "^2.7.3",
+    "prettier": "^3.2.5",
+    "typescript": "^5.5.4",
+    "vite": "^5.4.3"
+  },
+  "dependencies": {
+    "statuses": "^2.0.1"
+  }
+}

src/constants/index.js

@@ -0,0 +1,78 @@
+import statuses from 'statuses';
+
+/**
+ * @typedef {Object} StatusEntry
+ * @property {number} code
+ * @property {string} name
+ * @property {string} message
+ */
+
+/**
+ * Maps HTTP status code to name/message
+ * @type {Record<number, StatusEntry>}
+ */
+export const STATUS_CODE_MAP = statuses.codes.reduce((acc, code) => {
+  const name = statuses.message[code].toUpperCase().replace(/[^A-Z0-9]+/g, '_');
+  acc[code] = {
+    code,
+    name,
+    message: statuses.message[code],
+  };
+  return acc;
+}, {});
+
+/**
+ * Maps HTTP status name to code
+ * @type {Record<string, StatusEntry>}
+ */
+export const STATUS_NAME_MAP = Object.values(STATUS_CODE_MAP).reduce((acc, { code, name, message }) => {
+  acc[name] = { code, name, message };
+  return acc;
+}, {});
+
+/**
+ * @typedef {Object} HttpErrorConstant
+ * @property {number} status - HTTP status code
+ * @property {string} code - Uppercase constant name (e.g., NOT_FOUND)
+ * @property {string} message - Human-readable HTTP message
+ */
+
+/**
+ * @typedef {{
+ *   CONTINUE: HttpErrorConstant,
+ *   SWITCHING_PROTOCOLS: HttpErrorConstant,
+ *   PROCESSING: HttpErrorConstant,
+ *   OK: HttpErrorConstant,
+ *   CREATED: HttpErrorConstant,
+ *   ACCEPTED: HttpErrorConstant,
+ *   NO_CONTENT: HttpErrorConstant,
+ *   MOVED_PERMANENTLY: HttpErrorConstant,
+ *   FOUND: HttpErrorConstant,
+ *   NOT_MODIFIED: HttpErrorConstant,
+ *   BAD_REQUEST: HttpErrorConstant,
+ *   UNAUTHORIZED: HttpErrorConstant,
+ *   FORBIDDEN: HttpErrorConstant,
+ *   NOT_FOUND: HttpErrorConstant,
+ *   METHOD_NOT_ALLOWED: HttpErrorConstant,
+ *   CONFLICT: HttpErrorConstant,
+ *   UNPROCESSABLE_ENTITY: HttpErrorConstant,
+ *   TOO_MANY_REQUESTS: HttpErrorConstant,
+ *   INTERNAL_SERVER_ERROR: HttpErrorConstant,
+ *   BAD_GATEWAY: HttpErrorConstant,
+ *   SERVICE_UNAVAILABLE: HttpErrorConstant,
+ *   GATEWAY_TIMEOUT: HttpErrorConstant
+ * }} BaseHttpErrors
+ */
+
+/**
+ * @type {BaseHttpErrors}
+ */
+export const BASE_HTTP_ERRORS = Object.fromEntries(
+  Object.values(STATUS_CODE_MAP).map(({ code, name, message }) => {
+    return [name, Object.freeze({ status: code, code: name, message })];
+  })
+);
+// /**
+//  * Export default constants (e.g. NOT_FOUND, BAD_REQUEST)
+//  * @type {Record<string, { status: number, code: string, message: string }>}
+//  */

utils/generateError.js

@@ -0,0 +1,14 @@
+import { HttpError } from './http-error.js';
+
+/**
+ * @param {{ status: number, code: string, message: string }} base
+ * @param {Partial<import('./http-error.js').SerializedHttpError>} [override]
+ * @returns {HttpError}
+ */
+export function generateError(base, override = {}) {
+  return new HttpError(base.status, {
+    code: base.code,
+    message: override.message || base.message,
+    ...override,
+  });
+}

utils/http-error.js

@@ -0,0 +1,37 @@
+/**
+ * @typedef {Object} SerializedHttpError
+ * @property {number} status
+ * @property {string} code
+ * @property {string} message
+ * @property {string} [detail]
+ * @property {string} [path]
+ * @property {string} [method]
+ * @property {string} [timestamp]
+ * @property {string} [requestId]
+ * @property {string} [traceId]
+ */
+
+export class HttpError extends Error {
+  /**
+   * @param {number} status
+   * @param {Omit<SerializedHttpError, 'status'>} options
+   */
+  constructor(status, options) {
+    super(options.message);
+    this.name = 'HttpError';
+
+    /** @type {SerializedHttpError} */
+    this.meta = {
+      status,
+      timestamp: new Date().toISOString(),
+      ...options,
+    };
+  }
+
+  /**
+   * @returns {SerializedHttpError}
+   */
+  toJSON() {
+    return this.meta;
+  }
+}