backend-starter-kit 1.0.5

package/template/package.json

@@ -0,0 +1,67 @@
+{
+    "name": "backend",
+    "version": "0.1.0",
+    "description": "Production-ready backend using Bun",
+    "type": "module",
+    "private": true,
+    "license": "MIT",
+    "author": {
+        "name": "Harshit Ostwal",
+        "email": "harshitostwal1234@gmail.com",
+        "url": "https://harshitostwal.com"
+    },
+    "contributors": [
+        {
+            "name": "Harshit Ostwal",
+            "email": "harshitostwal1234@gmail.com",
+            "url": "https://harshitostwal.com"
+        }
+    ],
+    "main": "src/index.js",
+    "module": "src/index.js",
+    "scripts": {
+        "dev": "bun --hot src/index.js",
+        "start": "bun src/index.js",
+        "biome:format": "bunx biome format --write",
+        "biome:lint": "bunx biome lint --write",
+        "biome:check": "bunx biome check --write",
+        "biome:clean": "bunx biome clean",
+        "prisma:generate": "prisma generate",
+        "prisma:migrate": "prisma migrate dev --name",
+        "prisma:migrate:deploy": "prisma migrate deploy",
+        "prisma:migrate:reset": "prisma migrate reset",
+        "prisma:migrate:status": "prisma migrate status",
+        "prisma:studio": "prisma studio",
+        "prisma:db:push": "prisma db push",
+        "prisma:db:pull": "prisma db pull",
+        "prepare": "husky"
+    },
+    "lint-staged": {
+        "*": [
+            "bunx biome check --write --no-errors-on-unmatched --files-ignore-unknown=true"
+        ]
+    },
+    "dependencies": {
+        "@prisma/adapter-pg": "^7.3.0",
+        "@prisma/client": "^7.3.0",
+        "cookie-parser": "^1.4.7",
+        "cors": "^2.8.6",
+        "dotenv": "^17.2.3",
+        "express": "^5.2.1",
+        "helmet": "^8.1.0",
+        "jsonwebtoken": "^9.0.3",
+        "morgan": "^1.10.1",
+        "pg": "^8.18.0",
+        "swagger-jsdoc": "^6.2.8",
+        "swagger-ui-express": "^5.0.1",
+        "uuid": "^13.0.0",
+        "winston": "^3.19.0",
+        "zod": "^4.3.6"
+    },
+    "devDependencies": {
+        "@biomejs/biome": "2.3.13",
+        "husky": "^9.1.7",
+        "lint-staged": "^16.2.7",
+        "prisma": "^7.3.0"
+    }
+}

package/template/prisma/schema.prisma

@@ -0,0 +1,8 @@
+generator client {
+  provider = "prisma-client-js"
+  output   = "../src/generated/prisma"
+}
+
+datasource db {
+  provider = "postgresql"
+}

package/template/prisma.config.js

@@ -0,0 +1,12 @@
+import { defineConfig } from "prisma/config";
+import { NODE_ENV } from "./src/config/env.config.js";
+
+export default defineConfig({
+    schema: "prisma/schema.prisma",
+    migrations: {
+        path: "prisma/migrations",
+    },
+    datasource: {
+        url: NODE_ENV,
+    },
+});

package/template/src/app.js

