@naman_deep_singh/http-response 3.0.0

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@naman_deep_singh/http-response",
+  "version": "3.0.0",
+  "description": "TypeScript utilities for standardized API responses",
+  "author": "Naman Deep Singh",
+  "license": "MIT",
+  "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"
+    },
+    "./express": {
+      "import": "./dist/esm/adapters/express/index.js",
+      "require": "./dist/cjs/adapters/express/index.js",
+      "types": "./dist/types/adapters/express/index.d.ts"
+    },
+    "./legacy": {
+      "import": "./dist/esm/legacy/index.js",
+      "require": "./dist/cjs/legacy/index.js",
+      "types": "./dist/types/legacy/index.d.ts"
+    }
+  },
+  "sideEffects": false,
+  "keywords": [
+    "response",
+    "http",
+    "api",
+    "utils",
+    "express",
+    "typescript"
+  ],
+  "peerDependencies": {
+    "express": "^5.1.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.5",
+    "express": "^5.1.0",
+    "typescript": "^5.9.3",
+    "rimraf": "^5.0.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "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"
+  }
+}

package/src/adapters/express/ExpressResponder.ts

@@ -0,0 +1,64 @@
+import type { Response } from 'express'
+import { BaseResponder } from '../../core/BaseResponder'
+import type { ResponderConfig } from '../../core/config'
+
+export class ExpressResponder<P = unknown> extends BaseResponder<P> {
+	constructor(
+		cfg: Partial<ResponderConfig> | undefined,
+		private readonly res: Response,
+	) {
+		// attach sender which calls res.status().json()
+		super(cfg, (status, body) => res.status(status).json(body))
+	}
+
+	// convenience methods that return void for middleware/controller ergonomics
+	okAndSend(data?: P, message?: string) {
+		void this.ok(data, message)
+	}
+
+	createdAndSend(data?: P, message?: string) {
+		void this.created(data, message)
+	}
+
+	badRequestAndSend(message?: string, error?: unknown) {
+		void this.badRequest(message, error)
+	}
+
+	unauthorizedAndSend(message?: string) {
+		void this.unauthorized(message)
+	}
+
+	forbiddenAndSend(message?: string) {
+		void this.forbidden(message)
+	}
+
+	notFoundAndSend(message?: string) {
+		void this.notFound(message)
+	}
+
+	conflictAndSend(message?: string) {
+		void this.conflict(message)
+	}
+
+	unprocessableEntityAndSend(message?: string, error?: unknown) {
+		void this.unprocessableEntity(message, error)
+	}
+
+	tooManyRequestsAndSend(message?: string) {
+		void this.tooManyRequests(message)
+	}
+
+	serverErrorAndSend(message?: string, error?: unknown) {
+		void this.serverError(message, error)
+	}
+
+	paginateAndSend(
+		data: P[],
+		page: number,
+		limit: number,
+		total: number,
+		message?: string,
+	) {
+		void this.paginate(data, page, limit, total, message)
+	}
+}

package/src/constants/httpStatus.ts

@@ -0,0 +1,42 @@
+const SUCCESS = Object.freeze({
+	OK: 200,
+	CREATED: 201,
+	ACCEPTED: 202,
+	NO_CONTENT: 204,
+} as const)
+
+const REDIRECTION = Object.freeze({
+	NOT_MODIFIED: 304,
+} as const)
+
+const CLIENT_ERROR = Object.freeze({
+	BAD_REQUEST: 400,
+	UNAUTHORIZED: 401,
+	FORBIDDEN: 403,
+	NOT_FOUND: 404,
+	METHOD_NOT_ALLOWED: 405,
+	CONFLICT: 409,
+	UNPROCESSABLE_ENTITY: 422,
+	TOO_MANY_REQUESTS: 429,
+} as const)
+
+const SERVER_ERROR = Object.freeze({
+	INTERNAL_SERVER_ERROR: 500,
+	NOT_IMPLEMENTED: 501,
+	BAD_GATEWAY: 502,
+	SERVICE_UNAVAILABLE: 503,
+} as const)
+
+export const HTTP_STATUS = Object.freeze({
+	SUCCESS,
+	REDIRECTION,
+	CLIENT_ERROR,
+	SERVER_ERROR,
+} as const)
+
+// flattened union type if needed:
+export type HttpStatusCode =
+	| (typeof SUCCESS)[keyof typeof SUCCESS]
+	| (typeof REDIRECTION)[keyof typeof REDIRECTION]
+	| (typeof CLIENT_ERROR)[keyof typeof CLIENT_ERROR]
+	| (typeof SERVER_ERROR)[keyof typeof SERVER_ERROR]

package/src/core/BaseResponder.ts

