create-nexst-monorepo 0.1.0

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

@@ -0,0 +1,138 @@
+import { execFile } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { Injectable } from "@nestjs/common";
+import type { OnModuleDestroy, OnModuleInit } from "@nestjs/common";
+import { ConfigService } from "@nestjs/config";
+import { PrismaPg } from "@prisma/adapter-pg";
+import type { AppConfig } from "#src/config/app.config.js";
+import { PrismaClient } from "#src/generated/prisma/client.js";
+import type { Prisma } from "#src/generated/prisma/client.js";
+import { ContextLogger } from "#src/logging/context-logger.js";
+import { handleError } from "#src/utils/error-handler.util.js";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Prisma service for database access and lifecycle management.
+ *
+ * - Extends PrismaClient with NestJS lifecycle hooks
+ * - Configures query logging for development
+ * - Provides health check functionality
+ * - Handles connection management
+ */
+@Injectable()
+export class PrismaService extends PrismaClient implements OnModuleDestroy, OnModuleInit {
+  constructor(
+    cfg: ConfigService<AppConfig, true>,
+    private readonly logger: ContextLogger,
+  ) {
+    const adapter = new PrismaPg({
+      connectionString: cfg.get("db.url", { infer: true }),
+    });
+
+    super({
+      adapter,
+      errorFormat: "pretty",
+      log: [
+        { emit: "event", level: "query" },
+        { emit: "event", level: "info" },
+        { emit: "event", level: "warn" },
+        { emit: "event", level: "error" },
+      ],
+    });
+
+    this.$on("query" as never, (e: Prisma.QueryEvent) => {
+      if (process.env.NODE_ENV !== "production") {
+        this.logger.debug({ duration: e.duration, query: e.query }, "Query executed");
+      }
+    });
+    this.$on("info" as never, (e: Prisma.LogEvent) => {
+      this.logger.info(e.message);
+    });
+    this.$on("warn" as never, (e: Prisma.LogEvent) => {
+      this.logger.warn(e.message);
+    });
+    this.$on("error" as never, (e: Prisma.LogEvent) => {
+      this.logger.error(e.message);
+    });
+  }
+
+  /**
+   * Checks database connectivity.
+   *
+   * @returns True if database is reachable, false otherwise
+   */
+  async isHealthy(): Promise<boolean> {
+    try {
+      await this.$queryRaw`SELECT 1`;
+      return true;
+    } catch (error: unknown) {
+      this.logger.error({ error: handleError(error) }, "Database health check failed");
+      return false;
+    }
+  }
+
+  /**
+   * Disconnects from database on module destruction.
+   *
+   * @returns A promise that resolves when disconnection is complete
+   */
+  async onModuleDestroy(): Promise<void> {
+    try {
+      await this.$disconnect();
+      this.logger.info("Database connection closed");
+    } catch (error: unknown) {
+      this.logger.error({ error: handleError(error) }, "Error during database disconnect");
+    }
+  }
+
+  /**
+   * Connects to database on module initialization.
+   *
+   * @returns A promise that resolves when connection is established
+   * @throws {Error} When database connection fails
+   */
+  async onModuleInit(): Promise<void> {
+    try {
+      await this.$connect();
+      this.logger.info("Successfully connected to database");
+    } catch (error: unknown) {
+      this.logger.error({ error: handleError(error) }, "Failed to connect to database");
+      throw error;
+    }
+
+    await this.applyMigrations();
+  }
+
+  /**
+   * Applies pending database migrations on startup.
+   *
+   * Runs `prisma migrate deploy`, which is idempotent: it creates the schema
+   * from scratch when the database is empty, applies any pending migrations,
+   * and is a no-op when the schema is already up to date.
+   *
+   * Skipped when `PRISMA_AUTO_MIGRATE=false` (e.g. when migrations are run as a
+   * separate deploy step).
+   *
+   * @throws {Error} When migrations fail to apply
+   */
+  private async applyMigrations(): Promise<void> {
+    if (process.env.PRISMA_AUTO_MIGRATE === "false") {
+      this.logger.info("Auto-migration disabled (PRISMA_AUTO_MIGRATE=false), skipping");
+      return;
+    }
+
+    try {
+      const prismaCli = fileURLToPath(import.meta.resolve("prisma/build/index.js"));
+      const { stdout } = await execFileAsync(process.execPath, [prismaCli, "migrate", "deploy"], {
+        cwd: process.cwd(),
+        env: process.env,
+      });
+      this.logger.info({ output: stdout.trim() }, "Database migrations applied");
+    } catch (error: unknown) {
+      this.logger.error({ error: handleError(error) }, "Failed to apply database migrations");
+      throw error;
+    }
+  }
+}

