ts-packages 1.0.0 → 3.0.0

package/packages/errors-utils/dist/types/middleware/express/errorConverter.middleware.d.ts

@@ -0,0 +1,2 @@
+import type { NextFunction, Request, Response } from 'express';
+export declare function errorConverter(err: unknown, _req: Request, _res: Response, next: NextFunction): void;

package/packages/errors-utils/dist/types/middleware/express/errorHandler.middleware.d.ts

@@ -0,0 +1,2 @@
+import type { NextFunction, Request, Response } from 'express';
+export declare function expressErrorHandler(err: unknown, _req: Request, res: Response, _next: NextFunction): any;

package/packages/errors-utils/dist/types/middleware/express/index.d.ts

@@ -0,0 +1,2 @@
+export * from './errorHandler.middleware';
+export * from './errorConverter.middleware';

package/packages/errors-utils/node_modules/.bin/rimraf

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/namandev2704/projects/ts-packages/node_modules/.pnpm/rimraf@5.0.10/node_modules/rimraf/dist/esm/node_modules:/home/namandev2704/projects/ts-packages/node_modules/.pnpm/rimraf@5.0.10/node_modules/rimraf/dist/node_modules:/home/namandev2704/projects/ts-packages/node_modules/.pnpm/rimraf@5.0.10/node_modules/rimraf/node_modules:/home/namandev2704/projects/ts-packages/node_modules/.pnpm/rimraf@5.0.10/node_modules:/home/namandev2704/projects/ts-packages/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/namandev2704/projects/ts-packages/node_modules/.pnpm/rimraf@5.0.10/node_modules/rimraf/dist/esm/node_modules:/home/namandev2704/projects/ts-packages/node_modules/.pnpm/rimraf@5.0.10/node_modules/rimraf/dist/node_modules:/home/namandev2704/projects/ts-packages/node_modules/.pnpm/rimraf@5.0.10/node_modules/rimraf/node_modules:/home/namandev2704/projects/ts-packages/node_modules/.pnpm/rimraf@5.0.10/node_modules:/home/namandev2704/projects/ts-packages/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../rimraf/dist/esm/bin.mjs" "$@"
+else
+  exec node  "$basedir/../rimraf/dist/esm/bin.mjs" "$@"
+fi

package/packages/errors-utils/node_modules/.bin/tsc

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/namandev2704/projects/ts-packages/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/bin/node_modules:/home/namandev2704/projects/ts-packages/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/namandev2704/projects/ts-packages/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/namandev2704/projects/ts-packages/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/namandev2704/projects/ts-packages/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/bin/node_modules:/home/namandev2704/projects/ts-packages/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/namandev2704/projects/ts-packages/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/namandev2704/projects/ts-packages/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsc" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsc" "$@"
+fi

package/packages/errors-utils/node_modules/.bin/tsserver

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/namandev2704/projects/ts-packages/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/bin/node_modules:/home/namandev2704/projects/ts-packages/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/namandev2704/projects/ts-packages/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/namandev2704/projects/ts-packages/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/namandev2704/projects/ts-packages/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/bin/node_modules:/home/namandev2704/projects/ts-packages/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/namandev2704/projects/ts-packages/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/namandev2704/projects/ts-packages/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsserver" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsserver" "$@"
+fi

package/packages/errors-utils/package.json

