create-nexst-monorepo 0.1.0

package/template/apps/api/src/health/health.controller.spec.ts

@@ -0,0 +1,82 @@
+import { HealthCheckService, MemoryHealthIndicator } from "@nestjs/terminus";
+import type { TestingModule } from "@nestjs/testing";
+import { Test } from "@nestjs/testing";
+import { vi } from "vitest";
+import { HealthController } from "#src/health/health.controller.js";
+import { PrismaService } from "#src/prisma/prisma.service.js";
+
+describe("healthController", () => {
+  let controller: HealthController;
+
+  const prismaMock = {
+    isHealthy: vi.fn<() => Promise<boolean>>(),
+  };
+
+  const healthCheckServiceMock = {
+    check: vi.fn(async (indicators: Array<() => Promise<Record<string, unknown>>>) => {
+      const results = await Promise.all(indicators.map((function_) => function_()));
+      const combined = {};
+      for (const result of results) {
+        Object.assign(combined, result);
+      }
+      return combined;
+    }),
+  };
+
+  const memoryIndicatorMock = {};
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+
+    const module: TestingModule = await Test.createTestingModule({
+      controllers: [HealthController],
+      providers: [
+        { provide: HealthCheckService, useValue: healthCheckServiceMock },
+        { provide: MemoryHealthIndicator, useValue: memoryIndicatorMock },
+        { provide: PrismaService, useValue: prismaMock },
+      ],
+    }).compile();
+
+    controller = module.get<HealthController>(HealthController);
+  });
+
+  it("should be defined", () => {
+    expect(controller).toBeDefined();
+  });
+
+  describe("liveness", () => {
+    it("returns ok with timestamp and uptime", () => {
+      const uptimeSpy = vi.spyOn(process, "uptime").mockReturnValue(123.456);
+      const res = controller.liveness();
+
+      expect(res.status).toBe("ok");
+      expect(typeof res.timestamp).toBe("string");
+      expect(() => new Date(res.timestamp)).not.toThrow();
+      expect(res.uptime).toBe(123);
+
+      uptimeSpy.mockRestore();
+    });
+  });
+
+  describe("check", () => {
+    it("returns database: up when prisma is healthy", async () => {
+      prismaMock.isHealthy.mockResolvedValueOnce(true);
+      const res = await controller.check();
+
+      expect(healthCheckServiceMock.check).toHaveBeenCalledTimes(1);
+      expect(res).toEqual({ database: { status: "up" } });
+      expect(prismaMock.isHealthy).toHaveBeenCalledTimes(1);
+    });
+
+    it("returns database: down when prisma is NOT healthy", async () => {
+      prismaMock.isHealthy.mockResolvedValueOnce(false);
+      const res = await controller.check();
+
+      expect(healthCheckServiceMock.check).toHaveBeenCalledTimes(1);
+      expect(res).toEqual({
+        database: { status: "down" },
+      });
+      expect(prismaMock.isHealthy).toHaveBeenCalledTimes(1);
+    });
+  });
+});

package/template/apps/api/src/health/health.controller.ts

@@ -0,0 +1,57 @@
+import { Controller, Get } from "@nestjs/common";
+import { ApiOperation, ApiResponse, ApiTags } from "@nestjs/swagger";
+import { HealthCheck, HealthCheckService } from "@nestjs/terminus";
+import { AllowAnonymous } from "#src/auth/decorator/allow-anonymous.decorator.js"; // @if auth
+import { PrismaService } from "#src/prisma/prisma.service.js";
+
+/**
+ * Controller for health check endpoints.
+ *
+ * - Provides readiness probe with database connectivity check
+ * - Provides liveness probe for basic service status
+ * - Used by Kubernetes or Docker health checks
+ */
+@AllowAnonymous() // @if auth
+@ApiTags("Health")
+@Controller("health")
+export class HealthController {
+  constructor(
+    private readonly health: HealthCheckService,
+    private readonly prisma: PrismaService,
+  ) {}
+
+  /**
+   * Performs readiness check including database connectivity.
+   *
+   * @returns Health check result with database status
+   */
+  @ApiOperation({ summary: "Health check with database and memory" })
+  @ApiResponse({ description: "Service is healthy", status: 200 })
+  @ApiResponse({ description: "Service is unhealthy", status: 503 })
+  @Get()
+  @HealthCheck()
+  check() {
+    return this.health.check([
+      async () => {
+        const isHealthy = await this.prisma.isHealthy();
+        return { database: { status: isHealthy ? "up" : "down" } };
+      },
+    ]);
+  }
+
+  /**
+   * Performs basic liveness check.
+   *
+   * @returns Object with status, timestamp, and uptime
+   */
+  @ApiOperation({ summary: "Liveness probe" })
+  @ApiResponse({ description: "Service is alive", status: 200 })
+  @Get("live")
+  liveness() {
+    return {
+      status: "ok",
+      timestamp: new Date().toISOString(),
+      uptime: Math.floor(process.uptime()),
+    };
+  }
+}

