@codenokami/node-api-master 1.4.0

package/README.md

@@ -0,0 +1,164 @@
+# @cnk/node-api-master 🚀
+
+A robust, professional-grade utility package for Express.js APIs. This package simplifies database connections, authentication, real-time communication with Socket.io, error handling, and request validation.
+
+---
+
+## 📦 Installation
+
+This package is designed to work with **mongoose** and **socket.io** as peer dependencies to avoid version conflicts.
+
+```bash
+# Install the core package
+npm install @cnk/node-api-master
+
+# Install required peer dependencies
+npm install mongoose socket.io
+
+```
+
+---
+
+## 📂 Features
+
+- **🛡 Auth & Admin Middleware**: JWT-based route protection and role-based access control.
+- **🔌 Socket.io Helper**: Integrated real-time communication with JWT authentication support.
+- **🚨 Global Error Handler**: Centralized error management using the `AppError` class.
+- **⚡ CatchAsync Utility**: Eliminate repetitive `try-catch` blocks in your controllers.
+- **✅ Joi Validation**: Pre-defined and custom schemas for request validation.
+- **🔗 DB Helper**: Simplified MongoDB connection setup.
+- **📊 Standardized Responses**: Uniform success and error API response formats.
+
+---
+
+## 📖 Detailed Usage Guide
+
+### 1. Database Connection & Server Setup
+
+Handle dynamic ports and database connections efficiently.
+
+```javascript
+const { connectDB, STATUS_CODES } = require("@cnk/node-api-master");
+
+// Start DB
+connectDB(process.env.MONGO_URI);
+
+// Dynamic Port
+const PORT = process.env.PORT || 5000;
+app.listen(PORT, () => console.log(`Server running on port ${PORT}`));
+```
+
+---
+
+### 2. Socket.io with Authentication
+
+Setup a secure real-time server. The middleware automatically verifies tokens from `socket.handshake.auth.token`.
+
+```javascript
+const http = require("http");
+const { socket } = require("@cnk/node-api-master");
+
+const server = http.createServer(app);
+
+// Initialize Socket with JWT protection
+const io = socket.initSocket(server, {
+  authRequired: true,
+  jwtSecret: process.env.JWT_SECRET,
+});
+
+io.on("connection", (s) => {
+  console.log("Authenticated User ID:", s.user.id);
+});
+
+server.listen(PORT);
+```
+
+---
+
+### 3. Authentication Middleware (HTTP)
+
+Protect your Express routes using JWT.
+
+```javascript
+const { auth, admin } = require("@cnk/node-api-master");
+
+// Protect a route
+router.get("/me", auth(), userController.getMe);
+
+// Admin only route
+router.delete("/users/:id", auth(), admin, userController.deleteUser);
+```
+
+---
+
+### 4. Request Validation (Joi)
+
+Validate incoming request bodies, params, or queries.
+
+```javascript
+const { validate, schemas, Joi } = require("@cnk/node-api-master");
+
+// Use pre-built schemas
+router.post("/login", validate(schemas.user.login), authController.login);
+
+// Use custom schema
+const profileSchema = Joi.object({
+  bio: Joi.string().max(200),
+  website: Joi.string().uri(),
+});
+router.put("/profile", validate(profileSchema), userController.updateProfile);
+```
+
+---
+
+### 5. Standardized Responses & Error Handling
+
+Keep your API responses consistent across the entire project.
+
+```javascript
+const {
+  catchAsync,
+  AppError,
+  apiResponse,
+  STATUS_CODES,
+} = require("@cnk/node-api-master");
+
+exports.getUser = catchAsync(async (req, res, next) => {
+  const user = await User.findById(req.params.id);
+
+  if (!user) {
+    return next(new AppError("User not found!", STATUS_CODES.NOT_FOUND));
+  }
+
+  apiResponse.success(res, user, "User retrieved successfully");
+});
+```
+
+---
+
+### 6. Global Error Middleware
+
+**Mandatory:** Register this at the very end of your middleware stack in `app.js`.
+
+```javascript
+const { errorMiddleware } = require("@cnk/node-api-master");
+
+// After all your routes
+app.use(errorMiddleware);
+```
+
+---
+
+## 🛠 Project Structure
+
+- `src/db`: Mongoose connection helpers.
+- `src/middleware`: Auth, Admin, Validation, and Global Error handlers.
+- `src/socket`: Socket.io initialization and JWT middleware.
+- `src/utils`: `AppError`, `catchAsync`, and API response helpers.
+- `src/validations`: Reusable Joi schemas.
+
+---
+
+## 📄 License
+
+MIT © CNK