@@ -0,0 +1,45 @@
+import cookieParser from "cookie-parser";
+import cors from "cors";
+import express from "express";
+import helmet from "helmet";
+import morgan from "morgan";
+import { NODE_ENV } from "./config/env.config.js";
+import { API_VERSION, REQUEST_SIZE_LIMIT } from "./constants/api.constants.js";
+import { APP_NAME } from "./constants/app.constants.js";
+import { CORS_OPTIONS } from "./constants/security.constants.js";
+import errorHandler from "./core/middlewares/error.middleware.js";
+import notFound from "./core/middlewares/notFound.middleware.js";
+import { logger } from "./core/utils/logger.utils.js";
+import routes from "./routes/index.route.js";
+
+const app = express();
+
+app.set("title", `${APP_NAME} API Server (${API_VERSION})`);
+app.set("env", NODE_ENV || "development");
+
+app.set("trust proxy");
+app.set("json spaces", 2);
+
+app.use(
+  morgan(":method :url :status :res[content-length] - :response-time ms", {
+    stream: logger.stream,
+  }),
+);
+
+app.use(express.json({ limit: REQUEST_SIZE_LIMIT }));
+app.use(express.urlencoded({ extended: true, limit: REQUEST_SIZE_LIMIT }));
+app.use(express.static("public"));
+app.use(cookieParser());
+app.use(cors(CORS_OPTIONS));
+
+// Helmet for security headers
+// -- Disable contentSecurityPolicy for development to avoid issues with Swagger UI
+app.use(helmet({ contentSecurityPolicy: false }));
+
+// API routes
+app.use(`/api/${API_VERSION}`, routes);
+
+app.use(notFound);
+app.use(errorHandler);
+
+export { app };

package/template/src/config/cookie.config.js

@@ -0,0 +1,21 @@
+import { NODE_ENV } from "../config/env.config.js";
+
+const sharedCookieBase = {
+    httpOnly: true,
+    secure: NODE_ENV === "production",
+    sameSite:
+        NODE_ENV === "production" ? "none" : NODE_ENV === "testing" ? "" : "",
+    path: "/",
+};
+
+const cookieAccessOptions = {
+    ...sharedCookieBase,
+    maxAge: 15 * 60 * 1000, // 15 minutes
+};
+
+const cookieRefreshOptions = {
+    ...sharedCookieBase,
+    maxAge: 7 * 24 * 60 * 60 * 1000, // 7 days
+};
+
+export { cookieAccessOptions, cookieRefreshOptions };

package/template/src/config/env.config.js

@@ -0,0 +1,43 @@
+import { config } from "dotenv";
+
+config({
+    path: `.env.${process.env.NODE_ENV || "development"}`,
+    debug: process.env.NODE_ENV === "development",
+    encoding: "utf8",
+    override: false,
+    quiet: false,
+});
+
+export const {
+    NODE_ENV,
+    PORT,
+
+    // CORS
+    ALLOWED_ORIGINS,
+
+    // URL's
+    BACKEND_URL,
+    FRONTEND_URL,
+
+    // Database
+    DATABASE_URL,
+
+    // Redis
+    REDIS_HOST,
+    REDIS_PORT,
+    REDIS_PASSWORD,
+
+    // JWT
+    ACCESS_TOKEN_SECRET,
+    ACCESS_TOKEN_EXPIRY,
+    REFRESH_TOKEN_SECRET,
+    REFRESH_TOKEN_EXPIRY,
+
+    // Mail
+    SMPT_HOST,
+    SMPT_PORT,
+    SMPT_USER,
+    SMPT_PASSWORD,
+    SMPT_SECURE,
+    SMPT_SERVICE,
+} = process.env;

package/template/src/config/swagger.config.js

@@ -0,0 +1,62 @@
+import swaggerJsdoc from "swagger-jsdoc";
+import swaggerUi from "swagger-ui-express";
+import { API_VERSION } from "../constants/api.constants.js";
+import { APP_NAME } from "../constants/app.constants.js";
+import { BACKEND_URL } from "./env.config.js";
+
+const options = {
+    definition: {
+        openapi: "3.0.0",
+        info: {
+            contact: {
+                name: "API Support",
+                url: "https://www.example.com/support",
+                email: "support@example.com",
+            },
+            title: `${APP_NAME} API Documentation`,
+            version: "1.0.0",
+            description: `API documentation for the ${APP_NAME} application`,
+            license: {
+                name: "MIT",
+                url: "https://opensource.org/licenses/MIT",
+            },
+            termsOfService: "https://www.example.com/terms",
+        },
+        basePath: `/api/${API_VERSION}`,
+        consumes: ["application/json"],
+        produces: ["application/json"],
+        externalDocs: {
+            description: "Find out more",
+            url: "https://www.example.com/docs",
+        },
+        host: `${BACKEND_URL.replace(/^https?:\/\//, "")}`,
+        schemes: ["http", "https"],
+        tags: [{ name: "System", description: "System routes" }],
+        servers: [
+            {
+                url: `${BACKEND_URL}/api/${API_VERSION}`,
+                description: "Development server",
+            },
+        ],
+    },
+    apis: ["./src/routes/*.js"],
+};
+
+const theme = {
+    customFavIcon: "/favicon.ico",
+    customSiteTitle: `${APP_NAME} API`,
+    swaggerOptions: {
+        layout: "BaseLayout",
+        docExpansion: "none",
+        persistAuthorization: false,
+    },
+    customCss: `
+      .topbar { display: none !important; }
+      body { background: #ffffff !important; }
+      .swagger-ui { background: #ffffff !important; }
+    `,
+};
+
+const specs = swaggerJsdoc(options);
+
+export { swaggerUi, specs, theme };