package/template/apps/api/src/queue/dto/enqueue-example.input.ts

@@ -0,0 +1,11 @@
+import { Field, InputType } from "@nestjs/graphql";
+import { IsString, MaxLength, MinLength } from "class-validator";
+
+@InputType()
+export class EnqueueExampleInput {
+  @Field()
+  @IsString()
+  @MaxLength(500)
+  @MinLength(1)
+  message: string;
+}

package/template/apps/api/src/queue/example-queue.resolver.ts

@@ -0,0 +1,14 @@
+import { Args, ID, Mutation, Resolver } from "@nestjs/graphql";
+import { EnqueueExampleInput } from "#src/queue/dto/enqueue-example.input.js";
+import { ExampleQueueService } from "#src/queue/example-queue.service.js";
+
+@Resolver()
+export class ExampleQueueResolver {
+  constructor(private readonly exampleQueue: ExampleQueueService) {}
+
+  /** Hands a message to apps/worker and returns the BullMQ job id. */
+  @Mutation(() => ID)
+  enqueueExample(@Args("input") { message }: EnqueueExampleInput): Promise<string> {
+    return this.exampleQueue.enqueue(message);
+  }
+}

package/template/apps/api/src/queue/example-queue.service.spec.ts

@@ -0,0 +1,21 @@
+import { vi } from "vitest";
+import type { ContextLogger } from "#src/logging/context-logger.js";
+import { ExampleQueueService } from "#src/queue/example-queue.service.js";
+
+describe("exampleQueueService", () => {
+  it("adds a retrying job with the message and returns its id", async () => {
+    const add = vi.fn().mockResolvedValue({ id: "42" });
+    const service = new ExampleQueueService(
+      { add } as never,
+      { debug: vi.fn() } as unknown as ContextLogger,
+    );
+
+    await expect(service.enqueue("hello")).resolves.toBe("42");
+
+    expect(add).toHaveBeenCalledWith(
+      "example",
+      expect.objectContaining({ message: "hello" }),
+      expect.objectContaining({ attempts: 3 }),
+    );
+  });
+});

package/template/apps/api/src/queue/example-queue.service.ts

@@ -0,0 +1,32 @@
+import { InjectQueue } from "@nestjs/bullmq";
+import { Injectable } from "@nestjs/common";
+import { EXAMPLE_QUEUE } from "@nexst/queues";
+import type { ExampleJob, ExampleJobResult } from "@nexst/queues";
+import { Queue } from "bullmq";
+import { ContextLogger } from "#src/logging/context-logger.js";
+
+/**
+ * Enqueues jobs for apps/worker. Replace the example payload with real work.
+ */
+@Injectable()
+export class ExampleQueueService {
+  constructor(
+    @InjectQueue(EXAMPLE_QUEUE) private readonly queue: Queue<ExampleJob, ExampleJobResult>,
+    private readonly logger: ContextLogger,
+  ) {}
+
+  /**
+   * Adds one job and returns its id.
+   *
+   * @param message - Text the worker processes
+   */
+  async enqueue(message: string): Promise<string> {
+    const job = await this.queue.add(
+      "example",
+      { message, requestedAt: new Date().toISOString() },
+      { attempts: 3, backoff: { delay: 1000, type: "exponential" }, removeOnComplete: 100 },
+    );
+    this.logger.debug({ jobId: job.id }, "Example job enqueued");
+    return job.id ?? "";
+  }
+}

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

