create-forgeapi 1.0.0

package/template/src/config/SwaggerConfig.ts

@@ -0,0 +1,147 @@
+import RouteConfig from "@config/RouteConfig";
+import {GetControllerMetadata} from "@shared/decorators/ApiDecorator";
+import SwaggerUtil from "@shared/utils/SwaggerUtil";
+import {IRouteDefinition} from "@shared/interfaces/RouteMetadataInterface";
+import {ErrorResponse, SuccessResponse} from "@shared/models/response/ApiResponse";
+import {z} from "zod";
+
+// Default responses yang otomatis dipakai jika @BodyResponse tidak didefinisikan
+const DEFAULT_RESPONSES: Record<string, { description: string; schema: any }> = {
+    '200': {
+        description: 'Success',
+        schema: SwaggerUtil.generateSchema(SuccessResponse(z.object({})))
+    },
+    '400': {
+        description: 'Bad Request',
+        schema: SwaggerUtil.generateSchema(ErrorResponse())
+    },
+    '401': {
+        description: 'Unauthorized',
+        schema: SwaggerUtil.generateSchema(ErrorResponse())
+    },
+    '500': {
+        description: 'Internal Server Error',
+        schema: SwaggerUtil.generateSchema(ErrorResponse())
+    }
+};
+
+
+export default class SwaggerConfig extends RouteConfig {
+
+    protected static MainObject = {
+        openapi: '3.0.0',
+        info: {
+            title: 'REST API Documentation',
+            version: '1.0.0',
+            description: 'Auto-generated API documentation with TypeScript decorators'
+        },
+        servers: [
+            {
+                url: 'http://localhost:3000',
+                description: 'Local development server'
+            }
+        ]
+        ,
+        components: {
+            securitySchemes: {
+                bearerAuth: {
+                    type: 'http',
+                    scheme: 'bearer',
+                    bearerFormat: 'JWT',
+                    description: 'Enter your JWT token'
+                }
+            }
+        }
+    };
+
+    static generate() {
+        const paths: any = {};
+
+        RouteConfig.getControllers().forEach(ControllerClass => {
+            const metadata = GetControllerMetadata(ControllerClass);
+
+            metadata.routes.forEach((route: IRouteDefinition) => {
+                const fullPath = `${metadata.basePath}${route.path}`
+                    .replace(/:/g, '{')
+                    .replace(/{(\w+)}/g, '{$1}');
+
+                if (!paths[fullPath]) {
+                    paths[fullPath] = {};
+                }
+
+                const swagger = route.swagger || {};
+                const requireAuth = route.authenticate?.authenticate === true; // true hanya jika explisit { authenticate: true }
+
+                const operation: any = {
+                    tags: metadata.swagger.tags || [],
+                    summary: swagger.summary || '',
+                    description: swagger.description || swagger.summary || '',
+                    parameters: [],
+                    responses: {},
+                    // Add security if authentication required
+                    ...(requireAuth && { security: [{ bearerAuth: [] }] })
+                };
+
+                if (swagger.paramsType) {
+                    operation.parameters.push(
+                        ...SwaggerUtil.generateParameters(swagger.paramsType, 'path')
+                    );
+                }
+
+                if (swagger.queryType) {
+                    operation.parameters.push(
+                        ...SwaggerUtil.generateParameters(swagger.queryType, 'query')
+                    );
+                }
+
+                if (swagger.bodyType) {
+                    operation.requestBody = {
+                        required: true,
+                        content: {
+                            'application/json': {
+                                schema: SwaggerUtil.generateSchema(swagger.bodyType)
+                            }
+                        }
+                    };
+                }
+
+                // Mulai dari default responses, lalu timpa dengan yang didefinisikan via @BodyResponse
+                const mergedResponses: Record<string, any> = {
+                    ...DEFAULT_RESPONSES,
+                    ...(requireAuth ? {} : { '401': undefined }) // hapus 401 default jika tidak butuh auth
+                };
+
+                if (swagger.responses) {
+                    for (const [statusCode, config] of Object.entries(swagger.responses)) {
+                        const responseConfig: any = config;
+                        mergedResponses[statusCode] = {
+                            description: responseConfig.description || 'Success',
+                            schema: responseConfig.type
+                                ? SwaggerUtil.generateSchema(responseConfig.type)
+                                : { type: 'object' }
+                        };
+                    }
+                }
+
+                for (const [statusCode, config] of Object.entries(mergedResponses)) {
+                    if (!config) continue; // skip yang di-undefined-kan
+                    operation.responses[statusCode] = {
+                        description: config.description,
+                        content: {
+                            'application/json': {
+                                schema: config.schema
+                            }
+                        }
+                    };
+                }
+
+                paths[fullPath][route.method] = operation;
+            });
+        });
+
+        return {
+            ...this.MainObject,
+            paths
+        };
+    }
+}