package/template/src/constants/api.constants.js

@@ -0,0 +1,6 @@
+const API_VERSION = "v1";
+const API_PREFIX = `/api/${API_VERSION}`;
+
+const REQUEST_SIZE_LIMIT = "16kb";
+
+export { API_VERSION, API_PREFIX, REQUEST_SIZE_LIMIT };

package/template/src/constants/app.constants.js

@@ -0,0 +1,5 @@
+const APP_NAME = "Backend App";
+const APP = "backend-app";
+const DEVELOPER_NAME = "Harshit Ostwal";
+
+export { APP_NAME, APP, DEVELOPER_NAME };

package/template/src/constants/http.constants.js

@@ -0,0 +1,90 @@
+const HTTP_METHODS = {
+    GET: "GET",
+    POST: "POST",
+    PUT: "PUT",
+    PATCH: "PATCH",
+    DELETE: "DELETE",
+    OPTIONS: "OPTIONS",
+    HEAD: "HEAD",
+};
+
+const HTTP_STATUS = {
+    // Success
+    OK: 200,
+    CREATED: 201,
+    ACCEPTED: 202,
+    NO_CONTENT: 204,
+    PARTIAL_CONTENT: 206,
+
+    // Redirection (Optional but good to have)
+    MOVED_PERMANENTLY: 301,
+    FOUND: 302,
+    NOT_MODIFIED: 304,
+    TEMPORARY_REDIRECT: 307,
+    PERMANENT_REDIRECT: 308,
+
+    // Client Errors
+    BAD_REQUEST: 400,
+    UNAUTHORIZED: 401,
+    FORBIDDEN: 403,
+    NOT_FOUND: 404,
+    METHOD_NOT_ALLOWED: 405,
+    NOT_ACCEPTABLE: 406,
+    REQUEST_TIMEOUT: 408,
+    CONFLICT: 409,
+    GONE: 410,
+    PAYLOAD_TOO_LARGE: 413,
+    UNSUPPORTED_MEDIA_TYPE: 415,
+    UNPROCESSABLE_ENTITY: 422,
+    TOO_MANY_REQUESTS: 429,
+
+    // Server Errors
+    INTERNAL_SERVER_ERROR: 500,
+    NOT_IMPLEMENTED: 501,
+    BAD_GATEWAY: 502,
+    SERVICE_UNAVAILABLE: 503,
+    GATEWAY_TIMEOUT: 504,
+    HTTP_VERSION_NOT_SUPPORTED: 505,
+};
+
+const HTTP_MESSAGES = {
+    // Success
+    OK: "Success",
+    CREATED: "Resource created successfully",
+    ACCEPTED: "Request accepted",
+    NO_CONTENT: "No content",
+    PARTIAL_CONTENT: "Partial content",
+
+    // Redirection
+    MOVED_PERMANENTLY: "Moved permanently",
+    FOUND: "Found",
+    NOT_MODIFIED: "Not modified",
+    TEMPORARY_REDIRECT: "Temporary redirect",
+    PERMANENT_REDIRECT: "Permanent redirect",
+
+    // Client Errors
+    BAD_REQUEST: "Bad request",
+    UNAUTHORIZED: "Unauthorized",
+    FORBIDDEN: "Forbidden",
+    NOT_FOUND: "Resource not found",
+    METHOD_NOT_ALLOWED: "Method not allowed",
+    NOT_ACCEPTABLE: "Not acceptable",
+    REQUEST_TIMEOUT: "Request timeout",
+    CONFLICT: "Resource already exists",
+    GONE: "Resource no longer available",
+    PAYLOAD_TOO_LARGE: "Payload too large",
+    UNSUPPORTED_MEDIA_TYPE: "Unsupported media type",
+    UNPROCESSABLE_ENTITY: "Unprocessable entity",
+    VALIDATION_ERROR: "Validation error",
+    TOO_MANY_REQUESTS: "Too many requests",
+
+    // Server Errors
+    INTERNAL_SERVER_ERROR: "Internal server error",
+    NOT_IMPLEMENTED: "Not implemented",
+    BAD_GATEWAY: "Bad gateway",
+    SERVICE_UNAVAILABLE: "Service unavailable",
+    GATEWAY_TIMEOUT: "Gateway timeout",
+    HTTP_VERSION_NOT_SUPPORTED: "HTTP version not supported",
+};
+
+export { HTTP_METHODS, HTTP_STATUS, HTTP_MESSAGES };