@@ -0,0 +1,42 @@
+{
+    "name": "@naman_deep_singh/errors-utils",
+    "version": "1.4.2",
+    "description": "Standardized error classes and Express middleware for consistent error handling with TypeScript",
+    "type": "module",
+    "main": "./dist/cjs/index.js",
+    "module": "./dist/esm/index.js",
+    "exports": {
+        ".": {
+            "import": "./dist/esm/index.js",
+            "require": "./dist/cjs/index.js",
+            "types": "./dist/types/index.d.ts"
+        }
+    },
+    "sideEffects": false,
+    "files": [
+        "dist",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "pnpm run build:types && tsc -p tsconfig.cjs.json && tsc -p tsconfig.esm.json",
+        "build:types": "tsc -p tsconfig.base.json --emitDeclarationOnly --outDir dist/types",
+        "clean": "rimraf dist",
+        "prepublishOnly": "npm run clean && npm run build"
+    },
+    "keywords": [
+        "errors"
+    ],
+    "author": "Naman Deep Singh",
+    "license": "ISC",
+    "packageManager": "pnpm@10.20.0",
+    "devDependencies": {
+        "@types/express": "^5.0.5",
+        "@types/node": "^25.0.1",
+        "express": "^5.1.0",
+        "rimraf": "^5.0.5",
+        "typescript": "^5.9.3"
+    },
+    "dependencies": {
+        "@naman_deep_singh/response-utils": "^2.1.4"
+    }
+}

package/packages/errors-utils/src/constants/errorCodes.ts

@@ -0,0 +1,78 @@
+export const ERROR_CODES = {
+	/* ------------------------------------------------------------------ */
+	/* 🧱 Common / Generic                                                  */
+	/* ------------------------------------------------------------------ */
+	BAD_REQUEST: 'BAD_REQUEST',
+	VALIDATION_FAILED: 'VALIDATION_FAILED',
+	UNAUTHORIZED: 'UNAUTHORIZED',
+	FORBIDDEN: 'FORBIDDEN',
+	NOT_FOUND: 'NOT_FOUND',
+	CONFLICT: 'CONFLICT',
+	TOO_MANY_REQUESTS: 'TOO_MANY_REQUESTS',
+
+	INTERNAL_SERVER_ERROR: 'INTERNAL_SERVER_ERROR',
+	SERVICE_UNAVAILABLE: 'SERVICE_UNAVAILABLE',
+	DEPENDENCY_FAILURE: 'DEPENDENCY_FAILURE',
+
+	/* ------------------------------------------------------------------ */
+	/* 🌐 HTTP / Network                                                    */
+	/* ------------------------------------------------------------------ */
+	HTTP_ERROR: 'HTTP_ERROR',
+	HTTP_TIMEOUT: 'HTTP_TIMEOUT',
+	UPSTREAM_SERVICE_ERROR: 'UPSTREAM_SERVICE_ERROR',
+
+	/* ------------------------------------------------------------------ */
+	/* 🔐 Authentication / Authorization                                   */
+	/* ------------------------------------------------------------------ */
+	AUTH_FAILED: 'AUTH_FAILED',
+	TOKEN_MISSING: 'TOKEN_MISSING',
+	TOKEN_INVALID: 'TOKEN_INVALID',
+	TOKEN_EXPIRED: 'TOKEN_EXPIRED',
+
+	/* ------------------------------------------------------------------ */
+	/* 🔑 Cryptography / Security                                          */
+	/* ------------------------------------------------------------------ */
+	CRYPTO_ERROR: 'CRYPTO_ERROR',
+	CRYPTO_INTEGRITY_ERROR: 'CRYPTO_INTEGRITY_ERROR',
+
+	/* ------------------------------------------------------------------ */
+	/* 💾 Cache                                                             */
+	/* ------------------------------------------------------------------ */
+	CACHE_ERROR: 'CACHE_ERROR',
+	CACHE_CONNECTION_FAILED: 'CACHE_CONNECTION_FAILED',
+
+	/* ------------------------------------------------------------------ */
+	/* 🗄️ Database                                                          */
+	/* ------------------------------------------------------------------ */
+	DATABASE_ERROR: 'DATABASE_ERROR',
+	DATABASE_CONNECTION_FAILED: 'DATABASE_CONNECTION_FAILED',
+	DATABASE_CONSTRAINT_VIOLATION: 'DATABASE_CONSTRAINT_VIOLATION',
+
+	/* ------------------------------------------------------------------ */
+	/* 📩 Messaging / Queues                                                */
+	/* ------------------------------------------------------------------ */
+	MESSAGE_BROKER_ERROR: 'MESSAGE_BROKER_ERROR',
+	MESSAGE_PUBLISH_FAILED: 'MESSAGE_PUBLISH_FAILED',
+
+	/* ------------------------------------------------------------------ */
+	/* 📁 File / Storage                                                    */
+	/* ------------------------------------------------------------------ */
+	FILE_ERROR: 'FILE_ERROR',
+	FILE_NOT_FOUND: 'FILE_NOT_FOUND',
+	FILE_UPLOAD_FAILED: 'FILE_UPLOAD_FAILED',
+	FILE_TOO_LARGE: 'FILE_TOO_LARGE',
+
+	/* ------------------------------------------------------------------ */
+	/* ⚙️ Configuration / Environment                                      */
+	/* ------------------------------------------------------------------ */
+	CONFIG_ERROR: 'CONFIG_ERROR',
+	CONFIG_MISSING: 'CONFIG_MISSING',
+
+	/* ------------------------------------------------------------------ */
+	/* ⏱️ Timeouts / Resources                                              */
+	/* ------------------------------------------------------------------ */
+	TIMEOUT_ERROR: 'TIMEOUT_ERROR',
+	RESOURCE_EXHAUSTED: 'RESOURCE_EXHAUSTED',
+} as const
+
+export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES]

