@ngxtm/devkit 3.4.0 → 3.4.1

package/rules/nestjs/controllers-services/references/controller-patterns.md

@@ -0,0 +1,119 @@
+# NestJS Controller Patterns
+
+## Basic Controller
+
+```typescript
+import { Controller, Get, Post, Body, Param, Query, HttpStatus } from '@nestjs/common';
+import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';
+
+@ApiTags('users')
+@Controller('users')
+export class UsersController {
+  constructor(private readonly usersService: UsersService) {}
+
+  @Get()
+  @ApiOperation({ summary: 'List all users' })
+  async findAll(@Query() query: ListUsersDto) {
+    return this.usersService.findAll(query);
+  }
+
+  @Get(':id')
+  @ApiResponse({ status: 200, type: UserResponseDto })
+  async findOne(@Param('id', ParseIntPipe) id: number) {
+    return this.usersService.findOne(id);
+  }
+
+  @Post()
+  @HttpCode(HttpStatus.CREATED)
+  async create(@Body() createUserDto: CreateUserDto) {
+    return this.usersService.create(createUserDto);
+  }
+}
+```
+
+## Request Handling
+
+```typescript
+// Path parameters
+@Get(':id')
+findOne(@Param('id') id: string) {}
+
+// Multiple params
+@Get(':userId/posts/:postId')
+findPost(@Param('userId') userId: string, @Param('postId') postId: string) {}
+
+// Query parameters
+@Get()
+findAll(@Query('page') page: number, @Query('limit') limit: number) {}
+
+// Request body
+@Post()
+create(@Body() dto: CreateDto) {}
+
+// Headers
+@Get()
+getWithHeader(@Headers('authorization') auth: string) {}
+
+// Full request
+@Get()
+handleRequest(@Req() request: Request) {}
+```
+
+## Response Patterns
+
+```typescript
+// Standard response
+@Get()
+async findAll(): Promise<User[]> {
+  return this.usersService.findAll();
+}
+
+// Custom status
+@Post()
+@HttpCode(201)
+create() {}
+
+// Redirect
+@Get('old-path')
+@Redirect('new-path', 301)
+redirect() {}
+
+// Custom headers
+@Get()
+@Header('Cache-Control', 'none')
+findAll() {}
+
+// Stream response
+@Get('file')
+getFile(@Res() res: Response) {
+  const file = createReadStream(join(process.cwd(), 'file.txt'));
+  file.pipe(res);
+}
+```
+
+## Validation
+
+```typescript
+import { ValidationPipe, UsePipes } from '@nestjs/common';
+import { IsString, IsEmail, MinLength } from 'class-validator';
+
+class CreateUserDto {
+  @IsString()
+  @MinLength(2)
+  name: string;
+
+  @IsEmail()
+  email: string;
+}
+
+@Post()
+@UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
+create(@Body() dto: CreateUserDto) {}
+
+// Global validation (main.ts)
+app.useGlobalPipes(new ValidationPipe({
+  whitelist: true,
+  forbidNonWhitelisted: true,
+  transform: true,
+}));
+```

package/rules/nestjs/controllers-services/references/service-patterns.md

