@ngxtm/devkit 3.3.0 → 3.4.1

package/rules/nestjs/architecture/references/dynamic-module.md

@@ -0,0 +1,53 @@
+# Dynamic Module Builder Reference
+
+## Overview
+
+The `ConfigurableModuleBuilder` drastically reduces the boilerplate required to create typed `forRoot` / `register` methods for dynamic modules.
+
+## Implementation
+
+```typescript
+// 1. definition.ts
+import { ConfigurableModuleBuilder } from '@nestjs/common';
+
+export interface MyModuleOptions {
+  apiKey: string;
+  isGlobal?: boolean;
+}
+
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN } =
+  new ConfigurableModuleBuilder<MyModuleOptions>()
+    .setClassMethodName('forRoot') // or 'register'
+    .setExtras(
+      {
+        isGlobal: true,
+      },
+      (definition, extras) => ({
+        ...definition,
+        global: extras.isGlobal,
+      }),
+    )
+    .build();
+
+// 2. my.module.ts
+import { Module } from '@nestjs/common';
+import { ConfigurableModuleClass } from './definition';
+import { MyService } from './my.service';
+
+@Module({
+  providers: [MyService],
+  exports: [MyService],
+})
+export class MyModule extends ConfigurableModuleClass {}
+
+// 3. usage (AppModule)
+@Module({
+  imports: [
+    MyModule.forRoot({
+      apiKey: 'secret',
+      isGlobal: true,
+    }),
+  ],
+})
+export class AppModule {}
+```

package/rules/nestjs/caching/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: NestJS Caching & Redis
+description: Multi-level caching, Invalidation patterns, and Stampede protection.
+metadata:
+  labels: [nestjs, caching, redis, performance]
+  triggers:
+    files: ['**/*.service.ts', '**/*.interceptor.ts']
+    keywords: [CacheInterceptor, CacheTTL, Redis, stale-while-revalidate]
+---
+
+# Caching & Redis Standards
+
+## Caching Strategy
+
+- **Layering**: Use **Multi-Level Caching** for high-traffic read endpoints.
+  - **L1 (Local)**: In-Memory (Node.js heap). Ultra-fast, no network. Ideal for config/static data. Use `lru-cache`.
+  - **L2 (Distributed)**: Redis. Shared across pods.
+- **Pattern**: Implement **Stale-While-Revalidate** where possible to avoid latency spikes during cache misses.
+
+## NestJS Implementation
+
+- **Library**: Use `cache-manager` with `cache-manager-redis-yet` (Recommended over `cache-manager-redis-store` for better V4 support and stability).
+- **Interceptors**: Use `@UseInterceptors(CacheInterceptor)` for simple GET responses.
+  - **Warning**: By default, this uses the URL as the key. Ensure consistent query param ordering or custom key generators.
+- **Decorators**: Standardize custom cache keys.
+
+  ```typescript
+  @CacheKey('users_list')
+  @CacheTTL(300) // 5 minutes
+  findAll() { ... }
+  ```
+
+## Redis Data Structures (Expert)
+
+- Don't just use `GET/SET`.
+- **Hash (`HSET`)**: Storing objects (User profiles). Allows partial updates (`HSET user:1 lastLogin result`) without serialization overhead.
+- **Set (`SADD`)**: Unique collections (e.g., "Online User IDs"). O(1) membership checks.
+- **Sorted Set (`ZADD`)**: Priority queues, Leaderboards, or Rate Limiting windows.
+
+## Invalidation Patterns
+
+- **Problem**: "There are only two hard things in Computer Science: cache invalidation and naming things."
+- **Tagging**: Since Redis doesn't support wildcards efficiently (`KEYS` is O(N) - bans in PROD), use **Sets** to group keys.
+  - _Create_: `SADD post:1:tags cache:post:1`
+  - _Invalidate_: Fetch tags from Set, then `DEL` usage keys.
+- **Event-Driven**: Listen to Domain Events (`UserUpdated`) to trigger invalidation asynchronously.
+
+## Stampede Protection
+
+- **Jitter**: Add random variance to TTLs (e.g., 300s ± 10s) to prevent all keys expiring simultaneously.
+- **Locking**: If a key is missing, **one** process computes it while others wait or return stale. (Complex, often handled by `swr` libraries).

package/rules/nestjs/caching/references/REFERENCE.md

@@ -0,0 +1,13 @@
+# NestJS Caching References
+
+## References
+
+- [**Cache Patterns**](cache-patterns.md) - CacheModule, Redis, strategies
+
+## Quick Checks
+
+- [ ] Use CacheModule for simple caching
+- [ ] Redis for production/distributed
+- [ ] Cache interceptors for routes
+- [ ] TTL configuration per cache
+- [ ] Cache invalidation strategy

