create-lumina-project 1.0.0

package/template/scripts/migrate.ts

@@ -0,0 +1,146 @@
+import { Umzug, SequelizeStorage } from 'umzug';
+import { Sequelize, QueryInterface } from 'sequelize';
+import { pathToFileURL } from 'url';
+import db from '../src/models/index.js';
+import configList from '../src/config/database.js';
+import Logger from '../src/utils/Logger.js';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+class MigrationRunner {
+  /**
+   * The command line argument (e.g., 'up', 'down', 'reset')
+   */
+  private command: string;
+
+  constructor() {
+    // Get the command from process arguments
+    this.command = process.argv[2] || '';
+  }
+
+  /**
+   * Main entry point to execute the migration logic.
+   */
+  public async run(): Promise<void> {
+    try {
+      // 1. Ensure Database Exists
+      await this.ensureDatabaseExists();
+
+      // 2. Connect to the App Database
+      await this.connectDatabase();
+
+      // 3. Configure Umzug (The Migration Engine)
+      const umzug = this.getUmzugInstance();
+
+      // 4. Execute the requested command
+      await this.executeCommand(umzug);
+      
+      process.exit(0);
+    } catch (error) {
+      Logger.error('Migration failed:', error);
+      process.exit(1);
+    }
+  }
+
+  /**
+   * Check if the database exists and create it if not.
+   */
+  private async ensureDatabaseExists(): Promise<void> {
+    const env = process.env.NODE_ENV || 'development';
+    const config = (configList as any)[env];
+    const dbName = config.database;
+
+    // Connect to the server, not the specific DB
+    const tempSequelize = new Sequelize('', config.username, config.password, {
+      host: config.host,
+      dialect: config.dialect,
+      logging: false,
+    });
+
+    try {
+      await tempSequelize.query(`CREATE DATABASE IF NOT EXISTS \`${dbName}\`;`);
+    } catch (error) {
+      Logger.error('Failed to create database:', error);
+      throw error;
+    } finally {
+      await tempSequelize.close();
+    }
+  }
+
+  /**
+   * Verify the database connection.
+   */
+  private async connectDatabase(): Promise<void> {
+      await db.connect();
+  }
+
+  /**
+   * Initialize and configure Umzug.
+   */
+  private getUmzugInstance(): Umzug<QueryInterface> {
+    const sequelize = db.sequelize;
+
+    return new Umzug<QueryInterface>({
+      migrations: {
+        glob: 'src/database/migrations/*.js',
+        resolve: ({ name, path, context }) => {
+          return {
+            name,
+            up: async () => {
+              // Windows Fix: Convert path to URL
+              const migration = await import(pathToFileURL(path as string).href);
+              return migration.default.up(context, sequelize.Sequelize);
+            },
+            down: async () => {
+              // Windows Fix: Convert path to URL
+              const migration = await import(pathToFileURL(path as string).href);
+              return migration.default.down(context, sequelize.Sequelize);
+            },
+          };
+        },
+      },
+      context: sequelize.getQueryInterface(),
+      storage: new SequelizeStorage({ sequelize }),
+      logger: console,
+    });
+  }
+
+  /**
+   * Handle the specific CLI command logic.
+   */
+  private async executeCommand(umzug: Umzug<QueryInterface>): Promise<void> {
+    switch (this.command) {
+      case 'up':
+        Logger.info('Running Migrations...');
+        await umzug.up();
+        Logger.info('Migrations executed successfully.');
+        break;
+
+      case 'down':
+        Logger.info('Rolling back last migration...');
+        await umzug.down();
+        Logger.info('Rollback complete.');
+        break;
+
+      case 'reset':
+        Logger.info('Resetting Database...');
+        await umzug.down({ to: 0 });
+        Logger.info('Database reset complete.');
+        break;
+
+      default:
+        Logger.info(`
+        Unknown command: "${this.command}"
+        
+        Usage:
+          npm run migrate       -> Run pending migrations
+          npm run migrate:undo  -> Undo last migration
+          npm run migrate:reset -> Undo all migrations
+        `);
+        break;
+    }
+  }
+}
+
+new MigrationRunner().run();