@@ -0,0 +1,129 @@
+# NestJS Service Patterns
+
+## Basic Service
+
+```typescript
+import { Injectable, NotFoundException } from '@nestjs/common';
+
+@Injectable()
+export class UsersService {
+  constructor(
+    private readonly usersRepository: UsersRepository,
+    private readonly emailService: EmailService,
+  ) {}
+
+  async findAll(query: ListUsersDto): Promise<User[]> {
+    return this.usersRepository.find(query);
+  }
+
+  async findOne(id: number): Promise<User> {
+    const user = await this.usersRepository.findById(id);
+    if (!user) {
+      throw new NotFoundException(`User #${id} not found`);
+    }
+    return user;
+  }
+
+  async create(dto: CreateUserDto): Promise<User> {
+    const user = await this.usersRepository.create(dto);
+    await this.emailService.sendWelcome(user.email);
+    return user;
+  }
+}
+```
+
+## Provider Scopes
+
+```typescript
+import { Injectable, Scope } from '@nestjs/common';
+
+// Singleton (default) - shared across all requests
+@Injectable()
+export class SingletonService {}
+
+// Request scope - new instance per request
+@Injectable({ scope: Scope.REQUEST })
+export class RequestScopedService {
+  constructor(@Inject(REQUEST) private request: Request) {}
+}
+
+// Transient - new instance each injection
+@Injectable({ scope: Scope.TRANSIENT })
+export class TransientService {}
+```
+
+## Custom Providers
+
+```typescript
+// Value provider
+const configProvider = {
+  provide: 'CONFIG',
+  useValue: { apiKey: 'xxx' },
+};
+
+// Factory provider
+const dbProvider = {
+  provide: 'DATABASE',
+  useFactory: async (config: ConfigService) => {
+    return createConnection(config.get('DATABASE_URL'));
+  },
+  inject: [ConfigService],
+};
+
+// Class provider
+const loggerProvider = {
+  provide: LoggerService,
+  useClass: process.env.NODE_ENV === 'test' 
+    ? MockLoggerService 
+    : LoggerService,
+};
+
+// Existing provider (alias)
+const aliasProvider = {
+  provide: 'ALIAS',
+  useExisting: RealService,
+};
+
+@Module({
+  providers: [configProvider, dbProvider, loggerProvider],
+})
+export class AppModule {}
+```
+
+## Async Providers
+
+```typescript
+@Module({
+  providers: [
+    {
+      provide: 'ASYNC_CONNECTION',
+      useFactory: async () => {
+        const connection = await createConnection();
+        return connection;
+      },
+    },
+  ],
+})
+export class DatabaseModule {}
+```
+
+## Circular Dependencies
+
+```typescript
+// Use forwardRef for circular deps
+@Injectable()
+export class CatsService {
+  constructor(
+    @Inject(forwardRef(() => DogsService))
+    private dogsService: DogsService,
+  ) {}
+}
+
+@Injectable()
+export class DogsService {
+  constructor(
+    @Inject(forwardRef(() => CatsService))
+    private catsService: CatsService,
+  ) {}
+}
+```

package/rules/nestjs/database/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: NestJS Database
+description: Data access patterns, Scaling, Migrations, and ORM selection.
+metadata:
+  labels: [nestjs, database, typeorm, prisma, mongodb]
+  triggers:
+    files: ['**/*.entity.ts', 'prisma/schema.prisma']
+    keywords: [TypeOrmModule, PrismaService, MongooseModule, Repository]
+---
+
+# NestJS Database Standards
+
+## Selection Framework
+
+### 1. Data Structure Analysis (The "What")
+
+- **Structured & Highly Related**: Users, Orders, Inventory, Financials.
+  - **Choice**: **PostgreSQL** (Default).
+  - _Why_: Strict schema validation, ACID transactions, complex generic queries (Joins).
+- **Unstructured / Polymorphic**: Product Catalogs (lots of unique attributes), CMS Content, Raw JSON blobs.
+  - **Choice**: **MongoDB**.
+  - _Why_: Schema flexibility, fast development speed for flexible data models.
+- **Time-Series / Metrics**: IoT Sensor Data, Stock Prices, Server Logs.
+  - **Choice**: **TimescaleDB** (Postgres Extension).
+  - _Why_: Compression, hypertable partitioning, rapid ingestion.
+
+### 2. Access Pattern Analysis (The "How")
+
+- **Transactional (OLTP)**: "User buys items to cart".
+  - **Requirement**: Strong Consistency (ACID). **SQL** is mandatory.
+- **Analytical (OLAP)**: "Dashboard showing sales trends".
+  - **Requirement**: Aggregation speed. Columnar storage (ClickHouse) or Read Replicas.
+- **High Throughput Write**: "1M events/sec".
+  - **Requirement**: Append-only speed. **Cassandra** / **DynamoDB** (Leaderless replication).
+
+### 3. Decision Matrix
+
+| Feature Needed         | Primary Choice    | Alternative            |
+| :--------------------- | :---------------- | :--------------------- |
+| General Purpose App    | **PostgreSQL**    | MySQL                  |
+| Flexible JSON Docs     | **MongoDB**       | PostgreSQL (JSONB)     |
+| Search Engine          | **ElasticSearch** | PostgreSQL (Full Text) |
+| Financial Transactions | **PostgreSQL**    | (None)                 |
+
+## Patterns
+
+- **Repository Pattern**: Isolate database logic.
+  - **TypeORM**: Inject `@InjectRepository(Entity)`.
+  - **Prisma**: Create a comprehensive `PrismaService`.
+- **Abstraction**: Services should call Repositories, not raw SQL queries.
+
+## Configuration (TypeORM)
+
+- **Async Loading**: Always use `TypeOrmModule.forRootAsync` to load secrets from `ConfigService`.
+- **Sync**: Set `synchronize: false` in production; use migrations instead.
+
+## Scaling & Production
+
+- **Read Replicas**: Configure separate `replication` connections (Master for Write, Slaves for Read) in TypeORM/Prisma to distribute load.
+- **Connection Multiplexing**:
+  - **Problem**: Scaling K8s pods to 100+ exhausts DB connection limits (100 pods \* 10 connections = 1000 conns).
+  - **Solution**: Use **PgBouncer** (Postgres) or **ProxySQL** (MySQL) in transaction mode. Do NOT rely solely on ORM pooling.
+- **Migrations**:
+  - **NEVER** run `synchronize: true` in production.
+  - **Execution**: Run migrations via a dedicated "init container" or CD job step. Do **NOT** auto-run inside the main app process on startup (race conditions when scaling to multiple pods).
+- **Soft Deletes**: Use `@DeleteDateColumn` (TypeORM) or middleware (Prisma) to preserve data integrity.
+
+## Architectures (Multi-Tenancy & Sharding)
+
+- **Column-Based (SaaS Standard)**: Single DB, `tenant_id` column.
+  - _Scale_: High. _Isolation_: Low.
+  - _Code_: Requires Row-Level Security (RLS) policies or strict `Where` scopes.
+- **Schema-Based**: One DB, one Schema per Tenant.
+  - _Scale_: Medium. _Isolation_: Medium. Good for B2B.
+- **Database-Based**: One DB per Tenant.
+  - _Scale_: Low (max ~500 tenants per cluster). _Isolation_: High.
+  - _Code_: Requires "Connection Switching" middleware. Complex.
+- **Horizontal Sharding**:
+  - **Logic**: Shard massive tables by a key (e.g. `user_id`) across physical nodes to exceed single-node write limits.
+  - **Complexity**: Extreme. Avoid until >10TB data. Use "Partitioning" first.
+- **Partioning (Postgres)**:
+  - **Strategy**: Use native Table Partitioning (e.g., by range/date) for massive tables (Logs, Audit, Events).
+  - **App Logic**: Ensure partition keys (e.g., `created_at`) are included in `WHERE` clauses to enable "Partition Pruning".
+
+## Migrations & Data Evolution
+
+- **Separation**:
+  - **Schema Migrations (DDL)**: Structural changes (`CREATE TABLE`, `ADD COLUMN`). Fast. Run before app deploy.
+  - **Data Migrations (DML)**: transforming data (`UPDATE users SET name = ...`). Slow. Run as background jobs or separate scripts purely to avoid locking tables for too long.
+- **Zero-Downtime Field Migration (Expand-Contract Pattern)**:
+  1. **Expand**: Add new column `new_field` (nullable). Deploy App v1 (Writes to both `old` and `new`).
+  2. **Migrate**: Backfill data from `old` to `new` in batches (background script).
+  3. **Contract**: Deploy App v2 (Reads/Writes only `new`). Drop `old_field` in next schema migration.
+- **Seeding**:
+  - **Dev**: Use factories (`@faker-js/faker`) to generate mock data.
+  - **Prod**: Only seed static dictionaries (Roles, Countries) using "Upsert" logic to prevent duplicates.
+
+## Best Practices
+
+1. **Pagination**: Mandatory. Use limit/offset or cursor-based pagination.
+2. **Indexing**: Define indexes in code (decorators/schema) for frequently filtered columns (`where`, `order by`).
+3. **Transactions**: Use `QueryRunner` (TypeORM) or `$transaction` (Prisma) for all multi-step mutations to ensure atomicity.

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

@@ -0,0 +1,14 @@
+# NestJS Database References
+
+## References
+
+- [**TypeORM Patterns**](typeorm-patterns.md) - Entities, repositories, relations
+- [**Prisma Patterns**](prisma-patterns.md) - Schema, client, transactions
+
+## Quick Checks
+
+- [ ] Use repository pattern for data access
+- [ ] Define entities/models with proper relations
+- [ ] Use transactions for multi-operation consistency
+- [ ] Implement soft delete where appropriate
+- [ ] Use migrations for schema changes

package/rules/nestjs/database/references/typeorm-patterns.md

@@ -0,0 +1,156 @@
+# NestJS TypeORM Patterns
+
+## Entity Definition
+
+```typescript
+import { Entity, Column, PrimaryGeneratedColumn, CreateDateColumn, ManyToOne, OneToMany } from 'typeorm';
+
+@Entity('users')
+export class User {
+  @PrimaryGeneratedColumn()
+  id: number;
+
+  @Column({ length: 100 })
+  name: string;
+
+  @Column({ unique: true })
+  email: string;
+
+  @Column({ default: true })
+  isActive: boolean;
+
+  @CreateDateColumn()
+  createdAt: Date;
+
+  @OneToMany(() => Post, post => post.author)
+  posts: Post[];
+}
+
+@Entity('posts')
+export class Post {
+  @PrimaryGeneratedColumn()
+  id: number;
+
+  @Column()
+  title: string;
+
+  @ManyToOne(() => User, user => user.posts)
+  author: User;
+
+  @Column()
+  authorId: number;
+}
+```
+
+## Repository Pattern
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+
+@Injectable()
+export class UsersRepository {
+  constructor(
+    @InjectRepository(User)
+    private readonly repo: Repository<User>,
+  ) {}
+
+  async findAll(): Promise<User[]> {
+    return this.repo.find({ relations: ['posts'] });
+  }
+
+  async findById(id: number): Promise<User | null> {
+    return this.repo.findOne({ where: { id }, relations: ['posts'] });
+  }
+
+  async create(data: CreateUserDto): Promise<User> {
+    const user = this.repo.create(data);
+    return this.repo.save(user);
+  }
+
+  async update(id: number, data: UpdateUserDto): Promise<User> {
+    await this.repo.update(id, data);
+    return this.findById(id);
+  }
+
+  async delete(id: number): Promise<void> {
+    await this.repo.delete(id);
+  }
+}
+```
+
+## Query Builder
+
+```typescript
+async findWithFilters(filters: FilterDto): Promise<User[]> {
+  const qb = this.repo.createQueryBuilder('user')
+    .leftJoinAndSelect('user.posts', 'post');
+
+  if (filters.name) {
+    qb.andWhere('user.name ILIKE :name', { name: `%${filters.name}%` });
+  }
+
+  if (filters.isActive !== undefined) {
+    qb.andWhere('user.isActive = :isActive', { isActive: filters.isActive });
+  }
+
+  return qb
+    .orderBy('user.createdAt', 'DESC')
+    .skip(filters.offset)
+    .take(filters.limit)
+    .getMany();
+}
+```
+
+## Transactions
+
+```typescript
+import { DataSource } from 'typeorm';
+
+@Injectable()
+export class OrdersService {
+  constructor(private dataSource: DataSource) {}
+
+  async createOrder(dto: CreateOrderDto): Promise<Order> {
+    const queryRunner = this.dataSource.createQueryRunner();
+    await queryRunner.connect();
+    await queryRunner.startTransaction();
+
+    try {
+      const order = await queryRunner.manager.save(Order, dto);
+      await queryRunner.manager.update(Product, dto.productId, {
+        stock: () => 'stock - 1',
+      });
+      await queryRunner.commitTransaction();
+      return order;
+    } catch (err) {
+      await queryRunner.rollbackTransaction();
+      throw err;
+    } finally {
+      await queryRunner.release();
+    }
+  }
+}
+```
+
+## Module Setup
+
+```typescript
+import { TypeOrmModule } from '@nestjs/typeorm';
+
+@Module({
+  imports: [
+    TypeOrmModule.forRoot({
+      type: 'postgres',
+      host: 'localhost',
+      port: 5432,
+      database: 'mydb',
+      entities: [User, Post],
+      synchronize: false, // Use migrations in production
+    }),
+    TypeOrmModule.forFeature([User, Post]),
+  ],
+})
+export class DatabaseModule {}
+```

