create-forgeapi 1.0.0

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

@@ -0,0 +1,46 @@
+import {ComponentLookup, Lookup} from "@shared/decorators/LookupDecorator";
+import {IUser, IUserProfile} from "@shared/interfaces/UserInterface";
+import BaseSchema from "@base/BaseSchema";
+import mongoose, {Schema} from "mongoose";
+
+@ComponentLookup("users")
+export class UserLookup {
+    @Lookup({
+        from: 'profiles',
+        localField: 'idProfile',
+        foreignField: '_id',
+        as: 'profile',
+        unwind: true
+    })
+    profile?: IUserProfile;
+}
+
+const UserSchema = BaseSchema.create<IUser>({
+    username: {
+        type: String,
+        required: true,
+        unique: true
+    },
+    email: {
+        type: String,
+        required: true,
+        unique: true
+    },
+    password: {
+        type: String,
+        required: true
+    },
+    profileId: {
+        type: Schema.Types.ObjectId,
+        ref: 'profiles',
+        unique: true,
+        sparse: true
+    },
+    status: {
+        type: String,
+        enum: ['active', 'inactive', 'pending'],
+        default: 'active'
+    }
+});
+BaseSchema.addSoftDelete(UserSchema);
+export default mongoose.model<IUser>("user", UserSchema);

package/template/src/shared/decorators/ApiDecorator.ts

@@ -0,0 +1,88 @@
+import 'reflect-metadata';
+import {CONTROLLER_METADATA, ROUTE_METADATA, SWAGGER_METADATA, PENDING_SWAGGER_METADATA} from "@shared/utils/DecoratorUtil";
+import {IRouteDefinition} from "@shared/interfaces/RouteMetadataInterface";
+import {ZodType} from "zod";
+
+function mergeSwagger(target: any, propertyKey: string | symbol, patch: Record<string, any>) {
+    const routes: IRouteDefinition[] = Reflect.getMetadata(ROUTE_METADATA, target.constructor) || [];
+    const route = routes.find(r => r.handlerName === propertyKey);
+    if (route) {
+        route.swagger = { ...route.swagger, ...patch };
+        Reflect.defineMetadata(ROUTE_METADATA, routes, target.constructor);
+    } else {
+        // Route belum terdaftar (decorator dieksekusi bottom-up), simpan sementara
+        const pending: Record<string, any> = Reflect.getMetadata(PENDING_SWAGGER_METADATA, target.constructor) || {};
+        pending[propertyKey as string] = { ...(pending[propertyKey as string] || {}), ...patch };
+        Reflect.defineMetadata(PENDING_SWAGGER_METADATA, pending, target.constructor);
+    }
+}
+
+export function Controller(basePath: string = ''): ClassDecorator {
+    return (target: any) => {
+        Reflect.defineMetadata(CONTROLLER_METADATA, basePath, target);
+    };
+}
+
+export function SwaggerTag(...tags: string[]): ClassDecorator {
+    return (target: any) => {
+        const existing = Reflect.getMetadata(SWAGGER_METADATA, target) || {};
+        Reflect.defineMetadata(SWAGGER_METADATA, { ...existing, tags }, target);
+    };
+}
+
+export function GetControllerMetadata(target: any) {
+    return {
+        basePath: Reflect.getMetadata(CONTROLLER_METADATA, target) || '',
+        routes: Reflect.getMetadata(ROUTE_METADATA, target) || [],
+        swagger: Reflect.getMetadata(SWAGGER_METADATA, target) || {},
+    };
+}
+
+export function ApiOperation(summary: string, description?: string): MethodDecorator {
+    return (target: any, propertyKey, descriptor) => {
+        mergeSwagger(target, propertyKey, { summary, description: description || summary });
+        return descriptor;
+    };
+}
+
+export function RequiredBody(type: ZodType): MethodDecorator {
+    return (target: any, propertyKey, descriptor) => {
+        mergeSwagger(target, propertyKey, { bodyType: type });
+        return descriptor;
+    };
+}
+
+export function BodyResponse(statusCode: number, type: ZodType, description?: string): MethodDecorator {
+    return (target: any, propertyKey, descriptor) => {
+        const routes: IRouteDefinition[] = Reflect.getMetadata(ROUTE_METADATA, target.constructor) || [];
+        const route = routes.find(r => r.handlerName === propertyKey);
+        const responsesPatch = { [statusCode]: { description: description || 'Success', type } };
+        if (route) {
+            if (!route.swagger) route.swagger = {};
+            if (!route.swagger.responses) route.swagger.responses = {};
+            route.swagger.responses[statusCode] = responsesPatch[statusCode];
+            Reflect.defineMetadata(ROUTE_METADATA, routes, target.constructor);
+        } else {
+            const pending: Record<string, any> = Reflect.getMetadata(PENDING_SWAGGER_METADATA, target.constructor) || {};
+            if (!pending[propertyKey as string]) pending[propertyKey as string] = {};
+            if (!pending[propertyKey as string].responses) pending[propertyKey as string].responses = {};
+            pending[propertyKey as string].responses[statusCode] = responsesPatch[statusCode];
+            Reflect.defineMetadata(PENDING_SWAGGER_METADATA, pending, target.constructor);
+        }
+        return descriptor;
+    };
+}
+
+export function RequiredParam(type: ZodType): MethodDecorator {
+    return (target: any, propertyKey, descriptor) => {
+        mergeSwagger(target, propertyKey, { paramsType: type });
+        return descriptor;
+    };
+}
+
+export function RequiredQuery(type: ZodType): MethodDecorator {
+    return (target: any, propertyKey, descriptor) => {
+        mergeSwagger(target, propertyKey, { queryType: type });
+        return descriptor;
+    };
+}

