spoonfeeder 0.1.0

package/templates/recipes/seq2/src/infrastructure/logging/seq.transport.ts

@@ -0,0 +1,57 @@
+import { Injectable, OnModuleDestroy } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { Logger as SeqLogger } from 'seq-logging';
+
+type SeqLogLevel = 'Verbose' | 'Debug' | 'Information' | 'Warning' | 'Error' | 'Fatal';
+
+interface SeqTransportOptions {
+  serverUrl: string;
+  apiKey?: string;
+  batchingDelay?: number;
+}
+
+@Injectable()
+export class SeqTransport implements OnModuleDestroy {
+  private readonly logger: SeqLogger;
+
+  constructor(private readonly config: ConfigService) {
+    const serverUrl = this.config.getOrThrow<string>('SEQ_SERVER_URL');
+
+    this.logger = new SeqLogger({
+      serverUrl,
+      apiKey: this.config.get<string>('SEQ_API_KEY'),
+      onError: (err: Error) => {
+        console.error('[SeqTransport] Failed to ship log event:', err.message);
+      },
+    });
+  }
+
+  log(level: SeqLogLevel, messageTemplate: string, properties?: Record<string, unknown>): void {
+    this.logger.emit({
+      timestamp: new Date(),
+      level,
+      messageTemplate,
+      properties,
+    });
+  }
+
+  info(messageTemplate: string, properties?: Record<string, unknown>): void {
+    this.log('Information', messageTemplate, properties);
+  }
+
+  warn(messageTemplate: string, properties?: Record<string, unknown>): void {
+    this.log('Warning', messageTemplate, properties);
+  }
+
+  error(messageTemplate: string, properties?: Record<string, unknown>): void {
+    this.log('Error', messageTemplate, properties);
+  }
+
+  debug(messageTemplate: string, properties?: Record<string, unknown>): void {
+    this.log('Debug', messageTemplate, properties);
+  }
+
+  async onModuleDestroy(): Promise<void> {
+    await this.logger.close();
+  }
+}

package/templates/recipes/seq2/tests/unit/infrastructure/logging/seq.transport.spec.ts

@@ -0,0 +1,53 @@
+import { ConfigService } from '@nestjs/config';
+
+jest.mock('seq-logging', () => ({
+  Logger: jest.fn().mockImplementation(() => ({
+    emit: jest.fn(),
+    close: jest.fn().mockResolvedValue(undefined),
+  })),
+}));
+
+import { SeqTransport } from '../../../../src/infrastructure/logging/seq.transport';
+
+describe('SeqTransport', () => {
+  let transport: SeqTransport;
+
+  beforeEach(() => {
+    const configService = new ConfigService({
+      SEQ_SERVER_URL: 'http://localhost:5341',
+      SEQ_API_KEY: 'test-api-key',
+    });
+
+    transport = new SeqTransport(configService);
+  });
+
+  it('should create a Seq logger on construction', () => {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { Logger } = require('seq-logging');
+    expect(Logger).toHaveBeenCalledWith(
+      expect.objectContaining({
+        serverUrl: 'http://localhost:5341',
+        apiKey: 'test-api-key',
+      }),
+    );
+  });
+
+  it('should emit info-level log events', () => {
+    transport.info('User {UserId} logged in', { UserId: '42' });
+    // Access the internal mock to verify emit was called
+    const loggerInstance = (transport as any).logger;
+    expect(loggerInstance.emit).toHaveBeenCalledWith(
+      expect.objectContaining({
+        level: 'Information',
+        messageTemplate: 'User {UserId} logged in',
+        properties: { UserId: '42' },
+      }),
+    );
+  });
+
+  it('should close the logger on module destroy', async () => {
+    const loggerInstance = (transport as any).logger;
+    await transport.onModuleDestroy();
+    expect(loggerInstance.close).toHaveBeenCalled();
+  });
+});

