base-lw-project-test 1.0.0

package/bin/index.js

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+
+import fs from "fs-extra";
+import path from "path";
+import inquirer from "inquirer";
+import chalk from "chalk";
+import ora from "ora";
+import { execSync } from "child_process";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// 🔥 pega autor do git
+const getGitUser = () => {
+  try {
+    return execSync("git config user.name").toString().trim();
+  } catch {
+    return "";
+  }
+};
+
+// 🔁 replace global
+const replaceInFiles = async (dir, replacements) => {
+  const files = await fs.readdir(dir);
+
+  for (const file of files) {
+    const fullPath = path.join(dir, file);
+    const stat = await fs.stat(fullPath);
+
+    if (stat.isDirectory()) {
+      await replaceInFiles(fullPath, replacements);
+    } else {
+      let content = await fs.readFile(fullPath, "utf8");
+
+      for (const [key, value] of Object.entries(replacements)) {
+        const regex = new RegExp(key, "g");
+        content = content.replace(regex, value);
+      }
+
+      await fs.writeFile(fullPath, content);
+    }
+  }
+};
+
+const run = async () => {
+  console.log(chalk.green("🚀 Criando projeto base LW...\n"));
+
+  const answers = await inquirer.prompt([
+    {
+      type: "input",
+      name: "projectName",
+      message: "Nome do projeto:",
+      default: "my-app",
+    },
+    {
+      type: "input",
+      name: "port",
+      message: "Porta da aplicação:",
+      default: "3000",
+    },
+    {
+      type: "input",
+      name: "description",
+      message: "Descrição:",
+      default: "API com Fastify + Mongoose",
+    },
+    {
+      type: "input",
+      name: "author",
+      message: "Autor:",
+      default: getGitUser(),
+    },
+    {
+      type: "list",
+      name: "packageManager",
+      message: "Gerenciador de pacotes:",
+      choices: ["npm", "yarn", "pnpm"],
+      default: "npm",
+    },
+  ]);
+
+  const projectPath = path.resolve(process.cwd(), answers.projectName);
+  const templatePath = path.join(__dirname, "../template");
+
+  // ❌ evita sobrescrever
+  if (fs.existsSync(projectPath)) {
+    console.log(chalk.red("❌ Essa pasta já existe"));
+    process.exit(1);
+  }
+
+  // 🚀 copiar template
+  const copySpinner = ora("Copiando template...").start();
+  await fs.copy(templatePath, projectPath);
+  copySpinner.succeed("Template copiado!");
+
+  // 🔁 replace global
+  const replaceSpinner = ora("Configurando projeto...").start();
+
+  await replaceInFiles(projectPath, {
+    "__PROJECT_NAME__": answers.projectName,
+    "__PORT__": answers.port,
+    "__DESCRIPTION__": answers.description,
+    "__AUTHOR__": answers.author || "Unknown",
+  });
+
+  replaceSpinner.succeed("Projeto configurado!");
+
+  // 📦 instalar deps baseado no gerenciador
+  const installSpinner = ora("Instalando dependências...").start();
+
+  let installCommand = "";
+  let runDevCommand = "";
+
+  if (answers.packageManager === "yarn") {
+    installCommand = "yarn";
+    runDevCommand = "yarn dev";
+  } else if (answers.packageManager === "pnpm") {
+    installCommand = "pnpm install";
+    runDevCommand = "pnpm dev";
+  } else {
+    installCommand = "npm install";
+    runDevCommand = "npm run dev";
+  }
+
+  execSync(installCommand, {
+    cwd: projectPath,
+    stdio: "ignore",
+  });
+
+  installSpinner.succeed("Dependências instaladas!");
+
+  console.log(chalk.green("\n✅ Projeto criado com sucesso!"));
+  console.log(chalk.yellow("\n👉 Próximos passos:"));
+  console.log(chalk.blue(`cd ${answers.projectName}`));
+  console.log(chalk.blue(runDevCommand + "\n"));
+};
+
+run();

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "base-lw-project-test",
+  "version": "1.0.0",
+  "description": "CLI para gerar projetos Fastify + Mongoose",
+  "license": "MIT",
+  "bin": {
+    "base-lw-project": "./bin/index.js"
+  },
+  "type": "module",
+  "dependencies": {
+    "chalk": "^5.0.0",
+    "fs-extra": "^11.2.0",
+    "inquirer": "^9.0.0",
+    "ora": "^9.3.0"
+  },
+  "files": [
+    "bin",
+    "template"
+  ],
+  "keywords": [
+  "cli",
+  "fastify",
+  "mongoose",
+  "template",
+  "scaffold"
+]
+}

