spoonfeeder 0.1.0

package/templates/recipes/pagination/src/shared/decorators/paginate.decorator.ts

@@ -0,0 +1,25 @@
+import { createParamDecorator, ExecutionContext } from '@nestjs/common';
+import { plainToInstance } from 'class-transformer';
+import { validateSync } from 'class-validator';
+import { PaginatedQuery } from '@/shared/dto/pagination.dto';
+import { FastifyRequest } from 'fastify';
+
+export const Paginate = createParamDecorator(
+  (_data: unknown, ctx: ExecutionContext): PaginatedQuery => {
+    const request = ctx.switchToHttp().getRequest<FastifyRequest>();
+    const query = request.query as Record<string, string>;
+
+    const pagination = plainToInstance(PaginatedQuery, {
+      page: query.page ? parseInt(query.page, 10) : 1,
+      limit: query.limit ? parseInt(query.limit, 10) : 20,
+    });
+
+    const errors = validateSync(pagination);
+
+    if (errors.length > 0) {
+      return plainToInstance(PaginatedQuery, { page: 1, limit: 20 });
+    }
+
+    return pagination;
+  },
+);

package/templates/recipes/pagination/src/shared/dto/pagination.dto.ts

@@ -0,0 +1,64 @@
+import { IsInt, IsOptional, Max, Min } from 'class-validator';
+import { Type } from 'class-transformer';
+import { ApiPropertyOptional } from '@nestjs/swagger';
+
+export class PaginatedQuery {
+  @ApiPropertyOptional({ minimum: 1, default: 1 })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  page: number = 1;
+
+  @ApiPropertyOptional({ minimum: 1, maximum: 100, default: 20 })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(100)
+  limit: number = 20;
+
+  get skip(): number {
+    return (this.page - 1) * this.limit;
+  }
+}
+
+export class PaginatedResponse<T> {
+  readonly items: T[];
+  readonly total: number;
+  readonly page: number;
+  readonly limit: number;
+  readonly totalPages: number;
+  readonly hasNextPage: boolean;
+  readonly hasPreviousPage: boolean;
+
+  constructor(items: T[], total: number, page: number, limit: number) {
+    this.items = items;
+    this.total = total;
+    this.page = page;
+    this.limit = limit;
+    this.totalPages = Math.ceil(total / limit);
+    this.hasNextPage = page < this.totalPages;
+    this.hasPreviousPage = page > 1;
+  }
+}
+
+export function buildPaginationLinks(
+  baseUrl: string,
+  page: number,
+  pageSize: number,
+  totalPages: number,
+): string {
+  const links: string[] = [];
+
+  if (page > 1) {
+    links.push(`<${baseUrl}?page=${page - 1}&pageSize=${pageSize}>; rel="prev"`);
+  }
+  if (page < totalPages) {
+    links.push(`<${baseUrl}?page=${page + 1}&pageSize=${pageSize}>; rel="next"`);
+  }
+  links.push(`<${baseUrl}?page=1&pageSize=${pageSize}>; rel="first"`);
+  links.push(`<${baseUrl}?page=${totalPages}&pageSize=${pageSize}>; rel="last"`);
+
+  return links.join(', ');
+}

package/templates/recipes/pagination/src/shared/interceptors/pagination-link.interceptor.ts

@@ -0,0 +1,31 @@
+import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';
+import { Observable } from 'rxjs';
+import { map } from 'rxjs/operators';
+import { FastifyReply, FastifyRequest } from 'fastify';
+import { buildPaginationLinks } from '../dto/pagination.dto';
+
+@Injectable()
+export class PaginationLinkInterceptor implements NestInterceptor {
+  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
+    return next.handle().pipe(
+      map((data) => {
+        if (data && typeof data === 'object' && 'pagination' in data) {
+          const pagination = (data as any).pagination;
+          const request = context.switchToHttp().getRequest<FastifyRequest>();
+          const response = context.switchToHttp().getResponse<FastifyReply>();
+          const baseUrl = `${request.protocol}://${request.hostname}${request.url.split('?')[0]}`;
+
+          const linkHeader = buildPaginationLinks(
+            baseUrl,
+            pagination.page,
+            pagination.pageSize,
+            pagination.totalPages,
+          );
+
+          void response.header('Link', linkHeader);
+        }
+        return data;
+      }),
+    );
+  }
+}

package/templates/recipes/pagination/tests/unit/shared/dto/pagination.dto.spec.ts