@@ -0,0 +1,27 @@
+import { BullModule } from "@nestjs/bullmq";
+import { Module } from "@nestjs/common";
+import { ConfigService } from "@nestjs/config";
+import { createRedisConnectionOptions, EXAMPLE_QUEUE } from "@nexst/queues";
+import type { AppConfig } from "#src/config/app.config.js";
+import { ExampleQueueResolver } from "#src/queue/example-queue.resolver.js";
+import { ExampleQueueService } from "#src/queue/example-queue.service.js";
+
+/**
+ * BullMQ producer side: connects to Redis and registers the queues apps/worker
+ * consumes. Queue names and payload types live in `@nexst/queues` so both
+ * sides stay in sync.
+ */
+@Module({
+  exports: [ExampleQueueService],
+  imports: [
+    BullModule.forRootAsync({
+      inject: [ConfigService],
+      useFactory: (cfg: ConfigService<AppConfig, true>) => ({
+        connection: createRedisConnectionOptions(cfg.get("redis", { infer: true })),
+      }),
+    }),
+    BullModule.registerQueue({ name: EXAMPLE_QUEUE }),
+  ],
+  providers: [ExampleQueueResolver, ExampleQueueService],
+})
+export class QueueModule {}

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

@@ -0,0 +1,12 @@
+import { Global, Module } from "@nestjs/common";
+import { R2Service } from "#src/r2/r2.service.js";
+
+/**
+ * Global module sharing the Cloudflare R2 storage service.
+ */
+@Global()
+@Module({
+  exports: [R2Service],
+  providers: [R2Service],
+})
+export class R2Module {}

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

@@ -0,0 +1,117 @@
+import {
+  DeleteObjectCommand,
+  DeleteObjectsCommand,
+  PutObjectCommand,
+  S3Client,
+} from "@aws-sdk/client-s3";
+import { ConfigService } from "@nestjs/config";
+import type { TestingModule } from "@nestjs/testing";
+import { Test } from "@nestjs/testing";
+import { mockClient } from "aws-sdk-client-mock";
+import { vi } from "vitest";
+import { ContextLogger } from "#src/logging/context-logger.js";
+import { R2Service } from "#src/r2/r2.service.js";
+
+describe("r2Service", () => {
+  const s3Mock = mockClient(S3Client);
+  let service: R2Service;
+
+  const build = async (publicUrl?: string) => {
+    const r2 = {
+      accessKeyId: "test-key",
+      bucket: "test-bucket",
+      endpoint: "https://account.r2.cloudflarestorage.com",
+      maxAttempts: 3,
+      presignExpiresInSeconds: 600,
+      publicUrl,
+      region: "auto",
+      secretAccessKey: "test-secret",
+    };
+
+    const mod: TestingModule = await Test.createTestingModule({
+      providers: [
+        R2Service,
+        { provide: ConfigService, useValue: { get: vi.fn(() => r2) } },
+        { provide: ContextLogger, useValue: { debug: vi.fn(), error: vi.fn() } },
+      ],
+    }).compile();
+
+    service = mod.get(R2Service);
+  };
+
+  beforeEach(async () => {
+    s3Mock.reset();
+    await build();
+  });
+
+  it("uploads an object to the configured bucket", async () => {
+    s3Mock.on(PutObjectCommand).resolves({ ETag: "etag" });
+
+    const key = await service.putObject({ body: "hello", contentType: "text/plain", key: "a.txt" });
+
+    expect(key).toBe("a.txt");
+    expect(s3Mock.commandCalls(PutObjectCommand)[0].args[0].input).toMatchObject({
+      Bucket: "test-bucket",
+      ContentType: "text/plain",
+      Key: "a.txt",
+    });
+  });
+
+  it("rethrows upload failures", async () => {
+    s3Mock.on(PutObjectCommand).rejects(new Error("Upload failed"));
+
+    await expect(
+      service.putObject({ body: "x", contentType: "text/plain", key: "a.txt" }),
+    ).rejects.toThrow("Upload failed");
+  });
+
+  it("deletes a single object", async () => {
+    s3Mock.on(DeleteObjectCommand).resolves({});
+
+    await service.deleteObject("a.txt");
+
+    expect(s3Mock.commandCalls(DeleteObjectCommand)[0].args[0].input).toEqual({
+      Bucket: "test-bucket",
+      Key: "a.txt",
+    });
+  });
+
+  it("batches bulk deletes to 1000 keys per request", async () => {
+    s3Mock.on(DeleteObjectsCommand).resolves({});
+    const keys = Array.from({ length: 1001 }, (_, index) => `file-${index}`);
+
+    await service.deleteObjects(keys);
+
+    const calls = s3Mock.commandCalls(DeleteObjectsCommand);
+    expect(calls).toHaveLength(2);
+    expect(calls[1].args[0].input.Delete?.Objects).toEqual([{ Key: "file-1000" }]);
+  });
+
+  it("does not call R2 for an empty key list", async () => {
+    await service.deleteObjects([]);
+
+    expect(s3Mock.commandCalls(DeleteObjectsCommand)).toHaveLength(0);
+  });
+
+  it("signs a download URL with an attachment filename", async () => {
+    const url = await service.getPresignedDownloadUrl("docs/a.pdf", 'My "File".pdf');
+
+    expect(url).toContain("test-bucket");
+    expect(url).toContain("docs/a.pdf");
+    expect(decodeURIComponent(url)).toContain('filename="My File.pdf"');
+  });
+
+  it("signs an upload URL", async () => {
+    const url = await service.getPresignedUploadUrl("docs/b.pdf", "application/pdf");
+
+    expect(url).toContain("X-Amz-Signature");
+  });
+
+  it("builds public URLs only when a public base is configured", async () => {
+    expect(service.getPublicUrl("a.png")).toBeUndefined();
+
+    await build("https://cdn.example.com/");
+
+    expect(service.getPublicUrl("a.png")).toBe("https://cdn.example.com/a.png");
+  });
+});

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