package/dist/index.d.mts

@@ -0,0 +1,436 @@
+import Joi from 'joi';
+export { default as Joi } from 'joi';
+import mongoose from 'mongoose';
+import jwt from 'jsonwebtoken';
+import bcrypt from 'bcryptjs';
+import crypto from 'crypto';
+import { Server } from 'socket.io';
+
+/**
+ * Database သို့ ချိတ်ဆက်ပေးသော function
+ * @param {string} url - MongoDB Connection String
+ */
+const connectDB = async (url) => {
+  if (!url) {
+    console.error(
+      "❌ Error: MongoDB URL is required to connect to the database.",
+    );
+    process.exit(1);
+  }
+
+  try {
+    const conn = await mongoose.connect(url);
+    console.log(`✅ MongoDB Connected: ${conn.connection.host}`);
+  } catch (error) {
+    console.error(`❌ Error: ${error.message}`);
+    process.exit(1); // ချိတ်မရရင် Server ကို ရပ်ပစ်မယ်
+  }
+};
+
+/**
+ * Custom Error Class for API Errors
+ */
+class AppError extends Error {
+  constructor(message, statusCode) {
+    super(message);
+
+    this.statusCode = statusCode;
+    // status က 4xx ဆိုရင် 'fail', 5xx ဆိုရင် 'error' လို့ သတ်မှတ်မယ်
+    this.status = `${statusCode}`.startsWith("4") ? "fail" : "error";
+
+    // ဒါက ကျွန်တော်တို့ကိုယ်တိုင် သတ်မှတ်လိုက်တဲ့ Error ဖြစ်ကြောင်း အမှတ်အသားပြုတာပါ
+    this.isOperational = true;
+
+    // Error ဘယ်နေရာမှာ ဖြစ်တယ်ဆိုတဲ့ stack trace ကို သိမ်းထားမယ်
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+/**
+ * catchAsync - try-catch block တွေကို အစားထိုးရန်
+ * @param {Function} fn - Async controller function
+ */
+const catchAsync = (fn) => {
+  return (req, res, next) => {
+    // ပေးလိုက်တဲ့ function ကို run မယ်၊ error တက်ရင် .catch() ကနေ next(err) ကို ပို့ပေးမယ်
+    fn(req, res, next).catch(next);
+  };
+};
+
+/**
+ * Auth Middleware - Supports Bearer Token & Cookies
+ * @param {string} secret - JWT Secret (Default is process.env.JWT_SECRET)
+ */
+const auth = (secret = process.env.JWT_SECRET) =>
+  catchAsync(async (req, res, next) => {
+    let token;
+
+    // 1) Header ကနေ Bearer Token ကို စစ်ဆေးခြင်း
+    if (
+      req.headers.authorization &&
+      req.headers.authorization.startsWith("Bearer")
+    ) {
+      token = req.headers.authorization.split(" ")[1];
+    }
+    // 2) Cookie ကနေ Token ကို စစ်ဆေးခြင်း
+    else if (req.cookies && req.cookies.jwt) {
+      token = req.cookies.jwt;
+    }
+
+    // Secret မရှိရင် Developer ကို သတိပေးဖို့ Error ပြမယ်
+    if (!secret) {
+      return next(
+        new AppError("JWT Secret is not defined in environment variables", 500),
+      );
+    }
+
+    if (!token) {
+      return next(
+        new AppError(
+          "You are not logged in! Please log in to get access.",
+          401,
+        ),
+      );
+    }
+
+    // Verify token
+    try {
+      const decoded = jwt.verify(token, secret);
+      req.user = decoded;
+      next();
+    } catch (error) {
+      return next(
+        new AppError("Invalid token or expired. Please log in again.", 401),
+      );
+    }
+  });
+
+/**
+ * Admin Middleware
+ */
+const admin = (req, res, next) => {
+  if (req.user && req.user.role === "admin") {
+    next();
+  } else {
+    return next(
+      new AppError("You do not have permission to perform this action", 403),
+    );
+  }
+};
+
+/**
+ * Joi Schema Validation Middleware
+ * @param {Object} schema - Joi validation schema
+ */
+const validate = (schema) => (req, res, next) => {
+  // body, query, params အားလုံးကို စစ်လို့ရအောင် req object တစ်ခုလုံးကို schema နဲ့ တိုက်စစ်မယ်
+  const { error, value } = schema.validate(req.body, {
+    abortEarly: false, // Error အားလုံးကို တစ်ခါတည်း ပြရန်
+    allowUnknown: true, // Schema ထဲမပါတဲ့ field တွေပါလာရင် လက်ခံရန်
+    stripUnknown: true, // Schema ထဲမပါတဲ့ field တွေကို ဖယ်ထုတ်ပစ်ရန်
+  });
+
+  if (error) {
+    // Error message တွေကို စုစည်းပြီး format လုပ်မယ်
+    const errorMessage = error.details
+      .map((detail) => detail.message.replace(/"/g, ""))
+      .join(", ");
+
+    return next(new AppError(errorMessage, 400));
+  }
+
+  // စစ်ဆေးပြီးသား data (sanitized data) ကို req.body ထဲ ပြန်ထည့်မယ်
+  req.body = value;
+  next();
+};
+
+/**
+ * Standard HTTP Status Codes
+ */
+const PORT = process.env.PORT || 5000;
+
+const STATUS_CODES = {
+  // --- 2xx Success ---
+  OK: 200, // Request အောင်မြင်သည်
+  CREATED: 201, // Data အသစ် တည်ဆောက်မှု အောင်မြင်သည်
+  ACCEPTED: 202, // လက်ခံရရှိသည် (နောက်မှ အလုပ်လုပ်မည်)
+  NO_CONTENT: 204, // အောင်မြင်သည်၊ သို့သော် ပြစရာ Data မရှိ (ဥပမာ- Delete လုပ်ပြီးချိန်)
+
+  // --- 3xx Redirection ---
+  MOVED_PERMANENTLY: 301,
+  FOUND: 302,
+
+  // --- 4xx Client Errors ---
+  BAD_REQUEST: 400, // ပေးပို့လိုက်သော Data Format မှားနေသည် (Validation error)
+  UNAUTHORIZED: 401, // Login ဝင်ရန် လိုအပ်သည် (သို့မဟုတ် Token မှားသည်)
+  FORBIDDEN: 403, // လုပ်ပိုင်ခွင့်မရှိ (ဥပမာ- Admin မဟုတ်ဘဲ Admin panel ဝင်ခြင်း)
+  NOT_FOUND: 404, // ရှာဖွေနေသော Resource မရှိပါ
+  METHOD_NOT_ALLOWED: 405, // API Method (GET, POST, etc.) မှားနေသည်
+  CONFLICT: 409, // Data ထပ်နေသည် (ဥပမာ- ရှိပြီးသား Email နဲ့ Register လုပ်ခြင်း)
+  UNPROCESSABLE_ENTITY: 422, // Validation Error များအတွက် အသုံးများသည်
+  TOO_MANY_REQUESTS: 429, // API ကို ခဏခဏ ဆက်တိုက်ခေါ်ခြင်း (Rate limiting)
+
+  // --- 5xx Server Errors ---
+  INTERNAL_SERVER_ERROR: 500, // Server ထဲတွင် Code မှားယွင်းခြင်း
+  NOT_IMPLEMENTED: 501,
+  BAD_GATEWAY: 502,
+  SERVICE_UNAVAILABLE: 503, // Server ခေတ္တပိတ်ထားသည်
+  GATEWAY_TIMEOUT: 504,
+
+  PORT,
+};
+
+/**
+ * Global Error Handling Middleware
+ */
+const errorMiddleware = (err, req, res, next) => {
+  err.statusCode = err.statusCode || STATUS_CODES.INTERNAL_SERVER_ERROR;
+  err.status = err.status || "error";
+
+  // Development mode မှာ Error အပြည့်အစုံပြပြီး Production မှာ message ပဲ ပြမယ်
+  if (process.env.NODE_ENV === "development") {
+    res.status(err.statusCode).json({
+      status: err.status,
+      error: err,
+      message: err.message,
+      stack: err.stack,
+    });
+  } else {
+    // Production Mode
+    // အကယ်၍ ဒါက ကျွန်တော်တို့ သတ်မှတ်ထားတဲ့ Operational Error (AppError) ဆိုရင်
+    if (err.isOperational) {
+      res.status(err.statusCode).json({
+        status: err.status,
+        message: err.message,
+      });
+    } else {
+      // မထင်မှတ်ထားတဲ့ Programming error တွေဖြစ်ရင် (ဥပမာ- Library တစ်ခုက တက်တဲ့ error)
+      console.error("ERROR 💥", err);
+      res.status(STATUS_CODES.INTERNAL_SERVER_ERROR).json({
+        status: "error",
+        message: "Something went very wrong!",
+      });
+    }
+  }
+};
+
+/**
+ * Standard API Response Wrapper
+ */
+const apiResponse = {
+  // အောင်မြင်တဲ့ response ပေးပို့ရန်
+  success: (res, data, message = "Success", statusCode = STATUS_CODES.OK) => {
+    return res.status(statusCode).json({
+      status: "success",
+      message,
+      data,
+    });
+  },
+
+  // Error response ပေးပို့ရန် (Operational error များအတွက်)
+  error: (
+    res,
+    message = "Internal Server Error",
+    statusCode = STATUS_CODES.INTERNAL_SERVER_ERROR,
+  ) => {
+    return res.status(statusCode).json({
+      status: "error",
+      message,
+    });
+  },
+};
+
+declare namespace response {
+  export { apiResponse as default };
+}
+
+/**
+ * Password ကို Hash လုပ်ရန်
+ */
+const hashPassword = async (password) => {
+  const salt = await bcrypt.genSalt(10);
+  return await bcrypt.hash(password, salt);
+};
+
+/**
+ * Password မှန်/မမှန် စစ်ဆေးရန်
+ */
+const comparePassword = async (password, hashedPassword) => {
+  return await bcrypt.compare(password, hashedPassword);
+};
+
+/**
+ * JWT Token ထုတ်ပေးပြီး Cookie ထဲသို့ တန်းထည့်ပေးမည့် Helper
+ * @param {Object} payload - Token ထဲတွင် သိမ်းလိုသော အချက်အလက် (e.g., { userId })
+ * @param {Object} res - Express Response Object
+ * @param {Object} options - စိတ်ကြိုက်ပြင်ဆင်နိုင်သော options များ
+ */
+const generateToken = (payload, res, options = {}) => {
+  const secret = options.secret || process.env.JWT_SECRET;
+  const expiresIn = options.expiresIn || "30d";
+  const cookieName = options.cookieName || "jwt";
+
+  // 1. Token Generate လုပ်ခြင်း
+  const token = jwt.sign(payload, secret, {
+    expiresIn: expiresIn,
+  });
+
+  // 2. Cookie Options သတ်မှတ်ခြင်း
+  const cookieOptions = {
+    maxAge: options.maxAge || 30 * 24 * 60 * 60 * 1000, // Default 30 days
+    httpOnly: true, // JavaScript မှ ဖတ်မရအောင် (Prevent XSS)
+    sameSite: process.env.NODE_ENV === "production" ? "none" : "lax", // CSRF Protection
+    secure: process.env.NODE_ENV === "production", // Production တွင် HTTPS သုံးမှသာ အလုပ်လုပ်မည်
+    ...options.extraCookieOptions, // တခြား အပို options များရှိလျှင် ထည့်ရန်
+  };
+
+  // 3. Cookie ထဲသို့ ထည့်ခြင်း
+  res.cookie(cookieName, token, cookieOptions);
+
+  return token;
+};
+
+/**
+ * တကယ့်ကို ခိုင်ခံ့ပြီး Secure ဖြစ်တဲ့ UUID v4 ထုတ်ပေးရန်
+ * (RFC 4122 Standard Compliant)
+ */
+const generateUUID = () => {
+  // 1. ခေတ်သစ် Node.js (v14.17.0+) အတွက် တိုက်ရိုက်သုံးမယ်
+  if (typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+
+  // 2. Fallback: Node ဗားရှင်းအနိမ့်တွေအတွက် Cryptographically Secure ဖြစ်အောင် ကိုယ်တိုင်ထုတ်မယ်
+  return ([1e7] + -1e3 + -4e3 + -8e3 + -1e11).replace(/[018]/g, (c) =>
+    (c ^ (crypto.randomBytes(1).readUInt8() & (15 >> (c / 4)))).toString(16),
+  );
+};
+
+/**
+ * User Validation Schemas
+ */
+const userSchema = {
+  // Standard Register Schema
+  register: Joi.object({
+    username: Joi.string().alphanum().min(3).max(30).required().messages({
+      "string.min": "Username must be at least 3 characters long",
+      "any.required": "Username is a required field",
+    }),
+    email: Joi.string()
+      .email({ minDomainSegments: 2, tlds: { allow: ["com", "net", "org"] } })
+      .required()
+      .messages({
+        "string.email": "Please provide a valid email address",
+      }),
+    password: Joi.string().min(8).required().messages({
+      "string.min": "Password must be at least 8 characters long",
+    }),
+    confirmPassword: Joi.any()
+      .equal(Joi.ref("password"))
+      .required()
+      .messages({ "any.only": "Passwords do not match" }),
+    role: Joi.string().valid("user", "admin").default("user"),
+  }),
+
+  // Login Schema
+  login: Joi.object({
+    email: Joi.string().email().required(),
+    password: Joi.string().required(),
+  }),
+
+  // Password Update Schema
+  updatePassword: Joi.object({
+    currentPassword: Joi.string().required(),
+    newPassword: Joi.string().min(8).required(),
+  }),
+
+  /**
+   * စိတ်ကြိုက် schema အသစ်ဆောက်ချင်ရင် သုံးရန် (Dynamic Flexibility)
+   * @param {Object} schemaDefinition - Joi object definition
+   */
+  custom: (schemaDefinition) => Joi.object(schemaDefinition),
+};
+
+/**
+ * Common Joi Schemas
+ */
+const commonSchema = {
+  // MongoDB ObjectId စစ်ဆေးရန် (24 hex characters)
+  objectId: Joi.string()
+    .regex(/^[0-9a-fA-F]{24}$/)
+    .messages({
+      "string.pattern.base": "Invalid ID format. Must be a valid ObjectId.",
+    }),
+
+  // Pagination အတွက် (Query strings)
+  pagination: Joi.object({
+    page: Joi.number().integer().min(1).default(1),
+    limit: Joi.number().integer().min(1).max(100).default(10),
+    sort: Joi.string().optional(),
+    fields: Joi.string().optional(),
+  }),
+};
+
+const schemas = {
+  user: userSchema,
+  common: commonSchema,
+};
+
+let io;
+
+/**
+ * Socket Authentication Middleware
+ */
+const socketAuth = (secret) => {
+  return (socket, next) => {
+    const token =
+      socket.handshake.auth?.token || socket.handshake.headers?.token;
+
+    if (!token) {
+      return next(new Error("Authentication error: Token missing"));
+    }
+
+    try {
+      const decoded = jwt.verify(token, secret || process.env.JWT_SECRET);
+      socket.user = decoded; // socket ထဲမှာ user data သိမ်းထားမယ်
+      next();
+    } catch (err) {
+      next(new Error("Authentication error: Invalid token"));
+    }
+  };
+};
+
+/**
+ * Socket Initialize လုပ်ခြင်း
+ */
+const initSocket = (server, options = {}) => {
+  io = new Server(server, {
+    cors: {
+      origin: options.origin || "*",
+    },
+    ...options,
+  });
+
+  // JWT Middleware ကို အသုံးပြုခြင်း
+  if (options.authRequired) {
+    io.use(socketAuth(options.jwtSecret));
+  }
+
+  return io;
+};
+
+/**
+ * Initialize ပြီးသား IO object ကို ပြန်ယူခြင်း
+ */
+const getIO = () => {
+  if (!io) throw new Error("Socket.io not initialized!");
+  return io;
+};
+
+declare const index_getIO: typeof getIO;
+declare const index_initSocket: typeof initSocket;
+declare namespace index {
+  export { index_getIO as getIO, index_initSocket as initSocket };
+}
+
+export { AppError, STATUS_CODES, admin, response as apiResponse, auth, catchAsync, comparePassword, connectDB, errorMiddleware, generateToken, generateUUID, hashPassword, schemas, index as socket, validate };