ts-coding-standards

name	ts-coding-standards
description	Use when writing, reviewing, or refactoring TypeScript code. Provides type safety patterns, error handling, project layout, and async programming guidelines.
allowed-tools	Read, Grep, Glob

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

Source file size

• Hard limit: No TypeScript source file under src/ (including *.test.ts / *.tsx) should stay above 1000 lines. If a file is at or past that size, split it in the same change set or as a focused follow-up.
• How to split: Prefer clear module boundaries (feature, layer, or cohesive helpers). When many imports point at one path, use a thin facade file that re-exports from *-helpers.ts, *-types.ts, or a small subdirectory so callers keep stable import paths.
• Agents: When editing or reviewing code, if a touched file is 1000+ lines, treat splitting as in scope for the task unless the user explicitly excludes it.
• Automation: Non-test sources under src/ are checked by Biome (noExcessiveLinesPerFile, 1000 lines). Legacy *.test.ts files may exceed this until split; the guideline above still applies during review.

After coding (agents)

After modifying TypeScript under src/ or vitest.config.ts:

1. Run biome check . --diagnostic-level=warn (or bun run lint:biome, which sets that threshold). Use Biome from nix develop / flake devShell, or bunx biome ... when the platform binary works.
2. Run bun run typecheck.
3. Run bun run test (or the subset relevant to the change).
4. Run Prettier when you touch formatted paths: bun run format or bunx prettier --write on the files you edited.

If Biome or typecheck reports issues, fix them before declaring the task complete.

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