@@ -0,0 +1,131 @@
+import type { Readable } from "node:stream";
+import {
+  DeleteObjectCommand,
+  DeleteObjectsCommand,
+  GetObjectCommand,
+  PutObjectCommand,
+  S3Client,
+} from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import { Injectable } from "@nestjs/common";
+import { ConfigService } from "@nestjs/config";
+import type { AppConfig } from "#src/config/app.config.js";
+import { ContextLogger } from "#src/logging/context-logger.js";
+import { handleError } from "#src/utils/error-handler.util.js";
+
+/** R2's `DeleteObjects` accepts at most this many keys per request. */
+const DELETE_BATCH_SIZE = 1000;
+
+export type PutObjectInput = {
+  body: Buffer | Readable | string | Uint8Array;
+  contentType: string;
+  key: string;
+  metadata?: Record<string, string>;
+};
+
+/**
+ * Service for Cloudflare R2 object storage (S3-compatible API).
+ *
+ * - Uploads and deletes objects in the configured bucket
+ * - Signs short-lived GET/PUT URLs so clients never see credentials
+ * - Builds public URLs when the bucket is exposed via `R2_PUBLIC_URL`
+ */
+@Injectable()
+export class R2Service {
+  private readonly bucket: string;
+  private readonly client: S3Client;
+  private readonly presignExpiresInSeconds: number;
+  private readonly publicUrl?: string;
+
+  constructor(
+    cfg: ConfigService<AppConfig, true>,
+    private readonly logger: ContextLogger,
+  ) {
+    const r2 = cfg.get("r2", { infer: true });
+
+    this.bucket = r2.bucket;
+    this.presignExpiresInSeconds = r2.presignExpiresInSeconds;
+    this.publicUrl = r2.publicUrl?.replace(/\/+$/, "");
+    this.client = new S3Client({
+      credentials: { accessKeyId: r2.accessKeyId, secretAccessKey: r2.secretAccessKey },
+      endpoint: r2.endpoint,
+      maxAttempts: r2.maxAttempts,
+      region: r2.region,
+    });
+  }
+
+  /** Deletes a single object; a missing key is not an error. */
+  async deleteObject(key: string): Promise<void> {
+    await this.client.send(new DeleteObjectCommand({ Bucket: this.bucket, Key: key }));
+  }
+
+  /** Deletes many objects, batched to R2's per-request limit. */
+  async deleteObjects(keys: string[]): Promise<void> {
+    for (let start = 0; start < keys.length; start += DELETE_BATCH_SIZE) {
+      const batch = keys.slice(start, start + DELETE_BATCH_SIZE);
+      await this.client.send(
+        new DeleteObjectsCommand({
+          Bucket: this.bucket,
+          Delete: { Objects: batch.map((Key) => ({ Key })), Quiet: true },
+        }),
+      );
+    }
+  }
+
+  /**
+   * Signs a URL the client can download the object from.
+   *
+   * @param key - The object key
+   * @param downloadName - When set, the browser saves the file under this name
+   */
+  getPresignedDownloadUrl(key: string, downloadName?: string): Promise<string> {
+    const command = new GetObjectCommand({
+      Bucket: this.bucket,
+      Key: key,
+      ...(downloadName
+        ? {
+            ResponseContentDisposition: `attachment; filename="${downloadName.replaceAll('"', "")}"`,
+          }
+        : {}),
+    });
+    return getSignedUrl(this.client, command, { expiresIn: this.presignExpiresInSeconds });
+  }
+
+  /** Signs a URL the client can upload one object to directly, bypassing the API. */
+  getPresignedUploadUrl(key: string, contentType: string): Promise<string> {
+    const command = new PutObjectCommand({
+      Bucket: this.bucket,
+      ContentType: contentType,
+      Key: key,
+    });
+    return getSignedUrl(this.client, command, { expiresIn: this.presignExpiresInSeconds });
+  }
+
+  /**
+   * The public URL of an object, for buckets exposed through a custom domain
+   * or r2.dev (`R2_PUBLIC_URL`). Undefined when the bucket is private.
+   */
+  getPublicUrl(key: string): string | undefined {
+    return this.publicUrl ? `${this.publicUrl}/${key}` : undefined;
+  }
+
+  /** Uploads an object and returns its key. */
+  async putObject({ body, contentType, key, metadata }: PutObjectInput): Promise<string> {
+    try {
+      await this.client.send(
+        new PutObjectCommand({
+          Body: body,
+          Bucket: this.bucket,
+          ContentType: contentType,
+          Key: key,
+          Metadata: metadata,
+        }),
+      );
+      this.logger.debug({ key }, "Object uploaded to R2");
+      return key;
+    } catch (error: unknown) {
+      this.logger.error({ error: handleError(error), key }, "R2 upload failed");
+      throw error;
+    }
+  }
+}

