pantheon-ai/typescript-advanced

Runtime type guards, narrowing, and exhaustiveness checking for TypeScript — typeof/instanceof/in guards, custom and generic type predicates (value is T), discriminated union narrowing, assertion functions (asserts value is T), branded/nominal types validated at runtime, and exhaustive switch statements with a never guard. Use when replacing an unsafe `as` assertion with a real runtime check, fixing "Object is possibly undefined", modeling impossible states out of existence, writing an `is*` predicate, or making a switch over a union fail to compile when a case is missing.

Advanced TypeScript type-system mechanics — union and intersection types, conditional types with `infer`, mapped types, template literal types, generics and their constraints, index signatures, type assertions, and extracting types from other types (return types, array elements, promise results). Use when designing a complex generic, modeling a type that transforms based on another type, extracting a type from a function or structure with `infer`, or deciding between a type assertion and a real narrowing check.

TypeScript design patterns that use the type system to enforce correctness at compile time — the builder pattern with required-field tracking, type-safe state machines and event emitters, dependency injection, plugin systems, recursive/deep-readonly utility types, type-safe module encapsulation, advanced generic constraints, and typed API clients. Use when structuring a class or module so invalid usage fails to compile rather than throwing at runtime, e.g. "how do I stop `.build()` being called before required fields are set" or "how do I type an event emitter so payloads match their event name".

TypeScript's built-in utility types and how to build custom ones — Partial/Required, Pick/Omit, Readonly/Record, Extract/Exclude, NonNullable/Awaited, ReturnType/Parameters/ConstructorParameters/InstanceType, key remapping with `as` in mapped types, and hand-rolled custom mapped types. Use when picking the right built-in utility type instead of hand-writing one, extracting a function's parameter or return type, filtering a union with Extract/Exclude, or remapping object keys.

TypeScript compiler configuration — tsconfig.json structure, strict-mode flags and what each one catches, module resolution strategies (node/bundler/nodenext), and diagnosing/fixing slow type-checking. Use when bootstrapping a tsconfig.json for a new project, deciding which strictness flags to enable beyond `strict: true`, debugging a module-resolution error, or a `tsc --noEmit` run that has gotten too slow.

Type-first TypeScript coding practices — designing types before implementation, making illegal states unrepresentable with discriminated unions, runtime validation with Zod at system boundaries, and module organization (single-function modules, barrel files, encapsulation). Use when starting a new feature by asking what the types should look like first, spotting an interface with too many optional fields that let impossible combinations compile, or deciding how to validate data coming from outside the type system (an API response, form input, environment variables).

Documentation tooling for TypeScript projects — JSDoc comment patterns that surface in IDE tooltips, TypeDoc configuration for generating API documentation sites, Architectural Decision Record (ADR) templates for recording design decisions, and framework-specific documentation patterns (NestJS, React, Angular/Compodoc). Use when writing JSDoc for a public API, setting up TypeDoc to generate documentation from source, recording why a technical decision was made, or documenting a framework-specific pattern.