create-lumina-project 1.0.0

package/template/src/exceptions/Handler.ts

@@ -0,0 +1,32 @@
+import { Request, Response, NextFunction } from 'express';
+import ApiResponse from '../utils/ApiResponse.js';
+import Logger from '../utils/Logger.js';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+class ExceptionHandler {
+  /**
+   * Handle 404 Not Found errors.
+   */
+  notFound(req: Request, res: Response, next: NextFunction) {
+    return ApiResponse.error(res, 'Route not found', 404);
+  }
+
+  /**
+   * Handle global application errors.
+   * Matches Express (err, req, res, next) signature.
+   */
+  handle(err: any, req: Request, res: Response, next: NextFunction) {
+    // Log the error
+    Logger.error('Exception:', err.stack || err.message);
+
+    const status = err.status || 500;
+    const message = err.message || 'Internal Server Error';
+    const errorDetails = process.env.NODE_ENV === 'development' ? err : {};
+
+    return ApiResponse.error(res, message, status, errorDetails);
+  }
+}
+
+export default new ExceptionHandler();

package/template/src/middlewares/Authentication.ts

@@ -0,0 +1,34 @@
+import { Request, Response, NextFunction } from 'express';
+import jwt from 'jsonwebtoken';
+import ApiResponse from '../utils/ApiResponse.js';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+class Authentication {
+  /**
+   * Handle an incoming request.
+   */
+  handle(req: Request, res: Response, next: NextFunction) {
+    const authHeader = req.headers.authorization;
+
+    if (!authHeader || !authHeader.startsWith('Bearer')) {
+      return ApiResponse.error(res, 'Unauthorized: No token provided', 401);
+    }
+
+    const token = authHeader.split(' ')[1];
+
+    try {
+      const secret = process.env.JWT_SECRET || 'default_secret';
+      const decoded = jwt.verify(token, secret);
+
+      req.user = decoded;
+
+      next();
+    } catch (error) {
+      return ApiResponse.error(res, 'Unauthorized: Invalid token', 401);
+    }
+  }
+}
+
+export default new Authentication();

package/template/src/middlewares/Limiter.ts

@@ -0,0 +1,34 @@
+import rateLimit from 'express-rate-limit';
+import ApiResponse from '../utils/ApiResponse.js';
+
+class Limiter {
+  /**
+   * General limiter for the entire API.
+   * Allows 100 requests per 15 minutes.
+   */
+  public static global = rateLimit({
+    windowMs: 15 * 60 * 1000,
+    max: 100,
+    standardHeaders: true,
+    legacyHeaders: false,
+    handler: (req, res) => {
+      return ApiResponse.error(res, 'Too many requests, please try again later.', 429);
+    },
+  });
+
+  /**
+   * Strict limiter for sensitive routes (Login/Register).
+   * Allows 5 attempts per hour.
+   */
+  public static auth = rateLimit({
+    windowMs: 60 * 60 * 1000,
+    max: 5,
+    standardHeaders: true,
+    legacyHeaders: false,
+    handler: (req, res) => {
+      return ApiResponse.error(res, 'Too many login attempts, please try again after an hour.', 429);
+    },
+  });
+}
+
+export default Limiter;

package/template/src/middlewares/Maintenance.ts

@@ -0,0 +1,37 @@
+import { Request, Response, NextFunction } from 'express';
+import fs from 'fs';
+import path from 'path';
+import ApiResponse from '../utils/ApiResponse.js';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+class Maintenance {
+  private lockFile = path.join(process.cwd(), 'maintenance.lock');
+
+  public handle = (req: Request, res: Response, next: NextFunction) => {
+    if (fs.existsSync(this.lockFile)) {
+      const bypassSecret = req.headers['x-bypass-maintenance'];
+
+      if (bypassSecret === process.env.MAINTENANCE_SECRET) {
+        return next();
+      }
+
+      res.status(503);
+      res.setHeader('Retry-After', '60');
+
+      if (req.accepts('html')) {
+        const viewPath = path.join(process.cwd(), 'views', 'maintenance.html');
+        if (fs.existsSync(viewPath)) {
+          return res.sendFile(viewPath);
+        }
+      }
+
+      return ApiResponse.error(res, 'System is currently under maintenance. Please try again later.', 503);
+    }
+    
+    next();
+  };
+}
+
+export default new Maintenance();

package/template/src/middlewares/Validator.ts