package/packages/errors-utils/src/constants/errorMessages.ts

@@ -0,0 +1,94 @@
+import { ERROR_CODES, type ErrorCode } from './errorCodes'
+
+/**
+ * Canonical error messages mapped to ERROR_CODES
+ * - Human-readable
+ * - Safe for API responses
+ * - Useful for logs
+ * - Can be overridden by services if needed
+ */
+
+export const ERROR_MESSAGES: Record<ErrorCode, string> = {
+	/* ------------------------------------------------------------------ */
+	/* 🧱 Common / Generic                                                  */
+	/* ------------------------------------------------------------------ */
+	[ERROR_CODES.BAD_REQUEST]: 'The request is invalid or malformed.',
+	[ERROR_CODES.VALIDATION_FAILED]: 'Request validation failed.',
+	[ERROR_CODES.UNAUTHORIZED]: 'Authentication is required.',
+	[ERROR_CODES.FORBIDDEN]: 'You do not have permission to perform this action.',
+	[ERROR_CODES.NOT_FOUND]: 'The requested resource was not found.',
+	[ERROR_CODES.CONFLICT]:
+		'The request could not be completed due to a conflict.',
+	[ERROR_CODES.TOO_MANY_REQUESTS]: 'Too many requests. Please try again later.',
+
+	[ERROR_CODES.INTERNAL_SERVER_ERROR]: 'An unexpected internal error occurred.',
+	[ERROR_CODES.SERVICE_UNAVAILABLE]: 'The service is currently unavailable.',
+	[ERROR_CODES.DEPENDENCY_FAILURE]: 'A dependent service failed to respond.',
+
+	/* ------------------------------------------------------------------ */
+	/* 🌐 HTTP / Network                                                    */
+	/* ------------------------------------------------------------------ */
+	[ERROR_CODES.HTTP_ERROR]:
+		'An HTTP error occurred while processing the request.',
+	[ERROR_CODES.HTTP_TIMEOUT]: 'The request timed out.',
+	[ERROR_CODES.UPSTREAM_SERVICE_ERROR]:
+		'An upstream service returned an error.',
+
+	/* ------------------------------------------------------------------ */
+	/* 🔐 Authentication / Authorization                                   */
+	/* ------------------------------------------------------------------ */
+	[ERROR_CODES.AUTH_FAILED]: 'Authentication failed.',
+	[ERROR_CODES.TOKEN_MISSING]: 'Authentication token is missing.',
+	[ERROR_CODES.TOKEN_INVALID]: 'Authentication token is invalid.',
+	[ERROR_CODES.TOKEN_EXPIRED]: 'Authentication token has expired.',
+
+	/* ------------------------------------------------------------------ */
+	/* 🔑 Cryptography / Security                                          */
+	/* ------------------------------------------------------------------ */
+	[ERROR_CODES.CRYPTO_ERROR]: 'A cryptographic operation failed.',
+	[ERROR_CODES.CRYPTO_INTEGRITY_ERROR]: 'Data integrity verification failed.',
+
+	/* ------------------------------------------------------------------ */
+	/* 💾 Cache                                                             */
+	/* ------------------------------------------------------------------ */
+	[ERROR_CODES.CACHE_ERROR]: 'A cache operation failed.',
+	[ERROR_CODES.CACHE_CONNECTION_FAILED]:
+		'Failed to connect to the cache store.',
+
+	/* ------------------------------------------------------------------ */
+	/* 🗄️ Database                                                          */
+	/* ------------------------------------------------------------------ */
+	[ERROR_CODES.DATABASE_ERROR]: 'A database error occurred.',
+	[ERROR_CODES.DATABASE_CONNECTION_FAILED]:
+		'Failed to connect to the database.',
+	[ERROR_CODES.DATABASE_CONSTRAINT_VIOLATION]:
+		'The operation violates a database constraint.',
+
+	/* ------------------------------------------------------------------ */
+	/* 📩 Messaging / Queues                                                */
+	/* ------------------------------------------------------------------ */
+	[ERROR_CODES.MESSAGE_BROKER_ERROR]: 'A message broker error occurred.',
+	[ERROR_CODES.MESSAGE_PUBLISH_FAILED]:
+		'Failed to publish message to the message broker.',
+
+	/* ------------------------------------------------------------------ */
+	/* 📁 File / Storage                                                    */
+	/* ------------------------------------------------------------------ */
+	[ERROR_CODES.FILE_ERROR]: 'A file operation failed.',
+	[ERROR_CODES.FILE_NOT_FOUND]: 'The requested file was not found.',
+	[ERROR_CODES.FILE_UPLOAD_FAILED]: 'File upload failed.',
+	[ERROR_CODES.FILE_TOO_LARGE]: 'The uploaded file exceeds the allowed size.',
+
+	/* ------------------------------------------------------------------ */
+	/* ⚙️ Configuration / Environment                                      */
+	/* ------------------------------------------------------------------ */
+	[ERROR_CODES.CONFIG_ERROR]: 'Configuration error detected.',
+	[ERROR_CODES.CONFIG_MISSING]: 'Required configuration is missing.',
+
+	/* ------------------------------------------------------------------ */
+	/* ⏱️ Timeouts / Resources                                              */
+	/* ------------------------------------------------------------------ */
+	[ERROR_CODES.TIMEOUT_ERROR]: 'The operation timed out.',
+	[ERROR_CODES.RESOURCE_EXHAUSTED]:
+		'The system has exhausted required resources.',
+}

