create-tigra 1.1.0 → 2.0.1

package/template/server/src/server.ts

@@ -1,139 +1,58 @@
-/**
- * Server Entry Point
- * 
- * Responsible for initializing the application, starting the HTTP server,
- * and handling graceful shutdowns of all core dependencies.
- * 
- * @see /mnt/project/02-general-rules.md
- */
-
-import 'dotenv/config';
-import buildApp from './app.js';
-import { env } from './config/env.js';
-import logger from './libs/logger.js';
-import { prisma } from './libs/db.js';
-import { redis } from './libs/redis.js';
-import { fileQueue } from './libs/queue.js';
-
-/**
- * Start the Fastify server
- */
-// Track shutdown state to prevent race conditions
-let isShuttingDown = false;
-
-async function startServer() {
-    try {
-        const app = await buildApp();
-
-        // Verify Database Connection
-        try {
-            await prisma.$connect();
-            logger.info('Database connected successfully');
-        } catch (dbError) {
-            logger.error({
-                error: dbError instanceof Error ? dbError.message : 'Unknown DB error'
-            }, 'Failed to connect to database');
-            logger.warn('Database connection closed. Running without database.');
-        }
-
-        // Start listening on configured port
-        await app.listen({
-            port: env.PORT,
-            host: '0.0.0.0', // Listen on all interfaces (required for Docker)
-        });
-
-        const serverUrl = `http://localhost:${env.PORT}`;
-
-        logger.info(`Server started in ${env.NODE_ENV} mode`);
-        logger.info(`API is listening at: ${serverUrl}${env.API_PREFIX}`);
-        logger.info(`Health check available at: ${serverUrl}/health`);
-
-        /**
-         * Graceful Shutdown Handler
-         * 
-         * Ensures all connections are closed properly before exiting.
-         */
-        const gracefulShutdown = async (signal: string) => {
-            if (isShuttingDown) return;
-            isShuttingDown = true;
-
-            // Use console.log for shutdown messages to ensure they are printed
-            // even if the async logger is terminated early.
-            console.log(`\nReceived ${signal}. Starting graceful shutdown...`);
-
-            try {
-                await app.close();
-                console.log('HTTP server closed');
-            } catch (err) {
-                console.error('Error closing HTTP server:', err);
-            }
-
-            try {
-                await prisma.$disconnect();
-                console.log('Database connection closed');
-            } catch (err) {
-                console.error('Error closing database connection:', err);
-            }
-
-            // Close Redis-dependent services first, then Redis itself
-            // fileQueue uses the shared redis connection, so close it before redis
-            try {
-                await fileQueue.close();
-                console.log('File queue connection closed');
-            } catch (err) {
-                // Ignore - queue may already be disconnected if Redis failed
-            }
-
-            // Close Redis connection - use disconnect() for immediate close
-            // quit() can hang or reject if connection is already closed by BullMQ
-            try {
-                // Check if Redis is still connected before attempting to close
-                if (redis.status === 'ready' || redis.status === 'connect') {
-                    await redis.quit();
-                    console.log('Redis connection closed');
-                } else {
-                    redis.disconnect();
-                    console.log('Redis connection closed (was not connected)');
-                }
-            } catch (err) {
-                // Force disconnect if quit fails
-                try { redis.disconnect(); } catch (e) { /* ignore */ }
-                console.log('Redis connection closed (forced)');
-            }
-
-            console.log('Graceful shutdown complete. Goodbye');
-
-            // Give a small grace period for any pending logs/events to flush
-            setTimeout(() => {
-                process.exit(0);
-            }, 500);
-        };
-
-        // Listen for termination signals
-        process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
-        process.on('SIGINT', () => gracefulShutdown('SIGINT'));
-
-    } catch (error) {
-        logger.fatal({
-            error: error instanceof Error ? error.message : 'Unknown error',
-            stack: error instanceof Error ? error.stack : undefined
-        }, 'Failed to start server');
-        process.exit(1);
-    }
-}
-
-// Global Rejection Handler for Uncaught Promises
-process.on('unhandledRejection', (reason, promise) => {
-    // During shutdown, BullMQ/ioredis may emit unhandled rejections
-    // as they try to perform operations on closed connections.
-    // These are expected and safe to ignore during graceful shutdown.
-    if (isShuttingDown) {
-        return;
-    }
-
-    logger.fatal({ promise, reason }, 'Unhandled Rejection at Promise');
-    process.exit(1);
-});
-
-// Run the server
-startServer();
+import { env } from '@config/env.js';
+import { logger } from '@libs/logger.js';
+import { testDatabaseConnection, disconnectPrisma } from '@libs/prisma.js';
+import { connectRedis, disconnectRedis } from '@libs/redis.js';
+import { buildApp } from './app.js';
+
+async function start(): Promise<void> {
+  let app: Awaited<ReturnType<typeof buildApp>> | null = null;
+  let isShuttingDown = false;
+
+  // Graceful shutdown
+  const shutdown = async (signal: string): Promise<void> => {
+    if (isShuttingDown) return; // Prevent multiple shutdown attempts
+    isShuttingDown = true;
+
+    logger.info(`[SERVER] Received ${signal} — shutting down gracefully`);
+    try {
+      if (app) {
+        await app.close();
+      }
+      await disconnectRedis();
+      await disconnectPrisma();
+      logger.info('[SERVER] Shutdown complete');
+      process.exit(0);
+    } catch (error) {
+      logger.error(error, '[SERVER] Error during shutdown');
+      process.exit(1);
+    }
+  };
+
+  // Register signal handlers early
+  process.on('SIGINT', () => shutdown('SIGINT'));
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+  process.on('uncaughtException', (error) => {
+    logger.fatal(error, '[SERVER] Uncaught exception');
+    shutdown('uncaughtException');
+  });
+  process.on('unhandledRejection', (reason) => {
+    logger.fatal(reason, '[SERVER] Unhandled rejection');
+    shutdown('unhandledRejection');
+  });
+
+  try {
+    // Test external connections (non-fatal)
+    await testDatabaseConnection();
+    await connectRedis();
+
+    app = await buildApp();
+
+    await app.listen({ port: env.PORT, host: env.HOST });
+    logger.info(`[SERVER] Started on http://${env.HOST}:${env.PORT} [${env.NODE_ENV}]`);
+  } catch (error) {
+    logger.fatal(error, '[SERVER] Failed to start');
+    await shutdown('startup-error');
+  }
+}
+
+start();