@@ -0,0 +1,56 @@
+import {
+  PaginatedQuery,
+  PaginatedResponse,
+  buildPaginationLinks,
+} from '../../../../src/shared/dto/pagination.dto';
+
+describe('PaginatedQuery', () => {
+  it('should have default page 1 and limit 20', () => {
+    const query = new PaginatedQuery();
+    expect(query.page).toBe(1);
+    expect(query.limit).toBe(20);
+  });
+
+  it('should compute skip correctly', () => {
+    const query = new PaginatedQuery();
+    query.page = 3;
+    query.limit = 10;
+    expect(query.skip).toBe(20);
+  });
+});
+
+describe('PaginatedResponse', () => {
+  it('should compute totalPages, hasNextPage, and hasPreviousPage', () => {
+    const response = new PaginatedResponse(['a', 'b'], 10, 2, 5);
+    expect(response.totalPages).toBe(2);
+    expect(response.hasNextPage).toBe(false);
+    expect(response.hasPreviousPage).toBe(true);
+  });
+});
+
+describe('buildPaginationLinks', () => {
+  const baseUrl = 'https://api.example.com/items';
+
+  it('should include prev, next, first, and last links for a middle page', () => {
+    const links = buildPaginationLinks(baseUrl, 2, 10, 5);
+    expect(links).toContain('rel="prev"');
+    expect(links).toContain('rel="next"');
+    expect(links).toContain('rel="first"');
+    expect(links).toContain('rel="last"');
+    expect(links).toContain('page=1');
+    expect(links).toContain('page=3');
+    expect(links).toContain('page=5');
+  });
+
+  it('should omit prev link on the first page', () => {
+    const links = buildPaginationLinks(baseUrl, 1, 10, 5);
+    expect(links).not.toContain('rel="prev"');
+    expect(links).toContain('rel="next"');
+  });
+
+  it('should omit next link on the last page', () => {
+    const links = buildPaginationLinks(baseUrl, 5, 10, 5);
+    expect(links).toContain('rel="prev"');
+    expect(links).not.toContain('rel="next"');
+  });
+});

package/templates/recipes/passport/README.md

