ts-packages 1.0.0 → 3.0.0

package/packages/response-utils/dist/types/core/config.d.ts

@@ -0,0 +1,15 @@
+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 declare const defaultConfig: ResponderConfig;

package/packages/response-utils/dist/types/core/factory.d.ts

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

package/packages/response-utils/dist/types/core/types.d.ts

@@ -0,0 +1,32 @@
+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/packages/response-utils/dist/types/index.d.ts

@@ -0,0 +1,8 @@
+export { BaseResponder } from './core/BaseResponder';
+export { createResponderFactory } from './core/factory';
+export * from './core/types';
+export * from './core/config';
+export { ExpressResponder } from './adapters/express/ExpressResponder';
+export { responderMiddleware } from './middleware/express/expressMiddleware';
+export { HTTP_STATUS } from './constants/httpStatus';
+export type { HttpStatusCode } from './constants/httpStatus';

package/packages/response-utils/dist/types/legacy.d.ts

@@ -0,0 +1,19 @@
+export declare const success: <T>(data: T, message?: string, status?: number, res?: {
+    status: (code: number) => any;
+    json: (body: unknown) => any;
+}) => any;
+export declare const error: (message: string, status?: number, err?: string, res?: {
+    status: (code: number) => any;
+    json: (body: unknown) => any;
+}) => any;
+declare const _default: {
+    success: <T>(data: T, message?: string, status?: number, res?: {
+        status: (code: number) => any;
+        json: (body: unknown) => any;
+    }) => any;
+    error: (message: string, status?: number, err?: string, res?: {
+        status: (code: number) => any;
+        json: (body: unknown) => any;
+    }) => any;
+};
+export default _default;

package/packages/response-utils/dist/types/middleware/express/expressMiddleware.d.ts

@@ -0,0 +1,3 @@
+import type { RequestHandler } from 'express';
+import type { ResponderConfig } from '../../core/config';
+export declare const responderMiddleware: (cfg?: Partial<ResponderConfig>) => RequestHandler;

package/packages/response-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/response-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/response-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/response-utils/package.json

@@ -1,22 +1,50 @@
 {
   "name": "@naman_deep_singh/response-utils",
-  "version": "1.0.7",
-  "description": "TypeScript utilities for standardized HTTP API responses with common status codes and error handling",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "version": "2.1.4",
+  "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,
   "scripts": {
-    "build": "tsc"
+    "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"
   },
   "keywords": [
     "response",
     "http",
     "api",
-    "utils"
+    "utils",
+    "express",
+    "typescript"
   ],
-  "author": "Naman Deep Singh",
-  "license": "ISC",
-  "packageManager": "pnpm@10.20.0",
+  "peerDependencies": {
+    "express": "^5.1.0"
+  },
   "devDependencies": {
-    "typescript": "^5.9.3"
+    "@types/express": "^5.0.5",
+    "express": "^5.1.0",
+    "typescript": "^5.9.3",
+    "rimraf": "^5.0.5"
   }
 }

package/packages/response-utils/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/packages/response-utils/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/packages/response-utils/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/packages/response-utils/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/packages/response-utils/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/packages/response-utils/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
+	}
+}