package/template/apps/api/src/health/health.module.ts

@@ -0,0 +1,12 @@
+import { Module } from "@nestjs/common";
+import { TerminusModule } from "@nestjs/terminus";
+import { HealthController } from "#src/health/health.controller.js";
+
+/**
+ * Module exposing standard health and readiness endpoints.
+ */
+@Module({
+  controllers: [HealthController],
+  imports: [TerminusModule],
+})
+export class HealthModule {}

package/template/apps/api/src/logging/context-logger.ts

@@ -0,0 +1,18 @@
+import { Inject, Injectable, Scope } from "@nestjs/common";
+import { INQUIRER } from "@nestjs/core";
+import { type Params, PARAMS_PROVIDER_TOKEN, PinoLogger } from "nestjs-pino";
+
+/**
+ * A `PinoLogger` that sets its own context from the injecting class via
+ * `INQUIRER`, so consumers no longer need to call `setContext` themselves.
+ */
+@Injectable({ scope: Scope.TRANSIENT })
+export class ContextLogger extends PinoLogger {
+  constructor(
+    @Inject(INQUIRER) parentClass: object,
+    @Inject(PARAMS_PROVIDER_TOKEN) params: Params,
+  ) {
+    super(params);
+    this.setContext(parentClass?.constructor?.name ?? "App");
+  }
+}

package/template/apps/api/src/logging/logger.config.ts

@@ -0,0 +1,23 @@
+import type { Params } from "nestjs-pino";
+
+export const loggerConfig: Params = {
+  pinoHttp: {
+    autoLogging: false,
+    formatters: {
+      level: (label: string) => ({ level: label.toUpperCase() }),
+    },
+    level: process.env.LOG_LEVEL ?? "debug",
+    ...(process.env.NODE_ENV === "development" && {
+      transport: {
+        options: {
+          colorize: true,
+          ignore: "pid,hostname,req,res,context",
+          messageFormat: "[{context}] {msg}",
+          singleLine: true,
+          translateTime: "dd.mm.yyyy, HH:MM:ss",
+        },
+        target: "pino-pretty",
+      },
+    }),
+  },
+};

package/template/apps/api/src/logging/logging.module.ts

@@ -0,0 +1,22 @@
+import { Global, Module } from "@nestjs/common";
+import { LoggerModule } from "nestjs-pino";
+import { ContextLogger } from "#src/logging/context-logger.js";
+import { loggerConfig } from "#src/logging/logger.config.js";
+
+/**
+ * The application's logging module.
+ *
+ * It wires `nestjs-pino` (pino transport + the request-scoped
+ * `Logger`/`PinoLogger` providers, configured via `loggerConfig`) and layers
+ * `ContextLogger` on top, which derives its log context from the injecting
+ * class. Feature modules inject `ContextLogger`; `main.ts` pulls `Logger` for
+ * `app.useLogger`. Nothing should import `nestjs-pino`'s `LoggerModule`
+ * directly — import this module instead.
+ */
+@Global()
+@Module({
+  exports: [ContextLogger, LoggerModule],
+  imports: [LoggerModule.forRoot(loggerConfig)],
+  providers: [ContextLogger],
+})
+export class LoggingModule {}

package/template/apps/api/src/mail/mail.module.ts

@@ -0,0 +1,12 @@
+import { Global, Module } from "@nestjs/common";
+import { MailService } from "#src/mail/mail.service.js";
+
+/**
+ * Global module sharing the mail-sending service.
+ */
+@Global()
+@Module({
+  exports: [MailService],
+  providers: [MailService],
+})
+export class MailModule {}

package/template/apps/api/src/mail/mail.service.spec.ts

