swe-programming-typescript

TypeScript Coding Standards

Purpose

Progressive disclosure of TypeScript coding standards for agents writing TypeScript code.

Authoritative Source: docs/explanation/software-engineering/programming-languages/typescript/README.md

Usage: Auto-loaded for agents when writing TypeScript code. Provides quick reference to idioms, best practices, and antipatterns.

Quick Standards Reference

Naming Conventions

Types and Interfaces: PascalCase

• Types: UserAccount, PaymentDetails
• Interfaces: IPaymentProcessor or PaymentProcessor (no prefix preferred)
• Type aliases: type UserId = string

Functions and Variables: camelCase

• Functions: calculateTotal(), findUserById()
• Variables: userName, totalAmount
• Constants: UPPER_SNAKE_CASE (MAX_RETRIES, API_ENDPOINT)

Files: kebab-case

• user-account.ts, payment-processor.ts

Modern TypeScript Features

Type Inference: Let TypeScript infer when obvious

const name = "John"; // string inferred
const count = 42; // number inferred

Union Types: Use for multiple possible types

type Result = Success | Error;
type Status = "pending" | "completed" | "failed";

Type Guards: Use for type narrowing

function isString(value: unknown): value is string {
  return typeof value === "string";
}

Generics: Use for reusable type-safe code

function identity<T>(value: T): T {
  return value;
}

Utility Types: Leverage built-in utilities

• Partial<T>: Make all properties optional
• Pick<T, K>: Select specific properties
• Omit<T, K>: Remove specific properties
• Readonly<T>: Make all properties readonly

Error Handling

Result Pattern: Prefer over throwing exceptions

type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };

Error Types: Define specific error types

class ValidationError extends Error {
  constructor(
    public field: string,
    message: string,
  ) {
    super(message);
    this.name = "ValidationError";
  }
}

Testing Standards

Jest/Vitest: Primary testing frameworks

• describe() for test suites
• it() or test() for individual tests
• beforeEach(), afterEach() for setup

Type-safe Tests: Ensure tests are type-checked

it("should return user", () => {
  const user: User = findUser("123");
  expect(user.name).toBe("John");
});

Security Practices

No any: Avoid any type

• Use unknown for truly unknown types
• Use generics for flexible typing

Input Validation: Validate external data

• Use Zod or similar for runtime validation
• Validate before processing

XSS Prevention: Sanitize user input

• Use framework escaping (React, Angular)
• Never use dangerouslySetInnerHTML without sanitization

Comprehensive Documentation

For detailed guidance, refer to:

• Idioms - TypeScript-specific patterns
• Best Practices - Clean code standards
• Anti-Patterns - Common mistakes

Related Skills

• docs-applying-content-quality
• repo-practicing-trunk-based-development

References

• TypeScript README
• Functional Programming