Svelte 5 $effect Cleanup and Asynchronous Task Cancellation Boundary

--- description: Svelte 5 $effect Cleanup and Asynchronous Task Cancellation Boundary - Enforces synchronous teardown return contracts and deterministic AbortController cancellation inside Svelte 5 $effect runes. Prevents floating asynchronous microtasks from mutating unmounted component state or causing cross-render race conditions by binding all async execution lifecycles to reactive scope disposal boundaries. globs: src/**/*.svelte, src/**/*.svelte.ts, src/**/*.svelte.js, src/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/svelte-5-effect-async-cancellation-boundary" --- # Svelte 5 $effect Cleanup and Asynchronous Task Cancellation Boundary > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Async $effect Function Signatures and Unbound Microtask State Mutation ## System Constraints You are a Principal Software Architect enforcing rigorous Svelte 5 concurrency and reactivity standards. You must strictly forbid passing async functions directly to $effect, $effect.pre, or untracked effect scopes, because Promises discard Svelte's synchronous cleanup function return contract. You must mandate deterministic teardown boundaries using AbortController and synchronous scope cleanup to prevent zombie microtasks and state corruption. ## Strict Guidelines - Engineers MUST NEVER declare the top-level callback of $effect() or $effect.pre() as 'async' because returning a Promise discards the reactive teardown function. - Engineers MUST instantiate an AbortController synchronously inside the $effect callback and return an explicit cleanup closure invoking controller.abort(). - Asynchronous tasks inside $effect MUST capture the AbortSignal and verify signal.aborted prior to committing mutations to reactive $state runes. - Code SHOULD gracefully catch and suppress DOMException 'AbortError' instances while rethrowing or handling unexpected network and parsing failures. - Services invoked within reactive effects MUST accept an AbortSignal parameter as part of their cancellation contract. - Components NEVER execute floating detached promises within an effect scope without binding them to an enclosing cancellation token or explicit disposal lifecycle. ## Bad vs Good Implementations ### Async $effect Anti-Pattern vs Deterministic AbortController Boundary #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring the $effect callback as async causes it to return a Promise instead of a synchronous teardown function. Svelte 5 discards returned Promises, making cleanup impossible and permitting stale responses from prior effect runs to overwrite current state. ```typescript import { untrack } from 'svelte'; let userId = $state('usr_123'); let profile = $state<UserProfile | null>(null); let error = $state<string | null>(null); // ANTI-PATTERN: Async callback returns a Promise<void>. Svelte 5 ignores the returned // Promise, meaning the returned cleanup function is never executed by runtime disposal. // Outdated microtasks resolve out-of-order and corrupt current state (Race Condition). $effect(async () => { try { const response = await fetch(`/api/users/${userId}`); profile = await response.json(); } catch (err: any) { error = err.message; } return () => { // DEAD CODE: Never executed by Svelte 5 reactive effect lifecycle! console.log('Cleanup invoked'); }; }); ``` #### Production Standard (Correct) > **Standard**: The $effect callback remains strictly synchronous, returning a deterministic disposal function. The AbortController aborts active I/O on re-runs or unmounts, and signal.aborted guards prevent zombie microtasks from mutating reactive state. ```typescript let userId = $state('usr_123'); let profile = $state<UserProfile | null>(null); let error = $state<string | null>(null); // PRODUCTION INVARIANT: Synchronous effect callback creates cancellation token // and returns an immediate, deterministic cleanup closure. $effect(() => { const controller = new AbortController(); const { signal } = controller; const currentId = userId; async function loadProfile(id: string) { try { const response = await fetch(`/api/users/${id}`, { signal }); if (!response.ok) { throw new Error(`Failed to load profile: ${response.statusText}`); } const data = await response.json(); // Guard state mutation against cancellation boundary if (!signal.aborted) { profile = data; error = null; } } catch (err: unknown) { if (err instanceof DOMException && err.name === 'AbortError') { return; // Scope disposed or superseded; suppress cancellation error } if (!signal.aborted) { error = err instanceof Error ? err.message : 'Unknown error'; } } } loadProfile(currentId); return () => { controller.abort(); }; }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 $effect Cleanup and Asynchronous Task Cancellation Boundary

Svelte 5 $effect Cleanup and Asynchronous Task Cancellation Boundary defines an industrial-grade behavioral standard for frontend engineering. Enforces synchronous teardown return contracts and deterministic AbortController cancellation inside Svelte 5 $effect runes. Prevents floating asynchronous microtasks from mutating unmounted component state or causing cross-render race conditions by binding all async execution lifecycles to reactive scope disposal boundaries. 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: Async $effect Function Signatures and Unbound Microtask State Mutation 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	Async $effect Function Signatures and Unbound Microtask State Mutation	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 NEVER declare the top-level callback of $effect() or $effect.pre() as 'async' because returning a Promise discards the reactive teardown function.

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.