package/templates/recipes/serialization-groups/README.md

@@ -0,0 +1,105 @@
+# Response Serialization Groups
+
+Return different field sets based on role or endpoint using class-transformer decorators.
+
+## Links
+
+- [NestJS Serialization Documentation](https://docs.nestjs.com/techniques/serialization)
+- [class-transformer on npm](https://www.npmjs.com/package/class-transformer)
+- [class-transformer @Expose and @Exclude](https://github.com/typestack/class-transformer#exposing-getters-and-method-return-values)
+
+## Dependencies
+
+No additional dependencies. Uses `class-transformer` which is already included in the base template.
+
+## Usage
+
+### Basic Serialization
+
+Apply `Serialize(DtoClass)` to controller methods to control which fields are returned. Only properties marked with `@Expose()` are included in the response.
+
+```typescript
+import { Serialize } from '@/shared/interceptors/serialize.interceptor';
+import { Expose, Exclude } from 'class-transformer';
+
+// Define a response DTO
+export class UserResponseDto {
+  @Expose()
+  id: string;
+
+  @Expose()
+  name: string;
+
+  @Expose()
+  email: string;
+
+  // password is NOT exposed — it will be excluded from responses
+}
+
+// Apply to controller method
+@Controller('users')
+export class UserController {
+  @Get(':id')
+  @Serialize(UserResponseDto)
+  findOne(@Param('id') id: string) {
+    // Even if the service returns a full user entity with password,
+    // only id, name, and email will be in the response
+    return this.userService.findOne(id);
+  }
+}
+```
+
+### Groups for Role-Based Visibility
+
+Use the `groups` option on `@Expose()` to show different fields based on the requester's role:
+
+```typescript
+export class UserDetailDto {
+  @Expose()
+  id: string;
+
+  @Expose()
+  name: string;
+
+  @Expose({ groups: ['admin', 'self'] })
+  email: string;
+
+  @Expose({ groups: ['admin'] })
+  role: string;
+
+  @Expose({ groups: ['admin'] })
+  createdAt: Date;
+}
+```
+
+To use groups, pass them when calling `plainToInstance`:
+
+```typescript
+plainToInstance(UserDetailDto, user, {
+  excludeExtraneousValues: true,
+  groups: ['admin'],
+});
+```
+
+### Using @Exclude()
+
+You can also use `@Exclude()` to explicitly exclude specific fields while including everything else:
+
+```typescript
+export class UserDto {
+  id: string;
+  name: string;
+
+  @Exclude()
+  password: string;
+
+  @Exclude()
+  internalNotes: string;
+}
+```
+
+## Generated Files
+
+| File                                               | Description                                          |
+| -------------------------------------------------- | ---------------------------------------------------- |
+| `src/shared/interceptors/serialize.interceptor.ts` | Serialize() decorator and SerializeInterceptor class |

package/templates/recipes/serialization-groups/src/shared/interceptors/serialize.interceptor.ts

@@ -0,0 +1,29 @@
+import {
+  CallHandler,
+  ExecutionContext,
+  Injectable,
+  NestInterceptor,
+  UseInterceptors,
+} from '@nestjs/common';
+import { Observable } from 'rxjs';
+import { map } from 'rxjs/operators';
+import { plainToInstance, ClassConstructor } from 'class-transformer';
+
+export function Serialize<T>(dto: ClassConstructor<T>) {
+  return UseInterceptors(new SerializeInterceptor(dto));
+}
+
+@Injectable()
+class SerializeInterceptor<T> implements NestInterceptor {
+  constructor(private readonly dto: ClassConstructor<T>) {}
+
+  intercept(context: ExecutionContext, next: CallHandler): Observable<T> {
+    return next.handle().pipe(
+      map((data) =>
+        plainToInstance(this.dto, data, {
+          excludeExtraneousValues: true,
+        }),
+      ),
+    );
+  }
+}

package/templates/recipes/serialization-groups/tests/unit/shared/interceptors/serialize.interceptor.spec.ts

@@ -0,0 +1,48 @@
+import { Expose } from 'class-transformer';
+import { of } from 'rxjs';
+import { CallHandler, ExecutionContext } from '@nestjs/common';
+
+class UserDto {
+  @Expose() id: number;
+  @Expose() name: string;
+  // password is intentionally not exposed
+}
+
+// Inline the interceptor logic to avoid pulling in UseInterceptors decorator side effects
+import { plainToInstance } from 'class-transformer';
+
+function serializeWith<T>(dto: new () => T, data: unknown): T {
+  return plainToInstance(dto, data, { excludeExtraneousValues: true });
+}
+
+describe('SerializeInterceptor', () => {
+  it('should strip properties not decorated with @Expose', () => {
+    const raw = { id: 1, name: 'Alice', password: 'secret' };
+    const result = serializeWith(UserDto, raw);
+
+    expect(result).toHaveProperty('id', 1);
+    expect(result).toHaveProperty('name', 'Alice');
+    expect(result).not.toHaveProperty('password');
+  });
+
+  it('should handle an array of objects and serialize each element', () => {
+    const raw = [
+      { id: 1, name: 'Alice', password: 's1' },
+      { id: 2, name: 'Bob', password: 's2' },
+    ];
+    const results = raw.map((item) => serializeWith(UserDto, item));
+
+    expect(results).toHaveLength(2);
+    expect(results[0]).not.toHaveProperty('password');
+    expect(results[1]).toHaveProperty('name', 'Bob');
+  });
+
+  it('should return undefined for non-exposed fields even if source has them', () => {
+    const raw = { id: 10, name: 'Charlie', email: 'charlie@example.com', role: 'admin' };
+    const result = serializeWith(UserDto, raw);
+
+    expect(result.id).toBe(10);
+    expect((result as any).email).toBeUndefined();
+    expect((result as any).role).toBeUndefined();
+  });
+});

package/templates/recipes/soft-delete/README.md

@@ -0,0 +1,71 @@
+# Soft Delete
+
+Mark records as deleted instead of removing them from the database.
+
+## Links
+
+- [TypeORM @DeleteDateColumn](https://typeorm.io/decorator-reference#deletedatecolumn)
+- [TypeORM Soft Delete](https://typeorm.io/delete-query-builder#soft-delete)
+
+## Dependencies
+
+None — uses TypeORM decorators (already included with a TypeORM recipe) or can be adapted for Prisma.
+
+## Usage
+
+### TypeORM
+
+Extend `SoftDeletableEntity` to add soft-delete support to any entity:
+
+```typescript
+import { Entity, Column } from 'typeorm';
+import { SoftDeletableEntity } from '@/shared/entities/soft-deletable.entity';
+
+@Entity()
+export class User extends SoftDeletableEntity {
+  @Column()
+  name: string;
+}
+```
+
+Use `softRemove()` or `softDelete()` instead of `remove()` or `delete()`:
+
+```typescript
+await this.userRepository.softRemove(user);
+await this.userRepository.softDelete(user.id);
+```
+
+Recover a soft-deleted record:
+
+```typescript
+await this.userRepository.recover(user);
+```
+
+Query including soft-deleted records:
+
+```typescript
+const users = await this.userRepository.find({ withDeleted: true });
+```
+
+Use the `@WithDeleted()` decorator to set metadata for interceptors or guards that need to include deleted records.
+
+### Prisma Alternative
+
+For Prisma, implement soft delete via middleware:
+
+```typescript
+prisma.$use(async (params, next) => {
+  if (params.action === 'delete') {
+    params.action = 'update';
+    params.args.data = { deletedAt: new Date() };
+  }
+  return next(params);
+});
+```
+
+## Generated Files
+
+| File                                              | Description                                      |
+| ------------------------------------------------- | ------------------------------------------------ |
+| `src/shared/entities/soft-deletable.entity.ts`    | Abstract base entity with soft-delete columns    |
+| `src/shared/decorators/with-deleted.decorator.ts` | Metadata decorator for including deleted records |

package/templates/recipes/soft-delete/src/shared/decorators/with-deleted.decorator.ts

@@ -0,0 +1,4 @@
+import { SetMetadata } from '@nestjs/common';
+
+export const WITH_DELETED_KEY = 'WITH_DELETED';
+export const WithDeleted = () => SetMetadata(WITH_DELETED_KEY, true);

package/templates/recipes/soft-delete/src/shared/entities/soft-deletable.entity.ts

@@ -0,0 +1,20 @@
+import {
+  CreateDateColumn,
+  UpdateDateColumn,
+  DeleteDateColumn,
+  PrimaryGeneratedColumn,
+} from 'typeorm';
+
+export abstract class SoftDeletableEntity {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @CreateDateColumn()
+  createdAt: Date;
+
+  @UpdateDateColumn()
+  updatedAt: Date;
+
+  @DeleteDateColumn()
+  deletedAt: Date | null;
+}

package/templates/recipes/soft-delete/tests/unit/shared/entities/soft-deletable.entity.spec.ts

@@ -0,0 +1,35 @@
+import 'reflect-metadata';
+import { SoftDeletableEntity } from '../../../../src/shared/entities/soft-deletable.entity';
+import { getMetadataArgsStorage } from 'typeorm';
+
+class TestEntity extends SoftDeletableEntity {
+  name: string;
+}
+
+describe('SoftDeletableEntity', () => {
+  it('should have a deletedAt column marked as DeleteDateColumn', () => {
+    const columns = getMetadataArgsStorage().columns.filter(
+      (col) => col.target === SoftDeletableEntity,
+    );
+    const deletedAtColumn = columns.find((col) => col.propertyName === 'deletedAt');
+
+    expect(deletedAtColumn).toBeDefined();
+    expect(deletedAtColumn!.mode).toBe('deleteDate');
+  });
+
+  it('should initialize deletedAt as undefined on a new instance', () => {
+    const entity = new TestEntity();
+
+    expect(entity.deletedAt).toBeUndefined();
+  });
+
+  it('should have uuid-based primary key generation', () => {
+    const generatedColumns = getMetadataArgsStorage().generations.filter(
+      (gen) => gen.target === SoftDeletableEntity,
+    );
+    const idGeneration = generatedColumns.find((gen) => gen.propertyName === 'id');
+
+    expect(idGeneration).toBeDefined();
+    expect(idGeneration!.strategy).toBe('uuid');
+  });
+});

package/templates/recipes/sse/README.md

@@ -0,0 +1,43 @@
+# Server-Sent Events
+
+Lightweight real-time server-to-client streaming using the built-in NestJS `@Sse()` decorator.
+
+## Links
+
+- [NestJS Server-Sent Events](https://docs.nestjs.com/techniques/server-sent-events)
+
+## Dependencies
+
+None — SSE support is built into NestJS.
+
+## Usage
+
+```typescript
+import { SseController } from '@/shared/gateways/events.sse.controller';
+
+@Module({
+  controllers: [SseController],
+})
+export class AppModule {}
+```
+
+Connect from a client:
+
+```typescript
+const source = new EventSource('http://localhost:3000/events/stream');
+source.addEventListener('notification', (event) => {
+  console.log(JSON.parse(event.data));
+});
+```
+
+Push events from a service by injecting `SseController`:
+
+```typescript
+this.sseController.emit('notification', { message: 'Hello' });
+```
+
+## Generated Files
+
+| File                                           | Description                               |
+| ---------------------------------------------- | ----------------------------------------- |
+| `src/shared/gateways/events.sse.controller.ts` | SSE controller with Subject-based emitter |

package/templates/recipes/sse/src/shared/gateways/events.sse.controller.ts

@@ -0,0 +1,21 @@
+import { Controller, Sse, MessageEvent } from '@nestjs/common';
+import { Observable, Subject, map } from 'rxjs';
+
+@Controller('events')
+export class SseController {
+  private readonly events$ = new Subject<{ type: string; data: unknown }>();
+
+  @Sse('stream')
+  stream(): Observable<MessageEvent> {
+    return this.events$.pipe(
+      map((event) => ({
+        type: event.type,
+        data: JSON.stringify(event.data),
+      })),
+    );
+  }
+
+  emit(type: string, data: unknown): void {
+    this.events$.next({ type, data });
+  }
+}

package/templates/recipes/sse/tests/unit/shared/gateways/events.sse.controller.spec.ts

@@ -0,0 +1,32 @@
+import { SseController } from '@/shared/gateways/events.sse.controller';
+
+describe('SseController', () => {
+  let controller: SseController;
+
+  beforeEach(() => {
+    controller = new SseController();
+  });
+
+  it('should be defined', () => {
+    expect(controller).toBeDefined();
+  });
+
+  it('should return an observable from stream()', () => {
+    const stream$ = controller.stream();
+
+    expect(stream$).toBeDefined();
+    expect(typeof stream$.subscribe).toBe('function');
+  });
+
+  it('should emit events that are received by the stream', (done) => {
+    const stream$ = controller.stream();
+
+    stream$.subscribe((event) => {
+      expect(event.type).toBe('user.created');
+      expect(event.data).toBe(JSON.stringify({ id: 1 }));
+      done();
+    });
+
+    controller.emit('user.created', { id: 1 });
+  });
+});

package/templates/recipes/swagger/README.md

@@ -0,0 +1,42 @@
+# Swagger / OpenAPI
+
+API documentation using Swagger UI and OpenAPI specification for NestJS applications.
+
+## Links
+
+- [NestJS OpenAPI Documentation](https://docs.nestjs.com/openapi/introduction)
+- [@nestjs/swagger on npm](https://www.npmjs.com/package/@nestjs/swagger)
+- [@nestjs/swagger on GitHub](https://github.com/nestjs/swagger)
+- [Swagger UI](https://swagger.io/tools/swagger-ui/)
+
+## Dependencies
+
+| Package           | Version | Purpose                            |
+| ----------------- | ------- | ---------------------------------- |
+| `@nestjs/swagger` | `8.1.0` | NestJS Swagger/OpenAPI integration |
+
+## Environment Variables
+
+| Variable          | Default    | Description                  |
+| ----------------- | ---------- | ---------------------------- |
+| `SWAGGER_ENABLED` | `true`     | Enable or disable Swagger UI |
+| `SWAGGER_PATH`    | `api/docs` | URL path for Swagger UI      |
+
+## Usage
+
+```typescript
+// In main.ts
+import { setupSwagger } from '@/main.swagger';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  setupSwagger(app);
+  await app.listen(3000);
+}
+```
+
+## Generated Files
+
+| File                  | Description                                                    |
+| --------------------- | -------------------------------------------------------------- |
+| `src/main.swagger.ts` | Swagger setup function using DocumentBuilder and SwaggerModule |

package/templates/recipes/swagger/src/main.swagger.ts.ejs

@@ -0,0 +1,20 @@
+import { INestApplication } from '@nestjs/common';
+import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
+
+export function setupSwagger(app: INestApplication): void {
+  if (process.env.SWAGGER_ENABLED === 'false') return;
+
+  const config = new DocumentBuilder()
+    .setTitle('<%= name %>')
+    .setDescription('The <%= name %> API documentation')
+    .setVersion('1.0')
+    .addBearerAuth()
+    .build();
+
+  const document = SwaggerModule.createDocument(app, config);
+  SwaggerModule.setup(process.env.SWAGGER_PATH ?? 'api/docs', app, document, {
+    swaggerOptions: {
+      persistAuthorization: true,
+    },
+  });
+}

package/templates/recipes/swagger/tests/unit/main.swagger.spec.ts

@@ -0,0 +1,5 @@
+describe('Swagger Setup', () => {
+  it('should be configurable via environment', () => {
+    expect(process.env.SWAGGER_ENABLED).toBeUndefined(); // Not set in test
+  });
+});

package/templates/recipes/throttler/README.md

@@ -0,0 +1,49 @@
+# Throttler (Rate Limiting)
+
+Rate limiting for NestJS using the official throttler module.
+
+## Links
+
+- [NestJS Rate Limiting](https://docs.nestjs.com/security/rate-limiting)
+- [@nestjs/throttler on npm](https://www.npmjs.com/package/@nestjs/throttler)
+- [@nestjs/throttler on GitHub](https://github.com/nestjs/throttler)
+
+## Dependencies
+
+| Package             | Version | Purpose                        |
+| ------------------- | ------- | ------------------------------ |
+| `@nestjs/throttler` | `6.3.0` | Rate limiting guard and module |
+
+## Usage
+
+```typescript
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { ThrottlerModule } from '@nestjs/throttler';
+import { throttlerConfigFactory } from '@/shared/guards/throttle.config';
+
+@Module({
+  imports: [
+    ThrottlerModule.forRootAsync({
+      imports: [ConfigModule],
+      inject: [ConfigService],
+      useFactory: throttlerConfigFactory,
+    }),
+  ],
+  providers: [{ provide: APP_GUARD, useClass: ThrottlerGuard }],
+})
+export class AppModule {}
+```
+
+Skip throttling on specific routes:
+
+```typescript
+@SkipThrottle()
+@Get('health')
+healthCheck() { return { ok: true }; }
+```
+
+## Generated Files
+
+| File                                   | Description                                                   |
+| -------------------------------------- | ------------------------------------------------------------- |
+| `src/shared/guards/throttle.config.ts` | Throttler module configuration with multiple rate limit tiers |

package/templates/recipes/throttler/src/shared/guards/throttle.config.ts

@@ -0,0 +1,33 @@
+import { ConfigService } from '@nestjs/config';
+import { ThrottlerModuleOptions } from '@nestjs/throttler';
+
+/**
+ * Rate limiting configuration with multiple tiers.
+ *
+ * Each tier reads its values from environment variables with sensible defaults:
+ * - THROTTLE_SHORT_TTL / THROTTLE_SHORT_LIMIT  (burst protection, default 1 s / 10 req)
+ * - THROTTLE_MEDIUM_TTL / THROTTLE_MEDIUM_LIMIT (default 10 s / 100 req)
+ * - THROTTLE_LONG_TTL / THROTTLE_LONG_LIMIT     (default 60 s / 1 000 req)
+ *
+ * The legacy THROTTLE_TTL and THROTTLE_LIMIT variables override the "long" tier
+ * to stay backwards-compatible with the env vars declared in the recipe definition.
+ */
+export const throttlerConfigFactory = (configService: ConfigService): ThrottlerModuleOptions => ({
+  throttlers: [
+    {
+      name: 'short',
+      ttl: configService.get<number>('THROTTLE_SHORT_TTL', 1000),
+      limit: configService.get<number>('THROTTLE_SHORT_LIMIT', 10),
+    },
+    {
+      name: 'medium',
+      ttl: configService.get<number>('THROTTLE_MEDIUM_TTL', 10_000),
+      limit: configService.get<number>('THROTTLE_MEDIUM_LIMIT', 100),
+    },
+    {
+      name: 'long',
+      ttl: configService.get<number>('THROTTLE_TTL', 60_000),
+      limit: configService.get<number>('THROTTLE_LIMIT', 1000),
+    },
+  ],
+});