package/template/src/config/envConfig.ts

@@ -0,0 +1,5 @@
+import {config} from "dotenv";
+const env = process.env.NODE_ENV || 'dev'
+config({
+    path: `.env.${env}`
+})

package/template/src/core/Server.ts

@@ -0,0 +1,75 @@
+import "@config/envConfig"
+import cors from "cors";
+import express, {Router} from "express";
+import swaggerUi from 'swagger-ui-express';
+import expressRateLimit from "express-rate-limit";
+import {log, serverLogger} from "@config/LoggerConfig";
+import GlobalHandlerError from "@config/GlobalHandlerError";
+import UnauthorizedException from "@core/exceptions/UnauthorizedException";
+import DatabaseConnection from "@database/DatabaseConnection";
+import LookupConfig from "@config/LookupConfig";
+import {UserLookup} from "@database/entity/UserModel";
+import {ProfileLookup} from "@database/entity/ProfileModel";
+import SwaggerConfig from "@config/SwaggerConfig";
+import RouteConfig from "@config/RouteConfig";
+import UserController from "@api/controllers/UserController";
+
+DatabaseConnection().then(() => {
+    log.info("✅ Database connected successfully.");
+    LookupConfig.init([UserLookup, ProfileLookup])
+    log.info("🚀 Starting server...");
+    RouteConfig.register(UserController)
+    const app = express();
+
+    app.use(serverLogger({
+        enableFileLog: false,
+        enableConsoleLog: true
+    }))
+
+    app.use(express.json({
+        limit: '20mb'
+    }));
+
+    app.use(express.urlencoded({extended: true}));
+    app.use(cors({
+        origin: '*',
+        methods: ['GET', 'POST', 'DELETE'],
+        allowedHeaders: "*"
+    }));
+
+// Rate Limiter
+    const limiter = expressRateLimit({
+        windowMs: 15 * 60 * 1000, // 15 minutes
+        max: 100, // limit each IP to 100 requests per windowMs
+        standardHeaders: true,
+        legacyHeaders: false,
+        message: 'Too many requests from this IP, please try again later.'
+    });
+    app.use(limiter);
+
+    // Register routes
+    const router = RouteConfig.buildRoutes(Router());
+    app.use(router);
+
+    // Test error endpoint
+    app.get("/test-error", (req, res, next) => {
+        next(new UnauthorizedException("Test unauthorized error"));
+    });
+
+    const swaggerDoc = SwaggerConfig.generate();
+    app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(swaggerDoc));
+
+    // 404 handler harus sebelum error handler
+    app.use(GlobalHandlerError.notFound);
+
+    // Error handler harus terakhir (4 parameters)
+    app.use(GlobalHandlerError.error);
+
+    app.listen(process.env.SERVER_PORT || 3000, () => {
+        log.info('Server is running on port ' + (process.env.SERVER_PORT || 3000));
+        log.info("━".repeat(60));
+    })
+}).catch((err) => {
+    log.error("❌ Database connection failed:", err);
+    process.exit(1);
+})

