Never Use Type Assertions on External Data — Validate Instead

// ❌ Looks safe — TypeScript shows no errors — but is a lie
interface User {
  id: string
  name: string
  email: string
  role: 'admin' | 'user'
}
 
export async function GET() {
  const res = await fetch('https://api.example.com/user/1')
  const user = await res.json() as User // TypeScript trusts you completely
 
  // If API returns { id: 1, fullName: "..." } instead:
  // user.name → undefined (no crash here, silent corruption)
  // user.name.toUpperCase() → "Cannot read properties of undefined" (crashes later)
  // user.role === 'admin' → false (security bug: can't distinguish missing from 'user')
  return NextResponse.json({ greeting: `Hello ${user.name}` }) // "Hello undefined"
}

// ❌ Type assertion on search params
export default function Page({ searchParams }: { searchParams: Record<string, string> }) {
  const filters = searchParams as { category: string; sort: 'asc' | 'desc'; page: string }
  // If ?sort=invalid → filters.sort is "invalid" but TypeScript says it's 'asc' | 'desc'
  const items = await getItems({ sort: filters.sort }) // Passes invalid value to query
}

// ❌ Double assertion to force incompatible types
const config = JSON.parse(rawConfig) as unknown as AppConfig
// If rawConfig is malformed, config silently has wrong shape

// ✅ Parse + infer — type comes from the schema, not an assertion
import { z } from 'zod'
 
const UserSchema = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string().email(),
  role: z.enum(['admin', 'user']),
})
 
type User = z.infer<typeof UserSchema> // Derived from schema, always in sync
 
export async function GET() {
  const res = await fetch('https://api.example.com/user/1')
  const json = await res.json()
  const user = UserSchema.parse(json) // Throws with clear error if shape is wrong
 
  // TypeScript knows the exact shape — because it was validated
  return NextResponse.json({ greeting: `Hello ${user.name}` })
}

// ✅ Search params with safe parsing and defaults
const FiltersSchema = z.object({
  category: z.string().optional(),
  sort: z.enum(['asc', 'desc']).default('asc'),
  page: z.coerce.number().int().min(1).default(1),
})
 
export default async function Page({
  searchParams,
}: {
  searchParams: Record<string, string | string[] | undefined>
}) {
  const filters = FiltersSchema.parse(searchParams) // Validated + defaulted
  const items = await getItems(filters) // All values are guaranteed valid
}

// ✅ Use safeParse when you want to handle errors gracefully
const result = UserSchema.safeParse(json)
if (!result.success) {
  console.error('API returned unexpected shape:', result.error.flatten())
  return NextResponse.json({ error: 'Upstream API error' }, { status: 502 })
}
const user = result.data // Fully typed

# Find type assertions on external data
grep -rn "as \w\+\b" src/ --include="*.ts" --include="*.tsx" | grep -E "json\(\)|formData|searchParams|params|\.body|JSON\.parse"
# Find double assertions (almost always wrong)
grep -rn "as unknown as" src/ --include="*.ts" --include="*.tsx"