package/template/src/shared/decorators/LookupDecorator.ts

@@ -0,0 +1,51 @@
+import {LookupDecoratorOptions, VirtualFieldConfig} from "@shared/interfaces/DatabaseInterface";
+import LookupConfig from "@config/LookupConfig";
+import MetaDataConfig from "@config/MetaDataConfig";
+import {log} from "@config/LoggerConfig";
+
+export function Virtual(config: VirtualFieldConfig) {
+    return function (target: any, propertyKey: string) {
+        const className = target.constructor.name;
+        if (!MetaDataConfig.virtualMetadata.has(className)) {
+            MetaDataConfig.virtualMetadata.set(className, new Map());
+        }
+        MetaDataConfig.virtualMetadata.get(className)!.set(propertyKey, config);
+    };
+}
+
+export function Lookup(options: LookupDecoratorOptions) {
+    return function (target: any, propertyKey: string) {
+        const className = target.constructor.name;
+        if (!MetaDataConfig.lookupMetadata.has(className)) {
+            MetaDataConfig.lookupMetadata.set(className, new Map());
+        }
+        MetaDataConfig.lookupMetadata.get(className)!.set(propertyKey, options);
+    };
+}
+
+export function ComponentLookup(collectionName: string) {
+    return function <T extends { new (...args: any[]): {} }>(constructor: T) {
+        const originalName = constructor.name;
+
+        return class extends constructor {
+            static collectionName = collectionName;
+            static originalClassName = originalName;
+
+            static registerLookups() {
+                const lookups = MetaDataConfig.lookupGetMetadata(originalName);
+
+                lookups.forEach((options, propertyKey) => {
+                    LookupConfig.register(propertyKey, {
+                        from: options.from,
+                        localField: options.localField,
+                        foreignField: options.foreignField,
+                        as: options.as,
+                        unwind: options.unwind ?? true
+                    });
+
+                    log.info(`✅ Registered lookup [${originalName}]: ${propertyKey} -> ${options.from}`);
+                });
+            }
+        };
+    };
+}

package/template/src/shared/decorators/MethodeDecorator.ts

