pantheon-org/typescript-advanced

TypeScript Advanced

Comprehensive TypeScript guidance covering compiler configuration, advanced types, utilities, type narrowing, best practices, and documentation patterns.

When to Apply

Use this skill when:

• Configuring TypeScript compiler (tsconfig.json)
• Working with advanced type features (generics, conditionals, mapped types)
• Creating custom utility types and type guards
• Implementing type-first development workflow
• Making illegal states unrepresentable with discriminated unions
• Implementing runtime validation with Zod
• Generating API documentation with JSDoc/TypeDoc
• Creating architectural decision records (ADRs)
• Debugging complex type errors
• Optimizing type checking performance

Use When

• "Help me do this with strict TypeScript."
• "How should I model this union/generic type?"
• "How do I avoid any and unsafe assertions?"
• "How do I fix this TypeScript compile error safely?"

Scope

In Scope

• tsconfig and strict-mode guidance.
• Advanced type modeling (generics, conditionals, mapped types).
• Runtime narrowing and type-safe validation patterns.
• TypeScript documentation patterns (JSDoc/TypeDoc, ADRs).

Out of Scope

• End-to-end testing setup.
• Framework build pipeline setup unrelated to TypeScript design.
• Language-agnostic coding standards.

Consolidation Note

This skill consolidates 5 original TypeScript skills (~3,372 lines) into a ~120-line navigation hub with on-demand reference loading:

• typescript-type-system (738 lines) - Compiler config, strict mode, module resolution
• typescript-utility-types (832 lines) - Built-in and custom utility types
• typescript-advanced-types (724 lines) - Generics, conditional types, mapped types, patterns
• typescript-best-practices (270 lines) - Type-first development, illegal states, Zod validation
• typescript-docs (808 lines) - JSDoc, TypeDoc, ADRs, framework-specific documentation

Categories by Priority

| Priority | Category | Impact | Prefix | | --- | --- | --- | --- | | CRITICAL | Compiler & Configuration | Essential foundation | compiler- | | CRITICAL | Best Practices & Patterns | Type-first workflow | practices- | | HIGH | Advanced Types | Complex type logic | types-advanced- | | HIGH | Built-in Utilities | Common transformations | utilities-builtin- | | MEDIUM | Custom Utilities | Specialized types | utilities-custom- | | MEDIUM | Type Narrowing | Runtime type guards | narrowing- | | MEDIUM | Documentation | API docs & ADRs | docs- |

How to Use

Read individual reference files for detailed guidance:

references/compiler-strict-mode.md
references/practices-type-first.md
references/types-advanced-conditional.md
references/utilities-builtin-partial.md
references/docs-jsdoc-patterns.md

Each reference file contains:

• Concepts and explanations
• Practical TypeScript examples
• Common patterns and use cases
• Best practices and pitfalls
• Performance considerations

Navigation Workflow

1. Start with practices - Understand type-first development workflow
2. Configure compiler - Set up tsconfig with strict mode; run npx tsc --noEmit to confirm zero errors before proceeding
3. Apply advanced types - Use generics, conditionals, mapped types; run npx tsc --noEmit after each change — if errors persist, consult references/types-advanced-conditional.md
4. Use utilities - Leverage built-in and custom utility types; if assignability errors appear, check references/utilities-builtin-partial.md
5. Implement narrowing - Add type guards for runtime safety; run npx tsc --noEmit to confirm narrowing is recognised — if not, consult references/narrowing-guards.md
6. Document - Generate API docs with JSDoc/TypeDoc; run npx typedoc --out docs src/index.ts and verify output

Quick Commands

Type Check

npx tsc --noEmit

Type Check Single Entry

npx tsc --noEmit src/index.ts

Generate Docs

npx typedoc --out docs src/index.ts

Find Unsafe Patterns

rg -n "\\bany\\b|@ts-ignore| as " src

Quick Fixes

Common TypeScript errors and their safe resolutions:

"Type X is not assignable to type Y"

Caused by incompatible types being assigned without narrowing.

// BAD — forces an incompatible assignment
const id = getValue() as string;

// GOOD — narrow first, then assign
const raw = getValue();
if (typeof raw !== "string") throw new TypeError("Expected string");
const id = raw; // TypeScript now knows id: string

"Object is possibly 'undefined'"

Caused by accessing a property without a null/undefined check.

// BAD — unsafe access
function getLength(arr: string[] | undefined) {
  return arr.length; // error
}

// GOOD — guard before access
function getLength(arr: string[] | undefined): number {
  if (arr === undefined) return 0;
  return arr.length;
}

"Parameter implicitly has an 'any' type"

Caused by missing type annotations under noImplicitAny.

// BAD — implicit any
function double(n) {
  return n * 2;
}

// GOOD — explicit annotation
function double(n: number): number {
  return n * 2;
}

Anti-Patterns

NEVER use any as a default escape hatch

WHY: any disables type checking and hides design bugs.

BAD:

function process(data: any) {
  return data.value;
}

GOOD:

function process<T extends { value: unknown }>(data: T) {
  return data.value;
}

NEVER silence type errors with unchecked assertions

WHY: assertions bypass compiler safety without runtime guarantees.

BAD:

const id = input as string;

GOOD:

if (typeof input !== "string") throw new TypeError("Expected string");
const id = input;

NEVER disable strict-mode findings instead of fixing model issues

WHY: strict mode surfaces real defects early.

BAD: @ts-ignore, strict: false, or broad ignore patterns.

GOOD: adjust type model, narrow correctly, and keep strict checks enabled.

References

• TypeScript Handbook
• TSConfig Reference
• Utility Types
• Type Challenges