@@ -0,0 +1,29 @@
+import { Request, Response, NextFunction } from 'express';
+import { ZodType, ZodError } from 'zod';
+import ApiResponse from '../utils/ApiResponse.js';
+
+class Validator {
+  /**
+   * Validates the request body against a Zod schema.
+   */
+  public validate(schema: ZodType<any>) {
+    return (req: Request, res: Response, next: NextFunction) => {
+      try {
+        schema.parse(req.body);
+        next();
+      } catch (error) {
+        if (error instanceof ZodError) {
+          const formattedErrors = error.issues.map((err) => ({
+            field: err.path.join('.'),
+            message: err.message,
+          }));
+
+          return ApiResponse.error(res, 'Validation Failed', 422, formattedErrors);
+        }
+        next(error);
+      }
+    };
+  }
+}
+
+export default new Validator();

package/template/src/models/User.ts

@@ -0,0 +1,91 @@
+import { Model, DataTypes, Sequelize, Optional } from 'sequelize';
+import Hash from '../utils/Hash.js';
+
+interface UserAttributes {
+  id: number;
+  firstname: string;
+  lastname: string;
+  email: string;
+  password: string;
+  role: string;
+  avatar: string | null;
+  created_at?: Date;
+  updated_at?: Date;
+  deleted_at?: Date | null
+}
+
+export interface UserCreationAttributes extends Optional<UserAttributes, 'id' | 'created_at' | 'updated_at' | 'deleted_at' | 'role' | 'avatar'> {}
+
+class User extends Model<UserAttributes, UserCreationAttributes> implements UserAttributes {
+  declare id: number;
+  declare firstname: string;
+  declare lastname: string;
+  declare email: string;
+  declare password: string;
+  declare role: string;
+  declare avatar: string | null;
+  declare created_at: Date;
+  declare updated_at: Date;
+  declare deleted_at?: Date | null;
+
+  static initModel(sequelize: Sequelize) {
+    User.init(
+      {
+        id: {
+          type: DataTypes.INTEGER,
+          autoIncrement: true,
+          primaryKey: true,
+        },
+        firstname: {
+          type: DataTypes.STRING,
+          allowNull: false,
+        },
+        lastname: {
+          type: DataTypes.STRING,
+          allowNull: false,
+        },
+        email: {
+          type: DataTypes.STRING,
+          unique: true,
+          allowNull: false,
+        },
+        password: {
+          type: DataTypes.STRING,
+          allowNull: false,
+        },
+        role: {
+          type: DataTypes.STRING,
+          allowNull: false,
+          defaultValue: 'user',
+        },
+        avatar: {
+          type: DataTypes.TEXT,
+          allowNull: true,
+          defaultValue: null,
+        },
+      },
+      {
+        sequelize,
+        modelName: 'User',
+        tableName: 'users',
+        paranoid: true,
+        timestamps: true,
+        underscored: true,
+        hooks: {
+          beforeCreate: async (user: User) => {
+            if (user.password) {
+              user.password = await Hash.make(user.password);
+            }
+          },
+          beforeUpdate: async (user: User) => {
+            if (user.changed('password')) {
+              user.password = await Hash.make(user.password);
+            }
+          },
+        },
+      }
+    );
+  }
+}
+
+export default User;

package/template/src/models/index.ts

@@ -0,0 +1,92 @@
+import fs from 'fs';
+import path from 'path';
+import { Sequelize } from 'sequelize';
+import { fileURLToPath, pathToFileURL } from 'url';
+import configList from '../config/database.js';
+import Logger from '../utils/Logger.js';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+class Database {
+  public sequelize: Sequelize;
+  public models: any = {};
+
+  constructor() {
+    const env = process.env.NODE_ENV || 'development';
+    const config = (configList as any)[env];
+
+    if (!config) {
+      Logger.error(`Fatal Error: Database config for "${env}" not found.`);
+      process.exit(1);
+    }
+
+    // Initialize Sequelize
+    this.sequelize = new Sequelize(
+      config.database, 
+      config.username, 
+      config.password, 
+      config
+    );
+  }
+
+  /**
+   * Connect to DB and Load Models
+   */
+  public async connect() {
+    try {
+      // 1. Authenticate Connection
+      await this.sequelize.authenticate();
+      Logger.info('Database connection established.');
+
+      // 2. Load Models Dynamically
+      await this.loadModels();
+      
+      // 3. Setup Associations
+      this.associateModels();
+      
+    } catch (error) {
+      Logger.error('Unable to connect to the database:', error);
+      process.exit(1);
+    }
+  }
+
+  private async loadModels() {
+    const basename = path.basename(__filename);
+    
+    // Read all files in this directory
+    const files = fs.readdirSync(__dirname).filter((file) => {
+      return (
+        file.indexOf('.') !== 0 &&
+        file !== basename &&
+        (file.slice(-3) === '.ts' || file.slice(-3) === '.js')
+      );
+    });
+
+    // Import and Init each model
+    for (const file of files) {
+      const modelPath = pathToFileURL(path.join(__dirname, file)).href;
+      const modelModule = await import(modelPath);
+      const model = modelModule.default;
+
+      if (model && model.initModel) {
+        model.initModel(this.sequelize);
+        // Store in models object instead of root
+        this.models[model.name] = model; 
+      }
+    }
+  }
+
+  private associateModels() {
+    Object.keys(this.models).forEach((modelName) => {
+      if (this.models[modelName].associate) {
+        this.models[modelName].associate(this.models);
+      }
+    });
+  }
+}
+
+export default new Database();

