type-safety-validation（类型安全验证）

Type Safety & Validation

Overview

When to use this skill:

• Building type-safe APIs (REST, RPC, GraphQL)
• Validating user input and external data
• Ensuring database queries are type-safe
• Creating end-to-end typed full-stack applications
• Implementing strict validation rules

Core Stack Quick Reference

Zod Essentials

import { z } from 'zod'

// Define schema
const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  age: z.number().int().positive().max(120),
  role: z.enum(['admin', 'user', 'guest']),
  createdAt: z.date().default(() => new Date())
})

// Infer TypeScript type
type User = z.infer<typeof UserSchema>

// Validate with error handling
const result = UserSchema.safeParse(data)
if (result.success) {
  const user: User = result.data
} else {
  console.error(result.error.issues)
}

See: references/zod-patterns.md for transforms, refinements, discriminated unions, and recursive types.

tRPC Essentials

import { initTRPC } from '@trpc/server'
import { z } from 'zod'

const t = initTRPC.create()

export const appRouter = t.router({
  getUser: t.procedure
    .input(z.object({ id: z.string() }))
    .query(async ({ input }) => {
      return await db.user.findUnique({ where: { id: input.id } })
    }),

  createUser: t.procedure
    .input(z.object({ email: z.string().email(), name: z.string() }))
    .mutation(async ({ input }) => {
      return await db.user.create({ data: input })
    })
})

export type AppRouter = typeof appRouter

See: references/trpc-setup.md for middleware, authentication, React integration, and error handling.

Exhaustive Type Checking

// ALWAYS use assertNever for compile-time exhaustiveness
function assertNever(x: never): never {
  throw new Error("Unexpected value: " + x)
}

type Status = 'pending' | 'running' | 'completed' | 'failed'

function getStatusColor(status: Status): string {
  switch (status) {
    case 'pending': return 'gray'
    case 'running': return 'blue'
    case 'completed': return 'green'
    case 'failed': return 'red'
    default: return assertNever(status) // Compile-time check!
  }
}

// Exhaustive record mapping
const statusColors = {
  pending: 'gray',
  running: 'blue',
  completed: 'green',
  failed: 'red',
} as const satisfies Record<Status, string>

See: references/typescript-advanced.md for handler objects, type guards, and anti-patterns.

Branded Types

TypeScript (with Zod):

const UserId = z.string().uuid().brand<'UserId'>()
const AnalysisId = z.string().uuid().brand<'AnalysisId'>()

type UserId = z.infer<typeof UserId>
type AnalysisId = z.infer<typeof AnalysisId>

function deleteAnalysis(id: AnalysisId): void { ... }
deleteAnalysis(userId) // Error: UserId not assignable to AnalysisId

Python (with NewType):

from typing import NewType
from uuid import UUID

AnalysisID = NewType("AnalysisID", UUID)
ArtifactID = NewType("ArtifactID", UUID)

def delete_analysis(id: AnalysisID) -> None: ...
delete_analysis(artifact_id)  # Error with mypy/ty

See: references/typescript-advanced.md for factory patterns and pure TypeScript branding.

Python Type Safety with Ty

from typing import cast

# Type-safe extraction from untyped dict
result = {"findings": {...}, "confidence_score": 0.85}

findings_to_save: dict[str, object] | None = (
    cast("dict[str, object]", result.get("findings"))
    if isinstance(result.get("findings"), dict) else None
)
confidence_to_save: float | None = (
    float(result.get("confidence_score"))
    if isinstance(result.get("confidence_score"), (int, float)) else None
)

See: references/ty-type-checker-patterns.md for mixed numeric handling and nested dict extraction.

References

Best Practices

Validation

• Validate at boundaries (API inputs, form submissions, external data)
• Use .safeParse() to handle errors gracefully
• Use branded types for IDs (z.string().brand<'UserId'>())

Type Safety

• Enable strict: true in tsconfig.json
• Use noUncheckedIndexedAccess for safer array access
• Prefer unknown over any
• Exhaustive switches: Always use assertNever in default case
• Exhaustive records: Use satisfies Record<UnionType, Value>

Performance

• Reuse schemas (don't create inline in hot paths)
• Use .parse() for known-good data (faster than .safeParse())
• Use tRPC batching for multiple queries

Resources

• Zod Documentation
• tRPC Documentation
• Prisma Documentation
• TypeScript Handbook

Related Skills

• input-validation - Security-focused validation and sanitization patterns
• api-design-framework - REST API design with type-safe contracts
• fastapi-advanced - Python backend with Pydantic type validation

Key Decisions

Skill Version: 1.2.0 Last Updated: 2025-12-27 Maintained by: AI Agent Hub Team

Capability Details

zod-schemas

Keywords: zod, schema, validation, parse, safeParse, infer, refine, transform Solves:

• How do I validate input with Zod?
• Create runtime validation schema
• Infer TypeScript types from Zod
• Transform and refine data with Zod

exhaustive-types

Keywords: exhaustive, assertNever, never assertion, switch exhaustive, compile-time exhaustiveness Solves:

• How do I make switch statements exhaustive?
• Compile-time check for missing union cases
• assertNever pattern for TypeScript

branded-types

Keywords: branded type, type branding, nominal type, NewType, brand, distinct types, id types Solves:

• How do I prevent mixing different ID types?
• Branded types with Zod
• Python NewType for type safety

trpc

Keywords: trpc, type-safe api, procedure, router, mutation, query, middleware Solves:

• How do I set up tRPC?
• Type-safe API calls
• tRPC with React Query

prisma-types

Keywords: prisma, orm, generated types, model, client, payload Solves:

• How do I use Prisma types?
• Type-safe database queries

typescript-5-features

Keywords: typescript 5, const parameters, satisfies, decorators, template literals Solves:

• Use TypeScript 5.x features
• Const type parameters
• Satisfies operator

ty-type-checker

Keywords: ty, rust type checker, strict typing, isinstance, cast, type narrowing Solves:

• How do I make ty type checker pass?
• Extract values from untyped dicts safely
• Type narrowing with isinstance checks