package/template/scripts/seed.ts

@@ -0,0 +1,42 @@
+import db from '../src/models/index.js';
+import DatabaseSeeder from '../src/database/seeders/DatabaseSeeder.js';
+import Logger from '../src/utils/Logger.js';
+
+class SeederRunner {
+  /**
+   * Main entry point to execute the seeding logic.
+   */
+  public async run(): Promise<void> {
+    try {
+      // 1. Connect to the Database
+      await this.connectDatabase();
+
+      // 2. Execute the Main Seeder
+      await this.executeSeeding();
+
+      Logger.info('Database seeding completed successfully.');
+      process.exit(0);
+    } catch (error) {
+      Logger.error('Seeding failed:', error);
+      process.exit(1);
+    }
+  }
+
+  /**
+   * Verify the database connection.
+   */
+  private async connectDatabase(): Promise<void> {
+      await db.connect();
+  }
+
+  /**
+   * Instantiate and run the main DatabaseSeeder.
+   */
+  private async executeSeeding(): Promise<void> {
+    Logger.info('Starting Database Seeder...');
+    
+    await DatabaseSeeder.run();
+  }
+}
+
+new SeederRunner().run();

package/template/scripts/stubs/controller.stub

@@ -0,0 +1,50 @@
+import { Request, Response } from 'express';
+import ApiResponse from '../utils/ApiResponse.js';
+
+class {{ControllerName}} {
+  
+  /**
+   * Display a listing of the resource.
+   */
+  public async index(req: Request, res: Response) {
+    // const items = await Model.findAll();
+    return ApiResponse.success(res, []);
+  }
+
+  /**
+   * Store a newly created resource in storage.
+   */
+  public async store(req: Request, res: Response) {
+    // const item = await Model.create(req.body);
+    return ApiResponse.success(res, {}, 'Resource created successfully');
+  }
+
+  /**
+   * Display the specified resource.
+   */
+  public async show(req: Request, res: Response) {
+    const { id } = req.params;
+    // const item = await Model.findByPk(id);
+    return ApiResponse.success(res, { id });
+  }
+
+  /**
+   * Update the specified resource in storage.
+   */
+  public async update(req: Request, res: Response) {
+    const { id } = req.params;
+    // await Model.update(req.body, { where: { id } });
+    return ApiResponse.success(res, { id }, 'Resource updated successfully');
+  }
+
+  /**
+   * Remove the specified resource from storage.
+   */
+  public async destroy(req: Request, res: Response) {
+    const { id } = req.params;
+    // await Model.destroy({ where: { id } });
+    return ApiResponse.success(res, null, 'Resource deleted successfully');
+  }
+}
+
+export default new {{ControllerName}}();

package/template/scripts/stubs/factory.stub

@@ -0,0 +1,19 @@
+import { faker } from '@faker-js/faker';
+import {{ModelName}} from '../../models/{{ModelName}}.js';
+import Factory from './Factory.js';
+
+class {{FactoryName}} extends Factory<{{ModelName}}> {
+  protected model = {{ModelName}};
+
+  /**
+   * Define the model's default state.
+   */
+  protected definition() {
+    return {
+      // name: faker.person.fullName(),
+      // email: faker.internet.email(),
+    };
+  }
+}
+
+export default new {{FactoryName}}();

package/template/scripts/stubs/migration.stub

