spoonfeeder 0.1.0

package/templates/recipes/cqrs/README.md

@@ -0,0 +1,39 @@
+# CQRS
+
+Command Query Responsibility Segregation pattern using the official NestJS CQRS module.
+
+## Links
+
+- [NestJS CQRS Recipe](https://docs.nestjs.com/recipes/cqrs)
+- [@nestjs/cqrs on npm](https://www.npmjs.com/package/@nestjs/cqrs)
+- [@nestjs/cqrs on GitHub](https://github.com/nestjs/cqrs)
+
+## Dependencies
+
+| Package        | Version  | Purpose                                               |
+| -------------- | -------- | ----------------------------------------------------- |
+| `@nestjs/cqrs` | `11.0.0` | CQRS module with commands, queries, events, and sagas |
+
+## Usage
+
+```typescript
+import { CqrsModule } from '@nestjs/cqrs';
+import { CreateUserCommand } from '@/shared/cqrs/example.command';
+
+@Module({
+  imports: [CqrsModule],
+  providers: [CreateUserHandler],
+})
+export class UsersModule {}
+
+// Dispatch a command
+constructor(private readonly commandBus: CommandBus) {}
+
+await this.commandBus.execute(new CreateUserCommand('alice@example.com', 'Alice'));
+```
+
+## Generated Files
+
+| File                                 | Description                           |
+| ------------------------------------ | ------------------------------------- |
+| `src/shared/cqrs/example.command.ts` | Example command class and its handler |

package/templates/recipes/cqrs/src/shared/cqrs/example.command.ts

@@ -0,0 +1,29 @@
+import { CommandHandler, ICommand, ICommandHandler } from '@nestjs/cqrs';
+import { Logger } from '@nestjs/common';
+
+export class CreateUserCommand implements ICommand {
+  constructor(
+    public readonly email: string,
+    public readonly name: string,
+  ) {}
+}
+
+@CommandHandler(CreateUserCommand)
+export class CreateUserHandler implements ICommandHandler<CreateUserCommand> {
+  private readonly logger = new Logger(CreateUserHandler.name);
+
+  async execute(command: CreateUserCommand): Promise<{ id: string; email: string; name: string }> {
+    this.logger.log(`Creating user: ${command.email}`);
+
+    // Replace with actual persistence logic
+    const user = {
+      id: crypto.randomUUID(),
+      email: command.email,
+      name: command.name,
+    };
+
+    this.logger.log(`User created: ${user.id}`);
+
+    return user;
+  }
+}

package/templates/recipes/cqrs/tests/unit/shared/cqrs/example.command.spec.ts

@@ -0,0 +1,38 @@
+import { CreateUserCommand, CreateUserHandler } from '../../../../src/shared/cqrs/example.command';
+
+describe('CreateUserCommand', () => {
+  it('should store email and name', () => {
+    const command = new CreateUserCommand('user@example.com', 'Alice');
+    expect(command.email).toBe('user@example.com');
+    expect(command.name).toBe('Alice');
+  });
+});
+
+describe('CreateUserHandler', () => {
+  let handler: CreateUserHandler;
+
+  beforeEach(() => {
+    handler = new CreateUserHandler();
+  });
+
+  it('should return a user with a generated id', async () => {
+    const command = new CreateUserCommand('bob@example.com', 'Bob');
+    const result = await handler.execute(command);
+
+    expect(result).toEqual(
+      expect.objectContaining({
+        email: 'bob@example.com',
+        name: 'Bob',
+      }),
+    );
+    expect(result.id).toBeDefined();
+    expect(typeof result.id).toBe('string');
+    expect(result.id.length).toBeGreaterThan(0);
+  });
+
+  it('should produce unique ids for different executions', async () => {
+    const result1 = await handler.execute(new CreateUserCommand('a@b.com', 'A'));
+    const result2 = await handler.execute(new CreateUserCommand('c@d.com', 'C'));
+    expect(result1.id).not.toBe(result2.id);
+  });
+});

package/templates/recipes/csrf/README.md

@@ -0,0 +1,55 @@
+# CSRF Protection
+
+Cross-Site Request Forgery protection for Fastify-based NestJS applications.
+
+## Links
+
+- [@fastify/csrf-protection on npm](https://www.npmjs.com/package/@fastify/csrf-protection)
+- [@fastify/csrf-protection on GitHub](https://github.com/fastify/csrf-protection)
+- [OWASP CSRF Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html)
+
+## Dependencies
+
+| Package                    | Version  | Purpose                                   |
+| -------------------------- | -------- | ----------------------------------------- |
+| `@fastify/csrf-protection` | `7.0.1`  | CSRF token generation and validation      |
+| `@fastify/cookie`          | `11.0.2` | Cookie support (required for CSRF tokens) |
+
+## Usage
+
+Register in `main.ts`:
+
+```typescript
+import cookie from '@fastify/cookie';
+import csrf from '@fastify/csrf-protection';
+
+const app = await NestFactory.create<NestFastifyApplication>(AppModule, new FastifyAdapter());
+
+await app.register(cookie);
+await app.register(csrf, {
+  sessionPlugin: '@fastify/cookie',
+  cookieOpts: {
+    signed: true,
+    httpOnly: true,
+    sameSite: 'strict',
+    secure: process.env.NODE_ENV === 'production',
+  },
+});
+```
+
+Generate and validate tokens in routes:
+
+```typescript
+// Generate token
+@Get('csrf-token')
+async getCsrfToken(@Req() request: FastifyRequest, @Res() reply: FastifyReply) {
+  const token = await reply.generateCsrf();
+  return reply.send({ token });
+}
+```
+
+## Generated Files
+
+| File   | Description                                                   |
+| ------ | ------------------------------------------------------------- |
+| (none) | Applied directly in `main.ts` via Fastify plugin registration |

package/templates/recipes/data-masking/README.md

@@ -0,0 +1,85 @@
+# Data Masking / PII Redaction
+
+Automatic PII redaction in logs and API responses for GDPR/CCPA compliance.
+
+## Links
+
+- [GDPR Article 25 — Data Protection by Design](https://gdpr-info.eu/art-25-gdpr/)
+- [CCPA — California Consumer Privacy Act](https://oag.ca.gov/privacy/ccpa)
+- [class-transformer on npm](https://www.npmjs.com/package/class-transformer)
+
+## Dependencies
+
+No additional dependencies. Uses `class-transformer` which is already included in the base template.
+
+## Usage
+
+### DTO Masking with @Sensitive()
+
+Apply the `@Sensitive()` decorator to DTO properties that contain PII. Masking is applied automatically when serializing to plain objects via `class-transformer` (`toPlainOnly: true`).
+
+```typescript
+import { Sensitive } from '@/shared/decorators/sensitive.decorator';
+import { Expose } from 'class-transformer';
+
+export class UserResponseDto {
+  @Expose()
+  id: string;
+
+  @Expose()
+  name: string;
+
+  @Expose()
+  @Sensitive('*', 4) // last 4 characters visible
+  email: string;
+
+  @Expose()
+  @Sensitive('*', 4)
+  phone: string;
+}
+```
+
+Response output:
+
+```json
+{
+  "id": "abc-123",
+  "name": "Jane Doe",
+  "email": "***********e.com",
+  "phone": "********1234"
+}
+```
+
+### Log Redaction with Mask Utilities
+
+Use the mask utility functions to redact PII before writing to logs:
+
+```typescript
+import { maskEmail, maskPhone, maskCreditCard, maskIban } from '@/shared/utils/mask.util';
+
+logger.log(`Processing payment for ${maskEmail('jane@example.com')}`);
+// => Processing payment for j**e@example.com
+
+logger.log(`Card: ${maskCreditCard('4111 1111 1111 1234')}`);
+// => Card: ************1234
+
+logger.log(`IBAN: ${maskIban('NL91ABNA0417164300')}`);
+// => IBAN: NL91**********4300
+
+logger.log(`Phone: ${maskPhone('+31 6 1234 5678')}`);
+// => Phone: ******5678
+```
+
+### GDPR/CCPA Compliance Patterns
+
+1. **Response masking** — Apply `@Sensitive()` to all DTO fields containing PII (email, phone, SSN, etc.)
+2. **Log redaction** — Use mask utilities before logging any PII. Never log raw personal data.
+3. **Database queries** — Mask PII when returning data in admin/reporting contexts where full values are not needed.
+4. **Audit trails** — Store masked versions of PII in audit logs to maintain traceability without exposing raw data.
+
+## Generated Files
+
+| File                                           | Description                                            |
+| ---------------------------------------------- | ------------------------------------------------------ |
+| `src/shared/decorators/sensitive.decorator.ts` | @Sensitive() property decorator for DTO field masking  |
+| `src/shared/utils/mask.util.ts`                | Utility functions for masking email, phone, card, IBAN |

package/templates/recipes/data-masking/src/shared/decorators/sensitive.decorator.ts

@@ -0,0 +1,12 @@
+import { Transform } from 'class-transformer';
+
+export function Sensitive(maskChar = '*', visibleChars = 4): PropertyDecorator {
+  return Transform(
+    ({ value }) => {
+      if (typeof value !== 'string' || value.length <= visibleChars) return value;
+      const visible = value.slice(-visibleChars);
+      return maskChar.repeat(value.length - visibleChars) + visible;
+    },
+    { toPlainOnly: true },
+  );
+}

package/templates/recipes/data-masking/src/shared/utils/mask.util.ts

@@ -0,0 +1,26 @@
+export function maskEmail(email: string): string {
+  const [local, domain] = email.split('@');
+  if (!domain) return '***';
+  const maskedLocal =
+    local.length <= 2
+      ? '*'.repeat(local.length)
+      : local[0] + '*'.repeat(local.length - 2) + local[local.length - 1];
+  return `${maskedLocal}@${domain}`;
+}
+
+export function maskPhone(phone: string): string {
+  const digits = phone.replace(/\D/g, '');
+  if (digits.length <= 4) return '*'.repeat(digits.length);
+  return '*'.repeat(digits.length - 4) + digits.slice(-4);
+}
+
+export function maskCreditCard(card: string): string {
+  const digits = card.replace(/\D/g, '');
+  if (digits.length <= 4) return '*'.repeat(digits.length);
+  return '*'.repeat(digits.length - 4) + digits.slice(-4);
+}
+
+export function maskIban(iban: string): string {
+  if (iban.length <= 6) return '*'.repeat(iban.length);
+  return iban.slice(0, 4) + '*'.repeat(iban.length - 8) + iban.slice(-4);
+}

package/templates/recipes/data-masking/tests/unit/shared/utils/mask.util.spec.ts

@@ -0,0 +1,21 @@
+import { maskEmail, maskPhone, maskCreditCard, maskIban } from '@/shared/utils/mask.util';
+
+describe('Masking Utilities', () => {
+  it('should mask email', () => {
+    expect(maskEmail('john@example.com')).toMatch(/^\w\*+\w@example\.com$/);
+  });
+
+  it('should mask phone', () => {
+    expect(maskPhone('+31612345678')).toMatch(/\*+5678$/);
+  });
+
+  it('should mask credit card', () => {
+    expect(maskCreditCard('4111111111111111')).toMatch(/\*+1111$/);
+  });
+
+  it('should mask IBAN', () => {
+    const masked = maskIban('NL91ABNA0417164300');
+    expect(masked.startsWith('NL91')).toBe(true);
+    expect(masked.endsWith('4300')).toBe(true);
+  });
+});

package/templates/recipes/database-factories/README.md

@@ -0,0 +1,48 @@
+# Database Factories
+
+Test factory pattern for creating consistent test data with type-safe overrides.
+
+## Links
+
+- [NestJS Testing](https://docs.nestjs.com/fundamentals/testing)
+- [Factory Pattern](https://refactoring.guru/design-patterns/factory-method)
+
+## Dependencies
+
+No additional dependencies required.
+
+| Package | Version | Purpose                           |
+| ------- | ------- | --------------------------------- |
+| (none)  | -       | Pure TypeScript factory functions |
+
+## Usage
+
+```typescript
+import { createFactory } from '@tests/factories/base.factory';
+
+interface User {
+  id: string;
+  email: string;
+  name: string;
+  isActive: boolean;
+}
+
+const userFactory = createFactory<User>(() => ({
+  id: crypto.randomUUID(),
+  email: `user-${Date.now()}@example.com`,
+  name: 'Test User',
+  isActive: true,
+}));
+
+// Create a single entity
+const user = userFactory.build({ name: 'Alice' });
+
+// Create multiple entities
+const users = userFactory.buildMany(5, { isActive: false });
+```
+
+## Generated Files
+
+| File                              | Description                      |
+| --------------------------------- | -------------------------------- |
+| `tests/factories/base.factory.ts` | Generic factory builder function |

package/templates/recipes/database-factories/tests/factories/base.factory.ts

@@ -0,0 +1,51 @@
+type DefaultsFn<T> = () => T;
+type Overrides<T> = Partial<T>;
+
+interface Factory<T> {
+  /** Build a single entity with optional overrides */
+  build(overrides?: Overrides<T>): T;
+
+  /** Build multiple entities with optional shared overrides */
+  buildMany(count: number, overrides?: Overrides<T>): T[];
+
+  /** Build an entity and transform it before returning */
+  buildWith<R>(transform: (entity: T) => R, overrides?: Overrides<T>): R;
+}
+
+/**
+ * Create a type-safe factory for generating test data.
+ *
+ * @param defaultsFn - A function returning the default values for each entity.
+ *                     Called for every build to ensure unique values (e.g. UUIDs).
+ *
+ * @example
+ * ```typescript
+ * const userFactory = createFactory<User>(() => ({
+ *   id: crypto.randomUUID(),
+ *   email: `user-${Date.now()}@example.com`,
+ *   name: 'Test User',
+ *   isActive: true,
+ * }));
+ *
+ * const user = userFactory.build({ name: 'Alice' });
+ * const users = userFactory.buildMany(3);
+ * ```
+ */
+export function createFactory<T>(defaultsFn: DefaultsFn<T>): Factory<T> {
+  return {
+    build(overrides: Overrides<T> = {}): T {
+      return {
+        ...defaultsFn(),
+        ...overrides,
+      };
+    },
+
+    buildMany(count: number, overrides: Overrides<T> = {}): T[] {
+      return Array.from({ length: count }, () => this.build(overrides));
+    },
+
+    buildWith<R>(transform: (entity: T) => R, overrides: Overrides<T> = {}): R {
+      return transform(this.build(overrides));
+    },
+  };
+}

package/templates/recipes/database-seeding/README.md

@@ -0,0 +1,40 @@
+# Database Seeding
+
+Database seed command scaffold for populating development and test data.
+
+## Links
+
+- [NestJS Standalone Applications](https://docs.nestjs.com/standalone-applications)
+- [NestJS Lifecycle Events](https://docs.nestjs.com/fundamentals/lifecycle-events)
+
+## Dependencies
+
+No additional dependencies beyond the existing database driver.
+
+| Package | Version | Purpose                           |
+| ------- | ------- | --------------------------------- |
+| (none)  | -       | Uses existing database connection |
+
+## Usage
+
+Add a seed script to `package.json`:
+
+```json
+{
+  "scripts": {
+    "seed": "ts-node -r tsconfig-paths/register src/infrastructure/database/seed.ts"
+  }
+}
+```
+
+Run the seed command:
+
+```bash
+pnpm seed
+```
+
+## Generated Files
+
+| File                                  | Description                                        |
+| ------------------------------------- | -------------------------------------------------- |
+| `src/infrastructure/database/seed.ts` | Standalone NestJS application for database seeding |

package/templates/recipes/database-seeding/src/infrastructure/database/seed.ts

@@ -0,0 +1,61 @@
+import { Logger } from '@nestjs/common';
+import { NestFactory } from '@nestjs/core';
+
+// Import your AppModule — adjust the path to match your project structure
+// import { AppModule } from '@/app.module';
+
+const logger = new Logger('Seed');
+
+interface Seeder {
+  name: string;
+  run: (app: unknown) => Promise<number>;
+}
+
+const seeders: Seeder[] = [
+  {
+    name: 'Users',
+    run: async (_app) => {
+      // Example: const userRepo = app.get(UserRepository);
+      // await userRepo.save([
+      //   { email: 'admin@example.com', name: 'Admin', role: 'admin' },
+      //   { email: 'user@example.com', name: 'User', role: 'user' },
+      // ]);
+      logger.log('Seeding users — replace with actual implementation');
+      return 2;
+    },
+  },
+];
+
+async function bootstrap(): Promise<void> {
+  // Uncomment once AppModule is available:
+  // const app = await NestFactory.createApplicationContext(AppModule);
+
+  const app = null; // Remove this line when uncommenting above
+
+  logger.log('Starting database seed...');
+
+  let totalRecords = 0;
+
+  for (const seeder of seeders) {
+    try {
+      const count = await seeder.run(app);
+      totalRecords += count;
+      logger.log(`Seeded ${count} ${seeder.name} records`);
+    } catch (error) {
+      logger.error(`Failed to seed ${seeder.name}: ${(error as Error).message}`);
+      throw error;
+    }
+  }
+
+  logger.log(`Seed complete — ${totalRecords} total records created`);
+
+  // Uncomment once AppModule is available:
+  // await app.close();
+
+  process.exit(0);
+}
+
+bootstrap().catch((error) => {
+  logger.error('Seed failed', error);
+  process.exit(1);
+});

package/templates/recipes/database-seeding/tests/unit/infrastructure/database/seed.spec.ts

@@ -0,0 +1,37 @@
+describe('Database seed script', () => {
+  it('should define at least one seeder', () => {
+    // The seed script defines a seeders array; verify structure expectations
+    const seeders = [
+      {
+        name: 'Users',
+        run: async () => 2,
+      },
+    ];
+
+    expect(seeders.length).toBeGreaterThanOrEqual(1);
+    expect(seeders[0].name).toBe('Users');
+  });
+
+  it('should return the number of seeded records', async () => {
+    const seeder = {
+      name: 'Users',
+      run: async (_app: unknown) => {
+        return 5;
+      },
+    };
+
+    const count = await seeder.run(null);
+    expect(count).toBe(5);
+  });
+
+  it('should propagate errors from individual seeders', async () => {
+    const failingSeeder = {
+      name: 'BadSeeder',
+      run: async () => {
+        throw new Error('seed failed');
+      },
+    };
+
+    await expect(failingSeeder.run()).rejects.toThrow('seed failed');
+  });
+});

package/templates/recipes/dead-letter-queue/README.md

@@ -0,0 +1,79 @@
+# Dead Letter Queue
+
+Handle permanently failed messages with DLQ routing, inspection, and replay.
+
+## Links
+
+- [BullMQ Dead Letter Queue](https://docs.bullmq.io/)
+- [RabbitMQ Dead Letter Exchanges](https://www.rabbitmq.com/docs/dlx)
+
+## Dependencies
+
+No additional dependencies required.
+
+## Usage
+
+Inject `DeadLetterQueueService` in your queue consumers and route permanently failed messages to the DLQ:
+
+```typescript
+import { DeadLetterQueueService } from '@/infrastructure/queue/dlq.service';
+
+@Injectable()
+export class OrderConsumer {
+  constructor(private readonly dlq: DeadLetterQueueService) {}
+
+  async handleMessage(message: unknown): Promise<void> {
+    try {
+      await this.process(message);
+    } catch (error) {
+      this.dlq.add({
+        queue: 'orders',
+        payload: message,
+        error: error instanceof Error ? error.message : String(error),
+        attempts: 3,
+      });
+    }
+  }
+}
+```
+
+### BullMQ Integration
+
+Configure BullMQ to route failed jobs after max attempts:
+
+```typescript
+@Processor('orders')
+export class OrderProcessor {
+  constructor(private readonly dlq: DeadLetterQueueService) {}
+
+  @OnWorkerEvent('failed')
+  onFailed(job: Job, error: Error): void {
+    if (job.attemptsMade >= job.opts.attempts) {
+      this.dlq.add({
+        queue: 'orders',
+        payload: job.data,
+        error: error.message,
+        attempts: job.attemptsMade,
+      });
+    }
+  }
+}
+```
+
+### RabbitMQ Integration
+
+For RabbitMQ, configure dead letter exchanges at the queue level and use the service to track and inspect failed messages in your application.
+
+### Inspecting Dead Letters
+
+```typescript
+const allMessages = dlqService.getAll();
+const orderFailures = dlqService.getByQueue('orders');
+dlqService.remove(messageId);
+```
+
+## Generated Files
+
+| File                                      | Description               |
+| ----------------------------------------- | ------------------------- |
+| `src/infrastructure/queue/dlq.service.ts` | Dead letter queue service |

package/templates/recipes/dead-letter-queue/src/infrastructure/queue/dlq.service.ts

@@ -0,0 +1,43 @@
+import { Injectable, Logger } from '@nestjs/common';
+
+export interface DeadLetterMessage {
+  id: string;
+  queue: string;
+  payload: unknown;
+  error: string;
+  attempts: number;
+  failedAt: Date;
+}
+
+@Injectable()
+export class DeadLetterQueueService {
+  private readonly logger = new Logger(DeadLetterQueueService.name);
+  // TODO: Replace this in-memory store with a persistent backend (Redis, database).
+  // This implementation is for development only — messages are lost on restart and unbounded in memory.
+  private readonly messages: DeadLetterMessage[] = [];
+
+  add(message: Omit<DeadLetterMessage, 'id' | 'failedAt'>): void {
+    const dlqMessage: DeadLetterMessage = {
+      ...message,
+      id: crypto.randomUUID(),
+      failedAt: new Date(),
+    };
+    this.messages.push(dlqMessage);
+    this.logger.warn(`Message added to DLQ from queue "${message.queue}": ${message.error}`);
+  }
+
+  getAll(): DeadLetterMessage[] {
+    return [...this.messages];
+  }
+
+  getByQueue(queue: string): DeadLetterMessage[] {
+    return this.messages.filter((m) => m.queue === queue);
+  }
+
+  remove(id: string): boolean {
+    const index = this.messages.findIndex((m) => m.id === id);
+    if (index === -1) return false;
+    this.messages.splice(index, 1);
+    return true;
+  }
+}