package/template/server/src/shared/errors/AppError.ts

@@ -0,0 +1,21 @@
+export class AppError extends Error {
+  public readonly isAppError = true;
+  public readonly code: string;
+  public readonly statusCode: number;
+
+  constructor(code: string, message: string, statusCode: number) {
+    super(message);
+    this.code = code;
+    this.statusCode = statusCode;
+    this.name = this.constructor.name;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+export function isAppError(error: unknown): error is AppError {
+  return (
+    error instanceof Error &&
+    'isAppError' in error &&
+    (error as AppError).isAppError === true
+  );
+}

package/template/server/src/shared/errors/errors.ts

@@ -0,0 +1,43 @@
+import { AppError } from './AppError.js';
+
+export class BadRequestError extends AppError {
+  constructor(message = 'Bad request', code = 'BAD_REQUEST') {
+    super(code, message, 400);
+  }
+}
+
+export class ValidationError extends AppError {
+  constructor(message = 'Validation failed', code = 'VALIDATION_FAILED') {
+    super(code, message, 422);
+  }
+}
+
+export class UnauthorizedError extends AppError {
+  constructor(message = 'Unauthorized', code = 'UNAUTHORIZED') {
+    super(code, message, 401);
+  }
+}
+
+export class ForbiddenError extends AppError {
+  constructor(message = 'Forbidden', code = 'FORBIDDEN') {
+    super(code, message, 403);
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(message = 'Resource not found', code = 'NOT_FOUND') {
+    super(code, message, 404);
+  }
+}
+
+export class ConflictError extends AppError {
+  constructor(message = 'Resource already exists', code = 'CONFLICT') {
+    super(code, message, 409);
+  }
+}
+
+export class InternalError extends AppError {
+  constructor(message = 'Internal server error', code = 'INTERNAL_ERROR') {
+    super(code, message, 500);
+  }
+}

package/template/server/src/shared/responses/paginatedResponse.ts

@@ -0,0 +1,38 @@
+export function paginatedResponse<T>(
+  message: string,
+  items: T[],
+  page: number,
+  limit: number,
+  totalItems: number,
+): {
+  success: true;
+  message: string;
+  data: {
+    items: T[];
+    pagination: {
+      page: number;
+      limit: number;
+      totalItems: number;
+      totalPages: number;
+      hasNextPage: boolean;
+      hasPreviousPage: boolean;
+    };
+  };
+} {
+  const totalPages = Math.ceil(totalItems / limit);
+  return {
+    success: true as const,
+    message,
+    data: {
+      items,
+      pagination: {
+        page,
+        limit,
+        totalItems,
+        totalPages,
+        hasNextPage: page < totalPages,
+        hasPreviousPage: page > 1,
+      },
+    },
+  };
+}

package/template/server/src/shared/responses/successResponse.ts

@@ -0,0 +1,17 @@
+export function successResponse<T>(message: string, data: T): {
+  success: true;
+  message: string;
+  data: T;
+} {
+  return { success: true as const, message, data };
+}
+
+export function errorResponse(code: string, message: string): {
+  success: false;
+  error: { code: string; message: string };
+} {
+  return {
+    success: false as const,
+    error: { code, message },
+  };
+}

package/template/server/src/shared/schemas/pagination.schema.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+
+export const PaginationSchema = z.object({
+  page: z.coerce.number().int().min(1).default(1),
+  limit: z.coerce.number().int().min(1).max(100).default(10),
+});
+
+export type PaginationInput = z.infer<typeof PaginationSchema>;
+
+export function calculateOffset(page: number, limit: number): number {
+  return (page - 1) * limit;
+}

package/template/server/src/shared/types/index.ts

@@ -0,0 +1,26 @@
+import type { FastifyRequest } from 'fastify';
+
+export type UserRole = 'USER' | 'ADMIN';
+
+export interface JwtPayload {
+  userId: string;
+  role: UserRole;
+}
+
+declare module '@fastify/jwt' {
+  interface FastifyJWT {
+    payload: JwtPayload;
+    user: JwtPayload;
+  }
+}
+
+declare module 'fastify' {
+  interface FastifyRequest {
+    user: JwtPayload;
+    startTime?: number; // Added for duration calculation
+  }
+}
+
+export interface AuthenticatedRequest extends FastifyRequest {
+  user: JwtPayload;
+}

package/template/server/src/test/setup.ts

@@ -1,38 +1,74 @@
-import { vi, beforeAll } from 'vitest';
-
-// Pre-fill process.env with required values for tests
-// This ensures zod validation in src/config/env.ts passes
-process.env['DATABASE_URL'] = process.env['DATABASE_URL'] || 'mysql://root:root@localhost:3306/test_db';
-process.env['JWT_SECRET'] = process.env['JWT_SECRET'] || 'test-secret-must-be-at-least-32-chars-long-for-validation';
-process.env['NODE_ENV'] = 'test';
-
-// Global mocks if needed
-console.log('Test setup loaded');
-
-// Mock database globally to prevent connection attempts
-vi.mock('@/libs/db', () => ({
-    prisma: {
-        $connect: vi.fn(),
-        $disconnect: vi.fn(),
-        $on: vi.fn(),
-        user: {
-            findUnique: vi.fn(),
-            create: vi.fn(),
-        },
-        session: {
-            create: vi.fn(),
-            findUnique: vi.fn(),
-        },
-        $queryRaw: vi.fn(),
-    },
-}));
-
-// Mock redis globally
-vi.mock('@/libs/redis', () => ({
-    redis: {
-        get: vi.fn(),
-        set: vi.fn(),
-        del: vi.fn(),
-        ping: vi.fn(),
-    },
-}));
+import { vi } from 'vitest';
+
+// Mock environment variables for testing
+process.env.NODE_ENV = 'test';
+process.env.DATABASE_URL = 'mysql://test:test@localhost:3306/test_db';
+process.env.REDIS_URL = 'redis://localhost:6379';
+process.env.JWT_SECRET = 'test-jwt-secret-must-be-at-least-32-characters-long';
+process.env.JWT_ACCESS_EXPIRY = '15m';
+process.env.JWT_REFRESH_EXPIRY = '7d';
+process.env.PORT = '3000';
+process.env.HOST = '0.0.0.0';
+
+// Test user data
+export const testUsers = {
+  validUser: {
+    id: 'test-user-id-1',
+    email: 'test@example.com',
+    password: '$2a$12$LQv3c1yqBWVHxkd0LHAkCOYz6TtxMQJqhN8/LewY5GyYiIJU6u1Em', // hashed "Password123!"
+    firstName: 'Test',
+    lastName: 'User',
+    avatarUrl: null,
+    role: 'USER' as const,
+    isActive: true,
+    deletedAt: null,
+    failedLoginAttempts: 0,
+    lockedUntil: null,
+    createdAt: new Date('2024-01-01T00:00:00Z'),
+    updatedAt: new Date('2024-01-01T00:00:00Z'),
+  },
+  inactiveUser: {
+    id: 'test-user-id-2',
+    email: 'inactive@example.com',
+    password: '$2a$12$LQv3c1yqBWVHxkd0LHAkCOYz6TtxMQJqhN8/LewY5GyYiIJU6u1Em',
+    firstName: 'Inactive',
+    lastName: 'User',
+    avatarUrl: null,
+    role: 'USER' as const,
+    isActive: false,
+    deletedAt: null,
+    failedLoginAttempts: 0,
+    lockedUntil: null,
+    createdAt: new Date('2024-01-01T00:00:00Z'),
+    updatedAt: new Date('2024-01-01T00:00:00Z'),
+  },
+  adminUser: {
+    id: 'test-user-id-3',
+    email: 'admin@example.com',
+    password: '$2a$12$LQv3c1yqBWVHxkd0LHAkCOYz6TtxMQJqhN8/LewY5GyYiIJU6u1Em',
+    firstName: 'Admin',
+    lastName: 'User',
+    avatarUrl: null,
+    role: 'ADMIN' as const,
+    isActive: true,
+    deletedAt: null,
+    failedLoginAttempts: 0,
+    lockedUntil: null,
+    createdAt: new Date('2024-01-01T00:00:00Z'),
+    updatedAt: new Date('2024-01-01T00:00:00Z'),
+  },
+};
+
+// Test refresh token data
+export const testRefreshToken = {
+  id: 'test-token-id-1',
+  token: 'test-refresh-token-uuid',
+  userId: testUsers.validUser.id,
+  expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000), // 7 days from now
+  createdAt: new Date(),
+};
+
+// Reset all mocks before each test
+export const resetMocks = (): void => {
+  vi.clearAllMocks();
+};

package/template/server/tsconfig.json

@@ -1,89 +1,27 @@
-{
-    "compilerOptions": {
-        /* Language and Environment */
-        "target": "ES2022",
-        "lib": [
-            "ES2022"
-        ],
-        "module": "ES2022",
-        "moduleResolution": "bundler",
-        /* Emit */
-        "outDir": "./dist",
-        "rootDir": "./src",
-        "declaration": true,
-        "declarationMap": true,
-        "sourceMap": true,
-        "removeComments": true,
-        "noEmit": false,
-        /* Interop Constraints */
-        "esModuleInterop": true,
-        "allowSyntheticDefaultImports": true,
-        "forceConsistentCasingInFileNames": true,
-        "resolveJsonModule": true,
-        "isolatedModules": true,
-        /* Type Checking - STRICT MODE ENABLED */
-        "strict": true,
-        "noImplicitAny": true,
-        "strictNullChecks": true,
-        "strictFunctionTypes": true,
-        "strictBindCallApply": true,
-        "strictPropertyInitialization": true,
-        "noImplicitThis": true,
-        "alwaysStrict": true,
-        "noUnusedLocals": true,
-        "noUnusedParameters": true,
-        "noImplicitReturns": true,
-        "noFallthroughCasesInSwitch": true,
-        "noUncheckedIndexedAccess": true,
-        "noImplicitOverride": true,
-        "noPropertyAccessFromIndexSignature": true,
-        /* Completeness */
-        "skipLibCheck": true,
-        "skipDefaultLibCheck": true,
-        /* Type Resolution */
-        "types": [],
-        /* Performance */
-        "incremental": true,
-        /* Path Mapping */
-        "baseUrl": ".",
-        "paths": {
-            "@/*": [
-                "src/*"
-            ],
-            "@/config/*": [
-                "src/config/*"
-            ],
-            "@/libs/*": [
-                "src/libs/*"
-            ],
-            "@/modules/*": [
-                "src/modules/*"
-            ],
-            "@/utils/*": [
-                "src/utils/*"
-            ],
-            "@/types/*": [
-                "src/types/*"
-            ]
-        },
-        /* Advanced */
-        "experimentalDecorators": true,
-        "emitDecoratorMetadata": true
-    },
-    "include": [
-        "src/**/*"
-    ],
-    "exclude": [
-        "node_modules",
-        "dist",
-        "**/*.test.ts",
-        "**/*.spec.ts"
-    ],
-    "ts-node": {
-        "require": [
-            "tsconfig-paths/register"
-        ],
-        "transpileOnly": true,
-        "files": true
-    }
-}
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"],
+      "@modules/*": ["./src/modules/*"],
+      "@libs/*": ["./src/libs/*"],
+      "@config/*": ["./src/config/*"],
+      "@shared/*": ["./src/shared/*"]
+    }
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/template/server/uploads/avatars/.gitkeep

@@ -0,0 +1 @@
+