@akash-electron/ts-backend 1.0.0

package/README.md

@@ -0,0 +1,175 @@
+## 📦 Installation
+
+```bash
+npm install @akash-electron/ts-backend
+```
+
+## 🚀 Usage
+
+This package provides a set of utilities and middlewares to build robust TypeScript backends.
+
+### Global Error Handling
+
+```typescript
+import express from "express";
+import { globalErrorHandler, AppError, catchAsync } from "backlinks_backend";
+
+const app = express();
+
+// Your routes
+app.get(
+  "/example",
+  catchAsync(async (req, res) => {
+    if (!req.query.id) {
+      throw new AppError("ID is required", 400);
+    }
+    res.json({ id: req.query.id });
+  }),
+);
+
+// Use the global error handler at the end
+app.use(globalErrorHandler);
+```
+
+---
+
+## 📂 Folder Structure (Inherited)
+
+```text
+src/
+├── config/             # Configuration files (env vars, database, etc.)
+├── controllers/        # Request handlers (processes input/output)
+├── middlewares/        # Custom Express middlewares (error, auth, validation)
+├── models/             # Data models/schemas (Prisma/Mongoose)
+├── routes/             # API route definitions
+├── services/           # Business logic (kept separate from controllers)
+├── utils/              # Helper functions and utility classes
+├── validations/        # Request validation schemas (Zod)
+├── types/              # Global TypeScript interfaces & types
+├── app.ts              # Express application configuration
+└── server.ts           # Entry point and server initialization
+```
+
+---
+
+## 🛠️ Key Components & Implementation
+
+### 1. Global Error Handling
+
+We use a centralized error handling mechanism to ensure consistent error responses across the entire application.
+
+- **`AppError` Class**: A custom error class to handle operational errors.
+- **`catchAsync` Utility**: A wrapper to eliminate the need for `try-catch` blocks in controllers.
+- **Global Error Middleware**: The final destination for all errors.
+
+### 2. Request Validation
+
+Using **Zod** for schema validation ensures that only valid data reaches your business logic. We validate:
+
+- Request Body
+- Query Parameters
+- URL Parameters
+
+### 3. Business Logic (Services)
+
+Controllers should only handle requests and responses. All "heavy lifting" and business rules are encapsulated in **Services**, making the code testable and reusable.
+
+### 4. Consistent API Responses
+
+All successful responses follow a standard format:
+
+```json
+{
+  "status": "success",
+  "data": { ... }
+}
+```
+
+---
+
+## 🚀 Getting Started
+
+### Prerequisites
+
+- Node.js (v18+)
+- npm or pnpm
+
+### Initial Setup
+
+1. **Initialize Project**
+
+   ```bash
+   npm init -y
+   npm install typescript ts-node nodemon @types/node @types/express express dotenv
+   npx tsc --init
+   ```
+
+2. **Install Essentials**
+   ```bash
+   npm install zod cors helmet morgan winston
+   npm install -D @types/cors @types/morgan
+   ```
+
+---
+
+## 🛡️ Important Files (Quick Reference)
+
+### `src/utils/AppError.ts`
+
+```typescript
+export class AppError extends Error {
+  public readonly statusCode: number;
+  public readonly isOperational: boolean;
+
+  constructor(message: string, statusCode: number) {
+    super(message);
+    this.statusCode = statusCode;
+    this.isOperational = true;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+```
+
+### `src/middlewares/errorMiddleware.ts`
+
+```typescript
+import { Request, Response, NextFunction } from "express";
+import { AppError } from "../utils/AppError";
+
+export const globalErrorHandler = (
+  err: any,
+  req: Request,
+  res: Response,
+  next: NextFunction,
+) => {
+  err.statusCode = err.statusCode || 500;
+  err.status = err.status || "error";
+
+  res.status(err.statusCode).json({
+    status: err.status,
+    message: err.message,
+    ...(process.env.NODE_ENV === "development" && { stack: err.stack }),
+  });
+};
+```
+
+### `src/utils/catchAsync.ts`
+
+```typescript
+import { Request, Response, NextFunction } from "express";
+
+export const catchAsync = (fn: Function) => {
+  return (req: Request, res: Response, next: NextFunction) => {
+    fn(req, res, next).catch(next);
+  };
+};
+```
+
+---
+
+## 📝 Best Practices Included
+
+- **Environment Safety**: Validate `.env` variables at startup.
+- **Security Check**: Pre-configured with `helmet` for secure headers.
+- **Clean Code**: Deep separation of concerns (Routes → Controllers → Services).
+- **Graceful Shutdown**: Handles `SIGTERM` and `SIGINT` signals to close DB connections properly.

package/dist/app.d.ts

@@ -0,0 +1,2 @@
+declare const app: import("@types/express-serve-static-core").Express;
+export default app;

package/dist/app.js

@@ -0,0 +1,35 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const cors_1 = __importDefault(require("cors"));
+const express_1 = __importDefault(require("express"));
+const helmet_1 = __importDefault(require("helmet"));
+const morgan_1 = __importDefault(require("morgan"));
+const errorMiddleware_1 = require("./middlewares/errorMiddleware");
+const AppError_1 = require("./utils/AppError");
+const app = (0, express_1.default)();
+// Security HTTP headers
+app.use((0, helmet_1.default)());
+// Development logging
+if (process.env.NODE_ENV === "development") {
+    app.use((0, morgan_1.default)("dev"));
+}
+// Body parser
+app.use(express_1.default.json({ limit: "10kb" }));
+// CORS
+app.use((0, cors_1.default)());
+// Routes
+// app.use('/api/v1/users', userRouter);
+// Health check
+app.get("/health", (req, res) => {
+    res.status(200).json({ status: "ok" });
+});
+// Handle undefined routes
+app.all("*", (req, res, next) => {
+    next(new AppError_1.AppError(`Can't find ${req.originalUrl} on this server!`, 404));
+});
+// Global error handling middleware
+app.use(errorMiddleware_1.globalErrorHandler);
+exports.default = app;