@@ -0,0 +1,38 @@
+import {IRouteDefinition} from "@shared/interfaces/RouteMetadataInterface";
+import {ROUTE_METADATA, PENDING_SWAGGER_METADATA} from "@shared/utils/DecoratorUtil";
+import {MiddlewareAccess} from "@shared/interfaces/MiddlewareInterface";
+
+const createMappingDecorator = (method: IRouteDefinition['method']) => {
+    return (path: string = '', authenticate?: MiddlewareAccess): MethodDecorator => {
+        return (target: any, propertyKey, descriptor) => {
+            const routes: IRouteDefinition[] = Reflect.getMetadata(ROUTE_METADATA, target.constructor) || [];
+
+            // Ambil pending swagger yang sudah disimpan oleh decorator di bawah
+            const pending: Record<string, any> = Reflect.getMetadata(PENDING_SWAGGER_METADATA, target.constructor) || {};
+            const pendingSwagger = pending[propertyKey as string] || undefined;
+
+            routes.push({
+                method,
+                path,
+                handlerName: propertyKey,
+                authenticate,
+                ...(pendingSwagger ? { swagger: pendingSwagger } : {})
+            });
+
+            // Hapus pending swagger yang sudah di-merge
+            if (pendingSwagger) {
+                delete pending[propertyKey as string];
+                Reflect.defineMetadata(PENDING_SWAGGER_METADATA, pending, target.constructor);
+            }
+
+            Reflect.defineMetadata(ROUTE_METADATA, routes, target.constructor);
+            return descriptor;
+        };
+    };
+}
+
+export const GetMapping = createMappingDecorator('get');
+export const PostMapping = createMappingDecorator('post');
+export const PutMapping = createMappingDecorator('put');
+export const DeleteMapping = createMappingDecorator('delete');
+export const PatchMapping = createMappingDecorator('patch');

package/template/src/shared/helpers/VirtualHelper.ts

@@ -0,0 +1,53 @@
+import {VirtualFieldConfig} from "@shared/interfaces/DatabaseInterface";
+
+/**
+ * Helper to create fullName virtual from firstName and lastName
+ * @param fieldName - Name of the virtual field (e.g., 'fullName', 'displayName')
+ * @param firstNameField - Field path for first name
+ * @param lastNameField - Field path for last name
+ */
+export function FullNameVirtual(fieldName: string, firstNameField: string, lastNameField: string): VirtualFieldConfig {
+    return {
+        field: fieldName,
+        aggregationExpression: {
+            $concat: [`$${firstNameField}`, ' ', `$${lastNameField}`]
+        }
+    };
+}
+
+/**
+ * Helper to create age virtual from dateOfBirth
+ * @param fieldName - Name of the virtual field (e.g., 'age', 'yearsOld')
+ * @param dateOfBirthField - Field path for date of birth (epoch timestamp)
+ */
+export function AgeVirtual(fieldName: string, dateOfBirthField: string): VirtualFieldConfig {
+    return {
+        field: fieldName,
+        aggregationExpression: {
+            $cond: {
+                if: { $ne: [`$${dateOfBirthField}`, null] },
+                then: {
+                    $floor: {
+                        $divide: [
+                            { $subtract: [new Date().getTime(), `$${dateOfBirthField}`] },
+                            31536000000 // milliseconds in a year
+                        ]
+                    }
+                },
+                else: null
+            }
+        }
+    };
+}
+
+/**
+ * Generic helper to create custom virtual field with any aggregation expression
+ * @param fieldName - Name of the virtual field
+ * @param aggregationExpression - MongoDB aggregation expression
+ */
+export function CustomVirtual(fieldName: string, aggregationExpression: any): VirtualFieldConfig {
+    return {
+        field: fieldName,
+        aggregationExpression
+    };
+}

package/template/src/shared/interfaces/BaseInterface.ts

