tacogips/ts-coding-standards

TypeScript Coding Standards

This skill provides modern TypeScript coding guidelines and best practices for this project.

When to Apply

Apply these standards when:

• Writing new TypeScript code
• Reviewing or refactoring existing TypeScript code
• Designing module APIs and interfaces
• Implementing error handling strategies

Core Principles

1. Type Safety Over Convenience - Never sacrifice type safety for shorter code
2. Explicit Over Implicit - Make types and intentions clear
3. Simple Over Clever - Prefer readable code over clever abstractions
4. Fail Fast - Catch errors at compile time, not runtime

Quick Reference

Must-Use Patterns

| Pattern | Use Case | |---------|----------| | Discriminated Unions | State machines, API responses, Result types | | Branded Types | IDs, emails, validated strings | | readonly | Data that should not mutate | | unknown in catch | Safe error handling | | Explicit undefined checks | Array/object indexed access |

Must-Avoid Anti-Patterns

| Anti-Pattern | Alternative | |--------------|-------------| | any type | unknown with type guards | | Throwing exceptions for control flow | Result type pattern | | Optional chaining without null check | Explicit narrowing | | Deep folder nesting (>3 levels) | Flat, feature-based structure | | Implicit undefined in optional props | Explicit T \| undefined |

Detailed Guidelines

For comprehensive guidance, see:

• Error Handling Patterns - Result types, discriminated unions, neverthrow
• Type Safety Best Practices - Branded types, strict config, type guards
• Project Layout Conventions - Directory structure, file naming, imports
• Async Programming Patterns - Promise handling, concurrent execution
• Security Guidelines - Credential protection, path sanitization, sensitive data handling

tsconfig.json Strict Mode

This project uses maximum TypeScript strictness. Ensure your code compiles with:

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noPropertyAccessFromIndexSignature": true,
    "noFallthroughCasesInSwitch": true,
    "noImplicitOverride": true,
    "noImplicitReturns": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true
  }
}

References

• TypeScript Advanced Patterns 2025
• The Strictest TypeScript Config
• neverthrow - Type-Safe Errors