package/rules/nestjs/caching/references/cache-patterns.md

@@ -0,0 +1,183 @@
+# NestJS Cache Patterns
+
+## Basic Setup
+
+```typescript
+import { CacheModule } from '@nestjs/cache-manager';
+
+@Module({
+  imports: [
+    CacheModule.register({
+      ttl: 5000, // 5 seconds
+      max: 100, // max items
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+## Cache Interceptor
+
+```typescript
+import { CacheInterceptor, CacheKey, CacheTTL } from '@nestjs/cache-manager';
+
+@Controller('users')
+@UseInterceptors(CacheInterceptor)
+export class UsersController {
+  @Get()
+  @CacheTTL(30000) // 30 seconds
+  findAll() {
+    return this.usersService.findAll();
+  }
+
+  @Get(':id')
+  @CacheKey('user')
+  findOne(@Param('id') id: string) {
+    return this.usersService.findOne(id);
+  }
+}
+```
+
+## Programmatic Caching
+
+```typescript
+import { CACHE_MANAGER } from '@nestjs/cache-manager';
+import { Cache } from 'cache-manager';
+
+@Injectable()
+export class UsersService {
+  constructor(@Inject(CACHE_MANAGER) private cacheManager: Cache) {}
+
+  async findOne(id: string): Promise<User> {
+    // Check cache
+    const cached = await this.cacheManager.get<User>(`user:${id}`);
+    if (cached) return cached;
+
+    // Fetch from DB
+    const user = await this.usersRepository.findById(id);
+
+    // Store in cache
+    await this.cacheManager.set(`user:${id}`, user, 60000);
+
+    return user;
+  }
+
+  async update(id: string, data: UpdateUserDto): Promise<User> {
+    const user = await this.usersRepository.update(id, data);
+    
+    // Invalidate cache
+    await this.cacheManager.del(`user:${id}`);
+    
+    return user;
+  }
+
+  async clearAllUsers(): Promise<void> {
+    await this.cacheManager.reset();
+  }
+}
+```
+
+## Redis Store
+
+```typescript
+import { CacheModule } from '@nestjs/cache-manager';
+import * as redisStore from 'cache-manager-redis-store';
+
+@Module({
+  imports: [
+    CacheModule.registerAsync({
+      imports: [ConfigModule],
+      inject: [ConfigService],
+      useFactory: (config: ConfigService) => ({
+        store: redisStore,
+        host: config.get('REDIS_HOST'),
+        port: config.get('REDIS_PORT'),
+        ttl: 60,
+      }),
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+## Custom Cache Key
+
+```typescript
+@Injectable()
+export class CustomCacheInterceptor extends CacheInterceptor {
+  trackBy(context: ExecutionContext): string | undefined {
+    const request = context.switchToHttp().getRequest();
+    const { method, url } = request;
+    
+    // Don't cache POST, PUT, DELETE
+    if (method !== 'GET') return undefined;
+    
+    // Include user in cache key
+    const userId = request.user?.id || 'anonymous';
+    return `${userId}:${url}`;
+  }
+}
+```
+
+## Cache-Aside Pattern
+
+```typescript
+@Injectable()
+export class ProductsService {
+  constructor(
+    @Inject(CACHE_MANAGER) private cache: Cache,
+    private productsRepo: ProductsRepository,
+  ) {}
+
+  async getProduct(id: string): Promise<Product> {
+    const cacheKey = `product:${id}`;
+    
+    // Try cache first
+    let product = await this.cache.get<Product>(cacheKey);
+    
+    if (!product) {
+      // Cache miss - fetch from DB
+      product = await this.productsRepo.findById(id);
+      
+      if (product) {
+        // Populate cache
+        await this.cache.set(cacheKey, product, 300000); // 5 min
+      }
+    }
+    
+    return product;
+  }
+}
+```
+
+## Bulk Cache Operations
+
+```typescript
+async getProducts(ids: string[]): Promise<Product[]> {
+  const products: Product[] = [];
+  const missingIds: string[] = [];
+
+  // Check cache for each
+  for (const id of ids) {
+    const cached = await this.cache.get<Product>(`product:${id}`);
+    if (cached) {
+      products.push(cached);
+    } else {
+      missingIds.push(id);
+    }
+  }
+
+  // Fetch missing from DB
+  if (missingIds.length > 0) {
+    const dbProducts = await this.productsRepo.findByIds(missingIds);
+    
+    // Cache and add to result
+    for (const product of dbProducts) {
+      await this.cache.set(`product:${product.id}`, product);
+      products.push(product);
+    }
+  }
+
+  return products;
+}
+```

package/rules/nestjs/configuration/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: NestJS Configuration
+description: Environment variables validation and ConfigModule setup.
+metadata:
+  labels: [nestjs, config, env]
+  triggers:
+    files: ['.env', 'app.module.ts', '**/config.ts']
+    keywords: [ConfigModule, Joi, env]
+---
+
+# NestJS Configuration Standards
+
+## Setup
+
+1. **Library**: Use `@nestjs/config`.
+2. **Initialization**: Import `ConfigModule.forRoot({ isGlobal: true })` in `AppModule`.
+
+## Validation
+
+- **Mandatory**: Validate environment variables at startup.
+- **Tool**: Use `joi` or a custom validation class.
+- **Effect**: The app **must crash** immediately if a required env var (e.g., `DB_URL`) is missing.
+
+```typescript
+// app.module.ts
+ConfigModule.forRoot({
+  validationSchema: Joi.object({
+    NODE_ENV: Joi.string()
+      .valid('development', 'production')
+      .default('development'),
+    PORT: Joi.number().default(3000),
+    DATABASE_URL: Joi.string().required(),
+  }),
+});
+```
+
+## Usage
+
+- **Injection**: Inject `ConfigService` to access values.
+- **Typing**: Avoid magic strings. Use a type-safe getter helper or a dedicated configuration object/interface.
+- **Secrets**: Never commit `.env` files. Add `.env*` to `.gitignore`.

package/rules/nestjs/configuration/references/REFERENCE.md

@@ -0,0 +1,13 @@
+# NestJS Configuration References
+
+## References
+
+- [**Config Patterns**](config-patterns.md) - ConfigModule, validation, environments
+
+## Quick Checks
+
+- [ ] Use ConfigModule for configuration
+- [ ] Validate env vars with Joi/class-validator
+- [ ] Type-safe config with interfaces
+- [ ] Environment-specific configs
+- [ ] Never commit secrets

package/rules/nestjs/configuration/references/config-patterns.md

@@ -0,0 +1,184 @@
+# NestJS Configuration Patterns
+
+## Basic Setup
+
+```typescript
+import { ConfigModule, ConfigService } from '@nestjs/config';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({
+      isGlobal: true,
+      envFilePath: ['.env.local', '.env'],
+    }),
+  ],
+})
+export class AppModule {}
+
+// Usage
+@Injectable()
+export class AppService {
+  constructor(private configService: ConfigService) {}
+
+  getDatabaseUrl(): string {
+    return this.configService.get<string>('DATABASE_URL');
+  }
+}
+```
+
+## Validation with Joi
+
+```typescript
+import * as Joi from 'joi';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({
+      validationSchema: Joi.object({
+        NODE_ENV: Joi.string()
+          .valid('development', 'production', 'test')
+          .default('development'),
+        PORT: Joi.number().default(3000),
+        DATABASE_URL: Joi.string().required(),
+        JWT_SECRET: Joi.string().required(),
+        JWT_EXPIRATION: Joi.string().default('1h'),
+      }),
+      validationOptions: {
+        abortEarly: true,
+      },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+## Configuration Namespaces
+
+```typescript
+// config/database.config.ts
+import { registerAs } from '@nestjs/config';
+
+export default registerAs('database', () => ({
+  host: process.env.DB_HOST || 'localhost',
+  port: parseInt(process.env.DB_PORT, 10) || 5432,
+  name: process.env.DB_NAME,
+  user: process.env.DB_USER,
+  password: process.env.DB_PASSWORD,
+}));
+
+// config/jwt.config.ts
+export default registerAs('jwt', () => ({
+  secret: process.env.JWT_SECRET,
+  expiresIn: process.env.JWT_EXPIRATION || '1h',
+}));
+
+// app.module.ts
+@Module({
+  imports: [
+    ConfigModule.forRoot({
+      load: [databaseConfig, jwtConfig],
+    }),
+  ],
+})
+export class AppModule {}
+
+// Usage
+@Injectable()
+export class DatabaseService {
+  constructor(private configService: ConfigService) {}
+
+  getConfig() {
+    return {
+      host: this.configService.get<string>('database.host'),
+      port: this.configService.get<number>('database.port'),
+    };
+  }
+}
+```
+
+## Type-Safe Configuration
+
+```typescript
+// config/configuration.ts
+export interface DatabaseConfig {
+  host: string;
+  port: number;
+  name: string;
+}
+
+export interface AppConfig {
+  database: DatabaseConfig;
+  port: number;
+}
+
+export default (): AppConfig => ({
+  port: parseInt(process.env.PORT, 10) || 3000,
+  database: {
+    host: process.env.DB_HOST,
+    port: parseInt(process.env.DB_PORT, 10) || 5432,
+    name: process.env.DB_NAME,
+  },
+});
+
+// Type-safe access
+@Injectable()
+export class AppService {
+  constructor(private configService: ConfigService<AppConfig, true>) {}
+
+  getPort(): number {
+    return this.configService.get('port', { infer: true });
+  }
+
+  getDbHost(): string {
+    return this.configService.get('database.host', { infer: true });
+  }
+}
+```
+
+## Environment Files
+
+```bash
+# .env
+DATABASE_URL=postgres://localhost:5432/myapp
+JWT_SECRET=your-secret-key
+
+# .env.development
+DEBUG=true
+LOG_LEVEL=debug
+
+# .env.production
+LOG_LEVEL=error
+
+# .env.test
+DATABASE_URL=postgres://localhost:5432/myapp_test
+```
+
+```typescript
+ConfigModule.forRoot({
+  envFilePath: process.env.NODE_ENV === 'test' 
+    ? '.env.test' 
+    : [`.env.${process.env.NODE_ENV}`, '.env'],
+})
+```
+
+## Async Configuration
+
+```typescript
+@Module({
+  imports: [
+    TypeOrmModule.forRootAsync({
+      imports: [ConfigModule],
+      inject: [ConfigService],
+      useFactory: (config: ConfigService) => ({
+        type: 'postgres',
+        host: config.get('database.host'),
+        port: config.get('database.port'),
+        database: config.get('database.name'),
+        autoLoadEntities: true,
+        synchronize: config.get('NODE_ENV') !== 'production',
+      }),
+    }),
+  ],
+})
+export class DatabaseModule {}
+```

package/rules/nestjs/controllers-services/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: NestJS Controllers & Services
+description: Controller/Service separation and Custom Decorators.
+metadata:
+  labels: [nestjs, controller, service]
+  triggers:
+    files: ['**/*.controller.ts', '**/*.service.ts']
+    keywords: [Controller, Injectable, ExecutionContext, createParamDecorator]
+---
+
+# NestJS Controllers & Services Standards
+
+## Controllers
+
+- **Role**: Handler only. Delegate **all** logic to Services.
+- **Context**: Use `ExecutionContext` helpers (`switchToHttp()`) for platform-agnostic code.
+- **Custom Decorators**:
+  - **Avoid**: `@Request() req` -> `req.user` (Not type-safe).
+  - **Pattern**: Create typed decorators like `@CurrentUser()`, `@DeviceIp()`.
+
+  ```typescript
+  export const CurrentUser = createParamDecorator(
+    (data: unknown, ctx: ExecutionContext) =>
+      ctx.switchToHttp().getRequest().user,
+  );
+  ```
+
+## DTOs & Validation
+
+- **Strictness**:
+  - `whitelist: true`: Strip properties without decorators.
+  - **Critical**: `forbidNonWhitelisted: true`: Throw error if unknown properties exist.
+- **Transformation**:
+  - `transform: true`: Auto-convert primitives (String '1' -> Number 1) and instantiate DTO classes.
+- **Documentation**:
+  - **Automation**: Use the `@nestjs/swagger` CLI plugin (`nest-cli.json`) to auto-detect DTO properties without manual `@ApiProperty()` tags.
+
+## Interceptors (Response Mapping)
+
+- **Standardization**: specific responses should be mapped in **Interceptors**, not Controllers.
+  - Use `map()` to wrap success responses (e.g. `{ data: T }`).
+  - Refer to **[API Standards](../api-standards/SKILL.md)** for `PageDto` and `ApiResponse`.
+  - Use `catchError()` to map low-level errors (DB constraints) to `HttpException` (e.g. `ConflictException`) _before_ they hit the global filter.
+
+## Services & Business Logic
+
+- **Singleton**: Default.
+- **Stateless**: Do not store request-specific state in class properties unless identifying as `Scope.REQUEST`.
+
+## Pipes & Validation
+
+- **Global**: Register `ValidationPipe` globally.
+- **Route Params**: Fail fast. Always use `ParseIntPipe`, `ParseUUIDPipe` on all ID parameters.
+
+```typescript
+@Get(':id')
+findOne(@Param('id', ParseIntPipe) id: number) { ... }
+```
+
+## Lifecycle Events
+
+- **Init**: Use `OnModuleInit` for connection setup.
+- **Destroy**: Use `OnApplicationShutdown` for cleanup. (Requires `enableShutdownHooks()`).

package/rules/nestjs/controllers-services/references/REFERENCE.md

@@ -0,0 +1,14 @@
+# NestJS Controllers & Services References
+
+## References
+
+- [**Controller Patterns**](controller-patterns.md) - Routes, decorators, responses
+- [**Service Patterns**](service-patterns.md) - DI, business logic, providers
+
+## Quick Checks
+
+- [ ] Use @Controller decorator with route prefix
+- [ ] Inject services via constructor
+- [ ] Use DTOs for request/response
+- [ ] Apply validation pipes
+- [ ] Keep controllers thin, services fat