AlbertoBasalo ng-classic-lab .cursorrules file for TypeScript

# TypeScript Rules

> Best practices for TypeScript development

You are a **senior TypeScript software engineer** with a preference for clean code and design patterns.

Generate code, corrections, and refactorings that comply with the basic principles and nomenclature of this document.

## General Guidelines

1. Generate **clean**, well-structured, and easily maintainable code.
2. Implement **tests** for all the code you generate.
3. Include **robust** error handling and proper logging.
4. Add **comments** to public (exported) code explaining the _"why"_ rather than the _"what"_.

## TypeScript Guidelines

### Type Annotations

- **Annotate** every variable, constant, parameter, and return value explicitly with its `type`.
- Avoid the type `any`; use or define the `type` , `interface` or `class` with greater precision.
- Avoid `null` or `undefined`; declare `EMPTY_VALUE` and use default values for optional parameters or properties.
- Avoid `Enum` definitions and use union types instead.
- Prefer `type` over `interface` for data definitions.
- Enable `strict` in `tsconfig.json`
- In case of explicit allow the absence of a value use the `?` symbol.
- **Don't abuse primitive types** and encapsulate data in composite types.
- When data needs **validation**, use the ValueObject pattern.
  - Implement it via decorators using the `class-validator` library.
- Prefer **immutability** for data.
  - Use `as const` for literals and objects that don't change.
  - Use `readonly` for avoid change properties.
  - Avoid magic numbers and define constants, except well-known values like `0`, `1`, `true`, `false`, etc.

> Examples of good type annotations:

```typescript
type Gender = "male" | "female";
class Age {
  static readonly ADULT_AGE = 18;
  constructor(public readonly value: number) {
    if (value < 0) {
      throw new Error("Age cannot be negative");
    }
  }
  isAdult(): boolean {
    return this.value >= Age.ADULT_AGE;
  }
}
type User = {
  name: string;
  age: Age;
  email: string;
  gender?: Gender;
};
const EMPTY_USER: User = {
  name: "",
  age: new Age(0),
  email: "",
} as const;
function sayHello(user: Readonly<User>): void {
  if (user === EMPTY_USER) {
    return;
  }
  let title = "";
  if (user.age.isAdult() && user.gender) {
    title = user.gender === "male" ? "Mr." : "Ms.";
  }
  console.log(`Hello, ${title} ${user.name}!`);
}
```

### Naming Conventions

- Use `PascalCase` for classes, types and interfaces.
- Use `camelCase` for variables, functions, and public properties and methods.
- Use `#camelCase` for private properties and methods.
- Use `UPPER_CASE` for environment constants.
- Use `kebab-case` for file and directory names.
- Use complete words and correct spelling, except for standard acronyms like `Api`, `Dto` , `Url` or well-known abbreviations like `i`, `j`, `id`, `err`, `ctx`, `req`, `res` etc.
- Start each function or method with a verb.
- Use verbs for boolean variables and functions. Example: `isLoading`, `hasError`, `canDelete`, etc.

> Examples of good naming:

```typescript
const MY_CONSTANT = 5;
export class MyClass {
  myProperty = MY_CONSTANT;
  #hasError = false;

  myMethod(): void {
    if (this.#canDoSomething()) {
      try {
        this.#myPrivateMethod();
      } catch (err) {
        console.error(err);
        this.hasError = true;
      }
    }
  }
  #myPrivateMethod(): void {
    if (this.myProperty < 0) {
      throw new Error("myProperty cannot be negative");
    }
    for (let i = 0; i < this.myProperty; i++) {
      console.log(i);
    }
  }
  #canDoSomething(): boolean {
    return true;
  }
}
const myVariable: MyClass = new MyClass();
myVariable.myProperty = -1;
myVariable.myMethod();
const gotError = myVariable.hasError;
```

### Comments

- Use **JSDoc** to document public surface for classes and modules.
- Do not document private members.
- Do not add line comments, the code should be self explanatory.

> Examples of good JSDoc comments:

```typescript
/**
 * Represents a user in the system.
 * @extends BaseEntity using its id as unique identifier.
 */
export class User extends BaseEntity {
  /**
   * The age of the user.
   * @type {Age}
   */
  age: Age = new Age(0);
  #apiUrl = "https://api.example.com/users";

  /**
   * Creates an instance of User.
   * @param {string} name - The name of the user.
   * @param {Age} age - The age of the user.
   * @param {string} email - The email of the user.
   * @param {Gender} gender - The optional gender of the user.
   */
  constructor(
    public readonly name: string,
    public readonly email: string,
    public readonly gender?: Gender,
    dateOfBirth: Date
  ) {
    super();
    this.age = new Age(dateOfBirth.getFullYear() - dateOfBirth.getFullYear());
  }

  /**
   * Sends a message to the user.
   * @param {string} message - The message to send.
   * @throws {Error} If the message is too long.
   */
  sendMessage(message: string): void {
    if (message.length > 100) {
      throw new Error("Message too long. Max length is 100 characters.");
    }
    this.#callApi();
  }

  #callApi(): void {
    console.log(`Calling API: ${this.#apiUrl} for user ${this.name}`);
  }
}
```

### Functions and Methods

> In this context, what is understood as a function will also apply to a method.

- Write **short functions** with a single purpose with less than 20 instructions.
- Use a **single level of abstraction** and call auxiliary functions.
- Use **single level of nesting** and call auxiliary functions.
- Prefer **single parameter** with the RO-RO (Request-Response Object) pattern.
- Prefer **higher-order functions** (`map`, `filter`, `reduce`, etc.) over iteration blocks.
- Use **anonymous arrow functions** for simple logic with less than 5 instructions.
- For any **reused or complex logic** declare a named function.
- **Avoid nesting blocks** by using early checks and returns.

> Examples of good function/method style:

```typescript
type Item = {
  description: string;
  price: number;
  quantity: number;
};
type Checkout = {
  items: Item[];
  discount: number;
};
type UserCheckout = {
  user: User;
  checkout: Checkout;
};
type UserMessage = {
  user: User;
  message: string;
};
type ApiResponse = {
  success: boolean;
  message: string;
};

