typescript-advanced

# 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