package/template/src/constants/queue.constants.js

@@ -0,0 +1,5 @@
+import { APP } from "./api.constants.js";
+
+const MAIL_QUEUE_NAME = `${APP}-mail-queue`;
+
+export { MAIL_QUEUE_NAME };

package/template/src/constants/security.constants.js

@@ -0,0 +1,22 @@
+import { ALLOWED_ORIGINS } from "../config/env.config.js";
+
+const CORS_OPTIONS = {
+    origin: ALLOWED_ORIGINS?.split(",") || ["*"],
+    credentials: true,
+    methods: ["GET", "POST", "PATCH", "DELETE"],
+    allowedHeaders: ["Content-Type", "Authorization"],
+};
+
+const RATE_LIMIT = {
+    WINDOW_MS: 60 * 60 * 1000,
+    MAX_REQUESTS: 500,
+};
+
+const SALT_ROUNDS = 10;
+
+const TOKEN_TYPE = {
+    ACCESS: "access",
+    REFRESH: "refresh",
+};
+
+export { CORS_OPTIONS, RATE_LIMIT, SALT_ROUNDS, TOKEN_TYPE };

package/template/src/constants/validation.constants.js

@@ -0,0 +1,8 @@
+const ValidationSource = {
+    BODY: "body",
+    QUERY: "query",
+    HEADER: "header",
+    PARAMS: "params",
+};
+
+export { ValidationSource };

package/template/src/core/http/api.error.js

