spoonfeeder 0.1.0

package/templates/recipes/feature-flags/tests/unit/shared/services/feature-flag.service.spec.ts

@@ -0,0 +1,36 @@
+import { FeatureFlagService } from '@/shared/services/feature-flag.service';
+import { ConfigService } from '@nestjs/config';
+
+describe('FeatureFlagService', () => {
+  let service: FeatureFlagService;
+  let configService: { get: jest.Mock };
+
+  beforeEach(() => {
+    configService = { get: jest.fn() };
+    service = new FeatureFlagService(configService as unknown as ConfigService);
+  });
+
+  it('should return true when the flag value is "true"', () => {
+    configService.get.mockReturnValue('true');
+
+    expect(service.isEnabled('MY_FLAG')).toBe(true);
+  });
+
+  it('should return true when the flag value is "1"', () => {
+    configService.get.mockReturnValue('1');
+
+    expect(service.isEnabled('MY_FLAG')).toBe(true);
+  });
+
+  it('should return false when the flag is not configured', () => {
+    configService.get.mockReturnValue(undefined);
+
+    expect(service.isEnabled('UNKNOWN_FLAG')).toBe(false);
+  });
+
+  it('should return the inverse for isDisabled()', () => {
+    configService.get.mockReturnValue('true');
+
+    expect(service.isDisabled('MY_FLAG')).toBe(false);
+  });
+});

package/templates/recipes/file-upload/README.md