@@ -0,0 +1,47 @@
+import type { ConfigService } from "@nestjs/config";
+import { vi } from "vitest";
+import type { AppConfig } from "#src/config/app.config.js";
+import type { ContextLogger } from "#src/logging/context-logger.js";
+import { MailService } from "#src/mail/mail.service.js";
+
+const { sendMail } = vi.hoisted(() => ({ sendMail: vi.fn() }));
+
+vi.mock("nodemailer", () => ({
+  createTransport: vi.fn(() => ({ sendMail })),
+}));
+
+describe("mailService (SMTP outside production)", () => {
+  const cfg = {
+    get: vi.fn(() => ({
+      from: "App <no-reply@example.com>",
+      smtp: { host: "localhost", port: 1025 },
+    })),
+  } as unknown as ConfigService<AppConfig, true>;
+  const logger = { debug: vi.fn() } as unknown as ContextLogger;
+
+  beforeEach(() => {
+    sendMail.mockReset();
+  });
+
+  it("sends the verification link in both the text and the HTML part", async () => {
+    const service = new MailService(cfg, logger);
+
+    await service.sendVerificationEmail("user@example.com", "https://example.com/verify?t=1");
+
+    expect(sendMail).toHaveBeenCalledTimes(1);
+    const [message] = sendMail.mock.calls[0] as [{ html: string; text: string; to: string }];
+    expect(message.to).toBe("user@example.com");
+    expect(message.text).toContain("https://example.com/verify?t=1");
+    expect(message.html).toContain("https://example.com/verify?t=1");
+  });
+
+  it("sends the password reset link", async () => {
+    const service = new MailService(cfg, logger);
+
+    await service.sendPasswordResetEmail("user@example.com", "https://example.com/reset?t=2");
+
+    const [message] = sendMail.mock.calls[0] as [{ subject: string; text: string }];
+    expect(message.subject).toMatch(/reset/i);
+    expect(message.text).toContain("https://example.com/reset?t=2");
+  });
+});

package/template/apps/api/src/mail/mail.service.ts

@@ -0,0 +1,123 @@
+import { Injectable } from "@nestjs/common";
+import { ConfigService } from "@nestjs/config";
+import { createTransport } from "nodemailer";
+import { Resend } from "resend";
+import type { AppConfig } from "#src/config/app.config.js";
+import { ContextLogger } from "#src/logging/context-logger.js";
+
+const APP_NAME = "Nexst";
+
+export type MailInput = {
+  html: string;
+  subject: string;
+  text: string;
+  to: string;
+};
+
+/** Sends a single email. Lets callers depend on the capability, not the service. */
+export type MailSender = (input: MailInput) => Promise<void>;
+
+/**
+ * Service for sending authentication emails.
+ *
+ * The provider is derived from `NODE_ENV`: Resend in production and SMTP
+ * (MailHog in local development) otherwise. The sender is built once at
+ * construction and reused for every message.
+ */
+@Injectable()
+export class MailService {
+  private readonly sender: MailSender;
+
+  constructor(
+    private readonly cfg: ConfigService<AppConfig, true>,
+    private readonly logger: ContextLogger,
+  ) {
+    this.sender = this.createSender();
+  }
+
+  /** Sends an email through the configured mail provider. */
+  async send(input: MailInput): Promise<void> {
+    await this.sender(input);
+    this.logger.debug({ subject: input.subject, to: input.to }, "Email sent");
+  }
+
+  /** Sends the password-reset message used by Better Auth. */
+  async sendPasswordResetEmail(to: string, url: string): Promise<void> {
+    await this.send({
+      html: this.layout(
+        "Reset your password",
+        `We received a request to reset your ${APP_NAME} password. This link expires soon. If you did not request it, you can ignore this email.`,
+        url,
+        "Reset password",
+      ),
+      subject: `Reset your ${APP_NAME} password`,
+      text: `Reset your ${APP_NAME} password by opening this link:\n\n${url}\n\nIf you did not request this, ignore this email.`,
+      to,
+    });
+  }
+
+  /** Sends the email-verification message used by Better Auth. */
+  async sendVerificationEmail(to: string, url: string): Promise<void> {
+    await this.send({
+      html: this.layout(
+        "Confirm your email",
+        `Welcome to ${APP_NAME}! Please confirm your email address to activate your account.`,
+        url,
+        "Verify email",
+      ),
+      subject: `Confirm your ${APP_NAME} email`,
+      text: `Welcome to ${APP_NAME}! Confirm your email address by opening this link:\n\n${url}`,
+      to,
+    });
+  }
+
+  /**
+   * Builds the mail sender for the configured provider: Resend in production and
+   * SMTP (MailHog in local development) otherwise.
+   */
+  private createSender(): MailSender {
+    const mail = this.cfg.get("mail", { infer: true });
+    const { from } = mail;
+
+    if (process.env.NODE_ENV === "production") {
+      const resend = new Resend(mail.resendApiKey);
+
+      return async (input) => {
+        const { error } = await resend.emails.send({ from, ...input });
+        if (error) {
+          throw new Error(`Resend failed to send email: ${error.message}`);
+        }
+      };
+    }
+
+    const transporter = createTransport(mail.smtp);
+
+    return async (input) => {
+      await transporter.sendMail({ from, ...input });
+    };
+  }
+
+  private layout(heading: string, body: string, actionUrl: string, actionLabel: string): string {
+    return `<!doctype html>
+            <html>
+              <body style="margin:0;background:#f4f5f7;font-family:Arial,Helvetica,sans-serif;color:#111">
+                <table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="padding:32px 0">
+                  <tr>
+                    <td align="center">
+                      <table role="presentation" width="480" cellpadding="0" cellspacing="0" style="background:#fff;border-radius:12px;padding:32px">
+                        <tr><td style="font-size:20px;font-weight:700;padding-bottom:12px">${heading}</td></tr>
+                        <tr><td style="font-size:15px;line-height:1.6;color:#374151;padding-bottom:24px">${body}</td></tr>
+                        <tr>
+                          <td>
+                            <a href="${actionUrl}" style="display:inline-block;background:#2563eb;color:#fff;text-decoration:none;font-weight:600;padding:12px 24px;border-radius:8px">${actionLabel}</a>
+                          </td>
+                        </tr>
+                        <tr><td style="font-size:12px;color:#9ca3af;padding-top:24px">If the button does not work, copy this link into your browser:<br>${actionUrl}</td></tr>
+                      </table>
+                    </td>
+                  </tr>
+                </table>
+              </body>
+            </html>`;
+  }
+}