@@ -0,0 +1,162 @@
+import { HTTP_MESSAGES, HTTP_STATUS } from "../../constants/http.constants.js";
+
+class ApiError extends Error {
+    constructor(
+        statusCode = HTTP_STATUS.INTERNAL_SERVER_ERROR,
+        message = HTTP_MESSAGES.INTERNAL_SERVER_ERROR,
+        errors = [],
+        isOperational = true,
+        options = {}
+    ) {
+        const { cause, code, stack } = options ?? {};
+
+        super(message, cause ? { cause } : undefined);
+
+        Object.setPrototypeOf(this, new.target.prototype);
+
+        this.name = "ApiError";
+        this.statusCode = statusCode;
+        this.success = false;
+        this.errors = Array.isArray(errors) ? errors : [];
+        this.isOperational = isOperational;
+
+        if (code !== undefined) this.code = code;
+        if (cause !== undefined) this.cause = cause;
+
+        if (stack) {
+            this.stack = stack;
+        } else if (typeof Error.captureStackTrace === "function") {
+            Error.captureStackTrace(this, this.constructor);
+        } else {
+            this.stack = new Error(message).stack ?? "";
+        }
+    }
+
+    static from(error, statusCode = HTTP_STATUS.INTERNAL_SERVER_ERROR) {
+        if (!error) return new ApiError(statusCode);
+        if (error instanceof ApiError) return error;
+
+        const message = error instanceof Error ? error.message : String(error);
+
+        return new ApiError(statusCode, message, error.errors ?? [], false, {
+            cause: error,
+            code: error instanceof Error ? error.code : undefined,
+        });
+    }
+
+    // 400
+    static badRequest(message = HTTP_MESSAGES.BAD_REQUEST, errors = []) {
+        return new ApiError(HTTP_STATUS.BAD_REQUEST, message, errors);
+    }
+
+    // 401
+    static unauthorized(message = HTTP_MESSAGES.UNAUTHORIZED, errors = []) {
+        return new ApiError(HTTP_STATUS.UNAUTHORIZED, message, errors);
+    }
+
+    // 403
+    static forbidden(message = HTTP_MESSAGES.FORBIDDEN, errors = []) {
+        return new ApiError(HTTP_STATUS.FORBIDDEN, message, errors);
+    }
+
+    // 404
+    static notFound(message = HTTP_MESSAGES.NOT_FOUND, errors = []) {
+        return new ApiError(HTTP_STATUS.NOT_FOUND, message, errors);
+    }
+
+    // 409
+    static conflict(message = HTTP_MESSAGES.CONFLICT, errors = []) {
+        return new ApiError(HTTP_STATUS.CONFLICT, message, errors);
+    }
+
+    // 410
+    static gone(message = HTTP_MESSAGES.GONE ?? "Gone", errors = []) {
+        return new ApiError(HTTP_STATUS.GONE ?? 410, message, errors);
+    }
+
+    // 422
+    static validationError(
+        message = HTTP_MESSAGES.VALIDATION_ERROR,
+        errors = []
+    ) {
+        return new ApiError(HTTP_STATUS.UNPROCESSABLE_ENTITY, message, errors);
+    }
+
+    // 429
+    static tooManyRequests(
+        message = HTTP_MESSAGES.TOO_MANY_REQUESTS,
+        errors = []
+    ) {
+        return new ApiError(HTTP_STATUS.TOO_MANY_REQUESTS, message, errors);
+    }
+
+    // 500
+    static internalServerError(
+        message = HTTP_MESSAGES.INTERNAL_SERVER_ERROR,
+        errors = []
+    ) {
+        return new ApiError(HTTP_STATUS.INTERNAL_SERVER_ERROR, message, errors);
+    }
+
+    // 501
+    static notImplemented(
+        message = HTTP_MESSAGES.NOT_IMPLEMENTED,
+        errors = []
+    ) {
+        return new ApiError(HTTP_STATUS.NOT_IMPLEMENTED, message, errors);
+    }
+
+    // 502
+    static badGateway(message = HTTP_MESSAGES.BAD_GATEWAY, errors = []) {
+        return new ApiError(HTTP_STATUS.BAD_GATEWAY, message, errors);
+    }
+
+    // 503
+    static serviceUnavailable(
+        message = HTTP_MESSAGES.SERVICE_UNAVAILABLE,
+        errors = []
+    ) {
+        return new ApiError(HTTP_STATUS.SERVICE_UNAVAILABLE, message, errors);
+    }
+
+    // 504
+    static gatewayTimeout(
+        message = HTTP_MESSAGES.GATEWAY_TIMEOUT,
+        errors = []
+    ) {
+        return new ApiError(HTTP_STATUS.GATEWAY_TIMEOUT, message, errors);
+    }
+
+    toJSON() {
+        return {
+            name: this.name,
+            success: false,
+            statusCode: this.statusCode,
+            message: this.message,
+            errors: this.errors,
+            ...(this.code !== undefined && { code: this.code }),
+        };
+    }
+
+    toDebugJSON() {
+        return {
+            ...this.toJSON(),
+            isOperational: this.isOperational,
+            stack: this.stack,
+            cause:
+                this.cause instanceof Error
+                    ? { message: this.cause.message, stack: this.cause.stack }
+                    : this.cause,
+        };
+    }
+
+    isClientError() {
+        return this.statusCode >= 400 && this.statusCode < 500;
+    }
+
+    isServerError() {
+        return this.statusCode >= 500;
+    }
+}
+
+export default ApiError;

