Clean NestJS TypeScript Coding Rules: Best Practices for Cursor AI Optimization

- **Core TypeScript Principles**
  - Stick to English for all code comments and documentation.
  - Explicitly type every variable, parameter, and return value.
  - Eliminate use of the 'any' type entirely.
  - Define custom interfaces and types where required.
  - Apply JSDoc comments to all public classes and methods.
  - Remove any empty lines inside function bodies.
  - Export only one primary item per file.

- **Naming Standards**
  - Apply PascalCase to class names.
  - Use camelCase for variables, functions, and methods.
  - Adopt kebab-case for file and folder names.
  - Employ UPPER_CASE for environment variables.
  - Replace magic numbers with descriptive constants.
  - Begin function names with action verbs.
  - Prefix booleans with 'is', 'has', 'can', etc. (e.g., isActive, hasPermission).
  - Favor full words with correct spelling; permit common shortcuts like API, URL, i/j for loops, err, ctx, req/res/next.

- **Function and Method Best Practices**
  - Keep functions concise (under 20 lines) with one clear responsibility.
  - Name with verb + descriptor (e.g., fetchUser, validateInput).
  - For booleans: prefix with 'is/has/can'.
  - For void returns: use 'execute/save/perform'.
  - Minimize nesting via early returns, guard clauses, and helper functions.
  - Leverage array methods like map, filter, reduce to flatten logic.
  - Prefer arrow functions for brevity (<3 lines); named functions otherwise.
  - Set default params over null checks.
  - Group params into objects (RO-RO pattern) for 3+ args.
  - Return structured objects; always type inputs/outputs.
  - Maintain single abstraction level per function.

- **Data Handling Guidelines**
  - Wrap primitives in structured types or classes.
  - Handle validation within classes, not ad-hoc in functions.
  - Prioritize immutability with 'readonly' properties.
  - Use 'as const' for unchanging literals.

- **Class Design Rules**
  - Adhere to SOLID principles strictly.
  - Favor composition over inheritance.
  - Define interfaces for all contracts.
  - Limit classes to one purpose (<200 lines, <10 public methods, <10 properties).

- **Error Management**
  - Reserve exceptions for unanticipated issues.
  - Catch only to resolve known issues or enrich context; otherwise, rely on global handlers.

- **Testing Standards**
  - Structure unit tests as Arrange-Act-Assert.
  - Use descriptive names: inputData, mockService, actualResult, expectedOutput.
  - Test every public method with unit tests and test doubles (skip cheap third-party calls).
  - Create acceptance tests per module using Given-When-Then.

- **NestJS-Specific Architecture**
  - Build modular monoliths: one module per domain/route.
  - Assign one primary controller per route, plus sub-controllers as needed.
  - Organize with 'models' folder for types/DTOs (validate inputs via class-validator).
  - Use simple types for outputs.
  - Place business logic and MikroORM entities in dedicated services (one per entity).
  - Develop a shared @app/common module containing:
    - Configs for app-wide settings.
    - Reusable decorators, DTOs, guards, interceptors.
    - Notification services, utils, validators.
    - Common types and shared services.
  - Implement core features: global exception filters, middlewares, guards, interceptors.
  - **NestJS Testing**:
    - Leverage Jest for all tests.
    - Test controllers and services comprehensively.
    - Add E2E tests per API module.
    - Include an admin/test endpoint in controllers for quick smoke testing.