TypeScript satisfies Operator vs Type Assertion Casting Standard

--- description: TypeScript satisfies Operator vs Type Assertion Casting Standard - Production TypeScript typing standard. Mandates using the 'satisfies' operator for configuration objects, themes, and route definitions to validate schema conformity while preserving exact literal types, strictly forbidding 'as Type' type assertions that mask missing properties. globs: **/*.ts, **/*.tsx, **/config/**/*.ts alwaysApply: false verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/typescript-satisfies-operator-narrowing" --- # TypeScript satisfies Operator vs Type Assertion Casting Standard > **Severity**: HIGH | **Category**: frontend > **Anti-Pattern Warning**: AI uses 'as ConfigType' or ': Record<string, any>' annotations, blowing away specific literal keys and breaking autocompletion and type narrowing. ## System Constraints You are a Principal TypeScript Architect. NEVER use type assertion casting (as Config) or widened type annotations (: Record<string, Route>) on configuration dictionaries. Always use the TypeScript 'satisfies' operator to guarantee schema adherence while retaining precise literal types and exact keys. ## Strict Guidelines - MUST use 'satisfies' when defining design tokens, route maps, and feature flags: const config = { ... } satisfies AppConfig. - MUST NOT use 'as Type' to silence compiler errors on configuration dictionaries (type assertions bypass excess property checks). - SHOULD combine 'as const satisfies Schema' when tuple lengths or string literal unions must be preserved immutably. - MUST verify that autocompletion retains exact object keys after validation rather than degrading to string indexes. - SHOULD use const type parameters (const T) in generic factory functions for zero-annotation inference. ## Bad vs Good Implementations ### Validating Schema without Widening via satisfies Operator #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Explicitly typing routes as Record<string, ...> widens literal property keys to general strings. Autocompletion is destroyed and typos are not detected at compile time. ```typescript // FATAL: Type annotation widens property keys and disables typos checks type RouteConfig = Record<string, { path: string; secure: boolean }>; // Widens routes to Record<string, ...>! routes.hommme (typo) is permitted by TS! const routes: RouteConfig = { home: { path: '/', secure: false }, dashboard: { path: '/dashboard', secure: true }, }; // TypeScript cannot catch typos because keys were widened to generic string console.log(routes.profile.path); // Runtime Crash: Cannot read properties of undefined ``` #### Production Standard (Correct) > **Standard**: The satisfies operator validates that every item adheres to RouteDefinition while preserving exact object shape and literal values. Compile-time typos trigger immediate errors. ```typescript type RouteDefinition = { path: string; secure: boolean }; type ValidRouteMap = Record<string, RouteDefinition>; // Type-checked against ValidRouteMap while PRESERVING exact keys ('home' | 'dashboard') const routes = { home: { path: '/', secure: false }, dashboard: { path: '/dashboard', secure: true }, } as const satisfies ValidRouteMap; // 1. Full autocomplete for 'home' and 'dashboard' // 2. Exact literal path type: '/' instead of string // 3. Typo prevention: routes.profile triggers compile-time error Property 'profile' does not exist const homePath = routes.home.path; // Type is exactly '/' ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: TypeScript satisfies Operator vs Type Assertion Casting Standard

TypeScript satisfies Operator vs Type Assertion Casting Standard defines an industrial-grade behavioral standard for frontend engineering. Production TypeScript typing standard. Mandates using the 'satisfies' operator for configuration objects, themes, and route definitions to validate schema conformity while preserving exact literal types, strictly forbidding 'as Type' type assertions that mask missing properties. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: AI uses 'as ConfigType' or ': Record<string, any>' annotations, blowing away specific literal keys and breaking autocompletion and type narrowing. Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	AI uses 'as ConfigType' or ': Record<string, any>' annotations, blowing away specific literal keys and breaking autocompletion and type narrowing.	High	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

MUST use 'satisfies' when defining design tokens, route maps, and feature flags

MUST use 'satisfies' when defining design tokens, route maps, and feature flags: const config = { ... } satisfies AppConfig.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.