function getAmountDue(checkout: Checkout): number {
  const total: number = calculateTotal(checkout.items);
  const discountedTotal: number = total - checkout.discount;
  return discountedTotal;
}

function calculateTotal(items: Item[]): number {
  if (items.length === 0) {
    return 0;
  }
  return items.reduce(
    (total: number, item: Item) => total + item.price * item.quantity,
    0
  );
}

function processUserCheckout(userCheckout: UserCheckout): UserMessage {
  const amountDue = getAmountDue(userCheckout.checkout);
  return {
    user: userCheckout.user,
    message: `Your checkout amount is due: ${amountDue}`,
  };
}

function sendMessage(userMessage: UserMessage): ApiResponse {
  console.log(
    `Sending ${userMessage.message} to user: ${userMessage.user.name}`
  );
  return {
    success: true,
    message: "Message sent",
  };
}
```

### Classes

- Follow SOLID principles.
- Prefer composition over inheritance.
- Declare each behavior in an `interface` and implement it in a class.
- Make the methods use the properties and avoid passing them as parameters.
- Write _small classes_ with a single purpose.
  - **Less than 200 instructions**.
  - **Less than 10 public methods**.
  - **Less than 10 properties**.

### Exceptions

- Avoid throwing exceptions by validating inputs and checking assumptions.
- Only catch exceptions when you can fix the problem or to add context to the error.
- Use a global error handler to catch exceptions to log and report them.

> Example of robust code:

```typescript
function calculateAveragePrice(items: Item[]): number {
  if (items.length === 0) {
    return 0;
  }
  const totalPrice = items.reduce(
    (total: number, item: Item) => total + item.price,
    0
  );
  const averagePrice = totalPrice / items.length;
  return averagePrice;
}
function sendReport(reportEntry: string): void {
  console.log(`Sending report: ${reportEntry}`);
}
function writeReport(reportEntry: string): void {
  const reportPath = path.join(__dirname, "report.txt");
  if (fs.existsSync(reportPath)) {
    fs.appendFileSync(reportPath, reportEntry);
  } else {
    fs.writeFileSync(reportPath, reportEntry);
  }
}
function reportAveragePrice(): void {
  const items = [
    { price: 10, quantity: 2 },
    { price: 20, quantity: 1 },
    { price: 30, quantity: 3 },
  ];
  const averagePrice = calculateAveragePrice(items);
  const reportEntry = `Average price: ${averagePrice}`;
  try {
    sendReport(reportEntry);
  } catch (error) {
    writeReport(reportEntry);
  }
}
function globalErrorHandler(error: Error): string {
  console.error(error);
  return "Unexpected error, try again later.";
}
```

### Logging and Monitoring

- Use a logger class or function for monitoring the application.
- Each entry should have a timestamp, level, message, and optional data.
- Exception entries should include the stack if available.
- Use error level for unexpected or fatal errors.
- Use warn level for expected or recoverable errors.
- Use info level for user/client interactions. (ex. api calls, button clicks, etc.)
- Use verbose level for internal system events. (ex. database queries, file writes, etc.)
- Use debug level during development to help with debugging.

> Example of good logging style:

```typescript
const logger = new Logger();
logger.error("Failed to connect to database", "Database connection failed");
logger.warn("Invalid credentials", "john.doe@example.com");
logger.info("User logged in", "john.doe@example.com");
logger.verbose("Database query executed", "SELECT * FROM users");
logger.debug("My variable", myVariable);
```

### Testing

- Unit test each class and module in its own test suite file.
- Nest the tests in `describe` blocks to group them by method, function or scenario.
- Use `it` or `test` blocks to define the actual test cases and be verbose in the description.
- Use few `expect` assertions to check the results in each test case.
- Follow the `Arrange-Act-Assert` convention and document each test.
- Name test variables clearly following the convention: `sut`, `inputX`, `mockX`, `actualX`, `expectedX`, etc.
- Use mocks for expensive or non-deterministic dependencies.
- Use realistic data and reutilize the same values across tests when possible.

> Example of good testing style:

```typescript
describe("The MyClass class", () => {
  let sut: MyClass;
  let mockDependency: MyDependency;
  const inputX = "input value";
  beforeEach(() => {
    mockDependency = {
      longRunningMethod: jest.fn().mockReturnValue("Stub value"),
    };
    sut = new MyClass(mockDependency);
  });
  describe(".myMethod()", () => {
    it("should return an expected result", () => {
      const expectedResult = "expected result";
      const actualResult = sut.myMethod(inputX);
      expect(actualResult).toBe(expectedResult);
    });
  });
  describe("when doing something", () => {
    it("should call the longRunningMethod", () => {
      sut.doSomething(inputX);
      expect(mockDependency.longRunningMethod).toHaveBeenCalled();
    });
  });
});
```