package/template/apps/api/src/main.ts

@@ -0,0 +1,41 @@
+import { ValidationPipe } from "@nestjs/common";
+import { NestFactory } from "@nestjs/core";
+import type { NestFastifyApplication } from "@nestjs/platform-fastify";
+import { FastifyAdapter } from "@nestjs/platform-fastify";
+import { Logger } from "nestjs-pino";
+import { AppModule } from "#src/app.module.js";
+import { registerGraphqlEnums } from "#src/bootstrap/register-graphql-enums.js"; // @if auth
+import { addSecurity } from "#src/bootstrap/security.js";
+import { addSwagger } from "#src/bootstrap/swagger.js";
+import { validationExceptionFactory } from "#src/errors/validation-exception.factory.js";
+
+async function bootstrap() {
+  const app = await NestFactory.create<NestFastifyApplication>(AppModule, new FastifyAdapter(), {
+    // @if auth
+    // Better Auth parses its own request bodies.
+    bodyParser: false,
+    // @endif
+  });
+
+  await addSecurity(app);
+  registerGraphqlEnums(); // @if auth
+  app.useLogger(app.get(Logger));
+
+  app.useGlobalPipes(
+    new ValidationPipe({
+      exceptionFactory: validationExceptionFactory,
+      transform: true,
+      transformOptions: { enableImplicitConversion: true },
+      whitelist: true,
+    }),
+  );
+
+  if (process.env.NODE_ENV === "development") {
+    addSwagger(app);
+  }
+
+  app.enableShutdownHooks();
+  await app.listen(process.env.PORT ?? 3001, "0.0.0.0");
+}
+
+void bootstrap();

package/template/apps/api/src/prisma/prisma.module.ts

@@ -0,0 +1,12 @@
+import { Global, Module } from "@nestjs/common";
+import { PrismaService } from "#src/prisma/prisma.service.js";
+
+/**
+ * Global module exposing PrismaService so repositories can access the database.
+ */
+@Global()
+@Module({
+  exports: [PrismaService],
+  providers: [PrismaService],
+})
+export class PrismaModule {}

package/template/apps/api/src/prisma/prisma.service.spec.ts