package/template/src/core/exceptions/BadRequestException.ts

@@ -0,0 +1,7 @@
+import BaseResponseError from "@base/BaseResponseError";
+
+export default class BadRequestException extends BaseResponseError {
+    constructor(message: string = 'Bad request', errors?: Record<string, unknown>[]) {
+        super(400, message, errors);
+    }
+}

package/template/src/core/exceptions/ForbiddenException.ts

@@ -0,0 +1,7 @@
+import BaseResponseError from "@base/BaseResponseError";
+
+export default class ForbiddenException extends BaseResponseError {
+    constructor(message: string = "You don't have permission to access this resource") {
+        super(403, message);
+    }
+}

package/template/src/core/exceptions/NotFoundException.ts

@@ -0,0 +1,7 @@
+import BaseResponseError from "@base/BaseResponseError";
+
+export default class NotFoundException extends BaseResponseError {
+    constructor(message: string = 'Resource not found') {
+        super(404, message);
+    }
+}

package/template/src/core/exceptions/UnauthorizedException.ts

@@ -0,0 +1,7 @@
+import BaseResponseError from "@base/BaseResponseError";
+
+export default class UnauthorizedException extends BaseResponseError {
+    constructor(message: string = 'Authentication required') {
+        super(401, message);
+    }
+}

package/template/src/core/repositories/UserRepository.ts

@@ -0,0 +1,53 @@
+import BaseRepository from "@base/BaseRepository";
+import {IUser, IUserCreate, IUserProfileCreate} from "@shared/interfaces/UserInterface";
+import UserEntity from "@database/entity/UserModel";
+import ProfileEntity from "@database/entity/ProfileModel";
+import {dbCreateSeason} from "@shared/utils/DatabaseUtil";
+
+export default class UserRepository extends BaseRepository<IUser>{
+    constructor() {
+        super(UserEntity);
+    }
+
+    async createWithProfile(
+        userData: IUserCreate,
+        profileData: IUserProfileCreate,
+        idUser?: ObjectId
+    ) {
+        const session = await dbCreateSeason();
+        session.startTransaction();
+        try {
+            // Create user
+            const user = new this.model({
+                ...userData,
+                createdBy: idUser,
+                modifiedBy: idUser
+            })
+            await user.save({ session });
+
+            // Create profile linked to the user
+            const profile = new ProfileEntity({
+                ...profileData,
+                idUser,
+                createdBy: idUser,
+                modifiedBy: idUser
+            })
+            await profile.save({ session });
+
+            // Link profile to user
+            user.idProfile = profile._id;
+            await user.save({ session });
+
+            // Commit transaction
+            await session.commitTransaction();
+
+            // Return the created user with profile populated
+            return user;
+        } catch (error) {
+            await session.abortTransaction();
+            throw new Error("Internal Server Error");
+        } finally {
+            await session.endSession();
+        }
+    }
+}

package/template/src/database/DatabaseConnection.ts

@@ -0,0 +1,11 @@
+import mongoose from "mongoose";
+import {log} from "@config/LoggerConfig";
+
+export default async () => {
+    log.info("━".repeat(60));
+    log.info("🔄️Connecting to MongoDB");
+    await mongoose.connect(process.env.MONGO_DB_URL || "http://localhost:27017/local",{
+        user: process.env.MONGO_DB_USER,
+        pass: process.env.MONGO_DB_PASSWORD
+    });
+}

package/template/src/database/builder/CustomBuilder.ts