@@ -0,0 +1,44 @@
+import { DataTypes } from 'sequelize';
+
+class Create{{ClassName}} {
+  /**
+   * Run the migrations.
+   */
+  async up(queryInterface, sequelize) {
+    await queryInterface.createTable('{{TableName}}', {
+      id: {
+        allowNull: false,
+        autoIncrement: true,
+        primaryKey: true,
+        type: DataTypes.BIGINT
+      },
+      
+      // Add your columns here...
+
+      created_at: {
+        type: DataTypes.DATE,
+        allowNull: false,
+        defaultValue: sequelize.literal('CURRENT_TIMESTAMP')
+      },
+      updated_at: {
+        type: DataTypes.DATE,
+        allowNull: false,
+        defaultValue: sequelize.literal('CURRENT_TIMESTAMP')
+      },
+      // Uncomment for paranoid mode
+      // deleted_at: {
+      //   type: DataTypes.DATE,
+      //   allowNull: true,
+      // }
+    });
+  }
+
+  /**
+   * Reverse the migrations.
+   */
+  async down(queryInterface, sequelize) {
+    await queryInterface.dropTable('{{TableName}}');
+  }
+}
+
+export default new Create{{ClassName}}();

package/template/scripts/stubs/model.stub

@@ -0,0 +1,39 @@
+import { Model, DataTypes, Sequelize, Optional } from 'sequelize';
+
+interface {{ModelName}}Attributes {
+  id: number;
+  created_at?: Date;
+  updated_at?: Date;
+  deleted_at?: Date | null;
+}
+
+export interface {{ModelName}}CreationAttributes extends Optional<{{ModelName}}Attributes, 'id' | 'created_at' | 'updated_at' | 'deleted_at'> {}
+
+class {{ModelName}} extends Model<{{ModelName}}Attributes, {{ModelName}}CreationAttributes> implements {{ModelName}}Attributes {
+  declare id: number;
+  declare created_at: Date;
+  declare updated_at: Date;
+  declare deleted_at: Date | null;
+
+  static initModel(sequelize: Sequelize) {
+    {{ModelName}}.init(
+      {
+        id: {
+          type: DataTypes.INTEGER,
+          autoIncrement: true,
+          primaryKey: true,
+        },
+      },
+      {
+        sequelize,
+        modelName: '{{ModelName}}',
+        tableName: '{{TableName}}', // e.g. 'products'
+        paranoid: true,
+        timestamps: true,
+        underscored: true,
+      }
+    );
+  }
+}
+
+export default {{ModelName}};

package/template/server.ts

@@ -0,0 +1,63 @@
+import express, { Application } from 'express';
+import cors from 'cors';
+import helmet from 'helmet';
+import path from 'path';
+import db from './src/models/index.js';
+import RouteService from './src/services/RouteService.js';
+import ExceptionHandler from './src/exceptions/Handler.js';
+import Logger from './src/utils/Logger.js';
+import Limiter from './src/middlewares/Limiter.js';
+import Maintenance from './src/middlewares/Maintenance.js';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+const app: Application = express();
+const PORT = process.env.APP_PORT || 3000;
+
+// ==========================
+// Global Middleware
+// ==========================
+app.use(Maintenance.handle);
+app.use(helmet({ crossOriginResourcePolicy: false }));
+app.use(cors());
+app.use(express.json());
+app.use(express.urlencoded({ extended: true }));
+app.use(express.static(path.join(process.cwd(), 'public')));
+app.use(Limiter.global);
+
+// ==========================
+// Register Routes
+// ==========================
+// This loads both your API and Web routes
+RouteService.boot(app);
+
+// ==========================
+// Error Handling
+// ==========================
+
+// 404 Not Found Handler
+app.use(ExceptionHandler.notFound);
+
+// Global Error Handler
+app.use(ExceptionHandler.handle);
+
+// ==========================
+// Start Server
+// ==========================
+const start = async () => {
+  try {
+    // Test Database Connection
+    await db.connect();
+
+    // Start Listening
+    app.listen(PORT, () => {
+      Logger.info(`Server running on http://localhost:${PORT}`);
+    });
+  } catch (error) {
+    Logger.error('Unable to connect to the database:', error);
+    process.exit(1);
+  }
+};
+
+start();

package/template/src/config/database.ts

