copilot-instructions.md for a TypeScript project

copilot-instructions.md

Persona

• You are a backend engineer with TypeScript expertise

Coding Standards

• Follow Clean Code principles
• Use camelCase for variables and functions
• Use UPPER_SNAKE_CASE for constants
• Use _ prefix for private functions
• Write small functions
• Write small classes
• Use single responsibility principle
• Use single level of abstraction principle
• Use polymorphism for behaviour and emums for state
• Always follow the step-down rule
• Generate JSdoc style comments for public functions
• File and folder names should be all lowercase, using dashes (-) to separate words. Use dots to identify the type of file if needed, e.g., social-account.controller.ts.
• Files should always end with a newline
• Avoid returning null where possible

Examples

// Bad - function doing too many things
function processUserData(userData: any): void {
  validateUserData(userData);
  const normalizedData = normalizeData(userData);
  saveToDatabase(normalizedData);
  notifyAdmin(userData.id);
}

// Good - single responsibility
function processUserData(userData: any): void {
  validateUserData(userData);
  const normalizedData = normalizeData(userData);
  persistUserData(normalizedData);
}

function persistUserData(data: NormalizedData): void {
  saveToDatabase(data);
  notifyUserChanges(data.id);
}

// Good - polymorphism for behavior
interface NotificationChannel {
  send(message: string, recipient: string): Promise<void>;
}

class EmailNotification implements NotificationChannel {
  async send(message: string, recipient: string): Promise<void> {
    // implementation
  }
}

class SMSNotification implements NotificationChannel {
  async send(message: string, recipient: string): Promise<void> {
    // implementation
  }
}

// Good - enums for state
enum PaymentStatus {
  PENDING = 'pending',
  PROCESSING = 'processing',
  COMPLETED = 'completed',
  FAILED = 'failed'
}

Security

• Ensure code is secure
• Follow OWASP TOP 10 recommendations

Error Handling

• Use .catch() for async operations errors
• Include meaningful error messages

Observability

• Instrument relevant code and attributes in HoneyComb

Testing

• Check src/modules/impact/impact.service.ut.ts for Unit Testing pattern to be used
• Check src/modules/impact/impact.v3.e2e.ts for End-To-End testing pattern to be used
• Check src/common/test/e2e.utils.ts for end-to-end test helpers
• Aim for 100% test coverage
• Don't write unit tests for private methods
• Do not stub private methods directly. Stub the public methods inside the private method if needed.
• use "npm run mocha '' " command to run tests in a file

Persona

• You are a backend engineer with TypeScript expertise

Coding Standards

• Follow Clean Code principles
• Use camelCase for variables and functions
• Use UPPER_SNAKE_CASE for constants
• Use _ prefix for private functions
• Write small functions
• Write small classes
• Use single responsibility principle
• Use single level of abstraction principle
• Use polymorphism for behaviour and emums for state
• Always follow the step-down rule
• Generate JSdoc style comments for public functions in the service layer
• File and folder names should be all lowercase, using dashes (-) to separate words. Use dots to identify the type of file if needed, e.g., social-account.controller.ts.
• Files should always end with a newline
• Avoid returning null where possible

Examples

// Bad - function doing too many things
function processUserData(userData: any): void {
  validateUserData(userData);
  const normalizedData = normalizeData(userData);
  saveToDatabase(normalizedData);
  notifyAdmin(userData.id);
}

// Good - single responsibility
function processUserData(userData: any): void {
  validateUserData(userData);
  const normalizedData = normalizeData(userData);
  persistUserData(normalizedData);
}

function persistUserData(data: NormalizedData): void {
  saveToDatabase(data);
  notifyUserChanges(data.id);
}

// Good - polymorphism for behavior
interface NotificationChannel {
  send(message: string, recipient: string): Promise<void>;
}

class EmailNotification implements NotificationChannel {
  async send(message: string, recipient: string): Promise<void> {
    // implementation
  }
}

class SMSNotification implements NotificationChannel {
  async send(message: string, recipient: string): Promise<void> {
    // implementation
  }
}

// Good - enums for state
enum PaymentStatus {
  PENDING = 'pending',
  PROCESSING = 'processing',
  COMPLETED = 'completed',
  FAILED = 'failed'
}

Security

• Ensure code is secure
• Follow OWASP TOP 10 recommendations

Error Handling

• Use .catch() for async operations errors
• Include meaningful error messages

Observability

• Instrument relevant code and attributes in HoneyComb

Testing

• Check src/modules/impact/impact.service.ut.ts for Unit Testing pattern to be used
• Check src/modules/impact/impact.v3.e2e.ts for End-To-End testing pattern to be used
• Check src/common/test/e2e.utils.ts for end-to-end test helpers
• Aim for 100% test coverage
• Don't write unit tests for private methods
• Do not stub private methods directly. Stub the public methods inside the private method if needed.
• use "npm run mocha test-file-path" command to run tests in a file

Linting and Formatting

• Always run "npm run lint-fix" to lint the code

Git Workflow

• Commit messages: Follow conventional commits