package/packages/errors-utils/src/constants/index.ts

@@ -0,0 +1,2 @@
+export * from './errorCodes'
+export * from './errorMessages'

package/packages/errors-utils/src/error/AppError.ts

@@ -0,0 +1,36 @@
+import { HTTP_STATUS } from '@naman_deep_singh/response-utils'
+import { errorMessageRegistry } from 'src'
+import type { ErrorCode } from '../constants'
+
+export class AppError extends Error {
+	public statusCode: number
+	public isOperational: boolean
+	public code: ErrorCode
+	public details?: unknown
+	public cause?: Error
+
+	constructor(
+		code: ErrorCode,
+		statusCode: number = HTTP_STATUS.SERVER_ERROR.INTERNAL_SERVER_ERROR,
+		details?: unknown,
+		cause?: Error,
+	) {
+		super(errorMessageRegistry.resolve(code)) // message comes from mapping
+		this.code = code
+		this.statusCode = statusCode
+		this.isOperational = true
+		this.details = details
+
+		if (cause) this.cause = cause
+		Error.captureStackTrace(this, this.constructor)
+	}
+
+	toJSON() {
+		return {
+			success: false,
+			code: this.code,
+			message: this.message,
+			details: this.details ?? null,
+		}
+	}
+}

package/packages/errors-utils/src/error/BadRequestError.ts