package/template/apps/api/src/user/dto/user.dto.ts

@@ -0,0 +1,26 @@
+import { Field, ID, ObjectType } from "@nestjs/graphql";
+import { UserRole } from "#src/generated/prisma/client.js";
+
+@ObjectType("User")
+export class UserDto {
+  @Field()
+  createdAt: Date;
+
+  @Field()
+  email: string;
+
+  @Field()
+  emailVerified: boolean;
+
+  @Field(() => ID)
+  id: string;
+
+  @Field(() => String, { nullable: true })
+  image: null | string;
+
+  @Field(() => String, { nullable: true })
+  name: null | string;
+
+  @Field(() => [UserRole])
+  role: UserRole[];
+}

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

@@ -0,0 +1,10 @@
+import { Module } from "@nestjs/common";
+import { UserResolver } from "#src/user/user.resolver.js";
+
+/**
+ * Exposes the signed-in user over GraphQL.
+ */
+@Module({
+  providers: [UserResolver],
+})
+export class UserModule {}

package/template/apps/api/src/user/user.resolver.spec.ts

@@ -0,0 +1,18 @@
+import { makeSession } from "#src/auth/testing/make-session.js";
+import { UserRole } from "#src/generated/prisma/client.js";
+import { UserResolver } from "#src/user/user.resolver.js";
+
+describe("userResolver", () => {
+  it("returns the session user as `me`", () => {
+    const resolver = new UserResolver();
+
+    const me = resolver.me(makeSession("user-42", { email: "me@example.com", name: "" }));
+
+    expect(me).toMatchObject({
+      email: "me@example.com",
+      id: "user-42",
+      name: null,
+      role: [UserRole.USER],
+    });
+  });
+});

package/template/apps/api/src/user/user.resolver.ts

@@ -0,0 +1,24 @@
+import { Query, Resolver } from "@nestjs/graphql";
+import { Session } from "@thallesp/nestjs-better-auth";
+import type { UserSession } from "#src/auth/types/auth.types.js";
+import { UserDto } from "#src/user/dto/user.dto.js";
+
+@Resolver(() => UserDto)
+export class UserResolver {
+  /**
+   * The signed-in user. Requires a session like every route that is not
+   * marked `@AllowAnonymous()`.
+   */
+  @Query(() => UserDto)
+  me(@Session() { user }: UserSession): UserDto {
+    return {
+      createdAt: user.createdAt,
+      email: user.email,
+      emailVerified: user.emailVerified,
+      id: user.id,
+      image: user.image ?? null,
+      name: user.name || null,
+      role: user.role,
+    };
+  }
+}