Agent Skills: TypeScript Advanced Patterns

TypeScript Advanced Patterns

Expert guidance for leveraging TypeScript's advanced type system features to build robust, type-safe applications with sophisticated type inference, compile-time guarantees, and maintainable domain models.

When to Use This Skill

• Building type-safe APIs with strict contracts and validation
• Implementing complex domain models with compile-time enforcement
• Creating reusable libraries with sophisticated type inference
• Enforcing business rules through the type system
• Building type-safe state machines and builders
• Developing framework integrations requiring advanced types
• Implementing runtime validation with type-level guarantees

Core Concepts

TypeScript's type system enables compile-time safety through:

1. Conditional Types: Type selection based on conditions (type-level if/else)
2. Mapped Types: Transform object types systematically (Partial, Readonly, Pick, Omit)
3. Template Literal Types: String manipulation at compile time
4. Type Guards: Runtime checking with type narrowing (value is Type)
5. Discriminated Unions: Type-safe state machines with exhaustiveness checking
6. Branded Types: Nominal types for preventing primitive mixing
7. Builder Pattern: Type-safe fluent APIs with progressive type constraints
8. Advanced Generics: Constraints, inference, and higher-kinded type patterns
9. Utility Types: Deep transformations and compositions
10. Type Inference: Const assertions and contextual typing

Quick Reference

Load detailed references on-demand:

| Topic | Reference File | |-------|----------------| | Conditional Types | skills/typescript-advanced-patterns/references/conditional-types.md | | Mapped Types | skills/typescript-advanced-patterns/references/mapped-types.md | | Template Literal Types | skills/typescript-advanced-patterns/references/template-literal-types.md | | Type Guards | skills/typescript-advanced-patterns/references/type-guards.md | | Discriminated Unions | skills/typescript-advanced-patterns/references/discriminated-unions.md | | Branded Types | skills/typescript-advanced-patterns/references/branded-types.md | | Builder Pattern | skills/typescript-advanced-patterns/references/builder-pattern.md | | Advanced Generics | skills/typescript-advanced-patterns/references/advanced-generics.md | | Utility Types | skills/typescript-advanced-patterns/references/utility-types.md | | Type Inference | skills/typescript-advanced-patterns/references/type-inference.md | | Decorators | skills/typescript-advanced-patterns/references/decorators.md | | Performance Best Practices | skills/typescript-advanced-patterns/references/performance-best-practices.md | | Common Pitfalls | skills/typescript-advanced-patterns/references/common-pitfalls.md | | Testing Types | skills/typescript-advanced-patterns/references/testing-types.md |

Implementation Workflow

1. Identify Pattern Need

• Analyze type safety requirements
• Identify runtime vs compile-time constraints
• Choose appropriate pattern from Quick Reference

2. Load Reference

• Read specific reference file for pattern
• Review examples and use cases
• Understand trade-offs

3. Implement Pattern

• Start simple, add complexity as needed
• Use strict mode (tsconfig.json with "strict": true)
• Test with type assertions

4. Validate

• Ensure type errors caught at compile time
• Verify runtime behavior matches types
• Check performance (avoid excessive type complexity)

5. Document

• Add JSDoc comments for public APIs
• Document type constraints and assumptions
• Provide usage examples

Common Mistakes to Avoid

1. Using any instead of unknown: Loses all type safety

   • Use unknown and type guards instead

2. Type assertions without validation: Unsafe runtime behavior

   • Prefer type guards (value is Type) over as Type

3. Overusing generics: Unnecessary complexity

   • Only use generics when types truly vary

4. Deep type nesting: Slow compilation, hard to debug

   • Keep types composable and shallow

5. Forgetting readonly: Accidental mutations

   • Mark immutable data structures as readonly

6. Not enabling strict mode: Missing null checks and type errors

   • Always use "strict": true in tsconfig.json

7. Mixing type and interface incorrectly: Confusing semantics

   • Use type for unions/utilities, interface for object shapes

Quick Patterns

Type-Safe ID

type UserId = string & { readonly __brand: 'UserId' };
function createUserId(id: string): UserId { return id as UserId; }

Discriminated Union

type State =
  | { status: 'loading' }
  | { status: 'success'; data: string }
  | { status: 'error'; error: Error };

Mapped Type Transformation

type Readonly<T> = { readonly [P in keyof T]: T[P] };
type Partial<T> = { [P in keyof T]?: T[P] };

Type Guard

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

Resources

• TypeScript Handbook: https://www.typescriptlang.org/docs/handbook/
• Type Challenges: https://github.com/type-challenges/type-challenges
• ts-toolbelt: Advanced type utilities library
• zod: Runtime validation with TypeScript inference
• tsd: Test TypeScript type definitions