@@ -0,0 +1,14 @@
+import { HTTP_STATUS } from '@naman_deep_singh/response-utils'
+import { ERROR_CODES } from '../constants'
+import { HTTPError } from './HTTPError'
+
+export class BadRequestError extends HTTPError {
+	constructor(details?: unknown, cause?: Error) {
+		super(
+			ERROR_CODES.BAD_REQUEST,
+			HTTP_STATUS.CLIENT_ERROR.BAD_REQUEST,
+			details,
+			cause,
+		)
+	}
+}

package/packages/errors-utils/src/error/ConflictError.ts

@@ -0,0 +1,14 @@
+import { HTTP_STATUS } from '@naman_deep_singh/response-utils'
+import { ERROR_CODES } from 'src/constants'
+import { HTTPError } from './HTTPError'
+
+export class ConflictError extends HTTPError {
+	constructor(details?: unknown, cause?: Error) {
+		super(
+			ERROR_CODES.CONFLICT,
+			HTTP_STATUS.CLIENT_ERROR.CONFLICT,
+			details,
+			cause,
+		)
+	}
+}

package/packages/errors-utils/src/error/CryptoIntegrityError.ts

@@ -0,0 +1,8 @@
+import { ERROR_CODES } from 'src/constants'
+import { InternalServerError } from './InternalServerError'
+
+export class CryptoIntegrityError extends InternalServerError {
+	constructor(details?: unknown, cause?: Error) {
+		super(ERROR_CODES.CRYPTO_INTEGRITY_ERROR, details, cause)
+	}
+}

package/packages/errors-utils/src/error/ForbiddenError.ts

@@ -0,0 +1,14 @@
+import { HTTP_STATUS } from '@naman_deep_singh/response-utils'
+import { ERROR_CODES } from 'src/constants'
+import { HTTPError } from './HTTPError'
+
+export class ForbiddenError extends HTTPError {
+	constructor(details?: unknown, cause?: Error) {
+		super(
+			ERROR_CODES.FORBIDDEN,
+			HTTP_STATUS.CLIENT_ERROR.FORBIDDEN,
+			details,
+			cause,
+		)
+	}
+}

package/packages/errors-utils/src/error/HTTPError.ts

@@ -0,0 +1,17 @@
+import type { ErrorCode } from '../constants'
+import { AppError } from './AppError'
+
+export class HTTPError extends AppError {
+	public status: 'fail' | 'error'
+
+	constructor(
+		errorCode: ErrorCode,
+		statusCode: number,
+		details?: unknown,
+		cause?: Error,
+	) {
+		super(errorCode, statusCode, details, cause)
+
+		this.status = statusCode >= 400 && statusCode < 500 ? 'fail' : 'error'
+	}
+}

package/packages/errors-utils/src/error/InternalServerError.ts

@@ -0,0 +1,18 @@
+import { HTTP_STATUS } from '@naman_deep_singh/response-utils'
+import { ERROR_CODES, type ErrorCode } from 'src/constants'
+import { HTTPError } from './HTTPError'
+
+export class InternalServerError extends HTTPError {
+	constructor(
+		errorCode: ErrorCode = ERROR_CODES.INTERNAL_SERVER_ERROR,
+		details?: unknown,
+		cause?: Error,
+	) {
+		super(
+			errorCode,
+			HTTP_STATUS.SERVER_ERROR.INTERNAL_SERVER_ERROR,
+			details,
+			cause,
+		)
+	}
+}

package/packages/errors-utils/src/error/NotFoundError.ts

@@ -0,0 +1,14 @@
+import { HTTP_STATUS } from '@naman_deep_singh/response-utils'
+import { ERROR_CODES } from 'src/constants'
+import { HTTPError } from './HTTPError'
+
+export class NotFoundError extends HTTPError {
+	constructor(details?: unknown, cause?: Error) {
+		super(
+			ERROR_CODES.NOT_FOUND,
+			HTTP_STATUS.CLIENT_ERROR.NOT_FOUND,
+			details,
+			cause,
+		)
+	}
+}