@@ -0,0 +1,39 @@
+import { Options } from 'sequelize';
+import Logger from '../utils/Logger.js';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+class DatabaseConfig {
+  public development: Options;
+  public test: Options;
+  public production: Options;
+
+  constructor() {
+    this.development = this.getEnvironmentConfig();
+    this.test = this.getEnvironmentConfig('test');
+    this.production = this.getEnvironmentConfig('production');
+  }
+
+  /**
+   * Helper to generate config based on the environment.
+   * This reduces repetition.
+   */
+  private getEnvironmentConfig(env: 'development' | 'test' | 'production' = 'development'): Options {
+    const isTest = env === 'test';
+    const isProd = env === 'production';
+
+    return {
+      username: process.env.DB_USERNAME,
+      password: process.env.DB_PASSWORD,
+      database: isTest ? process.env.DB_DATABASE_TEST : process.env.DB_DATABASE,
+      host: process.env.DB_HOST,
+      port: Number(process.env.DB_PORT) || 3306,
+      dialect: (process.env.DB_DIALECT as any) || 'mysql',
+      // Disable logging in test/production to keep logs clean
+      logging: isProd || isTest ? false : (msg) => Logger.info(`[SQL] ${msg}`),
+    };
+  }
+}
+
+export default new DatabaseConfig();

package/template/src/controllers/AuthController.ts

@@ -0,0 +1,21 @@
+import { Request, Response } from 'express';
+import AuthService from '../services/AuthService.js';
+import ApiResponse from '../utils/ApiResponse.js';
+
+class AuthController {
+  public async login(req: Request, res: Response) {
+    try {
+      const { email, password } = req.body;
+      const result = await AuthService.login(email, password);
+      return ApiResponse.success(res, result, 'Login successful');
+    } catch (error: any) {
+      return ApiResponse.error(res, error.message, 401);
+    }
+  }
+
+  public async me(req: Request, res: Response) {
+    return ApiResponse.success(res, req.user);
+  }
+}
+
+export default new AuthController();

package/template/src/controllers/UserController.ts

@@ -0,0 +1,52 @@
+import { Request, Response, NextFunction } from 'express';
+import UserService from '../services/UserService.js';
+import ApiResponse from '../utils/ApiResponse.js';
+
+class UserController {
+  /**
+   * Get paginated list of users.
+   */
+  public async index(req: Request, res: Response, next: NextFunction) {
+    try {
+      const page = Number(req.query.page) || 1;
+      const limit = Number(req.query.limit) || 15;
+      const users = await UserService.getAllUsers(page, limit);
+      return ApiResponse.success(res, users, 'Users retrieved successfully');
+    } catch (error) {
+      next(error);
+    }
+  }
+
+  public async store(req: Request, res: Response, next: NextFunction) {
+    try {
+      const user = await UserService.createUser(req.body);
+      return ApiResponse.success(res, user, 'User created successfully', 201);
+    } catch (error) {
+      next(error);
+    }
+  }
+
+  public async uploadAvatar(req: Request, res: Response, next: NextFunction) {
+    try {
+      if (!req.file) {
+        return ApiResponse.error(res, 'No file uploaded', 400);
+      }
+
+      // 1. Get the file path relative to your server
+      const filePath = `uploads/${req.file.filename}`;
+
+      // 2. Update the user in the DB (assuming you have req.user from AuthMiddleware)
+      await UserService.updateAvatar(req.user.id, filePath);
+
+      // 3. Return success
+      return ApiResponse.success(res, {
+        path: filePath,
+        url: `${req.protocol}://${req.get('host')}/${filePath}`
+      }, 'Avatar uploaded successfully');
+    } catch (error) {
+      next(error);
+    }
+  }
+}
+
+export default new UserController();

package/template/src/database/factories/Factory.ts