package/template/.env

@@ -0,0 +1 @@
+PORT=__PORT__

package/template/ecosystem.config.js

@@ -0,0 +1,18 @@
+module.exports = {
+  apps: [
+    {
+      name: 'base-project-api',
+      script: './dist/server.js',
+      instances: 1,
+      autorestart: true,
+      watch: false,
+      max_memory_restart: '1G',
+      env: {
+        NODE_ENV: 'development',
+      },
+      env_production: {
+        NODE_ENV: 'production',
+      },
+    },
+  ],
+}

package/template/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "1.0.0",
+  "main": "index.js",
+  "license": "MIT",
+  "author": "__AUTHOR__",
+  "scripts": {
+    "dev": "tsx watch src/server.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint . --ext .ts",
+    "lint:fix": "eslint . --ext .ts --fix",
+    "format": "prettier . --write",
+    "format:check": "prettier . --check",
+    "commit:smart": "bash scripts/commit-smart.sh",
+    "build": "tsup src",
+    "start": "node ./dist/server.js"
+  },
+  "dependencies": {
+    "@fastify/cors": "11.2.0",
+    "axios": "^1.14.0",
+    "dotenv": "^17.3.1",
+    "fastify": "^5.8.4",
+    "jsonwebtoken": "^9.0.3",
+    "mongoose": "^9.3.3",
+    "tsup": "8.5.1",
+    "yup": "^1.7.1"
+  },
+  "devDependencies": {
+    "@types/jsonwebtoken": "^9.0.10",
+    "@types/node": "^25.5.0",
+    "@typescript-eslint/eslint-plugin": "^8.57.2",
+    "@typescript-eslint/parser": "^8.57.2",
+    "eslint": "^8",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.8.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}

package/template/scripts/commit-smart.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "-> Formatando o projeto..."
+yarn format
+
+echo "-> Validando lint..."
+yarn lint
+
+echo
+read -r -p "Mensagem do commit: " commit_message
+
+if [[ -z "${commit_message}" ]]; then
+  echo "Mensagem de commit vazia. Operacao cancelada."
+  exit 1
+fi
+
+echo "-> Adicionando arquivos..."
+git add -A
+
+if git diff --cached --quiet; then
+  echo "Nenhuma alteracao para commitar."
+  exit 1
+fi
+
+echo "-> Criando commit..."
+git commit -m "${commit_message}"
+
+echo "Commit criado com sucesso."

package/template/src/config/cors.ts

@@ -0,0 +1,24 @@
+import { FastifyCorsOptions, FastifyCorsOptionsDelegate } from '@fastify/cors'
+import { FastifyRegisterOptions } from 'fastify'
+import { env } from './env'
+
+const allowedOrigins = env.CORS_ORIGINS.split(',')
+  .map((origin) => origin.trim())
+  .filter(Boolean)
+
+export const corsConfig: FastifyRegisterOptions<FastifyCorsOptions | FastifyCorsOptionsDelegate> = {
+  origin: (origin, cb) => {
+    if (!origin) {
+      cb(null, true)
+      return
+    }
+
+    if (allowedOrigins.includes(origin)) {
+      cb(null, true)
+    } else {
+      cb(new Error(`Not allowed by CORS: ${origin}`), false)
+    }
+  },
+
+  methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
+}

package/template/src/config/database.ts

@@ -0,0 +1,15 @@
+import mongoose from 'mongoose'
+import { env } from '@config/env'
+
+const MONGO_URI = `${env.DB_URI}/${env.DB_NAME}`
+
+export const connectDatabase = async () => {
+  try {
+    await mongoose.connect(MONGO_URI)
+
+    console.log('✅ Mongo connected')
+  } catch (error) {
+    console.error('❌ Mongo connection error', error)
+    process.exit(1)
+  }
+}

package/template/src/config/env.ts