package/template/src/core/http/api.response.js

@@ -0,0 +1,118 @@
+import { HTTP_MESSAGES, HTTP_STATUS } from "../../constants/http.constants.js";
+
+class ApiResponse {
+    constructor(
+        statusCode = HTTP_STATUS.OK,
+        data = null,
+        message = HTTP_MESSAGES.OK ?? "Success",
+        meta
+    ) {
+        if (
+            !Number.isInteger(statusCode) ||
+            statusCode < 100 ||
+            statusCode > 599
+        ) {
+            throw new TypeError(`Invalid HTTP status code: ${statusCode}`);
+        }
+
+        this.success = statusCode < 400;
+        this.statusCode = statusCode;
+        this.message =
+            typeof message === "string" && message.trim()
+                ? message.trim()
+                : "Success";
+        this.data = data !== undefined ? data : null;
+        this.timestamp = new Date().toISOString();
+
+        if (
+            meta !== null &&
+            meta !== undefined &&
+            typeof meta === "object" &&
+            !Array.isArray(meta)
+        ) {
+            this.meta = meta;
+        }
+    }
+
+    static ok(data, message = HTTP_MESSAGES.OK ?? "OK") {
+        return new ApiResponse(HTTP_STATUS.OK, data, message);
+    }
+
+    static created(data, message = HTTP_MESSAGES.CREATED ?? "Created") {
+        return new ApiResponse(HTTP_STATUS.CREATED, data, message);
+    }
+
+    static accepted(data, message = HTTP_MESSAGES.ACCEPTED ?? "Accepted") {
+        return new ApiResponse(HTTP_STATUS.ACCEPTED, data, message);
+    }
+
+    static noContent() {
+        return new ApiResponse(HTTP_STATUS.NO_CONTENT, null, null);
+    }
+
+    static paginated(
+        items,
+        { page, limit, total },
+        message = HTTP_MESSAGES.OK ?? "OK"
+    ) {
+        if (!Number.isInteger(limit) || limit < 1)
+            throw new TypeError(
+                `Pagination "limit" must be a positive integer, got: ${limit}`
+            );
+        if (!Number.isInteger(page) || page < 1)
+            throw new TypeError(
+                `Pagination "page" must be a positive integer, got: ${page}`
+            );
+        if (!Number.isInteger(total) || total < 0)
+            throw new TypeError(
+                `Pagination "total" must be a non-negative integer, got: ${total}`
+            );
+
+        const totalPages = total === 0 ? 0 : Math.ceil(total / limit);
+        const meta = {
+            page,
+            limit,
+            total,
+            totalPages,
+            hasNext: page < totalPages,
+            hasPrev: page > 1,
+        };
+
+        return new ApiResponse(HTTP_STATUS.OK, items, message, meta);
+    }
+
+    toJSON() {
+        return {
+            success: this.success,
+            statusCode: this.statusCode,
+            message: this.message,
+            data: this.data,
+            ...(this.meta !== undefined && { meta: this.meta }),
+            timestamp: this.timestamp,
+        };
+    }
+
+    send(res) {
+        if (this.statusCode === HTTP_STATUS.NO_CONTENT) {
+            return res.status(this.statusCode).end();
+        }
+
+        return res.status(this.statusCode).json(this.toJSON());
+    }
+
+    static redirect(res, url, statusCode = HTTP_STATUS.FOUND) {
+        if (
+            !Number.isInteger(statusCode) ||
+            statusCode < 300 ||
+            statusCode > 399
+        ) {
+            throw new TypeError(
+                `Invalid HTTP redirect status code: ${statusCode}`
+            );
+        }
+
+        return res.redirect(statusCode, url);
+    }
+}
+
+export default ApiResponse;