Svelte 5 Runes Async Effect Teardown and State Mirroring Invariant

--- description: Svelte 5 Runes Async Effect Teardown and State Mirroring Invariant - Enforces deterministic signal disposal and prevents micro-memory leaks during async transitions in Svelte 5. Prohibits direct async executor callbacks in $effect runes and mandates AbortController-backed synchronous teardowns with cancellation checks before state mutation. globs: src/**/*.{svelte,svelte.ts,ts} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/svelte5-async-effect-teardown-state-mirroring-invariant" --- # Svelte 5 Runes Async Effect Teardown and State Mirroring Invariant > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Direct Async $effect Callbacks Swallowing Teardown Functions and Causing Out-of-Order State Mutations ## System Constraints You are a Principal Engineer enforcing Svelte 5 Runes Async Effect Teardown & State Mirroring Invariants. Mandate synchronous return of cleanup functions in $effect runes, strict encapsulation of async execution, deterministic AbortController teardowns, and verification of cancellation flags prior to any $state mutation across async boundaries. ## Strict Guidelines - Engineers MUST ALWAYS return a synchronous teardown function from `$effect` when triggering asynchronous workflows or event subscriptions. - Engineers MUST NOT pass an `async` function directly to `$effect`, because an async function returns a `Promise`, completely bypassing Svelte's teardown registry. - Engineers MUST instantiate an `AbortController` inside the `$effect` scope and pass its `signal` to all cancellable asynchronous calls (e.g., fetch, stream listeners). - Engineers MUST guard all mutations to `$state` runes across an `await` boundary by verifying that the active signal has not been aborted (`if (controller.signal.aborted) return;`). - Engineers MUST NOT replicate upstream reactive values into local `$state` within an `$effect`; derive state declaratively using `$derived` or `$derived.by` instead. - Components NEVER execute side-effects or dispatch mutable state modifications within `$derived` or `$derived.by` runes. ## Bad vs Good Implementations ### Deterministic Async Teardown in Svelte 5 $effect #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Passing an async function to $effect returns a Promise instead of a teardown function. If userId changes rapidly, prior fetch operations cannot be cancelled, leading to race conditions where older requests overwrite newer ones and leaked micro-tasks retain memory. ```typescript import { untrack } from 'svelte'; let userId = $state('usr_123'); let profile = $state<UserProfile | null>(null); let error = $state<string | null>(null); // ANTI-PATTERN: Direct async effect callback swallows teardown function. // Rapid updates cause out-of-order resolution and dangling async memory leaks. $effect(async () => { try { const response = await fetch(`/api/users/${userId}`); profile = await response.json(); // Race condition: stale resolution overrides fresh state } catch (err: unknown) { error = (err as Error).message; } }); ``` #### Production Standard (Correct) > **Standard**: The effect returns a synchronous cleanup function invoking controller.abort(). Async execution is isolated within an inner function, and state updates check `signal.aborted` before mutating runes, guaranteeing race-condition-free UI transitions and zero memory leaks. ```typescript import { untrack } from 'svelte'; let userId = $state('usr_123'); let profile = $state<UserProfile | null>(null); let error = $state<string | null>(null); let isLoading = $state(false); // CORRECT: Synchronous effect returning a deterministic AbortController teardown. $effect(() => { const currentId = userId; const controller = new AbortController(); const { signal } = controller; isLoading = true; error = null; async function executeFetch(): Promise<void> { try { const response = await fetch(`/api/users/${currentId}`, { signal }); if (!response.ok) throw new Error(`HTTP error: ${response.status}`); const data: UserProfile = await response.json(); if (!signal.aborted) { profile = data; isLoading = false; } } catch (err: unknown) { if (!signal.aborted) { error = err instanceof Error ? err.message : 'Unknown error'; isLoading = false; } } } void executeFetch(); return () => { controller.abort(); }; }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Runes Async Effect Teardown and State Mirroring Invariant

Svelte 5 Runes Async Effect Teardown and State Mirroring Invariant defines an industrial-grade behavioral standard for frontend engineering. Enforces deterministic signal disposal and prevents micro-memory leaks during async transitions in Svelte 5. Prohibits direct async executor callbacks in $effect runes and mandates AbortController-backed synchronous teardowns with cancellation checks before state mutation. 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: Direct Async $effect Callbacks Swallowing Teardown Functions and Causing Out-of-Order State Mutations 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	Direct Async $effect Callbacks Swallowing Teardown Functions and Causing Out-of-Order State Mutations	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 return a synchronous teardown function from `$effect` when triggering asynchronous workflows or event subscriptions.

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.