@@ -0,0 +1,198 @@
+import { HTTP_STATUS } from '../constants/httpStatus'
+
+import { type ResponderConfig, defaultConfig } from './config'
+
+import type { PaginationMeta, ResponseEnvelope, Sender } from './types'
+
+export class BaseResponder<P = unknown, M = PaginationMeta> {
+	protected readonly cfg: ResponderConfig
+	protected sender?: Sender
+
+	constructor(cfg?: Partial<ResponderConfig>, sender?: Sender) {
+		this.cfg = { ...defaultConfig, ...(cfg ?? {}) }
+		this.sender = sender
+	}
+
+	attachSender(sender: Sender) {
+		this.sender = sender
+	}
+
+	protected normalizeError(err: unknown): {
+		message: string
+		code?: string
+		details?: unknown
+	} {
+		// errors-utils AppError compatibility
+		if (typeof err === 'object' && err !== null) {
+			const e = err as Record<string, unknown>
+
+			if (typeof e.message === 'string') {
+				return {
+					message: e.message,
+					code: typeof e.code === 'string' ? e.code : undefined,
+					details: e.details,
+				}
+			}
+		}
+
+		if (err instanceof Error) {
+			return { message: err.message }
+		}
+
+		if (typeof err === 'string') {
+			return { message: err }
+		}
+
+		return {
+			message: 'Internal server error',
+			details: err,
+		}
+	}
+
+	protected buildEnvelope(
+		data?: P,
+		message?: string,
+		error?: unknown,
+		meta?: M,
+	) {
+		const env: ResponseEnvelope<P, M> = {
+			success: !error,
+			message: message ?? (error ? 'Error' : undefined),
+			data: error ? undefined : data,
+			error: error ? this.normalizeError(error) : null,
+			meta: meta ?? null,
+		}
+
+		if (this.cfg.timestamp) {
+			env.meta = {
+				...(env.meta ?? {}),
+				timestamp: new Date().toISOString(),
+			} as M
+		}
+
+		if (this.cfg.extra) {
+			Object.assign(env as Record<string, unknown>, this.cfg.extra)
+		}
+
+		return env
+	}
+
+	protected send(status: number, envelope: ResponseEnvelope<P, M>) {
+		if (!this.sender) return { status, body: envelope }
+		return this.sender(status, envelope)
+	}
+
+	/** -----------------------------
+	 *  Standard REST Response Helpers
+	 * ----------------------------- */
+	ok(data?: P, message = 'Success') {
+		return this.send(HTTP_STATUS.SUCCESS.OK, this.buildEnvelope(data, message))
+	}
+
+	created(data?: P, message = 'Created successfully') {
+		return this.send(
+			HTTP_STATUS.SUCCESS.CREATED,
+			this.buildEnvelope(data, message),
+		)
+	}
+
+	noContent(message = 'No Content') {
+		return this.send(
+			HTTP_STATUS.SUCCESS.NO_CONTENT,
+			this.buildEnvelope(undefined, message),
+		)
+	}
+
+	badRequest(message = 'Bad request', error?: unknown) {
+		return this.send(
+			HTTP_STATUS.CLIENT_ERROR.BAD_REQUEST,
+			this.buildEnvelope(undefined, message, error),
+		)
+	}
+
+	unauthorized(message = 'Unauthorized') {
+		return this.send(
+			HTTP_STATUS.CLIENT_ERROR.UNAUTHORIZED,
+			this.buildEnvelope(undefined, message),
+		)
+	}
+
+	forbidden(message = 'Forbidden') {
+		return this.send(
+			HTTP_STATUS.CLIENT_ERROR.FORBIDDEN,
+			this.buildEnvelope(undefined, message),
+		)
+	}
+
+	notFound(message = 'Not found') {
+		return this.send(
+			HTTP_STATUS.CLIENT_ERROR.NOT_FOUND,
+			this.buildEnvelope(undefined, message),
+		)
+	}
+
+	conflict(message = 'Conflict') {
+		return this.send(
+			HTTP_STATUS.CLIENT_ERROR.CONFLICT,
+			this.buildEnvelope(undefined, message),
+		)
+	}
+
+	unprocessableEntity(message = 'Unprocessable Entity', error?: unknown) {
+		return this.send(
+			HTTP_STATUS.CLIENT_ERROR.UNPROCESSABLE_ENTITY,
+			this.buildEnvelope(undefined, message, error),
+		)
+	}
+
+	tooManyRequests(message = 'Too Many Requests') {
+		return this.send(
+			HTTP_STATUS.CLIENT_ERROR.TOO_MANY_REQUESTS,
+			this.buildEnvelope(undefined, message),
+		)
+	}
+
+	serverError(message = 'Internal server error', error?: unknown) {
+		return this.send(
+			HTTP_STATUS.SERVER_ERROR.INTERNAL_SERVER_ERROR,
+			this.buildEnvelope(undefined, message, error),
+		)
+	}
+
+	paginate(
+		data: P[],
+		page: number,
+		limit: number,
+		total: number,
+		message = 'Success',
+	) {
+		const totalPages = Math.max(1, Math.ceil(total / limit))
+		const offset = (page - 1) * limit
+
+		const pagination: PaginationMeta = {
+			page,
+			limit,
+			total,
+			totalPages,
+			offset,
+			hasNext: page < totalPages,
+			hasPrev: page > 1,
+		}
+
+		return this.send(
+			HTTP_STATUS.SUCCESS.OK,
+			this.buildEnvelope(data as any, message, undefined, pagination as any),
+		)
+	}
+
+	paginateOffset(
+		data: P[],
+		offset: number,
+		limit: number,
+		total: number,
+		message = 'Success',
+	) {
+		const page = Math.floor(offset / limit) + 1
+		return this.paginate(data, page, limit, total, message)
+	}
+}