package/packages/errors-utils/src/error/ServiceUnavailableError.ts

@@ -0,0 +1,8 @@
+import { ERROR_CODES } from 'src/constants'
+import { InternalServerError } from './InternalServerError'
+
+export class ServiceUnavailableError extends InternalServerError {
+	constructor(details?: unknown, cause?: Error) {
+		super(ERROR_CODES.SERVICE_UNAVAILABLE, details, cause)
+	}
+}

package/packages/errors-utils/src/error/TokenExpiredError.ts

@@ -0,0 +1,14 @@
+import { HTTP_STATUS } from '@naman_deep_singh/response-utils'
+import { ERROR_CODES } from 'src/constants'
+import { HTTPError } from './HTTPError'
+
+export class TokenExpiredError extends HTTPError {
+	constructor(details?: unknown, cause?: Error) {
+		super(
+			ERROR_CODES.TOKEN_EXPIRED,
+			HTTP_STATUS.CLIENT_ERROR.UNAUTHORIZED,
+			details,
+			cause,
+		)
+	}
+}

package/packages/errors-utils/src/error/TokenMalformedError.ts

@@ -0,0 +1,14 @@
+import { HTTP_STATUS } from '@naman_deep_singh/response-utils'
+import { ERROR_CODES } from 'src/constants'
+import { HTTPError } from './HTTPError'
+
+export class TokenMalformedError extends HTTPError {
+	constructor(details?: unknown, cause?: Error) {
+		super(
+			ERROR_CODES.TOKEN_INVALID,
+			HTTP_STATUS.CLIENT_ERROR.UNAUTHORIZED,
+			details,
+			cause,
+		)
+	}
+}

package/packages/errors-utils/src/error/TooManyRequestsError.ts

@@ -0,0 +1,13 @@
+import { HTTP_STATUS } from '@naman_deep_singh/response-utils'
+import { ERROR_CODES, type ErrorCode } from 'src/constants'
+import { HTTPError } from './HTTPError'
+
+export class TooManyRequestsError extends HTTPError {
+	constructor(
+		errorCode: ErrorCode = ERROR_CODES.TOO_MANY_REQUESTS,
+		details?: unknown,
+		cause?: Error,
+	) {
+		super(errorCode, HTTP_STATUS.CLIENT_ERROR.TOO_MANY_REQUESTS, details, cause)
+	}
+}

package/packages/errors-utils/src/error/UnauthorizedError.ts

@@ -0,0 +1,14 @@
+import { HTTP_STATUS } from '@naman_deep_singh/response-utils'
+import { ERROR_CODES } from 'src/constants'
+import { HTTPError } from './HTTPError'
+
+export class UnauthorizedError extends HTTPError {
+	constructor(details?: unknown, cause?: Error) {
+		super(
+			ERROR_CODES.UNAUTHORIZED,
+			HTTP_STATUS.CLIENT_ERROR.UNAUTHORIZED,
+			details,
+			cause,
+		)
+	}
+}

package/packages/errors-utils/src/error/ValidationError.ts

@@ -0,0 +1,14 @@
+import { HTTP_STATUS } from '@naman_deep_singh/response-utils'
+import { ERROR_CODES } from 'src/constants'
+import { HTTPError } from './HTTPError'
+
+export class ValidationError extends HTTPError {
+	constructor(details?: unknown, cause?: Error) {
+		super(
+			ERROR_CODES.VALIDATION_FAILED,
+			HTTP_STATUS.CLIENT_ERROR.UNPROCESSABLE_ENTITY,
+			details,
+			cause,
+		)
+	}
+}

package/packages/errors-utils/src/error/index.ts

@@ -0,0 +1,26 @@
+export * from './AppError'
+export * from './HTTPError'
+
+// =========================
+// 4xx Client Errors
+// =========================
+export * from './BadRequestError'
+export * from './UnauthorizedError'
+export * from './ForbiddenError'
+export * from './NotFoundError'
+export * from './ConflictError'
+export * from './ValidationError'
+export * from './TooManyRequestsError'
+
+// =========================
+// Auth / Token Errors
+// =========================
+export * from './TokenExpiredError'
+export * from './TokenMalformedError'
+
+// =========================
+// 5xx Server Errors
+// =========================
+export * from './InternalServerError'
+export * from './CryptoIntegrityError'
+export * from './ServiceUnavailableError'