@@ -0,0 +1,136 @@
+import type { ConfigService } from "@nestjs/config";
+import { vi } from "vitest";
+import type { Mocked } from "vitest";
+import type { ContextLogger } from "#src/logging/context-logger.js";
+import { PrismaService } from "#src/prisma/prisma.service.js";
+
+vi.mock("#src/generated/prisma/client.js", () => {
+  class PrismaClient {
+    $connect = vi.fn(async () => {});
+
+    $disconnect = vi.fn(async () => {});
+    $on = vi.fn();
+    $queryRaw = vi.fn();
+  }
+  return { PrismaClient };
+});
+
+vi.mock("@prisma/adapter-pg", () => ({
+  PrismaPg: vi.fn(function () {
+    return {};
+  }),
+}));
+
+describe("prismaService (unit)", () => {
+  let service: PrismaService;
+  let configMock: Mocked<ConfigService>;
+  let loggerMock: Mocked<ContextLogger>;
+
+  const originalAutoMigrate = process.env.PRISMA_AUTO_MIGRATE;
+
+  beforeAll(() => {
+    process.env.PRISMA_AUTO_MIGRATE = "false";
+  });
+
+  afterAll(() => {
+    if (originalAutoMigrate === undefined) {
+      delete process.env.PRISMA_AUTO_MIGRATE;
+    } else {
+      process.env.PRISMA_AUTO_MIGRATE = originalAutoMigrate;
+    }
+  });
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+
+    configMock = {
+      get: vi.fn().mockImplementation((key: string) => {
+        if (key === "db.url") {
+          return "postgresql://user:pass@localhost:5432/db";
+        }
+      }),
+    } as unknown as Mocked<ConfigService>;
+
+    loggerMock = {
+      debug: vi.fn(),
+      error: vi.fn(),
+      info: vi.fn(),
+      setContext: vi.fn(),
+      warn: vi.fn(),
+    } as unknown as Mocked<ContextLogger>;
+
+    service = new PrismaService(configMock, loggerMock);
+  });
+
+  describe("isHealthy", () => {
+    it("returns true when $queryRaw resolves", async () => {
+      vi.spyOn(service, "$queryRaw").mockResolvedValue([{ "?column?": 1 }]);
+
+      const result = await service.isHealthy();
+
+      expect(result).toBe(true);
+      expect(service.$queryRaw).toHaveBeenCalledTimes(1);
+    });
+
+    it("returns false and logs error when $queryRaw rejects", async () => {
+      const error = new Error("boom");
+      vi.spyOn(service, "$queryRaw").mockRejectedValue(error);
+
+      const result = await service.isHealthy();
+
+      expect(result).toBe(false);
+      expect(service.$queryRaw).toHaveBeenCalledTimes(1);
+      expect(loggerMock.error).toHaveBeenCalledWith(
+        { error: "boom" },
+        "Database health check failed",
+      );
+    });
+  });
+
+  describe("onModuleDestroy", () => {
+    it('calls $disconnect and logs "closed"', async () => {
+      vi.spyOn(service, "$disconnect").mockResolvedValue();
+
+      await service.onModuleDestroy();
+
+      expect(service.$disconnect).toHaveBeenCalledTimes(1);
+      expect(loggerMock.info).toHaveBeenCalledWith("Database connection closed");
+    });
+
+    it("logs error if $disconnect throws", async () => {
+      const error = new Error("cannot close");
+      vi.spyOn(service, "$disconnect").mockRejectedValue(error);
+
+      await service.onModuleDestroy();
+
+      expect(service.$disconnect).toHaveBeenCalled();
+      expect(loggerMock.error).toHaveBeenCalledWith(
+        { error: "cannot close" },
+        "Error during database disconnect",
+      );
+    });
+  });
+
+  describe("onModuleInit", () => {
+    it("calls $connect and logs success", async () => {
+      vi.spyOn(service, "$connect").mockResolvedValue();
+
+      await service.onModuleInit();
+
+      expect(service.$connect).toHaveBeenCalledTimes(1);
+      expect(loggerMock.info).toHaveBeenCalledWith("Successfully connected to database");
+    });
+
+    it("logs error and rethrows if $connect throws", async () => {
+      const error = new Error("cannot connect");
+      vi.spyOn(service, "$connect").mockRejectedValue(error);
+
+      await expect(service.onModuleInit()).rejects.toThrow("cannot connect");
+      expect(service.$connect).toHaveBeenCalled();
+      expect(loggerMock.error).toHaveBeenCalledWith(
+        { error: "cannot connect" },
+        "Failed to connect to database",
+      );
+    });
+  });
+});