@@ -0,0 +1,177 @@
+import SearchCriteria from "@database/builder/SearchCriteria";
+import MultipleSearchCriteria from "@database/builder/MultipleSearchCriteria";
+import MetaDataConfig from "@config/MetaDataConfig";
+import LookupConfig from "@config/LookupConfig";
+
+
+export default class CustomBuilder<T> {
+    private criteria: Array<SearchCriteria | MultipleSearchCriteria> = [];
+    private requiredLookups: Set<string> = new Set();
+    private entityClass?: any;
+
+    /**
+     * @param entityClass - Optional Entity class to auto-include all @Lookup decorators
+     */
+    constructor(entityClass?: any) {
+        if (entityClass) {
+            this.entityClass = entityClass;
+            this.withLookupsFrom(entityClass);
+        }
+    }
+
+    /**
+     * Auto-include all lookups defined in Entity class via @Lookup decorator
+     * @param entityClass - The Entity class (e.g., UserEntity)
+     */
+    withLookupsFrom(entityClass: any): CustomBuilder<T> {
+        // Use originalClassName from @Entity decorator, fallback to name
+        const className = entityClass.originalClassName || entityClass.name;
+        const lookupKeys = MetaDataConfig.lookupGetKeys(className);
+        lookupKeys.forEach(key => this.requiredLookups.add(key));
+        return this;
+    }
+
+    with(criterion: SearchCriteria | MultipleSearchCriteria): CustomBuilder<T> {
+        this.criteria.push(criterion);
+
+        if (criterion instanceof SearchCriteria && criterion.isLookupOperation()) {
+            const lookupInfo = criterion.getLookupInfo();
+            if (lookupInfo) {
+                this.requiredLookups.add(lookupInfo.prefix);
+            }
+        } else if (criterion instanceof MultipleSearchCriteria) {
+            criterion.criteriaList.forEach(c => {
+                if (c.isLookupOperation()) {
+                    const lookupInfo = c.getLookupInfo();
+                    if (lookupInfo) {
+                        this.requiredLookups.add(lookupInfo.prefix);
+                    }
+                }
+            });
+        }
+
+        return this;
+    }
+
+    /**
+     * Explicitly add a lookup to join related collection
+     * @param lookupName - The registered lookup name (e.g., 'profile', 'user')
+     */
+    withLookup(lookupName: string): CustomBuilder<T> {
+        this.requiredLookups.add(lookupName);
+        return this;
+    }
+
+    build(): any {
+        if (this.criteria.length === 0) {
+            return {};
+        }
+
+        if (this.criteria.length === 1) {
+            return this.criteria[0].toMongoQuery();
+        }
+
+        const queries = this.criteria.map(c => c.toMongoQuery());
+        return { $and: queries };
+    }
+
+    buildAggregation(): any[] {
+        const pipeline: any[] = [];
+
+        this.requiredLookups.forEach(prefix => {
+            const config = LookupConfig.get(prefix);
+            if (config) {
+                pipeline.push({
+                    $lookup: {
+                        from: config.from,
+                        localField: config.localField,
+                        foreignField: config.foreignField,
+                        as: config.as
+                    }
+                });
+
+                if (config.unwind) {
+                    pipeline.push({
+                        $unwind: {
+                            path: `$${config.as}`,
+                            preserveNullAndEmptyArrays: true
+                        }
+                    });
+                }
+
+                // Auto-apply virtual fields for the looked-up entity
+                this.applyVirtualFields(pipeline, prefix, config.from);
+            }
+        });
+
+        if (this.criteria.length > 0) {
+            pipeline.push({
+                $match: this.build()
+            });
+        }
+
+        return pipeline;
+    }
+
+    /**
+     * Apply virtual/computed fields from @Virtual decorators to aggregation pipeline
+     */
+    private applyVirtualFields(pipeline: any[], lookupPrefix: string, collectionName: string): void {
+        // Map collection names to entity class names
+        const collectionToEntity: Record<string, string> = {
+            'profiles': 'ProfileEntity',
+            'users': 'UserEntity'
+        };
+
+        const entityName = collectionToEntity[collectionName];
+        if (!entityName) return;
+
+        const virtualFields = MetaDataConfig.virtualGetFields(entityName);
+        if (virtualFields.length === 0) return;
+
+        const addFieldsStage: any = { $addFields: {} };
+
+        virtualFields.forEach(virtual => {
+            const fieldPath = `${lookupPrefix}.${virtual.field}`;
+            // Replace field references in expression to include lookup prefix
+            addFieldsStage.$addFields[fieldPath] = this.prefixFieldPaths(virtual.aggregationExpression, lookupPrefix);
+        });
+
+        pipeline.push(addFieldsStage);
+    }
+
+    /**
+     * Prefix field paths in aggregation expression with lookup prefix
+     */
+    private prefixFieldPaths(expression: any, prefix: string): any {
+        if (typeof expression === 'string' && expression.startsWith('$')) {
+            // Replace $fieldName with $prefix.fieldName
+            const fieldName = expression.substring(1);
+            return `$${prefix}.${fieldName}`;
+        }
+
+        if (Array.isArray(expression)) {
+            return expression.map(item => this.prefixFieldPaths(item, prefix));
+        }
+
+        if (typeof expression === 'object' && expression !== null) {
+            const result: any = {};
+            for (const [key, value] of Object.entries(expression)) {
+                result[key] = this.prefixFieldPaths(value, prefix);
+            }
+            return result;
+        }
+
+        return expression;
+    }
+
+    hasLookups(): boolean {
+        return this.requiredLookups.size > 0;
+    }
+
+    clear(): CustomBuilder<T> {
+        this.criteria = [];
+        this.requiredLookups.clear();
+        return this;
+    }
+}

