TypeScript Typescape: Type-System Escape Patterns and Why They Hurt Your Code

// ✅ Use a type guard instead of casting
function isMouseEvent(e: Event): e is MouseEvent {
  return 'clientX' in e
}

function handler(event: Event) {
  if (isMouseEvent(event)) {
    // TypeScript knows: event is MouseEvent
    console.log(event.clientX)
  }
}

type Theme = Record<string, string | number>

// ❌ as — loses literal types
const colors = {
  red: '#f00',
  green: '#0f0',
} as Theme  // colors.red: string | number (lost!)

// ✅ satisfies — keeps the literal, but still validates
const colors = {
  red: '#f00',
  green: '#0f0',
} satisfies Theme  // colors.red: string (kept, still validated)

// ❌ WRONG: Blind @ts-ignore
// @ts-ignore
someUntypedCall()  // hides ANY error on this line

// ❌ WRONG: Disabling a whole file
// @ts-nocheck
export function doStuff(x: any) { ... }  // no type checking anymore

// ✅ RIGHT: @ts-expect-error with documented reason
// @ts-expect-error: Library types are wrong, see ticket XYZ-123
legacyApi.call()

// ✅ RIGHT: Minimal scope + justification
try { ... }
catch (e: unknown) {  // catch variable is unknown — TS 4.4+
  // @ts-expect-error: legacy lib throws plain objects
  const msg = e.message
}

// ❌ WRONG: any everywhere
function processData(data: any): any {  // input + output loose
  return data.result.user.name
}

// ❌ WRONG: object/{} are "almost any"
function handleError(e: object) {
  return e.message  // Property 'message' does not exist on object
}

// ❌ WRONG: Record<string, any> for configuration
type Config = Record<string, any>
const cfg: Config = loadConfig()  // anything goes

// ❌ WRONG: Index signature in interface
interface ApiResponse {
  [key: string]: any  // typos in property names go unnoticed
}

// ✅ RIGHT: Real interface
interface ApiResponse {
  status: number
  data: User[]
  message: string
}

// ✅ RIGHT: unknown + type guard
function isApiResponse(x: unknown): x is ApiResponse {
  return typeof x === 'object' && x !== null && 'status' in x
}

function processData(data: unknown): User[] {
  if (isApiResponse(data)) {
    return data.data  // TypeScript checks it
  }
  throw new Error('Invalid API response')
}

// ❌ WRONG: Type guard lies
function isString(x: unknown): x is string {
  return true  // TS trusts you, even though x can be anything
}

// ✅ RIGHT: Real validation
function isString(x: unknown): x is string {
  return typeof x === 'string'
}

### Typescape check (TypeScript)

For every file with `as`, `any`, `unknown`, `@ts-`, or `Record<...>`:

**Runtime casts:**
- [ ] No `as any` casts (exception: documented, isolated, with justification)
- [ ] No `as unknown as T` double casts
- [ ] No `as never` / `as never[]`
- [ ] `x!` (non-null assertion) is justified (not "because I don't have time")
- [ ] Function parameters typed `unknown` have a preceding type guard
- [ ] `this as Record<...>` and similar `this` casts removed
- [ ] `JSON.parse(...)` always followed by validation (Zod or similar)
- [ ] Real types used (e.g., `ClassName | undefined` instead of `unknown + cast`)

**Compiler directives:**
- [ ] No `// @ts-ignore` (blocking — use `@ts-expect-error` + ticket)
- [ ] No `// @ts-nocheck` (disabling the whole file = blocking)
- [ ] `@ts-expect-error` has a ticket reference in the comment

**Type annotations:**
- [ ] No `: any` in function signatures (input or output)
- [ ] No `: object` / `: {}` / `: Function` as parameter type
- [ ] No `Record<string, any>` for structured data
- [ ] No index signatures `[key: string]: any` in interfaces
- [ ] Type predicates (`x is T`) actually validate

**tsconfig:**
- [ ] `strict: true` (or migration plan toward it)
- [ ] No disabled strict options without a tracking ticket

**Special cases — allowed when documented:**
- `value as const` (narrowing, not an escape)
- `value satisfies T` (constraint check, not an escape) — TS 4.9+
- `unknown` + type guard (correct narrowing flow)