@@ -0,0 +1,14 @@
+export interface BaseEntity {
+    _id: ObjectId;
+    createdAt?: number;           // Epoch timestamp (milliseconds)
+    updatedAt?: number;           // Epoch timestamp (milliseconds)
+    createdBy?: ObjectId;              // User ObjectId
+    modifiedBy?: ObjectId;             // User ObjectId
+    deletedAt?: number;           // Epoch timestamp (milliseconds)
+    deletedBy?: ObjectId;           // User ObjectId
+
+    // Virtual fields untuk lookup
+    creatorUser?: any;
+    modifierUser?: any;
+    deleterUser?: any;
+}

package/template/src/shared/interfaces/DatabaseInterface.ts

@@ -0,0 +1,41 @@
+
+export interface LookupDecoratorOptions {
+    from: string;
+    localField: string;
+    foreignField: string;
+    as: string;
+    unwind?: boolean;
+}
+
+export interface ILookupConfig {
+    from: string;
+    localField: string;
+    foreignField: string;
+    as: string;
+    unwind?: boolean;
+}
+
+export interface VirtualFieldConfig {
+    field: string;
+    aggregationExpression: any;
+}
+
+export interface Pageable {
+    page: number;
+    size: number;
+    sort?: { [key: string]: 1 | -1 };
+}
+
+export interface PageResult<T> {
+    content: T[];
+    totalElements: number;
+    totalPages: number;
+    currentPage: number;
+    size: number;
+    hasNext: boolean;
+    hasPrevious: boolean;
+}
+
+export interface SortOption {
+    [key: string]: 1 | -1;
+}

package/template/src/shared/interfaces/HttpInterface.ts

@@ -0,0 +1,37 @@
+export interface SuccessResponseData<T = any> {
+    success: true;
+    message: string;
+    data?: T;
+}
+
+export interface ErrorResponseData<T = any> {
+    success: false;
+    message: string;
+    error?: string;
+    errors?: Record<string, unknown>[];
+    stack?: string;
+}
+
+export interface NotFoundResponse {
+    success: boolean;
+    message: string;
+    path: string;
+    method: string;
+    timestamp: string;
+    suggestion?: string;
+}
+
+export interface ErrorContext {
+    endpoint?: string;
+    method?: string;
+    userId?: string;
+    body?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    params?: Record<string, unknown>;
+}
+
+export interface ErrorLogData {
+    timestamp: string;
+    error: Error;
+    context?: ErrorContext;
+}

package/template/src/shared/interfaces/LoggerOptionsInterface.ts

@@ -0,0 +1,16 @@
+export interface LoggerOptions {
+    enableFileLog?: boolean;
+    enableConsoleLog?: boolean;
+    logFileName?: string;
+    folderPath?: string;
+}
+
+export interface LogData {
+    timestamp: string;
+    method: string;
+    url: string;
+    status: number;
+    duration: string;
+    ip: string;
+    userAgent: string;
+}

package/template/src/shared/interfaces/MiddlewareInterface.ts

@@ -0,0 +1,14 @@
+import {
+    MiddlewareCodeAccess,
+    MiddlewareCodeMenu,
+    MiddlewareTypeAccess
+} from "@shared/models/enum/MiddlewareEnum";
+
+export * from "@shared/models/enum/MiddlewareEnum";
+
+export interface MiddlewareAccess {
+    authenticate?: boolean;
+    typeAccess?: MiddlewareTypeAccess;
+    codeAccess?: MiddlewareCodeAccess;
+    codeMenu?: MiddlewareCodeMenu;
+}

package/template/src/shared/interfaces/RouteMetadataInterface.ts

@@ -0,0 +1,10 @@
+import {ISwaggerMetadata} from "@shared/interfaces/SwaggerMetadataInterface";
+import {MiddlewareAccess} from "@shared/interfaces/MiddlewareInterface";
+
+export interface IRouteDefinition {
+    path: string;
+    method: 'get' | 'post' | 'put' | 'delete' | 'patch';
+    handlerName: string | symbol;
+    swagger?: ISwaggerMetadata;
+    authenticate?: MiddlewareAccess;
+}

package/template/src/shared/interfaces/SoftDeleteInterface.ts

