typescript-magician

---

name: typescript-magician description: Designs complex generic types, refactors any types to strict alternatives, creates type guards and utility types, and resolves TypeScript compiler errors. Use when the user asks about TypeScript (TS) types, generics, type inference, type guards, removing any types, strict typing, type errors, infer, extends, conditional types, mapped types, template literal types, branded/opaque types, or utility types like Partial, Record, ReturnType, and Awaited. metadata: tags: typescript, types, generics, type-safety, advanced-typescript

When to use

Use this skill for:

• TypeScript errors and type challenges
• Eliminating any types from codebases
• Complex generics and type inference issues
• When strict typing is needed

Instructions

When invoked:

1. Run tsc --noEmit to capture the full error output before making changes
2. Identify the root cause of type issues (unsound inference, missing constraints, implicit any, etc.)
3. Craft precise, type-safe solutions using advanced TypeScript features
4. Eliminate all any types with proper typing — validate each replacement still satisfies call sites
5. Confirm the fix compiles cleanly with a second tsc --noEmit pass

Capabilities include:

• Advanced generics and conditional types
• Template literal types and mapped types
• Utility types and type manipulation
• Brand types and nominal typing
• Complex inference patterns
• Variance and distribution rules
• Module augmentation and declaration merging

For every TypeScript challenge:

• Explain the type theory behind the problem
• Provide multiple solution approaches when applicable
• Show before/after type representations
• Include comprehensive type tests
• Ensure full IntelliSense support

Quick Examples

Eliminating any with generics

Before

function getProperty(obj: any, key: string): any {
  return obj[key];
}

After

function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}
// getProperty({ name: "Alice" }, "name") → inferred as string ✓

Narrowing an unknown API response

Before

async function fetchUser(): Promise<any> {
  const res = await fetch("/api/user");
  return res.json();
}

After

interface User { id: number; name: string }

function isUser(value: unknown): value is User {
  return (
    typeof value === "object" &&
    value !== null &&
    "id" in value &&
    "name" in value
  );
}

async function fetchUser(): Promise<User> {
  const res = await fetch("/api/user");
  const data: unknown = await res.json();
  if (!isUser(data)) throw new Error("Invalid user shape");
  return data;
}

Reference

Read individual rule files for detailed explanations and code examples:

Core Patterns

• rules/as-const-typeof.md - Deriving types from runtime values using as const and typeof
• rules/array-index-access.md - Accessing array element types using [number] indexing
• rules/utility-types.md - Built-in utility types: Parameters, ReturnType, Awaited, Omit, Partial, Record

Advanced Generics

• rules/generics-basics.md - Fundamentals of generic types, constraints, and inference
• rules/builder-pattern.md - Type-safe builder pattern with chainable methods
• rules/deep-inference.md - Achieving deep type inference with F.Narrow and const type parameters

Type-Level Programming

• rules/conditional-types.md - Conditional types for type-level if/else logic
• rules/infer-keyword.md - Using infer to extract types within conditional types
• rules/template-literal-types.md - String manipulation at the type level
• rules/mapped-types.md - Creating new types by transforming existing type properties

Type Safety Patterns

• rules/opaque-types.md - Brand types and opaque types for type-safe identifiers
• rules/type-narrowing.md - Narrowing types through control flow analysis
• rules/function-overloads.md - Using function overloads for complex function signatures

Debugging

• rules/error-diagnosis.md - Strategies for diagnosing and understanding TypeScript type errors