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

Generate clean, well-structured, and easily maintainable code.
Implement tests for all the code you generate.
Include robust error handling and proper logging.
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:

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:

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:

/** * 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:

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:

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:

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:

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();    });  });});

stack: