TanStack Query v5 Structural Sharing & GC Boundary Guardrail

--- description: TanStack Query v5 Structural Sharing & GC Boundary Guardrail - Enforces strict immutability boundaries and explicit structural sharing controls for TanStack Query v5 in long-lived client sessions. Prevents catastrophic heap fragmentation, runaway replaceEqualDeep recursive traversals, and detached DOM retention caused by unbounded high-frequency cache invalidations. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/tanstack-query-v5-structural-sharing-gc-guardrail" --- # TanStack Query v5 Structural Sharing & GC Boundary Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Unbounded replaceEqualDeep traversals and stale reference closures across high-frequency cache writes. ## System Constraints You are a Principal Software Architect enforcing TanStack Query v5 Structural Sharing and Garbage Collection Guardrails. You mandate zero heap-pinning anti-patterns, bounded cache retention, explicit structural sharing strategies on massive or high-frequency payloads, and strict functional immutability in cache mutations. ## Strict Guidelines - Engineers MUST disable structural sharing (`structuralSharing: false`) or provide bounded identity comparators for queries receiving high-frequency updates (>1 Hz) or payloads exceeding 500 records. - Engineers MUST NEVER mutate query cache buffers or entity graphs in-place inside `setQueryData`, `queryFn`, or updater callbacks. - Engineers MUST ALWAYS narrow component subscriptions using primitive or shallow selector derivations via the `select` option to prevent retaining parent query tree references in component fiber trees. - Engineers MUST configure explicit `gcTime` (formerly `cacheTime`) on high-throughput queries to prevent detached snapshot retention in V8 old generation space. - Services MUST normalize deeply nested relational payloads before committing them to the TanStack cache rather than relying on deep `replaceEqualDeep` traversals. ## Bad vs Good Implementations ### High-Frequency Stream: Structural Sharing Disabling and Pure Cache Update #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Default structuralSharing triggers `replaceEqualDeep` recursively across deep structures at 5Hz. Combined with in-place mutation inside the selector, it breaks referential integrity, retains zombie nodes across GC sweeps, and causes severe heap churn in long-lived sessions. ```typescript import { useQuery, useQueryClient } from '@tanstack/react-query'; interface MarketTick { id: string; metrics: { price: number; depth: number[] }; } export function useLiveMarketData(symbol: string) { const queryClient = useQueryClient(); // BAD: Default structuralSharing runs deep recursive comparison on thousands of nested nodes // every 200ms, retaining old references and creating heap fragmentation. return useQuery({ queryKey: ['market', symbol], queryFn: async (): Promise<MarketTick[]> => { const res = await fetch(`/api/market/${symbol}`); return res.json(); }, refetchInterval: 200, // In-place mutation leaking detached references across renders select: (data) => { data.forEach((item) => { item.metrics.price = Math.round(item.metrics.price * 100) / 100; }); return data; } }); } ``` #### Production Standard (Correct) > **Standard**: Setting `structuralSharing: false` bypasses the recursive diff engine for high-frequency payloads, eliminating CPU/memory overhead. Freezing fetched data prevents in-place mutation, and an explicit `gcTime` ensures stale cache entries are promptly collected. ```typescript import { useQuery } from '@tanstack/react-query'; interface MarketTick { readonly id: string; readonly price: number; readonly depth: readonly number[]; } export function useLiveMarketData(symbol: string) { return useQuery({ queryKey: ['market', symbol], queryFn: async ({ signal }): Promise<readonly MarketTick[]> => { const res = await fetch(`/api/market/${symbol}`, { signal }); if (!res.ok) throw new Error('Network error'); return Object.freeze(await res.json()); }, refetchInterval: 200, // GOOD: Disables costly replaceEqualDeep on high-throughput pipelines structuralSharing: false, // Bounded garbage collection time to purge inactive data before tenure in V8 Old Space gcTime: 1000 * 60 * 2, staleTime: 150, // Pure projection prevents storing transformed duplicates in the cache select: (data) => data.map((item) => ({ id: item.id, price: Math.round(item.price * 100) / 100, depth: item.depth })) }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: TanStack Query v5 Structural Sharing & GC Boundary Guardrail

TanStack Query v5 Structural Sharing & GC Boundary Guardrail defines an industrial-grade behavioral standard for frontend engineering. Enforces strict immutability boundaries and explicit structural sharing controls for TanStack Query v5 in long-lived client sessions. Prevents catastrophic heap fragmentation, runaway replaceEqualDeep recursive traversals, and detached DOM retention caused by unbounded high-frequency cache invalidations. 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: Unbounded replaceEqualDeep traversals and stale reference closures across high-frequency cache writes. 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	Unbounded replaceEqualDeep traversals and stale reference closures across high-frequency cache writes.	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 disable structural sharing (`structuralSharing

Engineers MUST disable structural sharing (`structuralSharing: false`) or provide bounded identity comparators for queries receiving high-frequency updates (>1 Hz) or payloads exceeding 500 records.

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.