spoonfeeder 0.1.0

package/templates/recipes/cloud-gcp/pubsub/README.md

@@ -0,0 +1,43 @@
+# GCP Pub/Sub
+
+Google Cloud Pub/Sub messaging integration for NestJS.
+
+## Documentation
+
+- [GCP Pub/Sub Documentation](https://cloud.google.com/pubsub/docs)
+- [@google-cloud/pubsub on npm](https://www.npmjs.com/package/@google-cloud/pubsub)
+- [NestJS Microservices](https://docs.nestjs.com/microservices/basics)
+
+## Dependencies
+
+| Package                | Version | Purpose                     |
+| ---------------------- | ------- | --------------------------- |
+| `@google-cloud/pubsub` | `4.9.0` | Google Cloud Pub/Sub client |
+
+## Environment Variables
+
+| Variable              | Default | Description               |
+| --------------------- | ------- | ------------------------- |
+| `GCP_PROJECT_ID`      | —       | GCP project ID            |
+| `PUBSUB_TOPIC`        | —       | Pub/Sub topic name        |
+| `PUBSUB_SUBSCRIPTION` | —       | Pub/Sub subscription name |
+
+## Usage
+
+```typescript
+import { PubSubService } from '@/gcp/pubsub.service';
+
+@Injectable()
+export class EventPublisher {
+  constructor(private readonly pubsub: PubSubService) {}
+
+  async publish(event: DomainEvent): Promise<string> {
+    const messageId = await this.pubsub.publishMessage(
+      this.configService.get('PUBSUB_TOPIC'),
+      JSON.stringify(event),
+      { eventType: event.type },
+    );
+    return messageId;
+  }
+}
+```

package/templates/recipes/cloud-gcp/pubsub/src/infrastructure/gcp/pubsub.module.ts

@@ -0,0 +1,10 @@
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { PubSubService } from './pubsub.service';
+
+@Module({
+  imports: [ConfigModule],
+  providers: [PubSubService],
+  exports: [PubSubService],
+})
+export class PubSubModule {}

package/templates/recipes/cloud-gcp/pubsub/src/infrastructure/gcp/pubsub.service.ts

@@ -0,0 +1,60 @@
+import { Injectable, Logger, OnModuleDestroy } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { PubSub, Subscription, Topic } from '@google-cloud/pubsub';
+
+@Injectable()
+export class PubSubService implements OnModuleDestroy {
+  private readonly logger = new Logger(PubSubService.name);
+  private readonly client: PubSub;
+  private readonly subscriptions: Subscription[] = [];
+
+  constructor(private readonly config: ConfigService) {
+    this.client = new PubSub({
+      projectId: this.config.getOrThrow<string>('GCP_PROJECT_ID'),
+    });
+  }
+
+  async publishMessage(
+    topicName: string,
+    data: string,
+    attributes?: Record<string, string>,
+  ): Promise<string> {
+    const topic: Topic = this.client.topic(topicName);
+    const dataBuffer = Buffer.from(data);
+    const messageId = await topic.publishMessage({
+      data: dataBuffer,
+      attributes,
+    });
+    this.logger.log(`Message ${messageId} published to topic ${topicName}`);
+    return messageId;
+  }
+
+  async createSubscription(
+    topicName: string,
+    subscriptionName: string,
+    handler: (message: { data: Buffer; ack: () => void }) => void,
+  ): Promise<Subscription> {
+    const topic = this.client.topic(topicName);
+    const [subscription] = await topic.createSubscription(subscriptionName).catch(() => {
+      return [this.client.subscription(subscriptionName)];
+    });
+
+    subscription.on('message', (message) => {
+      handler({ data: message.data, ack: () => message.ack() });
+    });
+
+    subscription.on('error', (error) => {
+      this.logger.error(`Subscription ${subscriptionName} error: ${error.message}`);
+    });
+
+    this.subscriptions.push(subscription);
+    this.logger.log(`Listening on subscription ${subscriptionName}`);
+    return subscription;
+  }
+
+  async onModuleDestroy(): Promise<void> {
+    for (const subscription of this.subscriptions) {
+      subscription.removeAllListeners();
+    }
+  }
+}

package/templates/recipes/cloud-gcp/secret-manager/README.md

@@ -0,0 +1,40 @@
+# GCP Secret Manager
+
+Google Cloud Secret Manager for secret storage in NestJS.
+
+## Documentation
+
+- [GCP Secret Manager Documentation](https://cloud.google.com/secret-manager/docs)
+- [@google-cloud/secret-manager on npm](https://www.npmjs.com/package/@google-cloud/secret-manager)
+- [NestJS Configuration](https://docs.nestjs.com/techniques/configuration)
+
+## Dependencies
+
+| Package                        | Version | Purpose                            |
+| ------------------------------ | ------- | ---------------------------------- |
+| `@google-cloud/secret-manager` | `5.6.0` | Google Cloud Secret Manager client |
+
+## Environment Variables
+
+| Variable         | Default | Description    |
+| ---------------- | ------- | -------------- |
+| `GCP_PROJECT_ID` | —       | GCP project ID |
+
+## Usage
+
+```typescript
+import { GcpSecretsService } from '@/gcp/secrets.service';
+
+@Injectable()
+export class DatabaseConfig {
+  constructor(private readonly secrets: GcpSecretsService) {}
+
+  async getDatabasePassword(): Promise<string> {
+    return this.secrets.accessSecret('database-password');
+  }
+
+  async getApiKey(name: string): Promise<string> {
+    return this.secrets.accessSecret(name);
+  }
+}
+```

package/templates/recipes/cloud-gcp/secret-manager/src/infrastructure/gcp/secrets.module.ts

@@ -0,0 +1,10 @@
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { GcpSecretsService } from './secrets.service';
+
+@Module({
+  imports: [ConfigModule],
+  providers: [GcpSecretsService],
+  exports: [GcpSecretsService],
+})
+export class GcpSecretsModule {}

package/templates/recipes/cloud-gcp/secret-manager/src/infrastructure/gcp/secrets.service.ts

@@ -0,0 +1,41 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { SecretManagerServiceClient } from '@google-cloud/secret-manager';
+
+@Injectable()
+export class GcpSecretsService {
+  private readonly logger = new Logger(GcpSecretsService.name);
+  private readonly client: SecretManagerServiceClient;
+  private readonly projectId: string;
+
+  constructor(private readonly config: ConfigService) {
+    this.client = new SecretManagerServiceClient();
+    this.projectId = this.config.getOrThrow<string>('GCP_PROJECT_ID');
+  }
+
+  async getSecret(secretName: string, version = 'latest'): Promise<string> {
+    const name = `projects/${this.projectId}/secrets/${secretName}/versions/${version}`;
+    const [response] = await this.client.accessSecretVersion({ name });
+    const payload = response.payload?.data;
+
+    if (!payload) {
+      throw new Error(`Secret ${secretName} has no payload`);
+    }
+
+    this.logger.log(`Accessed secret ${secretName} version ${version}`);
+    return typeof payload === 'string' ? payload : new TextDecoder('utf-8').decode(payload);
+  }
+
+  async getSecretJson<T = Record<string, unknown>>(
+    secretName: string,
+    version = 'latest',
+  ): Promise<T> {
+    const raw = await this.getSecret(secretName, version);
+
+    try {
+      return JSON.parse(raw) as T;
+    } catch {
+      throw new Error(`Secret ${secretName} is not valid JSON`);
+    }
+  }
+}

package/templates/recipes/config-validation/README.md

@@ -0,0 +1,61 @@
+# Config Schema Validation
+
+Validate environment variables at startup using Zod schemas, providing typed configuration access and fast failure on misconfiguration.
+
+## Links
+
+- [Zod Documentation](https://zod.dev/)
+- [NestJS Configuration](https://docs.nestjs.com/techniques/configuration)
+
+## Dependencies
+
+No additional dependencies required. Uses Zod, which is already available via the CLI.
+
+## Usage
+
+Pass `validateEnv` as the `validate` function in `ConfigModule.forRoot()`:
+
+```typescript
+import { ConfigModule } from '@nestjs/config';
+import { validateEnv } from '@/config/env.validation';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({
+      validate: validateEnv,
+      isGlobal: true,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+The application will fail to start if any required environment variable is missing or has an invalid value, with a clear error message listing all validation failures.
+
+### Typed Config Access
+
+Use the `EnvConfig` type for type-safe configuration access:
+
+```typescript
+import { ConfigService } from '@nestjs/config';
+import { EnvConfig } from '@/config/env.validation';
+
+@Injectable()
+export class AppService {
+  constructor(private readonly config: ConfigService<EnvConfig, true>) {}
+
+  getPort(): number {
+    return this.config.get('PORT');
+  }
+}
+```
+
+### Adding New Variables
+
+Add new environment variables to the `envSchema` object in `src/config/env.validation.ts`. The schema supports defaults, coercion, and custom validation rules via Zod.
+
+## Generated Files
+
+| File                           | Description                                     |
+| ------------------------------ | ----------------------------------------------- |
+| `src/config/env.validation.ts` | Zod schema and validation function for env vars |

package/templates/recipes/config-validation/src/config/env.validation.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+
+const envSchema = z.object({
+  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
+  PORT: z.coerce.number().int().positive().default(3000),
+
+  // Database (uncomment when using a database recipe)
+  // DB_HOST: z.string().min(1),
+  // DB_PORT: z.coerce.number().int().positive(),
+  // DB_NAME: z.string().min(1),
+  // DB_USERNAME: z.string().min(1),
+  // DB_PASSWORD: z.string().min(1),
+});
+
+export type EnvConfig = z.infer<typeof envSchema>;
+
+export function validateEnv(config: Record<string, unknown>): EnvConfig {
+  const result = envSchema.safeParse(config);
+
+  if (!result.success) {
+    const errors = result.error.issues
+      .map((issue) => `  ${issue.path.join('.')}: ${issue.message}`)
+      .join('\n');
+    throw new Error(`Environment validation failed:\n${errors}`);
+  }
+
+  return result.data;
+}

package/templates/recipes/config-validation/tests/unit/config/env.validation.spec.ts

@@ -0,0 +1,34 @@
+import { validateEnv } from '@/config/env.validation';
+
+describe('validateEnv', () => {
+  it('should return defaults when no environment variables are provided', () => {
+    const result = validateEnv({});
+
+    expect(result.NODE_ENV).toBe('development');
+    expect(result.PORT).toBe(3000);
+  });
+
+  it('should accept valid environment variables', () => {
+    const result = validateEnv({
+      NODE_ENV: 'production',
+      PORT: '8080',
+    });
+
+    expect(result.NODE_ENV).toBe('production');
+    expect(result.PORT).toBe(8080);
+  });
+
+  it('should coerce PORT from string to number', () => {
+    const result = validateEnv({ PORT: '4000' });
+    expect(result.PORT).toBe(4000);
+    expect(typeof result.PORT).toBe('number');
+  });
+
+  it('should throw for an invalid NODE_ENV value', () => {
+    expect(() => validateEnv({ NODE_ENV: 'staging' })).toThrow('Environment validation failed');
+  });
+
+  it('should throw for a non-positive PORT value', () => {
+    expect(() => validateEnv({ PORT: '-1' })).toThrow('Environment validation failed');
+  });
+});

package/templates/recipes/content-digest/README.md

@@ -0,0 +1,28 @@
+# Content Digest
+
+Implements [RFC 9530 — HTTP Content Digest](https://datatracker.ietf.org/doc/html/rfc9530) for payload integrity verification via digest headers.
+
+## How it works
+
+### Response digest (interceptor)
+
+`ContentDigestInterceptor` hashes the serialized JSON response body with SHA-256 and sets both `Content-Digest` and `Repr-Digest` headers on every non-empty response.
+
+### Request verification (guard)
+
+`ContentDigestGuard` optionally validates inbound requests. If a `Content-Digest` header is present, the guard recomputes the hash and rejects the request with `400 Bad Request` when the digest does not match.
+
+## Setup
+
+Register the interceptor globally and apply the guard where needed:
+
+```typescript
+import { ContentDigestInterceptor } from '@/shared/interceptors/content-digest.interceptor';
+import { ContentDigestGuard } from '@/shared/guards/content-digest.guard';
+
+app.useGlobalInterceptors(new ContentDigestInterceptor());
+```
+
+## References
+
+- [RFC 9530 — Digest Fields](https://datatracker.ietf.org/doc/html/rfc9530)

package/templates/recipes/content-digest/src/shared/guards/content-digest.guard.ts

@@ -0,0 +1,30 @@
+import { CanActivate, ExecutionContext, Injectable, BadRequestException } from '@nestjs/common';
+import { createHash } from 'node:crypto';
+import { timingSafeEqual } from 'node:crypto';
+import { FastifyRequest } from 'fastify';
+
+@Injectable()
+export class ContentDigestGuard implements CanActivate {
+  canActivate(context: ExecutionContext): boolean {
+    const request = context.switchToHttp().getRequest<FastifyRequest>();
+    const digestHeader = request.headers['content-digest'] as string | undefined;
+
+    if (!digestHeader) return true; // Optional — only verify if provided
+
+    const match = digestHeader.match(/sha-256=:([^:]+):/);
+    if (!match) throw new BadRequestException('Invalid Content-Digest header format');
+
+    const expectedHash = match[1];
+    const body = JSON.stringify(request.body);
+    const actualHash = createHash('sha-256').update(body).digest('base64');
+
+    const expectedBuffer = Buffer.from(expectedHash, 'base64');
+    const actualBuffer = Buffer.from(actualHash, 'base64');
+
+    if (expectedBuffer.length !== actualBuffer.length || !timingSafeEqual(expectedBuffer, actualBuffer)) {
+      throw new BadRequestException('Content-Digest mismatch — payload integrity check failed');
+    }
+
+    return true;
+  }
+}

package/templates/recipes/content-digest/src/shared/interceptors/content-digest.interceptor.ts

@@ -0,0 +1,23 @@
+import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';
+import { Observable } from 'rxjs';
+import { tap } from 'rxjs/operators';
+import { createHash } from 'node:crypto';
+import { FastifyReply } from 'fastify';
+
+@Injectable()
+export class ContentDigestInterceptor implements NestInterceptor {
+  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
+    return next.handle().pipe(
+      tap((data) => {
+        if (data === undefined || data === null) return;
+
+        const response = context.switchToHttp().getResponse<FastifyReply>();
+        const body = JSON.stringify(data);
+        const hash = createHash('sha-256').update(body).digest('base64');
+
+        void response.header('Content-Digest', `sha-256=:${hash}:`);
+        void response.header('Repr-Digest', `sha-256=:${hash}:`);
+      }),
+    );
+  }
+}

package/templates/recipes/content-digest/tests/unit/shared/guards/content-digest.guard.spec.ts

@@ -0,0 +1,56 @@
+import { ExecutionContext, BadRequestException } from '@nestjs/common';
+import { createHash } from 'node:crypto';
+import { ContentDigestGuard } from '@/shared/guards/content-digest.guard';
+
+describe('ContentDigestGuard', () => {
+  let guard: ContentDigestGuard;
+
+  function createMockContext(body: unknown, digestHeader?: string): ExecutionContext {
+    return {
+      switchToHttp: () => ({
+        getRequest: () => ({
+          headers: {
+            'content-digest': digestHeader,
+          },
+          body,
+        }),
+      }),
+    } as unknown as ExecutionContext;
+  }
+
+  beforeEach(() => {
+    guard = new ContentDigestGuard();
+  });
+
+  it('should be defined', () => {
+    expect(guard).toBeDefined();
+  });
+
+  it('should return true when no Content-Digest header is present', () => {
+    const context = createMockContext({ foo: 'bar' }, undefined);
+    expect(guard.canActivate(context)).toBe(true);
+  });
+
+  it('should return true when the digest matches the body', () => {
+    const body = { message: 'hello' };
+    const hash = createHash('sha-256').update(JSON.stringify(body)).digest('base64');
+    const context = createMockContext(body, `sha-256=:${hash}:`);
+
+    expect(guard.canActivate(context)).toBe(true);
+  });
+
+  it('should throw BadRequestException when the digest does not match', () => {
+    const body = { message: 'hello' };
+    const context = createMockContext(body, 'sha-256=:aW52YWxpZA==:');
+
+    expect(() => guard.canActivate(context)).toThrow(BadRequestException);
+    expect(() => guard.canActivate(context)).toThrow('Content-Digest mismatch');
+  });
+
+  it('should throw BadRequestException for an invalid header format', () => {
+    const context = createMockContext({ a: 1 }, 'md5=abc123');
+
+    expect(() => guard.canActivate(context)).toThrow(BadRequestException);
+    expect(() => guard.canActivate(context)).toThrow('Invalid Content-Digest header format');
+  });
+});

package/templates/recipes/content-digest/tests/unit/shared/interceptors/content-digest.interceptor.spec.ts

@@ -0,0 +1,54 @@
+import { ExecutionContext } from '@nestjs/common';
+import { of } from 'rxjs';
+import { createHash } from 'node:crypto';
+import { ContentDigestInterceptor } from '@/shared/interceptors/content-digest.interceptor';
+
+describe('ContentDigestInterceptor', () => {
+  let interceptor: ContentDigestInterceptor;
+
+  beforeEach(() => {
+    interceptor = new ContentDigestInterceptor();
+  });
+
+  it('should be defined', () => {
+    expect(interceptor).toBeDefined();
+  });
+
+  it('should set Content-Digest and Repr-Digest headers on the response', (done) => {
+    const responseBody = { id: 1, name: 'test' };
+    const expectedHash = createHash('sha-256')
+      .update(JSON.stringify(responseBody))
+      .digest('base64');
+
+    const headerFn = jest.fn();
+    const context = {
+      switchToHttp: () => ({
+        getResponse: () => ({ header: headerFn }),
+      }),
+    } as unknown as ExecutionContext;
+
+    const next = { handle: () => of(responseBody) };
+
+    interceptor.intercept(context, next).subscribe(() => {
+      expect(headerFn).toHaveBeenCalledWith('Content-Digest', `sha-256=:${expectedHash}:`);
+      expect(headerFn).toHaveBeenCalledWith('Repr-Digest', `sha-256=:${expectedHash}:`);
+      done();
+    });
+  });
+
+  it('should not set headers when the response body is null or undefined', (done) => {
+    const headerFn = jest.fn();
+    const context = {
+      switchToHttp: () => ({
+        getResponse: () => ({ header: headerFn }),
+      }),
+    } as unknown as ExecutionContext;
+
+    const next = { handle: () => of(null) };
+
+    interceptor.intercept(context, next).subscribe(() => {
+      expect(headerFn).not.toHaveBeenCalled();
+      done();
+    });
+  });
+});

package/templates/recipes/correlation-id/README.md

@@ -0,0 +1,44 @@
+# Correlation ID
+
+Request correlation using AsyncLocalStorage for distributed tracing across services.
+
+## Links
+
+- [Node.js AsyncLocalStorage](https://nodejs.org/api/async_context.html#class-asynclocalstorage)
+- [NestJS Middleware](https://docs.nestjs.com/middleware)
+
+## Dependencies
+
+No additional dependencies required. Uses the built-in `node:async_hooks` module.
+
+| Package | Version | Purpose                     |
+| ------- | ------- | --------------------------- |
+| (none)  | -       | Built-in `node:async_hooks` |
+
+## Usage
+
+Register middleware in your module:
+
+```typescript
+import { CorrelationIdMiddleware } from '@/shared/middleware/correlation-id.middleware';
+
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    consumer.apply(CorrelationIdMiddleware).forRoutes('*');
+  }
+}
+```
+
+Access the correlation ID anywhere in the call chain:
+
+```typescript
+import { correlationStorage } from '@/shared/middleware/correlation-id.middleware';
+
+const correlationId = correlationStorage.getStore();
+```
+
+## Generated Files
+
+| File                                                 | Description                                                                               |
+| ---------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `src/shared/middleware/correlation-id.middleware.ts` | Middleware that extracts or generates a correlation ID and stores it in AsyncLocalStorage |

package/templates/recipes/correlation-id/src/shared/middleware/correlation-id.middleware.ts

@@ -0,0 +1,29 @@
+import { Injectable, NestMiddleware } from '@nestjs/common';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { FastifyReply, FastifyRequest } from 'fastify';
+
+const CORRELATION_HEADER = 'x-correlation-id';
+
+export const correlationStorage = new AsyncLocalStorage<string>();
+
+@Injectable()
+export class CorrelationIdMiddleware implements NestMiddleware {
+  use(req: FastifyRequest['raw'], res: FastifyReply['raw'], next: () => void): void {
+    const incoming = req.headers[CORRELATION_HEADER] as string | undefined;
+    const correlationId = incoming || crypto.randomUUID();
+
+    res.setHeader(CORRELATION_HEADER, correlationId);
+
+    correlationStorage.run(correlationId, () => {
+      next();
+    });
+  }
+}
+
+/**
+ * Retrieve the current correlation ID from anywhere in the async call chain.
+ * Returns undefined if called outside of a request context.
+ */
+export function getCorrelationId(): string | undefined {
+  return correlationStorage.getStore();
+}

package/templates/recipes/correlation-id/tests/unit/shared/middleware/correlation-id.spec.ts

@@ -0,0 +1,5 @@
+describe('CorrelationIdMiddleware', () => {
+  it('should generate correlation ID if not present', () => {
+    expect(true).toBe(true);
+  });
+});

package/templates/recipes/cors/README.md

@@ -0,0 +1,45 @@
+# CORS
+
+Cross-Origin Resource Sharing configuration for NestJS.
+
+## Links
+
+- [NestJS CORS Documentation](https://docs.nestjs.com/security/cors)
+- [MDN CORS Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)
+
+## Dependencies
+
+No additional dependencies required. CORS support is built into NestJS and the Fastify adapter.
+
+| Package | Version | Purpose                                |
+| ------- | ------- | -------------------------------------- |
+| (none)  | -       | Built-in to `@nestjs/platform-fastify` |
+
+## Environment Variables
+
+| Variable       | Description                     | Example                                             |
+| -------------- | ------------------------------- | --------------------------------------------------- |
+| `CORS_ORIGIN` | Comma-separated allowed origins | `https://app.example.com,https://admin.example.com` |
+
+## Usage
+
+Configure in `main.ts`:
+
+```typescript
+const app = await NestFactory.create<NestFastifyApplication>(AppModule, new FastifyAdapter());
+
+app.enableCors({
+  origin: process.env.CORS_ORIGIN?.split(',') ?? false,
+  methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
+  allowedHeaders: ['Content-Type', 'Authorization', 'X-Correlation-Id'],
+  exposedHeaders: ['X-Correlation-Id'],
+  credentials: true,
+  maxAge: 3600,
+});
+```
+
+## Generated Files
+
+| File   | Description                                 |
+| ------ | ------------------------------------------- |
+| (none) | Applied directly in `main.ts` configuration |