package/template/src/requests/UserRequest.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+
+class UserRequest {
+  /**
+   * Rules for creating a user.
+   */
+  public static store = z.object({
+    firstname: z.string().min(2, 'First name must be at least 2 characters'),
+    lastname: z.string().min(2, 'Last name must be at least 2 characters'),
+    email: z.email('Invalid email address'),
+    password: z.string().min(8, 'Password must be at least 8 characters'),
+    // Optional: role is not required here if you default it in the database
+  });
+
+  /**
+   * Rules for updating a user.
+   */
+  public static update = z.object({
+    // fields optional for updates
+    firstname: z.string().min(2).optional(),
+    lastname: z.string().min(2).optional(),
+    email: z.string().email().optional(), 
+  });
+}
+
+export default UserRequest;

package/template/src/routes/api.ts

@@ -0,0 +1,30 @@
+import { Router } from 'express';
+import UserController from '../controllers/UserController.js';
+import Authentication from '../middlewares/Authentication.js';
+import Validator from '../middlewares/Validator.js';
+import UserRequest from '../requests/UserRequest.js';
+import AuthController from '../controllers/AuthController.js';
+import Limiter from '../middlewares/Limiter.js';
+import StorageService from '../services/StorageService.js';
+
+class ApiRoutes {
+  public router: Router;
+
+  constructor() {
+    this.router = Router();
+    this.initializeRoutes();
+  }
+
+  /**
+   * Define all API routes here.
+   */
+  protected initializeRoutes(): void {
+    this.router.post('/login', Limiter.auth, AuthController.login);
+    this.router.get('/me', Authentication.handle, AuthController.me);
+    this.router.get('/users', Authentication.handle, UserController.index);
+    this.router.post('/users', Validator.validate(UserRequest.store), UserController.store);
+    this.router.post('/users/avatar', Authentication.handle, StorageService.uploader.single('avatar'), UserController.uploadAvatar);
+  }
+}
+
+export default new ApiRoutes().router;

package/template/src/routes/web.ts

@@ -0,0 +1,29 @@
+import { Router, Request, Response } from 'express';
+import path from 'path';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+class WebRoutes {
+  public router: Router;
+
+  constructor() {
+    this.router = Router();
+    this.initializeRoutes();
+  }
+
+  protected initializeRoutes(): void {
+    // Home Route
+    this.router.get('/', (req: Request, res: Response) => {
+      const viewPath = path.join(process.cwd(), 'views', 'welcome.html');
+      res.sendFile(viewPath);
+    });
+
+    // Status Route
+    this.router.get('/status', (req: Request, res: Response) => {
+      res.json({ status: 'UP', environment: process.env.NODE_ENV });
+    });
+  }
+}
+
+export default new WebRoutes().router;

package/template/src/services/AuthService.ts

@@ -0,0 +1,29 @@
+import jwt from 'jsonwebtoken';
+import User from '../models/User.js';
+import Hash from '../utils/Hash.js';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+class AuthService {
+  public async login(email: string, password: string) {
+    const user = await User.findOne({ where: { email } });
+
+    if (!user || !(await Hash.check(password, user.password))) {
+      throw new Error('Invalid credentials');
+    }
+
+    const token = jwt.sign(
+      { id: user.id, email: user.email, role: user.role },
+      process.env.JWT_SECRET as string,
+      { expiresIn: process.env.JWT_EXPIRES_IN || '1d' } as jwt.SignOptions
+    );
+
+    const userResponse = user.toJSON();
+    const { password: _, ...userWithoutPassword } = userResponse;
+
+    return { user: userWithoutPassword, token };
+  }
+}
+
+export default new AuthService();

package/template/src/services/RouteService.ts

@@ -0,0 +1,15 @@
+import { Application } from 'express';
+import apiRoutes from '../routes/api.js';
+import webRoutes from '../routes/web.js';
+
+class RouteService {
+  /**
+   * Register all routes for the application.
+   */
+  public boot(app: Application): void {
+    app.use('/api', apiRoutes);
+    app.use('/', webRoutes);
+  }
+}
+
+export default new RouteService();

package/template/src/services/StorageService.ts