@@ -0,0 +1,54 @@
+import * as yup from 'yup'
+import 'dotenv/config'
+
+const envSchema = yup.object({
+  NODE_ENV: yup
+    .mixed<'development' | 'test' | 'production'>()
+    .oneOf(['development', 'test', 'production'])
+    .default('development')
+    .required(),
+
+  PORT: yup
+    .number()
+    .transform((_, originalValue) => Number(originalValue))
+    .default(8080)
+    .required(),
+
+  BODY_LIMIT: yup
+    .number()
+    .transform((_, originalValue) => Number(originalValue))
+    .default(10485760)
+    .required(),
+
+  JWT_EXPIRES_IN: yup.string().default('7d').required(),
+
+  JWT_SECRET: yup.string().min(10).required(),
+
+  DB_NAME: yup.string().min(1).required(),
+
+  DB_URI: yup
+    .string()
+    .matches(/^mongodb(\+srv)?:\/\//, 'DB must be a valid Mongo URI')
+    .required(),
+
+  CORS_ORIGINS: yup.string().default('http://localhost:3000').required(),
+})
+
+let env: yup.InferType<typeof envSchema>
+
+try {
+  env = envSchema.validateSync(process.env, {
+    abortEarly: false,
+    stripUnknown: true,
+  })
+} catch (err) {
+  console.error('❌ Invalid environment variables')
+
+  if (err instanceof yup.ValidationError) {
+    console.error(err.errors)
+  }
+
+  process.exit(1)
+}
+
+export { env }

package/template/src/config/index.ts

@@ -0,0 +1,4 @@
+export * from './cors'
+export * from './database'
+export * from './env'
+export * from './logger'

package/template/src/config/logger.ts

@@ -0,0 +1,11 @@
+import { FastifyServerOptions } from 'fastify'
+import { env } from './env'
+
+export const loggerConfig: FastifyServerOptions['logger'] =
+  env.NODE_ENV === 'production'
+    ? {
+        level: 'info',
+      }
+    : {
+        level: 'debug',
+      }

package/template/src/modules/example/example.controller.ts

@@ -0,0 +1,62 @@
+import { AppRouteHandler, RHWithParamsId } from '@types'
+import {
+  createExampleSchema,
+  listExamplesSchema,
+  paramsIdSchema,
+  updateExampleSchema,
+} from './example.validators'
+import { ExampleService } from './example.service'
+import { validateSchema } from '@utils'
+import { HttpStatusCode } from 'axios'
+
+const createExample: AppRouteHandler = async (req, res) => {
+  const body = await validateSchema(createExampleSchema, req.body)
+
+  const result = await ExampleService.createExample(body)
+
+  return res.status(HttpStatusCode.Created).send(result)
+}
+
+const listExamples: AppRouteHandler = async (req, res) => {
+  const query = await validateSchema(listExamplesSchema, req.query)
+
+  const result = await ExampleService.listExamples(query)
+
+  return res.status(HttpStatusCode.Ok).send(result)
+}
+
+const getExampleById: RHWithParamsId = async (req, res) => {
+  const params = await validateSchema(paramsIdSchema, req.params)
+
+  const result = await ExampleService.getExampleById(params.id)
+
+  return res.status(HttpStatusCode.Ok).send(result)
+}
+
+const updateExample: RHWithParamsId = async (req, res) => {
+  const params = await validateSchema(paramsIdSchema, req.params)
+  const body = await validateSchema(updateExampleSchema, req.body)
+
+  const result = await ExampleService.updateExample({
+    id: params.id,
+    ...body,
+  })
+
+  return res.status(HttpStatusCode.Ok).send(result)
+}
+
+const deleteExample: RHWithParamsId = async (req, res) => {
+  const params = await validateSchema(paramsIdSchema, req.params)
+
+  await ExampleService.deleteExample(params.id)
+
+  return res.status(HttpStatusCode.NoContent).send()
+}
+
+export const ExampleController = {
+  createExample,
+  listExamples,
+  getExampleById,
+  updateExample,
+  deleteExample,
+}

package/template/src/modules/example/example.repository.ts

@@ -0,0 +1,48 @@
+import { ExampleModel } from './example.schema'
+
+const findByName = async (name: string) => {
+  return ExampleModel.findOne({ name })
+}
+
+const findById = async (id: string) => {
+  return ExampleModel.findById(id)
+}
+
+const list = async ({ page, limit }: { page: number; limit: number }) => {
+  const skip = (page - 1) * limit
+
+  const [items, total] = await Promise.all([
+    ExampleModel.find().sort({ createdAt: -1 }).skip(skip).limit(limit),
+    ExampleModel.countDocuments(),
+  ])
+
+  return { items, total }
+}
+
+const create = async (data: { name: string; description?: string }) => {
+  return ExampleModel.create(data)
+}
+
+const update = async (
+  id: string,
+  data: {
+    name?: string
+    description?: string
+    isActive?: boolean
+  },
+) => {
+  return ExampleModel.findByIdAndUpdate(id, data, { new: true })
+}
+
+const remove = async (id: string) => {
+  return ExampleModel.findByIdAndDelete(id)
+}
+
+export const ExampleRepository = {
+  findByName,
+  findById,
+  list,
+  create,
+  update,
+  remove,
+}

package/template/src/modules/example/example.routes.ts

@@ -0,0 +1,15 @@
+import { FastifyPluginAsync } from 'fastify'
+import { AuthMiddleware } from '@middlewares'
+import { ExampleController } from './example.controller'
+
+export const exampleRoutes: FastifyPluginAsync = async (fastify) => {
+  fastify.register(async (authenticated) => {
+    authenticated.addHook('preHandler', AuthMiddleware)
+
+    authenticated.post('/', ExampleController.createExample)
+    authenticated.get('/', ExampleController.listExamples)
+    authenticated.get('/:id', ExampleController.getExampleById)
+    authenticated.patch('/:id', ExampleController.updateExample)
+    authenticated.delete('/:id', ExampleController.deleteExample)
+  })
+}

package/template/src/modules/example/example.schema.ts

@@ -0,0 +1,30 @@
+import { Schema, model, InferSchemaType } from 'mongoose'
+import { COLLECTIONS } from '@constants'
+
+const ExampleSchema = new Schema(
+  {
+    name: {
+      type: String,
+      required: true,
+      unique: true,
+      trim: true,
+    },
+    description: {
+      type: String,
+      required: false,
+      trim: true,
+    },
+    isActive: {
+      type: Boolean,
+      default: true,
+    },
+  },
+  {
+    timestamps: true,
+    versionKey: false,
+  },
+)
+
+export type Example = InferSchemaType<typeof ExampleSchema>
+
+export const ExampleModel = model('Example', ExampleSchema, COLLECTIONS.EXAMPLES)

package/template/src/modules/example/example.service.ts

@@ -0,0 +1,139 @@
+import {
+  AlreadyExistsException,
+  BadRequestException,
+  NotFoundException,
+} from '@errors'
+import { omitUndefined } from '@helpers'
+import { ExampleRepository } from './example.repository'
+
+type CreateExampleInput = {
+  name: string
+  description?: string
+}
+
+type UpdateExampleInput = {
+  id: string
+  name?: string
+  description?: string
+  isActive?: boolean
+}
+
+type ListExamplesInput = {
+  page?: number
+  limit?: number
+}
+
+type ExampleResponse = {
+  id: string
+  name: string
+  description?: string
+  isActive: boolean
+  createdAt: Date
+  updatedAt: Date
+}
+
+const toExampleResponse = (example: {
+  _id: { toString(): string }
+  name: string
+  description?: string | null
+  isActive: boolean
+  createdAt: Date
+  updatedAt: Date
+}): ExampleResponse => {
+  return {
+    id: example._id.toString(),
+    name: example.name,
+    description: example.description ?? undefined,
+    isActive: example.isActive,
+    createdAt: example.createdAt,
+    updatedAt: example.updatedAt,
+  }
+}
+
+const createExample = async ({ name, description }: CreateExampleInput) => {
+  const exists = await ExampleRepository.findByName(name)
+
+  if (exists) {
+    throw new AlreadyExistsException('Example with this name already exists')
+  }
+
+  const example = await ExampleRepository.create({
+    name,
+    description,
+  })
+
+  return {
+    data: toExampleResponse(example),
+  }
+}
+
+const listExamples = async ({ page = 1, limit = 10 }: ListExamplesInput) => {
+  const result = await ExampleRepository.list({
+    page,
+    limit,
+  })
+
+  return {
+    data: result.items.map(toExampleResponse),
+    meta: {
+      page,
+      limit,
+      total: result.total,
+      totalPages: Math.ceil(result.total / limit),
+    },
+  }
+}
+
+const getExampleById = async (id: string) => {
+  const example = await ExampleRepository.findById(id)
+
+  if (!example) {
+    throw new NotFoundException('Example not found')
+  }
+
+  return {
+    data: toExampleResponse(example),
+  }
+}
+
+const updateExample = async ({ id, name, description, isActive }: UpdateExampleInput) => {
+  const payload = omitUndefined({ name, description, isActive })
+
+  if (Object.keys(payload).length === 0) {
+    throw new BadRequestException('No fields provided for update')
+  }
+
+  if (name) {
+    const exists = await ExampleRepository.findByName(name)
+
+    if (exists && exists._id.toString() !== id) {
+      throw new AlreadyExistsException('Example with this name already exists')
+    }
+  }
+
+  const updated = await ExampleRepository.update(id, payload)
+
+  if (!updated) {
+    throw new NotFoundException('Example not found')
+  }
+
+  return {
+    data: toExampleResponse(updated),
+  }
+}
+
+const deleteExample = async (id: string) => {
+  const deleted = await ExampleRepository.remove(id)
+
+  if (!deleted) {
+    throw new NotFoundException('Example not found')
+  }
+}
+
+export const ExampleService = {
+  createExample,
+  listExamples,
+  getExampleById,
+  updateExample,
+  deleteExample,
+}

package/template/src/modules/example/example.validators.ts

@@ -0,0 +1,19 @@
+import { pageableSchema } from '@validators'
+import { boolean, object, string } from 'yup'
+
+export const createExampleSchema = object({
+  name: string().min(2).required(),
+  description: string().max(1000).optional(),
+})
+
+export const listExamplesSchema = pageableSchema
+
+export const paramsIdSchema = object({
+  id: string().required(),
+})
+
+export const updateExampleSchema = object({
+  name: string().min(2).optional(),
+  description: string().max(1000).optional(),
+  isActive: boolean().optional(),
+})

package/template/src/modules/example/index.ts

@@ -0,0 +1,6 @@
+export * from './example.schema'
+export * from './example.repository'
+export * from './example.validators'
+export * from './example.service'
+export * from './example.controller'
+export * from './example.routes'

package/template/src/modules/health/health.controller.ts

@@ -0,0 +1,10 @@
+import { healthHandler } from '@handlers'
+import { AppRouteHandler } from '@types'
+
+const check: AppRouteHandler = async (req, res) => {
+  return healthHandler(req, res)
+}
+
+export const HealthController = {
+  check,
+}

package/template/src/modules/health/health.routes.ts

@@ -0,0 +1,6 @@
+import { FastifyPluginAsync } from 'fastify'
+import { HealthController } from './health.controller'
+
+export const healthRoutes: FastifyPluginAsync = async (fastify) => {
+  fastify.get('/', HealthController.check)
+}

package/template/src/modules/health/index.ts

@@ -0,0 +1,2 @@
+export * from './health.controller'
+export * from './health.routes'

package/template/src/routes/index.ts

@@ -0,0 +1,8 @@
+import { exampleRoutes } from '../modules/example/example.routes'
+import { healthRoutes } from '../modules/health/health.routes'
+import { FastifyInstance } from 'fastify'
+
+export const registerRoutes = async (app: FastifyInstance) => {
+  app.register(healthRoutes, { prefix: '/health' })
+  app.register(exampleRoutes, { prefix: '/examples' })
+}

package/template/src/server.ts

@@ -0,0 +1,41 @@
+import Fastify from "fastify";
+import { connectDatabase, corsConfig, env, loggerConfig } from "@config";
+import { errorHandler } from "@errors";
+import { registerRoutes } from "@routes";
+import cors from "@fastify/cors";
+import "@validators/yup";
+
+export const buildApp = () => {
+  const app = Fastify({
+    logger: loggerConfig,
+    bodyLimit: env.BODY_LIMIT,
+  });
+
+  app.setErrorHandler(errorHandler);
+
+  app.register(cors, corsConfig);
+
+  app.register(registerRoutes);
+
+  return app;
+};
+
+const start = async () => {
+  const app = buildApp();
+
+  try {
+    await connectDatabase();
+
+    await app.listen({
+      port: env.PORT,
+      host: "0.0.0.0",
+    });
+
+    app.log.info(`Server __PROJECT_NAME__ listening on port ${env.PORT}`);
+  } catch (err) {
+    app.log.error(err);
+    process.exit(1);
+  }
+};
+
+void start();

package/template/src/shared/constants/db.constant.ts

@@ -0,0 +1,3 @@
+export const COLLECTIONS = {
+  EXAMPLES: 'examples',
+}

package/template/src/shared/constants/errors.constant.ts

@@ -0,0 +1,8 @@
+export const ERRORS_MESSAGES = {
+  UNEXPECTED_ERROR: 'An unexpected error occurred.',
+  ALREADY_EXISTS: 'Resource already exists.',
+  INVALID_PARAMS: 'Invalid request payload.',
+  NOT_FOUND: 'Resource not found.',
+  UNAUTHORIZED: 'Unauthorized.',
+  FORBIDDEN: 'Forbidden.',
+}

package/template/src/shared/constants/index.ts

@@ -0,0 +1,2 @@
+export * from './db.constant'
+export * from './errors.constant'

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

@@ -0,0 +1,14 @@
+import { HttpStatusCode } from 'axios'
+import { ERRORS_MESSAGES } from '@constants'
+import { BaseError } from '@errors/BaseError'
+
+const DEFAULT_MESSAGE = ERRORS_MESSAGES.ALREADY_EXISTS
+
+export class AlreadyExistsException extends BaseError {
+  constructor(message?: string) {
+    super({
+      message: message || DEFAULT_MESSAGE,
+      statusCode: HttpStatusCode.BadRequest,
+    })
+  }
+}

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

@@ -0,0 +1,11 @@
+import { HttpStatusCode } from 'axios'
+import { BaseError } from '@errors/BaseError'
+
+export class BadRequestException extends BaseError {
+  constructor(message?: string) {
+    super({
+      message: message,
+      statusCode: HttpStatusCode.BadRequest,
+    })
+  }
+}

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

@@ -0,0 +1,12 @@
+import { HttpStatusCode } from 'axios'
+import { ERRORS_MESSAGES } from '@constants'
+
+export class BaseError {
+  message: string
+  statusCode: number
+
+  constructor({ message, statusCode }: { message?: string; statusCode?: number }) {
+    this.message = message || ERRORS_MESSAGES.UNEXPECTED_ERROR
+    this.statusCode = statusCode || HttpStatusCode.InternalServerError
+  }
+}

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

@@ -0,0 +1,14 @@
+export enum CodesStatus {
+  Error = 1,
+  SystemOut,
+}
+
+export class ErrorResponse {
+  message: string
+  code = 1
+
+  constructor(message: string, code: number = CodesStatus.Error) {
+    this.message = message
+    this.code = code
+  }
+}

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

@@ -0,0 +1,12 @@
+import { HttpStatusCode } from 'axios'
+import { ERRORS_MESSAGES } from '@constants'
+import { BaseError } from '@errors/BaseError'
+
+export class ForbiddenException extends BaseError {
+  constructor(message?: string) {
+    super({
+      message: message || ERRORS_MESSAGES.FORBIDDEN,
+      statusCode: HttpStatusCode.Forbidden,
+    })
+  }
+}

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

@@ -0,0 +1,11 @@
+import { HttpStatusCode } from 'axios'
+import { BaseError } from '@errors/BaseError'
+
+export class InternalServerException extends BaseError {
+  constructor(message?: string) {
+    super({
+      message: message,
+      statusCode: HttpStatusCode.InternalServerError,
+    })
+  }
+}

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

@@ -0,0 +1,12 @@
+import { HttpStatusCode } from 'axios'
+import { ERRORS_MESSAGES } from '@constants'
+import { BaseError } from '@errors/BaseError'
+
+export class InvalidParamsException extends BaseError {
+  constructor(message?: string) {
+    super({
+      message: message || ERRORS_MESSAGES.INVALID_PARAMS,
+      statusCode: HttpStatusCode.BadRequest,
+    })
+  }
+}

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

@@ -0,0 +1,12 @@
+import { HttpStatusCode } from 'axios'
+import { ERRORS_MESSAGES } from '@constants'
+import { BaseError } from '@errors/BaseError'
+
+export class NotFoundException extends BaseError {
+  constructor(message?: string) {
+    super({
+      message: message || ERRORS_MESSAGES.NOT_FOUND,
+      statusCode: HttpStatusCode.NotFound,
+    })
+  }
+}

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

@@ -0,0 +1,12 @@
+import { HttpStatusCode } from 'axios'
+import { ERRORS_MESSAGES } from '@constants'
+import { BaseError } from '@errors/BaseError'
+
+export class UnauthorizedException extends BaseError {
+  constructor(message?: string) {
+    super({
+      message: message || ERRORS_MESSAGES.UNAUTHORIZED,
+      statusCode: HttpStatusCode.Unauthorized,
+    })
+  }
+}

package/template/src/shared/errors/error.handler.ts

@@ -0,0 +1,23 @@
+import { FastifyReply, FastifyRequest } from 'fastify'
+import { BaseError, ErrorResponse } from '@errors'
+import { ValidationError } from 'yup'
+import { ERRORS_MESSAGES } from '@constants'
+import { HttpStatusCode } from 'axios'
+
+export const errorHandler = (error: unknown, _req: FastifyRequest, res: FastifyReply) => {
+  console.error(error)
+
+  if (error instanceof BaseError) {
+    return res.status(error.statusCode).send(new ErrorResponse(error.message))
+  }
+
+  if (error instanceof ValidationError) {
+    return res
+      .status(HttpStatusCode.BadRequest)
+      .send(new ErrorResponse(ERRORS_MESSAGES.INVALID_PARAMS))
+  }
+
+  return res
+    .status(HttpStatusCode.InternalServerError)
+    .send(new ErrorResponse(ERRORS_MESSAGES.UNEXPECTED_ERROR))
+}

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

@@ -0,0 +1,10 @@
+export * from './AlreadyExistsException'
+export * from './BadRequestException'
+export * from './BaseError'
+export * from './ErrorResponse'
+export * from './InternalServerException'
+export * from './InvalidParamsException'
+export * from './NotFoundException'
+export * from './UnauthorizedException'
+export * from './error.handler'
+export * from './ForbiddenException'

package/template/src/shared/handlers/health.handler.ts

@@ -0,0 +1,9 @@
+import { HttpStatusCode } from 'axios'
+import { FastifyReply, FastifyRequest } from 'fastify'
+
+export const healthHandler = async (_req: FastifyRequest, reply: FastifyReply) => {
+  return reply.status(HttpStatusCode.Ok).send({
+    status: 'ok',
+    timestamp: new Date().toISOString(),
+  })
+}

package/template/src/shared/handlers/index.ts

@@ -0,0 +1 @@
+export * from './health.handler'

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

@@ -0,0 +1 @@
+export * from './object.helper'

package/template/src/shared/helpers/object.helper.ts

@@ -0,0 +1,5 @@
+export const omitUndefined = <T extends Record<string, unknown>>(value: T): Partial<T> => {
+  return Object.fromEntries(
+    Object.entries(value).filter(([, fieldValue]) => fieldValue !== undefined),
+  ) as Partial<T>
+}

package/template/src/shared/middlewares/auth.middleware.ts

@@ -0,0 +1,32 @@
+import { UnauthorizedException } from '@errors'
+import { verifyToken } from '@utils'
+import { FastifyReply, FastifyRequest } from 'fastify'
+
+export const AuthMiddleware = async (req: FastifyRequest, _res: FastifyReply) => {
+  const authHeader = req.headers.authorization
+
+  if (!authHeader) {
+    throw new UnauthorizedException('Missing authorization header')
+  }
+
+  const [scheme, token] = authHeader.split(' ')
+
+  if (scheme !== 'Bearer' || !token) {
+    throw new UnauthorizedException('Invalid token format')
+  }
+
+  try {
+    const { userId, role } = verifyToken(token)
+
+    if (!userId) {
+      throw new UnauthorizedException('Invalid token payload')
+    }
+
+    req.user = {
+      id: userId,
+      role,
+    }
+  } catch {
+    throw new UnauthorizedException('Invalid or expired token')
+  }
+}

package/template/src/shared/middlewares/index.ts

@@ -0,0 +1 @@
+export * from './auth.middleware'

package/template/src/shared/types/auth.context.ts

@@ -0,0 +1,4 @@
+export interface AuthContext {
+  id: string
+  role?: string
+}

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

@@ -0,0 +1,8 @@
+import 'fastify'
+import { AuthContext } from './auth.context'
+
+declare module 'fastify' {
+  interface FastifyRequest {
+    user: AuthContext
+  }
+}

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

@@ -0,0 +1,3 @@
+export * from './mongo'
+export * from './route'
+export * from './auth.context'

package/template/src/shared/types/mongo.ts

@@ -0,0 +1,12 @@
+import { Types } from 'mongoose'
+
+export type WithId<T> = T & {
+  _id: Types.ObjectId
+}
+
+export type WithTimestamps<T> = T & {
+  createdAt: Date
+  updatedAt: Date
+}
+
+export type MongoEntity<T> = WithId<WithTimestamps<T>>

package/template/src/shared/types/route.ts

@@ -0,0 +1,35 @@
+import { FastifyReply, FastifyRequest, RouteGenericInterface } from 'fastify'
+
+export interface AppRouteGeneric<
+  TBody = unknown,
+  TQuery = unknown,
+  TParams = unknown,
+  THeaders = unknown,
+> extends RouteGenericInterface {
+  Body: TBody
+  Querystring: TQuery
+  Params: TParams
+  Headers: THeaders
+}
+
+export type RouteHandler<T extends RouteGenericInterface> = (
+  req: FastifyRequest<T>,
+  reply: FastifyReply,
+) => Promise<unknown> | unknown
+
+export type AppRouteHandler<
+  TBody = unknown,
+  TQuery = unknown,
+  TParams = unknown,
+  THeaders = unknown,
+> = RouteHandler<AppRouteGeneric<TBody, TQuery, TParams, THeaders>>
+
+type ParamsWithId = {
+  id: string
+}
+
+export type RHWithParamsId<TBody = unknown, TQuery = unknown> = AppRouteHandler<
+  TBody,
+  TQuery,
+  ParamsWithId
+>

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

@@ -0,0 +1,2 @@
+export * from './jwt'
+export * from './validate'

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

@@ -0,0 +1,26 @@
+import { env } from '@config'
+import { InternalServerException } from '@errors'
+import jwt, { SignOptions } from 'jsonwebtoken'
+
+export type TokenPayload = {
+  userId: string
+  role?: string
+}
+
+export const signToken = (payload: TokenPayload, secret = env.JWT_SECRET): string => {
+  const options: SignOptions = {
+    expiresIn: env.JWT_EXPIRES_IN as SignOptions['expiresIn'],
+  }
+
+  return jwt.sign(payload, secret, options)
+}
+
+export const verifyToken = (token: string): TokenPayload => {
+  const decoded = jwt.verify(token, env.JWT_SECRET)
+
+  if (typeof decoded === 'string') {
+    throw new InternalServerException('Invalid token')
+  }
+
+  return decoded as TokenPayload
+}

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

@@ -0,0 +1,11 @@
+import { AnySchema, InferType } from 'yup'
+
+export const validateSchema = async <TSchema extends AnySchema>(
+  schema: TSchema,
+  data: unknown,
+): Promise<InferType<TSchema>> => {
+  return schema.validate(data, {
+    abortEarly: false,
+    stripUnknown: true,
+  })
+}

package/template/src/shared/validators/index.ts

@@ -0,0 +1,3 @@
+export * from './pageable.schema'
+export * from './number.utils'
+export * from './objectId'

package/template/src/shared/validators/number.utils.ts

@@ -0,0 +1,15 @@
+export const toNumber = (defaultValue: number) => (_: unknown, originalValue: unknown) => {
+  const parsed = Number(originalValue)
+  return isNaN(parsed) ? defaultValue : parsed
+}
+
+export const toClampedNumber =
+  (min: number, max: number, defaultValue: number) => (_: unknown, originalValue: unknown) => {
+    const parsed = Number(originalValue)
+
+    if (isNaN(parsed)) return defaultValue
+    if (parsed > max) return max
+    if (parsed < min) return min
+
+    return parsed
+  }

package/template/src/shared/validators/objectId.ts

@@ -0,0 +1,6 @@
+import { ObjectId } from 'mongodb'
+
+export const isValidObjectId = (value?: string): boolean => {
+  if (!value) return false
+  return ObjectId.isValid(value) && String(new ObjectId(value)) === value
+}

package/template/src/shared/validators/pageable.schema.ts

@@ -0,0 +1,11 @@
+import { object, number } from 'yup'
+import { toNumber, toClampedNumber } from './number.utils'
+
+export const pageableSchema = object({
+  page: number().transform(toNumber(1)).min(1).default(1).optional(),
+
+  limit: number()
+    .transform(toClampedNumber(1, 100, 10))
+    .default(10)
+    .optional(),
+})

package/template/src/shared/validators/yup.ts

@@ -0,0 +1,9 @@
+import * as yup from 'yup'
+import { isValidObjectId } from './objectId'
+
+yup.addMethod(yup.string, 'isObjectId', function (message?: string) {
+  return this.test('is-object-id', message || 'Invalid ObjectId', (value) => {
+    if (!value) return true
+    return isValidObjectId(value)
+  })
+})

package/template/tsconfig.json

@@ -0,0 +1,41 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "CommonJS",
+    "moduleResolution": "node",
+    "baseUrl": ".",
+    "rootDir": "src",
+    "paths": {
+      "@errors": ["./src/shared/errors/index.ts"],
+      "@errors/*": ["./src/shared/errors/*"],
+      "@constants": ["./src/shared/constants/index.ts"],
+      "@constants/*": ["./src/shared/constants/*"],
+      "@handlers": ["./src/shared/handlers/index.ts"],
+      "@handlers/*": ["./src/shared/handlers/*"],
+      "@helpers": ["./src/shared/helpers/index.ts"],
+      "@helpers/*": ["./src/shared/helpers/*"],
+      "@middlewares": ["./src/shared/middlewares/index.ts"],
+      "@middlewares/*": ["./src/shared/middlewares/*"],
+      "@types": ["./src/shared/types/index.ts"],
+      "@types/*": ["./src/shared/types/*"],
+      "@utils": ["./src/shared/utils/index.ts"],
+      "@utils/*": ["./src/shared/utils/*"],
+      "@validators": ["./src/shared/validators/index.ts"],
+      "@validators/*": ["./src/shared/validators/*"],
+      "@config": ["./src/config/index.ts"],
+      "@config/*": ["./src/config/*"],
+      "@Health": ["./src/modules/health/index.ts"],
+      "@Health/*": ["./src/modules/health/*"],
+      "@Example": ["./src/modules/example/index.ts"],
+      "@Example/*": ["./src/modules/example/*"],
+      "@routes": ["./src/routes/index.ts"],
+      "@routes/*": ["./src/routes/*"]
+    },
+    "outDir": "dist",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["dist", "node_modules"]
+}