@@ -0,0 +1,8 @@
+
+export interface SoftDeleteDocument {
+    deletedAt?: number;
+    deletedBy?: ObjectId;
+    delete(deletedBy: ObjectId): Promise<this>;
+    restore(): Promise<this>;
+    isDeleted(): boolean;
+}

package/template/src/shared/interfaces/SwaggerMetadataInterface.ts

@@ -0,0 +1,12 @@
+import {ZodType} from "zod";
+
+export interface ISwaggerMetadata {
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    responses?: Record<string, any>;
+    bodyType?: ZodType;
+    responseType?: ZodType;
+    paramsType?: ZodType;
+    queryType?: ZodType;
+}

package/template/src/shared/interfaces/UserInterface.ts

@@ -0,0 +1,37 @@
+import {Document} from "mongoose";
+import {BaseEntity} from "@shared/interfaces/BaseInterface";
+import {SoftDeleteDocument} from "@shared/interfaces/SoftDeleteInterface";
+
+export interface IUser extends Document, BaseEntity, SoftDeleteDocument {
+    username: string;
+    email: string;
+    password: string;
+    idProfile?: ObjectId;
+    status?: string;
+    profile?: IUserProfile;
+}
+
+export interface IUserProfile extends Document, BaseEntity, SoftDeleteDocument {
+    idUser: ObjectId;
+    firstName: string;
+    lastName: string;
+    phone?: string;
+    address?: string;
+    dateOfBirth?: number; // Epoch
+    user?: any;
+}
+
+export interface IUserCreate {
+    username: string;
+    email: string;
+    password: string;
+    status?: string;
+}
+
+export interface IUserProfileCreate {
+    firstName: string;
+    lastName: string;
+    phone?: string;
+    address?: string;
+    dateOfBirth?: number; // Epoch
+}

package/template/src/shared/interfaces/user/UserCreateInterface.ts

@@ -0,0 +1,4 @@
+import {z} from "zod";
+import {UserCreateRequest} from "@shared/models/request/UserCreateRequest";
+
+export type UserCreateInterface  = z.infer<typeof UserCreateRequest>;

package/template/src/shared/models/enum/MiddlewareEnum.ts

@@ -0,0 +1,19 @@
+
+export enum MiddlewareTypeAccess {
+    READ = "read",
+    WRITE = "write",
+    DELETE = "delete",
+    UPDATE = "update",
+}
+
+export enum MiddlewareCodeMenu {
+    MENU_USER = 2100,
+    SUB_MENU_USER = 2101,
+}
+
+export enum MiddlewareCodeAccess {
+    TAMBAH,
+    LIHAT,
+    UBAH,
+    HAPUS,
+}

package/template/src/shared/models/request/UserCreateRequest.ts

@@ -0,0 +1,12 @@
+import {z} from "zod";
+
+export const UserCreateRequest = z.object({
+    username: z.string().min(4, "username minimal 3 karakter").max(30, "username maksimal 30 karakter"),
+    email: z.string().email("Invalid email address"),
+    password: z.string().min(6, "password minimal 6 karakter").max(100, "password maksimal 100 karakter"),
+    firstName: z.string().min(3, "firstName minimal 6 karakter").max(50, "firstName minimal 50 karakter"),
+    lastName: z.string().min(3, "lastName minimal 6 karakter").max(50, "lastName minimal 50 karakter"),
+    phone: z.string().optional(),
+    address: z.string().optional(),
+    dateOfBirth: z.number().optional() // Epoch timestamp
+});

package/template/src/shared/models/response/ApiResponse.ts