package/rules/nestjs/deployment/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: NestJS Deployment
+description: Docker builds, Memory tuning, and Graceful shutdown.
+metadata:
+  labels: [nestjs, deployment, docker, k8s]
+  triggers:
+    files: ['Dockerfile', 'k8s/**', 'helm/**']
+    keywords: [Dockerfile, max-old-space-size, shutdown hooks]
+---
+
+# Deployment & Ops Standards
+
+## Docker Optimization
+
+- **Multi-Stage Builds**: Mandatory.
+  1. **Build Stage**: Install `devDependencies`, build NestJS (`nest build`).
+  2. **Run Stage**: Copy only `dist` and `node_modules` (pruned), use `node:alpine`.
+- **Security**: Do not run as `root`.
+  - **Dockerfile**: `USER node`.
+
+## Runtime Tuning (Node.js)
+
+- **Memory Config**: Container memory != Node memory.
+  - **Rule**: Explicitly set Max Old Space.
+  - **Command**: `node --max-old-space-size=XXX dist/main`
+  - **Calculation**: Set to ~75-80% of Kubernetes Limit. (Limit: 1GB -> OldSpace: 800MB).
+- **Graceful Shutdown**:
+  - **Signal**: Listen to `SIGTERM`.
+  - **NestJS**: `app.enableShutdownHooks()` is mandatory.
+  - **Sleep**: Add a "Pre-Stop" sleep in K8s (5-10s) to allow Load Balancer to drain connections before Node process stops accepting traffic.
+
+## Init Patterns
+
+- **Database Migrations**:
+  - **Anti-Pattern**: Running migration in `main.ts` on startup.
+  - **Pro Pattern**: Use an **Init Container** in Kubernetes that runs `npm run typeorm:migration:run` before the app container starts.

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