package/packages/errors-utils/src/errorRegistry/errorRegistry.ts

@@ -0,0 +1,74 @@
+import { HTTP_STATUS } from '@naman_deep_singh/response-utils'
+import type { ExpressResponder } from '@naman_deep_singh/response-utils'
+import { ERROR_MESSAGES, type ErrorCode } from 'src/constants'
+import type { AppError } from 'src/error/AppError'
+
+export class ErrorMessageRegistry {
+	private static instance: ErrorMessageRegistry
+	private readonly registry = new Map<ErrorCode | string, string>()
+
+	private constructor() {
+		// Initialize with default messages
+		Object.entries(ERROR_MESSAGES).forEach(([code, message]) => {
+			this.registry.set(code, message)
+		})
+	}
+
+	/** Singleton accessor */
+	public static getInstance(): ErrorMessageRegistry {
+		if (!ErrorMessageRegistry.instance) {
+			ErrorMessageRegistry.instance = new ErrorMessageRegistry()
+		}
+		return ErrorMessageRegistry.instance
+	}
+
+	/** Register or override messages */
+	public register(messages: Record<string, string>): void {
+		for (const [code, message] of Object.entries(messages)) {
+			this.registry.set(code, message)
+		}
+	}
+
+	/** Resolve a message for a given error code */
+	public resolve(
+		code: ErrorCode | string,
+		defaultMessage = 'Unexpected error',
+	): string {
+		return this.registry.get(code) ?? defaultMessage
+	}
+
+	/**
+	 * Map an AppError to an ExpressResponder
+	 * Centralizes error-to-HTTP mapping
+	 */
+	public mapAppErrorToResponder(
+		responder: ExpressResponder<unknown>,
+		err: AppError,
+	) {
+		switch (err.statusCode) {
+			case HTTP_STATUS.CLIENT_ERROR.BAD_REQUEST:
+				return responder.badRequest(this.resolve(err.code), {
+					details: err.details,
+				})
+			case HTTP_STATUS.CLIENT_ERROR.UNAUTHORIZED:
+				return responder.unauthorized(this.resolve(err.code))
+			case HTTP_STATUS.CLIENT_ERROR.FORBIDDEN:
+				return responder.forbidden(this.resolve(err.code))
+			case HTTP_STATUS.CLIENT_ERROR.NOT_FOUND:
+				return responder.notFound(this.resolve(err.code))
+			case HTTP_STATUS.CLIENT_ERROR.CONFLICT:
+				return responder.conflict(this.resolve(err.code))
+			case HTTP_STATUS.CLIENT_ERROR.UNPROCESSABLE_ENTITY:
+				return responder.unprocessableEntity(this.resolve(err.code), {
+					details: err.details,
+				})
+			case HTTP_STATUS.CLIENT_ERROR.TOO_MANY_REQUESTS:
+				return responder.tooManyRequests(this.resolve(err.code))
+			default:
+				// Any other status maps to generic server error
+				return responder.serverError(this.resolve(err.code), {
+					details: err.details,
+				})
+		}
+	}
+}

package/packages/errors-utils/src/errorRegistry/index.ts

@@ -0,0 +1,4 @@
+import { ErrorMessageRegistry } from './errorRegistry'
+
+/** Singleton export for easy access */
+export const errorMessageRegistry = ErrorMessageRegistry.getInstance()

package/packages/errors-utils/src/index.ts

@@ -0,0 +1,13 @@
+export * from './errorRegistry'
+// =========================
+// default errors
+// =========================
+export * from './error'
+// =========================
+// Constants
+// =========================
+export * from './constants'
+// =========================
+// Express Middleware
+// =========================
+export * from './middleware/express'