typescript-advanced

What this skill does

# TypeScript Advanced Types

Comprehensive guidance for mastering TypeScript's advanced type system. This SKILL.md is a **dispatcher** — the detailed code patterns live in `references/*.md` and are loaded on demand.

## Required Reading Router

Read the matching reference before producing code. Each is one level deep and self-contained.

| Goal | Read |
|------|------|
| Refresh foundational generics, conditional types, mapped types, template literals, utility types | `references/core-concepts.md` |
| Build a type-safe event emitter, API client, builder, deep utility, form validator, or discriminated state machine | `references/advanced-patterns.md` |
| Use `infer`, type guards, assertion functions, or write compile-time type tests | `references/type-inference.md` |
| Apply project-level configuration, interfaces-vs-types, error handling, performance | `references/best-practices.md` |

## When to Use This Skill

- Building type-safe libraries or frameworks
- Creating reusable generic components
- Implementing complex type inference logic
- Designing type-safe API clients
- Building form validation systems
- Creating strongly-typed configuration objects
- Implementing type-safe state management
- Migrating JavaScript codebases to TypeScript

## Decision Map

Use these decision points to pick the right tool before writing code:

| Scenario | Recommendation |
|----------|----------------|
| Function parameters | Always explicit |
| Return types | Let TypeScript infer (usually) |
| Local variables | Let TypeScript infer |
| Public API boundaries | Always explicit |
| Object shapes (extensible) | Use `interface` |
| Union types | Use `type` |
| Computed/mapped types | Use `type` |
| Runtime-narrowing of `unknown` | Type guard or assertion (see `references/type-inference.md`) |
| Variant data with shared field | Discriminated union (see `references/advanced-patterns.md` Pattern 6) |

## Core Guidelines

1. **Use `unknown` over `any`** — Enforce type checking at boundaries.
2. **Prefer `interface` for object shapes** — Better error messages, declaration merging.
3. **Use `type` for unions and computed types** — More flexible for mapped/conditional types.
4. **Leverage type inference** — Let TypeScript infer when possible; annotate only at boundaries.
5. **Create helper types** — Build reusable type utilities (see `references/advanced-patterns.md`).
6. **Use const assertions** — Preserve literal types.
7. **Avoid type assertions** — Prefer type guards (see `references/type-inference.md`).
8. **Document complex types** — Add JSDoc on exported public types.
9. **Use strict mode** — Enable all strict compiler options.
10. **Test your types** — Use `Expect<Equal<X, Y>>` compile-time tests (see `references/type-inference.md`).

## Recommended `tsconfig.json`

```json
{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "moduleResolution": "Bundler"
  }
}
```

For deeper configuration rationale, read `references/best-practices.md`.

## Common Pitfalls

1. **Over-using `any`** — Defeats the purpose of TypeScript.
2. **Ignoring strict null checks** — Can lead to runtime errors.
3. **Too complex types** — Can slow down compilation.
4. **Not using discriminated unions** — Misses type narrowing opportunities.
5. **Forgetting `readonly` modifiers** — Allows unintended mutations.
6. **Circular type references** — Can cause compiler errors.
7. **Not handling edge cases** — Empty arrays, null values, missing keys.

## Performance Considerations

- Avoid deeply nested conditional types.
- Use simple types when possible.
- Cache complex type computations behind `type Alias = ...`.
- Limit recursion depth in recursive types (TS caps around 50).
- Use build tools to skip type checking in production.
- Prefer type guards over type assertions for runtime safety.
- Keep union types small in hot paths.

See `references/best-practices.md#performance-considerations` for deeper analysis.

## External Resources

- TypeScript Handbook — https://www.typescriptlang.org/docs/handbook/
- Type Challenges — https://github.com/type-challenges/type-challenges
- TypeScript Deep Dive — https://basarat.gitbook.io/typescript/
- Effective TypeScript — book by Dan Vanderkam