spoonfeeder 0.1.0

package/templates/recipes/prometheus/README.md

@@ -0,0 +1,54 @@
+# Prometheus Metrics
+
+Application metrics collection and exposition using prom-client for NestJS applications.
+
+## Links
+
+- [prom-client on npm](https://www.npmjs.com/package/prom-client)
+- [prom-client on GitHub](https://github.com/siimon/prom-client)
+- [Prometheus Documentation](https://prometheus.io/docs/)
+
+## Dependencies
+
+| Package       | Version  | Purpose                               |
+| ------------- | -------- | ------------------------------------- |
+| `prom-client` | `15.1.3` | Prometheus client library for Node.js |
+
+## Environment Variables
+
+| Variable         | Default | Description                          |
+| ---------------- | ------- | ------------------------------------ |
+| `METRICS_PREFIX` | —       | Optional prefix for all metric names |
+
+## Usage
+
+```typescript
+import { MetricsModule } from '@/infrastructure/metrics/metrics.module';
+
+@Module({
+  imports: [MetricsModule],
+})
+export class AppModule {}
+
+// Access metrics at GET /metrics
+// Inject the Registry to create custom metrics:
+@Injectable()
+export class OrderService {
+  private readonly orderCounter: Counter;
+
+  constructor(@Inject('PROM_REGISTRY') private registry: Registry) {
+    this.orderCounter = new Counter({
+      name: 'orders_total',
+      help: 'Total number of orders',
+      registers: [registry],
+    });
+  }
+}
+```
+
+## Generated Files
+
+| File                                               | Description                                               |
+| -------------------------------------------------- | --------------------------------------------------------- |
+| `src/infrastructure/metrics/metrics.module.ts`     | Prometheus metrics module with default metrics collection |
+| `src/infrastructure/metrics/metrics.controller.ts` | Controller exposing `/metrics` endpoint                   |

package/templates/recipes/prometheus/src/infrastructure/metrics/metrics.controller.ts

@@ -0,0 +1,15 @@
+import { Controller, Get, Header, Inject } from '@nestjs/common';
+import { Registry } from 'prom-client';
+
+// WARNING: The /metrics endpoint exposes internal runtime data.
+// In production, protect this endpoint with a guard or network-level restrictions.
+@Controller('metrics')
+export class MetricsController {
+  constructor(@Inject('PROM_REGISTRY') private readonly registry: Registry) {}
+
+  @Get()
+  @Header('Content-Type', 'text/plain; version=0.0.4; charset=utf-8')
+  async getMetrics(): Promise<string> {
+    return this.registry.metrics();
+  }
+}

package/templates/recipes/prometheus/src/infrastructure/metrics/metrics.module.ts

@@ -0,0 +1,29 @@
+import { Module } from '@nestjs/common';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { Registry, collectDefaultMetrics } from 'prom-client';
+import { MetricsController } from './metrics.controller';
+
+@Module({
+  imports: [ConfigModule],
+  controllers: [MetricsController],
+  providers: [
+    {
+      provide: 'PROM_REGISTRY',
+      useFactory: (configService: ConfigService) => {
+        const registry = new Registry();
+        const prefix = configService.get<string>('METRICS_PREFIX');
+
+        if (prefix) {
+          registry.setDefaultLabels({ app: prefix });
+        }
+
+        collectDefaultMetrics({ register: registry });
+
+        return registry;
+      },
+      inject: [ConfigService],
+    },
+  ],
+  exports: ['PROM_REGISTRY'],
+})
+export class MetricsModule {}

package/templates/recipes/prometheus/tests/unit/infrastructure/metrics/metrics.controller.spec.ts

@@ -0,0 +1,22 @@
+import { Registry } from 'prom-client';
+import { MetricsController } from '../../../../src/infrastructure/metrics/metrics.controller';
+
+describe('MetricsController', () => {
+  let controller: MetricsController;
+  let registry: Registry;
+
+  beforeEach(() => {
+    registry = new Registry();
+    controller = new MetricsController(registry);
+  });
+
+  it('should be defined', () => {
+    expect(controller).toBeDefined();
+  });
+
+  it('should return metrics string from getMetrics', async () => {
+    const result = await controller.getMetrics();
+
+    expect(typeof result).toBe('string');
+  });
+});

package/templates/recipes/rabbitmq/README.md

@@ -0,0 +1,53 @@
+# RabbitMQ
+
+Message queue integration using RabbitMQ for NestJS microservices.
+
+## Links
+
+- [NestJS RabbitMQ Documentation](https://docs.nestjs.com/microservices/rabbitmq)
+- [@nestjs/microservices on npm](https://www.npmjs.com/package/@nestjs/microservices)
+- [amqplib on npm](https://www.npmjs.com/package/amqplib)
+- [amqplib on GitHub](https://github.com/amqp-node/amqplib)
+- [amqp-connection-manager on npm](https://www.npmjs.com/package/amqp-connection-manager)
+
+## Dependencies
+
+| Package                   | Version   | Purpose                           |
+| ------------------------- | --------- | --------------------------------- |
+| `@nestjs/microservices`   | `10.4.15` | NestJS microservices module       |
+| `amqplib`                 | `0.10.5`  | AMQP 0-9-1 client for RabbitMQ    |
+| `amqp-connection-manager` | `4.1.14`  | Connection management for amqplib |
+
+## Environment Variables
+
+| Variable         | Default                 | Description             |
+| ---------------- | ----------------------- | ----------------------- |
+| `RABBITMQ_URL`   | `amqp://localhost:5672` | RabbitMQ connection URL |
+| `RABBITMQ_QUEUE` | —                       | Default queue name      |
+
+## Usage
+
+```typescript
+import { QueueModule } from '@/infrastructure/queue/queue.module';
+
+@Module({
+  imports: [QueueModule],
+})
+export class AppModule {}
+
+// Send a message
+@Injectable()
+export class NotificationSender {
+  constructor(@Inject('RABBITMQ_CLIENT') private client: ClientProxy) {}
+
+  async sendNotification(data: any) {
+    return this.client.emit('notification.send', data);
+  }
+}
+```
+
+## Generated Files
+
+| File                                       | Description                                                |
+| ------------------------------------------ | ---------------------------------------------------------- |
+| `src/infrastructure/queue/queue.module.ts` | RabbitMQ client module with ConfigService-based connection |

package/templates/recipes/rabbitmq/src/infrastructure/queue/queue.module.ts.ejs

@@ -0,0 +1,27 @@
+import { Module } from '@nestjs/common';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { ClientsModule, Transport } from '@nestjs/microservices';
+
+@Module({
+  imports: [
+    ClientsModule.registerAsync([
+      {
+        name: 'RABBITMQ_CLIENT',
+        imports: [ConfigModule],
+        inject: [ConfigService],
+        useFactory: (configService: ConfigService) => ({
+          transport: Transport.RMQ,
+          options: {
+            urls: [configService.get<string>('RABBITMQ_URL', 'amqp://localhost:5672')],
+            queue: configService.get<string>('RABBITMQ_QUEUE', '<%= name %>-queue'),
+            queueOptions: {
+              durable: true,
+            },
+          },
+        }),
+      },
+    ]),
+  ],
+  exports: [ClientsModule],
+})
+export class QueueModule {}

package/templates/recipes/rbac-casl/README.md

@@ -0,0 +1,69 @@
+# RBAC Authorization (CASL)
+
+Role-based access control with CASL ability factory for NestJS.
+
+## Resources
+
+- [NestJS Authorization](https://docs.nestjs.com/security/authorization)
+- [CASL Documentation](https://casl.js.org/v6/en/)
+
+## Usage
+
+### Role-based guard
+
+Use the `@Roles()` decorator with the `RolesGuard` for simple role checks:
+
+```typescript
+import { Controller, Get, UseGuards } from '@nestjs/common';
+import { Roles } from '@/shared/decorators/roles.decorator';
+import { RolesGuard } from '@/shared/guards/roles.guard';
+import { Role } from '@/shared/auth/casl-ability.factory';
+
+@Controller('admin')
+@UseGuards(RolesGuard)
+export class AdminController {
+  @Get()
+  @Roles(Role.Admin)
+  findAll() {
+    return 'Admin-only endpoint';
+  }
+}
+```
+
+### Policy-based guard
+
+Use the `@CheckPolicies()` decorator with the `PoliciesGuard` for fine-grained CASL policies:
+
+```typescript
+import { Controller, Get, UseGuards } from '@nestjs/common';
+import { CheckPolicies, PoliciesGuard, PolicyHandler } from '@/shared/guards/policies.guard';
+import { AppAbility, Action } from '@/shared/auth/casl-ability.factory';
+
+class ReadUserPolicy implements PolicyHandler {
+  handle(ability: AppAbility): boolean {
+    return ability.can(Action.Read, 'User');
+  }
+}
+
+@Controller('users')
+@UseGuards(PoliciesGuard)
+export class UsersController {
+  @Get()
+  @CheckPolicies(new ReadUserPolicy())
+  findAll() {
+    return 'Users with read access';
+  }
+}
+```
+
+### Available roles
+
+| Role         | Permissions                                       |
+| ------------ | ------------------------------------------------- |
+| `User`       | Read all, update own User record                  |
+| `Admin`      | Read, create, and update all; cannot delete users |
+| `SuperAdmin` | Full access to everything                         |
+
+### Extending abilities
+
+Add new subjects and conditions in `CaslAbilityFactory.createForUser()` to match your domain model.

package/templates/recipes/rbac-casl/src/shared/auth/casl-ability.factory.ts

@@ -0,0 +1,43 @@
+import { Injectable } from '@nestjs/common';
+import { AbilityBuilder, createMongoAbility, MongoAbility, InferSubjects } from '@casl/ability';
+
+export enum Action {
+  Manage = 'manage',
+  Create = 'create',
+  Read = 'read',
+  Update = 'update',
+  Delete = 'delete',
+}
+
+export enum Role {
+  User = 'user',
+  Admin = 'admin',
+  SuperAdmin = 'super-admin',
+}
+
+export type AppAbility = MongoAbility;
+
+@Injectable()
+export class CaslAbilityFactory {
+  createForUser(user: { id: string; role: Role }): AppAbility {
+    const { can, cannot, build } = new AbilityBuilder(createMongoAbility);
+
+    switch (user.role) {
+      case Role.SuperAdmin:
+        can(Action.Manage, 'all');
+        break;
+      case Role.Admin:
+        can(Action.Read, 'all');
+        can(Action.Create, 'all');
+        can(Action.Update, 'all');
+        cannot(Action.Delete, 'User');
+        break;
+      case Role.User:
+        can(Action.Read, 'all');
+        can(Action.Update, 'User', { id: user.id });
+        break;
+    }
+
+    return build();
+  }
+}

package/templates/recipes/rbac-casl/src/shared/decorators/roles.decorator.ts

@@ -0,0 +1,5 @@
+import { SetMetadata } from '@nestjs/common';
+import { Role } from '../auth/casl-ability.factory';
+
+export const ROLES_KEY = 'roles';
+export const Roles = (...roles: Role[]) => SetMetadata(ROLES_KEY, roles);

package/templates/recipes/rbac-casl/src/shared/guards/policies.guard.ts

@@ -0,0 +1,32 @@
+import { CanActivate, ExecutionContext, Injectable, ForbiddenException } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { CaslAbilityFactory, AppAbility } from '../auth/casl-ability.factory';
+
+export interface PolicyHandler {
+  handle(ability: AppAbility): boolean;
+}
+
+export const CHECK_POLICIES_KEY = 'check_policies';
+export const CheckPolicies = (...handlers: PolicyHandler[]) =>
+  Reflect.metadata(CHECK_POLICIES_KEY, handlers);
+
+@Injectable()
+export class PoliciesGuard implements CanActivate {
+  constructor(
+    private readonly reflector: Reflector,
+    private readonly caslAbilityFactory: CaslAbilityFactory,
+  ) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    const handlers =
+      this.reflector.get<PolicyHandler[]>(CHECK_POLICIES_KEY, context.getHandler()) ?? [];
+    if (handlers.length === 0) return true;
+
+    const request = context.switchToHttp().getRequest();
+    const user = request.user;
+    if (!user) throw new ForbiddenException('No user context');
+
+    const ability = this.caslAbilityFactory.createForUser(user);
+    return handlers.every((handler) => handler.handle(ability));
+  }
+}

package/templates/recipes/rbac-casl/src/shared/guards/roles.guard.ts

@@ -0,0 +1,21 @@
+import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { ROLES_KEY } from '../decorators/roles.decorator';
+import { Role } from '../auth/casl-ability.factory';
+
+@Injectable()
+export class RolesGuard implements CanActivate {
+  constructor(private readonly reflector: Reflector) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    const requiredRoles = this.reflector.getAllAndOverride<Role[]>(ROLES_KEY, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+    if (!requiredRoles) return true;
+
+    const request = context.switchToHttp().getRequest();
+    const user = request.user;
+    return requiredRoles.includes(user?.role);
+  }
+}

package/templates/recipes/rbac-casl/tests/unit/shared/auth/casl-ability.factory.spec.ts

@@ -0,0 +1,6 @@
+describe('CaslAbilityFactory', () => {
+  it('should create ability for user role', () => {
+    // Test that different roles get different permissions
+    expect(true).toBe(true);
+  });
+});

package/templates/recipes/redis-cache/README.md

@@ -0,0 +1,55 @@
+# Redis Cache
+
+Caching layer using cache-manager with Redis store for NestJS applications.
+
+## Links
+
+- [NestJS Caching Documentation](https://docs.nestjs.com/techniques/caching)
+- [cache-manager on npm](https://www.npmjs.com/package/cache-manager)
+- [cache-manager-redis-yet on npm](https://www.npmjs.com/package/cache-manager-redis-yet)
+- [cache-manager-redis-yet on GitHub](https://github.com/node-cache-manager/node-cache-manager-redis-yet)
+- [@nestjs/cache-manager on npm](https://www.npmjs.com/package/@nestjs/cache-manager)
+
+## Dependencies
+
+| Package                   | Version | Purpose                          |
+| ------------------------- | ------- | -------------------------------- |
+| `@nestjs/cache-manager`   | `2.3.0` | NestJS cache manager integration |
+| `cache-manager`           | `5.7.6` | Flexible cache module            |
+| `cache-manager-redis-yet` | `5.1.5` | Redis store for cache-manager    |
+
+## Environment Variables
+
+| Variable         | Default     | Description                  |
+| ---------------- | ----------- | ---------------------------- |
+| `REDIS_HOST`     | `localhost` | Redis server hostname        |
+| `REDIS_PORT`     | `6379`      | Redis server port            |
+| `REDIS_PASSWORD` | —           | Redis password (optional)    |
+| `REDIS_TTL`      | `300`       | Default cache TTL in seconds |
+
+## Usage
+
+```typescript
+import { CacheModule } from '@/infrastructure/cache/cache.module';
+
+@Module({
+  imports: [CacheModule],
+})
+export class AppModule {}
+
+// Inject in a service
+@Injectable()
+export class UserService {
+  constructor(@Inject(CACHE_MANAGER) private cacheManager: Cache) {}
+
+  async getCachedUser(id: string) {
+    return this.cacheManager.get(`user:${id}`);
+  }
+}
+```
+
+## Generated Files
+
+| File                                       | Description                                               |
+| ------------------------------------------ | --------------------------------------------------------- |
+| `src/infrastructure/cache/cache.module.ts` | CacheModule configured with Redis store and ConfigService |

package/templates/recipes/redis-cache/src/infrastructure/cache/cache.module.ts

@@ -0,0 +1,26 @@
+import { Module } from '@nestjs/common';
+import { CacheModule as NestCacheModule } from '@nestjs/cache-manager';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { redisStore } from 'cache-manager-redis-yet';
+
+@Module({
+  imports: [
+    NestCacheModule.registerAsync({
+      imports: [ConfigModule],
+      inject: [ConfigService],
+      isGlobal: true,
+      useFactory: async (configService: ConfigService) => ({
+        store: await redisStore({
+          socket: {
+            host: configService.get<string>('REDIS_HOST', 'localhost'),
+            port: configService.get<number>('REDIS_PORT', 6379),
+          },
+          password: configService.get<string>('REDIS_PASSWORD'),
+        }),
+        ttl: configService.get<number>('REDIS_TTL', 300) * 1000,
+      }),
+    }),
+  ],
+  exports: [NestCacheModule],
+})
+export class CacheModule {}

package/templates/recipes/redis-cache/tests/unit/infrastructure/cache/cache.module.spec.ts

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

package/templates/recipes/request-context/README.md

@@ -0,0 +1,57 @@
+# Request Context (CLS)
+
+AsyncLocalStorage-based request context via nestjs-cls, providing correlation IDs, user info, and request metadata throughout the request lifecycle without explicit parameter passing.
+
+## Links
+
+- [nestjs-cls Documentation](https://papooch.github.io/nestjs-cls/)
+- [nestjs-cls on npm](https://www.npmjs.com/package/nestjs-cls)
+- [Node.js AsyncLocalStorage](https://nodejs.org/api/async_context.html#class-asynclocalstorage)
+
+## Dependencies
+
+| Package      | Version | Purpose                                     |
+| ------------ | ------- | ------------------------------------------- |
+| `nestjs-cls` | `4.5.0` | CLS (Continuation-Local Storage) for NestJS |
+
+## Usage
+
+Import `RequestContextModule` in your root module:
+
+```typescript
+import { RequestContextModule } from '@/shared/context/request-context.module';
+
+@Module({
+  imports: [RequestContextModule],
+})
+export class AppModule {}
+```
+
+Access context anywhere via `ClsService`:
+
+```typescript
+import { ClsService } from 'nestjs-cls';
+
+@Injectable()
+export class OrderService {
+  constructor(private readonly cls: ClsService) {}
+
+  createOrder(dto: CreateOrderDto) {
+    const correlationId = this.cls.get('correlationId');
+    const userId = this.cls.get('userId');
+    // Use context without explicit parameter passing
+  }
+}
+```
+
+The middleware automatically sets:
+
+- `correlationId` — from `x-correlation-id` header or a generated UUID
+- `userId` — from `request.user.sub` (available after auth middleware)
+- `ip` — client IP address
+
+## Generated Files
+
+| File                                           | Description                           |
+| ---------------------------------------------- | ------------------------------------- |
+| `src/shared/context/request-context.module.ts` | CLS module with middleware auto-setup |

package/templates/recipes/request-context/src/shared/context/request-context.module.ts

@@ -0,0 +1,19 @@
+import { Module } from '@nestjs/common';
+import { ClsModule } from 'nestjs-cls';
+
+@Module({
+  imports: [
+    ClsModule.forRoot({
+      middleware: {
+        mount: true,
+        setup: (cls, req) => {
+          cls.set('correlationId', req.headers['x-correlation-id'] ?? crypto.randomUUID());
+          cls.set('userId', (req as any).user?.sub ?? null);
+          cls.set('ip', req.ip);
+        },
+      },
+    }),
+  ],
+  exports: [ClsModule],
+})
+export class RequestContextModule {}

package/templates/recipes/request-context/tests/unit/shared/context/request-context.module.spec.ts

@@ -0,0 +1,20 @@
+import { RequestContextModule } from '../../../../src/shared/context/request-context.module';
+
+describe('RequestContextModule', () => {
+  it('should be a valid NestJS module with imports and exports', () => {
+    const imports = Reflect.getMetadata('imports', RequestContextModule);
+    const exports = Reflect.getMetadata('exports', RequestContextModule);
+
+    expect(imports).toBeDefined();
+    expect(imports.length).toBeGreaterThan(0);
+    expect(exports).toBeDefined();
+    expect(exports.length).toBeGreaterThan(0);
+  });
+
+  it('should export ClsModule so dependents can inject CLS', () => {
+    const exports = Reflect.getMetadata('exports', RequestContextModule);
+
+    const exportNames = exports.map((e: any) => e?.name ?? String(e));
+    expect(exportNames).toContain('ClsModule');
+  });
+});

package/templates/recipes/request-logging/README.md

@@ -0,0 +1,36 @@
+# Request Logging
+
+HTTP request/response logging middleware with timing, status codes, and structured output.
+
+## Links
+
+- [NestJS Middleware](https://docs.nestjs.com/middleware)
+- [NestJS Logger](https://docs.nestjs.com/techniques/logger)
+
+## Dependencies
+
+No additional dependencies required. Uses the built-in NestJS logger.
+
+| Package | Version | Purpose                  |
+| ------- | ------- | ------------------------ |
+| (none)  | -       | Built-in NestJS `Logger` |
+
+## Usage
+
+Register middleware in your module:
+
+```typescript
+import { RequestLoggingMiddleware } from '@/shared/middleware/request-logging.middleware';
+
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    consumer.apply(RequestLoggingMiddleware).forRoutes('*');
+  }
+}
+```
+
+## Generated Files
+
+| File                                                  | Description                                                               |
+| ----------------------------------------------------- | ------------------------------------------------------------------------- |
+| `src/shared/middleware/request-logging.middleware.ts` | Middleware that logs incoming requests and outgoing responses with timing |

package/templates/recipes/request-logging/src/shared/middleware/request-logging.middleware.ts

@@ -0,0 +1,40 @@
+import { Injectable, Logger, NestMiddleware } from '@nestjs/common';
+import { FastifyReply, FastifyRequest } from 'fastify';
+
+@Injectable()
+export class RequestLoggingMiddleware implements NestMiddleware {
+  private readonly logger = new Logger('HTTP');
+
+  use(req: FastifyRequest['raw'], res: FastifyReply['raw'], next: () => void): void {
+    const start = performance.now();
+    const { method, url } = req;
+    const userAgent = req.headers['user-agent'] || '-';
+    const correlationId = req.headers['x-correlation-id'] || '-';
+
+    res.on('finish', () => {
+      const duration = (performance.now() - start).toFixed(2);
+      const { statusCode } = res;
+      const contentLength = res.getHeader('content-length') || 0;
+
+      const logData = {
+        method,
+        url,
+        statusCode,
+        duration: `${duration}ms`,
+        contentLength,
+        userAgent,
+        correlationId,
+      };
+
+      if (statusCode >= 500) {
+        this.logger.error(logData);
+      } else if (statusCode >= 400) {
+        this.logger.warn(logData);
+      } else {
+        this.logger.log(logData);
+      }
+    });
+
+    next();
+  }
+}