package/template/src/database/builder/CustomFilter.ts

@@ -0,0 +1,12 @@
+export default class CustomFilter {
+    static readonly OPERATION_EQUAL = 'eq';
+    static readonly OPERATION_NOT_EQUAL = 'ne';
+    static readonly OPERATION_LIKE = 'like';
+    static readonly OPERATION_GREATER_THAN = 'gt';
+    static readonly OPERATION_LESS_THAN = 'lt';
+    static readonly OPERATION_GREATER_THAN_EQUAL = 'gte';
+    static readonly OPERATION_LESS_THAN_EQUAL = 'lte';
+    static readonly OPERATION_IN = 'in';
+    static readonly OPERATION_LOOKUP_EQUAL = 'lookup_eq';
+    static readonly OPERATION_LOOKUP_LIKE = 'lookup_like';
+}

package/template/src/database/builder/MultipleSearchCriteria.ts

@@ -0,0 +1,25 @@
+import SearchCriteria from "@database/builder/SearchCriteria";
+
+export default class MultipleSearchCriteria {
+    constructor(
+        public logicalOperation: string,
+        public criteriaList: SearchCriteria[]
+    ) {}
+
+    static of(
+        logicalOperation: string,
+        ...criteriaList: SearchCriteria[]
+    ): MultipleSearchCriteria {
+        return new MultipleSearchCriteria(logicalOperation, criteriaList);
+    }
+
+    toMongoQuery(): any {
+        const queries = this.criteriaList.map(c => c.toMongoQuery());
+
+        if (this.logicalOperation === SearchCriteria.OPERATION_OR) {
+            return { $or: queries };
+        } else {
+            return { $and: queries };
+        }
+    }
+}

package/template/src/database/builder/SearchCriteria.ts