@@ -0,0 +1,33 @@
+import { Model, ModelStatic } from 'sequelize';
+
+export default abstract class Factory<T extends Model> {
+  protected abstract model: ModelStatic<T>;
+
+  // abstract method where you define the default state
+  protected abstract definition(): Record<string, any>;
+
+  // Make a single object (not saved to DB)
+  public make(overrides: Record<string, any> = {}): Record<string, any> {
+    return {
+      ...this.definition(),
+      ...overrides,
+    };
+  }
+
+  // Make multiple objects (not saved to DB)
+  public makeMany(count: number, overrides: Record<string, any> = {}): Record<string, any>[] {
+    return Array.from({ length: count }).map(() => this.make(overrides));
+  }
+
+  // Create single record in DB
+  public async create(overrides: Record<string, any> = {}): Promise<T> {
+    const data = this.make(overrides);
+    return await this.model.create(data as any);
+  }
+
+  // Create multiple records in DB
+  public async createMany(count: number, overrides: Record<string, any> = {}): Promise<T[]> {
+    const data = this.makeMany(count, overrides);
+    return await this.model.bulkCreate(data as any);
+  }
+}

package/template/src/database/factories/UserFactory.ts

@@ -0,0 +1,26 @@
+import { faker } from '@faker-js/faker';
+import User from '../../models/User.js'; // Import your Model
+import Factory from './Factory.js';
+
+class UserFactory extends Factory<User> {
+  protected model = User;
+
+  protected definition() {
+    return {
+      firstname: faker.person.firstName(),
+      lastname: faker.person.lastName(),
+      email: faker.internet.email(),
+      password: '$2b$10$YourHashedPasswordHere',
+      role: 'user',
+      avatar: null,
+    };
+  }
+
+  public admin() {
+    return {
+      role: 'admin',
+    };
+  }
+}
+
+export default new UserFactory();

package/template/src/database/migrations/20260205084944-create_user.js

@@ -0,0 +1,68 @@
+import { DataTypes } from 'sequelize';
+
+class CreateUserTable {
+  /**
+   * Run the migrations.
+   */
+  async up(queryInterface, Sequelize) {
+    await queryInterface.createTable('users', {
+      id: {
+        allowNull: false,
+        autoIncrement: true,
+        primaryKey: true,
+        type: DataTypes.BIGINT
+      },
+      firstname: {
+        type: DataTypes.STRING(50),
+        allowNull: false
+      },
+      lastname: {
+        type: DataTypes.STRING(50),
+        allowNull: false
+      },
+      email: {
+        type: DataTypes.STRING(100),
+        unique: true,
+        allowNull: false
+      },
+      password: {
+        type: DataTypes.STRING(255),
+        allowNull: false
+      },
+      role: {
+        type: DataTypes.STRING(20),
+        allowNull: false,
+        defaultValue: 'user'
+      },
+      avatar: {
+        type: DataTypes.TEXT,
+        allowNull: true,
+        defaultValue: null,
+      },
+      created_at: {
+        type: DataTypes.DATE,
+        allowNull: false,
+        defaultValue: Sequelize.literal('CURRENT_TIMESTAMP'),
+      },
+      updated_at: {
+        type: DataTypes.DATE,
+        allowNull: false,
+        defaultValue: Sequelize.literal('CURRENT_TIMESTAMP'),
+      },
+      deleted_at: {
+        type: DataTypes.DATE,
+        allowNull: true,
+        defaultValue: null,
+      },
+    });
+  }
+
+  /**
+   * Reverse the migrations.
+   */
+  async down(queryInterface, Sequelize) {
+    await queryInterface.dropTable('users');
+  }
+}
+
+export default new CreateUserTable();

package/template/src/database/seeders/DatabaseSeeder.js

@@ -0,0 +1,32 @@
+import UserFactory from '../factories/UserFactory.js';
+import Logger from '../../utils/Logger.js';
+
+class DatabaseSeeder {
+  /**
+   * Run the database seeds.
+   */
+  async run() {
+    Logger.info('Seeding database...');
+
+    try {
+      // 1. Create a specific Admin User
+      await UserFactory.create({
+        firstname: 'Admin',
+        lastname: 'Lumina',
+        email: 'admin@lumina.com',
+        password: "lumina123",
+        role: 'admin',
+      });
+
+      // 2. Create random users
+      await UserFactory.createMany(20);
+
+      Logger.info('Seeding complete!');
+    } catch (error) {
+      Logger.error('Seeding failed:', error);
+      throw error;
+    }
+  }
+}
+
+export default new DatabaseSeeder();