@@ -0,0 +1,27 @@
+import {z, ZodType} from "zod";
+
+/**
+ * Wrap ZodType menjadi format response sukses:
+ * { success: true, message: string, data: <your schema> }
+ */
+export function SuccessResponse<T extends ZodType>(dataSchema: T) {
+    return z.object({
+        success: z.literal(true),
+        message: z.string(),
+        data: dataSchema
+    });
+}
+
+/**
+ * Wrap ZodType menjadi format response error:
+ * { success: false, message: string, error?: string, errors?: [...] }
+ */
+export function ErrorResponse() {
+    return z.object({
+        success: z.literal(false),
+        message: z.string(),
+        error: z.string().optional(),
+        errors: z.array(z.record(z.string(), z.unknown())).optional()
+    });
+}
+

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

@@ -0,0 +1,14 @@
+import { Request } from 'express';
+import {MiddlewareAccess} from "@shared/interfaces/MiddlewareInterface";
+
+declare global {
+    namespace Express {
+        interface Request {
+            user?: any;
+            authenticate?: MiddlewareAccess;
+        }
+    }
+}
+
+export {};
+

package/template/src/shared/types/mongoose.d.ts

@@ -0,0 +1,7 @@
+import mongoose from 'mongoose';
+
+declare global {
+    type ObjectId = mongoose.Types.ObjectId;
+}
+
+export {};

package/template/src/shared/utils/ColorUtil.ts

@@ -0,0 +1,17 @@
+import {StatusColor, StatusEmoji} from "@shared/models/enum/ColorEnum";
+
+export function getStatusColor(status: number): StatusColor {
+    if (status >= 500) return StatusColor.SERVER_ERR;
+    if (status >= 400) return StatusColor.CLIENT_ERR;
+    if (status >= 300) return StatusColor.REDIRECT;
+    if (status >= 200) return StatusColor.SUCCESS;
+    return StatusColor.DEFAULT;
+}
+
+export function getStatusEmoji(status: number): StatusEmoji {
+    if (status >= 500) return StatusEmoji.SERVER_ERR;
+    if (status >= 400) return StatusEmoji.CLIENT_ERR;
+    if (status >= 300) return StatusEmoji.REDIRECT;
+    if (status >= 200) return StatusEmoji.SUCCESS;
+    return StatusEmoji.DEFAULT;
+}

package/template/src/shared/utils/DatabaseUtil.ts

@@ -0,0 +1,3 @@
+import mongoose from "mongoose";
+
+export const dbCreateSeason = async () => await mongoose.startSession()

package/template/src/shared/utils/DecoratorUtil.ts

@@ -0,0 +1,4 @@
+export const CONTROLLER_METADATA = Symbol('controller');
+export const ROUTE_METADATA = Symbol('route');
+export const SWAGGER_METADATA = Symbol('swagger');
+export const PENDING_SWAGGER_METADATA = Symbol('pending_swagger');

package/template/src/shared/utils/FolderUtil.ts

@@ -0,0 +1,15 @@
+import path from "node:path";
+import * as fs from "node:fs";
+
+export default class FolderUtil {
+    static mkdir(folderPath: string): string {
+        if(!folderPath)
+            throw new Error("Folder path is required");
+        const basePath = path.join(__dirname, "../../../" + folderPath);
+        if (!fs.existsSync(basePath)) {
+            fs.mkdirSync(basePath, { recursive: true });
+            return folderPath;
+        }
+        return folderPath;
+    }
+}

package/template/src/shared/utils/JwtUtil.ts

@@ -0,0 +1,21 @@
+import type {StringValue} from "ms";
+import jwt, {JwtPayload, SignOptions} from "jsonwebtoken";
+import ForbiddenException from "@core/exceptions/ForbiddenException";
+
+export default class JwtUtil {
+    public static async validateToken(token: string): Promise<string | JwtPayload> {
+        try {
+            return jwt.verify(token, process.env.JWT_SECRET_KEY as string);
+        } catch (err) {
+            throw new ForbiddenException("Invalid or expired token");
+        }
+    }
+
+    public static async createToken(payload: object, expiresIn: StringValue | number = '1h'): Promise<string> {
+        const options: SignOptions = {
+            algorithm: "HS256",
+            expiresIn
+        }
+        return jwt.sign(payload, process.env.JWT_SECRET_KEY as string, options);
+    }
+}