@@ -0,0 +1,41 @@
+# Passport Local Authentication
+
+Local (username/password) authentication strategy using Passport for NestJS applications.
+
+## Links
+
+- [NestJS Authentication Documentation](https://docs.nestjs.com/security/authentication)
+- [Passport.js Documentation](https://www.passportjs.org)
+- [@nestjs/passport on npm](https://www.npmjs.com/package/@nestjs/passport)
+- [passport on npm](https://www.npmjs.com/package/passport)
+- [passport-local on npm](https://www.npmjs.com/package/passport-local)
+- [Passport on GitHub](https://github.com/jaredhanson/passport)
+
+## Dependencies
+
+| Package                 | Version  | Purpose                                   |
+| ----------------------- | -------- | ----------------------------------------- |
+| `@nestjs/passport`      | `10.0.3` | Passport integration for NestJS           |
+| `passport`              | `0.7.0`  | Authentication middleware                 |
+| `passport-local`        | `1.0.0`  | Local (username/password) strategy        |
+| `@types/passport-local` | `1.0.38` | TypeScript definitions for passport-local |
+
+## Usage
+
+```typescript
+// Protect a login route with local strategy
+@Controller('auth')
+export class AuthController {
+  @UseGuards(LocalAuthGuard)
+  @Post('login')
+  login(@Request() req) {
+    return req.user;
+  }
+}
+```
+
+## Generated Files
+
+| File                                    | Description                                                 |
+| --------------------------------------- | ----------------------------------------------------------- |
+| `src/shared/guards/local-auth.guard.ts` | Local authentication guard wrapping Passport local strategy |

package/templates/recipes/passport/src/shared/guards/local-auth.guard.ts

@@ -0,0 +1,5 @@
+import { Injectable } from '@nestjs/common';
+import { AuthGuard } from '@nestjs/passport';
+
+@Injectable()
+export class LocalAuthGuard extends AuthGuard('local') {}

package/templates/recipes/passport/tests/unit/shared/guards/local-auth.guard.spec.ts

@@ -0,0 +1,17 @@
+import { LocalAuthGuard } from '../../../../src/shared/guards/local-auth.guard';
+
+describe('LocalAuthGuard', () => {
+  let guard: LocalAuthGuard;
+
+  beforeEach(() => {
+    guard = new LocalAuthGuard();
+  });
+
+  it('should be defined', () => {
+    expect(guard).toBeDefined();
+  });
+
+  it('should be an instance of LocalAuthGuard', () => {
+    expect(guard).toBeInstanceOf(LocalAuthGuard);
+  });
+});

package/templates/recipes/pino/README.md

@@ -0,0 +1,48 @@
+# Pino Logger
+
+Structured JSON logging using Pino for NestJS applications.
+
+## Links
+
+- [nestjs-pino on npm](https://www.npmjs.com/package/nestjs-pino)
+- [nestjs-pino on GitHub](https://github.com/iamolegga/nestjs-pino)
+- [Pino Documentation](https://getpino.io)
+- [pino on npm](https://www.npmjs.com/package/pino)
+- [pino-pretty on npm](https://www.npmjs.com/package/pino-pretty)
+
+## Dependencies
+
+| Package       | Version  | Purpose                               |
+| ------------- | -------- | ------------------------------------- |
+| `nestjs-pino` | `4.2.0`  | NestJS Pino integration module        |
+| `pino`        | `9.6.0`  | Fast JSON logger                      |
+| `pino-pretty` | `13.0.0` | Pretty-print Pino logs in development |
+| `pino-http`   | `10.4.0` | HTTP request logging for Pino         |
+
+## Environment Variables
+
+| Variable    | Default       | Description                                                            |
+| ----------- | ------------- | ---------------------------------------------------------------------- |
+| `LOG_LEVEL` | `info`        | Minimum log level (`trace`, `debug`, `info`, `warn`, `error`, `fatal`) |
+| `NODE_ENV`  | `development` | Environment (controls pretty-printing)                                 |
+
+## Usage
+
+```typescript
+import { LoggerModule } from '@/infrastructure/logging/logger.module';
+
+@Module({
+  imports: [LoggerModule],
+})
+export class AppModule {}
+
+// In main.ts
+import { Logger } from 'nestjs-pino';
+app.useLogger(app.get(Logger));
+```
+
+## Generated Files
+
+| File                                          | Description                                                        |
+| --------------------------------------------- | ------------------------------------------------------------------ |
+| `src/infrastructure/logging/logger.module.ts` | LoggerModule configured with Pino and environment-aware formatting |

package/templates/recipes/pino/src/infrastructure/logging/logger.module.ts

@@ -0,0 +1,39 @@
+import { Module } from '@nestjs/common';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { LoggerModule as PinoLoggerModule } from 'nestjs-pino';
+
+@Module({
+  imports: [
+    PinoLoggerModule.forRootAsync({
+      imports: [ConfigModule],
+      inject: [ConfigService],
+      useFactory: (configService: ConfigService) => ({
+        pinoHttp: {
+          level: configService.get<string>('LOG_LEVEL', 'info'),
+          transport:
+            configService.get<string>('NODE_ENV') !== 'production'
+              ? {
+                  target: 'pino-pretty',
+                  options: {
+                    colorize: true,
+                    singleLine: true,
+                  },
+                }
+              : undefined,
+          autoLogging: true,
+          serializers: {
+            req: (req: Record<string, unknown>) => ({
+              method: req.method,
+              url: req.url,
+            }),
+            res: (res: Record<string, unknown>) => ({
+              statusCode: res.statusCode,
+            }),
+          },
+        },
+      }),
+    }),
+  ],
+  exports: [PinoLoggerModule],
+})
+export class LoggerModule {}

package/templates/recipes/pino/tests/unit/infrastructure/logging/logger.module.spec.ts

@@ -0,0 +1,6 @@
+describe('LoggerModule', () => {
+  it('should configure pino for the environment', () => {
+    const env = process.env.NODE_ENV ?? 'development';
+    expect(['development', 'test', 'production']).toContain(env);
+  });
+});

package/templates/recipes/prefer-header/README.md

@@ -0,0 +1,92 @@
+# Prefer Header Interceptor
+
+Implementation of [RFC 7240 — Prefer Header for HTTP](https://datatracker.ietf.org/doc/html/rfc7240).
+
+The `PreferInterceptor` parses the `Prefer` request header and adjusts responses accordingly. Applied preferences are echoed back via the `Preference-Applied` response header.
+
+## Supported Preferences
+
+### `return=minimal`
+
+Returns `204 No Content` with an empty body, useful for clients that do not need the response payload after a mutation.
+
+```http
+POST /users HTTP/1.1
+Content-Type: application/json
+Prefer: return=minimal
+
+{"name": "Alice"}
+```
+
+```http
+HTTP/1.1 204 No Content
+Preference-Applied: return=minimal
+```
+
+### `return=representation`
+
+Returns the full resource representation in the response body (default behavior for most endpoints, but the header makes the intent explicit).
+
+```http
+PUT /users/1 HTTP/1.1
+Content-Type: application/json
+Prefer: return=representation
+
+{"name": "Bob"}
+```
+
+```http
+HTTP/1.1 200 OK
+Preference-Applied: return=representation
+Content-Type: application/json
+
+{"id": 1, "name": "Bob", "createdAt": "2025-01-01T00:00:00Z"}
+```
+
+### `respond-async`
+
+Signals that the client prefers asynchronous processing. The interceptor records the preference; the handler is responsible for returning `202 Accepted` with a polling URL when appropriate.
+
+```http
+POST /reports HTTP/1.1
+Content-Type: application/json
+Prefer: respond-async
+
+{"type": "annual-summary"}
+```
+
+```http
+HTTP/1.1 202 Accepted
+Preference-Applied: respond-async
+Location: /reports/jobs/42
+Content-Type: application/json
+
+{"jobId": 42, "status": "pending"}
+```
+
+## Registration
+
+Register the interceptor globally in your application module or bootstrap file:
+
+```typescript
+import { PreferInterceptor } from '@/shared/interceptors/prefer.interceptor';
+
+app.useGlobalInterceptors(new PreferInterceptor());
+```
+
+Or via a module provider:
+
+```typescript
+import { APP_INTERCEPTOR } from '@nestjs/core';
+import { PreferInterceptor } from '@/shared/interceptors/prefer.interceptor';
+
+@Module({
+  providers: [
+    {
+      provide: APP_INTERCEPTOR,
+      useClass: PreferInterceptor,
+    },
+  ],
+})
+export class AppModule {}
+```

package/templates/recipes/prefer-header/src/shared/interceptors/prefer.interceptor.ts

@@ -0,0 +1,60 @@
+import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';
+import { Observable } from 'rxjs';
+import { map } from 'rxjs/operators';
+import { FastifyRequest, FastifyReply } from 'fastify';
+
+@Injectable()
+export class PreferInterceptor implements NestInterceptor {
+  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
+    const request = context.switchToHttp().getRequest<FastifyRequest>();
+    const response = context.switchToHttp().getResponse<FastifyReply>();
+    const prefer = this.parsePrefer(request.headers['prefer'] as string);
+
+    return next.handle().pipe(
+      map((data) => {
+        const applied: string[] = [];
+
+        if (prefer.has('return')) {
+          const returnPref = prefer.get('return');
+          if (returnPref === 'minimal') {
+            applied.push('return=minimal');
+            void response.code(204);
+            return undefined;
+          }
+          if (returnPref === 'representation') {
+            applied.push('return=representation');
+          }
+        }
+
+        if (prefer.has('respond-async')) {
+          applied.push('respond-async');
+          // Signal to the handler that async processing was requested
+          // The handler should return 202 Accepted with a polling URL
+        }
+
+        if (applied.length > 0) {
+          void response.header('Preference-Applied', applied.join(', '));
+        }
+
+        return data;
+      }),
+    );
+  }
+
+  private parsePrefer(header: string | undefined): Map<string, string> {
+    const preferences = new Map<string, string>();
+    if (!header) return preferences;
+
+    for (const part of header.split(',')) {
+      const trimmed = part.trim();
+      const eqIndex = trimmed.indexOf('=');
+      if (eqIndex > 0) {
+        preferences.set(trimmed.slice(0, eqIndex).trim(), trimmed.slice(eqIndex + 1).trim());
+      } else {
+        preferences.set(trimmed, '');
+      }
+    }
+
+    return preferences;
+  }
+}

package/templates/recipes/prefer-header/tests/unit/shared/interceptors/prefer.interceptor.spec.ts

@@ -0,0 +1,44 @@
+import { PreferInterceptor } from '@/shared/interceptors/prefer.interceptor';
+import { of } from 'rxjs';
+
+describe('PreferInterceptor', () => {
+  let interceptor: PreferInterceptor;
+
+  beforeEach(() => {
+    interceptor = new PreferInterceptor();
+  });
+
+  it('should return data unchanged when no Prefer header is present', (done) => {
+    const context = {
+      switchToHttp: () => ({
+        getRequest: () => ({ headers: {} }),
+        getResponse: () => ({ header: jest.fn(), code: jest.fn() }),
+      }),
+    } as any;
+    const next = { handle: () => of({ id: 1 }) };
+
+    interceptor.intercept(context, next).subscribe((result) => {
+      expect(result).toEqual({ id: 1 });
+      done();
+    });
+  });
+
+  it('should return undefined and set status 204 when return=minimal is preferred', (done) => {
+    const codeFn = jest.fn();
+    const headerFn = jest.fn();
+    const context = {
+      switchToHttp: () => ({
+        getRequest: () => ({ headers: { prefer: 'return=minimal' } }),
+        getResponse: () => ({ header: headerFn, code: codeFn }),
+      }),
+    } as any;
+    const next = { handle: () => of({ id: 1 }) };
+
+    interceptor.intercept(context, next).subscribe((result) => {
+      expect(result).toBeUndefined();
+      expect(codeFn).toHaveBeenCalledWith(204);
+      expect(headerFn).toHaveBeenCalledWith('Preference-Applied', 'return=minimal');
+      done();
+    });
+  });
+});

package/templates/recipes/prisma/README.md

@@ -0,0 +1,52 @@
+# Prisma
+
+Type-safe database client using Prisma ORM for NestJS applications.
+
+## Links
+
+- [NestJS Prisma Recipe](https://docs.nestjs.com/recipes/prisma)
+- [Prisma Documentation](https://www.prisma.io/docs)
+- [prisma on npm](https://www.npmjs.com/package/prisma)
+- [@prisma/client on npm](https://www.npmjs.com/package/@prisma/client)
+- [Prisma on GitHub](https://github.com/prisma/prisma)
+
+## Setup
+
+> **Important:** Run `pnpm prisma generate` after installation to generate the typed client.
+> Then update `src/infrastructure/database/prisma.service.ts` to extend `PrismaClient`
+> as described in the inline comments.
+
+## Dependencies
+
+| Package          | Version | Purpose                                  |
+| ---------------- | ------- | ---------------------------------------- |
+| `prisma`         | `6.2.1` | Prisma CLI and migration engine          |
+| `@prisma/client` | `6.2.1` | Auto-generated type-safe database client |
+
+## Environment Variables
+
+| Variable       | Default | Description                                                                    |
+| -------------- | ------- | ------------------------------------------------------------------------------ |
+| `DATABASE_URL` | —       | Full database connection URL (e.g. `postgresql://user:pass@localhost:5432/db`) |
+
+## Usage
+
+```typescript
+import { PrismaService } from '@/infrastructure/database/prisma.service';
+
+@Injectable()
+export class UserRepository {
+  constructor(private readonly prisma: PrismaService) {}
+
+  async findAll() {
+    return this.prisma.user.findMany();
+  }
+}
+```
+
+## Generated Files
+
+| File                                            | Description                                                      |
+| ----------------------------------------------- | ---------------------------------------------------------------- |
+| `prisma/schema.prisma`                          | Base Prisma schema with datasource and generator configuration   |
+| `src/infrastructure/database/prisma.service.ts` | PrismaService extending PrismaClient with NestJS lifecycle hooks |

package/templates/recipes/prisma/prisma/schema.prisma.ejs

@@ -0,0 +1,8 @@
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}

package/templates/recipes/prisma/src/infrastructure/database/prisma.service.ts

@@ -0,0 +1,27 @@
+import { Injectable, OnModuleInit, OnModuleDestroy } from '@nestjs/common';
+
+/**
+ * Prisma service for database access.
+ *
+ * After installing dependencies, run:
+ *   pnpm prisma generate
+ *
+ * Then update this file to import from @prisma/client:
+ *   import { PrismaClient } from '@prisma/client';
+ *   export class PrismaService extends PrismaClient implements OnModuleInit, OnModuleDestroy { ... }
+ *
+ * Until prisma generate is run, this service provides a placeholder
+ * that will be replaced by the generated client.
+ */
+@Injectable()
+export class PrismaService implements OnModuleInit, OnModuleDestroy {
+  async onModuleInit(): Promise<void> {
+    // After running `prisma generate`, uncomment:
+    // await this.$connect();
+  }
+
+  async onModuleDestroy(): Promise<void> {
+    // After running `prisma generate`, uncomment:
+    // await this.$disconnect();
+  }
+}

package/templates/recipes/prisma/tests/unit/infrastructure/database/prisma.service.spec.ts

@@ -0,0 +1,21 @@
+import { PrismaService } from '../../../../src/infrastructure/database/prisma.service';
+
+describe('PrismaService', () => {
+  let service: PrismaService;
+
+  beforeEach(() => {
+    service = new PrismaService();
+  });
+
+  it('should be defined', () => {
+    expect(service).toBeDefined();
+  });
+
+  it('should implement onModuleInit', async () => {
+    await expect(service.onModuleInit()).resolves.toBeUndefined();
+  });
+
+  it('should implement onModuleDestroy', async () => {
+    await expect(service.onModuleDestroy()).resolves.toBeUndefined();
+  });
+});