spoonfeeder 0.1.0

package/templates/recipes/throttler/tests/unit/shared/guards/throttle.spec.ts

@@ -0,0 +1,5 @@
+describe('ThrottlerConfig', () => {
+  it('should export throttle configuration', () => {
+    expect(true).toBe(true);
+  });
+});

package/templates/recipes/transactional-outbox/README.md

@@ -0,0 +1,98 @@
+# Transactional Outbox
+
+Guarantee at-least-once event delivery alongside database writes using the transactional outbox pattern.
+
+## Links
+
+- [Microservices Pattern: Transactional Outbox](https://microservices.io/patterns/data/transactional-outbox.html)
+- [Debezium — Change Data Capture](https://debezium.io/)
+- [TypeORM Transactions](https://typeorm.io/transactions)
+
+## Dependencies
+
+No additional dependencies. Uses `typeorm` and `@nestjs/common` which are already included when using a TypeORM-based database recipe.
+
+## How It Works
+
+The transactional outbox pattern solves the dual-write problem: when you need to update a database **and** publish an event, doing both independently risks inconsistency (one succeeds, the other fails).
+
+1. **Write phase** — Business data and outbox message are written in the same database transaction.
+2. **Publish phase** — A separate polling publisher reads unpublished outbox rows and delivers them to the message broker.
+3. **Mark phase** — After successful delivery, the row is marked as `published = true`.
+
+This guarantees at-least-once delivery. Consumers must be idempotent.
+
+## Usage
+
+### Writing Events in a Transaction
+
+```typescript
+import { OutboxService } from '@/infrastructure/outbox/outbox.service';
+import { DataSource } from 'typeorm';
+
+@Injectable()
+export class OrderService {
+  constructor(
+    private readonly dataSource: DataSource,
+    private readonly outboxService: OutboxService,
+  ) {}
+
+  async createOrder(dto: CreateOrderDto): Promise<Order> {
+    return this.dataSource.transaction(async (manager) => {
+      const order = manager.create(Order, dto);
+      await manager.save(order);
+
+      await this.outboxService.addMessage(manager, 'Order', order.id, 'OrderCreated', {
+        orderId: order.id,
+        total: order.total,
+      });
+
+      return order;
+    });
+  }
+}
+```
+
+### Polling Publisher
+
+A scheduled task reads unpublished messages and delivers them:
+
+```typescript
+@Injectable()
+export class OutboxPublisher {
+  constructor(
+    private readonly dataSource: DataSource,
+    private readonly messageBroker: MessageBroker,
+  ) {}
+
+  @Cron(CronExpression.EVERY_5_SECONDS)
+  async publishPendingMessages(): Promise<void> {
+    const messages = await this.dataSource
+      .getRepository(OutboxMessage)
+      .find({ where: { published: false }, order: { createdAt: 'ASC' }, take: 100 });
+
+    for (const message of messages) {
+      await this.messageBroker.publish(message.eventType, message.payload);
+      await this.dataSource
+        .getRepository(OutboxMessage)
+        .update(message.id, { published: true, publishedAt: new Date() });
+    }
+  }
+}
+```
+
+### CDC Alternative
+
+For higher throughput, replace the polling publisher with Change Data Capture (CDC) using Debezium:
+
+1. Debezium monitors the `outbox` table for new inserts.
+2. New rows are automatically streamed to Kafka/RabbitMQ.
+3. No polling needed — events are delivered in near real-time.
+4. The application only writes to the outbox table; Debezium handles the rest.
+
+## Generated Files
+
+| File                                          | Description                               |
+| --------------------------------------------- | ----------------------------------------- |
+| `src/infrastructure/outbox/outbox.entity.ts`  | TypeORM entity for the outbox table       |
+| `src/infrastructure/outbox/outbox.service.ts` | Service for adding messages to the outbox |

package/templates/recipes/transactional-outbox/src/infrastructure/outbox/outbox.entity.ts

@@ -0,0 +1,30 @@
+import { Entity, PrimaryGeneratedColumn, Column, CreateDateColumn, Index } from 'typeorm';
+
+@Entity('outbox')
+export class OutboxMessage {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @Column()
+  @Index()
+  aggregateType: string;
+
+  @Column()
+  aggregateId: string;
+
+  @Column()
+  eventType: string;
+
+  @Column('jsonb')
+  payload: Record<string, unknown>;
+
+  @CreateDateColumn()
+  createdAt: Date;
+
+  @Column({ default: false })
+  @Index()
+  published: boolean;
+
+  @Column({ type: 'timestamp', nullable: true })
+  publishedAt: Date | null;
+}

package/templates/recipes/transactional-outbox/src/infrastructure/outbox/outbox.service.ts

@@ -0,0 +1,21 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { EntityManager } from 'typeorm';
+
+@Injectable()
+export class OutboxService {
+  private readonly logger = new Logger(OutboxService.name);
+
+  async addMessage(
+    manager: EntityManager,
+    aggregateType: string,
+    aggregateId: string,
+    eventType: string,
+    payload: Record<string, unknown>,
+  ): Promise<void> {
+    await manager.query(
+      `INSERT INTO outbox (id, "aggregateType", "aggregateId", "eventType", payload, "createdAt", published)
+       VALUES (gen_random_uuid(), $1, $2, $3, $4, NOW(), false)`,
+      [aggregateType, aggregateId, eventType, JSON.stringify(payload)],
+    );
+  }
+}

package/templates/recipes/transactional-outbox/tests/unit/infrastructure/outbox/outbox.service.spec.ts

@@ -0,0 +1,38 @@
+import { OutboxService } from '../../../../src/infrastructure/outbox/outbox.service';
+import { EntityManager } from 'typeorm';
+
+describe('OutboxService', () => {
+  let service: OutboxService;
+  let mockManager: jest.Mocked<Pick<EntityManager, 'query'>>;
+
+  beforeEach(() => {
+    service = new OutboxService();
+    mockManager = { query: jest.fn().mockResolvedValue(undefined) };
+  });
+
+  it('should insert a row into the outbox table with correct parameters', async () => {
+    const payload = { orderId: 'abc-123', total: 99.95 };
+
+    await service.addMessage(
+      mockManager as unknown as EntityManager,
+      'Order',
+      'order-1',
+      'OrderCreated',
+      payload,
+    );
+
+    expect(mockManager.query).toHaveBeenCalledTimes(1);
+
+    const [sql, params] = mockManager.query.mock.calls[0];
+    expect(sql).toContain('INSERT INTO outbox');
+    expect(params).toEqual(['Order', 'order-1', 'OrderCreated', JSON.stringify(payload)]);
+  });
+
+  it('should propagate errors from the entity manager', async () => {
+    mockManager.query.mockRejectedValue(new Error('connection lost'));
+
+    await expect(
+      service.addMessage(mockManager as unknown as EntityManager, 'User', 'u-1', 'UserCreated', {}),
+    ).rejects.toThrow('connection lost');
+  });
+});

package/templates/recipes/typeorm-mysql/README.md

@@ -0,0 +1,48 @@
+# TypeORM MySQL
+
+Database integration using TypeORM with MySQL driver for NestJS applications.
+
+## Links
+
+- [NestJS Database Documentation](https://docs.nestjs.com/techniques/database)
+- [@nestjs/typeorm on npm](https://www.npmjs.com/package/@nestjs/typeorm)
+- [TypeORM Documentation](https://typeorm.io)
+- [TypeORM on GitHub](https://github.com/typeorm/typeorm)
+- [mysql2 on npm](https://www.npmjs.com/package/mysql2)
+
+## Dependencies
+
+| Package           | Version  | Purpose                           |
+| ----------------- | -------- | --------------------------------- |
+| `@nestjs/typeorm` | `10.0.2` | NestJS TypeORM integration module |
+| `typeorm`         | `0.3.20` | TypeScript ORM for SQL databases  |
+| `mysql2`          | `3.11.5` | MySQL client for Node.js          |
+
+## Environment Variables
+
+| Variable         | Default     | Description                              |
+| ---------------- | ----------- | ---------------------------------------- |
+| `DB_HOST`        | `localhost` | MySQL server hostname                    |
+| `DB_PORT`        | `3306`      | MySQL server port                        |
+| `DB_USERNAME`    | `root`      | Database user                            |
+| `DB_PASSWORD`    | —           | Database password                        |
+| `DB_NAME`        | —           | Database name                            |
+| `DB_SYNCHRONIZE` | `false`     | Auto-sync schema (disable in production) |
+| `DB_LOGGING`     | `false`     | Enable SQL query logging                 |
+
+## Usage
+
+```typescript
+import { DatabaseModule } from '@/infrastructure/database/database.module';
+
+@Module({
+  imports: [DatabaseModule],
+})
+export class AppModule {}
+```
+
+## Generated Files
+
+| File                                             | Description                                            |
+| ------------------------------------------------ | ------------------------------------------------------ |
+| `src/infrastructure/database/database.module.ts` | TypeORM module configured with MySQL and ConfigService |

package/templates/recipes/typeorm-mysql/src/infrastructure/database/database.module.ts.ejs

@@ -0,0 +1,24 @@
+import { Module } from '@nestjs/common';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { TypeOrmModule } from '@nestjs/typeorm';
+
+@Module({
+  imports: [
+    TypeOrmModule.forRootAsync({
+      imports: [ConfigModule],
+      inject: [ConfigService],
+      useFactory: (configService: ConfigService) => ({
+        type: 'mysql',
+        host: configService.get<string>('DB_HOST', 'localhost'),
+        port: configService.get<number>('DB_PORT', 3306),
+        username: configService.get<string>('DB_USERNAME', 'root'),
+        password: configService.getOrThrow<string>('DB_PASSWORD'),
+        database: configService.get<string>('DB_NAME', '<%= name %>'),
+        autoLoadEntities: true,
+        synchronize: configService.get<boolean>('DB_SYNCHRONIZE', false),
+        logging: configService.get<boolean>('DB_LOGGING', false),
+      }),
+    }),
+  ],
+})
+export class DatabaseModule {}

package/templates/recipes/typeorm-postgres/README.md

@@ -0,0 +1,101 @@
+# TypeORM PostgreSQL
+
+Database integration using TypeORM with PostgreSQL driver for NestJS applications.
+
+## Links
+
+- [NestJS Database Documentation](https://docs.nestjs.com/techniques/database)
+- [@nestjs/typeorm on npm](https://www.npmjs.com/package/@nestjs/typeorm)
+- [TypeORM Documentation](https://typeorm.io)
+- [TypeORM on GitHub](https://github.com/typeorm/typeorm)
+- [pg on npm](https://www.npmjs.com/package/pg)
+
+## Dependencies
+
+| Package           | Version  | Purpose                           |
+| ----------------- | -------- | --------------------------------- |
+| `@nestjs/typeorm` | `10.0.2` | NestJS TypeORM integration module |
+| `typeorm`         | `0.3.20` | TypeScript ORM for SQL databases  |
+| `pg`              | `8.13.1` | PostgreSQL client for Node.js     |
+
+## Environment Variables
+
+| Variable         | Default     | Description                              |
+| ---------------- | ----------- | ---------------------------------------- |
+| `DB_HOST`        | `localhost` | PostgreSQL server hostname               |
+| `DB_PORT`        | `5432`      | PostgreSQL server port                   |
+| `DB_USERNAME`    | `postgres`  | Database user                            |
+| `DB_PASSWORD`    | —           | Database password                        |
+| `DB_NAME`        | —           | Database name                            |
+| `DB_SYNCHRONIZE` | `false`     | Auto-sync schema (disable in production) |
+| `DB_LOGGING`     | `false`     | Enable SQL query logging                 |
+
+## Usage
+
+```typescript
+import { DatabaseModule } from '@/infrastructure/database/database.module';
+
+@Module({
+  imports: [DatabaseModule],
+})
+export class AppModule {}
+```
+
+## Generated Files
+
+| File                                              | Description                                                 |
+| ------------------------------------------------- | ----------------------------------------------------------- |
+| `src/infrastructure/database/database.module.ts`  | TypeORM module configured with PostgreSQL and ConfigService |
+| `src/infrastructure/database/entities/`           | Directory for TypeORM entity definitions                    |
+| `src/infrastructure/database/migrations/`         | Directory for database migration files                      |
+| `src/infrastructure/database/migrations/index.ts` | Barrel file for explicit migration imports (Lambda compat)  |
+| `src/infrastructure/database/entities/index.ts`   | Barrel file for entity class exports                        |
+| `src/infrastructure/database/data-source.ts`      | CLI data source for local migration commands                |
+| `src/lambdas/migration-runner/index.ts`           | Lambda handler for serverless migration execution           |
+
+## Migration Workflow
+
+### Local Development
+
+```bash
+# Generate migration from entity changes
+pnpm migration:generate src/infrastructure/database/migrations/MigrationName
+
+# Run pending migrations
+pnpm migration:run
+
+# Revert last migration
+pnpm migration:revert
+```
+
+### Serverless (AWS Lambda)
+
+For serverless deployments, use the migration-runner Lambda pattern. See [Serverless Migrations Standard](../../../docs/standards/serverless-migrations.md).
+
+The migration-runner Lambda:
+
+1. Fetches DB password from AWS Secrets Manager
+2. Connects to the database in a VPC
+3. Runs pending migrations
+4. Returns a standardized JSON response
+5. Pipeline validates the response before deploying application Lambdas
+
+### Package.json Scripts
+
+Add these scripts to your generated project:
+
+```json
+{
+  "typeorm": "typeorm-ts-node-commonjs",
+  "migration:generate": "pnpm typeorm migration:generate -d src/infrastructure/database/data-source.ts",
+  "migration:run": "pnpm typeorm migration:run -d src/infrastructure/database/data-source.ts",
+  "migration:revert": "pnpm typeorm migration:revert -d src/infrastructure/database/data-source.ts"
+}
+```
+
+### Important Notes
+
+- Never use `synchronize: true` in production
+- Each migration runs in its own transaction (`transaction: 'each'`)
+- Always import migrations in the barrel file (`migrations/index.ts`) for Lambda compatibility
+- The CLI data source uses glob patterns (works on filesystem), the Lambda handler uses the barrel file

package/templates/recipes/typeorm-postgres/src/infrastructure/database/data-source.ts.ejs

@@ -0,0 +1,14 @@
+import 'reflect-metadata';
+import { DataSource } from 'typeorm';
+
+export default new DataSource({
+  type: 'postgres',
+  host: process.env.DB_HOST ?? 'localhost',
+  port: Number(process.env.DB_PORT ?? 5432),
+  database: process.env.DB_NAME ?? '<%= name %>',
+  username: process.env.DB_USERNAME ?? 'postgres',
+  password: process.env.DB_PASSWORD ?? (() => { throw new Error('DB_PASSWORD environment variable is required'); })(),
+  entities: ['src/infrastructure/database/entities/**/*.ts'],
+  migrations: ['src/infrastructure/database/migrations/*.ts'],
+  synchronize: false,
+});

package/templates/recipes/typeorm-postgres/src/infrastructure/database/database.module.ts.ejs

@@ -0,0 +1,24 @@
+import { Module } from '@nestjs/common';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { TypeOrmModule } from '@nestjs/typeorm';
+
+@Module({
+  imports: [
+    TypeOrmModule.forRootAsync({
+      imports: [ConfigModule],
+      inject: [ConfigService],
+      useFactory: (configService: ConfigService) => ({
+        type: 'postgres',
+        host: configService.get<string>('DB_HOST', 'localhost'),
+        port: configService.get<number>('DB_PORT', 5432),
+        username: configService.get<string>('DB_USERNAME', 'postgres'),
+        password: configService.getOrThrow<string>('DB_PASSWORD'),
+        database: configService.get<string>('DB_NAME', '<%= name %>'),
+        autoLoadEntities: true,
+        synchronize: configService.get<boolean>('DB_SYNCHRONIZE', false),
+        logging: configService.get<boolean>('DB_LOGGING', false),
+      }),
+    }),
+  ],
+})
+export class DatabaseModule {}

package/templates/recipes/typeorm-postgres/src/infrastructure/database/entities/index.ts

@@ -0,0 +1,7 @@
+// Import entity classes here as they are created.
+// Export them as an array for use in DataSource configuration.
+//
+// Example:
+//   import { User } from './user.entity';
+//   export const entities = [User];
+export const entities: Function[] = [];

package/templates/recipes/typeorm-postgres/src/infrastructure/database/migrations/index.ts

@@ -0,0 +1,10 @@
+import type { MigrationInterface } from 'typeorm';
+
+// Import migration classes here as they are generated.
+// esbuild cannot resolve glob patterns at runtime in Lambda,
+// so all migrations must be explicitly imported.
+//
+// Workflow:
+//   1. pnpm migration:generate src/infrastructure/database/migrations/MigrationName
+//   2. Import the generated class here and add it to the array
+export const migrations: (new () => MigrationInterface)[] = [];

package/templates/recipes/typeorm-postgres/tests/unit/infrastructure/database/database.module.spec.ts

@@ -0,0 +1,11 @@
+import { Test } from '@nestjs/testing';
+import { ConfigModule } from '@nestjs/config';
+
+describe('DatabaseModule', () => {
+  it('should compile with config', async () => {
+    const module = await Test.createTestingModule({
+      imports: [ConfigModule.forRoot()],
+    }).compile();
+    expect(module).toBeDefined();
+  });
+});

package/templates/recipes/webhooks/README.md

@@ -0,0 +1,76 @@
+# Webhook Delivery
+
+Outbound webhook system with HMAC-SHA256 signing and configurable timeouts.
+
+## Links
+
+- [Webhook Best Practices (Standard Webhooks)](https://www.standardwebhooks.com/)
+- [HMAC (RFC 2104)](https://datatracker.ietf.org/doc/html/rfc2104)
+
+## Dependencies
+
+No additional dependencies required.
+
+## Environment Variables
+
+| Variable         | Default     | Description                      |
+| ---------------- | ----------- | -------------------------------- |
+| `WEBHOOK_SECRET` | `change-me` | HMAC secret for signing payloads |
+
+## Usage
+
+Inject `WebhookService` and call `deliver()` with a target URL and payload:
+
+```typescript
+import { WebhookService, WebhookPayload } from '@/infrastructure/webhooks/webhook.service';
+
+@Injectable()
+export class OrderService {
+  constructor(private readonly webhooks: WebhookService) {}
+
+  async completeOrder(order: Order): Promise<void> {
+    await this.save(order);
+
+    await this.webhooks.deliver('https://partner.example.com/hooks', {
+      event: 'order.completed',
+      data: { orderId: order.id, total: order.total },
+      timestamp: new Date().toISOString(),
+    });
+  }
+}
+```
+
+### HMAC Signature Verification (Consumer Side)
+
+Consumers verify the signature by computing HMAC-SHA256 of the raw request body using the shared secret:
+
+```typescript
+import { createHmac } from 'node:crypto';
+
+function verifySignature(body: string, signature: string, secret: string): boolean {
+  const expected = createHmac('sha256', secret).update(body).digest('hex');
+  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
+}
+```
+
+### Retry Strategy
+
+The service includes a 10-second timeout per delivery attempt. For production use, combine with a queue (BullMQ or RabbitMQ) for automatic retries with exponential backoff:
+
+1. Enqueue webhook deliveries instead of sending inline
+2. Configure max retries and backoff in the queue processor
+3. Route permanently failed deliveries to a dead letter queue
+
+### Delivery Logging
+
+All delivery attempts are logged via NestJS Logger:
+
+- Successful deliveries: debug level
+- Non-2xx responses: warn level with status code
+- Network errors: error level with message
+
+## Generated Files
+
+| File                                             | Description                                |
+| ------------------------------------------------ | ------------------------------------------ |
+| `src/infrastructure/webhooks/webhook.service.ts` | Webhook delivery service with HMAC signing |

package/templates/recipes/webhooks/src/infrastructure/webhooks/webhook.service.ts

@@ -0,0 +1,53 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { createHmac } from 'node:crypto';
+import { ConfigService } from '@nestjs/config';
+
+export interface WebhookPayload {
+  event: string;
+  data: unknown;
+  timestamp: string;
+}
+
+@Injectable()
+export class WebhookService {
+  private readonly logger = new Logger(WebhookService.name);
+  private readonly secret: string;
+
+  constructor(private readonly configService: ConfigService) {
+    this.secret = this.configService.getOrThrow<string>('WEBHOOK_SECRET');
+  }
+
+  async deliver(url: string, payload: WebhookPayload): Promise<boolean> {
+    const body = JSON.stringify(payload);
+    const signature = this.sign(body);
+
+    try {
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Webhook-Signature': signature,
+          'X-Webhook-Timestamp': payload.timestamp,
+        },
+        body,
+        signal: AbortSignal.timeout(10000),
+      });
+
+      if (!response.ok) {
+        this.logger.warn(`Webhook delivery failed: ${url} returned ${response.status}`);
+        return false;
+      }
+
+      return true;
+    } catch (error) {
+      this.logger.error(
+        `Webhook delivery error: ${error instanceof Error ? error.message : String(error)}`,
+      );
+      return false;
+    }
+  }
+
+  private sign(payload: string): string {
+    return createHmac('sha256', this.secret).update(payload).digest('hex');
+  }
+}

package/templates/recipes/webhooks/tests/unit/infrastructure/webhooks/webhook.service.spec.ts

@@ -0,0 +1,31 @@
+import { WebhookService } from '@/infrastructure/webhooks/webhook.service';
+import { ConfigService } from '@nestjs/config';
+
+describe('WebhookService', () => {
+  let service: WebhookService;
+
+  beforeEach(() => {
+    const configService = {
+      get: jest.fn().mockReturnValue('test-secret'),
+    } as unknown as ConfigService;
+    service = new WebhookService(configService);
+  });
+
+  it('should produce a consistent HMAC-SHA256 signature for the same payload', () => {
+    const payload = JSON.stringify({ event: 'test', data: {}, timestamp: '2026-01-01T00:00:00Z' });
+
+    const sig1 = (service as any).sign(payload);
+    const sig2 = (service as any).sign(payload);
+
+    expect(typeof sig1).toBe('string');
+    expect(sig1).toHaveLength(64); // SHA-256 hex digest
+    expect(sig1).toBe(sig2);
+  });
+
+  it('should produce different signatures for different payloads', () => {
+    const sig1 = (service as any).sign('{"event":"a"}');
+    const sig2 = (service as any).sign('{"event":"b"}');
+
+    expect(sig1).not.toBe(sig2);
+  });
+});

package/templates/recipes/websockets/README.md

@@ -0,0 +1,44 @@
+# WebSockets
+
+Real-time bidirectional communication using NestJS WebSocket gateways.
+
+## Links
+
+- [NestJS WebSocket Gateways](https://docs.nestjs.com/websockets/gateways)
+- [@nestjs/websockets on npm](https://www.npmjs.com/package/@nestjs/websockets)
+- [@nestjs/platform-socket.io on npm](https://www.npmjs.com/package/@nestjs/platform-socket.io)
+- [@nestjs/websockets on GitHub](https://github.com/nestjs/nest/tree/master/packages/websockets)
+
+## Dependencies
+
+| Package                      | Version   | Purpose                     |
+| ---------------------------- | --------- | --------------------------- |
+| `@nestjs/websockets`         | `11.0.20` | WebSocket module for NestJS |
+| `@nestjs/platform-socket.io` | `11.0.20` | Socket.IO platform adapter  |
+
+## Usage
+
+```typescript
+import { EventsGateway } from '@/shared/gateways/events.gateway';
+
+@Module({
+  providers: [EventsGateway],
+})
+export class AppModule {}
+```
+
+Connect from a client:
+
+```typescript
+import { io } from 'socket.io-client';
+
+const socket = io('http://localhost:3000');
+socket.emit('ping', { timestamp: Date.now() });
+socket.on('pong', (data) => console.log(data));
+```
+
+## Generated Files
+
+| File                                    | Description                              |
+| --------------------------------------- | ---------------------------------------- |
+| `src/shared/gateways/events.gateway.ts` | Example WebSocket gateway with ping/pong |