@@ -0,0 +1,79 @@
+import CustomFilter from "@database/builder/CustomFilter";
+import LookupConfig from "@config/LookupConfig";
+
+export default class SearchCriteria {
+    static readonly OPERATION_AND = 'AND';
+    static readonly OPERATION_OR = 'OR';
+
+    constructor(
+        public key: string,
+        public operation: string,
+        public value: any
+    ) {}
+
+    static of(key: string, operation: string, value: any): SearchCriteria {
+        return new SearchCriteria(key, operation, value);
+    }
+
+    isLookupOperation(): boolean {
+        return this.operation === CustomFilter.OPERATION_LOOKUP_EQUAL ||
+            this.operation === CustomFilter.OPERATION_LOOKUP_LIKE;
+    }
+
+    getLookupInfo(): { prefix: string; config: LookupConfig; field: string } | null {
+        const lookupInfo = LookupConfig.getLookupForPath(this.key);
+        if (!lookupInfo) return null;
+
+        const { prefix, config } = lookupInfo;
+        const field = this.key.substring(prefix.length + 1);
+
+        return { prefix, config, field };
+    }
+
+    toMongoQuery(): any {
+        const operation = this.operation;
+
+        if (!this.isLookupOperation()) {
+            const fieldPath = this.key;
+
+            switch (operation) {
+                case CustomFilter.OPERATION_EQUAL:
+                    return { [fieldPath]: this.value };
+                case CustomFilter.OPERATION_NOT_EQUAL:
+                    return { [fieldPath]: { $ne: this.value } };
+                case CustomFilter.OPERATION_LIKE:
+                    return { [fieldPath]: { $regex: this.value, $options: 'i' } };
+                case CustomFilter.OPERATION_GREATER_THAN:
+                    return { [fieldPath]: { $gt: this.value } };
+                case CustomFilter.OPERATION_LESS_THAN:
+                    return { [fieldPath]: { $lt: this.value } };
+                case CustomFilter.OPERATION_GREATER_THAN_EQUAL:
+                    return { [fieldPath]: { $gte: this.value } };
+                case CustomFilter.OPERATION_LESS_THAN_EQUAL:
+                    return { [fieldPath]: { $lte: this.value } };
+                case CustomFilter.OPERATION_IN:
+                    return { [fieldPath]: { $in: this.value } };
+                default:
+                    return { [fieldPath]: this.value };
+            }
+        }
+
+        const lookupInfo = this.getLookupInfo();
+        if (!lookupInfo) {
+            throw new Error(`Lookup configuration not found for path: ${this.key}`);
+        }
+
+        const { prefix, field } = lookupInfo;
+        const matchField = `${prefix}.${field}`;
+
+        if (operation === CustomFilter.OPERATION_LOOKUP_EQUAL) {
+            return { [matchField]: this.value };
+        }
+
+        if (operation === CustomFilter.OPERATION_LOOKUP_LIKE) {
+            return { [matchField]: { $regex: this.value, $options: 'i' } };
+        }
+
+        return {};
+    }
+}

package/template/src/database/entity/ProfileModel.ts

@@ -0,0 +1,54 @@
+import {ComponentLookup, Lookup, Virtual} from "@shared/decorators/LookupDecorator";
+import {IUser, IUserProfile} from "@shared/interfaces/UserInterface";
+import {AgeVirtual, FullNameVirtual} from "@shared/helpers/VirtualHelper";
+import mongoose, {Schema} from "mongoose";
+import BaseSchema from "@base/BaseSchema";
+
+@ComponentLookup("profiles")
+export class ProfileLookup {
+    @Lookup({
+        from: 'users',
+        localField: 'idUser',
+        foreignField: '_id',
+        as: 'user',
+        unwind: true
+    })
+    user?: IUser;
+
+    @Virtual(
+        FullNameVirtual("fullName", "firstName", "lastName")
+    )
+    fullName?: string;
+
+    @Virtual(
+        AgeVirtual("age", "dateOfBirth")
+    )
+    age?: number;
+}
+
+const ProfileSchema = BaseSchema.create<IUserProfile>({
+    userId: {
+        type: Schema.Types.ObjectId,
+        ref: 'users',
+        required: true,
+        unique: true
+    },
+    firstName: {
+        type: String,
+        required: true },
+    lastName: {
+        type: String,
+        required: true
+    },
+    phone: {
+        type: String
+    },
+    address: {
+        type: String
+    },
+    dateOfBirth: {
+        type: Number
+    } // Epoch timestamp
+});
+BaseSchema.addSoftDelete(ProfileSchema);
+export default mongoose.model<IUserProfile>("profile", ProfileSchema);