React 19 Action Transition AbortSignal Propagation Invariant

--- description: React 19 Action Transition AbortSignal Propagation Invariant - Enforces deterministic lifecycle binding between React 19 Action Transitions (`useActionState`, `startTransition`) and underlying I/O tasks via explicit AbortSignal propagation. Guarantees that pending async microtasks, fetch payloads, and optimistic state reconciliations immediately terminate upon component unmount, route transition, or action preemption, preventing memory leaks, network contention, and stale cache hydration. globs: src/**/*.{ts,tsx}, app/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-19-action-transition-abort-signal-propagation-invariant" --- # React 19 Action Transition AbortSignal Propagation Invariant > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Unlinked Async Action Microtasks Causing Post-Unmount Network Contention and Stale State Rehydration ## System Constraints You are a Principal Frontend Architect enforcing strict concurrency invariants in React 19. All async operations executed within React 19 Action Transitions (`startTransition`, `useActionState`, or `<form action={...}>`) MUST bind directly to an explicit `AbortSignal`. You must prevent orphaned network tasks and lingering promise microtasks from completing after navigation or component teardown. ## Strict Guidelines - Engineers MUST ALWAYS instantiate or inject an `AbortController` linked to the component/action lifecycle and pass its `signal` directly to all nested fetch requests, third-party clients, and async primitives. - Engineers MUST NOT invoke fire-and-forget Promises or raw async functions within `startTransition` or `useActionState` without wiring an active `AbortSignal` for cancellation. - Code MUST handle `AbortError` or `DOMException.ABORT_ERR` explicitly within the action handler, treating aborted transitions as non-erroneous terminal states rather than unhandled rejections. - Components using custom transition wrappers or manual `startTransition` invocations MUST cancel previous in-flight controllers via `controller.abort()` when re-triggered to prevent race conditions and out-of-order state settlement. - Optimistic updates executed alongside Action Transitions MUST be scoped to the transition's active lifetime and must roll back cleanly without triggering secondary state writes if the transition is aborted. ## Bad vs Good Implementations ### React 19 Action State with AbortSignal Lifecycle Invariant #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The async action does not pass or consume an AbortSignal. Client navigation or fast successive form submissions will leave rogue network calls in flight, leaking resources, consuming network buffers, and triggering unexpected reconciliation side effects. ```typescript import React, { useActionState } from 'react'; interface State { error: string | null; data: string | null; } // ANTI-PATTERN: Async action invoked without AbortSignal linkage. // If the user navigates away or submits rapidly, network requests continue in background, // causing buffer contention and attempting state updates on unmounted transition tree. async function updateProfileName(prevState: State, formData: FormData): Promise<State> { const name = formData.get('name') as string; try { const response = await fetch('/api/profile', { method: 'POST', body: JSON.stringify({ name }), headers: { 'Content-Type': 'application/json' }, }); const data = await response.json(); return { data: data.name, error: null }; } catch (err: unknown) { return { data: null, error: (err as Error).message }; } } export function ProfileForm() { const [state, formAction, isPending] = useActionState(updateProfileName, { error: null, data: null, }); return ( <form action={formAction}> <input name="name" defaultValue="" /> <button type="submit" disabled={isPending}>Save</button> {state.error && <p>{state.error}</p>} </form> ); } ``` #### Production Standard (Correct) > **Standard**: Maintains an active AbortController ref tied directly to transition execution and component unmounting. Previous in-flight transitions are canceled on subsequent submissions and navigation, and AbortErrors are caught safely, preventing network thrashing and state corruption. ```typescript import React, { useActionState, useEffect, useRef } from 'react'; interface State { error: string | null; data: string | null; } async function mutateProfileWithSignal( formData: FormData, signal: AbortSignal ): Promise<State> { const name = formData.get('name') as string; const response = await fetch('/api/profile', { method: 'POST', body: JSON.stringify({ name }), headers: { 'Content-Type': 'application/json' }, signal, }); if (!response.ok) { throw new Error(`Profile mutation failed: ${response.statusText}`); } const data = await response.json(); return { data: data.name, error: null }; } export function ProfileForm() { const abortControllerRef = useRef<AbortController | null>(null); useEffect(() => { return () => { abortControllerRef.current?.abort(); }; }, []); const [state, formAction, isPending] = useActionState( async (prevState: State, formData: FormData): Promise<State> => { abortControllerRef.current?.abort(); const controller = new AbortController(); abortControllerRef.current = controller; try { return await mutateProfileWithSignal(formData, controller.signal); } catch (err: unknown) { if (err instanceof DOMException && err.name === 'AbortError') { return prevState; } return { data: null, error: (err as Error).message }; } }, { error: null, data: null } ); return ( <form action={formAction}> <input name="name" defaultValue="" /> <button type="submit" disabled={isPending}>Save</button> {state.error && <p role="alert">{state.error}</p>} </form> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React 19 Action Transition AbortSignal Propagation Invariant

React 19 Action Transition AbortSignal Propagation Invariant defines an industrial-grade behavioral standard for frontend engineering. Enforces deterministic lifecycle binding between React 19 Action Transitions (`useActionState`, `startTransition`) and underlying I/O tasks via explicit AbortSignal propagation. Guarantees that pending async microtasks, fetch payloads, and optimistic state reconciliations immediately terminate upon component unmount, route transition, or action preemption, preventing memory leaks, network contention, and stale cache hydration. 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: Unlinked Async Action Microtasks Causing Post-Unmount Network Contention and Stale State Rehydration 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	Unlinked Async Action Microtasks Causing Post-Unmount Network Contention and Stale State Rehydration	Critical	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:

Engineers MUST ALWAYS instantiate or inject an `AbortController` linked to the component/action lifecycle and pass its `signal` directly to all nested fetch requests, third-party clients, and async primitives.

Engineers MUST ALWAYS instantiate or inject an `AbortController` linked to the component/action lifecycle and pass its `signal` directly to all nested fetch requests, third-party clients, and async primitives.

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.