@@ -0,0 +1,59 @@
+import multer, { StorageEngine } from 'multer';
+import path from 'path';
+import fs from 'fs';
+import { Request } from 'express';
+
+class StorageService {
+  private storage: StorageEngine;
+  private uploadDir: string;
+
+  constructor() {
+    // 1. Define where files go
+    this.uploadDir = path.join(process.cwd(), 'public', 'uploads');
+    
+    // Ensure directory exists
+    if (!fs.existsSync(this.uploadDir)) {
+      fs.mkdirSync(this.uploadDir, { recursive: true });
+    }
+
+    // 2. Configure Disk Storage
+    this.storage = multer.diskStorage({
+      destination: (req, file, cb) => {
+        cb(null, this.uploadDir);
+      },
+      filename: (req, file, cb) => {
+        const uniqueSuffix = Date.now() + '-' + Math.round(Math.random() * 1E9);
+        const ext = path.extname(file.originalname);
+        cb(null, `${file.fieldname}-${uniqueSuffix}${ext}`);
+      },
+    });
+  }
+
+  /**
+   * Get the Multer instance with validation rules.
+   */
+  public get uploader() {
+    return multer({
+      storage: this.storage,
+      limits: {
+        fileSize: 5 * 1024 * 1024,
+      },
+      fileFilter: this.fileFilter,
+    });
+  }
+
+  /**
+   * Validate file types (e.g., Images only).
+   */
+  private fileFilter(req: Request, file: Express.Multer.File, cb: multer.FileFilterCallback) {
+    const allowedMimeTypes = ['image/jpeg', 'image/png', 'image/gif', 'application/pdf'];
+    
+    if (allowedMimeTypes.includes(file.mimetype)) {
+      cb(null, true);
+    } else {
+      cb(new Error('Invalid file type. Only JPEG, PNG, GIF, and PDF are allowed.'));
+    }
+  }
+}
+
+export default new StorageService();

package/template/src/services/UserService.ts

@@ -0,0 +1,31 @@
+import User, { UserCreationAttributes } from '../models/User.js';
+import Paginator from '../utils/Paginator.js';
+
+class UserService {
+  /**
+   * Get all users with pagination.
+   */
+  public async getAllUsers(page: number, limit: number) {
+    return await Paginator.paginate(User, page, limit, {
+      attributes: { exclude: ['password'] },
+      order: [['id', 'DESC']]
+    });
+  }
+
+  public async createUser(data: UserCreationAttributes) {
+    return await User.create(data);
+  }
+
+  public async updateAvatar(userId: number, avatarPath: string) {
+    const user = await User.findByPk(userId);
+
+    if (!user) {
+      throw new Error('User not found');
+    }
+
+    user.avatar = avatarPath;
+    return await user.save();
+  }
+}
+
+export default new UserService();

package/template/src/types/Pagination.d.ts

@@ -0,0 +1,13 @@
+export interface PaginationMeta {
+  total: number;
+  per_page: number;
+  current_page: number;
+  last_page: number;
+  from: number | null;
+  to: number | null;
+}
+
+export interface PaginatedResult<T> {
+  data: T[];
+  meta: PaginationMeta;
+}

package/template/src/types/express/index.d.ts

@@ -0,0 +1,9 @@
+import { JwtPayload } from 'jsonwebtoken';
+
+declare global {
+  namespace Express {
+    interface Request {
+      user?: string | JwtPayload | any;
+    }
+  }
+}

package/template/src/utils/ApiResponse.ts

@@ -0,0 +1,27 @@
+import { Response } from 'express';
+
+class ApiResponse {
+  /**
+   * Send a standard success response.
+   */
+  public success(res: Response, data: any, message: string = 'Success', code: number = 200) {
+    return res.status(code).json({
+      success: true,
+      message,
+      data,
+    });
+  }
+
+  /**
+   * Send a standard error response.
+   */
+  public error(res: Response, message: string = 'Error', code: number = 400, errors: any = null) {
+    return res.status(code).json({
+      success: false,
+      message,
+      errors,
+    });
+  }
+}
+
+export default new ApiResponse();

package/template/src/utils/Hash.ts

@@ -0,0 +1,21 @@
+import bcrypt from 'bcrypt';
+
+class Hash {
+  /**
+   * Hash a plain text string.
+   * Usage: await Hash.make('password123');
+   */
+  public async make(plainText: string): Promise<string> {
+    return await bcrypt.hash(plainText, 10);
+  }
+
+  /**
+   * Verify a plain text string against a hash.
+   * Usage: await Hash.check('password123', user.password);
+   */
+  public async check(plainText: string, hashedValue: string): Promise<boolean> {
+    return await bcrypt.compare(plainText, hashedValue);
+  }
+}
+
+export default new Hash();