Instruction file imported from GAIA-TECHNOLOGY/GeoMonitor (.github/instructions/typescript.instructions.md). Copyright stays with the author.

TypeScript Development Guidelines

Code Style

General TypeScript

• Use TypeScript strict mode (as configured in tsconfig.json)
• Prefer const over let, avoid var
• Use arrow functions for callbacks and short functions
• Use interface for object types, type for unions/intersections
• Add explicit return types for all public functions
• Use optional chaining (?.) and nullish coalescing (??) where appropriate

Naming Conventions

• Classes/Interfaces: PascalCase (e.g., FireIncident, UserService)
• Functions/Variables: camelCase (e.g., getUserById, fireData)
• Constants: UPPER_SNAKE_CASE for true constants (e.g., MAX_RETRY_COUNT)
• Type Parameters: Single uppercase letter or PascalCase (e.g., T, TResponse)
• Files: kebab-case for most files (e.g., fire-incident.service.ts)

Imports

• Group imports: external packages, then internal modules, then local
• Use absolute imports where configured (via paths in tsconfig.json)
• Avoid circular dependencies
• Prefer named exports over default exports for better refactoring

Error Handling

• Use try-catch for async operations
• Throw typed errors or custom error classes
• Handle Promise rejections properly
• Log errors with appropriate context

Async/Await

• Always use async/await over raw Promises
• Add proper error handling for all async functions
• Be mindful of concurrent operations - use Promise.all() when appropriate
• Don't forget to await async calls

Testing

• Test files: *.spec.ts (Jest) or *.test.ts (Vitest)
• Aim for meaningful test coverage, not just high percentages
• Test edge cases and error conditions
• Mock external dependencies (APIs, databases)
• Use descriptive test names that explain what is being tested

Documentation

• Add JSDoc comments for:
  • Public classes and interfaces
  • Public methods and functions
  • Complex logic that needs explanation
  • API endpoints (in NestJS controllers)

Example:

/**
 * Retrieves fire incidents within a geographic boundary
 * @param bounds - Geographic bounding box
 * @param options - Query options (date range, severity filter)
 * @returns Array of fire incidents matching criteria
 * @throws {ValidationError} If bounds are invalid
 */
async getFiresInBounds(bounds: Bounds, options: QueryOptions): Promise<FireIncident[]>

Performance

• Avoid unnecessary re-renders in React components
• Use pagination for large datasets
• Implement proper caching strategies
• Be mindful of memory leaks (event listeners, subscriptions)
• Use lazy loading for large dependencies

Security

• Never commit sensitive data (API keys, passwords)
• Use environment variables for configuration
• Validate and sanitize all user inputs
• Use parameterized queries (TypeORM handles this)
• Implement proper authentication and authorization checks