refactor: Improve env validation, build, and logging (#405)

* refactor: Update package.json scripts and improve environment variable validation

* fix: Update pnpm-lock.yaml to specify exact versions for pino-pretty and typescript

Author: edwinhern

package.json

@@ -9,10 +9,9 @@
 	"private": true,
 	"scripts": {
 		"build": "tsc && tsup",
-		"start:dev": "tsx watch --clear-screen=false src/index.ts | pino-pretty",
+		"start:dev": "node --import=tsx --watch src/index.ts",
 		"start:prod": "node dist/index.js",
-		"lint": "biome lint",
-		"lint:fix": "biome lint --fix",
+		"lint": "biome lint --fix",
 		"format": "biome format --write",
 		"test": "vitest run",
 		"test:cov": "vitest run --coverage",
@@ -22,7 +21,6 @@
 		"@asteasolutions/zod-to-openapi": "7.3.0",
 		"cors": "2.8.5",
 		"dotenv": "16.5.0",
-		"envalid": "8.0.0",
 		"express": "5.1.0",
 		"express-rate-limit": "7.5.0",
 		"helmet": "8.1.0",
@@ -48,10 +46,15 @@
 		"vitest": "3.1.2"
 	},
 	"tsup": {
-		"entry": ["src", "!src/**/__tests__/**", "!src/**/*.test.*"],
-		"splitting": false,
+		"entry": ["src/index.ts"],
+		"outDir": "dist",
+		"format": ["esm", "cjs"],
+		"target": "es2020",
 		"sourcemap": true,
-		"clean": true
+		"clean": true,
+		"dts": true,
+		"splitting": false,
+		"skipNodeModulesBundle": true
 	},
 	"packageManager": "[email protected]"
 }

pnpm-lock.yaml

@@ -3,7 +3,9 @@ import { OpenAPIRegistry, OpenApiGeneratorV3 } from "@asteasolutions/zod-to-open
 import { healthCheckRegistry } from "@/api/healthCheck/healthCheckRouter";
 import { userRegistry } from "@/api/user/userRouter";
 
