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](../../../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: UPPERSNAKECASE (MAXRETRIES, APIENDPOINT)

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](../../../docs/explanation/software-engineering/programming-languages/typescript/idioms.md) - TypeScript-specific patterns
• [Best Practices](../../../docs/explanation/software-engineering/programming-languages/typescript/best-practices.md) - Clean code standards
• [Anti-Patterns](../../../docs/explanation/software-engineering/programming-languages/typescript/anti-patterns.md) - Common mistakes

Test-Driven Development

TDD is required for all TypeScript code changes. Write the failing Vitest test first, confirm it fails for the right reason, implement the minimum code to pass, then refactor. For TypeScript the primary levels are Unit (Vitest with every OS-facing dependency injected), Integration (real isolated local resources with no network), E2E (Playwright or another real public boundary), and property/fuzz (fast-check for invariants). Every active Gherkin scenario requires Unit proof. The owning test:unit target collects native line coverage and hard-fails below 99%; only a narrow, enumerated boundary adapter with named Integration/E2E runtime proof may leave its denominator.

Canonical reference: [Test-Driven Development Convention](../../../repo-governance/development/workflow/test-driven-development.md)

Related Skills

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

References

• [TypeScript README](../../../docs/explanation/software-engineering/programming-languages/typescript/README.md)
• [Functional Programming](../../../repo-governance/development/pattern/functional-programming.md)