fix(react): force invalidation on entry disposal (#559)

harlan-zw · web-flow · commit 4ee5eac76941 · 2025-07-04T16:26:18.000+10:00
diff --git a/packages/react/src/composables.ts b/packages/react/src/composables.ts
@@ -9,7 +9,7 @@ import type {
   UseScriptReturn,
   UseSeoMetaInput,
 } from 'unhead/types'
-import { useContext, useEffect, useState } from 'react'
+import { useContext, useEffect, useRef } from 'react'
 import { useHead as baseHead, useHeadSafe as baseHeadSafe, useSeoMeta as baseSeoMeta, useScript as baseUseScript } from 'unhead'
 import { UnheadContext } from './context'
 
@@ -24,17 +24,30 @@ export function useUnhead(): Unhead {
 
 function withSideEffects<T extends ActiveHeadEntry<any>>(input: any, options: any, fn: any): T {
   const unhead = options.head || useUnhead()
-  const [entry] = useState<T>(() => fn(unhead, input, options))
+  const entryRef = useRef<T | null>(null)
+
+  // Create entry only once, even in Strict Mode
+  if (!entryRef.current) {
+    entryRef.current = fn(unhead, input, options)
+  }
+
+  const entry = entryRef.current
+
+  // Patch entry when input changes
   useEffect(() => {
-    entry.patch(input)
-  }, [input])
+    entry?.patch(input)
+  }, [input, entry])
+
+  // Cleanup on unmount
   useEffect(() => {
     return () => {
-      // unmount
-      entry.dispose()
+      entry?.dispose()
+      // Clear ref so new entry is created on remount
+      entryRef.current = null
     }
-  }, [])
-  return entry
+  }, [entry])
+
+  return entry as T
 }
 
 export function useHead(input: UseHeadInput = {}, options: HeadEntryOptions = {}): ActiveHeadEntry<UseHeadInput> {
diff --git a/packages/unhead/src/types/head.ts b/packages/unhead/src/types/head.ts
@@ -175,6 +175,10 @@ export interface Unhead<Input = ResolvableHead> {
    * Resolve tags from head entries.
    */
   resolveTags: () => Promise<HeadTag[]>
+  /**
+   * Invalidate all entries and re-queue them for normalization.
+   */
+  invalidate: () => void
   /**
    * Exposed hooks for easier extension.
    */
diff --git a/packages/unhead/src/unhead.ts b/packages/unhead/src/unhead.ts
@@ -47,7 +47,7 @@ export function createUnhead<T = ResolvableHead>(resolvedOptions: CreateHeadOpti
 
   const entries: Map<number, HeadEntry<T>> = new Map()
   const plugins: Map<string, HeadPlugin> = new Map()
-  const normalizeQueue: number[] = []
+  const normalizeQueue = new Set<number>()
   const head: Unhead<T> = {
     _entryCount: 1, // 0 is reserved for internal use
     plugins,
@@ -68,12 +68,13 @@ export function createUnhead<T = ResolvableHead>(resolvedOptions: CreateHeadOpti
       const _: ActiveHeadEntry<T> = {
         _poll(rm = false) {
           head.dirty = true
-          !rm && normalizeQueue.push(_i)
+          !rm && normalizeQueue.add(_i)
           hooks.callHook('entries:updated', head)
         },
         dispose() {
           if (entries.delete(_i)) {
-            _._poll(true)
+            // Re-queue remaining entries for normalization after disposal
+            head.invalidate()
           }
         },
         // a patch is the same as creating a new entry, just a nice DX
@@ -95,8 +96,9 @@ export function createUnhead<T = ResolvableHead>(resolvedOptions: CreateHeadOpti
         entries: [...head.entries.values()],
       }
       await hooks.callHook('entries:resolve', ctx)
-      while (normalizeQueue.length) {
-        const i = normalizeQueue.shift()!
+      while (normalizeQueue.size) {
+        const i = normalizeQueue.values().next().value!
+        normalizeQueue.delete(i)
         const e = entries.get(i)
         if (e) {
           const normalizeCtx = {
@@ -213,6 +215,14 @@ export function createUnhead<T = ResolvableHead>(resolvedOptions: CreateHeadOpti
       }
       return finalTags
     },
+    invalidate() {
+      // Re-queue all current entries for normalization
+      for (const entry of entries.values()) {
+        normalizeQueue.add(entry._i)
+      }
+      head.dirty = true
+      hooks.callHook('entries:updated', head)
+    },
   }
   ;(resolvedOptions?.plugins || []).forEach(p => registerPlugin(head, p))
   head.hooks.callHook('init', head)
diff --git a/packages/unhead/test/break-normalize-queue.test.ts b/packages/unhead/test/break-normalize-queue.test.ts
@@ -0,0 +1,138 @@
+import { describe, expect, it } from 'vitest'
+import { createUnhead } from '../src'
+
+describe('break Normalize Queue - Replicate Bug', () => {
+  it('replicates the bug by following React pattern exactly', async () => {
+    // First, let me revert the fix to test the original buggy behavior
+    const head = createUnhead({
+      init: [{ title: 'Init Title', meta: [{ name: 'description', content: 'Init description' }] }],
+    })
+
+    // Step 1: Initial state - init values should be normalized
+    let tags = await head.resolveTags()
+    expect(tags.find(t => t.tag === 'title')?.textContent).toBe('Init Title')
+
+    // Step 2: Component mounts - React creates entry via push()
+    const componentEntry = head.push({
+      title: 'Component Title',
+      meta: [{ name: 'description', content: 'Component description' }],
+    })
+
+    // Step 3: Component patches entry (React does this on every render/prop change)
+    componentEntry.patch({
+      title: 'Component Title',
+      meta: [{ name: 'description', content: 'Component description' }],
+    })
+
+    // Step 4: Resolve tags - component values should be active
+    tags = await head.resolveTags()
+    expect(tags.find(t => t.tag === 'title')?.textContent).toBe('Component Title')
+
+    // Step 5: Component unmounts - React calls dispose()
+    // This is where the bug happens: dispose() calls _._poll(true)
+    // which means !rm is false, so remaining entries don't get added to normalizeQueue
+    componentEntry.dispose()
+
+    // Step 6: The bug manifests here
+    // Without the fix, init entries won't be in normalizeQueue
+    // so they won't be normalized and their _tags might be stale
+    tags = await head.resolveTags()
+
+    // This should pass but may fail with the original buggy code
+    expect(tags.find(t => t.tag === 'title')?.textContent).toBe('Init Title')
+    expect(tags.find(t => t.tag === 'meta' && t.props.name === 'description')?.props.content).toBe('Init description')
+  })
+
+  it('breaks the normalize queue by examining internal state', async () => {
+    const head = createUnhead({
+      init: [{ title: 'Init Title' }],
+    })
+
+    // Get reference to the init entry to examine its internal state
+    const initEntry = Array.from(head.entries.values())[0]
+
+    // First resolution - init entry gets normalized
+    await head.resolveTags()
+    const originalTags = initEntry._tags
+    expect(originalTags).toBeDefined()
+    expect(originalTags?.[0]?.textContent).toBe('Init Title')
+
+    // Add component entry
+    const componentEntry = head.push({ title: 'Component Title' })
+
+    // Resolve - both entries get normalized
+    await head.resolveTags()
+
+    // Dispose component entry
+    componentEntry.dispose()
+
+    // The bug: after disposal, if normalizeQueue is empty,
+    // init entry won't be re-normalized even if its _tags are stale
+
+    // Let's check if init entry is in the normalize queue after disposal
+    // We can't access normalizeQueue directly, but we can infer by checking
+    // if the init entry gets re-normalized
+
+    // Force a scenario where init entry needs re-normalization
+    // by modifying its input directly (simulating what might happen in complex scenarios)
+    const tags = await head.resolveTags()
+
+    // If the bug exists, this might fail because init entry didn't get normalized
+    expect(tags.find(t => t.tag === 'title')?.textContent).toBe('Init Title')
+  })
+
+  it('exposes the bug through normalize queue manipulation', async () => {
+    const head = createUnhead({
+      init: [{ title: 'Init Title' }],
+    })
+
+    // Create a scenario where the normalize queue state matters
+
+    // Step 1: Add component entry and resolve
+    const componentEntry = head.push({ title: 'Component Title' })
+    await head.resolveTags() // This processes and clears the normalize queue
+
+    // Step 2: Manually trigger a state that requires re-normalization
+    // In a real scenario, this might happen due to plugins or other factors
+    const initEntry = Array.from(head.entries.values())[0]
+
+    // Clear the init entry's _tags to simulate needing re-normalization
+    delete initEntry._tags
+
+    // Step 3: Dispose component entry
+    componentEntry.dispose()
+
+    // Step 4: The bug - if dispose() doesn't add remaining entries to normalizeQueue,
+    // the init entry won't be normalized because its _tags is undefined
+    const tags = await head.resolveTags()
+
+    // This should work but might fail if normalize queue bug exists
+    expect(tags.find(t => t.tag === 'title')?.textContent).toBe('Init Title')
+  })
+
+  it('replicates React strict mode double disposal pattern', async () => {
+    const head = createUnhead({
+      init: [{ title: 'Init Title' }],
+    })
+
+    // React Strict Mode pattern: mount → unmount → mount → unmount
+
+    // First mount
+    const entry1 = head.push({ title: 'Component Title 1' })
+    await head.resolveTags()
+
+    // First unmount (Strict Mode)
+    entry1.dispose()
+
+    // Second mount (Strict Mode remount)
+    const entry2 = head.push({ title: 'Component Title 2' })
+    await head.resolveTags()
+
+    // Second unmount (actual unmount)
+    entry2.dispose()
+
+    // Multiple disposals might expose the normalize queue bug
+    const tags = await head.resolveTags()
+    expect(tags.find(t => t.tag === 'title')?.textContent).toBe('Init Title')
+  })
+})
diff --git a/packages/unhead/test/invalidate.test.ts b/packages/unhead/test/invalidate.test.ts
@@ -0,0 +1,82 @@
+import { describe, expect, it } from 'vitest'
+import { createUnhead } from '../src'
+
+describe('invalidate Function', () => {
+  it('should re-queue all entries for normalization', async () => {
+    const head = createUnhead({
+      init: [{ title: 'Init Title' }],
+    })
+
+    // Add some entries
+    head.push({ title: 'Entry 1' })
+    head.push({ title: 'Entry 2' })
+
+    // Resolve tags initially
+    let tags = await head.resolveTags()
+    expect(tags.find(t => t.tag === 'title')?.textContent).toBe('Entry 2')
+
+    // Get references to entries to examine their state
+    const initEntry = Array.from(head.entries.values()).find(e => e.input.title === 'Init Title')!
+    const entry1Ref = Array.from(head.entries.values()).find(e => e.input.title === 'Entry 1')!
+    const entry2Ref = Array.from(head.entries.values()).find(e => e.input.title === 'Entry 2')!
+
+    // Clear all _tags to simulate a state that needs re-normalization
+    delete initEntry._tags
+    delete entry1Ref._tags
+    delete entry2Ref._tags
+
+    // Call invalidate to re-queue all entries
+    head.invalidate()
+
+    // Resolve tags - all entries should be re-normalized
+    tags = await head.resolveTags()
+
+    // Should show Entry 2 (highest priority) and all entries should have their _tags restored
+    expect(tags.find(t => t.tag === 'title')?.textContent).toBe('Entry 2')
+    expect(initEntry._tags).toBeDefined()
+    expect(entry1Ref._tags).toBeDefined()
+    expect(entry2Ref._tags).toBeDefined()
+  })
+
+  it('should work with Set-based normalize queue without duplicates', async () => {
+    const head = createUnhead({
+      init: [{ title: 'Init Title' }],
+    })
+
+    const entry = head.push({ title: 'Test Entry' })
+
+    // Call invalidate multiple times
+    head.invalidate()
+    head.invalidate()
+    head.invalidate()
+
+    // Even with multiple invalidate calls, each entry should only be processed once
+    // (this tests the Set deduplication behavior)
+    const tags = await head.resolveTags()
+    expect(tags.find(t => t.tag === 'title')?.textContent).toBe('Test Entry')
+  })
+
+  it('should be useful after dispose operations', async () => {
+    const head = createUnhead({
+      init: [{ title: 'Init Title' }],
+    })
+
+    const entry = head.push({ title: 'Component Title' })
+
+    // Resolve initially
+    let tags = await head.resolveTags()
+    expect(tags.find(t => t.tag === 'title')?.textContent).toBe('Component Title')
+
+    // Dispose entry (this internally calls invalidate)
+    entry.dispose()
+
+    // Should restore init values
+    tags = await head.resolveTags()
+    expect(tags.find(t => t.tag === 'title')?.textContent).toBe('Init Title')
+
+    // Manual invalidate should still work
+    head.invalidate()
+    tags = await head.resolveTags()
+    expect(tags.find(t => t.tag === 'title')?.textContent).toBe('Init Title')
+  })
+})