-export function generateOpenAPIDocument() {
+export type OpenAPIDocument = ReturnType<OpenApiGeneratorV3["generateDocument"]>;
+
+export function generateOpenAPIDocument(): OpenAPIDocument {
 	const registry = new OpenAPIRegistry([healthCheckRegistry, userRegistry]);
 	const generator = new OpenApiGeneratorV3(registry.definitions);
 

src/api-docs/openAPIDocumentGenerator.ts

@@ -10,4 +10,4 @@ const addErrorToRequestLog: ErrorRequestHandler = (err, _req, res, next) => {
 	next(err);
 };
 
-export default () => [unexpectedRequest, addErrorToRequestLog];
+export default (): [RequestHandler, ErrorRequestHandler] => [unexpectedRequest, addErrorToRequestLog];

src/common/middleware/errorHandler.ts

@@ -1,90 +1,58 @@
 import { randomUUID } from "node:crypto";
-import type { IncomingMessage, ServerResponse } from "node:http";
-import type { Request, RequestHandler, Response } from "express";
-import { StatusCodes, getReasonPhrase } from "http-status-codes";
-import type { LevelWithSilent } from "pino";
-import { type CustomAttributeKeys, type Options, pinoHttp } from "pino-http";
+import type { NextFunction, Request, Response } from "express";
+import { StatusCodes } from "http-status-codes";
+import pino from "pino";
+import pinoHttp from "pino-http";
 
 import { env } from "@/common/utils/envConfig";
 
-enum LogLevel {
-	Fatal = "fatal",
-	Error = "error",
-	Warn = "warn",
-	Info = "info",
-	Debug = "debug",
-	Trace = "trace",
-	Silent = "silent",
-}
+const logger = pino({
+	level: env.isProduction ? "info" : "debug",
+	transport: env.isProduction ? undefined : { target: "pino-pretty" },
+});
 
-type PinoCustomProps = {
-	request: Request;
-	response: Response;
-	error: Error;
-	responseBody: unknown;
+const getLogLevel = (status: number) => {
+	if (status >= StatusCodes.INTERNAL_SERVER_ERROR) return "error";
+	if (status >= StatusCodes.BAD_REQUEST) return "warn";
+	return "info";
 };
 
-const requestLogger = (options?: Options): RequestHandler[] => {
-	const pinoOptions: Options = {
-		enabled: env.isProduction,
-		customProps: customProps as unknown as Options["customProps"],
-		redact: [],
-		genReqId,
-		customLogLevel,
-		customSuccessMessage,
-		customReceivedMessage: (req) => `request received: ${req.method}`,
-		customErrorMessage: (_req, res) => `request errored with status code: ${res.statusCode}`,
-		customAttributeKeys,
-		...options,
-	};
-	return [responseBodyMiddleware, pinoHttp(pinoOptions)];
-};
+const addRequestId = (req: Request, res: Response, next: NextFunction) => {
+	const existingId = req.headers["x-request-id"] as string;
+	const requestId = existingId || randomUUID();
+
+	// Set for downstream use
+	req.headers["x-request-id"] = requestId;
+	res.setHeader("X-Request-Id", requestId);
 
-const customAttributeKeys: CustomAttributeKeys = {
-	req: "request",
-	res: "response",
-	err: "error",
-	responseTime: "timeTaken",
+	next();
 };
 
-const customProps = (req: Request, res: Response): PinoCustomProps => ({
-	request: req,
-	response: res,
-	error: res.locals.err,
-	responseBody: res.locals.responseBody,
+const httpLogger = pinoHttp({
+	logger,
+	genReqId: (req) => req.headers["x-request-id"] as string,
+	customLogLevel: (_req, res) => getLogLevel(res.statusCode),
+	customSuccessMessage: (req) => `${req.method} ${req.url} completed`,
+	customErrorMessage: (_req, res) => `Request failed with status code: ${res.statusCode}`,
+	// Only log response bodies in development
+	serializers: {
+		req: (req) => ({
+			method: req.method,
+			url: req.url,
+			id: req.id,
+		}),
+	},
 });
 
-const responseBodyMiddleware: RequestHandler = (_req, res, next) => {
-	const isNotProduction = !env.isProduction;
-	if (isNotProduction) {
+const captureResponseBody = (req: Request, res: Response, next: NextFunction) => {
+	if (!env.isProduction) {
 		const originalSend = res.send;
-		res.send = (content) => {
-			res.locals.responseBody = content;
-			res.send = originalSend;
-			return originalSend.call(res, content);
+		res.send = function (body) {
+			res.locals.responseBody = body;
+			return originalSend.call(this, body);
 		};
 	}
 	next();
 };
 
-const customLogLevel = (_req: IncomingMessage, res: ServerResponse<IncomingMessage>, err?: Error): LevelWithSilent => {
-	if (err || res.statusCode >= StatusCodes.INTERNAL_SERVER_ERROR) return LogLevel.Error;
-	if (res.statusCode >= StatusCodes.BAD_REQUEST) return LogLevel.Warn;
-	if (res.statusCode >= StatusCodes.MULTIPLE_CHOICES) return LogLevel.Silent;
-	return LogLevel.Info;
-};
-
-const customSuccessMessage = (req: IncomingMessage, res: ServerResponse<IncomingMessage>) => {
-	if (res.statusCode === StatusCodes.NOT_FOUND) return getReasonPhrase(StatusCodes.NOT_FOUND);
-	return `${req.method} completed`;
-};
-
-const genReqId = (req: IncomingMessage, res: ServerResponse<IncomingMessage>) => {
-	const existingID = req.id ?? req.headers["x-request-id"];
-	if (existingID) return existingID;
-	const id = randomUUID();
-	res.setHeader("X-Request-Id", id);
-	return id;
-};
-
-export default requestLogger();
+export default [addRequestId, captureResponseBody, httpLogger];

src/common/middleware/requestLogger.ts

@@ -1,13 +1,32 @@
 import dotenv from "dotenv";
-import { cleanEnv, host, num, port, str, testOnly } from "envalid";
+import { z } from "zod";
 
 dotenv.config();
 
-export const env = cleanEnv(process.env, {
-	NODE_ENV: str({ devDefault: testOnly("test"), choices: ["development", "production", "test"] }),
-	HOST: host({ devDefault: testOnly("localhost") }),
-	PORT: port({ devDefault: testOnly(3000) }),
-	CORS_ORIGIN: str({ devDefault: testOnly("http://localhost:3000") }),
-	COMMON_RATE_LIMIT_MAX_REQUESTS: num({ devDefault: testOnly(1000) }),
-	COMMON_RATE_LIMIT_WINDOW_MS: num({ devDefault: testOnly(1000) }),
+const envSchema = z.object({
+	NODE_ENV: z.enum(["development", "production", "test"]).default("production"),
+
+	HOST: z.string().min(1).default("localhost"),
+
+	PORT: z.coerce.number().int().positive().default(8080),
+
+	CORS_ORIGIN: z.string().url().default("http://localhost:8080"),
+
+	COMMON_RATE_LIMIT_MAX_REQUESTS: z.coerce.number().int().positive().default(1000),
+
+	COMMON_RATE_LIMIT_WINDOW_MS: z.coerce.number().int().positive().default(1000),
 });
+
+const parsedEnv = envSchema.safeParse(process.env);
+
+if (!parsedEnv.success) {
+	console.error("❌ Invalid environment variables:", parsedEnv.error.format());
+	throw new Error("Invalid environment variables");
+}
+
+export const env = {
+	...parsedEnv.data,
+	isDevelopment: parsedEnv.data.NODE_ENV === "development",
+	isProduction: parsedEnv.data.NODE_ENV === "production",
+	isTest: parsedEnv.data.NODE_ENV === "test",
+};

src/common/utils/envConfig.ts

@@ -4,9 +4,9 @@ import type { ZodError, ZodSchema } from "zod";
 
 import { ServiceResponse } from "@/common/models/serviceResponse";
 
-export const validateRequest = (schema: ZodSchema) => (req: Request, res: Response, next: NextFunction) => {
+export const validateRequest = (schema: ZodSchema) => async (req: Request, res: Response, next: NextFunction) => {
 	try {
-		schema.parse({ body: req.body, query: req.query, params: req.params });
+		await schema.parseAsync({ body: req.body, query: req.query, params: req.params });
 		next();
 	} catch (err) {
 		const errorMessage = `Invalid input: ${(err as ZodError).errors.map((e) => e.message).join(", ")}`;

src/common/utils/httpHandlers.ts

@@ -1,10 +1,10 @@
 {
 	"compilerOptions": {
 		"target": "ESNext",
-		"module": "CommonJS",
-		"baseUrl": ".",
+		"module": "ESNext",
+		"baseUrl": "./src",
 		"paths": {
-			"@/*": ["src/*"]
+			"@/*": ["*"]
 		},
 		"moduleResolution": "Node",
 		"outDir": "dist",