@@ -0,0 +1,104 @@
+# File Upload
+
+Multipart file upload with validation and streaming for Fastify-based NestJS applications.
+
+## Links
+
+- [@fastify/multipart on npm](https://www.npmjs.com/package/@fastify/multipart)
+- [@fastify/multipart on GitHub](https://github.com/fastify/fastify-multipart)
+- [NestJS File Upload (Fastify)](https://docs.nestjs.com/techniques/file-upload#default-options-fastify)
+- [Presigned URL pattern for S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/PresignedUrlUploadObject.html)
+
+## Dependencies
+
+| Package              | Version | Purpose                                 |
+| -------------------- | ------- | --------------------------------------- |
+| `@fastify/multipart` | `9.0.3` | Multipart/form-data parsing for Fastify |
+
+## Environment Variables
+
+| Variable           | Default | Description           |
+| ------------------ | ------- | --------------------- |
+| `MAX_FILE_SIZE_MB` | `50`    | Max upload size in MB |
+
+## Setup
+
+Register the multipart plugin in `main.ts`:
+
+```typescript
+import multipart from '@fastify/multipart';
+
+async function bootstrap() {
+  const app = await NestFactory.create<NestFastifyApplication>(AppModule, new FastifyAdapter());
+
+  await app.register(multipart, {
+    limits: { fileSize: Number(process.env.MAX_FILE_SIZE_MB ?? 50) * 1024 * 1024 },
+  });
+
+  await app.listen(3000, '0.0.0.0');
+}
+```
+
+## Usage
+
+### Basic file upload
+
+```typescript
+@Controller('files')
+export class FileController {
+  @Post('upload')
+  @UseInterceptors(FileUploadInterceptor)
+  async upload(@Req() req: FastifyRequest) {
+    const file = (req as any).uploadedFile as UploadedFile;
+    // Process the file stream
+    return { filename: file.filename, mimetype: file.mimetype };
+  }
+}
+```
+
+### With validation
+
+```typescript
+@Post('upload')
+@UseInterceptors(FileUploadInterceptor)
+async upload(@Req() req: FastifyRequest) {
+  const pipe = new FileValidationPipe({
+    maxSizeBytes: 10 * 1024 * 1024,
+    allowedMimeTypes: ['image/jpeg', 'image/png'],
+  });
+
+  const file = pipe.transform((req as any).uploadedFile);
+  // file is validated — process the stream
+}
+```
+
+### Streaming to storage
+
+```typescript
+import { pipeline } from 'node:stream/promises';
+import { createWriteStream } from 'node:fs';
+
+@Post('upload')
+@UseInterceptors(FileUploadInterceptor)
+async upload(@Req() req: FastifyRequest) {
+  const file = (req as any).uploadedFile as UploadedFile;
+  await pipeline(file.file, createWriteStream(`./uploads/${file.filename}`));
+  return { saved: file.filename };
+}
+```
+
+### Presigned URL pattern
+
+For large files, prefer presigned URLs to avoid proxying through the application server:
+
+1. Client requests a presigned upload URL from your API
+2. Client uploads directly to the storage backend (S3, GCS, Azure Blob)
+3. Client notifies your API that the upload is complete
+4. API verifies the upload and processes metadata
+
+## Generated Files
+
+| File                                                 | Description                                  |
+| ---------------------------------------------------- | -------------------------------------------- |
+| `src/shared/pipes/file-validation.pipe.ts`           | Validates file MIME type and size            |
+| `src/shared/interceptors/file-upload.interceptor.ts` | Extracts multipart file from Fastify request |

package/templates/recipes/file-upload/src/shared/interceptors/file-upload.interceptor.ts

@@ -0,0 +1,33 @@
+import {
+  CallHandler,
+  ExecutionContext,
+  Injectable,
+  NestInterceptor,
+  BadRequestException,
+} from '@nestjs/common';
+import { Observable } from 'rxjs';
+import { FastifyRequest } from 'fastify';
+
+@Injectable()
+export class FileUploadInterceptor implements NestInterceptor {
+  async intercept(context: ExecutionContext, next: CallHandler): Promise<Observable<unknown>> {
+    const request = context.switchToHttp().getRequest<FastifyRequest>();
+
+    if (!request.isMultipart()) {
+      throw new BadRequestException('Expected multipart/form-data');
+    }
+
+    const file = await request.file();
+    if (!file) throw new BadRequestException('No file in request');
+
+    (request as any).uploadedFile = {
+      filename: file.filename,
+      mimetype: file.mimetype,
+      encoding: file.encoding,
+      file: file.file,
+      fieldname: file.fieldname,
+    };
+
+    return next.handle();
+  }
+}

package/templates/recipes/file-upload/src/shared/pipes/file-validation.pipe.ts

@@ -0,0 +1,45 @@
+import { PipeTransform, Injectable, BadRequestException } from '@nestjs/common';
+
+export interface UploadedFile {
+  filename: string;
+  mimetype: string;
+  encoding: string;
+  file: NodeJS.ReadableStream;
+  fieldname: string;
+}
+
+export interface FileValidationOptions {
+  maxSizeBytes?: number;
+  allowedMimeTypes?: string[];
+}
+
+@Injectable()
+export class FileValidationPipe implements PipeTransform {
+  private readonly maxSize: number;
+  private readonly allowedTypes: Set<string>;
+
+  constructor(options: FileValidationOptions = {}) {
+    this.maxSize = options.maxSizeBytes ?? 50 * 1024 * 1024;
+    this.allowedTypes = new Set(
+      options.allowedMimeTypes ?? [
+        'image/jpeg',
+        'image/png',
+        'image/gif',
+        'image/webp',
+        'application/pdf',
+        'application/msword',
+        'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+      ],
+    );
+  }
+
+  transform(file: UploadedFile): UploadedFile {
+    if (!file) throw new BadRequestException('No file uploaded');
+    // NOTE: mimetype comes from the client-supplied Content-Type header and can be spoofed.
+    // For production use, consider magic-byte validation (e.g. the 'file-type' npm package).
+    if (!this.allowedTypes.has(file.mimetype)) {
+      throw new BadRequestException(`File type ${file.mimetype} is not allowed`);
+    }
+    return file;
+  }
+}

package/templates/recipes/file-upload/tests/unit/shared/pipes/file-validation.pipe.spec.ts

@@ -0,0 +1,56 @@
+import { BadRequestException } from '@nestjs/common';
+import { FileValidationPipe, UploadedFile } from '@/shared/pipes/file-validation.pipe';
+
+describe('FileValidationPipe', () => {
+  function createFile(overrides: Partial<UploadedFile> = {}): UploadedFile {
+    return {
+      filename: 'test.png',
+      mimetype: 'image/png',
+      encoding: '7bit',
+      file: {} as NodeJS.ReadableStream,
+      fieldname: 'file',
+      ...overrides,
+    };
+  }
+
+  it('should pass through a file with a valid default mime type', () => {
+    const pipe = new FileValidationPipe();
+    const file = createFile({ mimetype: 'image/jpeg' });
+
+    const result = pipe.transform(file);
+    expect(result).toBe(file);
+  });
+
+  it('should throw BadRequestException when no file is provided', () => {
+    const pipe = new FileValidationPipe();
+    expect(() => pipe.transform(null as any)).toThrow(BadRequestException);
+    expect(() => pipe.transform(null as any)).toThrow('No file uploaded');
+  });
+
+  it('should throw BadRequestException for a disallowed mime type', () => {
+    const pipe = new FileValidationPipe();
+    const file = createFile({ mimetype: 'application/zip' });
+
+    expect(() => pipe.transform(file)).toThrow(BadRequestException);
+    expect(() => pipe.transform(file)).toThrow('File type application/zip is not allowed');
+  });
+
+  it('should accept custom allowed mime types', () => {
+    const pipe = new FileValidationPipe({
+      allowedMimeTypes: ['text/csv'],
+    });
+    const file = createFile({ mimetype: 'text/csv' });
+
+    const result = pipe.transform(file);
+    expect(result).toBe(file);
+  });
+
+  it('should reject default-allowed types when custom list overrides them', () => {
+    const pipe = new FileValidationPipe({
+      allowedMimeTypes: ['text/csv'],
+    });
+    const file = createFile({ mimetype: 'image/png' });
+
+    expect(() => pipe.transform(file)).toThrow(BadRequestException);
+  });
+});

package/templates/recipes/filtering/README.md

@@ -0,0 +1,43 @@
+# Filtering and Sorting
+
+Reusable filter and sort DTOs for list endpoints.
+
+## Links
+
+- [NestJS Techniques: Serialization](https://docs.nestjs.com/techniques/serialization)
+- [class-validator on npm](https://www.npmjs.com/package/class-validator)
+
+## Dependencies
+
+| Package             | Version  | Purpose                   |
+| ------------------- | -------- | ------------------------- |
+| `class-validator`   | `0.14.1` | DTO validation decorators |
+| `class-transformer` | `0.5.1`  | DTO transformation        |
+
+## Usage
+
+```typescript
+import { BaseFilterDto, SortDto } from '@/shared/dto/filter.dto';
+
+class UserFilterDto extends BaseFilterDto {
+  @IsOptional()
+  @IsString()
+  role?: string;
+
+  @IsOptional()
+  @IsBoolean()
+  @Type(() => Boolean)
+  isActive?: boolean;
+}
+
+@Get()
+async findAll(@Query() filter: UserFilterDto): Promise<User[]> {
+  return this.userService.findAll(filter);
+}
+```
+
+## Generated Files
+
+| File                           | Description               |
+| ------------------------------ | ------------------------- |
+| `src/shared/dto/filter.dto.ts` | Base filter and sort DTOs |

package/templates/recipes/filtering/src/shared/dto/filter.dto.ts

@@ -0,0 +1,49 @@
+import { IsEnum, IsOptional, IsString } from 'class-validator';
+import { ApiPropertyOptional } from '@nestjs/swagger';
+
+export enum SortOrder {
+  ASC = 'asc',
+  DESC = 'desc',
+}
+
+export class SortDto {
+  /** Consumers MUST validate sortBy against an allowlist of allowed column names before use in queries. */
+  @ApiPropertyOptional({ description: 'Field to sort by' })
+  @IsOptional()
+  @IsString()
+  sortBy?: string;
+
+  @ApiPropertyOptional({ enum: SortOrder, default: SortOrder.ASC })
+  @IsOptional()
+  @IsEnum(SortOrder)
+  sortOrder: SortOrder = SortOrder.ASC;
+}
+
+export class BaseFilterDto extends SortDto {
+  @ApiPropertyOptional({ description: 'Search term applied across searchable fields' })
+  @IsOptional()
+  @IsString()
+  search?: string;
+
+  /**
+   * Build a where clause from the filter properties.
+   * Override in subclasses to add domain-specific filters.
+   */
+  toWhere(): Record<string, unknown> {
+    const where: Record<string, unknown> = {};
+
+    if (this.search) {
+      where._search = this.search;
+    }
+
+    return where;
+  }
+
+  toOrder(): Record<string, SortOrder> | undefined {
+    if (!this.sortBy) {
+      return undefined;
+    }
+
+    return { [this.sortBy]: this.sortOrder };
+  }
+}

package/templates/recipes/filtering/tests/unit/shared/dto/filter.dto.spec.ts

@@ -0,0 +1,38 @@
+import { SortOrder, SortDto, BaseFilterDto } from '../../../../src/shared/dto/filter.dto';
+
+describe('SortDto', () => {
+  it('should default sortOrder to ASC', () => {
+    const dto = new SortDto();
+    expect(dto.sortOrder).toBe(SortOrder.ASC);
+  });
+
+  it('should leave sortBy undefined by default', () => {
+    const dto = new SortDto();
+    expect(dto.sortBy).toBeUndefined();
+  });
+});
+
+describe('BaseFilterDto', () => {
+  it('should produce an empty where clause when no search is set', () => {
+    const dto = new BaseFilterDto();
+    expect(dto.toWhere()).toEqual({});
+  });
+
+  it('should include _search in where clause when search is set', () => {
+    const dto = new BaseFilterDto();
+    dto.search = 'hello';
+    expect(dto.toWhere()).toEqual({ _search: 'hello' });
+  });
+
+  it('should return undefined order when sortBy is not set', () => {
+    const dto = new BaseFilterDto();
+    expect(dto.toOrder()).toBeUndefined();
+  });
+
+  it('should produce correct order object when sortBy is set', () => {
+    const dto = new BaseFilterDto();
+    dto.sortBy = 'name';
+    dto.sortOrder = SortOrder.DESC;
+    expect(dto.toOrder()).toEqual({ name: 'desc' });
+  });
+});

package/templates/recipes/graceful-shutdown/README.md

@@ -0,0 +1,60 @@
+# Graceful Shutdown
+
+Graceful application shutdown using NestJS lifecycle events.
+
+## Links
+
+- [NestJS Lifecycle Events](https://docs.nestjs.com/fundamentals/lifecycle-events)
+- [NestJS Application Shutdown](https://docs.nestjs.com/fundamentals/lifecycle-events#application-shutdown)
+
+## Dependencies
+
+No additional dependencies required. Uses built-in NestJS lifecycle hooks.
+
+| Package | Version | Purpose                          |
+| ------- | ------- | -------------------------------- |
+| (none)  | -       | Built-in NestJS lifecycle events |
+
+## Environment Variables
+
+| Variable              | Default | Description                        |
+| --------------------- | ------- | ---------------------------------- |
+| `SHUTDOWN_TIMEOUT_MS` | `10000` | Max wait time for graceful shutdown |
+
+## Usage
+
+Enable shutdown hooks in `main.ts`:
+
+```typescript
+const app = await NestFactory.create<NestFastifyApplication>(AppModule, new FastifyAdapter());
+
+app.enableShutdownHooks();
+
+await app.listen(3000, '0.0.0.0');
+```
+
+Register cleanup functions with `ShutdownService`:
+
+```typescript
+import { ShutdownService } from '@/shared/lifecycle/shutdown.service';
+
+@Injectable()
+export class DatabaseService implements OnModuleInit {
+  constructor(private readonly shutdownService: ShutdownService) {}
+
+  onModuleInit(): void {
+    this.shutdownService.registerCleanup(async () => {
+      await this.pool.end();
+    });
+  }
+}
+```
+
+The `ShutdownService` reads `SHUTDOWN_TIMEOUT_MS` from the environment. If cleanup
+functions take longer than this timeout, the shutdown proceeds and logs an error.
+
+## Generated Files
+
+| File                                       | Description                                                   |
+| ------------------------------------------ | ------------------------------------------------------------- |
+| `src/shared/lifecycle/shutdown.service.ts` | Shutdown service with configurable timeout and cleanup registry |

package/templates/recipes/graceful-shutdown/src/shared/lifecycle/shutdown.service.ts

@@ -0,0 +1,52 @@
+import { Injectable, OnApplicationShutdown, Logger } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+
+const DEFAULT_SHUTDOWN_TIMEOUT_MS = 10_000;
+
+@Injectable()
+export class ShutdownService implements OnApplicationShutdown {
+  private readonly logger = new Logger(ShutdownService.name);
+  private readonly cleanupFns: (() => Promise<void>)[] = [];
+  private readonly timeoutMs: number;
+
+  constructor(configService?: ConfigService) {
+    this.timeoutMs =
+      configService?.get<number>('SHUTDOWN_TIMEOUT_MS', DEFAULT_SHUTDOWN_TIMEOUT_MS) ??
+      DEFAULT_SHUTDOWN_TIMEOUT_MS;
+  }
+
+  registerCleanup(fn: () => Promise<void>): void {
+    this.cleanupFns.push(fn);
+  }
+
+  async onApplicationShutdown(signal?: string): Promise<void> {
+    this.logger.log(`Shutting down (signal: ${signal ?? 'none'})...`);
+
+    const cleanup = async () => {
+      for (const fn of this.cleanupFns) {
+        try {
+          await fn();
+        } catch (error) {
+          this.logger.error(
+            `Cleanup failed: ${error instanceof Error ? error.message : String(error)}`,
+          );
+        }
+      }
+    };
+
+    const timeout = new Promise<void>((_, reject) =>
+      setTimeout(
+        () => reject(new Error(`Shutdown timed out after ${this.timeoutMs}ms`)),
+        this.timeoutMs,
+      ),
+    );
+
+    try {
+      await Promise.race([cleanup(), timeout]);
+    } catch (error) {
+      this.logger.error(error instanceof Error ? error.message : String(error));
+    }
+
+    this.logger.log('Shutdown complete');
+  }
+}

package/templates/recipes/graceful-shutdown/tests/unit/shared/lifecycle/shutdown.service.spec.ts

@@ -0,0 +1,52 @@
+import { ConfigService } from '@nestjs/config';
+import { ShutdownService } from '../../../../src/shared/lifecycle/shutdown.service';
+
+describe('ShutdownService', () => {
+  let service: ShutdownService;
+
+  beforeEach(() => {
+    service = new ShutdownService();
+  });
+
+  it('should be defined', () => {
+    expect(service).toBeDefined();
+  });
+
+  it('should execute registered cleanup functions on shutdown', async () => {
+    const fn1 = jest.fn().mockResolvedValue(undefined);
+    const fn2 = jest.fn().mockResolvedValue(undefined);
+
+    service.registerCleanup(fn1);
+    service.registerCleanup(fn2);
+
+    await service.onApplicationShutdown('SIGTERM');
+
+    expect(fn1).toHaveBeenCalledTimes(1);
+    expect(fn2).toHaveBeenCalledTimes(1);
+  });
+
+  it('should continue cleanup even if one function throws', async () => {
+    const failing = jest.fn().mockRejectedValue(new Error('boom'));
+    const succeeding = jest.fn().mockResolvedValue(undefined);
+
+    service.registerCleanup(failing);
+    service.registerCleanup(succeeding);
+
+    await service.onApplicationShutdown('SIGINT');
+
+    expect(failing).toHaveBeenCalled();
+    expect(succeeding).toHaveBeenCalled();
+  });
+
+  it('should read SHUTDOWN_TIMEOUT_MS from ConfigService', () => {
+    const configService = new ConfigService({ SHUTDOWN_TIMEOUT_MS: 5000 });
+    const svc = new ShutdownService(configService);
+
+    expect(svc).toBeDefined();
+  });
+
+  it('should use the default timeout when ConfigService is not provided', () => {
+    const svc = new ShutdownService();
+    expect(svc).toBeDefined();
+  });
+});

package/templates/recipes/graphql-mercurius/README.md

@@ -0,0 +1,37 @@
+# GraphQL with Mercurius
+
+GraphQL API using Mercurius adapter for Fastify-based NestJS applications.
+
+## Links
+
+- [NestJS GraphQL Quick Start](https://docs.nestjs.com/graphql/quick-start)
+- [Mercurius Documentation](https://mercurius.dev)
+- [@nestjs/graphql on npm](https://www.npmjs.com/package/@nestjs/graphql)
+- [@nestjs/mercurius on npm](https://www.npmjs.com/package/@nestjs/mercurius)
+- [Mercurius on GitHub](https://github.com/mercurius-js/mercurius)
+
+## Dependencies
+
+| Package             | Version   | Purpose                      |
+| ------------------- | --------- | ---------------------------- |
+| `@nestjs/graphql`   | `13.0.4`  | NestJS GraphQL integration   |
+| `@nestjs/mercurius` | `13.0.4`  | Mercurius adapter for NestJS |
+| `mercurius`         | `15.1.0`  | Fastify GraphQL adapter      |
+| `graphql`           | `16.10.0` | GraphQL runtime              |
+
+## Usage
+
+```typescript
+import { GraphqlModule } from '@/infrastructure/graphql/graphql.module';
+
+@Module({
+  imports: [GraphqlModule],
+})
+export class AppModule {}
+```
+
+## Generated Files
+
+| File                                           | Description                                                      |
+| ---------------------------------------------- | ---------------------------------------------------------------- |
+| `src/infrastructure/graphql/graphql.module.ts` | GraphQL module configured with Mercurius and code-first approach |

package/templates/recipes/graphql-mercurius/src/infrastructure/graphql/graphql.module.ts

@@ -0,0 +1,18 @@
+import { Module } from '@nestjs/common';
+import { GraphQLModule } from '@nestjs/graphql';
+import { MercuriusDriver, MercuriusDriverConfig } from '@nestjs/mercurius';
+import { join } from 'node:path';
+
+@Module({
+  imports: [
+    GraphQLModule.forRoot<MercuriusDriverConfig>({
+      driver: MercuriusDriver,
+      autoSchemaFile: join(process.cwd(), 'schema.gql'),
+      sortSchema: true,
+      graphiql: process.env.NODE_ENV !== 'production',
+      subscription: true,
+      path: '/graphql',
+    }),
+  ],
+})
+export class GraphqlModule {}

package/templates/recipes/graphql-mercurius/tests/unit/infrastructure/graphql/graphql.module.spec.ts

@@ -0,0 +1,12 @@
+import { GraphqlModule } from '../../../../src/infrastructure/graphql/graphql.module';
+
+describe('GraphqlModule', () => {
+  it('should be defined', () => {
+    expect(GraphqlModule).toBeDefined();
+  });
+
+  it('should be a class that can be referenced as a module', () => {
+    expect(typeof GraphqlModule).toBe('function');
+    expect(GraphqlModule.name).toBe('GraphqlModule');
+  });
+});

package/templates/recipes/health-checks/README.md

@@ -0,0 +1,35 @@
+# Health Checks
+
+Application health monitoring using Terminus for NestJS applications.
+
+## Links
+
+- [NestJS Terminus Recipe](https://docs.nestjs.com/recipes/terminus)
+- [@nestjs/terminus on npm](https://www.npmjs.com/package/@nestjs/terminus)
+- [@nestjs/terminus on GitHub](https://github.com/nestjs/terminus)
+
+## Dependencies
+
+| Package            | Version  | Purpose                           |
+| ------------------ | -------- | --------------------------------- |
+| `@nestjs/terminus` | `10.2.3` | Health check utilities for NestJS |
+
+## Usage
+
+```typescript
+import { HealthModule } from '@/shared/health/health.module';
+
+@Module({
+  imports: [HealthModule],
+})
+export class AppModule {}
+
+// Access health checks at GET /health
+```
+
+## Generated Files
+
+| File                                     | Description                                             |
+| ---------------------------------------- | ------------------------------------------------------- |
+| `src/shared/health/health.module.ts`     | HealthModule registering the health controller          |
+| `src/shared/health/health.controller.ts` | Health check controller with disk and memory indicators |