@@ -0,0 +1,13 @@
+# NestJS Deployment References
+
+## References
+
+- [**Deployment Patterns**](deployment-patterns.md) - Docker, PM2, serverless, cloud platforms
+
+## Quick Checks
+
+- [ ] Use multi-stage Docker builds
+- [ ] Configure health checks
+- [ ] Use PM2 for process management
+- [ ] Set production environment variables
+- [ ] Enable graceful shutdown

package/rules/nestjs/deployment/references/deployment-patterns.md

@@ -0,0 +1,140 @@
+# NestJS Deployment Patterns
+
+## Docker Multi-Stage Build
+
+```dockerfile
+# Build stage
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+# Production stage
+FROM node:20-alpine AS production
+WORKDIR /app
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/package*.json ./
+
+ENV NODE_ENV=production
+EXPOSE 3000
+
+CMD ["node", "dist/main.js"]
+```
+
+## PM2 Configuration
+
+```javascript
+// ecosystem.config.js
+module.exports = {
+  apps: [{
+    name: 'api',
+    script: 'dist/main.js',
+    instances: 'max',
+    exec_mode: 'cluster',
+    env_production: {
+      NODE_ENV: 'production',
+      PORT: 3000,
+    },
+    max_memory_restart: '1G',
+    error_file: './logs/error.log',
+    out_file: './logs/out.log',
+  }],
+};
+```
+
+## Graceful Shutdown
+
+```typescript
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+
+  app.enableShutdownHooks();
+
+  await app.listen(3000);
+}
+
+// In service
+@Injectable()
+export class AppService implements OnModuleDestroy {
+  async onModuleDestroy() {
+    // Cleanup: close DB connections, finish jobs
+    await this.closeConnections();
+  }
+}
+```
+
+## Health Checks
+
+```typescript
+import { Controller, Get } from '@nestjs/common';
+import {
+  HealthCheck,
+  HealthCheckService,
+  HttpHealthIndicator,
+  TypeOrmHealthIndicator,
+} from '@nestjs/terminus';
+
+@Controller('health')
+export class HealthController {
+  constructor(
+    private health: HealthCheckService,
+    private http: HttpHealthIndicator,
+    private db: TypeOrmHealthIndicator,
+  ) {}
+
+  @Get()
+  @HealthCheck()
+  check() {
+    return this.health.check([
+      () => this.db.pingCheck('database'),
+      () => this.http.pingCheck('api', 'https://api.example.com'),
+    ]);
+  }
+
+  @Get('live')
+  liveness() {
+    return { status: 'ok' };
+  }
+
+  @Get('ready')
+  readiness() {
+    return this.health.check([
+      () => this.db.pingCheck('database'),
+    ]);
+  }
+}
+```
+
+## Serverless (AWS Lambda)
+
+```typescript
+// lambda.ts
+import { NestFactory } from '@nestjs/core';
+import { ExpressAdapter } from '@nestjs/platform-express';
+import serverlessExpress from '@vendia/serverless-express';
+import express from 'express';
+import { AppModule } from './app.module';
+
+let cachedServer;
+
+async function bootstrap() {
+  const expressApp = express();
+  const adapter = new ExpressAdapter(expressApp);
+  const app = await NestFactory.create(AppModule, adapter);
+  await app.init();
+  return serverlessExpress({ app: expressApp });
+}
+
+export const handler = async (event, context) => {
+  if (!cachedServer) {
+    cachedServer = await bootstrap();
+  }
+  return cachedServer(event, context);
+};
+```