package/dist/config/env.d.ts

@@ -0,0 +1,5 @@
+export declare const env: {
+    NODE_ENV: "development" | "test" | "production";
+    PORT: number;
+    DATABASE_URL?: string | undefined;
+};

package/dist/config/env.js

@@ -0,0 +1,22 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.env = void 0;
+const dotenv_1 = __importDefault(require("dotenv"));
+const zod_1 = require("zod");
+dotenv_1.default.config();
+const envSchema = zod_1.z.object({
+    NODE_ENV: zod_1.z
+        .enum(["development", "test", "production"])
+        .default("development"),
+    PORT: zod_1.z.coerce.number().default(5000),
+    DATABASE_URL: zod_1.z.string().optional(),
+});
+const envVars = envSchema.safeParse(process.env);
+if (!envVars.success) {
+    console.error("❌ Invalid environment variables:", envVars.error.format());
+    process.exit(1);
+}
+exports.env = envVars.data;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./config/env";
+export * from "./middlewares/errorMiddleware";
+export * from "./utils/AppError";
+export * from "./utils/catchAsync";

package/dist/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./config/env"), exports);
+__exportStar(require("./middlewares/errorMiddleware"), exports);
+__exportStar(require("./utils/AppError"), exports);
+__exportStar(require("./utils/catchAsync"), exports);

package/dist/middlewares/errorMiddleware.d.ts

@@ -0,0 +1,2 @@
+import { NextFunction, Request, Response } from "express";
+export declare const globalErrorHandler: (err: any, req: Request, res: Response, next: NextFunction) => void;

package/dist/middlewares/errorMiddleware.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.globalErrorHandler = void 0;
+const globalErrorHandler = (err, req, res, next) => {
+    err.statusCode = err.statusCode || 500;
+    err.status = err.status || "error";
+    if (process.env.NODE_ENV === "development") {
+        res.status(err.statusCode).json({
+            status: err.status,
+            error: err,
+            message: err.message,
+            stack: err.stack,
+        });
+    }
+    else {
+        if (err.isOperational) {
+            res.status(err.statusCode).json({
+                status: err.status,
+                message: err.message,
+            });
+        }
+        else {
+            console.error("ERROR 💥", err);
+            res.status(500).json({
+                status: "error",
+                message: "Something went very wrong!",
+            });
+        }
+    }
+};
+exports.globalErrorHandler = globalErrorHandler;

package/dist/server.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server.js

@@ -0,0 +1,25 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const app_1 = __importDefault(require("./app"));
+const env_1 = require("./config/env");
+const port = env_1.env.PORT || 5000;
+const server = app_1.default.listen(port, () => {
+    console.log(`🚀 Server running in ${env_1.env.NODE_ENV} mode on port ${port}`);
+});
+// Handle unhandled rejections
+process.on("unhandledRejection", (err) => {
+    console.log("UNHANDLED REJECTION! 💥 Shutting down...");
+    console.log(err.name, err.message);
+    server.close(() => {
+        process.exit(1);
+    });
+});
+// Handle uncaught exceptions
+process.on("uncaughtException", (err) => {
+    console.log("UNCAUGHT EXCEPTION! 💥 Shutting down...");
+    console.log(err.name, err.message);
+    process.exit(1);
+});

package/dist/utils/AppError.d.ts

@@ -0,0 +1,6 @@
+export declare class AppError extends Error {
+    readonly statusCode: number;
+    readonly status: string;
+    readonly isOperational: boolean;
+    constructor(message: string, statusCode: number);
+}

package/dist/utils/AppError.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppError = void 0;
+class AppError extends Error {
+    constructor(message, statusCode) {
+        super(message);
+        this.statusCode = statusCode;
+        this.status = `${statusCode}`.startsWith("4") ? "fail" : "error";
+        this.isOperational = true;
+        Error.captureStackTrace(this, this.constructor);
+    }
+}
+exports.AppError = AppError;

package/dist/utils/catchAsync.d.ts

@@ -0,0 +1,2 @@
+import { NextFunction, Request, Response } from "express";
+export declare const catchAsync: (fn: Function) => (req: Request, res: Response, next: NextFunction) => void;

package/dist/utils/catchAsync.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.catchAsync = void 0;
+const catchAsync = (fn) => {
+    return (req, res, next) => {
+        fn(req, res, next).catch(next);
+    };
+};
+exports.catchAsync = catchAsync;

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@akash-electron/ts-backend",
+  "version": "1.0.0",
+  "description": "A robust, scalable, and production-ready starter template for building Node.js backends with TypeScript. This boilerplate follows industry best practices for architecture, error handling, and type safety.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "nodemon --exec ts-node src/server.ts",
+    "build": "tsc",
+    "start": "node dist/server.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.6",
+    "@types/morgan": "^1.9.10",
+    "@types/node": "^25.2.2",
+    "cors": "^2.8.6",
+    "dotenv": "^17.2.4",
+    "express": "^5.2.1",
+    "helmet": "^8.1.0",
+    "morgan": "^1.10.1",
+    "nodemon": "^3.1.11",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3",
+    "winston": "^3.19.0",
+    "zod": "^4.3.6"
+  }
+}