Svelte 5 Runes Async Derived Dependency Isolation Invariant

--- description: Svelte 5 Runes Async Derived Dependency Isolation Invariant - Svelte 5's $derived rune must strictly remain synchronous and free of untracked post-await dependency reads to prevent asynchronous dependency leakage and cascading reactive loops. Asynchronous state derivation must explicitly isolate its trigger dependencies, encapsulate pending promises through un-tracked invocations or dedicated resource state holders, and prevent unawaited Promise resolutions from executing downstream effect loops. globs: src/**/*.{svelte,svelte.ts,svelte.js,ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/svelte-5-async-derived-dependency-isolation-invariant" --- # Svelte 5 Runes Async Derived Dependency Isolation Invariant > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Leaking Reactive Dependencies Across Asynchronous Execution Boundaries in Derived Runes ## System Constraints You are a Principal Engineer enforcing the Svelte 5 Runes Async Derived Dependency Isolation Invariant. Svelte 5 introduces fine-grained reactive runes ($state, $derived, $effect) driven by synchronous dependency tracking. Asynchronous derived state creates severe architectural flaws when async/await sequences inadvertently expand the reactive tracking scope or trigger race conditions through unsequenced microtask resolutions. You must mandate strict isolation between reactive tracking phases and asynchronous side effects, ensuring $derived is kept purely synchronous and async resolution boundaries are encapsulated cleanly with cancellation or sequence identification. ## Strict Guidelines - Engineers MUST ALWAYS keep $derived and $derived.by expressions completely synchronous, using explicit reactive triggers instead of unawaited Promise payloads inside derived scopes. - Engineers MUST NOT read mutable reactive signals ($state) after an 'await' boundary within an asynchronous context triggered by reactivity, as this can orphan dependency tracking or cause stale closure captures. - Engineers MUST encapsulate asynchronous derivation logic into dedicated classes or composable functions using explicit tracking primitives (e.g., untrack) combined with $state storage for resolution values, pending flags, and error states. - Components NEVER use inline asynchronous IIFEs inside $derived.by to fetch or resolve data; engineers must model asynchronous transitions via Svelte 5 resource patterns, deterministic sequence counters, or abortable async loaders. - Engineers MUST pass explicit, synchronously-read snapshot arguments into asynchronous worker functions rather than referencing ambient $state across asynchronous ticks. ## Bad vs Good Implementations ### Async Data Resolution: Inline Async Derived vs Isolated Encapsulated Resource #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: In Svelte 5, $derived.by expectations are synchronous. Returning a Promise creates an unhandled promise pipeline where reads after the first 'await' occur outside the synchronous tracking phase. Rapid changes to 'query' trigger concurrent fetches with zero cancellation, resulting in out-of-order resolution bugs. ```typescript import { state, derived } from 'svelte'; // ANTI-PATTERN: Async IIFE in $derived.by leads to uncollected dependencies, // post-await reads leaking reactivity, and non-deterministic race conditions. let query = $state(''); let filter = $state('active'); const searchResults = $derived.by(async () => { if (!query) return []; // First tick tracked query synchronously const res = await fetch(`/api/search?q=${query}`); // Post-await read of 'filter' is NOT reliably tracked or can trigger // unexpected cascading execution if accessed concurrently const json = await res.json(); return json.filter((item: any) => item.status === filter); }); ``` #### Production Standard (Correct) > **Standard**: This pattern guarantees dependency isolation. $effect synchronously tracks query and filter changes. Untrack prevents mutation of state variables from generating self-loops. Sequence counter and AbortController ensure that stale async ticks cannot overwrite newer state. ```typescript import { untrack } from 'svelte'; // PRODUCTION FIX: Purely synchronous parameter extraction paired with // deterministic sequence tracking and isolated async fetching. class AsyncResource<TParam, TResult> { value = $state<TResult | null>(null); isLoading = $state(false); error = $state<Error | null>(null); private sequence = 0; constructor( private paramsFn: () => TParam, private loader: (params: TParam, signal: AbortSignal) => Promise<TResult> ) { let controller: AbortController | null = null; $effect(() => { // Synchronously track only declared parameters const params = this.paramsFn(); const currentSeq = ++this.sequence; if (controller) controller.abort(); controller = new AbortController(); const signal = controller.signal; untrack(() => { this.isLoading = true; this.error = null; }); this.loader(params, signal) .then((data) => { if (currentSeq === this.sequence) { this.value = data; this.isLoading = false; } }) .catch((err) => { if (currentSeq === this.sequence && err.name !== 'AbortError') { this.error = err instanceof Error ? err : new Error(String(err)); this.isLoading = false; } }); return () => controller?.abort(); }); } } let query = $state(''); let filter = $state('active'); const searchResource = new AsyncResource( () => ({ query, filter }), async ({ query, filter }, signal) => { if (!query) return []; const res = await fetch(`/api/search?q=${encodeURIComponent(query)}`, { signal }); const json = await res.json(); return json.filter((item: { status: string }) => item.status === filter); } ); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Runes Async Derived Dependency Isolation Invariant

Svelte 5 Runes Async Derived Dependency Isolation Invariant defines an industrial-grade behavioral standard for frontend engineering. Svelte 5's $derived rune must strictly remain synchronous and free of untracked post-await dependency reads to prevent asynchronous dependency leakage and cascading reactive loops. Asynchronous state derivation must explicitly isolate its trigger dependencies, encapsulate pending promises through un-tracked invocations or dedicated resource state holders, and prevent unawaited Promise resolutions from executing downstream effect loops. 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: Leaking Reactive Dependencies Across Asynchronous Execution Boundaries in Derived Runes 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	Leaking Reactive Dependencies Across Asynchronous Execution Boundaries in Derived Runes	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 keep $derived and $derived.by expressions completely synchronous, using explicit reactive triggers instead of unawaited Promise payloads inside derived scopes.

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.