package/src/core/config.ts

@@ -0,0 +1,29 @@
+import type { PlainObject } from './types'
+
+export type EnvelopeKeys = {
+	success?: string
+	message?: string
+	data?: string
+	error?: string
+	meta?: string
+}
+
+export type ResponderConfig = {
+	envelopeKeys?: EnvelopeKeys
+	defaultStatus?: number
+	timestamp?: boolean
+	extra?: PlainObject | null
+}
+
+export const defaultConfig: ResponderConfig = {
+	envelopeKeys: {
+		success: 'success',
+		message: 'message',
+		data: 'data',
+		error: 'error',
+		meta: 'meta',
+	},
+	defaultStatus: 200,
+	timestamp: false,
+	extra: null,
+}

package/src/core/factory.ts

@@ -0,0 +1,11 @@
+import { ExpressResponder } from '../adapters/express/ExpressResponder'
+
+import type { ResponderConfig } from './config'
+
+export const createResponderFactory = (cfg?: Partial<ResponderConfig>) => {
+	return <P = unknown, _M = Record<string, unknown>>(
+		res: import('express').Response,
+	) => {
+		return new ExpressResponder<P>(cfg, res)
+	}
+}

package/src/core/types.ts

@@ -0,0 +1,34 @@
+export type PlainObject = Record<string, unknown>
+
+export type ErrorShape = {
+	code?: string
+	message: string
+	details?: unknown
+}
+
+export type ResponseEnvelope<T = unknown, M = PlainObject> = {
+	success: boolean
+	message?: string
+	data?: T
+	error?: ErrorShape | null
+	meta?: M | null
+}
+
+export type TransportResult = { status: number; body: unknown }
+
+export type Sender = (status: number, body: unknown) => Promise<any> | any
+
+export interface PaginationMeta {
+	page: number
+	limit: number
+	total: number
+	totalPages: number
+	hasNext?: boolean
+	hasPrev?: boolean
+	offset?: number
+	links?: {
+		next?: string
+		prev?: string
+		self: string
+	}
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+// Core Responders
+export { BaseResponder } from './core/BaseResponder'
+export { createResponderFactory } from './core/factory'
+export * from './core/types'
+export * from './core/config'
+
+// Adapters (Express)
+export { ExpressResponder } from './adapters/express/ExpressResponder'
+export { responderMiddleware } from './middleware/express/expressMiddleware'
+
+// HTTP Status Constants
+export { HTTP_STATUS } from './constants/httpStatus'
+export type { HttpStatusCode } from './constants/httpStatus'

package/src/middleware/express/expressMiddleware.ts

@@ -0,0 +1,14 @@
+import type { RequestHandler } from 'express'
+import type { ResponderConfig } from '../../core/config'
+import { createResponderFactory } from '../../core/factory'
+
+export const responderMiddleware = (
+	cfg?: Partial<ResponderConfig>,
+): RequestHandler => {
+	const factory = createResponderFactory(cfg)
+
+	return (_req, res, next) => {
+		;(res as any).responder = <P = unknown>() => factory<P>(res)
+		next()
+	}
+}

package/tsconfig.base.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true
+  },
+  "include": ["src/**/*"]
+}

package/tsconfig.cjs.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "module": "CommonJS",
+    "moduleResolution": "Node",
+    "rootDir": "./src",
+    "outDir": "./dist/cjs"
+  }
+}

package/tsconfig.esm.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "rootDir": "./src",
+    "outDir": "./dist/esm"
+  }
+}